fhanyuh
ef08ff0527
PFM-Scanner-Ringkasan-Scope.pdf/.odt — 20 pages covering the flow, folder map, ports, how to run each part and from which directory, how login and upload move data, and what is built versus what isn't. src/build_ringkasan.py draws its four diagrams as native shapes (same approach as build_deck.py), crops them to img/ring-*.png, and builds the document in one run.
108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
# 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.
|