Files
0pt/docs/guides/document-workbench.md
T
admin b3239487b7
CI (SIAX Cloud) / integration (push) Skipped
CI (SIAX Cloud) / sonar (push) Skipped
masterplan-lock / check (push) Successful in 10s
CI (SIAX Cloud) / sonar (pull_request) Skipped
Security Scan (SIAX Cloud) / security (push) Successful in 13s
masterplan-lock / check (pull_request) Successful in 7s
CI (SIAX Cloud) / security (push) Successful in 26s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 17s
CI (SIAX Cloud) / security (pull_request) Successful in 19s
CI (SIAX Cloud) / quality (push) Successful in 1m9s
CI (SIAX Cloud) / quality (pull_request) Successful in 2m26s
CI (SIAX Cloud) / integration (pull_request) Successful in 2m33s
feat(document-workbench): wire customer upload, structuring, credits and readiness
- POST /api/0pt/documents/upload: real multipart bytes into DOC0 through the
  durable attempt journal and the existing coordinator; verified tenant/actor
  only, project authorization fail-closed.
- POST /api/0pt/documents/structure: DOC0 segments -> INF0 -> evidence-bound
  validation -> optional JSON/CSV export, with credit reserve/settle.
- Credits: balance, server-owned price book, Stripe Checkout and idempotent
  webhook reconciliation via a Stripe re-read of session + payment intent.
- /portal/dokument and /portal/krediter: SIAX-styled workspace.
- @siax/access: universal, framework-neutral OpenFGA project relationship
  primitive reusable by DOC0/N0D/other products.
- Readiness: real Redis PING probe instead of presence-only; queue is now a
  live dependency when configured.
- Dockerfile: copy every workspace manifest so --frozen-lockfile works.
- Format/build hygiene: .prettierignore, .worktrees ignored, valid manifest YAML.
2026-11-02 14:46:10 +01:00

56 lines
3.2 KiB
Markdown

# Document workbench — upload → structure → validated export
The customer-facing slice that turns an uploaded file into evidence-bound data.
## Routes
| Route | Purpose | Fails closed with |
|---|---|---|
| `POST /api/0pt/documents/upload` | multipart upload of the original bytes into DOC0, recorded in a durable attempt journal before dispatch | `503 DOC0_NOT_CONFIGURED`, `503 PROJECT_AUTHORIZATION_NOT_CONFIGURED`, `503 UPLOAD_JOURNAL_NOT_CONFIGURED` |
| `POST /api/0pt/documents/structure` | re-reads the DOC0 segment index, calls INF0, validates every field against an exact source span, reserves/settles credits | `503 WORKBENCH_NOT_CONFIGURED`, `503 MODEL_POLICY_NOT_CONFIGURED`, `503 CREDITS_NOT_CONFIGURED`, `402 INSUFFICIENT_CREDITS` |
| `GET /api/0pt/documents/models` | the server-approved model routes and limits | `503 MODEL_POLICY_NOT_CONFIGURED` |
| `GET /api/0pt/credits/balance` | tenant credit balance | `503 CREDITS_NOT_CONFIGURED` |
| `GET /api/0pt/credits/packs` | sellable packs from the server-owned price book | `503 PRICE_BOOK_NOT_CONFIGURED` |
| `POST /api/0pt/credits/checkout` | Stripe Checkout session + server price snapshot | `503 PRICE_BOOK_NOT_CONFIGURED`, `503 STRIPE_NOT_CONFIGURED` |
| `POST /api/webhooks/stripe` | re-reads the session and payment intent, then grants credits idempotently | non-2xx until processed |
UI: `/portal/dokument` (upload, structure, review, download) and `/portal/krediter`
(balance, packs, checkout).
## Invariants
1. **Tenant and actor come only from middleware's verified headers.** A customer
route never trusts `tenant_id`/`actor_id` from the body.
2. **Project access is checked by OpenFGA** (`@siax/access`), the same primitive
DOC0 uses. Unconfigured or unavailable means *denied*, never allowed.
3. **The model never sees unverified text.** `Doc0SourceClient` verifies
version, tenant, checksum, segment hashes and that the index was not
truncated before anything is sent to INF0.
4. **Every returned value must point at an exact span** in the source; otherwise
the result is `needs_review` and nothing is exported.
5. **Credits are reserved before the model runs and settled to measured usage.**
An unknown model outcome keeps the reservation for reconciliation instead of
releasing it.
6. **No price is ever read from the client.** The price book is a versioned,
server-owned JSON document (`OPT_CREDIT_PRICE_BOOK`).
## Reusable packages
- `packages/siax-access` (`@siax/access`) — framework-neutral OpenFGA
relationship checks and a fail-closed `isProjectAccessAllowed`. Intended for
DOC0, N0D and every other SIAX product instead of per-repo copies of
`project-relationships.ts`.
- `src/document-workbench/*` — upload coordination, DOC0 source reading, INF0
admission, structured-output validation, export and credit ledger. These
modules have no Next.js imports and can be lifted into a published package
unchanged.
## What is still deliberately not claimed
- The output is `mechanically_validated`, not proven complete or semantically
correct. OCR quality and coverage require review.
- Refunds and chargebacks do not automatically revoke credits; no such handler
is wired.
- Format breadth is limited by DOC0's parser. A file DOC0 cannot parse is
reported, never guessed.