teatea-pension/.trellis/tasks/archive/2026-07/07-08-complete-ops-ai-board/design.md

Design

Boundaries

This task is a completion pass over existing persisted modules. It does not add schema or a new AI provider path.

• Collaboration data remains owned by modules/devices, modules/notices, modules/alerts, and modules/family.
• Dashboard data loading stays in the Server Component at app/(app)/app/dashboard/page.tsx.
• Presentation stays in modules/dashboard/components/DashboardHome.tsx.
• AI board aggregation belongs in modules/ai/server/analysis.ts because redaction depends on existing AI analysis scope rules.

Data Flow

1. Dashboard page loads auth context and checks whether any visible dashboard section is permitted.
2. It conditionally calls existing operations for core care/health/emergency and collaboration modules.
3. It calls a new AI analysis listing function only when ai:read is present.
4. The AI service lists organization-scoped elder_ai_analyses, joins elders for display names, and maps each row through canViewAnalysisScopes.
5. The dashboard component receives only serializable data and renders queue cards/summary cards from that data.

Seeding Strategy

Existing seedDefaultWorkspaceData exits early when core room/bed/elder/admission rows already exist. That protected existing workspaces, but it skipped collaboration seed records added later. Add a separate idempotent collaboration seeding helper that:

• reads existing rows by stable natural keys per table;
• inserts only missing default rows;
• resolves dependencies from existing or newly inserted rows;
• never updates or deletes existing operator data;
• runs both for fully new workspaces and for already-initialized workspaces.

Stable keys:

• devices: code
• tickets: title
• notices: title
• alert rules: name
• alert triggers: title
• family contacts: elderId + name
• family visits: elderId + contactId + scheduled offset/status/notes is not stable across reruns, so use elderId + contactId + notes for default records
• family feedback: elderId + contactId + content

Permission Model

• Dashboard visibility expands to collaboration and AI read permissions.
• Collaboration sections call server operations only when their read permission is present.
• AI board calls the aggregation function only with ai:read.
• Redaction uses the existing canViewAnalysisScopes and getPermissionForDataScope rules, so a user may see that an analysis exists without seeing restricted result details.

UI Shape

• Keep DashboardHome as a single Server-rendered component with small local helper render functions.
• Add collaboration queue cards for device tickets, notices, alert triggers, and family items.
• Add an AI analysis board card with risk/status badges, data scopes, created time, and a link back to the elder workspace.
• Empty states must be honest: no generated counts or placeholder rows.

Compatibility

No schema migration is required. The seeding helper is additive and only inserts missing default data.

Rollback

Rollback is limited to the AI aggregation helper, dashboard props/rendering, dashboard page conditional loads, and the additive seed helper. Existing collaboration CRUD modules remain untouched unless tests expose a direct integration bug.