docs: add collection region staff binding design and demo

Capture the approved design for region–user binding with multi-leader support, plus an interactive Fresh Mint HTML demo for UI review.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-09-18 11:09:59 +08:00
1 parent 679285dcc6
commit e24b3dbadf
2 files changed
+1116

No files matched your search

@@ -0,0 +1,185 @@
# 采集地区 · 人员绑定设计
**日期**: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`(或等价)增加:
```json
{
"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`;模板页医院弹窗交互以本页现有实现为准