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:
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`;模板页医院弹窗交互以本页现有实现为准
|
||||
Reference in new issue
Block a user