2647 lines
133 KiB
Markdown
2647 lines
133 KiB
Markdown
# 风险防控管理系统业务与技术需求分析推断报告
|
||
|
||
> 文档版本：V0.5（接口字段契约完善稿）
|
||
> 分析日期：2026-08-13
|
||
> 主要依据：`deprecated/build/20260812 prototype` 静态原型
|
||
> 参考输入：`docs/前期讨论/001-后端API文档-用户管理相关.md`、`docs/前期讨论/002-服务风险防控-工作流程-V2.pos`
|
||
|
||
## 1. 文档目的与结论
|
||
|
||
本文档将静态原型还原为可评审的业务与技术需求，覆盖页面、角色、业务流程、字段、接口和后端约束。20260812 原型共 41 个画板，其中 1 个名称带“备份”的画板属于页面状态变体；按业务能力合并后，可归纳为 18 类页面、12 个主要流程步骤、7 类业务角色。
|
||
|
||
系统核心业务是将线下取得的 12398 工单导入系统，关联 95598 业务处理信息，由服务监督主管判定主责或协查并派工。派工后服务监督员可以先行填报部分调查信息并保存草稿，但主责工单必须等待首联及全部初查完成、协查工单必须等待全部初查完成后才能提交。两级审核完成后，业务部主任基于派工阶段持久化的责任类型分支：主责进入回访，协查直接进入 11 调查报告编写；报告页面以汇总调查及回访信息并确认下载为主要交互。
|
||
|
||
原型能够证明页面展示、操作入口和大部分表单字段，但不能证明数据库结构、全部枚举值、必填规则、接口路径、异常处理、状态码和数据权限。本报告对这些内容采用以下标记：
|
||
|
||
| 标记 | 含义 |
|
||
| --- | --- |
|
||
| 已确认 | 原型或已有接口文档直接展示，可作为当前需求基线 |
|
||
| 参考补充 | 来自前期流程图，仅作需求评审输入，需业务确认 |
|
||
| 技术建议 | 为保证系统可实现、可审计而提出的设计建议 |
|
||
| 待确认 | 现有材料存在缺口或冲突，不能直接作为开发定论 |
|
||
|
||
### 1.1 版本变化
|
||
|
||
V0.5 主要变化：
|
||
|
||
- 将第 8 章重排为 8.1～8.12 连续章节，修复接口目录合并后遗留的跳号问题。
|
||
- 所有目录接口统一补充请求字段定义和响应字段定义，明确字段位置、类型、必填条件及业务含义。
|
||
- 保留请求与响应示例作为字段表的补充，并修正登录返回结构及章节交叉引用。
|
||
|
||
V0.4 主要变化：
|
||
|
||
- 为接口补充可直接用于联调的请求头、请求字段、响应字段、分页、错误响应和状态变更约定。
|
||
- 明确主责/协查派工、前置任务校验及业务部主任审核分支在接口层的表达方式。
|
||
- 补充联调枚举、版本字段、幂等键、文件引用和异步任务查询规则。
|
||
|
||
V0.3 主要变化：
|
||
|
||
- 将 41 张画板编号和名称整体切换到 20260812 原型，删除旧原型中的重复/备份编号判断。
|
||
- 固化服务监督主管判定主责/协查并派工、服务监督员先行填报及分支前置条件。
|
||
- 补入业务部主任审核弹窗和完整审核页，并明确协查审核通过后直接进入 11 调查报告编写。
|
||
- 将报告需求由“在线编辑并提交”调整为“汇总业务信息、确认生成并受权下载”，同时统一回访结果枚举和条件附件规则。
|
||
|
||
## 2. 分析范围与证据
|
||
|
||
### 2.1 分析范围
|
||
|
||
- 登录与当前用户识别；
|
||
- 12398 工单文件导入、预览、确认和批次查询；
|
||
- 工单查询、待办和工单详情；
|
||
- 服务监督主管判定主责/协查并派工、智能派工、回访分派；
|
||
- 首联、事件初查、调查结果填报；
|
||
- 服务监督主管审核、业务部主任审核；
|
||
- 回访结果、答复书及送达凭证；
|
||
- 调查报告、成果物输出；
|
||
- 派工规则、流程时限和统计分析；
|
||
- 角色权限、状态流转、审计、幂等、并发、文件与安全约束。
|
||
|
||
### 2.2 不在本稿中定论的内容
|
||
|
||
- 技术栈、部署架构、中间件和数据库产品；
|
||
- 组织机构与岗位编码的最终数据模型；
|
||
- 与 12398、95598 外部系统的在线对接方式；
|
||
- 智能派工、智能写作和“五级溯源”的算法实现；
|
||
- 统计指标口径、绩效考核与整改闭环的详细规则；
|
||
- 法定保存期限、附件大小和文件格式白名单的具体数值。
|
||
|
||
### 2.3 证据边界
|
||
|
||
1. 原型的日期、姓名、电话、工单号和数量均为示例数据，不应固化为业务规则。
|
||
2. 画板间没有足够完整的可执行跳转链，流程顺序主要由页面名称、按钮、表单内容及前期流程图交叉还原。
|
||
3. “备份”画板只用于识别方案差异，不应直接形成重复页面或重复接口。
|
||
4. `001-后端API文档-用户管理相关.md` 只确认登录及用户查询相关接口，不代表工单业务接口已经存在。
|
||
5. 20260812 原型替代 20260811 原型作为当前页面和字段基线；旧原型仅用于识别变化，不再作为编号或页面状态依据。
|
||
6. 已确认的主责/协查流程规则优先于画板中的静态展示。若画板仍同时展示不适用于协查的首联或回访字段，应视为设计待同步，而不能据此改变业务分支。
|
||
|
||
## 3. 业务范围与领域对象
|
||
|
||
### 3.1 核心领域对象
|
||
|
||
| 对象 | 说明 | 关键关系 |
|
||
| --- | --- | --- |
|
||
| 导入批次 ImportBatch | 一次 Excel/CSV 预览和确认导入记录 | 包含多条导入行，成功后产生或更新工单 |
|
||
| 12398 工单 WorkOrder | 系统的核心业务聚合 | 关联客户、分类、任务、95598 记录、附件、报告和审计轨迹 |
|
||
| 95598 处理记录 ServiceRecord | 与 12398 工单关联的历史业务处理信息 | 一张 12398 工单可关联多条记录、录音和转译文本 |
|
||
| 流程实例 ProcessInstance | 记录工单当前环节、状态、时限和流程版本 | 一张工单原则上对应一个有效流程实例 |
|
||
| 待办任务 Task | 分派到角色、部门、岗位或人员的可执行工作项 | 支持并行初查、单人首联、审核和回访任务 |
|
||
| 派工记录 Dispatch | 服务监督主管的主责/协查判定，以及首联、初查、监督员和提级督办选择 | 按责任类型产生对应待办任务，并向服务监督员开放调查填报 |
|
||
| 首联记录 FirstContact | 客服班组首次联系客户的结果 | 属于一张工单及一个首联任务 |
|
||
| 初查记录 PreliminaryInvestigation | 被选部门对事件的初步调查结果 | 多部门可并行，一任务一记录 |
|
||
| 全面调查 Investigation | 服务监督员可在派工后先行填报并保存草稿，待前置任务完成后提交完整调查结果 | 主责依赖首联及全部初查完成；协查依赖全部初查完成 |
|
||
| 审核记录 Review | 服务监督主管、业务部主任的审核结论 | 保留审核层级、结论、意见及驳回去向 |
|
||
| 回访记录 Callback | 主责工单的客服回访及服务监督员结果填报 | “不同意或客户主动要求”触发附件要求；协查工单不进入回访 |
|
||
| 调查报告 InvestigationReport | 基于调查及回访信息形成的报告版本和输出记录 | 最新原型以“确认下载”为主要动作；是否允许在线编辑或智能生成待确认 |
|
||
| 成果物 Deliverable | 办结输出物及其版本 | 与报告、附件和办结动作关联 |
|
||
| 规则配置 RuleConfig | 智能派工规则和流程时限配置 | 必须版本化并记录生效范围 |
|
||
|
||
### 3.2 业务关系要点
|
||
|
||
- 一个导入批次包含多条导入行；导入行应独立记录成功、失败和失败原因。
|
||
- 一张 12398 工单可关联多条 95598 处理记录。
|
||
- 一张工单可并行产生多个事件初查任务，但首联任务原则上为单选部门下的单个有效任务。
|
||
- 服务监督员首次指定后，后续调查、回访结果、报告和成果物环节原则上保持同一责任人（参考补充，待确认）；协查工单不产生回访任务，但仍由服务监督员完成报告。
|
||
- 审核、驳回和重新提交必须新增记录，不覆盖历史版本。
|
||
|
||
## 4. 页面梳理
|
||
|
||
### 4.1 页面结构总览
|
||
|
||
| 页面域 | 逻辑页面 | 主要能力 | 主要角色 |
|
||
| --- | --- | --- | --- |
|
||
| 公共 | 登录 | 账号、密码、验证码登录 | 全部用户 |
|
||
| 导入 | 工单导入、导入预览、导入明细 | 文件选择、批次号、预览、确认、批次历史 | 服务监督主管 |
|
||
| 查询 | 工单查询、工单详情 | 多条件查询、分页、详情查看 | 6 类业务角色 |
|
||
| 待办 | 待办列表、分类统计 | 按环节查看个人/岗位待办 | 除纯查询人员外的业务角色 |
|
||
| 派工 | 主管派单、智能派工 | 初查多选、首联单选、监督员、提级督办 | 服务监督主管 |
|
||
| 首联 | 首联分派、首联填报 | 分派班组/人员，填写首次联系信息 | 客服部主管、客服部班长/成员 |
|
||
| 调查 | 初查填报、全面调查填报 | 初查内容、调查问卷和处置结果 | 调查部门、服务监督员 |
|
||
| 审核 | 调查审核、业务审核 | 同意/不同意、驳回理由、按责任类型确定下步分支 | 服务监督主管、业务部主任 |
|
||
| 回访 | 回访分派、回访填报、结果确认 | 班组分派、回复信息、同意/不同意结果、条件附件 | 客服部主管、客服班组、服务监督员 |
|
||
| 输出 | 调查报告、成果物 | 汇总调查/回访信息、条件附件、确认下载、成果物输出 | 服务监督员 |
|
||
| 配置 | 智能派工规则、流程时限 | 规则维护、环节时限维护 | 服务监督主管或配置管理员 |
|
||
| 分析 | 统计分析 | 办结统计与展示 | 有菜单权限人员 |
|
||
|
||
### 4.2 41 个原型画板清单
|
||
|
||
| 原型编号 | 画板名称 | 页面状态/用途 | 处理结论 |
|
||
| --- | --- | --- | --- |
|
||
| 1-1 | 登录页2 | 登录 | 有效页面 |
|
||
| 1-2 | 服务监督主管-首页（工单导入）导入预览 | 导入文件后的行级预览 | 有效页面状态 |
|
||
| 1-3 | 服务监督主管-首页（工单导入）导入明细 | 历史批次列表 | 有效页面状态 |
|
||
| 1-4 | 服务监督主管-工单处理（审核弹窗） | 主管审核弹窗：审核结果、驳回理由、回访分派 | 有效页面状态；回访分派的实际生效时点待统一 |
|
||
| 1-5 | 服务监督主管-工单处理（待审核） | 主管待审核列表 | 有效页面状态 |
|
||
| 1-6 | 服务监督主管-规则配置-智能派工规则配置 | 智能派工规则入口 | 页面内容待补齐 |
|
||
| 1-7 | 服务监督主管-规则配置-流程时限管理 | 整体及环节时限配置 | 有效页面 |
|
||
| 1-8 | 服务监督主管-统计分析 | 统计分析入口 | 指标和图表待补齐 |
|
||
| 1-9 | 服务监督主管-工单处理（待审核） | 全量调查结果审核长页面 | 有效长页面 |
|
||
| 1-10 | 服务监督主管-工单处理（待分配派工） | 待派工列表和派工入口 | 有效页面状态 |
|
||
| 1-11 | 服务监督主管-待分派（确定标题版） | 主管派工详情 | 有效长页面；业务上由服务监督主管完成主责/协查判定和派工 |
|
||
| 1-12 | 服务监督主管-工单处理 | 主管任务总览 | 有效页面 |
|
||
| 1-13 | 服务监督人员-待办工单（调查结果填报）业务类型 | 调查表单简化/业务类型方案 | 与 1-21 的适用条件待确认 |
|
||
| 1-14 | 服务监督人员-待办工单（调查报告编写-不同意） | 报告确认下载及条件附件状态 | 有效条件分支 |
|
||
| 1-15 | 服务监督人员-待办工单（调查报告编写-同意） | 报告确认下载状态 | 有效页面状态 |
|
||
| 1-16 | 服务监督人员-待办工单（成果物输出） | 成果物输出 | 有效长页面；成果物清单仍待定义 |
|
||
| 1-17 | 服务监督人员-待办工单（处理工单）事件类型（回访结果填写）不同意上传 | “不同意或客户主动要求”附件状态 | 有效条件分支 |
|
||
| 1-18 | 业务部主任-待办工单（审核）（弹窗） | 二级审核弹窗：审核结果、驳回理由、回访分派 | 有效页面状态；协查通过后业务上不应要求回访分派 |
|
||
| 1-19 | 业务部主任-待办工单（审核） | 二级审核完整详情 | 有效长页面 |
|
||
| 1-20 | 服务监督人员-待办工单（处理工单）事件类型（回访结果填写） | 回访结果完整表单 | 有效长页面 |
|
||
| 1-21 | 服务监督人员-待办工单（调查结果填报） | 全面调查表单 | 有效长页面 |
|
||
| 1-22 | 服务监督人员-待办工单 | 调查、报告、回访、成果物待办总览 | 有效页面 |
|
||
| 1-23 | 总值班经理待办工单-待调查（处理） | 初查内容填报 | 有效页面 |
|
||
| 1-24 | 智能运营团队-待办工单-待调查（处理） | 初查内容填报 | 有效页面 |
|
||
| 1-25 | 客服部主管-待办工单-待调研 | 客服部门初查 | 有效页面 |
|
||
| 1-26 | 客服部班长-待办工单备份 | 首联填写状态 | 页面状态有效，名称应去掉“备份” |
|
||
| 1-27 | 业务部主任-待办工单 | 业务审核列表 | 有效页面 |
|
||
| 1-28 | 总值班经理-待办工单 | 初查待办列表 | 有效页面 |
|
||
| 1-29 | 智能运营团队-待办工单 | 初查待办列表 | 有效页面 |
|
||
| 1-30 | 客服部班长-待办工单 | 首联待办列表 | 有效页面 |
|
||
| 1-31 | 客服部主管-待办工单-回访分派 | 回访任务选择班组/人员 | 有效页面 |
|
||
| 1-32 | 客服部主管-待办工单-首联分派 | 首联任务选择班组/人员 | 有效页面 |
|
||
| 1-33 | 客服部主管-待办工单 | 任务总数、首联分派、回访分派入口 | 有效页面 |
|
||
| 1-34 | 业务部主任 | 工单查询 | 有效页面，名称需规范化 |
|
||
| 1-35 | 总值班经理-工单查询 | 工单查询 | 有效页面 |
|
||
| 1-36 | 智能运营团队-工单查询 | 工单查询 | 有效页面 |
|
||
| 1-37 | 客服部班长-工单查询 | 工单查询 | 有效页面 |
|
||
| 1-38 | 客服部主管-工单查询 | 工单查询 | 有效页面 |
|
||
| 1-39 | 服务监督人员-工单查询 | 工单查询 | 有效页面 |
|
||
| 1-40 | 服务监督主管-工单查询 | 工单查询 | 有效页面 |
|
||
| 1-41 | 服务监督主管-首页（工单导入） | 导入入口 | 有效页面 |
|
||
|
||
### 4.3 通用列表需求
|
||
|
||
工单查询页在各角色间基本一致，应实现为同一页面组件加数据权限，而不是复制六套接口。查询条件包括：12398 工单编号、工单环节、信息来源、客户致电 12398 日期、转办日期、客户名称、联系方式、用户地址、客户所在地区（省）、省份、事件类型、转办事项分类、问题分类。
|
||
|
||
列表至少展示：序号、12398 工单编号、工单状态/环节、信息来源、客户致电日期、转办日期、客户名称、联系方式、用户地址、客户所在地区及操作。列表必须服务端分页，排序字段使用白名单，手机号按权限脱敏。
|
||
|
||
待办列表应与查询列表区分：查询页返回用户可见工单，待办页只返回当前用户可办理的有效任务。任务统计卡片必须与相同筛选口径下的列表一致。
|
||
|
||
## 5. 角色与权限梳理
|
||
|
||
### 5.1 业务角色
|
||
|
||
| 角色 | 主要职责 | 原型可见菜单 | 关键操作 |
|
||
| --- | --- | --- | --- |
|
||
| 服务监督主管 | 导入、主责/协查判定与派工、调查一级审核、规则与时限管理 | 工单导入、工单查询、工单处理、规则配置、统计分析 | 预览/确认导入、判定责任类型并派工、审核、维护配置；原型显示的回访分派生效时点待统一 |
|
||
| 服务监督人员 | 全面调查、回访结果、调查报告、成果物 | 工单查询、待办工单 | 派工后先行填报调查草稿，满足前置条件后提交；填回访结果、上传材料、确认下载报告、输出成果物 |
|
||
| 客服部主管 | 将首联或回访任务分派到本部门班组/人员，也可承担部门初查 | 工单查询、待办工单 | 首联分派、回访分派、初查提交 |
|
||
| 客服部班长/成员 | 执行首联或客户回访 | 工单查询、待办工单 | 填写首联时间、首联工单号、首联内容；回访表单待进一步确认 |
|
||
| 智能运营团队 | 执行被派发的事件初查 | 工单查询、待办工单 | 填写初查内容并提交 |
|
||
| 总值班经理/团队 | 执行被派发的事件初查 | 工单查询、待办工单 | 填写初查内容并提交 |
|
||
| 业务部主任 | 对调查结果进行第二级业务审核，并依据前序责任类型触发后续分支 | 工单查询、待办工单 | 审核同意/不同意并填写意见；主责进入回访，协查直接进入调查报告 |
|
||
| 系统任务（建议） | 导入解析、时限计时、提醒、统计、智能派工/写作 | 无人工菜单 | 异步处理、规则计算、通知和审计 |
|
||
|
||
> 原型出现 7 个业务称谓，但“客服部班长/成员”可建模为同一执行角色下的岗位或人员范围；“智能运营团队”和“总值班经理”更适合作为可被派工的组织/岗位，而非写死在流程代码中。
|
||
|
||
### 5.2 权限矩阵
|
||
|
||
| 能力 | 监督主管 | 监督人员 | 客服主管 | 客服班组 | 智能运营 | 总值班 | 业务主任 |
|
||
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||
| 导入工单 | 写 | - | - | - | - | - | - |
|
||
| 查询可见工单 | 读 | 读 | 读 | 读 | 读 | 读 | 读 |
|
||
| 查看完整客户联系方式 | 按权限 | 按任务 | 按任务 | 按任务 | 按任务 | 按任务 | 按审核任务 |
|
||
| 主管派工 | 写 | - | - | - | - | - | - |
|
||
| 首联/回访班组分派 | - | - | 写 | - | - | - | - |
|
||
| 首联填报 | - | - | 可选 | 写 | - | - | - |
|
||
| 初查填报 | - | - | 写 | - | 写 | 写 | - |
|
||
| 全面调查填报 | - | 写 | - | - | - | - | - |
|
||
| 调查一级审核 | 写 | - | - | - | - | - | - |
|
||
| 调查二级审核 | - | - | - | - | - | - | 写 |
|
||
| 回访结果填报/材料 | - | 写 | 分派 | 执行待确认 | - | - | - |
|
||
| 报告和成果物 | - | 写 | - | - | - | - | - |
|
||
| 规则与时限 | 写或配置管理员 | - | - | - | - | - | - |
|
||
| 统计分析 | 按菜单权限 | 按菜单权限 | 按菜单权限 | 按菜单权限 | 按菜单权限 | 按菜单权限 | 按菜单权限 |
|
||
|
||
### 5.3 数据权限原则
|
||
|
||
- 服务监督主管：可查看其管理范围内全部工单和任务。
|
||
- 执行角色：默认只查看本人、本岗位或本部门被分派的工单；跨部门信息按任务需要开放。
|
||
- 查询权限与办理权限分离；能查看工单不代表可以提交当前任务。
|
||
- 联系方式、地址、录音、转译文本和附件属于敏感业务数据，应分别控制查看、播放、下载和导出权限。
|
||
- 所有写操作必须以服务端当前任务所有者、角色、状态和版本为准，不能只依赖前端隐藏按钮。
|
||
|
||
## 6. 业务流程
|
||
|
||
### 6.1 主流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["01 线下导入12398工单"] --> B["服务监督主管判定主责或协查并派工"]
|
||
B -. "同时开放" .-> H["05 服务监督员可先行填报并保存调查草稿"]
|
||
B --> R{"服务监督主管判定结果"}
|
||
R -->|"主责"| C["02 客服主管分派首联"]
|
||
C --> D["03 客服班组完成首联"]
|
||
R -->|"主责"| E["04 多部门并行事件初查"]
|
||
R -->|"协查"| E
|
||
D --> F{"主责：首联及全部初查均完成"}
|
||
E -->|"主责"| F
|
||
E -->|"协查"| G{"协查：全部初查均完成"}
|
||
H -. "只能在对应前置条件满足后提交" .-> S["05 提交全面调查"]
|
||
F --> S
|
||
G --> S
|
||
S --> I["06 服务监督主管审核"]
|
||
I -->|"不通过"| H
|
||
I -->|"通过"| J["07 业务部主任审核"]
|
||
J -->|"不通过"| H
|
||
J -->|"通过"| Q{"按服务监督主管前序判定分支"}
|
||
Q -->|"主责"| K["08 客服主管分派回访"]
|
||
Q -->|"协查"| O["11 调查报告编写"]
|
||
K --> L["09 客服班组回访"]
|
||
L --> M["10 服务监督员填报回访结果"]
|
||
M -->|"不同意或客户主动要求"| N["上传答复书和送达凭证"]
|
||
M -->|"同意"| O["11 调查报告编写"]
|
||
N --> O
|
||
O --> P["12 成果物输出并办结"]
|
||
```
|
||
|
||
### 6.2 流程步骤明细
|
||
|
||
| 步骤 | 操作人 | 输入 | 操作/输出 | 进入下一步条件 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 01 导入 | 服务监督主管 | Excel/CSV、导入批次 | 预览校验，确认生成工单 | 批次确认成功且行级校验通过 |
|
||
| 01A 判定派工 | 服务监督主管 | 工单、95598 记录 | 判定主责/协查，选择初查部门、首联部门、监督员、提级督办；同时向服务监督员开放调查填报 | 派工事务成功；服务监督员可开始填报和保存草稿 |
|
||
| 02 首联分派 | 客服部主管 | 首联任务 | 选择本部门班组/人员 | 目标人员有效且属于授权范围 |
|
||
| 03 班组首联 | 客服班组 | 客户及工单信息 | 填首联时间、首联工单号、首联内容 | 首联任务提交完成 |
|
||
| 04 事件初查 | 被派部门主管/岗位 | 工单及 95598 记录 | 填写初查内容 | 每个并行初查任务均提交完成 |
|
||
| 05 全面调查 | 服务监督人员 | 工单信息，以及办理过程中逐步形成的首联和初查信息 | 派工后可先行填报并保存部分信息；前置任务完成后提交完整调查表 | 主责：首联及全部初查完成；协查：全部初查完成；表单校验通过 |
|
||
| 06 主管审核 | 服务监督主管 | 调查版本 | 同意或驳回并填写意见 | 同意进入二级审核；驳回重开调查 |
|
||
| 07 业务审核 | 业务部主任 | 已通过一级审核的调查版本、服务监督主管前序判定结果 | 同意或驳回并填写意见 | 不同意则重开调查；同意且为主责进入回访，同意且为协查直接进入调查报告 |
|
||
| 08 回访分派 | 客服部主管 | 主责工单的回访任务 | 选择本部门班组/人员 | 仅主责工单进入；目标人员有效 |
|
||
| 09 班组回访 | 客服班组 | 主责工单的联系信息、处理结果 | 记录客户联系及原始回访情况 | 回访执行任务完成 |
|
||
| 10 回访结果 | 服务监督人员 | 主责工单的回访执行记录 | 填回复人、时间、电话、回复情况、结果 | “不同意或客户主动要求”分支附件齐全 |
|
||
| 11 调查报告 | 服务监督人员 | 调查数据；主责还包括回访及条件附件 | 核对报告上下文并确认生成/下载 | 主责在回访结果完成后进入；协查在业务部主任审核通过后直接进入；报告输出版本生成成功 |
|
||
| 12 成果物/办结 | 服务监督人员 | 报告和附件 | 汇总、输出、确认办结 | 必备成果物齐全且不存在未完成任务 |
|
||
|
||
### 6.3 主责与协查分支
|
||
|
||
流程分支规则如下：
|
||
|
||
- 服务监督主管负责判定工单属于主责还是协查，并完成派工；该判定结果必须随流程实例持久化，供后续分支使用。
|
||
- 主责工单同时产生首联任务、一个或多个并行事件初查任务，并向指定服务监督员开放全面调查填报。
|
||
- 协查工单从服务监督主管派工直接进入 04 多部门并行事件初查，不产生首联任务；同时向指定服务监督员开放全面调查填报。
|
||
- 服务监督员在派工完成后即可先行填写部分调查信息并保存草稿，无需等待首联或初查结束。
|
||
- 全面调查的“提交”动作受前置条件约束：主责必须等待首联及全部初查完成；协查必须等待全部初查完成。前置条件未满足时只能继续编辑或保存草稿。
|
||
- 服务监督主管审核通过后进入业务部主任审核。业务部主任审核通过时，系统读取服务监督主管在派工阶段作出的判定：主责进入 08～10 回访流程，协查直接进入 11 调查报告编写。
|
||
- 事件初查部门可多选；主责工单的首联部门单选。
|
||
|
||
### 6.4 建议状态模型
|
||
|
||
不建议只使用原型中的“待分派/处理中/已结束”三个展示状态驱动流程。建议拆分“工单生命周期状态”和“任务环节状态”：
|
||
|
||
| 类型 | 建议状态 |
|
||
| --- | --- |
|
||
| 工单生命周期 | `IMPORTED` 已导入、`DISPATCHING` 待派工、`PROCESSING` 办理中、`REVIEWING` 审核中、`CALLBACK` 回访中、`REPORTING` 报告中、`CLOSED` 已办结、`CANCELLED` 已取消 |
|
||
| 任务状态 | `PENDING` 待领取/待办理、`ASSIGNED` 已分派、`IN_PROGRESS` 办理中、`SUBMITTED` 已提交、`APPROVED` 已通过、`REJECTED` 已驳回、`COMPLETED` 已完成、`CANCELLED` 已取消 |
|
||
| 流程环节 | `DISPATCH`、`FIRST_CONTACT_ASSIGN`、`FIRST_CONTACT`、`PRELIMINARY_INVESTIGATION`、`INVESTIGATION`、`SUPERVISOR_REVIEW`、`BUSINESS_REVIEW`、`CALLBACK_ASSIGN`、`CALLBACK`、`CALLBACK_RESULT`、`REPORT`、`DELIVERABLE` |
|
||
|
||
工单状态由有效任务和流程实例聚合计算，不允许客户端直接提交任意目标状态。
|
||
|
||
## 7. 字段梳理
|
||
|
||
### 7.1 字段约定
|
||
|
||
- `ID` 建议使用系统内部不可猜测标识；业务编号另设唯一字段。
|
||
- 日期使用 `YYYY-MM-DD`，日期时间使用带时区的 ISO 8601；存储使用统一时区，展示按用户时区转换。
|
||
- `是否`类字段使用布尔或明确枚举，不使用自由文本。
|
||
- 所有枚举保存稳定编码，界面显示名称通过字典返回。
|
||
- “必填”在原型中未用星号完整表达，以下仅将流程成立所需字段标为“建议必填”，最终以业务评审为准。
|
||
|
||
### 7.2 登录与用户上下文
|
||
|
||
| 字段 | 建议类型 | 必填 | 来源/说明 |
|
||
| --- | --- | :---: | --- |
|
||
| username | string(64) | 是 | 登录账号 |
|
||
| password | string | 是 | 只用于认证请求，不落业务日志 |
|
||
| code | string(16) | 是 | 验证码 |
|
||
| uuid | string(64) | 是 | 验证码唯一标识 |
|
||
| userId | int64/string | 系统 | 当前用户标识 |
|
||
| nickName | string(64) | 系统 | 页头显示名称 |
|
||
| deptId | int64/string | 系统 | 数据权限和派工候选范围 |
|
||
| roleIds/postIds | array | 系统 | 菜单与操作授权 |
|
||
|
||
### 7.3 导入批次与导入行
|
||
|
||
| 字段 | 建议类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| batchId | string | 系统 | 导入批次内部标识 |
|
||
| batchNo | string(64) | 是 | 原型示例 `20260806-B01`，需唯一性规则 |
|
||
| fileId/fileName | string | 是 | 原始导入文件 |
|
||
| importMode | enum | 是 | `EXCEL`/`CSV` |
|
||
| status | enum | 系统 | 上传中、预览成功、部分失败、已确认、已取消 |
|
||
| totalCount/successCount/failureCount | integer | 系统 | 批次数量统计 |
|
||
| importedBy/importedAt | string/datetime | 系统 | 操作人和时间 |
|
||
| previewToken | string | 系统 | 预览到确认之间的短期凭证，防止文件被替换 |
|
||
| rowNo | integer | 系统 | 原文件行号 |
|
||
| rowStatus | enum | 系统 | 有效、重复、错误、待确认 |
|
||
| errorCode/errorMessage | string | 否 | 行级错误原因 |
|
||
|
||
### 7.4 12398 工单基础信息
|
||
|
||
| 字段 | 建议类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| workOrderId | string | 系统 | 内部主键 |
|
||
| workOrderNo12398 | string(64) | 是 | 12398 工单编号，建议唯一 |
|
||
| orderStatus | enum | 系统 | 工单生命周期状态 |
|
||
| currentStage | enum | 系统 | 当前流程环节 |
|
||
| sourceCode | enum | 是 | 信息来源，如 12398 电话 |
|
||
| customerCalledAt | date/datetime | 是 | 客户致电 12398 日期/时间 |
|
||
| transferredAt | date/datetime | 是 | 转办日期/时间 |
|
||
| customerName | string(128) | 建议 | 客户名称 |
|
||
| contactPhone | string(32) | 建议 | 联系方式，密文或受控存储 |
|
||
| customerAddress | string(512) | 否 | 用户地址，敏感字段 |
|
||
| customerRegion | string(128) | 否 | 客户所在地区（省） |
|
||
| provinceCode | string(32) | 建议 | 省份稳定编码 |
|
||
| eventTypeCode | string(32) | 建议 | 事件类型 |
|
||
| transferCategoryCode | string(32) | 建议 | 转办事项分类 |
|
||
| problemCategoryCode | string(32) | 建议 | 问题分类 |
|
||
| responsibilityType | enum | 是 | 由服务监督主管在派工时判定：`PRIMARY` 主责 / `ASSIST` 协查；后续业务审核分支以该值为准 |
|
||
| escalationFlag | boolean | 否 | 是否提级督办 |
|
||
| processVersion | integer | 系统 | 流程/乐观锁版本 |
|
||
| createdAt/updatedAt | datetime | 系统 | 审计时间 |
|
||
|
||
### 7.5 95598 业务处理信息
|
||
|
||
| 字段 | 建议类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| serviceRecordId | string | 系统 | 记录标识 |
|
||
| serviceOrderNo95598 | string(64) | 建议 | 95598 工单编号 |
|
||
| acceptanceContent | text | 建议 | 受理内容 |
|
||
| businessTypeCode | string(32) | 否 | 业务类型 |
|
||
| acceptedAt | datetime | 否 | 受理时间 |
|
||
| powerSupplyOrgId/name | string | 否 | 供电单位编码及名称 |
|
||
| recordingFileId | string | 否 | 录音文件引用 |
|
||
| recordingDuration | integer | 否 | 录音时长（秒） |
|
||
| transcriptText | text | 否 | 转译文本 |
|
||
| sequenceNo | integer | 系统 | 同一工单内排序 |
|
||
|
||
### 7.6 派工信息
|
||
|
||
| 字段 | 建议类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| dispatchId | string | 系统 | 派工记录标识 |
|
||
| workOrderId | string | 是 | 所属工单 |
|
||
| responsibilityType | enum | 是 | 服务监督主管在派工时判定主责/协查，并持久化到流程实例 |
|
||
| preliminaryDeptIds | array<string> | 是 | 初查部门，多选且去重 |
|
||
| firstContactDeptId | string | 主责必填 | 首联部门，单选；协查应为空 |
|
||
| supervisorUserId | string | 是 | 服务监督员，单选 |
|
||
| escalationDeptIds | array<string> | 否 | 提级督办部门多选 |
|
||
| dispatchMode | enum | 是 | `MANUAL`/`SMART` |
|
||
| ruleVersion | integer | 智能派工时 | 命中的规则版本 |
|
||
| dispatchedBy/dispatchedAt | string/datetime | 系统 | 派工人和时间 |
|
||
|
||
### 7.7 首联与初查
|
||
|
||
| 对象 | 字段 | 建议类型 | 必填 | 说明 |
|
||
| --- | --- | --- | :---: | --- |
|
||
| 首联分派 | assigneeDeptId | string | 是 | 客服主管所在部门 |
|
||
| 首联分派 | assigneeUserId/postId | string | 是 | 本部门班组人员或岗位 |
|
||
| 首联 | firstContactAt | datetime | 是 | 首联时间 |
|
||
| 首联 | firstContactOrderNo | string(64) | 是 | 首联工单号 |
|
||
| 首联 | firstContactContent | text | 是 | 首联内容 |
|
||
| 初查 | taskId | string | 是 | 一任务一初查，保证并行结果可追踪 |
|
||
| 初查 | preliminaryContent | text | 是 | 原型中的“初查内容” |
|
||
| 通用 | submittedBy/submittedAt | string/datetime | 系统 | 提交审计字段 |
|
||
|
||
### 7.8 全面调查
|
||
|
||
| 字段 | 建议类型 | 建议必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| investigationId/version | string/integer | 系统 | 每次提交生成不可变版本 |
|
||
| acceptedContent12398 | text | 否 | 原型业务类型方案中展示“导入的12398投诉内容” |
|
||
| externalExposureRisk | boolean | 是 | 是否存在国家级媒体、党政机关、监管机构等外部渠道风险 |
|
||
| internalAppealIssued | boolean | 是 | 是否派发内部诉求工单 |
|
||
| customerAppealSummary | text | 是 | 客户诉求概况 |
|
||
| escalationReason | text | 是 | 客户升级主要原因 |
|
||
| investigationProcess | text | 是 | 本期诉求调查过程 |
|
||
| localResponsibility | boolean | 条件 | 是否本单位事项 |
|
||
| handlingSituation | text | 条件 | 办理情况 |
|
||
| accountable | boolean | 条件 | 是否有责 |
|
||
| hasHandlingBasis | boolean | 条件 | 是否有处理依据 |
|
||
| handlingMethod | text | 条件 | 处理方式 |
|
||
| handlingResult | text | 条件 | 处理结果 |
|
||
| investigationSummary | text | 待确认 | 原型出现独立“调查结果”，与上述字段可能重复 |
|
||
| draftFlag | boolean | 系统 | 是否草稿；原型未显示“暂存”按钮，建议补充 |
|
||
|
||
“是否本单位事项”之后的字段在 1-21 完整调查页出现、在 1-13 业务类型方案中未出现，可能是按事件类型或责任判定动态展示，需确认显示条件及条件必填规则。
|
||
|
||
### 7.9 审核、回访、报告与成果物
|
||
|
||
| 对象 | 字段 | 建议类型 | 必填/条件 |
|
||
| --- | --- | --- | --- |
|
||
| 审核 | reviewLevel | enum | 是：主管审核/业务审核 |
|
||
| 审核 | reviewResult | enum | 是：同意/不同意 |
|
||
| 审核 | rejectReason | text | 不同意时必填 |
|
||
| 审核 | reviewedBy/reviewedAt | string/datetime | 系统生成 |
|
||
| 回访分派 | callbackDeptId | string | 是 |
|
||
| 回访分派 | assigneeUserId/postId | string | 客服主管二次分派时必填 |
|
||
| 回访 | respondentName | string(64) | 原型显示“回复人” |
|
||
| 回访 | repliedAt | datetime | 是 |
|
||
| 回访 | replyPhone | string(32) | 是，敏感字段 |
|
||
| 回访 | replySituation | text | 是 |
|
||
| 回访 | callbackResult | enum | 是；最新原型统一为 `AGREE` 同意 / `DISAGREE_OR_CUSTOMER_REQUEST` 不同意或客户主动要求 |
|
||
| 附件 | responseLetterFileIds | array<string> | 不同意或客户主动要求时至少 1 个答复书 |
|
||
| 附件 | deliveryProofFileIds | array<string> | 不同意或客户主动要求时至少 1 个送达凭证 |
|
||
| 报告 | reportId/version | string/integer | 系统 |
|
||
| 报告 | sourceInvestigationVersion | string/integer | 是；锁定生成报告所依据的调查版本 |
|
||
| 报告 | sourceCallbackVersion | string/integer | 主责必填；协查为空 |
|
||
| 报告 | outputFileId | string | 确认生成后返回的可控下载文件 |
|
||
| 报告 | outputStatus | enum | 待生成、生成中、可下载、生成失败、已确认 |
|
||
| 报告 | generationMode | enum | 模板生成/智能辅助；是否开放在线编辑待确认 |
|
||
| 成果物 | deliverableType/fileId | enum/string | 待确认具体成果物类型 |
|
||
| 办结 | closedBy/closedAt/closeReason | string/datetime/text | 系统/条件 |
|
||
|
||
20260812 原型未提供独立富文本报告编辑器，而是展示调查信息、主责工单的回访信息及条件附件，并通过“确认下载”输出报告。因此 `reportContent` 不应在当前阶段被直接定为前端必填字段；后端可内部保存结构化快照或模板渲染内容，但其格式属于技术方案而非原型已确认需求。
|
||
|
||
### 7.10 规则与时限
|
||
|
||
| 字段 | 建议类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| configId/configVersion | string/integer | 配置标识和版本 |
|
||
| totalLimitMinutes | integer | 整体时限，原型示例 188 分钟不能视为正式值 |
|
||
| stageCode | enum | 办理派工、首联、事件调查、调查审核、回访、调查报告、编写提交等 |
|
||
| stageLimitMinutes | integer | 环节时限，必须为正整数 |
|
||
| smartDispatchRule | json/rule DSL | 智能派工条件和结果，原型未提供字段 |
|
||
| effectiveFrom/effectiveTo | datetime | 生效区间 |
|
||
| status | enum | 草稿、启用、停用 |
|
||
| changedBy/changedAt/changeReason | string/datetime/text | 配置审计 |
|
||
|
||
## 8. 接口梳理
|
||
|
||
### 8.1 接口约定
|
||
|
||
现有后端文档采用 Bearer Token、`AjaxResult` 和 `TableDataInfo`。为保持兼容，本报告沿用这些返回结构；新业务接口路径是建议契约，最终应与后端统一前缀和命名规范后进入 OpenAPI。
|
||
|
||
通用约定：
|
||
|
||
- 除验证码和登录外，接口请求头携带 `Authorization: Bearer <token>`。
|
||
- 分页统一使用 `pageNum`、`pageSize`；响应使用 `total`、`rows`、`code`、`msg`。
|
||
- 写接口携带 `requestId` 或 `Idempotency-Key`，涉及状态变更时携带 `version`。
|
||
- 业务校验失败返回稳定业务错误码，不依赖提示语解析。
|
||
- 列表只返回摘要；详情接口按权限返回敏感字段和附件权限。
|
||
|
||
### 8.2 接口目录
|
||
|
||
接口目录只用于定位，不替代字段契约。每个接口的请求字段定义、响应字段定义和 JSON 示例见 8.5～8.11 节。
|
||
|
||
#### 8.2.1 已有认证与用户接口
|
||
|
||
| 方法 | 路径 | 用途 | 状态 |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/captchaImage` | 获取验证码和 uuid | 已有文档确认 |
|
||
| POST | `/login` | 账号、密码、验证码登录 | 已有文档确认 |
|
||
| GET | `/system/user/profile` | 当前用户信息 | 已有文档确认 |
|
||
| GET | `/system/user/list` | 用户候选查询 | 已有文档确认，业务派工应增加数据范围过滤 |
|
||
| GET | `/system/user/deptTree` | 部门树 | 已有文档确认 |
|
||
| GET | `/system/user/{userId}` | 用户详情 | 已有文档确认 |
|
||
| PUT | `/system/user/profile/updatePwd` | 修改密码 | 已有文档确认 |
|
||
|
||
#### 8.2.2 导入接口
|
||
|
||
| 编号 | 方法 | 建议路径 | 用途 | 备注 |
|
||
| --- | --- | --- | --- | --- |
|
||
| IMP-01 | GET | `/risk/import-batches/template` | 下载导入模板 | 返回文件流及模板版本 |
|
||
| IMP-02 | POST | `/risk/import-batches/preview` | 上传并解析 Excel/CSV | multipart：file、batchNo；返回 previewToken、统计、行级预览 |
|
||
| IMP-03 | GET | `/risk/import-batches/{previewToken}/rows` | 分页查看预览行 | pageNum/pageSize/rowStatus |
|
||
| IMP-04 | POST | `/risk/import-batches/confirm` | 确认导入 | previewToken、batchNo、requestId；返回 batchId 和成功/失败数量 |
|
||
| IMP-05 | GET | `/risk/import-batches` | 导入批次列表 | 时间、批次号、人员、状态、分页 |
|
||
| IMP-06 | GET | `/risk/import-batches/{batchId}` | 批次详情 | 批次统计和文件信息 |
|
||
| IMP-07 | GET | `/risk/import-batches/{batchId}/rows` | 导入结果行明细 | 行状态、错误码、关联工单 |
|
||
|
||
#### 8.2.3 工单查询与详情接口
|
||
|
||
| 编号 | 方法 | 建议路径 | 用途 | 备注 |
|
||
| --- | --- | --- | --- | --- |
|
||
| WO-01 | GET | `/risk/work-orders` | 权限范围内工单查询 | 原型全部查询条件、分页、排序 |
|
||
| WO-02 | GET | `/risk/work-orders/{workOrderId}` | 工单基础详情 | 基础信息、当前环节、权限动作 |
|
||
| WO-03 | GET | `/risk/work-orders/{workOrderId}/service-records` | 95598 处理信息 | 列表、录音授权、转译文本 |
|
||
| WO-04 | GET | `/risk/work-orders/{workOrderId}/process` | 流程视图 | 当前节点、并行任务、历史节点、时限 |
|
||
| WO-05 | GET | `/risk/work-orders/{workOrderId}/timeline` | 操作轨迹 | 派工、提交、审核、驳回、附件、办结事件 |
|
||
| WO-06 | GET | `/risk/work-orders/{workOrderId}/allowed-actions` | 当前用户可执行动作 | 动作编码及所需版本；也可并入详情响应 |
|
||
|
||
#### 8.2.4 待办与派工接口
|
||
|
||
| 编号 | 方法 | 建议路径 | 用途 | 备注 |
|
||
| --- | --- | --- | --- | --- |
|
||
| TASK-01 | GET | `/risk/tasks` | 当前用户待办列表 | stage/status/工单条件/分页 |
|
||
| TASK-02 | GET | `/risk/tasks/summary` | 待办统计卡片 | 各环节数量，与列表同口径 |
|
||
| TASK-03 | GET | `/risk/tasks/{taskId}` | 待办上下文 | 工单摘要、表单数据、任务版本、允许动作 |
|
||
| DSP-01 | GET | `/risk/work-orders/{id}/dispatch-candidates` | 派工候选 | 初查部门、首联部门、监督员、督办部门 |
|
||
| DSP-02 | POST | `/risk/work-orders/{id}/smart-dispatch-suggestion` | 获取智能派工建议 | 工单版本；返回建议和规则解释，不直接落单 |
|
||
| DSP-03 | POST | `/risk/work-orders/{id}/dispatch` | 确认人工/智能派工 | 主责/协查、部门、监督员、督办、version、requestId |
|
||
| DSP-04 | POST | `/risk/tasks/{taskId}/assign` | 客服主管分派班组/人员 | assigneeUserId/postId、version |
|
||
| DSP-05 | POST | `/risk/work-orders/{id}/callback-department` | 审核环节确定主责工单的回访承接部门 | callbackDeptId、reviewTaskId、version；具体由一级还是二级审核生效待确认 |
|
||
|
||
#### 8.2.5 办理与审核接口
|
||
|
||
| 编号 | 方法 | 建议路径 | 用途 | 备注 |
|
||
| --- | --- | --- | --- | --- |
|
||
| ACT-01 | PUT | `/risk/tasks/{taskId}/draft` | 保存草稿 | formType、formData、version；技术建议 |
|
||
| ACT-02 | POST | `/risk/tasks/{taskId}/first-contact/submit` | 提交首联 | 时间、工单号、内容、version |
|
||
| ACT-03 | POST | `/risk/tasks/{taskId}/preliminary-investigation/submit` | 提交初查 | preliminaryContent、version |
|
||
| ACT-04 | GET | `/risk/tasks/{taskId}/investigation-context` | 获取全面调查上下文 | 派工后即可调用；返回已形成的首联/初查、历史调查版本和 `submitReady`/未完成前置任务 |
|
||
| ACT-05 | POST | `/risk/tasks/{taskId}/investigation/submit` | 提交全面调查 | 第 7.8 节字段、version；主责校验首联及全部初查，协查校验全部初查 |
|
||
| ACT-06 | POST | `/risk/tasks/{taskId}/supervisor-review` | 主管审核 | result、rejectReason、investigationVersion、version |
|
||
| ACT-07 | POST | `/risk/tasks/{taskId}/business-review` | 业务审核 | result、rejectReason、investigationVersion、version |
|
||
| ACT-08 | POST | `/risk/tasks/{taskId}/callback/submit` | 提交班组回访 | 原始回访字段，具体字段待确认 |
|
||
| ACT-09 | POST | `/risk/tasks/{taskId}/callback-result/submit` | 提交回访结果 | 回复信息、结果、附件 fileIds、version |
|
||
| ACT-10 | GET | `/risk/tasks/{taskId}/report-context` | 获取报告确认上下文 | 返回责任类型、锁定的调查版本、主责回访版本、附件及当前输出状态 |
|
||
| ACT-11 | POST | `/risk/tasks/{taskId}/report/confirm` | 确认生成报告 | 模板版本、调查/回访数据版本、version、requestId；可同步返回 reportId，或异步返回 jobId |
|
||
| ACT-12 | GET | `/risk/reports/{reportId}/download` | 受权下载已生成报告 | 返回受控文件流或短期下载地址，不改变流程状态 |
|
||
| ACT-13 | POST | `/risk/tasks/{taskId}/deliverables/submit` | 提交成果物并申请办结 | deliverables、version |
|
||
| ACT-14 | POST | `/risk/work-orders/{id}/close` | 确认办结 | version、requestId；仅在所有前置条件满足时允许 |
|
||
|
||
#### 8.2.6 文件、字典、配置和统计接口
|
||
|
||
| 编号 | 方法 | 建议路径 | 用途 |
|
||
| --- | --- | --- | --- |
|
||
| FILE-01 | POST | `/risk/files` | 上传录音、答复书、送达凭证或成果物，返回 fileId |
|
||
| FILE-02 | GET | `/risk/files/{fileId}` | 受权下载/播放，建议返回短期签名地址或受控流 |
|
||
| FILE-03 | DELETE | `/risk/files/{fileId}` | 删除尚未绑定且由当前用户上传的临时文件 |
|
||
| DICT-01 | GET | `/risk/dictionaries/{type}` | 信息来源、省份、事件类型、事项分类、问题分类等 |
|
||
| CFG-01 | GET | `/risk/config/sla` | 获取当前时限配置和版本 |
|
||
| CFG-02 | PUT | `/risk/config/sla` | 保存并发布整体/环节时限 |
|
||
| CFG-03 | GET | `/risk/config/dispatch-rules` | 获取智能派工规则 |
|
||
| CFG-04 | PUT | `/risk/config/dispatch-rules` | 保存并发布规则版本 |
|
||
| ANA-01 | GET | `/risk/analytics/overview` | 统计概览；指标口径待定义 |
|
||
| ANA-02 | GET | `/risk/analytics/closed-orders` | 办结工单统计与明细 |
|
||
| JOB-01 | GET | `/risk/jobs/{jobId}` | 查询导入、报告生成等异步任务进度 |
|
||
|
||
### 8.3 页面—接口映射
|
||
|
||
| 页面 | 读接口 | 写接口 |
|
||
| --- | --- | --- |
|
||
| 登录 | `/captchaImage` | `/login` |
|
||
| 工单导入 | IMP-01、IMP-05 | IMP-02、IMP-04 |
|
||
| 导入预览/明细 | IMP-03、IMP-06、IMP-07 | IMP-04 |
|
||
| 工单查询 | WO-01、DICT-01 | 无 |
|
||
| 工单详情 | WO-02～WO-06 | 按允许动作进入对应接口 |
|
||
| 主管处理列表 | TASK-01、TASK-02 | 无 |
|
||
| 派工 | WO-02、WO-03、DSP-01 | DSP-02、DSP-03 |
|
||
| 首联/回访分派 | TASK-03、候选用户/岗位 | DSP-04、DSP-05 |
|
||
| 首联/初查 | TASK-03、WO-03 | ACT-01～ACT-03 |
|
||
| 全面调查 | ACT-04、WO-02、WO-03 | ACT-01、ACT-05 |
|
||
| 两级审核 | TASK-03、历史调查版本 | ACT-06、ACT-07 |
|
||
| 回访结果 | TASK-03、附件读取 | FILE-01、ACT-09 |
|
||
| 报告/成果物 | ACT-10、报告输出状态、流程上下文 | ACT-11～ACT-14、FILE-01 |
|
||
| 时限/规则配置 | CFG-01、CFG-03 | CFG-02、CFG-04 |
|
||
| 统计分析 | ANA-01、ANA-02 | 无 |
|
||
|
||
### 8.4 联调公共契约
|
||
|
||
本节给出前后端联调基线。除 8.2 节已有接口外，以下均为建议契约；进入开发前应固化为 OpenAPI 3.1。示例中的 ID、日期、人员和数量均为演示值。
|
||
|
||
8.5～8.11 节统一按以下顺序描述接口：
|
||
|
||
1. **请求字段定义**：逐项说明字段位置、名称、类型、是否必填和业务含义；无请求体也必须明确写出。
|
||
2. **响应字段定义**：逐项说明业务数据字段路径、类型和业务含义；公共包装字段引用 8.4.2～8.4.4。
|
||
3. **请求示例**：GET/DELETE 接口没有请求体时给出完整 URL；JSON 或 multipart 接口给出请求体。
|
||
4. **响应示例**：JSON 接口给出完整响应；文件流接口说明状态码、响应头和响应体类型。
|
||
|
||
字段路径中的 `[]` 表示数组元素，例如 `data.rows[].workOrderId`。标记为“条件必填”的字段必须在定义中写明触发条件。未在字段表中定义的业务字段，前后端不得仅凭示例自行增加。
|
||
|
||
#### 8.4.1 请求头
|
||
|
||
| 请求头 | 必填 | 适用范围 | 说明 |
|
||
| --- | :---: | --- | --- |
|
||
| `Authorization: Bearer <token>` | 是 | 除验证码、登录外 | 当前用户身份 |
|
||
| `Content-Type: application/json` | 是 | JSON 写接口 | 文件上传除外 |
|
||
| `Idempotency-Key` | 条件 | 导入确认、派工、提交、审核、报告确认、办结 | 客户端生成 UUID；同一业务动作重试必须复用 |
|
||
| `X-Request-Id` | 建议 | 全部接口 | 链路追踪；未传时由服务端生成 |
|
||
| `Accept-Language: zh-CN` | 否 | 全部接口 | 提示语语言，不影响业务错误码 |
|
||
|
||
#### 8.4.2 单对象成功响应
|
||
|
||
| 响应字段 | 类型 | 必有 | 定义 |
|
||
| --- | --- | :---: | --- |
|
||
| `code` | integer/string | 是 | 成功时为 `200`；失败时为稳定业务错误码 |
|
||
| `msg` | string | 是 | 面向用户的结果说明，不作为前端业务判断依据 |
|
||
| `data` | object/array/null | 是 | 业务响应数据；无业务数据时为 `null` 或空对象，项目内须统一 |
|
||
| `requestId` | string | 是 | 服务端链路追踪标识，应同时写入服务端日志 |
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {},
|
||
"requestId": "req-20260813-000001"
|
||
}
|
||
```
|
||
|
||
#### 8.4.3 分页成功响应
|
||
|
||
| 响应字段 | 类型 | 必有 | 定义 |
|
||
| --- | --- | :---: | --- |
|
||
| `total` | integer | 是 | 符合查询条件的数据总数，不是当前页条数 |
|
||
| `rows` | object[] | 是 | 当前页数据；无数据时返回空数组 |
|
||
| `code` | integer | 是 | 成功结果码，固定为 `200` |
|
||
| `msg` | string | 是 | 查询结果说明 |
|
||
| `requestId` | string | 是 | 服务端链路追踪标识 |
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"rows": [],
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"requestId": "req-20260813-000002"
|
||
}
|
||
```
|
||
|
||
分页请求统一使用 `pageNum`、`pageSize`；`pageNum` 从 1 开始，`pageSize` 建议限制为 10～100。排序使用 `orderByColumn` 和 `isAsc`，服务端必须使用字段白名单。
|
||
|
||
#### 8.4.4 业务错误响应
|
||
|
||
新增 `/risk/**` 接口建议由 HTTP 状态表达协议结果，响应体 `code` 使用第 9.7 节稳定业务错误码，不用 HTTP 200 包装业务失败；8.2 节列出的既有接口继续保持现有返回约定，避免破坏兼容性。
|
||
|
||
```json
|
||
{
|
||
"code": "RISK-4220",
|
||
"msg": "首联及全部初查完成后才能提交全面调查",
|
||
"data": {
|
||
"currentStage": "INVESTIGATION",
|
||
"responsibilityType": "PRIMARY",
|
||
"incompletePrerequisites": [
|
||
{ "type": "FIRST_CONTACT", "taskId": "TASK-FC-001", "status": "IN_PROGRESS" },
|
||
{ "type": "PRELIMINARY_INVESTIGATION", "taskId": "TASK-PI-003", "status": "PENDING" }
|
||
],
|
||
"fieldErrors": []
|
||
},
|
||
"requestId": "req-20260813-000003"
|
||
}
|
||
```
|
||
|
||
建议 HTTP 映射：认证失效 `401`，越权 `403`，不存在 `404`，版本/状态冲突 `409`，业务前置条件或字段校验失败 `422`，限流 `429`，服务端异常 `500`。
|
||
|
||
#### 8.4.5 状态变更通用响应
|
||
|
||
所有任务写接口至少返回最新任务版本、工单版本、当前环节和新建后续任务，前端必须用响应覆盖本地版本，不能自行推算状态。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "提交成功",
|
||
"data": {
|
||
"workOrderId": "WO-20260806-001",
|
||
"taskId": "TASK-INV-001",
|
||
"taskStatus": "COMPLETED",
|
||
"currentStage": "SUPERVISOR_REVIEW",
|
||
"workOrderVersion": 8,
|
||
"taskVersion": 3,
|
||
"nextTasks": [
|
||
{
|
||
"taskId": "TASK-SR-001",
|
||
"stage": "SUPERVISOR_REVIEW",
|
||
"status": "PENDING",
|
||
"assigneeRole": "SERVICE_SUPERVISOR"
|
||
}
|
||
]
|
||
},
|
||
"requestId": "req-20260813-000004"
|
||
}
|
||
```
|
||
|
||
### 8.5 认证与用户接口请求与响应字段定义
|
||
|
||
#### 8.5.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| `GET /captchaImage` | — | — | — | — | 无查询参数、无请求体 |
|
||
| `POST /login` | body | `username` | string | 是 | 登录账号 |
|
||
| `POST /login` | body | `password` | string | 是 | 登录密码；仅通过 HTTPS 传输 |
|
||
| `POST /login` | body | `code` | string | 条件 | 验证码开启时必填 |
|
||
| `POST /login` | body | `uuid` | string | 条件 | 验证码开启时必填，与验证码图片绑定 |
|
||
| `GET /system/user/profile` | — | — | — | — | 无查询参数、无请求体；用户由 Token 确定 |
|
||
| `GET /system/user/list` | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| `GET /system/user/list` | query | `pageSize` | integer | 是 | 每页数量，建议 10～100 |
|
||
| `GET /system/user/list` | query | `userName` | string | 否 | 用户名模糊查询 |
|
||
| `GET /system/user/list` | query | `phonenumber` | string | 否 | 手机号查询 |
|
||
| `GET /system/user/list` | query | `status` | string | 否 | 用户状态 |
|
||
| `GET /system/user/list` | query | `deptId` | string | 否 | 部门标识；服务端仍需执行数据范围过滤 |
|
||
| `GET /system/user/deptTree` | — | — | — | — | 无查询参数、无请求体 |
|
||
| `GET /system/user/{userId}` | path | `userId` | string | 是 | 用户标识 |
|
||
| `PUT /system/user/profile/updatePwd` | query | `oldPassword` | string | 是 | 原密码 |
|
||
| `PUT /system/user/profile/updatePwd` | query | `newPassword` | string | 是 | 新密码，须满足密码策略 |
|
||
|
||
#### 8.5.2 响应字段定义
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| `GET /captchaImage` | `code` | integer | 结果码 |
|
||
| `GET /captchaImage` | `data.uuid` | string | 验证码会话标识 |
|
||
| `GET /captchaImage` | `data.img` | string | Base64 编码的验证码图片 |
|
||
| `POST /login` | `code` | integer | 结果码 |
|
||
| `POST /login` | `msg` | string | 结果说明 |
|
||
| `POST /login` | `data` | string | Bearer Token；前端不得写入日志 |
|
||
| `GET /system/user/profile` | `data.user` | object | 当前用户基本信息 |
|
||
| `GET /system/user/profile` | `data.roles[]` | string[] | 当前用户角色编码 |
|
||
| `GET /system/user/profile` | `data.permissions[]` | string[] | 当前用户权限编码 |
|
||
| `GET /system/user/list` | `total` | integer | 符合条件的用户总数 |
|
||
| `GET /system/user/list` | `rows[]` | object[] | 用户摘要列表 |
|
||
| `GET /system/user/list` | `rows[].userId` | string | 用户标识 |
|
||
| `GET /system/user/list` | `rows[].userName` | string | 用户名 |
|
||
| `GET /system/user/list` | `rows[].nickName` | string | 用户显示名称 |
|
||
| `GET /system/user/list` | `rows[].dept` | object | 所属部门摘要 |
|
||
| `GET /system/user/list` | `rows[].status` | string | 用户状态 |
|
||
| `GET /system/user/deptTree` | `data[]` | object[] | 部门树根节点 |
|
||
| `GET /system/user/deptTree` | `data[].id` | string | 部门标识 |
|
||
| `GET /system/user/deptTree` | `data[].label` | string | 部门名称 |
|
||
| `GET /system/user/deptTree` | `data[].children[]` | object[] | 子部门，递归结构 |
|
||
| `GET /system/user/{userId}` | `data.user` | object | 用户详情 |
|
||
| `GET /system/user/{userId}` | `data.roleIds[]` | string[] | 已关联角色标识 |
|
||
| `GET /system/user/{userId}` | `data.postIds[]` | string[] | 已关联岗位标识 |
|
||
| `PUT /system/user/profile/updatePwd` | `code` | integer | 结果码，成功为 200 |
|
||
| `PUT /system/user/profile/updatePwd` | `msg` | string | 修改结果说明 |
|
||
|
||
#### 8.5.3 请求与响应示例
|
||
|
||
##### `GET /captchaImage`
|
||
|
||
无查询参数、无请求体。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"uuid": "4c25fa10-6f61-4ea3-aea5-977c26759468",
|
||
"img": "data:image/png;base64,iVBORw0KGgoAAA..."
|
||
}
|
||
}
|
||
```
|
||
|
||
##### `POST /login`
|
||
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "******",
|
||
"code": "TB5K",
|
||
"uuid": "4c25fa10-6f61-4ea3-aea5-977c26759468"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "登录成功",
|
||
"data": "eyJhbGciOiJIUzI1NiJ9...",
|
||
"requestId": "req-20260813-000010"
|
||
}
|
||
```
|
||
|
||
##### 用户和部门查询
|
||
|
||
- `GET /system/user/list?pageNum=1&pageSize=20&deptId=101&status=0`：无 body；响应 `rows` 为用户数组。
|
||
- `GET /system/user/deptTree?status=0`：无 body；响应 `data` 为部门树。
|
||
- `GET /system/user/{userId}`、`GET /system/user/profile`：无 body；响应 `data` 为用户对象。
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"rows": [
|
||
{
|
||
"userId": 1001,
|
||
"deptId": 101,
|
||
"userName": "zhangsan",
|
||
"nickName": "张某",
|
||
"phonenumber": "131****7777",
|
||
"status": "0",
|
||
"roleIds": [201],
|
||
"postIds": [301]
|
||
}
|
||
],
|
||
"code": 200,
|
||
"msg": "查询成功"
|
||
}
|
||
```
|
||
|
||
派工候选不得直接使用无业务范围限制的全量用户列表；后端应基于部门、岗位、角色和启用状态过滤。
|
||
|
||
### 8.6 导入接口请求与响应字段定义
|
||
|
||
#### 8.6.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| IMP-01 | query | `templateVersion` | string | 否 | 指定模板版本；不传则下载当前有效版本 |
|
||
| IMP-02 | multipart | `file` | binary | 是 | 待解析的 Excel/CSV 文件，须通过扩展名、MIME、大小和安全扫描校验 |
|
||
| IMP-02 | multipart | `batchNo` | string | 是 | 用户填写的业务批次号，同一有效批次内唯一 |
|
||
| IMP-02 | multipart | `templateVersion` | string | 是 | 文件使用的模板版本 |
|
||
| IMP-03 | path | `previewToken` | string | 是 | 预览会话标识，过期后不可使用 |
|
||
| IMP-03 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| IMP-03 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| IMP-03 | query | `rowStatus` | enum | 否 | 行状态：`VALID`、`DUPLICATE`、`INVALID` |
|
||
| IMP-04 | body | `previewToken` | string | 是 | IMP-02 返回的预览会话标识 |
|
||
| IMP-04 | body | `batchNo` | string | 是 | 必须与预览阶段批次号一致 |
|
||
| IMP-04 | body | `fileSha256` | string | 是 | 文件摘要，防止预览后文件被替换 |
|
||
| IMP-04 | body | `duplicatePolicy` | enum | 是 | 重复处理策略；当前建议仅支持 `REJECT` |
|
||
| IMP-04 | body | `requestId` | string | 是 | 幂等请求标识，与 `Idempotency-Key` 一致 |
|
||
| IMP-05 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| IMP-05 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| IMP-05 | query | `batchNo` | string | 否 | 批次号模糊或精确查询，开发前统一口径 |
|
||
| IMP-05 | query | `status` | enum | 否 | 批次状态 |
|
||
| IMP-05 | query | `importedFrom` | date | 否 | 导入开始日期，含边界 |
|
||
| IMP-05 | query | `importedTo` | date | 否 | 导入结束日期，含边界 |
|
||
| IMP-06 | path | `batchId` | string | 是 | 导入批次标识 |
|
||
| IMP-07 | path | `batchId` | string | 是 | 导入批次标识 |
|
||
| IMP-07 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| IMP-07 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| IMP-07 | query | `rowStatus` | enum | 否 | 行处理状态 |
|
||
|
||
#### 8.6.2 响应字段定义
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| IMP-01 | HTTP body | binary | 模板文件流 |
|
||
| IMP-01 | `Content-Type` | string | Excel 模板 MIME 类型 |
|
||
| IMP-01 | `Content-Disposition` | string | 下载文件名 |
|
||
| IMP-01 | `X-Template-Version` | string | 实际下载的模板版本 |
|
||
| IMP-02 | `data.previewToken` | string | 预览会话标识 |
|
||
| IMP-02 | `data.expiresAt` | datetime | 预览会话过期时间 |
|
||
| IMP-02 | `data.fileName` | string | 原始文件名 |
|
||
| IMP-02 | `data.fileSha256` | string | 文件 SHA-256 摘要 |
|
||
| IMP-02 | `data.templateVersion` | string | 解析所用模板版本 |
|
||
| IMP-02 | `data.batchNo` | string | 业务批次号 |
|
||
| IMP-02 | `data.totalCount` | integer | 数据总行数，不含标题行 |
|
||
| IMP-02 | `data.validCount` | integer | 校验通过且可导入行数 |
|
||
| IMP-02 | `data.duplicateCount` | integer | 重复行数 |
|
||
| IMP-02 | `data.invalidCount` | integer | 校验失败行数 |
|
||
| IMP-02 | `data.canConfirm` | boolean | 当前预览是否允许确认导入 |
|
||
| IMP-02 | `data.sampleRows[]` | object[] | 少量预览行；完整数据通过 IMP-03 查询 |
|
||
| IMP-02 | `data.sampleRows[].rowNo` | integer | 文件中的原始行号 |
|
||
| IMP-02 | `data.sampleRows[].rowStatus` | enum | 行校验状态 |
|
||
| IMP-02 | `data.sampleRows[].workOrderNo12398` | string | 12398 工单号 |
|
||
| IMP-02 | `data.sampleRows[].customerName` | string | 客户名称 |
|
||
| IMP-02 | `data.sampleRows[].errors[]` | object[] | 行级错误集合 |
|
||
| IMP-03/IMP-07 | `total` | integer | 符合行状态条件的总数 |
|
||
| IMP-03/IMP-07 | `rows[]` | object[] | 当前页行明细 |
|
||
| IMP-03/IMP-07 | `rows[].rowNo` | integer | 原始行号 |
|
||
| IMP-03/IMP-07 | `rows[].rowStatus` | enum | 行状态 |
|
||
| IMP-03/IMP-07 | `rows[].rawData` | object | 原始单元格键值，不作为正式业务数据 |
|
||
| IMP-03/IMP-07 | `rows[].normalizedData` | object/null | 类型和格式归一化后的业务数据 |
|
||
| IMP-03/IMP-07 | `rows[].errorCode` | string/null | 行级稳定错误码 |
|
||
| IMP-03/IMP-07 | `rows[].errorMessage` | string/null | 行级错误说明 |
|
||
| IMP-03/IMP-07 | `rows[].workOrderId` | string/null | 导入成功后关联的工单标识；预览阶段为空 |
|
||
| IMP-04 | `data.batchId` | string | 服务端生成的导入批次标识 |
|
||
| IMP-04 | `data.batchNo` | string | 业务批次号 |
|
||
| IMP-04 | `data.status` | enum | 批次处理结果：成功、部分成功或失败 |
|
||
| IMP-04 | `data.totalCount` | integer | 确认处理总数 |
|
||
| IMP-04 | `data.successCount` | integer | 成功创建/关联工单数 |
|
||
| IMP-04 | `data.failureCount` | integer | 失败数 |
|
||
| IMP-04 | `data.createdWorkOrderIds[]` | string[] | 本次新建工单标识 |
|
||
| IMP-05 | `total` | integer | 批次总数 |
|
||
| IMP-05 | `rows[]` | object[] | 批次摘要列表，字段结构见下方批次对象 |
|
||
| IMP-06 | `data` | object | 批次详情，字段结构见下方批次对象 |
|
||
| IMP-05/IMP-06 | `batchId` | string | 导入批次标识 |
|
||
| IMP-05/IMP-06 | `batchNo` | string | 业务批次号 |
|
||
| IMP-05/IMP-06 | `fileId` | string | 原始导入文件标识 |
|
||
| IMP-05/IMP-06 | `fileName` | string | 原始文件名 |
|
||
| IMP-05/IMP-06 | `templateVersion` | string | 模板版本 |
|
||
| IMP-05/IMP-06 | `status` | enum | 批次状态 |
|
||
| IMP-05/IMP-06 | `totalCount` | integer | 总行数 |
|
||
| IMP-05/IMP-06 | `successCount` | integer | 成功行数 |
|
||
| IMP-05/IMP-06 | `failureCount` | integer | 失败行数 |
|
||
| IMP-05/IMP-06 | `importedBy` | object | 导入人摘要，包含 `userId`、`name` |
|
||
| IMP-05/IMP-06 | `importedAt` | datetime | 导入时间 |
|
||
|
||
#### 8.6.3 请求与响应示例
|
||
|
||
##### IMP-01 下载模板
|
||
|
||
`GET /risk/import-batches/template?templateVersion=2026.08` 无 body。成功响应为文件流，并返回：
|
||
|
||
```http
|
||
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
|
||
Content-Disposition: attachment; filename="12398-work-order-template-2026.08.xlsx"
|
||
X-Template-Version: 2026.08
|
||
```
|
||
|
||
##### IMP-02 导入预览
|
||
|
||
`POST /risk/import-batches/preview` 使用 `multipart/form-data`：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| file | binary | 是 | Excel/CSV 文件 |
|
||
| batchNo | string | 是 | 客户端填写的业务批次号 |
|
||
| templateVersion | string | 是 | 使用的模板版本 |
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "文件解析完成",
|
||
"data": {
|
||
"previewToken": "pvw_6d0726d6",
|
||
"expiresAt": "2026-08-13T18:00:00+08:00",
|
||
"fileName": "12398工单.xlsx",
|
||
"fileSha256": "84a3...e02c",
|
||
"templateVersion": "2026.08",
|
||
"batchNo": "20260813-B01",
|
||
"totalCount": 10,
|
||
"validCount": 8,
|
||
"duplicateCount": 1,
|
||
"invalidCount": 1,
|
||
"canConfirm": true,
|
||
"sampleRows": [
|
||
{
|
||
"rowNo": 2,
|
||
"rowStatus": "VALID",
|
||
"workOrderNo12398": "2026-08-06-001",
|
||
"customerName": "某某有限公司",
|
||
"errors": []
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### IMP-03/IMP-07 行明细
|
||
|
||
`GET /risk/import-batches/{previewToken}/rows?pageNum=1&pageSize=20&rowStatus=INVALID` 或 `GET /risk/import-batches/{batchId}/rows` 无 body。
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"rows": [
|
||
{
|
||
"rowNo": 5,
|
||
"rowStatus": "INVALID",
|
||
"rawData": {
|
||
"workOrderNo12398": "",
|
||
"customerCalledAt": "2026/13/40"
|
||
},
|
||
"normalizedData": null,
|
||
"errorCode": "INVALID_DATE",
|
||
"errorMessage": "客户致电12398日期格式不正确",
|
||
"workOrderId": null
|
||
}
|
||
],
|
||
"code": 200,
|
||
"msg": "查询成功"
|
||
}
|
||
```
|
||
|
||
##### IMP-04 确认导入
|
||
|
||
```json
|
||
{
|
||
"previewToken": "pvw_6d0726d6",
|
||
"batchNo": "20260813-B01",
|
||
"fileSha256": "84a3...e02c",
|
||
"duplicatePolicy": "REJECT",
|
||
"requestId": "f332e303-d335-4a58-b09e-e5879122fb7b"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "导入完成",
|
||
"data": {
|
||
"batchId": "IB-20260813-001",
|
||
"batchNo": "20260813-B01",
|
||
"status": "PARTIAL_SUCCESS",
|
||
"totalCount": 10,
|
||
"successCount": 8,
|
||
"failureCount": 2,
|
||
"createdWorkOrderIds": ["WO-20260806-001", "WO-20260806-002"]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### IMP-05/IMP-06 批次列表与详情
|
||
|
||
`GET /risk/import-batches?pageNum=1&pageSize=20&batchNo=20260813-B01&status=CONFIRMED&importedFrom=2026-08-01&importedTo=2026-08-31` 无 body。
|
||
|
||
列表 `rows` 和详情 `data` 统一使用：
|
||
|
||
```json
|
||
{
|
||
"batchId": "IB-20260813-001",
|
||
"batchNo": "20260813-B01",
|
||
"fileId": "FILE-001",
|
||
"fileName": "12398工单.xlsx",
|
||
"templateVersion": "2026.08",
|
||
"status": "PARTIAL_SUCCESS",
|
||
"totalCount": 10,
|
||
"successCount": 8,
|
||
"failureCount": 2,
|
||
"importedBy": { "userId": "1001", "name": "服务监督主管" },
|
||
"importedAt": "2026-08-13T10:20:00+08:00"
|
||
}
|
||
```
|
||
|
||
### 8.7 工单与流程查询接口请求与响应字段定义
|
||
|
||
#### 8.7.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| WO-01 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| WO-01 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| WO-01 | query | `workOrderNo12398` | string | 否 | 12398 工单号 |
|
||
| WO-01 | query | `currentStage` | enum | 否 | 当前流程环节 |
|
||
| WO-01 | query | `orderStatus` | enum | 否 | 工单状态 |
|
||
| WO-01 | query | `sourceCode` | string | 否 | 信息来源编码 |
|
||
| WO-01 | query | `calledFrom`/`calledTo` | datetime | 否 | 客户致电 12398 时间范围 |
|
||
| WO-01 | query | `transferredFrom`/`transferredTo` | datetime | 否 | 工单转入时间范围 |
|
||
| WO-01 | query | `customerName` | string | 否 | 客户名称模糊查询 |
|
||
| WO-01 | query | `contactPhone` | string | 否 | 联系电话精确或后四位查询，须受敏感数据权限控制 |
|
||
| WO-01 | query | `customerAddress` | string | 否 | 客户地址模糊查询 |
|
||
| WO-01 | query | `regionCode` | string | 否 | 区域编码 |
|
||
| WO-01 | query | `provinceCode` | string | 否 | 省份编码 |
|
||
| WO-01 | query | `eventTypeCode` | string | 否 | 事件类型编码 |
|
||
| WO-01 | query | `transferCategoryCode` | string | 否 | 转办事项分类编码 |
|
||
| WO-01 | query | `problemCategoryCode` | string | 否 | 问题分类编码 |
|
||
| WO-01 | query | `responsibilityType` | enum | 否 | `PRIMARY` 主责或 `ASSIST` 协查 |
|
||
| WO-01 | query | `orderByColumn` | string | 否 | 排序字段，仅允许服务端白名单字段 |
|
||
| WO-01 | query | `isAsc` | enum | 否 | `asc` 或 `desc` |
|
||
| WO-02 | path | `workOrderId` | string | 是 | 工单标识 |
|
||
| WO-03 | path | `workOrderId` | string | 是 | 工单标识 |
|
||
| WO-03 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| WO-03 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| WO-04 | path | `workOrderId` | string | 是 | 工单标识 |
|
||
| WO-05 | path | `workOrderId` | string | 是 | 工单标识 |
|
||
| WO-05 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| WO-05 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| WO-06 | path | `workOrderId` | string | 是 | 工单标识 |
|
||
|
||
WO-01～WO-06 均无请求体，数据范围由当前用户身份和权限决定。
|
||
|
||
#### 8.7.2 响应字段定义
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| WO-01 | `total` | integer | 符合查询条件且当前用户有权查看的工单总数 |
|
||
| WO-01 | `rows[]` | object[] | 当前页工单摘要 |
|
||
| WO-01 | `rows[].workOrderId` | string | 工单标识 |
|
||
| WO-01 | `rows[].workOrderNo12398` | string | 12398 工单号 |
|
||
| WO-01 | `rows[].orderStatus` | enum | 工单状态 |
|
||
| WO-01 | `rows[].currentStage` | enum | 当前流程环节编码 |
|
||
| WO-01 | `rows[].currentStageName` | string | 当前环节显示名称 |
|
||
| WO-01 | `rows[].sourceCode`/`sourceName` | string | 信息来源编码及名称 |
|
||
| WO-01 | `rows[].customerCalledAt` | datetime | 客户致电时间 |
|
||
| WO-01 | `rows[].transferredAt` | datetime | 工单转入时间 |
|
||
| WO-01 | `rows[].customerName` | string | 客户名称，按权限脱敏 |
|
||
| WO-01 | `rows[].contactPhoneMasked` | string | 脱敏联系电话 |
|
||
| WO-01 | `rows[].customerAddressMasked` | string | 脱敏地址 |
|
||
| WO-01 | `rows[].responsibilityType` | enum/null | 派工前为空，派工后为主责或协查 |
|
||
| WO-01 | `rows[].version` | integer | 工单乐观锁版本 |
|
||
| WO-01 | `rows[].allowedActions[]` | string[] | 当前用户在该工单上的允许动作 |
|
||
| WO-02 | `data.workOrderId`/`workOrderNo12398` | string | 工单标识及 12398 工单号 |
|
||
| WO-02 | `data.orderStatus`/`currentStage` | enum | 工单状态及当前环节 |
|
||
| WO-02 | `data.responsibilityType` | enum/null | 主责/协查，派工前为空 |
|
||
| WO-02 | `data.sourceCode` | string | 信息来源编码 |
|
||
| WO-02 | `data.customerCalledAt`/`transferredAt` | datetime | 客户致电及转入时间 |
|
||
| WO-02 | `data.customer` | object | 客户信息对象 |
|
||
| WO-02 | `data.customer.name` | string | 客户名称 |
|
||
| WO-02 | `data.customer.contactPhone` | string | 联系电话，按权限脱敏 |
|
||
| WO-02 | `data.customer.address` | string | 地址，按权限脱敏 |
|
||
| WO-02 | `data.customer.regionCode`/`provinceCode` | string | 区域及省份编码 |
|
||
| WO-02 | `data.classification` | object | 事件、事项和问题分类编码集合 |
|
||
| WO-02 | `data.version` | integer | 工单版本 |
|
||
| WO-02 | `data.allowedActions[]` | string[] | 当前用户允许动作 |
|
||
| WO-03 | `total` | integer | 关联 95598 记录总数 |
|
||
| WO-03 | `rows[]` | object[] | 95598 业务记录 |
|
||
| WO-03 | `rows[].serviceRecordId` | string | 记录标识 |
|
||
| WO-03 | `rows[].serviceOrderNo95598` | string | 95598 工单号 |
|
||
| WO-03 | `rows[].acceptanceContent` | string | 受理内容 |
|
||
| WO-03 | `rows[].businessTypeCode` | string | 业务类型编码 |
|
||
| WO-03 | `rows[].acceptedAt` | datetime | 受理时间 |
|
||
| WO-03 | `rows[].powerSupplyOrg` | object | 供电单位，包含 `id`、`name` |
|
||
| WO-03 | `rows[].recording` | object/null | 录音信息，包含 `fileId`、`durationSeconds`、`playable` |
|
||
| WO-03 | `rows[].transcriptText` | string/null | 录音转译文本 |
|
||
| WO-04 | `data.processInstanceId` | string | 流程实例标识 |
|
||
| WO-04 | `data.processVersion` | integer | 流程定义/实例版本 |
|
||
| WO-04 | `data.responsibilityType` | enum | 主责或协查 |
|
||
| WO-04 | `data.currentStage` | enum | 当前环节 |
|
||
| WO-04 | `data.workOrderVersion` | integer | 工单版本 |
|
||
| WO-04 | `data.nodes[]` | object[] | 流程节点集合 |
|
||
| WO-04 | `data.nodes[].stage`/`status` | enum | 节点编码及状态 |
|
||
| WO-04 | `data.nodes[].completedAt` | datetime/null | 节点完成时间 |
|
||
| WO-04 | `data.nodes[].completedCount`/`totalCount` | integer/null | 并行节点完成数及总数 |
|
||
| WO-04 | `data.nodes[].submitReady` | boolean/null | 当前节点是否满足提交条件 |
|
||
| WO-04 | `data.deadlineAt` | datetime | 当前时限截止时间 |
|
||
| WO-04 | `data.overdue` | boolean | 是否逾期 |
|
||
| WO-05 | `total` | integer | 轨迹事件总数 |
|
||
| WO-05 | `rows[]` | object[] | 当前页轨迹事件 |
|
||
| WO-05 | `rows[].eventId`/`eventType` | string | 事件标识及类型 |
|
||
| WO-05 | `rows[].stage` | enum | 发生事件的环节 |
|
||
| WO-05 | `rows[].actor` | object | 操作人，包含 `userId`、`name`、`role` |
|
||
| WO-05 | `rows[].occurredAt` | datetime | 发生时间 |
|
||
| WO-05 | `rows[].fromStatus`/`toStatus` | enum/null | 变更前后状态 |
|
||
| WO-05 | `rows[].summary` | string | 事件摘要 |
|
||
| WO-06 | `data.workOrderId` | string | 工单标识 |
|
||
| WO-06 | `data.workOrderVersion` | integer | 当前工单版本 |
|
||
| WO-06 | `data.actions[]` | object[] | 动作集合 |
|
||
| WO-06 | `data.actions[].code` | string | 动作编码 |
|
||
| WO-06 | `data.actions[].enabled` | boolean | 是否允许执行 |
|
||
| WO-06 | `data.actions[].reasonCode` | string/null | 禁止执行时的稳定原因码 |
|
||
|
||
#### 8.7.3 请求与响应示例
|
||
|
||
##### WO-01 工单列表
|
||
|
||
```http
|
||
GET /risk/work-orders?pageNum=1&pageSize=20&workOrderNo12398=2026-08-06-001¤tStage=DISPATCH&customerName=某某&orderByColumn=transferredAt&isAsc=desc
|
||
```
|
||
|
||
无 body。响应：
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"rows": [
|
||
{
|
||
"workOrderId": "WO-20260806-001",
|
||
"workOrderNo12398": "2026-08-06-001",
|
||
"orderStatus": "PROCESSING",
|
||
"currentStage": "DISPATCH",
|
||
"currentStageName": "待分配派工",
|
||
"sourceCode": "12398_PHONE",
|
||
"sourceName": "12398 电话",
|
||
"customerCalledAt": "2026-08-06T09:15:00+08:00",
|
||
"transferredAt": "2026-08-06T11:00:00+08:00",
|
||
"customerName": "某某有限公司",
|
||
"contactPhoneMasked": "138****8888",
|
||
"customerAddressMasked": "XX市XX区XX路88号",
|
||
"responsibilityType": null,
|
||
"version": 3,
|
||
"allowedActions": ["VIEW", "DISPATCH"]
|
||
}
|
||
],
|
||
"code": 200,
|
||
"msg": "查询成功"
|
||
}
|
||
```
|
||
|
||
##### WO-02 工单详情
|
||
|
||
`GET /risk/work-orders/{workOrderId}` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"workOrderId": "WO-20260806-001",
|
||
"workOrderNo12398": "2026-08-06-001",
|
||
"orderStatus": "PROCESSING",
|
||
"currentStage": "INVESTIGATION",
|
||
"responsibilityType": "PRIMARY",
|
||
"sourceCode": "12398_PHONE",
|
||
"customerCalledAt": "2026-08-06T09:15:00+08:00",
|
||
"transferredAt": "2026-08-06T11:00:00+08:00",
|
||
"customer": {
|
||
"name": "某某有限公司",
|
||
"contactPhone": "138****8888",
|
||
"address": "XX市XX区XX路88号",
|
||
"regionCode": "120101",
|
||
"provinceCode": "120000"
|
||
},
|
||
"classification": {
|
||
"eventTypeCode": "COMPLAINT",
|
||
"transferCategoryCode": "COMPLAINT_ITEM",
|
||
"problemCategoryCode": "SAFETY_RISK"
|
||
},
|
||
"version": 7,
|
||
"allowedActions": ["VIEW", "SAVE_INVESTIGATION_DRAFT"]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### WO-03 95598 记录
|
||
|
||
`GET /risk/work-orders/{workOrderId}/service-records?pageNum=1&pageSize=20` 无 body，返回 `TableDataInfo`：
|
||
|
||
```json
|
||
{
|
||
"serviceRecordId": "SR-001",
|
||
"serviceOrderNo95598": "95598-20260806-001",
|
||
"acceptanceContent": "客户反映近期电压不稳，设备频繁重启。",
|
||
"businessTypeCode": "COMPLAINT",
|
||
"acceptedAt": "2026-08-06T08:45:00+08:00",
|
||
"powerSupplyOrg": { "id": "ORG-1200", "name": "国网天津市电力公司" },
|
||
"recording": {
|
||
"fileId": "FILE-AUDIO-001",
|
||
"durationSeconds": 384,
|
||
"playable": true
|
||
},
|
||
"transcriptText": "客户反映近期电压不稳……"
|
||
}
|
||
```
|
||
|
||
##### WO-04 流程视图
|
||
|
||
`GET /risk/work-orders/{workOrderId}/process` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"processInstanceId": "PI-001",
|
||
"processVersion": 1,
|
||
"responsibilityType": "PRIMARY",
|
||
"currentStage": "INVESTIGATION",
|
||
"workOrderVersion": 7,
|
||
"nodes": [
|
||
{ "stage": "DISPATCH", "status": "COMPLETED", "completedAt": "2026-08-06T12:00:00+08:00" },
|
||
{ "stage": "FIRST_CONTACT", "status": "COMPLETED", "completedAt": "2026-08-06T14:32:00+08:00" },
|
||
{ "stage": "PRELIMINARY_INVESTIGATION", "status": "IN_PROGRESS", "completedCount": 1, "totalCount": 3 },
|
||
{ "stage": "INVESTIGATION", "status": "IN_PROGRESS", "submitReady": false }
|
||
],
|
||
"deadlineAt": "2026-08-08T18:00:00+08:00",
|
||
"overdue": false
|
||
}
|
||
}
|
||
```
|
||
|
||
##### WO-05/WO-06 时间线与允许动作
|
||
|
||
`GET /risk/work-orders/{workOrderId}/timeline?pageNum=1&pageSize=50` 返回分页事件；`GET /risk/work-orders/{workOrderId}/allowed-actions` 返回动作集合。
|
||
|
||
```json
|
||
{
|
||
"eventId": "EVT-001",
|
||
"eventType": "DISPATCHED",
|
||
"stage": "DISPATCH",
|
||
"actor": { "userId": "1001", "name": "服务监督主管", "role": "SERVICE_SUPERVISOR" },
|
||
"occurredAt": "2026-08-06T12:00:00+08:00",
|
||
"fromStatus": "PENDING",
|
||
"toStatus": "COMPLETED",
|
||
"summary": "判定主责并完成派工"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"workOrderId": "WO-20260806-001",
|
||
"workOrderVersion": 7,
|
||
"actions": [
|
||
{ "code": "SAVE_INVESTIGATION_DRAFT", "enabled": true },
|
||
{ "code": "SUBMIT_INVESTIGATION", "enabled": false, "reasonCode": "PREREQUISITES_INCOMPLETE" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.8 待办与派工接口请求与响应字段定义
|
||
|
||
#### 8.8.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| TASK-01 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| TASK-01 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| TASK-01 | query | `stage` | enum | 否 | 任务环节 |
|
||
| TASK-01 | query | `status` | enum | 否 | 任务状态 |
|
||
| TASK-01 | query | `workOrderNo12398` | string | 否 | 12398 工单号 |
|
||
| TASK-01 | query | `customerName` | string | 否 | 客户名称 |
|
||
| TASK-02 | query | `workOrderNo12398` | string | 否 | 与任务列表相同口径的工单号条件 |
|
||
| TASK-02 | query | `customerName` | string | 否 | 与任务列表相同口径的客户条件 |
|
||
| TASK-02 | query | `status` | enum | 否 | 需要统计的任务状态 |
|
||
| TASK-03 | path | `taskId` | string | 是 | 任务标识 |
|
||
| DSP-01 | path | `id` | string | 是 | 工单标识 |
|
||
| DSP-01 | query | `responsibilityType` | enum | 是 | 用于筛选候选项；`PRIMARY` 或 `ASSIST` |
|
||
| DSP-02 | path | `id` | string | 是 | 工单标识 |
|
||
| DSP-02 | body | `workOrderVersion` | integer | 是 | 工单当前版本 |
|
||
| DSP-02 | body | `responsibilityType` | enum | 是 | 拟判定责任类型 |
|
||
| DSP-03 | path | `id` | string | 是 | 工单标识 |
|
||
| DSP-03 | body | `responsibilityType` | enum | 是 | 服务监督主管判定的 `PRIMARY` 或 `ASSIST` |
|
||
| DSP-03 | body | `preliminaryDeptIds[]` | string[] | 是 | 初查部门，至少 1 个且不可重复 |
|
||
| DSP-03 | body | `firstContactDeptId` | string/null | 条件 | 主责必填；协查必须为空 |
|
||
| DSP-03 | body | `serviceOfficerUserId` | string | 是 | 承办服务监督员用户标识 |
|
||
| DSP-03 | body | `escalationDeptIds[]` | string[] | 否 | 督办/协同部门标识集合 |
|
||
| DSP-03 | body | `dispatchMode` | enum | 是 | `MANUAL` 或 `SMART_CONFIRMED` |
|
||
| DSP-03 | body | `suggestionId` | string/null | 条件 | 采用智能建议时必填，人工派工为空 |
|
||
| DSP-03 | body | `workOrderVersion` | integer | 是 | 工单版本，用于并发校验 |
|
||
| DSP-03 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| DSP-04 | path | `taskId` | string | 是 | 待分派任务标识 |
|
||
| DSP-04 | body | `assigneeType` | enum | 是 | `USER` 或 `POST` |
|
||
| DSP-04 | body | `assigneeUserId` | string/null | 条件 | `assigneeType=USER` 时必填 |
|
||
| DSP-04 | body | `assigneePostId` | string/null | 条件 | `assigneeType=POST` 时必填 |
|
||
| DSP-04 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| DSP-04 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| DSP-05 | path | `id` | string | 是 | 工单标识 |
|
||
| DSP-05 | body | `reviewTaskId` | string | 是 | 当前审核任务标识 |
|
||
| DSP-05 | body | `callbackDeptId` | string | 是 | 主责工单回访承接部门 |
|
||
| DSP-05 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| DSP-05 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
|
||
TASK-01、TASK-02、TASK-03 和 DSP-01 均无请求体。
|
||
|
||
#### 8.8.2 响应字段定义
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| TASK-01 | `total` | integer | 当前用户符合条件的任务总数 |
|
||
| TASK-01 | `rows[]` | object[] | 当前页任务摘要 |
|
||
| TASK-01 | `rows[].taskId` | string | 任务标识 |
|
||
| TASK-01 | `rows[].workOrderId`/`workOrderNo12398` | string | 工单标识及 12398 工单号 |
|
||
| TASK-01 | `rows[].stage`/`stageName` | string | 环节编码及名称 |
|
||
| TASK-01 | `rows[].status` | enum | 任务状态 |
|
||
| TASK-01 | `rows[].assignee` | object/null | 承办人或岗位摘要 |
|
||
| TASK-01 | `rows[].deadlineAt` | datetime/null | 截止时间 |
|
||
| TASK-01 | `rows[].version` | integer | 任务版本 |
|
||
| TASK-01 | `rows[].allowedActions[]` | string[] | 当前用户允许动作 |
|
||
| TASK-02 | `data.total` | integer | 与当前过滤条件一致的任务总数 |
|
||
| TASK-02 | `data.counts[]` | object[] | 按环节统计集合 |
|
||
| TASK-02 | `data.counts[].stage`/`name` | string | 环节编码及名称 |
|
||
| TASK-02 | `data.counts[].count` | integer | 环节任务数量 |
|
||
| TASK-02 | `data.filterFingerprint` | string | 统计条件指纹，用于核对列表与卡片口径 |
|
||
| TASK-03 | `data.task` | object | 当前任务，至少包含 `taskId`、`stage`、`status`、`version` |
|
||
| TASK-03 | `data.workOrder` | object | 工单摘要及 `responsibilityType`、`version` |
|
||
| TASK-03 | `data.form` | object/null | 当前表单类型、草稿版本和保存时间 |
|
||
| TASK-03 | `data.allowedActions[]` | string[] | 当前任务允许动作 |
|
||
| DSP-01 | `data.preliminaryDepartments[]` | object[] | 可选初查部门，包含 `deptId`、`deptName`、`enabled` |
|
||
| DSP-01 | `data.firstContactDepartments[]` | object[] | 主责可选首联部门；协查返回空数组 |
|
||
| DSP-01 | `data.serviceOfficers[]` | object[] | 可选服务监督员，包含用户和部门标识 |
|
||
| DSP-01 | `data.escalationDepartments[]` | object[] | 可选督办/协同部门 |
|
||
| DSP-01 | `data.workOrderVersion` | integer | 当前工单版本 |
|
||
| DSP-02 | `data.suggestionId` | string | 智能建议标识 |
|
||
| DSP-02 | `data.ruleVersion` | integer | 命中的规则版本 |
|
||
| DSP-02 | `data.responsibilityType` | enum | 建议对应的责任类型 |
|
||
| DSP-02 | `data.preliminaryDeptIds[]` | string[] | 建议初查部门 |
|
||
| DSP-02 | `data.firstContactDeptId` | string/null | 建议首联部门，协查为空 |
|
||
| DSP-02 | `data.serviceOfficerUserId` | string | 建议服务监督员 |
|
||
| DSP-02 | `data.escalationDeptIds[]` | string[] | 建议督办部门 |
|
||
| DSP-02 | `data.explanations[]` | string[] | 规则命中说明，不作为最终派工事实 |
|
||
| DSP-03 | `data.dispatchId` | string | 派工记录标识 |
|
||
| DSP-03 | `data.workOrderId` | string | 工单标识 |
|
||
| DSP-03 | `data.responsibilityType` | enum | 已持久化的责任类型 |
|
||
| DSP-03 | `data.currentStage` | enum | 派工后的当前环节；主责与协查取值不同 |
|
||
| DSP-03 | `data.workOrderVersion` | integer | 更新后的工单版本 |
|
||
| DSP-03 | `data.createdTasks[]` | object[] | 本次派工生成的任务集合 |
|
||
| DSP-03 | `data.createdTasks[].taskId` | string | 新任务标识 |
|
||
| DSP-03 | `data.createdTasks[].stage`/`status` | enum | 新任务环节及状态 |
|
||
| DSP-03 | `data.createdTasks[].deptId` | string/null | 部门任务的承接部门 |
|
||
| DSP-03 | `data.createdTasks[].submitReady` | boolean/null | 调查任务当前是否可提交 |
|
||
| DSP-04 | `data.taskId` | string | 被分派任务标识 |
|
||
| DSP-04 | `data.assignee` | object | 新承办对象 |
|
||
| DSP-04 | `data.assignedBy` | object | 分派操作人 |
|
||
| DSP-04 | `data.assignedAt` | datetime | 分派时间 |
|
||
| DSP-04 | `data.taskVersion` | integer | 更新后的任务版本 |
|
||
| DSP-05 | `data.workOrderId` | string | 工单标识 |
|
||
| DSP-05 | `data.callbackDeptId` | string | 已确定的回访承接部门 |
|
||
| DSP-05 | `data.workOrderVersion` | integer | 更新后的工单版本 |
|
||
|
||
#### 8.8.3 请求与响应示例
|
||
|
||
##### TASK-01/TASK-02/TASK-03
|
||
|
||
`GET /risk/tasks?pageNum=1&pageSize=20&stage=INVESTIGATION&status=IN_PROGRESS&workOrderNo12398=2026-08-06-001` 无 body。
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"rows": [
|
||
{
|
||
"taskId": "TASK-INV-001",
|
||
"workOrderId": "WO-20260806-001",
|
||
"workOrderNo12398": "2026-08-06-001",
|
||
"stage": "INVESTIGATION",
|
||
"stageName": "调查结果填报",
|
||
"status": "IN_PROGRESS",
|
||
"assignee": { "type": "USER", "id": "1002", "name": "张某" },
|
||
"deadlineAt": "2026-08-08T18:00:00+08:00",
|
||
"version": 2,
|
||
"allowedActions": ["VIEW", "SAVE_DRAFT"]
|
||
}
|
||
],
|
||
"code": 200,
|
||
"msg": "查询成功"
|
||
}
|
||
```
|
||
|
||
`GET /risk/tasks/summary?workOrderNo12398=&customerName=` 无 body：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"total": 103,
|
||
"counts": [
|
||
{ "stage": "INVESTIGATION", "name": "调查结果填报", "count": 34 },
|
||
{ "stage": "REPORT", "name": "调查报告编写", "count": 12 }
|
||
],
|
||
"filterFingerprint": "sha256:62e8..."
|
||
}
|
||
}
|
||
```
|
||
|
||
`GET /risk/tasks/{taskId}` 返回工单摘要、任务、允许动作及当前表单版本：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"task": { "taskId": "TASK-INV-001", "stage": "INVESTIGATION", "status": "IN_PROGRESS", "version": 2 },
|
||
"workOrder": { "workOrderId": "WO-20260806-001", "workOrderNo12398": "2026-08-06-001", "responsibilityType": "PRIMARY", "version": 7 },
|
||
"form": { "formType": "INVESTIGATION", "draftVersion": 3, "lastSavedAt": "2026-08-13T10:10:00+08:00" },
|
||
"allowedActions": ["SAVE_DRAFT"]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### DSP-01 派工候选
|
||
|
||
`GET /risk/work-orders/{id}/dispatch-candidates?responsibilityType=PRIMARY` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"preliminaryDepartments": [{ "deptId": "D-OPS", "deptName": "运营部", "enabled": true }],
|
||
"firstContactDepartments": [{ "deptId": "D-CS1", "deptName": "客服一部", "enabled": true }],
|
||
"serviceOfficers": [{ "userId": "1002", "name": "张某", "deptId": "D-SERVICE", "enabled": true }],
|
||
"escalationDepartments": [{ "deptId": "D-BIZ", "deptName": "业务部", "enabled": true }],
|
||
"workOrderVersion": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
##### DSP-02 智能派工建议
|
||
|
||
```json
|
||
{
|
||
"workOrderVersion": 3,
|
||
"responsibilityType": "PRIMARY"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "建议生成成功",
|
||
"data": {
|
||
"suggestionId": "DS-001",
|
||
"ruleVersion": 5,
|
||
"responsibilityType": "PRIMARY",
|
||
"preliminaryDeptIds": ["D-OPS"],
|
||
"firstContactDeptId": "D-CS1",
|
||
"serviceOfficerUserId": "1002",
|
||
"escalationDeptIds": [],
|
||
"explanations": ["问题分类为安全隐患，命中运营部初查规则"]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### DSP-03 服务监督主管确认派工
|
||
|
||
主责请求体示例：
|
||
|
||
```json
|
||
{
|
||
"responsibilityType": "PRIMARY",
|
||
"preliminaryDeptIds": ["D-OPS", "D-BIZ"],
|
||
"firstContactDeptId": "D-CS1",
|
||
"serviceOfficerUserId": "1002",
|
||
"escalationDeptIds": [],
|
||
"dispatchMode": "MANUAL",
|
||
"suggestionId": null,
|
||
"workOrderVersion": 3,
|
||
"requestId": "04d7de39-3e48-4b1e-b327-e0048678ac6b"
|
||
}
|
||
```
|
||
|
||
协查请求体必须将 `firstContactDeptId` 设为 `null`：
|
||
|
||
```json
|
||
{
|
||
"responsibilityType": "ASSIST",
|
||
"preliminaryDeptIds": ["D-OPS", "D-BIZ"],
|
||
"firstContactDeptId": null,
|
||
"serviceOfficerUserId": "1002",
|
||
"escalationDeptIds": [],
|
||
"dispatchMode": "MANUAL",
|
||
"suggestionId": null,
|
||
"workOrderVersion": 3,
|
||
"requestId": "bc14ae85-cebd-4784-a30a-b42a56419ee5"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "派工成功",
|
||
"data": {
|
||
"dispatchId": "DISP-001",
|
||
"workOrderId": "WO-20260806-001",
|
||
"responsibilityType": "PRIMARY",
|
||
"currentStage": "FIRST_CONTACT_AND_PRELIMINARY_INVESTIGATION",
|
||
"workOrderVersion": 4,
|
||
"createdTasks": [
|
||
{ "taskId": "TASK-FC-001", "stage": "FIRST_CONTACT_ASSIGN", "status": "PENDING" },
|
||
{ "taskId": "TASK-PI-001", "stage": "PRELIMINARY_INVESTIGATION", "status": "PENDING", "deptId": "D-OPS" },
|
||
{ "taskId": "TASK-PI-002", "stage": "PRELIMINARY_INVESTIGATION", "status": "PENDING", "deptId": "D-BIZ" },
|
||
{ "taskId": "TASK-INV-001", "stage": "INVESTIGATION", "status": "IN_PROGRESS", "submitReady": false }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### DSP-04 班组/人员分派
|
||
|
||
```json
|
||
{
|
||
"assigneeType": "USER",
|
||
"assigneeUserId": "2001",
|
||
"assigneePostId": null,
|
||
"taskVersion": 1,
|
||
"requestId": "20cdb204-dc60-4182-bb9c-b6a1b5415c35"
|
||
}
|
||
```
|
||
|
||
响应采用 8.4.5 通用状态变更响应，并返回新的 `assignee`、`assignedBy`、`assignedAt`。
|
||
|
||
##### DSP-05 回访承接部门
|
||
|
||
```json
|
||
{
|
||
"reviewTaskId": "TASK-BR-001",
|
||
"callbackDeptId": "D-CS1",
|
||
"workOrderVersion": 10,
|
||
"requestId": "3197100b-1508-49c0-9d10-74459badbda2"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "回访承接部门已确定",
|
||
"data": {
|
||
"workOrderId": "WO-20260806-001",
|
||
"callbackDeptId": "D-CS1",
|
||
"workOrderVersion": 11
|
||
}
|
||
}
|
||
```
|
||
|
||
仅 `PRIMARY` 工单允许调用；具体由一级还是二级审核调用仍属于 D-03 待确认项。
|
||
|
||
### 8.9 办理、审核与回访接口请求与响应字段定义
|
||
|
||
#### 8.9.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| ACT-01 | path | `taskId` | string | 是 | 当前办理任务标识 |
|
||
| ACT-01 | body | `formType` | enum | 是 | 表单类型，如 `INVESTIGATION` |
|
||
| ACT-01 | body | `formData` | object | 是 | 草稿业务字段；结构必须与对应正式提交接口一致，可部分填写 |
|
||
| ACT-01 | body | `draftVersion` | integer | 是 | 草稿版本；首次保存传 0 |
|
||
| ACT-01 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-02 | path | `taskId` | string | 是 | 首联任务标识 |
|
||
| ACT-02 | body | `firstContactAt` | datetime | 是 | 实际首联时间，不得晚于提交时间 |
|
||
| ACT-02 | body | `firstContactOrderNo` | string | 是 | 首联关联工单号 |
|
||
| ACT-02 | body | `firstContactContent` | string | 是 | 首联内容 |
|
||
| ACT-02 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-02 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-03 | path | `taskId` | string | 是 | 初查任务标识 |
|
||
| ACT-03 | body | `preliminaryContent` | string | 是 | 本部门初查结论和事实说明 |
|
||
| ACT-03 | body | `attachmentFileIds[]` | string[] | 否 | 已上传且有权绑定的初查附件 |
|
||
| ACT-03 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-03 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-04 | path | `taskId` | string | 是 | 全面调查任务标识；无请求体 |
|
||
| ACT-05 | path | `taskId` | string | 是 | 全面调查任务标识 |
|
||
| ACT-05 | body | `acceptedContent12398` | string | 是 | 12398 受理内容 |
|
||
| ACT-05 | body | `externalExposureRisk` | boolean | 是 | 是否存在外部曝光风险 |
|
||
| ACT-05 | body | `internalAppealIssued` | boolean | 是 | 是否已下发内部诉求 |
|
||
| ACT-05 | body | `customerAppealSummary` | string | 是 | 客户诉求摘要 |
|
||
| ACT-05 | body | `escalationReason` | string | 否 | 升级/督办原因 |
|
||
| ACT-05 | body | `investigationProcess` | string | 是 | 调查过程 |
|
||
| ACT-05 | body | `localResponsibility` | boolean | 是 | 是否属于本单位责任 |
|
||
| ACT-05 | body | `handlingSituation` | string | 是 | 当前处理情况 |
|
||
| ACT-05 | body | `accountable` | boolean | 是 | 是否需要问责 |
|
||
| ACT-05 | body | `hasHandlingBasis` | boolean | 是 | 是否存在处理依据 |
|
||
| ACT-05 | body | `handlingMethod` | string | 是 | 处理方式 |
|
||
| ACT-05 | body | `handlingResult` | string | 是 | 处理结果 |
|
||
| ACT-05 | body | `investigationSummary` | string | 是 | 调查结论摘要 |
|
||
| ACT-05 | body | `draftVersion` | integer | 是 | 本次提交依据的草稿版本 |
|
||
| ACT-05 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-05 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-05 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-06 | path | `taskId` | string | 是 | 服务监督主管审核任务标识 |
|
||
| ACT-06 | body | `result` | enum | 是 | `APPROVED` 或 `REJECTED` |
|
||
| ACT-06 | body | `rejectReason` | string/null | 条件 | 驳回时必填，通过时为空 |
|
||
| ACT-06 | body | `investigationVersion` | integer | 是 | 审核所依据的调查版本 |
|
||
| ACT-06 | body | `taskVersion` | integer | 是 | 审核任务版本 |
|
||
| ACT-06 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-06 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-07 | path | `taskId` | string | 是 | 业务部主任审核任务标识 |
|
||
| ACT-07 | body | `result` | enum | 是 | `APPROVED` 或 `REJECTED` |
|
||
| ACT-07 | body | `rejectReason` | string/null | 条件 | 驳回时必填 |
|
||
| ACT-07 | body | `callbackDeptId` | string/null | 条件 | 若 D-03 确认为二级审核选部门，则主责通过时必填；协查必须为空 |
|
||
| ACT-07 | body | `investigationVersion` | integer | 是 | 审核依据的调查版本 |
|
||
| ACT-07 | body | `taskVersion` | integer | 是 | 审核任务版本 |
|
||
| ACT-07 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-07 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-08 | path | `taskId` | string | 是 | 主责工单的班组回访任务标识 |
|
||
| ACT-08 | body | `contactedAt` | datetime | 是 | 联系客户时间 |
|
||
| ACT-08 | body | `contactPhone` | string | 是 | 实际联系号码，敏感字段 |
|
||
| ACT-08 | body | `contactResult` | enum | 是 | 联系结果，如 `CONNECTED`、`NOT_CONNECTED` |
|
||
| ACT-08 | body | `contactSummary` | string | 是 | 回访执行摘要 |
|
||
| ACT-08 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-08 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-09 | path | `taskId` | string | 是 | 服务监督员回访结果任务标识 |
|
||
| ACT-09 | body | `respondentName` | string | 是 | 回复人姓名 |
|
||
| ACT-09 | body | `repliedAt` | datetime | 是 | 回复时间 |
|
||
| ACT-09 | body | `replyPhone` | string | 是 | 回复联系电话，敏感字段 |
|
||
| ACT-09 | body | `replySituation` | string | 是 | 回复情况 |
|
||
| ACT-09 | body | `callbackResult` | enum | 是 | `AGREE` 或 `DISAGREE_OR_CUSTOMER_REQUEST` |
|
||
| ACT-09 | body | `responseLetterFileIds[]` | string[] | 条件 | 不同意或客户主动要求时至少 1 个 |
|
||
| ACT-09 | body | `deliveryProofFileIds[]` | string[] | 条件 | 不同意或客户主动要求时至少 1 个 |
|
||
| ACT-09 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-09 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-09 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
|
||
#### 8.9.2 响应字段定义
|
||
|
||
除下列业务字段外，状态变更接口同时返回 8.4.5 定义的任务状态、当前环节、工单版本、任务版本和后续任务。
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| ACT-01 | `data.taskId` | string | 草稿所属任务 |
|
||
| ACT-01 | `data.draftVersion` | integer | 保存后的草稿版本 |
|
||
| ACT-01 | `data.taskVersion` | integer | 更新后的任务版本 |
|
||
| ACT-01 | `data.savedAt` | datetime | 服务端保存时间 |
|
||
| ACT-01 | `data.submitReady` | boolean | 当前是否满足正式提交条件 |
|
||
| ACT-02 | `data.firstContactId` | string | 不可变首联记录标识 |
|
||
| ACT-02 | `data.taskStatus` | enum | 首联任务完成后的状态 |
|
||
| ACT-02 | `data.workOrderVersion`/`taskVersion` | integer | 更新后的版本 |
|
||
| ACT-02 | `data.nextTasks[]` | object[] | 因首联完成而更新或生成的任务 |
|
||
| ACT-03 | `data.preliminaryInvestigationId` | string | 不可变初查记录标识 |
|
||
| ACT-03 | `data.taskId`/`taskStatus` | string/enum | 初查任务及完成状态 |
|
||
| ACT-03 | `data.completedCount`/`totalCount` | integer | 并行初查完成数及总数 |
|
||
| ACT-03 | `data.investigationSubmitReady` | boolean | 全面调查是否满足提交前置条件 |
|
||
| ACT-03 | `data.workOrderVersion`/`taskVersion` | integer | 更新后的版本 |
|
||
| ACT-04 | `data.taskId` | string | 全面调查任务标识 |
|
||
| ACT-04 | `data.taskVersion`/`workOrderVersion` | integer | 当前任务及工单版本 |
|
||
| ACT-04 | `data.responsibilityType` | enum | 主责或协查 |
|
||
| ACT-04 | `data.firstContact` | object/null | 主责首联结果；协查固定为空 |
|
||
| ACT-04 | `data.preliminaryProgress` | object | 并行初查完成数、总数及任务明细 |
|
||
| ACT-04 | `data.preliminaryProgress.items[]` | object[] | 各部门初查任务的 `taskId`、部门和状态 |
|
||
| ACT-04 | `data.draft` | object/null | 草稿版本及表单数据 |
|
||
| ACT-04 | `data.submitReady` | boolean | 是否允许提交全面调查 |
|
||
| ACT-04 | `data.incompletePrerequisites[]` | string[] | 未完成的前置任务标识 |
|
||
| ACT-05 | `data.investigationId` | string | 不可变调查记录标识 |
|
||
| ACT-05 | `data.investigationVersion` | integer | 本次形成的调查版本 |
|
||
| ACT-05 | `data.currentStage` | enum | 提交后进入 `SUPERVISOR_REVIEW` |
|
||
| ACT-05 | `data.nextTasks[]` | object[] | 新建的服务监督主管审核任务 |
|
||
| ACT-06 | `data.reviewId` | string | 审核记录标识 |
|
||
| ACT-06 | `data.reviewLevel` | enum | 固定为 `SUPERVISOR` |
|
||
| ACT-06 | `data.reviewResult` | enum | 审核结果 |
|
||
| ACT-06 | `data.currentStage` | enum | 通过进入业务审核，驳回回到调查 |
|
||
| ACT-06 | `data.nextTasks[]` | object[] | 业务审核或返工任务 |
|
||
| ACT-07 | `data.reviewId` | string | 业务审核记录标识 |
|
||
| ACT-07 | `data.responsibilityType` | enum | 服务端从派工记录读取的责任类型 |
|
||
| ACT-07 | `data.currentStage` | enum | 主责通过为 `CALLBACK_ASSIGN`；协查通过为 `REPORT`；驳回为 `INVESTIGATION` |
|
||
| ACT-07 | `data.nextTasks[]` | object[] | 按唯一业务分支生成的任务 |
|
||
| ACT-08 | `data.callbackExecutionId` | string | 班组回访执行记录标识 |
|
||
| ACT-08 | `data.taskStatus` | enum | 回访执行任务状态 |
|
||
| ACT-08 | `data.nextTasks[]` | object[] | 后续服务监督员回访结果任务 |
|
||
| ACT-09 | `data.callbackResultId` | string | 回访结果记录标识 |
|
||
| ACT-09 | `data.callbackResult` | enum | 已保存的回访结果 |
|
||
| ACT-09 | `data.currentStage` | enum | 成功后进入 `REPORT` |
|
||
| ACT-09 | `data.nextTasks[]` | object[] | 新建调查报告任务 |
|
||
|
||
#### 8.9.3 请求与响应示例
|
||
|
||
##### ACT-01 保存草稿
|
||
|
||
```json
|
||
{
|
||
"formType": "INVESTIGATION",
|
||
"formData": {
|
||
"investigationSummary": "经初查，台区监测记录存在短时电压波动。",
|
||
"customerAppealSummary": "客户要求核查原因并恢复稳定供电。",
|
||
"investigationProcess": "已调取历史记录并组织现场检查。"
|
||
},
|
||
"draftVersion": 3,
|
||
"taskVersion": 2
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "草稿已保存",
|
||
"data": {
|
||
"taskId": "TASK-INV-001",
|
||
"draftVersion": 4,
|
||
"taskVersion": 3,
|
||
"savedAt": "2026-08-13T10:30:00+08:00",
|
||
"submitReady": false
|
||
}
|
||
}
|
||
```
|
||
|
||
##### ACT-02 提交首联
|
||
|
||
```json
|
||
{
|
||
"firstContactAt": "2026-08-12T14:32:00+08:00",
|
||
"firstContactOrderNo": "2026-08-06-001",
|
||
"firstContactContent": "已联系客户核实情况并告知后续调查安排。",
|
||
"taskVersion": 1,
|
||
"requestId": "b4e95b87-3ec4-4207-aa85-d2df28641cc0"
|
||
}
|
||
```
|
||
|
||
响应采用 8.4.5，并返回 `firstContactId`；协查工单调用时返回 `RISK-4091`。
|
||
|
||
##### ACT-03 提交事件初查
|
||
|
||
```json
|
||
{
|
||
"preliminaryContent": "现场检查设备运行正常，监测到短时电压波动。",
|
||
"attachmentFileIds": ["FILE-PI-001"],
|
||
"taskVersion": 1,
|
||
"requestId": "85dd9477-c5df-444e-8b31-6fd660bc36ee"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "初查结果已提交",
|
||
"data": {
|
||
"preliminaryInvestigationId": "PINV-001",
|
||
"taskId": "TASK-PI-001",
|
||
"taskStatus": "COMPLETED",
|
||
"completedCount": 2,
|
||
"totalCount": 3,
|
||
"investigationSubmitReady": false,
|
||
"workOrderVersion": 6,
|
||
"taskVersion": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
##### ACT-04 全面调查上下文
|
||
|
||
`GET /risk/tasks/{taskId}/investigation-context` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"taskId": "TASK-INV-001",
|
||
"taskVersion": 3,
|
||
"workOrderVersion": 7,
|
||
"responsibilityType": "PRIMARY",
|
||
"firstContact": { "status": "COMPLETED", "firstContactAt": "2026-08-12T14:32:00+08:00", "content": "已完成首联" },
|
||
"preliminaryProgress": {
|
||
"completedCount": 1,
|
||
"totalCount": 3,
|
||
"items": [
|
||
{ "taskId": "TASK-PI-001", "deptId": "D-OPS", "deptName": "运营部", "status": "COMPLETED" },
|
||
{ "taskId": "TASK-PI-002", "deptId": "D-BIZ", "deptName": "业务部", "status": "PENDING" }
|
||
]
|
||
},
|
||
"draft": { "draftVersion": 4, "formData": {} },
|
||
"submitReady": false,
|
||
"incompletePrerequisites": ["TASK-PI-002", "TASK-PI-003"]
|
||
}
|
||
}
|
||
```
|
||
|
||
协查响应中的 `firstContact` 必须为 `null`，其 `submitReady` 只依据全部事件初查是否完成。
|
||
|
||
##### ACT-05 提交全面调查
|
||
|
||
```json
|
||
{
|
||
"acceptedContent12398": "客户反映近期电压不稳，设备频繁重启。",
|
||
"externalExposureRisk": false,
|
||
"internalAppealIssued": false,
|
||
"customerAppealSummary": "客户要求核查电压不稳原因并恢复稳定供电。",
|
||
"escalationReason": "问题偶发且多次反映。",
|
||
"investigationProcess": "调取95598历史记录及台区监测数据并现场检查。",
|
||
"localResponsibility": true,
|
||
"handlingSituation": "已完成线路及设备检查。",
|
||
"accountable": false,
|
||
"hasHandlingBasis": true,
|
||
"handlingMethod": "调整运行参数并增加监测频次。",
|
||
"handlingResult": "当前数据恢复正常，后续持续跟踪。",
|
||
"investigationSummary": "存在短时波动，已完成处置。",
|
||
"draftVersion": 4,
|
||
"taskVersion": 3,
|
||
"workOrderVersion": 7,
|
||
"requestId": "b6848224-1277-421e-907e-4a1f4c1039bb"
|
||
}
|
||
```
|
||
|
||
响应采用 8.4.5，并额外返回不可变的 `investigationId` 和 `investigationVersion`。前置任务未完成返回 `RISK-4220`。
|
||
|
||
##### ACT-06 服务监督主管审核
|
||
|
||
```json
|
||
{
|
||
"result": "APPROVED",
|
||
"rejectReason": null,
|
||
"investigationVersion": 1,
|
||
"taskVersion": 1,
|
||
"workOrderVersion": 8,
|
||
"requestId": "2ec9fd4b-c493-44dc-b1fd-8e70f72754ab"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "审核通过",
|
||
"data": {
|
||
"reviewId": "REV-S-001",
|
||
"reviewLevel": "SUPERVISOR",
|
||
"reviewResult": "APPROVED",
|
||
"currentStage": "BUSINESS_REVIEW",
|
||
"workOrderVersion": 9,
|
||
"taskVersion": 2,
|
||
"nextTasks": [{ "taskId": "TASK-BR-001", "stage": "BUSINESS_REVIEW", "status": "PENDING" }]
|
||
}
|
||
}
|
||
```
|
||
|
||
驳回时 `result` 为 `REJECTED` 且 `rejectReason` 必填；响应的 `currentStage` 回到 `INVESTIGATION`，并返回新建返工任务。
|
||
|
||
##### ACT-07 业务部主任审核
|
||
|
||
主责审核通过且 D-03 决定由二级审核选回访部门时：
|
||
|
||
```json
|
||
{
|
||
"result": "APPROVED",
|
||
"rejectReason": null,
|
||
"callbackDeptId": "D-CS1",
|
||
"investigationVersion": 1,
|
||
"taskVersion": 1,
|
||
"workOrderVersion": 9,
|
||
"requestId": "6c704449-6022-40fa-a7bb-509b879e93ee"
|
||
}
|
||
```
|
||
|
||
协查审核请求体必须省略或将 `callbackDeptId` 设为 `null`。主责响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "审核通过，进入回访分配",
|
||
"data": {
|
||
"reviewId": "REV-B-001",
|
||
"responsibilityType": "PRIMARY",
|
||
"currentStage": "CALLBACK_ASSIGN",
|
||
"workOrderVersion": 10,
|
||
"taskVersion": 2,
|
||
"nextTasks": [{ "taskId": "TASK-CA-001", "stage": "CALLBACK_ASSIGN", "status": "PENDING", "deptId": "D-CS1" }]
|
||
}
|
||
}
|
||
```
|
||
|
||
协查响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "审核通过，直接进入调查报告编写",
|
||
"data": {
|
||
"reviewId": "REV-B-002",
|
||
"responsibilityType": "ASSIST",
|
||
"currentStage": "REPORT",
|
||
"workOrderVersion": 10,
|
||
"taskVersion": 2,
|
||
"nextTasks": [{ "taskId": "TASK-RPT-001", "stage": "REPORT", "status": "PENDING" }]
|
||
}
|
||
}
|
||
```
|
||
|
||
服务端必须根据派工记录中的 `responsibilityType` 生成唯一分支，不接受客户端通过目标状态控制分支。
|
||
|
||
##### ACT-08 提交班组回访
|
||
|
||
班组回访字段仍待业务确认，当前最小请求体建议为：
|
||
|
||
```json
|
||
{
|
||
"contactedAt": "2026-08-13T15:20:00+08:00",
|
||
"contactPhone": "13800008888",
|
||
"contactResult": "CONNECTED",
|
||
"contactSummary": "已向客户说明处理情况。",
|
||
"taskVersion": 1,
|
||
"requestId": "8f596b61-fcd9-4d52-93cc-0908c4654b8c"
|
||
}
|
||
```
|
||
|
||
响应采用 8.4.5，并返回 `callbackExecutionId`；仅主责回访任务允许调用。
|
||
|
||
##### ACT-09 服务监督员提交回访结果
|
||
|
||
“同意”分支：
|
||
|
||
```json
|
||
{
|
||
"respondentName": "监督员A（张某）",
|
||
"repliedAt": "2026-08-13T16:00:00+08:00",
|
||
"replyPhone": "13100007777",
|
||
"replySituation": "客户认可处理结果。",
|
||
"callbackResult": "AGREE",
|
||
"responseLetterFileIds": [],
|
||
"deliveryProofFileIds": [],
|
||
"taskVersion": 1,
|
||
"workOrderVersion": 12,
|
||
"requestId": "84808ee5-c306-4543-89e1-53f733e2a3c8"
|
||
}
|
||
```
|
||
|
||
“不同意或客户主动要求”分支：
|
||
|
||
```json
|
||
{
|
||
"respondentName": "监督员A（张某）",
|
||
"repliedAt": "2026-08-13T16:00:00+08:00",
|
||
"replyPhone": "13100007777",
|
||
"replySituation": "客户要求提供书面答复。",
|
||
"callbackResult": "DISAGREE_OR_CUSTOMER_REQUEST",
|
||
"responseLetterFileIds": ["FILE-RL-001"],
|
||
"deliveryProofFileIds": ["FILE-DP-001"],
|
||
"taskVersion": 1,
|
||
"workOrderVersion": 12,
|
||
"requestId": "560215f4-cab9-4ff2-806f-d47950116eea"
|
||
}
|
||
```
|
||
|
||
响应采用 8.4.5，并创建 `REPORT` 任务。缺少任一类附件返回 `RISK-4221`。
|
||
|
||
### 8.10 调查报告、成果物与办结接口请求与响应字段定义
|
||
|
||
#### 8.10.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| ACT-10 | path | `taskId` | string | 是 | 调查报告任务标识；无请求体 |
|
||
| ACT-11 | path | `taskId` | string | 是 | 调查报告任务标识 |
|
||
| ACT-11 | body | `templateId` | string | 是 | 报告模板标识 |
|
||
| ACT-11 | body | `templateVersion` | integer | 是 | 报告模板版本 |
|
||
| ACT-11 | body | `investigationVersion` | integer | 是 | 锁定的调查版本 |
|
||
| ACT-11 | body | `callbackVersion` | integer/null | 条件 | 主责必填；协查必须为空 |
|
||
| ACT-11 | body | `taskVersion` | integer | 是 | 报告任务版本 |
|
||
| ACT-11 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-11 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-12 | path | `reportId` | string | 是 | 已生成报告标识；无请求体 |
|
||
| ACT-13 | path | `taskId` | string | 是 | 成果物提交任务标识 |
|
||
| ACT-13 | body | `reportId` | string | 是 | 已生成报告标识 |
|
||
| ACT-13 | body | `reportVersion` | integer | 是 | 报告版本 |
|
||
| ACT-13 | body | `deliverables[]` | object[] | 是 | 成果物集合，至少 1 项 |
|
||
| ACT-13 | body | `deliverables[].type` | enum | 是 | 成果物类型 |
|
||
| ACT-13 | body | `deliverables[].fileId` | string | 是 | 已上传并有权绑定的文件标识 |
|
||
| ACT-13 | body | `taskVersion` | integer | 是 | 任务版本 |
|
||
| ACT-13 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-13 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
| ACT-14 | path | `id` | string | 是 | 工单标识 |
|
||
| ACT-14 | body | `closeReason` | string | 是 | 办结原因/说明 |
|
||
| ACT-14 | body | `deliverableSetId` | string | 是 | 已提交成果物集合标识 |
|
||
| ACT-14 | body | `workOrderVersion` | integer | 是 | 工单版本 |
|
||
| ACT-14 | body | `requestId` | string | 是 | 幂等请求标识 |
|
||
|
||
#### 8.10.2 响应字段定义
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| ACT-10 | `data.taskId`/`taskVersion` | string/integer | 报告任务及版本 |
|
||
| ACT-10 | `data.workOrder` | object | 工单标识、12398 工单号、责任类型和版本 |
|
||
| ACT-10 | `data.investigation` | object | 锁定的调查记录、版本、提交时间和结构化数据 |
|
||
| ACT-10 | `data.callback` | object/null | 主责的回访结果；协查固定为空 |
|
||
| ACT-10 | `data.attachments[]` | object[] | 报告可引用附件 |
|
||
| ACT-10 | `data.template` | object | 模板标识、版本和名称 |
|
||
| ACT-10 | `data.output` | object | 输出状态、报告标识和文件标识 |
|
||
| ACT-10 | `data.allowedActions[]` | string[] | 当前允许的报告动作 |
|
||
| ACT-11 | `data.reportId` | string | 报告标识 |
|
||
| ACT-11 | `data.jobId` | string/null | 异步生成任务标识；同步生成时为空 |
|
||
| ACT-11 | `data.outputStatus` | enum | `GENERATING`、`READY` 或 `FAILED` |
|
||
| ACT-11 | `data.fileId`/`fileName` | string/null | 同步完成或异步完成后的文件信息 |
|
||
| ACT-11 | `data.contentType` | string/null | 报告文件 MIME 类型 |
|
||
| ACT-11 | `data.downloadable` | boolean | 当前是否可下载 |
|
||
| ACT-11 | `data.taskVersion`/`workOrderVersion` | integer | 更新后的版本 |
|
||
| ACT-12 | HTTP body | binary | 报告文件流 |
|
||
| ACT-12 | `Content-Type` | string | 报告文件 MIME 类型 |
|
||
| ACT-12 | `Content-Disposition` | string | 下载文件名 |
|
||
| ACT-12 | `X-File-Id` | string | 输出文件标识 |
|
||
| ACT-12 | `X-Report-Version` | integer | 报告版本 |
|
||
| ACT-13 | `data.deliverableSetId` | string | 成果物集合标识 |
|
||
| ACT-13 | `data.taskStatus` | enum | 成果物任务状态 |
|
||
| ACT-13 | `data.currentStage` | enum | 当前流程环节 |
|
||
| ACT-13 | `data.readyToClose` | boolean | 是否满足办结条件 |
|
||
| ACT-13 | `data.taskVersion`/`workOrderVersion` | integer | 更新后的版本 |
|
||
| ACT-14 | `data.workOrderId` | string | 已办结工单标识 |
|
||
| ACT-14 | `data.orderStatus` | enum | 固定为 `CLOSED` |
|
||
| ACT-14 | `data.currentStage` | enum | 办结时所在环节 |
|
||
| ACT-14 | `data.closedAt` | datetime | 服务端办结时间 |
|
||
| ACT-14 | `data.closedBy` | object | 办结人，包含 `userId`、`name` |
|
||
| ACT-14 | `data.workOrderVersion` | integer | 更新后的工单版本 |
|
||
|
||
#### 8.10.3 请求与响应示例
|
||
|
||
##### ACT-10 报告上下文
|
||
|
||
`GET /risk/tasks/{taskId}/report-context` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"taskId": "TASK-RPT-001",
|
||
"taskVersion": 1,
|
||
"workOrder": { "workOrderId": "WO-20260806-009", "workOrderNo12398": "2026-08-06-009", "responsibilityType": "ASSIST", "version": 10 },
|
||
"investigation": { "investigationId": "INV-009", "version": 1, "submittedAt": "2026-08-13T10:00:00+08:00", "data": {} },
|
||
"callback": null,
|
||
"attachments": [],
|
||
"template": { "templateId": "TPL-RPT-001", "templateVersion": 2, "name": "12398调查报告" },
|
||
"output": { "status": "PENDING", "reportId": null, "fileId": null },
|
||
"allowedActions": ["CONFIRM_REPORT"]
|
||
}
|
||
}
|
||
```
|
||
|
||
主责工单的 `callback` 必须包含已完成的回访版本；协查必须为 `null`。
|
||
|
||
##### ACT-11 确认生成报告
|
||
|
||
```json
|
||
{
|
||
"templateId": "TPL-RPT-001",
|
||
"templateVersion": 2,
|
||
"investigationVersion": 1,
|
||
"callbackVersion": null,
|
||
"taskVersion": 1,
|
||
"workOrderVersion": 10,
|
||
"requestId": "aec607a6-a962-4f97-9650-d49624988bcb"
|
||
}
|
||
```
|
||
|
||
异步生成响应建议使用 HTTP `202 Accepted`：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "报告生成任务已创建",
|
||
"data": {
|
||
"reportId": "RPT-001",
|
||
"jobId": "JOB-RPT-001",
|
||
"outputStatus": "GENERATING",
|
||
"taskVersion": 2,
|
||
"workOrderVersion": 11
|
||
}
|
||
}
|
||
```
|
||
|
||
若实现为同步生成，可返回 HTTP 200，并直接提供 `fileId`、`fileName`、`contentType` 和 `downloadable: true`。
|
||
|
||
##### ACT-12 下载报告
|
||
|
||
`GET /risk/reports/{reportId}/download` 无 body。成功返回受控文件流：
|
||
|
||
```http
|
||
Content-Type: application/pdf
|
||
Content-Disposition: attachment; filename="2026-08-06-009-调查报告.pdf"
|
||
X-File-Id: FILE-RPT-001
|
||
X-Report-Version: 1
|
||
```
|
||
|
||
报告仍在生成时返回 HTTP 409、`RISK-4091`；生成失败时响应应包含可展示的失败原因和是否允许重新生成。
|
||
|
||
##### ACT-13 提交成果物
|
||
|
||
```json
|
||
{
|
||
"reportId": "RPT-001",
|
||
"reportVersion": 1,
|
||
"deliverables": [
|
||
{ "type": "INVESTIGATION_REPORT", "fileId": "FILE-RPT-001" },
|
||
{ "type": "SUPPORTING_MATERIAL", "fileId": "FILE-SUP-001" }
|
||
],
|
||
"taskVersion": 1,
|
||
"workOrderVersion": 11,
|
||
"requestId": "e2f3d22c-2be0-461c-b9e5-c089ea4c0e9c"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "成果物已提交",
|
||
"data": {
|
||
"deliverableSetId": "DEL-001",
|
||
"taskStatus": "COMPLETED",
|
||
"currentStage": "DELIVERABLE",
|
||
"readyToClose": true,
|
||
"taskVersion": 2,
|
||
"workOrderVersion": 12
|
||
}
|
||
}
|
||
```
|
||
|
||
##### ACT-14 确认办结
|
||
|
||
```json
|
||
{
|
||
"closeReason": "调查、审核、报告及成果物均已完成",
|
||
"deliverableSetId": "DEL-001",
|
||
"workOrderVersion": 12,
|
||
"requestId": "995a8d84-a776-4dd8-98ca-779004ab8cbb"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "工单已办结",
|
||
"data": {
|
||
"workOrderId": "WO-20260806-001",
|
||
"orderStatus": "CLOSED",
|
||
"currentStage": "DELIVERABLE",
|
||
"closedAt": "2026-08-13T17:30:00+08:00",
|
||
"closedBy": { "userId": "1002", "name": "张某" },
|
||
"workOrderVersion": 13
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.11 文件、字典、配置、统计与异步任务接口请求与响应字段定义
|
||
|
||
#### 8.11.1 请求字段定义
|
||
|
||
| 接口 | 字段位置 | 字段 | 类型 | 必填 | 定义 |
|
||
| --- | --- | --- | --- | :---: | --- |
|
||
| FILE-01 | multipart | `file` | binary | 是 | 待上传文件，须校验大小、扩展名、MIME 和安全风险 |
|
||
| FILE-01 | multipart | `purpose` | enum | 是 | 文件用途，取值见 8.12 |
|
||
| FILE-01 | multipart | `workOrderId` | string | 是 | 所属工单标识 |
|
||
| FILE-01 | multipart | `taskId` | string | 条件 | 任务办理过程中上传时必填 |
|
||
| FILE-02 | path | `fileId` | string | 是 | 文件标识；无请求体 |
|
||
| FILE-03 | path | `fileId` | string | 是 | 临时文件标识 |
|
||
| FILE-03 | query | `version` | integer | 是 | 文件记录版本；无请求体 |
|
||
| DICT-01 | path | `type` | string | 是 | 字典类型编码 |
|
||
| DICT-01 | query | `enabled` | boolean | 否 | 是否只返回启用项，默认 `true` |
|
||
| CFG-01 | — | — | — | — | 无查询参数、无请求体 |
|
||
| CFG-02 | body | `configVersion` | integer | 是 | 当前时限配置版本 |
|
||
| CFG-02 | body | `totalLimitMinutes` | integer | 是 | 全流程总时限，必须为正整数 |
|
||
| CFG-02 | body | `stages[]` | object[] | 是 | 环节时限集合 |
|
||
| CFG-02 | body | `stages[].stageCode` | enum | 是 | 环节编码，不得重复 |
|
||
| CFG-02 | body | `stages[].limitMinutes` | integer | 是 | 环节时限，必须为正整数 |
|
||
| CFG-02 | body | `effectiveFrom` | datetime | 是 | 新版本生效时间 |
|
||
| CFG-02 | body | `changeReason` | string | 是 | 变更原因 |
|
||
| CFG-02 | body | `publish` | boolean | 是 | 是否立即发布 |
|
||
| CFG-03 | — | — | — | — | 无查询参数、无请求体 |
|
||
| CFG-04 | body | `ruleVersion` | integer | 是 | 当前规则版本 |
|
||
| CFG-04 | body | `rules[]` | object[] | 是 | 派工规则集合 |
|
||
| CFG-04 | body | `rules[].ruleId` | string | 条件 | 修改已有规则时必填；新增时可为空 |
|
||
| CFG-04 | body | `rules[].priority` | integer | 是 | 规则优先级，数值冲突处理方式待确认 |
|
||
| CFG-04 | body | `rules[].conditions[]` | object[] | 是 | 匹配条件集合 |
|
||
| CFG-04 | body | `rules[].conditions[].field` | string | 是 | 条件字段，必须来自白名单 |
|
||
| CFG-04 | body | `rules[].conditions[].operator` | enum | 是 | 比较操作符 |
|
||
| CFG-04 | body | `rules[].conditions[].value` | any | 是 | 比较值，类型须与字段一致 |
|
||
| CFG-04 | body | `rules[].result` | object | 是 | 派工建议结果 |
|
||
| CFG-04 | body | `rules[].enabled` | boolean | 是 | 规则是否启用 |
|
||
| CFG-04 | body | `effectiveFrom` | datetime | 是 | 生效时间 |
|
||
| CFG-04 | body | `changeReason` | string | 是 | 变更原因 |
|
||
| CFG-04 | body | `publish` | boolean | 是 | 是否发布 |
|
||
| ANA-01 | query | `from` | date | 是 | 统计开始日期，含边界 |
|
||
| ANA-01 | query | `to` | date | 是 | 统计结束日期，含边界 |
|
||
| ANA-01 | query | `deptId` | string | 否 | 部门范围；仍受当前用户数据权限约束 |
|
||
| ANA-02 | query | `pageNum` | integer | 是 | 页码，从 1 开始 |
|
||
| ANA-02 | query | `pageSize` | integer | 是 | 每页数量 |
|
||
| ANA-02 | query | `from` | date | 是 | 办结开始日期 |
|
||
| ANA-02 | query | `to` | date | 是 | 办结结束日期 |
|
||
| ANA-02 | query | `deptId` | string | 否 | 部门范围 |
|
||
| JOB-01 | path | `jobId` | string | 是 | 异步任务标识；无请求体 |
|
||
|
||
#### 8.11.2 响应字段定义
|
||
|
||
| 接口 | 响应字段 | 类型 | 定义 |
|
||
| --- | --- | --- | --- |
|
||
| FILE-01 | `data.fileId` | string | 文件标识，后续业务接口仅传此标识 |
|
||
| FILE-01 | `data.fileName` | string | 安全处理后的文件名 |
|
||
| FILE-01 | `data.contentType` | string | 服务端识别的 MIME 类型 |
|
||
| FILE-01 | `data.size` | integer | 文件字节数 |
|
||
| FILE-01 | `data.sha256` | string | 文件摘要 |
|
||
| FILE-01 | `data.purpose` | enum | 文件用途 |
|
||
| FILE-01 | `data.bindingStatus` | enum | `TEMPORARY` 或 `BOUND` |
|
||
| FILE-01 | `data.uploadedAt` | datetime | 上传完成时间 |
|
||
| FILE-02 | HTTP body | binary | 受控文件流 |
|
||
| FILE-02 | `Content-Type` | string | 文件 MIME 类型 |
|
||
| FILE-02 | `Content-Disposition` | string | 内联播放或附件下载及安全文件名 |
|
||
| FILE-02 | `Content-Length` | integer | 文件字节数 |
|
||
| FILE-03 | `data.fileId` | string | 已删除临时文件标识 |
|
||
| FILE-03 | `data.deleted` | boolean | 是否删除成功 |
|
||
| DICT-01 | `data.type` | string | 字典类型 |
|
||
| DICT-01 | `data.version` | integer | 字典版本 |
|
||
| DICT-01 | `data.items[]` | object[] | 字典项集合 |
|
||
| DICT-01 | `data.items[].value`/`label` | string | 字典编码及显示名称 |
|
||
| DICT-01 | `data.items[].sort` | integer | 排序值 |
|
||
| DICT-01 | `data.items[].enabled` | boolean | 是否启用 |
|
||
| CFG-01/CFG-02 | `data.configId` | string | 时限配置标识 |
|
||
| CFG-01/CFG-02 | `data.configVersion` | integer | 配置版本 |
|
||
| CFG-01/CFG-02 | `data.status` | enum | 草稿、启用或停用 |
|
||
| CFG-01/CFG-02 | `data.totalLimitMinutes` | integer | 全流程总时限 |
|
||
| CFG-01/CFG-02 | `data.stages[]` | object[] | 环节编码及分钟数 |
|
||
| CFG-01/CFG-02 | `data.effectiveFrom` | datetime | 生效时间 |
|
||
| CFG-03/CFG-04 | `data.ruleSetId` | string | 规则集标识 |
|
||
| CFG-03/CFG-04 | `data.ruleVersion` | integer | 规则版本 |
|
||
| CFG-03/CFG-04 | `data.status` | enum | 规则集状态 |
|
||
| CFG-03/CFG-04 | `data.rules[]` | object[] | 规则、条件和建议结果集合 |
|
||
| CFG-03/CFG-04 | `data.effectiveFrom` | datetime | 生效时间 |
|
||
| ANA-01 | `data.period` | object | 实际统计日期范围 |
|
||
| ANA-01 | `data.metrics.importedCount` | integer | 导入工单数 |
|
||
| ANA-01 | `data.metrics.processingCount` | integer | 处理中工单数 |
|
||
| ANA-01 | `data.metrics.closedCount` | integer | 已办结工单数 |
|
||
| ANA-01 | `data.metrics.overdueCount` | integer | 逾期工单数 |
|
||
| ANA-01 | `data.metrics.primaryCount` | integer | 主责工单数 |
|
||
| ANA-01 | `data.metrics.assistCount` | integer | 协查工单数 |
|
||
| ANA-01 | `data.generatedAt` | datetime | 统计数据生成时间 |
|
||
| ANA-02 | `total` | integer | 已办结工单总数 |
|
||
| ANA-02 | `rows[]` | object[] | 工单摘要，继承 WO-01 并增加办结字段 |
|
||
| ANA-02 | `rows[].closedAt` | datetime | 办结时间 |
|
||
| ANA-02 | `rows[].durationMinutes` | integer | 从规定起点到办结的耗时分钟数，口径待 D-07 确认 |
|
||
| ANA-02 | `rows[].overdue` | boolean | 是否逾期 |
|
||
| JOB-01 | `data.jobId` | string | 异步任务标识 |
|
||
| JOB-01 | `data.jobType` | enum | 任务类型，如导入或报告生成 |
|
||
| JOB-01 | `data.status` | enum | `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED`、`CANCELLED` |
|
||
| JOB-01 | `data.progress` | integer | 0～100 的整数进度 |
|
||
| JOB-01 | `data.createdAt`/`finishedAt` | datetime/null | 创建和结束时间 |
|
||
| JOB-01 | `data.result` | object/null | 成功结果；结构由 `jobType` 决定 |
|
||
| JOB-01 | `data.error` | object/null | 失败信息，至少包含稳定错误码和说明 |
|
||
|
||
#### 8.11.3 请求与响应示例
|
||
|
||
##### FILE-01/FILE-02/FILE-03 文件接口
|
||
|
||
`POST /risk/files` 使用 `multipart/form-data`：`file`、`purpose`、`workOrderId`、`taskId`。`purpose` 取值见 8.12。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "上传成功",
|
||
"data": {
|
||
"fileId": "FILE-RL-001",
|
||
"fileName": "答复书.pdf",
|
||
"contentType": "application/pdf",
|
||
"size": 248102,
|
||
"sha256": "53dd...a8cb",
|
||
"purpose": "RESPONSE_LETTER",
|
||
"bindingStatus": "TEMPORARY",
|
||
"uploadedAt": "2026-08-13T15:45:00+08:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
FILE-02 `GET /risk/files/{fileId}` 无 body，成功返回受控文件流；无权访问返回 `RISK-4031`。FILE-03：
|
||
|
||
```http
|
||
DELETE /risk/files/{fileId}?version=1
|
||
```
|
||
|
||
```json
|
||
{ "code": 200, "msg": "临时文件已删除", "data": { "fileId": "FILE-RL-001", "deleted": true } }
|
||
```
|
||
|
||
已绑定业务记录的文件不得通过 FILE-03 删除。
|
||
|
||
##### DICT-01 字典
|
||
|
||
`GET /risk/dictionaries/{type}?enabled=true` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"type": "RESPONSIBILITY_TYPE",
|
||
"version": 1,
|
||
"items": [
|
||
{ "value": "PRIMARY", "label": "主责", "sort": 1, "enabled": true },
|
||
{ "value": "ASSIST", "label": "协查", "sort": 2, "enabled": true }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
##### CFG-01/CFG-02 时限配置
|
||
|
||
`GET /risk/config/sla` 无 body；响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"configId": "SLA-001",
|
||
"configVersion": 3,
|
||
"status": "ENABLED",
|
||
"totalLimitMinutes": 188,
|
||
"stages": [
|
||
{ "stageCode": "DISPATCH", "limitMinutes": 20 },
|
||
{ "stageCode": "FIRST_CONTACT", "limitMinutes": 30 },
|
||
{ "stageCode": "PRELIMINARY_INVESTIGATION", "limitMinutes": 60 }
|
||
],
|
||
"effectiveFrom": "2026-08-01T00:00:00+08:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
`PUT /risk/config/sla` 请求体：
|
||
|
||
```json
|
||
{
|
||
"configVersion": 3,
|
||
"totalLimitMinutes": 188,
|
||
"stages": [
|
||
{ "stageCode": "DISPATCH", "limitMinutes": 20 },
|
||
{ "stageCode": "FIRST_CONTACT", "limitMinutes": 30 },
|
||
{ "stageCode": "PRELIMINARY_INVESTIGATION", "limitMinutes": 60 }
|
||
],
|
||
"effectiveFrom": "2026-09-01T00:00:00+08:00",
|
||
"changeReason": "调整事件初查时限",
|
||
"publish": true
|
||
}
|
||
```
|
||
|
||
响应返回新的 `configId`、`configVersion`、`status`、`effectiveFrom`，不得覆盖旧版本。
|
||
|
||
##### CFG-03/CFG-04 派工规则
|
||
|
||
`GET /risk/config/dispatch-rules` 无 body；响应 `data` 至少包含 `ruleSetId`、`ruleVersion`、`status`、`rules`。
|
||
|
||
```json
|
||
{
|
||
"ruleVersion": 5,
|
||
"rules": [
|
||
{
|
||
"ruleId": "RULE-001",
|
||
"priority": 10,
|
||
"conditions": [{ "field": "problemCategoryCode", "operator": "EQ", "value": "SAFETY_RISK" }],
|
||
"result": { "preliminaryDeptIds": ["D-OPS"] },
|
||
"enabled": true
|
||
}
|
||
],
|
||
"effectiveFrom": "2026-09-01T00:00:00+08:00",
|
||
"changeReason": "安全隐患默认由运营部初查",
|
||
"publish": true
|
||
}
|
||
```
|
||
|
||
响应返回新规则版本和发布状态。规则 DSL、冲突策略和试算接口仍属于 D-06 待确认项。
|
||
|
||
##### ANA-01/ANA-02 统计
|
||
|
||
`GET /risk/analytics/overview?from=2026-08-01&to=2026-08-31&deptId=D-OPS` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"period": { "from": "2026-08-01", "to": "2026-08-31" },
|
||
"metrics": {
|
||
"importedCount": 103,
|
||
"processingCount": 34,
|
||
"closedCount": 69,
|
||
"overdueCount": 2,
|
||
"primaryCount": 61,
|
||
"assistCount": 42
|
||
},
|
||
"generatedAt": "2026-08-13T18:00:00+08:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
`GET /risk/analytics/closed-orders?pageNum=1&pageSize=20&from=2026-08-01&to=2026-08-31` 返回 `TableDataInfo`，`rows` 使用 WO-01 工单摘要并增加 `closedAt`、`durationMinutes`、`overdue`。指标正式口径仍需关闭 D-07 后确定。
|
||
|
||
##### JOB-01 异步任务状态
|
||
|
||
`GET /risk/jobs/{jobId}` 无 body。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"jobId": "JOB-RPT-001",
|
||
"jobType": "REPORT_GENERATION",
|
||
"status": "SUCCEEDED",
|
||
"progress": 100,
|
||
"createdAt": "2026-08-13T17:00:00+08:00",
|
||
"finishedAt": "2026-08-13T17:00:08+08:00",
|
||
"result": { "reportId": "RPT-001", "fileId": "FILE-RPT-001", "downloadable": true },
|
||
"error": null
|
||
}
|
||
}
|
||
```
|
||
|
||
任务状态建议为 `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED`、`CANCELLED`。前端轮询间隔建议不小于 1 秒，并在完成或失败后停止轮询。
|
||
|
||
### 8.12 联调枚举与字段规则
|
||
|
||
| 业务字段 | 编码 | 中文显示 |
|
||
| --- | --- | --- |
|
||
| responsibilityType | `PRIMARY` / `ASSIST` | 主责 / 协查 |
|
||
| reviewResult | `APPROVED` / `REJECTED` | 同意 / 不同意 |
|
||
| callbackResult | `AGREE` / `DISAGREE_OR_CUSTOMER_REQUEST` | 同意 / 不同意或客户主动要求 |
|
||
| dispatchMode | `MANUAL` / `SMART` | 人工派工 / 智能建议后确认 |
|
||
| rowStatus | `VALID` / `DUPLICATE` / `INVALID` | 有效 / 重复 / 错误 |
|
||
| filePurpose | `IMPORT_SOURCE` / `RECORDING` / `PRELIMINARY_ATTACHMENT` / `RESPONSE_LETTER` / `DELIVERY_PROOF` / `REPORT_OUTPUT` / `DELIVERABLE` | 导入原件 / 录音 / 初查附件 / 答复书 / 送达凭证 / 报告输出 / 成果物 |
|
||
|
||
联调必须遵守以下规则：
|
||
|
||
1. 前端提交稳定编码，展示使用后端返回的中文名称或字典，不提交中文作为枚举值。
|
||
2. 所有时间使用带时区的 ISO 8601，例如 `2026-08-13T16:00:00+08:00`；纯日期使用 `YYYY-MM-DD`。
|
||
3. 金额以最小货币单位整数传输；当前原型没有金额字段，未来新增时不得使用浮点数。
|
||
4. 空数组使用 `[]`，无值对象使用 `null`；不得混用空字符串表达 `null`。
|
||
5. ID 一律按字符串处理，前端不得转换为 JavaScript `number` 后再传回。
|
||
6. 手机号、地址、录音和附件是否返回完整数据由服务端权限决定；前端不得依据掩码值发起写操作。
|
||
7. 前端只能提交当前详情响应中的 `version`；收到 `RISK-4090` 后重新获取详情，不自动覆盖。
|
||
8. 写接口成功后以响应中的 `currentStage`、`nextTasks` 和最新版本为准，不按按钮名称本地推断流程。
|
||
9. `PRIMARY` 的全面调查提交依赖首联和全部初查；`ASSIST` 只依赖全部初查。该判断必须以后端 `submitReady` 为权威。
|
||
10. 业务部主任审核请求不携带目标环节；后端依据持久化责任类型决定进入回访或调查报告。
|
||
11. 报告“确认生成”和“下载”是两个动作；生成接口使用幂等键，下载接口不得推进任务状态。
|
||
12. 文件先上传取得 `fileId`，业务提交再绑定；业务提交失败时文件保持临时状态并由后台清理。
|
||
|
||
## 9. 后端业务与技术约束
|
||
|
||
### 9.1 状态与权限约束
|
||
|
||
1. 每个写接口同时校验：用户权限、数据范围、任务所有权、任务状态、工单当前环节和数据版本。
|
||
2. 状态只允许按定义的状态机迁移；跳步、重复提交、对已完成任务再次提交均拒绝。
|
||
3. 驳回必须指定目标环节并新建返工任务，旧任务和旧调查版本保持不可变。
|
||
4. 并行初查使用任务集合判断完成，不能以工单上的单一“调查状态”覆盖多个部门结果。
|
||
5. 派工完成后即创建或开放服务监督员全面调查任务，允许编辑和保存草稿；是否允许提交由服务端根据 `responsibilityType` 及前置任务完成情况实时计算。
|
||
6. 业务部主任审核通过后必须读取派工阶段持久化的主责/协查判定：主责创建回访任务，协查创建调查报告任务，两个分支不得同时创建。
|
||
7. 主责/协查切换如已生成任务，必须撤销旧任务并记录原因；禁止静默修改。
|
||
8. 已办结工单默认只读；重新开启需独立权限、原因和审计事件。
|
||
|
||
### 9.2 幂等、并发与事务
|
||
|
||
- 确认导入、派工、提交、审核、办结必须支持幂等键，重复请求返回同一业务结果。
|
||
- 工单、任务、调查版本和配置均使用乐观锁版本号；版本冲突返回明确错误，提示用户刷新。
|
||
- “派工记录 + 多个任务创建 + 流程状态更新 + 审计事件”必须处于同一事务。
|
||
- “审核结果 + 当前任务完成 + 下游任务创建/返工任务创建 + 工单状态更新”必须处于同一事务。
|
||
- 文件上传与业务提交分两阶段处理：先上传临时文件，业务提交成功后绑定；定期清理超时未绑定文件。
|
||
- 异步导入和智能报告生成不能在 HTTP 请求中长时间阻塞，应使用任务状态查询，并保证重复消费幂等。
|
||
|
||
### 9.3 导入约束
|
||
|
||
1. 文件扩展名和实际 MIME/内容类型必须同时校验，禁止只看后缀。
|
||
2. 导入模板应带版本；字段缺失、类型错误、枚举无效、日期非法、编号重复必须形成行级错误。
|
||
3. 预览不写入正式工单；确认导入必须绑定原预览文件摘要和 previewToken。
|
||
4. 批次号唯一性、12398 工单编号重复处理策略需确认：拒绝、覆盖、忽略或形成新版本。
|
||
5. 部分成功策略需确认。建议默认“整批校验、有效行可确认”，确认结果保留失败行，不允许悄然丢弃。
|
||
6. 原始文件、解析版本、操作人和导入结果必须可追溯。
|
||
|
||
### 9.4 表单校验约束
|
||
|
||
- 所有文本字段设置长度上限并进行服务端校验；富文本需消毒，防止脚本注入。
|
||
- 电话号码保留业务允许的字符，但标准化后再用于查询；模糊查询需防止全表扫描。
|
||
- 日期不得明显晚于当前业务允许时间；首联、调查、审核、回访时间应满足流程先后顺序。
|
||
- 主责必须选择首联部门；协查不得生成首联任务；初查部门至少 1 个且不得重复。
|
||
- 调查草稿可在前置任务完成前保存；调查提交时，主责必须校验首联及全部初查完成，协查必须校验全部初查完成。
|
||
- 业务部主任审核通过时，主责必须进入回访分支，协查必须直接进入调查报告分支。
|
||
- 审核不同意时驳回理由必填；同意时不得携带会误导流程的驳回理由。
|
||
- 回访结果为“不同意或客户主动要求”时，答复书和送达凭证均为强制附件；“同意”分支不得被错误阻塞。
|
||
- 报告确认必须锁定所依据的调查版本；主责还必须锁定回访版本，协查不得伪造或要求回访版本。
|
||
- 报告生成与下载应分离：确认生成属于幂等写操作，重复下载属于受权读操作，不得因重复下载重复推进流程。
|
||
- 办结前必须校验不存在未完成的有效任务，报告和成果物满足配置要求。
|
||
|
||
### 9.5 文件与敏感数据
|
||
|
||
- 附件存储使用 fileId，不在业务表保存本地路径或公开 URL。
|
||
- 下载/播放每次鉴权；链接短期有效，禁止通过猜测 fileId 越权访问。
|
||
- 文件执行病毒/恶意内容扫描，限制类型、大小、数量和总容量；具体阈值待安全评审。
|
||
- 客户姓名、电话、地址、录音、转译文本、答复书和送达凭证按敏感等级控制，日志中脱敏。
|
||
- 导出和批量下载属于独立权限并记录审计；原型未展示导出入口，未经确认不实现。
|
||
|
||
### 9.6 时限、规则和审计
|
||
|
||
- 时限以流程配置版本计算，已开始实例是否随新配置变化必须明确；建议锁定启动时版本。
|
||
- 暂停、节假日、退回返工、并行任务的计时方式需业务确认。
|
||
- 智能派工只产生可解释建议，主管确认后才创建任务；必须记录输入摘要、规则版本、建议和人工调整。
|
||
- 配置发布需要高权限、二次确认、变更原因、生效时间和回滚能力。
|
||
- 审计事件至少记录 actor、角色、部门、动作、对象、前后状态、业务版本、requestId、IP、时间和结果。
|
||
|
||
### 9.7 错误码建议
|
||
|
||
| 错误码 | 含义 |
|
||
| --- | --- |
|
||
| `RISK-4001` | 请求字段校验失败 |
|
||
| `RISK-4002` | 枚举或字典值无效 |
|
||
| `RISK-4010` | 登录失效或令牌无效 |
|
||
| `RISK-4030` | 无菜单/操作权限 |
|
||
| `RISK-4031` | 超出数据范围或任务不属于当前用户 |
|
||
| `RISK-4040` | 工单、任务或文件不存在 |
|
||
| `RISK-4090` | 数据版本冲突 |
|
||
| `RISK-4091` | 当前状态不允许该操作 |
|
||
| `RISK-4092` | 幂等请求参数与首次请求不一致 |
|
||
| `RISK-4220` | 前置任务尚未全部完成 |
|
||
| `RISK-4221` | 条件必填附件缺失 |
|
||
| `RISK-4222` | 导入批次或工单编号重复 |
|
||
| `RISK-4290` | 请求过于频繁 |
|
||
| `RISK-5001` | 异步任务处理失败 |
|
||
|
||
## 10. 非功能需求
|
||
|
||
| 维度 | 需求建议 |
|
||
| --- | --- |
|
||
| 可用性 | 所有提交操作给出明确成功/失败反馈；长表单提供草稿和离开提醒 |
|
||
| 性能 | 普通分页查询在约定数据量下稳定响应；录音、附件和统计使用独立加载，不阻塞基础详情 |
|
||
| 可扩展性 | 流程环节、部门类型、事件分类和规则使用配置/字典，不写死角色名称 |
|
||
| 可观测性 | 请求链路、异步任务、状态迁移和外部存储均可追踪；requestId 贯穿日志与审计 |
|
||
| 安全 | 认证、最小权限、敏感字段脱敏、文件扫描、下载鉴权、防重放和输入消毒 |
|
||
| 可恢复性 | 导入和异步任务可重试；配置可回滚；关键写操作可根据审计恢复业务事实 |
|
||
| 兼容性 | 保持已有 Bearer Token、用户/部门接口及通用返回结构，变更需版本化 |
|
||
| 无障碍/易用性 | 表单标签、错误提示和键盘焦点明确；状态不只依赖颜色表达 |
|
||
|
||
## 11. 原型问题、冲突与待确认事项
|
||
|
||
### 11.1 高优先级业务决策
|
||
|
||
| 编号 | 问题 | 影响 | 建议决策方向 |
|
||
| --- | --- | --- | --- |
|
||
| D-01 | 派工完成后是否允许服务监督主管变更主责/协查判定 | 可能导致已生成的首联、初查、调查或回访任务失效 | 建议默认禁止；如业务必须支持，应限定时点并采用撤销旧任务、重新派工和全量审计 |
|
||
| D-02 | 全面调查的 1-13 与 1-21 字段范围不同 | 影响动态表单和必填规则 | 明确按业务类型/事件类型的适用条件 |
|
||
| D-03 | 1-4 与 1-18 审核弹窗均出现“回访分派”，但主流程只允许业务部主任通过后按责任类型分支 | 可能重复选择回访部门，或让协查错误进入回访 | 明确回访承接部门在哪一级审核生效；协查审核界面必须隐藏或禁用回访分派 |
|
||
| D-04 | 班组回访表单缺失，只有分派和结果页 | 无法区分执行回访与监督员结果填报 | 明确两个环节是否合并及各自字段 |
|
||
| D-05 | 调查报告已改为“确认下载”，但报告模板、文件格式、签章、重生成和历史版本规则未展示 | 无法确定报告生成与下载接口契约 | 明确模板、输出格式、生成失败处理、版本保留和重新下载规则 |
|
||
| D-06 | 智能派工规则配置页为空 | 无法定义规则数据结构 | 补充条件、优先级、冲突、试算、发布和回滚需求 |
|
||
| D-07 | 统计分析页为空 | 无法定义指标和接口 | 明确指标、口径、维度、权限和刷新频率 |
|
||
| D-08 | 重复工单和部分导入失败策略未说明 | 影响数据一致性 | 确认唯一键、覆盖/忽略/拒绝策略 |
|
||
| D-09 | 状态仅出现待分派/处理中/已结束，与实际 12 步不匹配 | 容易形成非法状态跃迁 | 采用生命周期 + 任务环节双层状态 |
|
||
| D-10 | 流程时限只展示分钟，未说明工作日、暂停和驳回重算 | 影响 SLA | 明确日历、起止点、暂停和重算规则 |
|
||
|
||
### 11.2 原型一致性问题
|
||
|
||
- “智能运营团队”与页头“运营智能团队”名称不一致。
|
||
- 总值班经理工单查询页页头错误显示“运营智能团队”。
|
||
- 监督员待办统计出现“成果无输出”，疑似应为“成果物输出”。
|
||
- 服务监督主管和业务部主任审核弹窗均出现回访分派字段，与“业务部主任审核通过后再按主责/协查分支”的流程规则存在职责重叠。
|
||
- 1-14/1-15 调查报告页面已经区分不同意与同意状态，但报告模板、生成进度、失败重试和历史版本未展示。
|
||
- 1-16 成果物输出继续复用大量调查/回访信息，专属成果物类型和办结清单仍不明确。
|
||
- 最新原型将回访结果展示为“同意/不同意或客户主动要求”，旧文档或流程中如仍使用“满意/不满意”应统一替换。
|
||
- “客户所在地区(省)”和“省份”同时存在，需明确一个是原始文本、一个是标准编码，还是重复字段。
|
||
- “工单状态”和“工单环节”在部分列表列中混用，必须拆分定义。
|
||
|
||
## 12. 验收建议与追踪矩阵
|
||
|
||
### 12.1 关键业务验收场景
|
||
|
||
1. 有效文件预览后确认导入，生成批次、工单和完整审计记录；重复确认不重复建单。
|
||
2. 含错误行的文件展示准确行号和原因，未确认前不写正式工单。
|
||
3. 服务监督主管判定主责并派工后，系统生成 1 个首联任务、N 个初查任务，并立即向指定服务监督员开放全面调查填报；服务监督员可先行填写和保存草稿。
|
||
4. 服务监督主管判定协查并派工后，系统只生成 N 个初查任务，不生成首联任务，同时立即向指定服务监督员开放全面调查填报。
|
||
5. 主责任一首联或初查任务未完成时、协查任一初查任务未完成时，全面调查均只能编辑/保存草稿，不能提交。
|
||
6. 服务监督主管审核或业务部主任审核驳回后生成返工任务，历史调查和审核记录仍可查看。
|
||
7. 业务部主任审核通过主责工单后生成回访分支任务；审核通过协查工单后不生成回访任务，直接生成调查报告任务。
|
||
8. 无任务所有权的用户即使直接调用接口也不能办理。
|
||
9. 两人同时操作同一任务时，后提交者收到版本冲突，不覆盖先提交结果。
|
||
10. 回访选择“不同意或客户主动要求”但缺少任一必需附件时不能提交；“同意”分支无需附件。
|
||
11. 协查报告上下文不要求首联或回访数据；主责报告必须引用已完成的回访版本。
|
||
12. 报告确认生成重复请求只产生一个业务版本；报告生成完成后可重复受权下载，不重复推进流程。
|
||
13. 已办结前存在未完成任务时拒绝办结；成功办结后普通用户不能再修改。
|
||
14. 修改时限或派工规则产生新版本，不篡改既有流程实例的历史计算结果。
|
||
15. 手机号、地址、录音和附件在无权限用户的列表、详情、日志和下载接口中均不可泄露。
|
||
16. 各待办统计卡片数量与同条件列表总数一致。
|
||
|
||
### 12.2 需求追踪
|
||
|
||
| 需求域 | 原型证据 | 主要接口 | 主要约束 |
|
||
| --- | --- | --- | --- |
|
||
| 登录 | 1-1 | 认证接口 | 验证码、Bearer Token |
|
||
| 导入 | 1-2、1-3、1-41 | IMP-01～07 | 预览隔离、幂等、行级错误 |
|
||
| 查询 | 1-34～1-40 | WO-01～06 | 数据权限、分页、脱敏 |
|
||
| 派工 | 1-10～1-12 | DSP-01～03 | 服务监督主管判定主责/协查、单选/多选、事务 |
|
||
| 首联 | 1-26、1-30、1-32、1-33 | DSP-04、ACT-02 | 仅主责、本部门候选、任务所有权 |
|
||
| 初查 | 1-23～1-25、1-28、1-29 | ACT-03 | 多部门并行任务全部完成 |
|
||
| 全面调查 | 1-13、1-21、1-22 | ACT-04、ACT-05 | 先行填报、动态字段、版本化、分支前置条件 |
|
||
| 主管审核 | 1-4、1-5、1-9 | ACT-06 | 驳回理由、不可覆盖历史 |
|
||
| 业务审核 | 1-18、1-19、1-27 | ACT-07 | 按持久化责任类型创建唯一后续分支 |
|
||
| 回访 | 1-17、1-20、1-31、1-33 | DSP-04/05、ACT-08/09、FILE | 仅主责、条件附件、敏感信息 |
|
||
| 报告/成果物 | 1-14～1-16 | ACT-10～14 | 数据版本快照、确认生成、受权下载、办结校验 |
|
||
| 配置/统计 | 1-6～1-8 | CFG、ANA | 版本发布、指标口径待补齐 |
|
||
|
||
## 13. 后续交付建议
|
||
|
||
在进入后端开发前，建议按以下顺序完成需求基线：
|
||
|
||
1. 业务评审本报告第 6、7、11 节，先关闭 D-01～D-10。
|
||
2. 设计人员统一两级审核中的回访分派职责，并补齐班组回访、报告生成状态、成果物清单、智能规则和统计分析页面。
|
||
3. 将字段字典固化为数据模型与枚举表，将状态模型固化为状态迁移矩阵。
|
||
4. 基于第 8 节生成 OpenAPI 3.1，补充请求/响应 Schema、权限编码和错误码。
|
||
5. 用第 12.1 节场景形成接口验收测试和流程集成测试。
|
||
|
||
本稿可作为需求评审和接口设计的输入，但在高优先级待确认项关闭前，不应直接据此创建数据库表或固化流程代码。
|