zkxw/docs/superpowers/specs/2026-10-08-protocol-market-specialist-region-manager-design.md

采集协议单：市场专员 / 采集地区 / 地区经理联动

日期： 2026-10-08
状态： 已确认待实现
范围： 细胞存储采集协议单 + 科研捐赠采集单（协议审核页两个 Tab 共用的表单/列表/查看）

背景

采集地区人员配置在「采集地区及医院」模块（biz_collection_region_staff）：

模块用语	业务用语
工作人员	市场专员
负责人（is_leader=1）	地区经理

采集协议单原字段「销售人员」需更名为「市场专员」，并按人员关联地区自动带出采集地区；再按所选地区带出地区经理并落库。

预签单（PresignOrderFormDialog）已有「采集经理 + 按地区负责人默认带出、可改选」模式，本设计对齐该行为。

目标

1. UI 文案：销售人员 → 市场专员（表单、列表列、查看弹窗、协议审核卡片展示）。
2. 选中市场专员后，采集地区选项收缩为其在 biz_collection_region_staff 中绑定的地区；多地区时默认第一项，可改选。
3. 市场专员仍可按姓名 remote 检索全部系统用户（不强制必须是已配置工作人员）。
4. 市场专员后新增「地区经理」：按当前采集地区负责人默认带出，可改选任意用户；必须写入采集信息表。
5. 细胞存储与科研捐赠两套采集单行为一致。

非目标

• 不改采集地区人员配置模块本身。
• 不做 HTML Demo。
• 不限制市场专员只能选自工作人员列表。
• 不重构预签单（仅复用其交互模式）。

数据模型

新增列

表	列	说明
biz_protocol_collection_info	region_manager_user_id VARCHAR(64) NULL	地区经理用户 ID
biz_research_donation_collection	region_manager_user_id VARCHAR(64) NULL	同上

迁移脚本放在 docs/sql/migrations/2026-10-08-protocol-region-manager.sql。

ORM / CRUD / CreateBody·UpdateBody / _row_to_dict / 前端 form 与提交体同步增加 regionManagerUserId；详情与列表填充 regionManagerUserName（由用户表昵称解析）。

既有 sales_user_id 字段保留，仅前端与注释语义改为「市场专员」。

API

新增：按用户查关联采集地区

GET /api/admin/collection-regions/by-staff-user/{userId}

• 租户隔离：仅当前用户 tenant_no。
• 查询 biz_collection_region_staff（del_flag=0）join 地区（del_flag=0）。
• 排序：order_num ASC，再 create_time DESC（与地区人员列表习惯一致）。
• 响应：{ list: [{ id, regionName }] }；无绑定时 list: []。

既有 GET /collection-regions/{regionId}/staff 继续用于按地区取负责人（与预签单一致）。

前端联动（ProtocolFormDialog + DonationFormDialog）

字段顺序（采集信息区）

市场专员 → 地区经理 → 采集地区 → 采集医院 → 采集医护 → 样本/母血采集时间 → …

市场专员

• Remote 检索全部启用用户（现状保留）。
• 新建默认当前登录人；默认后触发一次「按专员刷新关联地区」。

市场专员变更 → 采集地区

1. 调用 by-staff-user 取关联地区列表 linkedRegions。
2. 有关联：
   • 采集地区下拉选项 = linkedRegions（不再用全量 remote 检索，改为本地 filter 即可）。
   • 若当前已选地区仍在 linkedRegions 中则保留，否则默认第一项。
   • 若地区值发生变化：清空医院并重载；触发地区经理默认带出。地区未变则不强制改医院/经理。
3. 无关联：
   • 清空采集地区与医院。
   • 恢复全量地区 remote 检索（与改前一致），用户可手工选任意地区。
   • 清空地区经理（待用户选地区后再带出）。

采集地区变更 → 地区经理

• 清空医院并重载该地区医院。
• 拉取该地区 staff：优先 isLeader，否则取列表第一人；写入 regionManagerUserId 并保证 options 中有 stub。
• 地区经理控件：remote 检索全部用户、可 clear、可改选（对齐预签单「采集经理」）。

保存

提交 collectionInfo（或等价结构）时包含：

• salesUserId
• regionManagerUserId
• regionId / hospitalId / …

展示同步

以下位置文案与回显一并调整（有则改）：

位置	调整
ProtocolFormDialog / DonationFormDialog	label + 地区经理字段 + 联动
ProtocolViewDialog / DonationViewDialog	销售人员→市场专员；增加地区经理
协议列表 protocol/index.vue、科研捐赠 research-donation/list/index.vue	「销售人员」列改名为「市场专员」；列表不加「地区经理」列
protocol-audit 卡片（ProtocolAuditTab / DonationProtocolTab）	销售人员→市场专员；卡片增加地区经理展示

列表列策略： 列表只改名「市场专员」；地区经理在查看弹窗与审核卡片展示。

错误与边界

• 市场专员清空：清空关联地区约束，恢复全量地区检索；清空地区/医院/地区经理（与「无关联」一致）。
• 地区无任何 staff：地区经理留空，可手工选。
• 编辑回填：以库中已存 regionId / salesUserId / regionManagerUserId 为准；hydrate options stub；进入编辑后若用户改市场专员再走联动逻辑。
• 历史数据无 region_manager_user_id：展示为空，编辑保存时可补全。

测试

• 后端：by-staff-user 有/无绑定、租户隔离；采集信息 create/update/get 含 regionManagerUserId。
• 前端手工：新建默认专员→带地区；多地区默认第一可改；改地区→经理变化可改选；科研捐赠与细胞存储一致；编辑回显不丢经理。

参考实现

• 地区经理默认带出：web-admin/src/views/cell-storage/presign-order/PresignOrderFormDialog.vue 中 applyDefaultRegionManager
• 人员表：biz_collection_region_staff / backend/app/crud/collection_region.py