[Story-1032] Align Forums catalog schema with source-discriminated pattern

Story 1032Epic None13 files · +1025/−772

PR #256 · pramaan-io/pramaan-functions · merged 2026-06-04

How it flows

sequenceDiagram
  autonumber
  participant mig as Migration
  participant sch as Schema
  participant svc as Service
  participant rt as Router
  mig->>mig: Rebuild RLS
  mig->>mig: Seed system forums
  mig->>sch: Entity gains fields
  sch->>svc: List DTO ready
  svc->>rt: GET /app/forums
  rt->>rt: Write routes removed

forum domain

Method	in → out	what it does
`Forum`	`(type)`	system-or-firm venue row with source check constraint
`_seed_system_forums`	`() → None`	inserts the platform-owned forum venues
`_create_forum_reference_trigger`	`() → None`	guards Matter and Proceeding forum references

What changed, file by file

alembic/versions/1f8a2c3d4e5b_0071_forums_source_discriminated_catalog.py+427

Alembic migration that rebuilds forum row-level security, seeds system venues, and creates a database trigger guarding Matter and Proceeding references.

new method	signature
`_drop_forum_rls`	`() → None`
`_disable_forum_rls`	`() → None`
`_enable_forum_rls`	`() → None`
`_create_forum_rls`	`() → None`
`_create_legacy_forum_rls`	`() → None`
`_seed_system_forums`	`() → None`
`_create_forum_reference_trigger`	`() → None`
`_drop_forum_reference_trigger`	`() → None`
`upgrade`	`() → None`
`downgrade`	`() → None`

src/domains/forum/entity.py+67 −8

Forum entity — gained source, key, category, location and firm identifier fields, plus a check constraint pinning source to system or firm.

new class	signature
`Forum`	`(type)`

New fields: firm_id : UUID | Nonesource : strkey : strcategory : strlocation : str

src/domains/forum/dtos/forum.py+33 −24

Forum DTOs — added a list-ready shape carrying category, location, and source; dropped write-side DTOs because writes are gone from the app.

new class	signature
`ForumSource`	`(class)`
`ForumCategory`	`(class)`
`ForumListItem`	`(class)`

New fields: name : strcategory : ForumCategorycategory_label : strlocation : strsource : ForumSource

src/domains/forum/service.py+29 −142

Forum service — trimmed to a read-side list helper that maps a forum row into the list item DTO; write paths removed.

new method	signature
`_list_item`	`(forum) → ForumListItem`

Failure cases blocked

Matter references a missing forum
Source outside system or firm
Row without firm scope gets through
App writes to /forums
Empty category or location

DB trigger rejects bad refs

Check constraint pins source

RLS rebuilt on new shape

Write routes gone from router

Category and location are non-null

Seed runs once per env

Migration is reversible

Files changed (13)

File	±
`alembic/versions/1f8a2c3d4e5b_0071_forums_source_discriminated_catalog.py` ★	+427
`docs/walkthroughs/story-1032-walkthrough.html`	+111
`openapi/app-api.json` ★	+62 −438
`src/domains/forum/dtos/__init__.py`	+9 −9
`src/domains/forum/dtos/forum.py`	+33 −24
`src/domains/forum/entity.py` ★	+67 −8
`src/domains/forum/router.py`	+4 −41
`src/domains/forum/service.py`	+29 −142
`src/domains/matter/service.py`	+8 −2
`src/domains/proceeding/service.py`	+9 −3
`tests/contract/generate_fixtures.py`	+10 −13
`tests/integration/test_app_forums.py`	+248 −83
`tests/integration/test_app_matters.py`	+8 −9