docs(docs): sheet model spec matches the hardened code (counter, SQL-only codes, census, migration list)
This commit is contained in:
1 parent
d3fa65af29
commit
5d32bed829
2 files changed
+36
-32
No files matched your search
@@ -127,10 +127,13 @@ Integrity rules (error unless stated):
|
||||
| `finding_zone.unreferenced` (warning) | zone no annotation points to |
|
||||
|
||||
A draft may be saved with errors. Publishing a document with errors is
|
||||
refused in TypeScript (`assertPublishable`) and in SQL
|
||||
(`private.sheet_document_issues`), which re-checks every error-level rule
|
||||
except the two recursive ones (parent cycle, sibling uniqueness) and adds
|
||||
"every `svg_asset_id` is an asset of this sheet".
|
||||
refused in TypeScript (`assertPublishable`) and in SQL:
|
||||
`private.sheet_document_issues` re-checks every error-level rule except the
|
||||
two recursive ones (parent cycle, sibling uniqueness) and reports
|
||||
`document.shape` when an id-bearing collection is not an array;
|
||||
`private.sheet_document_unknown_assets` adds `view.asset.unknown` when a
|
||||
view points at an asset not registered for the sheet. Both run inside
|
||||
`publish_sheet_version`.
|
||||
|
||||
## 3. Relational model
|
||||
|
||||
@@ -165,16 +168,16 @@ any authenticated user; no write path through the API (platform step later).
|
||||
|
||||
### `anatomical_sheet_versions`
|
||||
|
||||
| Column | Notes |
|
||||
| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| `id uuid`, `sheet_id` | |
|
||||
| `version_number int` | unique per sheet, assigned by the server (`max + 1`) |
|
||||
| `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` |
|
||||
| `document_schema_version int` | CHECK = `content->>'schema_version'`; only `1` today |
|
||||
| `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB |
|
||||
| `change_note text` | what changed in this version |
|
||||
| `created_by`, `published_by`, `deprecated_by` | profile ids, `on delete set null` |
|
||||
| `published_at`, `deprecated_at`, `created_at`, `updated_at` | |
|
||||
| Column | Notes |
|
||||
| ----------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `id uuid`, `sheet_id` | |
|
||||
| `version_number int` | unique per sheet, assigned by the server from the sheet's monotonic counter |
|
||||
| `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` |
|
||||
| `document_schema_version int` | CHECK = `content->>'schema_version'`; only `1` today |
|
||||
| `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB |
|
||||
| `change_note text` | what changed in this version |
|
||||
| `created_by`, `published_by`, `deprecated_by` | profile ids, `on delete set null` |
|
||||
| `published_at`, `deprecated_at`, `created_at`, `updated_at` | |
|
||||
|
||||
Rules enforced by triggers (every role, including the table owner):
|
||||
|
||||
@@ -211,7 +214,7 @@ authorise through the sheet, never through a sha256 alone.
|
||||
| RPC | Actor | Effect |
|
||||
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `create_anatomical_sheet(species_id, name, slug, document, description, visibility, official)` | any active account; `official = true` needs platform admin | sheet + draft v1 |
|
||||
| `create_sheet_draft(sheet_id, from_version_id, change_note)` | editor | new draft `max + 1`, content copied from `from_version_id` (default: current version); refused if a draft exists |
|
||||
| `create_sheet_draft(sheet_id, from_version_id, change_note)` | editor | new draft (next counter value), content copied from `from_version_id` (default: current version); refused if a draft exists |
|
||||
| `publish_sheet_version(version_id)` | editor | draft → published; relational checks; sheet `current_version_id` ← version. Previous published versions stay `published` (historical reports keep rendering) |
|
||||
| `deprecate_sheet_version(version_id, reason)` | editor | published → deprecated (not offered for new reports; still readable) |
|
||||
| `delete_sheet_version(version_id)` | editor | physical delete, trigger preconditions |
|
||||
@@ -248,8 +251,8 @@ Policies:
|
||||
| `anatomical_sheet_assets` | same visibility as the sheet | none (RPC) |
|
||||
|
||||
`anon` gets nothing. Every `private` function has EXECUTE revoked from
|
||||
PUBLIC; only the two predicates above are granted to `authenticated`
|
||||
(pgTAP 001 keeps a census). Public discovery views for the public site come
|
||||
PUBLIC; `authenticated` executes only the policy predicates (the two above
|
||||
plus the five platform-role predicates of Step 3); pgTAP 001 keeps a census. Public discovery views for the public site come
|
||||
with the community step (§17.4).
|
||||
|
||||
## 4. What the model guarantees (acceptance criteria)
|
||||
|
||||
Reference in new issue
Block a user