From e24b3dbadfe3a191ff584fbf3e2157d4b6afbf17 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Fri, 18 Sep 2026 11:09:48 +0800 Subject: [PATCH] docs: add collection region staff binding design and demo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...-collection-region-staff-binding-demo.html | 931 ++++++++++++++++++ ...-collection-region-staff-binding-design.md | 185 ++++ 2 files changed, 1116 insertions(+) create mode 100644 docs/superpowers/demos/2026-09-18-collection-region-staff-binding-demo.html create mode 100644 docs/superpowers/specs/2026-09-18-collection-region-staff-binding-design.md diff --git a/docs/superpowers/demos/2026-09-18-collection-region-staff-binding-demo.html b/docs/superpowers/demos/2026-09-18-collection-region-staff-binding-demo.html new file mode 100644 index 00000000..fba5c1c0 --- /dev/null +++ b/docs/superpowers/demos/2026-09-18-collection-region-staff-binding-demo.html @@ -0,0 +1,931 @@ + + + + + + 采集地区 · 人员绑定 Demo + + + + + + +
+
+ 交互 Demo（非最终实现）：展示「采集地区 ↔ 系统人员」绑定，以及将部分人员设为地区负责人。可切换两种交互方案对比。 +
+ +

采集地区 · 人员绑定

+

+ 页面：细胞采集基础信息维护 → 采集地区及医院。本 Demo 在现有「地区医院配置」旁增加「地区人员配置」。 +

+ +
+ + +
+ + +
+
+
+

采集地区及医院

+
+ +
+
+
+ + +
+
+ + +
+
+ + +
+
+
+ + +
+
+ +
+
+
已选 0 项
+ + +
+
+ +
+ + + + + + + + + + + + + + +
序号地区名称医院信息工作人员负责人创建时间操作
+
共 3 条 · 10 条/页 · 1
+
+
+ +
+ 方案 A：与现有「地区医院配置」对称 —— 操作列增加「地区人员配置」弹窗；主列表用摘要列展示工作人员数 / 负责人 Tag。 + 数据建议：关联表 biz_collection_region_staff（region_id + user_id + is_leader）。 +
+
+ + +
+
+
+

采集地区及医院

+
+
+
+
已选 0 项
+ +
+
+
+ + + + + + + + + +
地区已绑定人员（点击星标设为负责人）操作
+
+
+
+ 方案 B：主表行内直接展示人员 Chip，星标切换负责人；适合人员少、频繁调整的场景，但主表会变「胖」。 +
+
+
+ + + + + +
+
+
+
人员绑定（方案 B 弹窗备选）
+ +
+
+
+
+
候选人员
+
+
+
+
已绑定（绿底 = 负责人）
+
+
+
+
+
+ + +
+
+
+ +
+ + + + diff --git a/docs/superpowers/specs/2026-09-18-collection-region-staff-binding-design.md b/docs/superpowers/specs/2026-09-18-collection-region-staff-binding-design.md new file mode 100644 index 00000000..208eb534 --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-collection-region-staff-binding-design.md @@ -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 主列表 + +- 新增列：**工作人员**（多行姓名；空为 `—`）、**负责人**（``；空为 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`；模板页医院弹窗交互以本页现有实现为准