# Handover materials

Two deliverables, same content, different jobs.

| File | What it's for |
|---|---|
| `PFM-Scanner-Knowledge-Transfer.odp` | 30-slide deck (LibreOffice Impress). For the walkthrough session. Diagrams are native draw shapes, so it also opens in Draw. |
| `PFM-Scanner-Handover-Document.odt` | 42-page document (LibreOffice Writer). For the person working alone, later. Adds an operational runbook, a troubleshooting guide, a glossary, and a full screenshot appendix. |
| `PFM-Scanner-Ringkasan-Scope.odt` | 20-page Indonesian summary (LibreOffice Writer). The one to read first: the flow, the folder map, the ports, how to run each part and from which directory, how login and upload actually move data, then what is built versus what isn't. |
| `*.pdf` | Same files, for sharing with people who won't edit them. |

All three are built entirely from what is committed in this repo. Nothing is invented.
Screenshots are the real captures from `screenshots/v2/` and `screenshots/`, taken on
a real device against the live backend.

## Before handing them over — fill these in

Three things the repo cannot know are marked `[ TO FILL IN ]`:

- **Deck slide 1 / document cover** — presenter name, handover date, successors.
- **Deck slide 24 / document §15** — the access & credentials checklist is a
  *checklist*, deliberately unfilled. Don't type secrets into either file; use it as
  the agenda for a session where the successor logs into each one themselves.
- **Document §12.5, §12.7, §15** — how the APK reaches store devices, whether any DB
  backup runs, and the current deployment state (which stores are live, on what
  hardware, since when).

## Contents

**Deck (30 slides)** — 1–2 intro · 3–8 what exists + architecture and sequence
diagrams · 9–11 the app on screen (shell, DO scan ×2) · 12–13 gateway + internal web
tooling · 14–16 accuracy · 17–18 Product Scan + its screens · 19–21 data, ops, repo
map · 22–24 gotchas + credentials · 25–30 roadmap, scope, first 30 days, index.

**Document (42 pages)** — §1–9 what exists · §10 accuracy · §11–13 setup, runbook,
troubleshooting · §14–18 gotchas, credentials, roadmap, out-of-scope, first 30 days ·
Appendix A glossary · B command reference · C doc index · D the app screen by screen.

## Regenerating

`src/` holds the generators. Both emit flat-ODF XML that LibreOffice converts.

```bash
cd docs/handover/src

python3 prepare_assets.py     # once — builds shots_small/ from ../../../screenshots/
                              # (needs Pillow; nothing else here does)

python3 build_deck.py                                     # -> pfm-handover.fodp
libreoffice --headless --convert-to odp pfm-handover.fodp

python3 build_doc.py                                      # -> pfm-handover-doc.fodt
libreoffice --headless --convert-to odt pfm-handover-doc.fodt
```

`shots_small/` is gitignored — it is display-resolution copies of screenshots already
committed elsewhere in the repo, and embedding the originals at full size makes the
`.odp` roughly 10MB for no visible gain.

The Indonesian summary has its own generator, same two-stage shape as the deck:

```bash
cd docs/handover/src
python3 build_ringkasan.py     # draws diagrams, crops them, builds the doc,
                               # writes ../PFM-Scanner-Ringkasan-Scope.{pdf,odt}
```

Its four diagrams are native shapes like the deck's, drawn in the same file that
builds the document, cropped to `img/ring-*.png`. Edit the shape coordinates in
`build_ringkasan.py` and re-run — there is no separate re-crop step.

Two layout constraints it works around, worth keeping if you edit it. Writer glues a
heading to a full-width image below it, so a section opening with a diagram jumps to
the next page and strands a half-empty one — `newpage()` makes that jump deliberate.
And a sequence diagram wider than about 20cm shrinks below readable size once scaled
into the A4 text column, so keep the crop narrow rather than the font large.

`build_deck.py` prints a text-overflow report for any frame whose content is
estimated to exceed its box — anything over ~0.15cm is worth fixing before shipping.

### If you change a deck diagram

The document embeds the deck's diagrams as PNGs from `src/img/`, cropped out of the
deck PDF. Re-crop after any diagram change, or the two will disagree. The crop
rectangles are in centimetres `(deck page, x, y, w, h)`; `build_doc.py` resolves them
by filename prefix, so the page number in the filename can change freely.

```bash
# after rebuilding the deck PDF
python3 - <<'PY'
import subprocess
DPI=200; K=DPI/2.54
crops={"flow":(3,1.35,4.40,22.70,2.90),"arch":(4,1.30,3.10,22.90,5.05),
       "sequence":(6,1.00,3.25,23.20,9.15),"layers":(14,1.35,4.25,22.70,7.00),
       "product":(17,1.35,4.25,22.70,2.20),"phases":(27,1.35,8.75,22.70,2.05)}
for n,(p,x,y,w,h) in crops.items():
    subprocess.run(["pdftoppm","-r",str(DPI),"-f",str(p),"-l",str(p),"-png",
        "-x",str(int(x*K)),"-y",str(int(y*K)),"-W",str(int(w*K)),"-H",str(int(h*K)),
        "pfm-handover.pdf","img/"+n],check=True)
PY
```

Note: LibreOffice installed from snap cannot read paths outside `$HOME`, so run the
conversions somewhere under your home directory.

Editing directly in Impress/Writer is fine, but then the generators are stale — pick
one as the source of truth rather than maintaining both.