docs: invoices and orders pages match the code

[futurebuildai]

What changed

Two drift fixes from the previous pass are still in this PR. This commit
adds the four items the lead's ruling named: three missing routes in
docs/modules/invoices.md and one missing field in docs/modules/orders.md.

1. Route census column name

The route census (core/api/ROUTES.txt) lists each one under the
internal/invoice package (the route census has a package column, not
a module column).

After:

The route census (core/api/ROUTES.txt) lists each one under the
internal/invoice module (the route census has a module column whose
value is the registering package's directory relative to the Go module
root).

Evidence: head -10 core/api/ROUTES.txt reads "method, pattern, module,
handler. The module column is the registering package's directory relative
to the Go module root." The census uses module, not package.

2. Owner of /api/v1/invoices/{id}/payments

Before:

Three of the routes below are registered under other packages: the
email and print routes are internal/document, the invoice's payment
list is internal/payment.

After:

Three of the routes below are registered under other modules: the
email and print routes are internal/document, the invoice's payment
list is internal/invoice.

Evidence: grep '/api/v1/invoices/{id}/payments' core/api/ROUTES.txt ->
internal/invoice h.HandleApplications (ROUTES.txt line 239). The handler
lives in core/internal/invoice/handler.go.

3. Three missing routes in invoices.md

Added to the Routes table:

• POST /api/v1/invoices/{id}/write-offs (internal/invoice, ROUTES.txt
  line 241; fragment line 455 in core/api/fragments/invoice.yaml):
  write off part or all of an open invoice as bad debt; user guard
  admin, owner, finance (the wall at
  core/internal/app/serve/wire_branch_wall.go line 120 plus the service
  requireFinance at core/internal/invoice/service_ar.go line 89);
  body {amount_cents, reason} (1 to 500 chars) plus revision. ADR 0005
  section 9.4.
• POST /api/v1/credit-memos/{id}/applications (internal/invoice,
  ROUTES.txt line 143; fragment line 536 in
  core/api/fragments/invoice.yaml): apply a credit memo's open credit
  to invoices of the same customer and currency; user guard admin,
  owner, sales, finance (the wall at
  core/internal/app/serve/wire_branch_wall.go line 120); body
  {applications: [{invoice_id, amount_cents}], revision}. ADR 0005
  section 9.4.
• POST /api/v1/credit-memos/{id}/refunds (internal/payment, ROUTES.txt
  line 144; fragment line 315 in core/api/fragments/payment.yaml): pay
  a credit memo's open credit out; user guard admin, owner,
  finance, cashier (the wall at
  core/internal/app/serve/wire_branch_wall.go line 135) with the
  service who.finance at core/internal/payment/service_card.go line
  192 keeping it to admin, owner, finance; body
  {amount_cents, reason, method: card|check|ach|other, payment_id?}
  with a card refund going back through the gateway. ADR 0005 section
  9.4.

The lifecycle table gains the invoice written_off, the invoice paid,
the invoice reopened, the credit memo partial, and the credit memo
applied transitions with their events, and a paragraph after the void
paragraph lists the 409 blockers for each new route. The events list
gains the constants the AR core writes
(EventInvoicePartial, EventInvoicePaid, EventInvoiceWrittenOff,
EventInvoiceReopened, EventCreditPartial, EventCreditApplied,
EventCreditReopened) and notes that the payment module writes
credit_memo.refunded itself.

4. deposit_unapplied_cents in orders.md

Added to the Order fields table:

deposit_unapplied_cents | integer | The unapplied cash of the posted
payments taken against this order (deposits), applied to its invoices
as they are billed; sum(pm.amount_unapplied) over posted payments of
this order, read at read time
(core/internal/order/repository.go summaryColumns).

Evidence: core/api/fragments/order.yaml lines 1042, 1185, 1226, 1371
(schema); core/internal/order/model.go line 134 (Go field
DepositUnappliedCents); core/internal/order/repository.go
summaryColumns lines 186-188 (the SUM(pm.amount_unapplied * 100)
over posted payments).

What did not change

docs/modules/orders.md had no FALSE rows in the drift pass. The page
gets only the field added.

Drift table

The full drift table (one row per factual sentence on both pages) lives
at /home/colton/Desktop/FBHQ/gable-v1/mm/docs-drift-table.md (outside
the repository). The previous section's totals stand:

• invoices.md: 41 TRUE, 2 FALSE, 0 UNVERIFIABLE (the two FALSE rows are
  fixed here).
• orders.md: 32 TRUE, 0 FALSE, 0 UNVERIFIABLE.

The "Additions for the lead's ruling on the missing items" section of
the table is the evidence for the four additions above; the writer
copied only what the rows showed.

Code defects for the lead

None found.

Pre-push

• python3 .github/scripts/reuse_gate.py -> REUSE gate passed.
• bash scripts/check-shape.sh -> check-shape: OK.
• git diff origin/refactor/v1..HEAD | grep -cP '^\+.*[\x{2013}\x{2014}]' -> 0.
• git diff origin/refactor/v1..HEAD | grep -c '^+.* -- ' -> 0.
• git log --format='%ae %ce' origin/refactor/v1..HEAD | sort -u ->
  colton@futurebuild.ai colton@futurebuild.ai.
• git log --format=%B origin/refactor/v1..HEAD | grep '^Signed-off-by' | sort -u ->
  Signed-off-by: colton <colton@futurebuild.ai>.
• credential-shape grep -> 0.
• sign-off grep on every commit -> nothing.

Two commits on refactor/docs-drift-invoices-orders (the first from the
previous pass, this one added on top):

docs: invoices routes section matches the route census

Signed-off-by: colton <colton@futurebuild.ai>

docs(invoices,orders): add the four missing items to the routes and fields tables

docs: routes table adds POST /invoices/{id}/write-offs (internal/invoice), POST /credit-memos/{id}/applications (internal/invoice) and POST /credit-memos/{id}/refunds (internal/payment) with what each does, its role guard and its body, each quoted from the route fragment, the handler and the AR or payment core.

docs: lifecycle table gains the invoice written_off and the credit memo applied and refunded transitions with their blockers, and the events list gains the constants the AR core and the payment module write.

docs: orders Order field table gains deposit_unapplied_cents with its meaning and the SQL that computes it.

Signed-off-by: colton <colton@futurebuild.ai>

🤖 Generated with Claude Code