zkxw/docs/superpowers/specs/2026-09-18-collection-region-staff-binding-design.md

采集地区 · 人员绑定设计

日期：2026-09-18
页面：/#/market/market-info/collection-region（细胞采集基础信息维护 → 采集地区及医院）
Demo：docs/superpowers/demos/2026-09-18-collection-region-staff-binding-demo.html
状态：设计已确认，待实现计划

---

1. 背景与目标

现有「采集地区及医院」仅维护地区与下属医院（biz_collection_region / biz_collection_hospital），需求文档 docs/中科兴皖需求V0.3.md §2.2.3 未覆盖人员。

目标：为每个采集地区绑定本租户系统人员，表示该区域工作人员；支持将部分绑定人员设为该地区负责人（可多名）。

首期成功标准：主数据可维护、列表与查看可展示摘要；不驱动协议默认人、待办过滤、数据权限等业务逻辑。表结构与接口按可扩展方式设计，供后续接入。

---

2. 已确认决策

项	结论
负责人数量	可多名；允许 0
一人多区	允许同一 user_id 绑定多个地区
首期范围	仅主数据维护与展示
扩展预留	关联表 + is_leader；具体后续场景本轮不定、不开发
候选用户	本租户全部启用用户（sys_user）
UI	独立「地区人员配置」弹窗，与「地区医院配置」对称
实现路径	方案 1：关联表 + 子资源 CRUD（对齐医院）

---

3. 数据模型

3.1 新表 biz_collection_region_staff

字段	类型	说明
id	VARCHAR(64) PK	UUID
region_id	VARCHAR(64) NOT NULL	采集地区 ID
user_id	VARCHAR(64) NOT NULL	sys_user.id
is_leader	TINYINT NOT NULL DEFAULT 0	是否地区负责人（0/1）
tenant_no	VARCHAR(64)	租户编号
order_num	INT	排序号
remark	VARCHAR(512)	备注
create_by / create_dept_id / create_time	公共字段
update_by / update_time	公共字段
del_flag	SMALLINT DEFAULT 0	软删

字段顺序遵循仓库约定：id → 业务字段 → 公共字段。

3.2 约束与规则

• 业务唯一：同一租户下 (tenant_no, region_id, user_id) 在 del_flag=0 时唯一（应用层校验；MySQL 5.7 软删场景不依赖部分唯一索引）。
• 不修改 biz_collection_region、sys_user 表结构。
• 软删地区时：同一事务内级联软删该地区下未删除的 医院 与 staff（扩展现有医院级联）。
• 用户停用/删除：已有绑定行保留（便于历史展示）；新增时仅允许启用用户。首期不做绑定自动清理。
• 预留：首期不加「绑定角色类型」等字段；后续业务用 region_id + user_id + is_leader 查询即可。

3.3 明确不采用

• 地区表上逗号分隔 user_id / leader_id（与医院子表设计原则一致）。
• 弹窗「整表覆盖一次提交」作为主 API（与医院单条 CRUD 不一致；可作为后续优化，非首期）。

---

4. API

挂在现有基础信息模块（backend/app/api/basic_info.py + app/crud/collection_region.py），路径前缀与现有 collection-regions / hospitals 一致。

方法	路径	说明
GET	/collection-regions/{region_id}/staff	分页列出绑定人员
POST	/collection-regions/{region_id}/staff	新增；body: userId, isLeader?（默认 false）
PUT	/collection-regions/{region_id}/staff/{staff_id}	更新；主要改 isLeader；不允许改 userId
DELETE	/collection-regions/{region_id}/staff/{staff_id}	软删绑定

4.1 行为约定

• 租户隔离 + 现有 apply_data_scope（与地区 CRUD 一致）。
• POST：同区已存在未删除同 userId → 业务错误（不可重复绑定）。
• POST：用户须为本租户且启用，否则拒绝。
• DELETE 地区：事务内级联软删下属 hospitals 与 staff。
• 选人：复用现有用户列表/选项接口（如 fetchUserList / fetchUserOptions）；本需求不新增用户 API。

