zkxw/openspec/changes/basic-info-management/design.md

Context

docs/sql/zkxw.sql（全库导出基线）已包含 biz_customer、biz_cell_sample_type、biz_collection_region、biz_collection_hospital、biz_collection_protocol_no、biz_sample_code 等表；需求文档 docs/中科兴皖需求V0.3.md 2.2.1～2.2.5 描述了字段与交互。后端 app/models 与路由中尚未覆盖上述业务主数据的完整 CRUD；Web 管理端缺少对应页面。

与需求文档的差异（以 DDL 为准）：2.2.3 文案提到「医院名称逗号分隔」；当前 schema 为地区表 + 医院子表 1:N，实现 SHALL 以子表为准，弹窗内维护医院行，避免双写。

现有代码模式参考：

• 后端：openspec/changes/dict-management 与 crud/tenant.py 类独立函数、api/admin.py 路由风格；租户 tenant_no、软删 del_flag、列表默认排序 create_time DESC（见 engineering-standards）。
• 前端：标准列表 views/system/unit/index.vue；复杂子表弹窗可参考字典「字典数据配置」或订单模块弹窗；API 封装于 src/api/*.ts。

Goals / Non-Goals

Goals:

• 五类主数据在租户范围内的分页列表、详情（可选）、创建、更新、软删除。
• 客户身份证去重（同租户、非空身份证、未删除记录唯一）；样本类型编码、协议号、样本编码在租户内唯一。
• 地区与医院：主列表为地区；「地区医院配置」弹窗内对 biz_collection_hospital 增删改查（按 region_id）。
• Web UI 符合 docs/web-admin-ui-spec-fresh-mint.md 与 .cursor/rules/web-admin-crud-dialog.mdc。
• 菜单与权限 SQL 或初始化说明写入 docs/sql/（与仓库惯例一致）。

Non-Goals:

• biz_customer_follow 客户随访（2.2.1 未在本次菜单范围单独展开时可列为后续）。
• 小程序端维护上述主数据。
• 协议号/样本编码的「下发」与下游业务流程联动（仅维护 issued 字段与展示）。
• 批量导入导出、复杂审批流。

Decisions

D1: 后端路由组织

选择：新增独立路由模块（例如 app/api/basic_info.py 或按域拆分为 customer.py + 聚合少量路由的文件），在 app/api/__init__.py 与 app/main.py 注册；路径前缀与现有 /api + admin 子前缀保持一致（如 /web/admin/... 或与 dict 同级命名空间）。

理由：五组资源边界清晰，避免单个 admin.py 过度膨胀；仍属同一业务域「基础信息」。

替代方案：全部写入 admin.py → 可行但不利于评审与合并冲突控制。

D2: SQLAlchemy 模型与 CRUD

选择：在 app/models/models.py（或按项目惯例的拆分文件）增加与 DDL 一致的 ORM 模型；app/crud/ 下每域独立模块或 basic_info 包内多文件，函数命名 list_*、get_*、create_*、update_*、soft_delete_*。

理由：与现有 tenant、dict 等模式一致，满足 database-conventions 公共字段与软删查询约定。

D3: 客户身份证唯一校验

选择：创建与更新时若 id_card_no 非空，则查询同租户下是否存在其他未删除记录占用相同证件号；存在则返回 4xx 与明确业务文案（与需求「不要重复创建…提醒」一致）。

理由：表上已有 idx_customer_idcard；应用层给出可读错误信息。

D4: 前端信息架构

选择：五个菜单入口（或二级菜单「基础信息」下五项），每页一个标准列表 + 表单弹窗；地区页主表 + 「地区医院配置」子弹窗（内嵌表格 + 分页）。

理由：与需求操作描述及工程 UI 模板一致。

D5: 初始化数据（样本类型）

选择：可选 SQL 种子插入三种需求既定编码（wcqzxgxb、qdjczgxb、tpyqngxb），若环境已手动录入则脚本需幂等（INSERT IGNORE 或先判存）。

理由：需求 2.2.2 明确当前三种类型。

Risks / Trade-offs

• [需求与 DDL 不一致]：2.2.3 逗号分隔 vs 子表 → 缓解：以 DDL 为准，在 proposal/design 中写明，避免实现回退到反范式存储。
• [唯一索引与软删]：uk_sample_type 等包含 del_flag → 删除后再建同编码可能冲突 → 缓解：软删后「复活」走更新 del_flag=0 或换编码；接口文档说明。
• [权限与菜单遗漏] → 缓解：tasks 中单列菜单 SQL 与路由权限码登记。

Migration Plan

• 无破坏性 schema 变更前提：部署顺序为 DB 已执行 V0.3 DDL → 后端 → 前端；回滚为下线路由与菜单，不物理删数据。
• 若某环境缺表：以 docs/sql/zkxw.sql 为基线导入/对齐，或从其中摘取对应 CREATE TABLE 段落执行。

Open Questions

• Web 菜单父级挂载在「Demo」下还是正式「业务/基础信息」根节点：建议与产品确认后写入 docs/sql 初始化脚本。
• biz_customer_follow 是否与本迭代一并提供只读/编辑入口：默认本变更 Non-Goal，若需可追加 capability。