teatea-pension/.trellis/tasks/07-02-care-service-workspace/prd.md

Health Care Admin Page

Goal

Build a separate backend management page for health care data instead of turning the existing operational 健康照护 module into a management surface. The first usable slice should let authorized staff manage real persisted health profiles, vital signs, chronic conditions, and abnormal-review records for elders in the active organization.

Background And Confirmed Facts

• The current 健康照护 operational route renders the generic placeholder only: app/(app)/app/health/page.tsx.
• The scoped 健康照护 route delegates to the unscoped placeholder: app/(app)/app/[organizationSlug]/health/page.tsx.
• The placeholder contract explicitly forbids fabricated operational records until real Drizzle-backed data exists: .trellis/spec/frontend/components.md.
• The sidebar already has a separate 管理系统 group for backend management pages: modules/shared/lib/navigation.ts.
• Existing management routes live under /settings/... and have scoped mirrors under /app/[organizationSlug]/settings/....
• Breadcrumbs already treat /settings/... as the management area: modules/shared/components/AppBreadcrumbs.tsx.
• The current Drizzle schema includes organizations, elders, rooms, beds, admissions, audit logs, incidents, permissions, roles, and sessions, but no health profile, vital sign, chronic condition, or health review tables: modules/core/server/schema.ts.
• Existing persisted feature pages load data in Server Components and pass initial records into Client Components, for example app/(app)/app/elders/page.tsx and app/(app)/app/beds/page.tsx.
• The user explicitly clarified that this should be a separate backend management page, split from the current operational health page.

Requirements

Route And Navigation

• Add a new backend management route under the management area.
• Recommended route: /app/settings/health with scoped mirror /app/{organizationSlug}/settings/health.
• Add a 管理系统 navigation item labeled 健康数据管理.
• Keep the existing /app/health operational page separate from this management page for this task.
• Breadcrumbs must show the new route under 工作台 > 管理系统 > 健康数据管理.

Data Model And Persistence

• Add Drizzle-backed tables for the health-care admin MVP.
• Health data must be scoped by organizationId.
• Health data that belongs to an elder must reference a real elder in the same organization.
• Minimum persisted domains:
  • health profile: allergy notes, medical history, medication notes, restrictions, emergency health note.
  • vital sign record: recorded time, source, blood pressure, heart rate, temperature, SpO2, blood glucose, weight, notes.
  • chronic condition: condition name, status, diagnosed date or note, treatment/follow-up notes.
  • abnormal review: severity, status, source vital record or elder, reviewer, reviewed time, handling notes.
• Generated migrations must stay coherent with modules/core/server/schema.ts.
• New mutations must use Drizzle queries or transactions through server boundaries, not legacy write helpers.

Permissions

• Add explicit health permissions unless implementation review finds an existing permission is a better fit:
  • health:read
  • health:manage
• The new management navigation item should require health:read.
• Mutations should require health:manage.
• Default role seeding should grant sensible permissions:
  • platform admin: all permissions through the existing all-permissions pattern.
  • organization admin and manager: read/manage.
  • caregiver: read/manage for health records if the product treats caregivers as health-data operators.
  • viewer: read only.

API And Server Boundaries

• Add health-specific Route Handlers under /api/health/....
• All health APIs must call requirePermission.
• All APIs must validate active organization presence before reading or mutating organization-scoped data.
• Invalid or cross-organization IDs must return structured failures.
• Mutations must record audit logs for create/update/review actions.
• API responses must follow the existing { success, reason, ... } shape.

Admin UI

• The new page must be dense and operational, not a hero or marketing page.
• The first screen should show summary metrics and data management controls.
• Expected tabs or sections:
  • 健康档案
  • 生命体征
  • 慢病记录
  • 异常复核
• The page should support filtering by elder, status/severity, and search terms where useful.
• Authorized users should be able to create or update health records from the UI.
• Users without manage permission may view records but must not see working mutation paths.
• Use project UI adapters from components/ui/*.
• Do not fabricate UI-only health records.

Default Workspace Data

• If seeded workspace data is used for first-run development/demo, it must create real persisted health records tied to real seeded elders.
• Seed records should cover normal vitals, abnormal vitals, chronic conditions, and at least one pending abnormal review.

Acceptance Criteria

• /app/settings/health renders a real backend health management page.
• /app/{organizationSlug}/settings/health renders the same management page in the active workspace.
• The new management page is reachable from the 管理系统 navigation group.
• Existing /app/health remains separate from the backend management page.
• Health admin data is loaded from Drizzle-backed tables and scoped to the active organization.
• Health profiles, vital signs, chronic conditions, and abnormal reviews have persisted list views.
• Authorized users can create or update at least the MVP health records from the UI.
• Users without health:manage cannot mutate health records through the API.
• Health mutations write audit log entries.
• Invalid input and cross-organization references return structured failure responses.
• Seeded examples, if added, are real database rows tied to seeded elders.
• pnpm db:generate is run after schema changes and generated SQL is reviewed.
• pnpm lint passes.
• pnpm type-check passes.
• pnpm build passes.

Out Of Scope

• Replacing the existing operational /app/health placeholder with a full clinical dashboard.
• Device telemetry integration.
• External medical system integration.
• AI-generated health recommendations.
• Complex clinical decision support.
• Full recurring measurement schedule engine.
• Family app notifications.
• Billing, pricing, or insurance flows.
• Replacing Route Handlers with oRPC.
• Replacing the current authentication/session implementation.

Open Questions

• None currently blocking planning.