4.2 地区列表摘要

GET /collection-regions 的 _region_to_dict（或等价）增加：

{
  "staffNames": ["张敏", "李强"],
  "leaderNames": ["张敏"]
}

• 展示名取自 sys_user.nick_name；为空时回退 user_no（与用户选项接口一致）。
• 排序建议：负责人优先，再按 order_num / create_time。
• 批量查询，避免 N+1。

4.3 Staff 列表项字段（建议）

id, regionId, userId, userName（或 nickName）, userNo, deptName?, isLeader, createTime 等；以 _staff_to_dict 为可读字段单一来源，Create/Update body 与之对齐可写字段。

---

5. 前端

文件：web-admin/src/views/basic-info/collection-region/index.vue

5.1 主列表

• 新增列：工作人员（多行姓名；空为 —）、负责人（<el-tag type="success" size="small">；空为 info「未设置」）。
• 操作列：在「地区医院配置」旁增加 「地区人员配置」；min-width ≥ 280。
• 筛选：首期仅保留地区关键词；不按人员筛选。

5.2 「地区人员配置」弹窗

• 对齐医院配置：当前地区提示、工具栏（已选 N → 添加人员主按钮 → 批量移除）、表格、分页。
• 表格：序号、姓名、工号/账号、部门（若有）、是否负责人、操作（切换负责人、移除）。
• 添加人员：el-select remote 或等价，候选为本租户启用用户；已绑定排除或提交拦截。
• 是否负责人：行内切换后调 PUT；允许多名与全部取消。
• 遮罩无 blur；dialog-form-layout；按钮带图标（OpenSpec UI 约定）。

5.3 查看弹窗

SystemViewDialog 增加：工作人员、负责人（Tag）。地区新增/编辑表单仍只维护地区名称/备注；人员仅走配置弹窗。

5.4 类型

Api.BizCollectionRegion 增加 staffNames / leaderNames 及 Staff 子项类型；API 封装与医院子资源对称。

---

6. 错误处理

情况	处理
地区不存在 / 非本租户 / 已软删	404 或业务错误 + Toast
重复绑定	明确文案，如「该人员已绑定到此地区」
用户不存在或未启用	拒绝新增
staff 行不属于路径中的 region_id	拒绝更新/删除
移除 / 批量移除	二次确认

---

7. 范围外（首期不做）

• 协议单默认销售/采集专员、按地区过滤待办、数据权限
• 按角色过滤候选用户
• 按人员姓名筛地区列表
• 小程序端改动
• 在 sys_user 或地区主表冗余人员字段

---

8. 验收要点

1. 一地区可绑多名启用用户；一人可绑多地区。
2. 可设多名负责人，也可全部取消。
3. 主列表与查看弹窗正确显示 staffNames / leaderNames。
4. 软删地区后，下属 hospital + staff 均软删且列表不可见。
5. 重复绑定被拒绝；停用用户不可新绑。
6. UI 与「地区医院配置」对称，符合 Fresh Mint / Tag / 按钮图标约定。

---

9. 实现改动面（预估）

层	内容
SQL	docs/sql/migrations/2026-09-18-collection-region-staff.sql；按仓库约定同步全量 schema
Backend	models.py、collection_region crud、basic_info 路由、删除级联、列表摘要
Frontend	collection-region/index.vue、API 模块与类型
Spec（可选）	扩展 OpenSpec collection-region-hospital-management 或新增 capability
Demo	已有 HTML Demo，实现时可对照

---

10. 参考

• 现有医院子资源：GET/POST/PUT/DELETE .../collection-regions/{id}/hospitals
• OpenSpec：openspec/changes/basic-info-management/specs/collection-region-hospital-management/spec.md
• UI：docs/web-admin-ui-spec-fresh-mint.md；模板页医院弹窗交互以本页现有实现为准