13 KiB
13 KiB
市场专员 / 地区经理：预签约订单移动端对齐 Web 设计
日期： 2026-10-11
状态： 视觉方向已通过 HTML Demo 确认，待设计文档确认
范围： mobile-oa-h5 预签约订单列表、表单及其配套移动 API；市场专员和地区经理使用同一套展示组件、不同角色路由与服务端数据范围
1. 背景与目标
现有移动市场模块使用通用配置驱动页面，已具备基础列表、详情、表单和移动 API，但预签约订单与 Web 管理端仍存在明显差距：
- 列表顶部使用了额外的绿色渐变头部，和小程序工作流页面不一致。
- 新增按钮占据列表顶部工具栏，状态下拉筛选与本期需求不符。
- 列表卡片只展示通用摘要，缺少 Web 端完整字段及编辑、转正式、删除操作。
- 表单仍使用原生 HTML 控件，采集地区、医院、缴费方式等未使用 Vant 移动选择器。
- 医院选项未随采集地区即时重新加载；缴费方式仍是普通文本输入。
- 意向金转账只支持新增时的通用重复块，未覆盖 Web 端编辑、提交财务确认、撤回和附件卡片能力。
- 列表仍使用“加载更多”按钮，不符合滚动触底动态分页要求。
本次目标是以 Web 管理端预签约订单为功能权威，以现有 OA 工作流移动页面为视觉与交互权威，把预签约订单完整复刻为移动端形式，并将其沉淀为后续其他市场模块改造的参考实现。
2. 权威参考
2.1 功能与字段权威
- 列表：
web-admin/src/views/cell-storage/presign-order/index.vue - 新增 / 编辑：
web-admin/src/views/cell-storage/presign-order/PresignOrderFormDialog.vue - Web API：
web-admin/src/api/presign-order.ts
2.2 移动视觉与交互权威
- 工作流卡片列表：
mobile-h5/pages/oa/pending/index.vue、mobile-h5/pages/oa/done/index.vue、mobile-oa-h5/src/views/OaHistory.vue - 工作流表单与固定底栏：
mobile-oa-h5/src/views/OaStart.vue - 工作流移动组件：
mobile-oa-h5/src/oa/components/* - UI 框架：Vant 4；
mobile-oa-h5/src/main.js已全局注册 Vant - 小程序品牌主色：
#0a9f6d，本模块不得使用 Web 管理端主色#10b981
2.3 已确认 HTML Demo
视觉确认稿由本次 brainstorming 会话生成：
- 列表保留白色顶部导航栏，移除绿色背景区域。
- 白色顶部栏显示返回按钮与“预签约订单”标题。
- 搜索框位于顶部栏下方。
- 右下角使用圆形悬浮新增按钮。
- 卡片显示 Web 列表全部业务字段与操作。
- 表单采用移动 Cell、底部选择器、分区卡片和固定底栏。
3. 方案比较与选择
方案 A：继续扩充通用配置驱动页面
在 presign.js 中增加更多字段配置，并不断增强 MarketFormField、MarketListCard。
优点是改动文件少；缺点是预签约订单的级联查询、人员远程搜索、意向金多状态操作和附件卡片会迫使通用配置层加入大量业务特例，后续其他模块更难维护。
方案 B：预签约订单专用页面 + 复用市场基础设施（采用）
为预签约订单提供专用列表卡片、专用新增 / 编辑表单及必要的业务组件；继续复用现有路由上下文、鉴权、HTTP、错误处理、请求状态和品牌 Token。
优点是能准确对齐 Web 功能，同时把成熟的移动交互组件沉淀为后续市场模块模板；缺点是会增加少量专用组件。
方案 C：逐段复制 Web 组件逻辑
把 Web 表格、弹窗与 Element Plus 交互直接翻译到移动端。
该方案功能映射直接，但会把桌面布局思路带入移动端，难以复用 OA 工作流组件，也不符合用户已确认的移动 Demo，因此不采用。
4. 列表页设计
4.1 页面结构
从上至下固定为：
- 白色顶部导航栏：返回按钮 + 居中标题“预签约订单”。
- 白色搜索区域：只保留一个关键词输入框，占位文案“搜索母亲姓名 / 协议编号”。
- 可滚动卡片列表。
- 右下角圆形悬浮新增按钮，按钮尺寸不小于 56×56px，
+水平、垂直居中。
明确移除：
- 原
MarketPageShell的绿色渐变标题区域。 - 列表顶部“新增预签约订单”长按钮。
- “全部状态”下拉筛选。
- 手工“加载更多”按钮。
4.2 卡片字段
每张卡片必须与 Web 表格展示字段一致：
| 顺序 | 字段 | 移动端展示 |
|---|---|---|
| 1 | 序号 | 左上角品牌绿圆形编号，跨分页连续编号 |
| 2 | 业务日期 | YYYY-MM-DD |
| 3 | 协议编号 | 无值显示 - |
| 4 | 母亲姓名 | 卡片主标题 |
| 5 | 预产期 | YYYY-MM-DD |
| 6 | 合同金额 | ¥ + 两位小数，无值显示 - |
| 7 | 到账金额 | ¥ + 两位小数，无值显示 - |
| 8 | 状态 | Vant Tag，文案与 Web 状态注册表一致 |
| 9 | 创建时间 | 移动端紧凑时间格式，但信息不得丢失 |
卡片底部操作与 Web 一致：
编辑：与 Web 一致始终显示；已转正式订单进入只读表单，不允许保存。转正式：非已转正式、非已作废且后端返回convert时显示。删除：非已转正式且后端返回delete时显示。
前端不得只根据状态自行推导权限；最终可见操作取“前端动作白名单 ∩ 后端 allowedActions”。
4.3 搜索与动态分页
- 输入关键词后，点击键盘搜索触发第一页加载；清空输入框立即重载第一页。
- 列表使用 Vant
List的滚动触底加载语义，分页大小保持 10。 - 首次加载、追加加载、空态、首屏失败和追加失败分别展示对应状态。
- 新搜索、保存返回、删除成功或转正式成功后重置到第一页，禁止与旧请求结果串页。
finished依据当前已加载条数与服务端total计算。- 默认排序继续由后端保证
create_time DESC。
5. 新增 / 编辑页设计
5.1 页面与底栏
- 顶部使用白色导航栏，标题为“新增预签约订单”或“编辑预签约订单”。
- 表单正文独立滚动，底部固定“取消 / 确定”操作栏，对齐
OaStart。 - 主操作按钮使用
#0a9f6d，所有点击目标不小于 44×44px。 - 表单按“预签信息”“意向金转账”分区，采用白色卡片 + 品牌绿标题竖条。
5.2 预签信息字段
字段、顺序、默认值、必填性和禁用规则与 Web 表单一致：
- 业务日期：日期选择器，新增默认当天。
- 协议编号：文本，可选。
- 母亲姓名：文本，必填。
- 预产期：日期选择器。
- 采集地区：数据库选项，Vant 弹出选择器。
- 医院：数据库选项，Vant 弹出选择器；未选地区时禁用。
- 采集专员：远程检索用户；新增默认当前用户；已转正式禁用。
- 采集经理：选择地区后默认该地区负责人，允许重新远程选择；已转正式禁用。
- 采集时间：日期时间选择器。
- 缴费方式：下拉选择，
趸交(dj)/分期(fq)，新增默认趸交。 - 整单合同金额(元)：金额输入，最小值 0。
- 订单状态：
草稿 / 进行中 / 已转正式 / 已作废；已转正式禁用。 - 样本类型：数据库选项、多选、必填。
- 备注：最多 500 字。
5.3 地区、医院与负责人级联
- 首次打开表单时加载地区、样本类型、转账方式等公共选项。
- 选择采集地区后立即清空原医院，并以
regionId重新请求医院选项。 - 同时加载地区工作人员，优先选择
isLeader=1的负责人作为采集经理默认值。 - 编辑页先回填地区，再加载该地区医院，最后回填医院，避免跨地区脏选项。
- 服务端继续校验地区、医院、样本类型均属于当前租户，且医院确实属于所选地区。
- 选择器中显示节点名称；表单回显使用业务名称，不显示数据库 ID。
5.4 移动选择器组件
- 单选字段使用
van-field只读入口 +van-popup/van-picker。 - 日期使用
van-popup/van-date-picker。 - 日期时间使用日期、时间两步选择或可复用的 OA 日期时间组件。
- 多选样本类型使用底部弹层 +
van-checkbox-group，确认后以 Tag 列表回显。 - 人员远程搜索使用底部弹层中的
van-search+ 可滚动结果列表。 - 金额输入优先复用 OA Money Field 的格式和校验方式。
6. 意向金转账设计
6.1 转账卡片字段
每笔转账在移动端表现为独立卡片，字段与 Web 一致：
- 转账方式：数据库字典选项。
- 转账金额(元)：金额输入。
- 转账时间：日期时间选择器。
- 转账凭证：上传卡片 + 已上传附件卡片。
- 备注。
- 财务备注：只读。
- 状态：Vant Tag。
6.2 附件上传
- 使用 Vant
Uploader的移动交互，上传按钮作为附件列表中的第一张卡片。 - 选择文件后立即上传；附件值仍以逗号分隔 URL 传输，后端继续验证附件登记与业务绑定。
- 图片按 1:1
aspectFill展示；非图片展示文件类型图标。 - 支持预览、下载和删除；单文件上限与 Web 一致为 20MB。
- 上传中、上传失败必须有明确状态，提交时不得携带仍在上传或失败的附件。
6.3 转账操作
与 Web 端一致：
- 添加转账笔。
- 待付款（
dfj）：允许修改、删除；已保存记录允许“提交财务确认”。 - 待财务确认（
jfqrz）：字段锁定，允许“撤回”。 - 已确认（
yjf）及其他锁定状态：字段只读，不允许删除。 - 已转正式订单：全部转账字段与主表单只读。
新增订单保存时可连同新转账笔一次创建；编辑订单时分别创建或更新未锁定的转账记录。
7. 确认操作与反馈
- 转正式、删除订单、撤回转账、删除转账笔均使用 Vant Confirm Dialog。
- 转正式确认文案与 Web 保持同一业务含义，明确人员和意向金会带入正式协议。
- 成功反馈使用 Vant Success Toast，失败使用统一
marketErrorMessage。 - 操作进行中禁用重复点击，并在按钮内展示 loading。
8. 前后端改造边界
8.1 mobile-oa-h5
- 预签约订单列表与表单切换为专用页面/组件，不再受通用
MarketListCard三字段摘要限制。 - 复用现有市场路由上下文、请求状态、鉴权 token、错误映射和
action-policy。 presign.js继续保留模块元数据，但不再承担复杂表单渲染。- 新增删除订单、转账创建/更新/提交/撤回等移动 API 调用。
8.2 backend
在现有两套固定 scope 路由下补齐与 Web 对齐的能力：
DELETE /api/mini/market/{scope}/presign-orders/{id}：软删除订单；已转正式不可删除。- 预签转账创建、更新、删除、提交财务确认和撤回端点。
form-options支持按regionId返回医院和地区负责人，并返回缴费方式、转账方式、状态等规范选项。- 列表和详情 DTO 返回 Web 所需全部字段与准确
allowedActions。 - 所有读写继续执行租户隔离、角色数据权限和当前页面现场 scope；客户端不得覆盖
tenant_no、sales_user_id或 scope。
8.3 不改动范围
- 不改变 Web 管理端既有行为。
- 不改变市场专员 / 地区经理两套路由和 scope 设计。
- 不在
mobile-h5小程序壳中实现业务表单。 - 不顺带改造协议、缴费、样本、运费等其他市场模块；它们在本模块验收后逐个参照改造。
9. 测试策略
9.1 前端
- 列表请求状态：首次、追加、搜索重置、重复触底、过期响应、追加失败重试。
- 卡片字段格式与动作可见性。
- 地区变更清空医院并重新加载；编辑回填顺序正确。
- 缴费方式、样本类型、人员选择器值映射。
- 转账锁定状态、上传状态和动作策略。
- 删除、转正式成功后列表重载。
pnpm build通过。
9.2 后端
- 专员与经理 scope 的列表、详情、更新、删除和转账操作隔离。
- 跨租户主数据、跨地区医院、越权人员和伪造附件拒绝。
- 已转正式 / 已作废订单不能编辑、删除或再次转正式。
- 转账状态机：待付款可改删可提交；待财务确认可撤回；已确认不可改删。
- 默认排序与分页稳定。
- 运行相关测试后再运行后端全量测试。
9.3 知识图谱
完成代码修改后按仓库规则执行：
./scripts/update-graph.sh backend- 涉及
mobile-oa-h5，当前图谱脚本无该目标；若本次同时修改web-admin才执行./scripts/update-graph.sh frontend。
10. 验收标准
- 列表保留白色顶部栏，完全移除绿色标题背景区域。
- 列表只提供关键词搜索；没有状态筛选和顶部新增长按钮。
- 右下角显示品牌绿圆形
+悬浮按钮，点击进入新增页。 - 卡片显示 Web 列表全部字段，并提供同等的编辑、转正式、删除能力。
- 上滑触底自动加载下一页，直到服务端数据加载完毕。
- 新增 / 编辑字段、默认值、校验、禁用规则与 Web 一致。
- 地区、医院、人员、缴费方式、样本类型和转账方式均使用数据库或规范枚举选项；地区与医院正确级联。
- 意向金转账、附件上传、提交财务确认与撤回行为与 Web 一致。
- 市场专员与地区经理只看到和操作各自 scope 内的数据。
- 页面使用 Vant 4 与工作流移动风格，品牌主色为
#0a9f6d，不混用 Web 主色。