touyun-elderly-care/openspec/changes/svc-org-c0-base/design.md

Context

服务机构端 P0 在 sysmgr 脚手架（ec-nest + ec-admin）上落地。脚手架已提供：多租户过滤（tenant_code）、RBAC（resource 树 + 权限码）、审计日志、软删（deleted_at）、错误码注册表。C0 只做映射 + 建业务表 + 配角色/权限/菜单/错误码，不侵入脚手架。

Goals / Non-Goals

Goals:

• 定死机构=租户映射，业务表复用脚手架多租户过滤。
• staff 持 user_id 关联账号，不动 sys_user。
• C0 建 9 张业务表 + 复用 sys_user。
• 5 业务角色 + 权限码 + 菜单 + 错误码 + 审计落地。

Non-Goals:

• 不实现 C1–C4 业务（待遇档案/派单/留痕/质控）。
• 不接真实 COS 上传（占位）。
• 不做护理员 APP、家属端。

Decisions

1. 机构=租户，tenant_code 作全局键（备选：扩展 sys_tenant → 弃，污染框架）。
2. staff.user_id 关联 user，不动 sys_user（备选：user.staff_id → 弃，动框架；user.ext_type/ext_id 多态 → 弃，YAGNI + 无外键保障）。
3. 业务角色用脚手架角色 + 权限码（PRD 的 user.role 逗号分隔不照搬，用 user↔role 多对多实现多角色并集）。
4. 主键 UUID v7（备选 varchar32 → 弃，跟随脚手架）。
5. 软删 deleted_at（备选 is_deleted 布尔 → 弃，跟随脚手架）。

数据模型（DDL 概览）

通用字段：created_at/created_by/updated_at/updated_by/deleted_at。

• org：org_code(PK, 与 tenant_code 同值)、org_name、org_type、credit_code、loc_code、loc_name、svc_source、license_no、address、contact_name、contact_phone、bed_count、sign_date
• staff：staff_id(PK uuid)、tenant_code、user_id(unique 可空 → user.id)、name、id_card_no(加密)、person_code、phone、job_type、work_type、entry_date、leave_date、employ_status、cert_type/cert_no/cert_level/cert_expire/cert_status、cert_verify_url、group_leader_id
• svc_national(L1)：nat_id、nat_code(unique varchar20)、nat_name、nat_category、nat_sub_category、recommend_staff、recommend_duration、is_medical、version
• svc_local(L2)：loc_id、loc_code、local_item_name、local_category、svc_time、min_freq、staff_qual、is_medical、source_doc、map_status
• svc_mapping(L3)：map_id、loc_id、nat_id(可空)、map_type、map_note、status
• svc_org(L4)：org_svc_id、tenant_code、src_type、src_id、is_enabled、price(预留)、price_effective(预留)、is_new_national
• dict_abnormal_type：code、name、sort；dict_photo_tier：code、name、tier
• loc_config：loc_code(PK)、loc_name、svc_source、item_count_rule(预留)

索引：staff.user_id 唯一、staff.tenant_code、svc_national.nat_code 唯一、svc_local.loc_code、svc_org.tenant_code。

Risks / Trade-offs

• [org 表与 sys_tenant 1:1 但分表] → 以 code = tenant_code 同值保证一致；创建机构时事务内同步建 tenant。
• [staff.user_id 无法用 DB 外键到不同库] → 同库内仍可建外键；业务层再校验 user 存在 + 唯一。
• [目录四层数据初始化量大] → seed 提供 L1 36 项 + 昆明 L2 45 项 + L3 映射；州市按需插入 loc_config + svc_local。

Migration Plan

• 新增 Prisma 迁移建 9 张表；seed 初始化目录（L1/L2/L3）、默认角色与权限码；不迁移旧数据（新库）。
• 回滚：删除本次迁移即可（纯新增，无破坏性改动）。