交开投数智建管平台

主题

运营对接管理 · 详细设计文档 ​

文档版本：0.10 ｜ 最近核对日期：2026-09-26

文档控制 ​

项目内容
模块名称运营对接管理
编写日期2026-09-26
关联文档需求分析、概要设计、数据库设计、测试报告

1. 页面、路由与实现组成 ​

页面范围按需求分析执行。运营对接管理下有问题清单及闭环、三权移交两个台账，以及由流程工作台进入的固定办理页；不另设业务详情或独立审批中心。

页面路由主要组件
问题清单及闭环台账、表单/operationDock/problemCloseLoopsrc/views/business/operationDock/problemCloseLoop/index.vue、components/ProblemCloseLoopForm.vue
问题清单及闭环流程办理/operationDock/problemCloseLoop/flowFormsrc/views/business/operationDock/problemCloseLoop/flowForm.vue
三权移交台账、表单/operationDock/threeRightsTransfersrc/views/business/operationDock/threeRightsTransfer/index.vue、components/ThreeRightsTransferForm.vue
三权移交流程办理/operationDock/threeRightsTransfer/flowFormsrc/views/business/operationDock/threeRightsTransfer/flowForm.vue

前端 API 类型位于 src/api/business/operationDock/。后端采用 Controller → Service → Mapper/Entity 分层，业务代码位于 com.bokun.business.operationdock，固定表单流程复用 OperationDockWorkflowHelper 与 Warm-Flow。

2. 接口、分页与权限 ​

两个列表接口返回 PageResult<VO>；前端读 rows 和 total，不把分页结果当数组。ID 在前端保留 string | number 原始值，后端 Long 由项目 JSON 映射处理。

三权移交按工点共享语义检查同一线路下整线授权，或至少一个当前有效标段×工点组合包含目标工点；候选、列表、详情和写入使用同一判断。问题闭环列表、详情和导出按跨部门台账基线全量可读；其线路→工点候选按共享工点授权过滤，新增/修改服务端校验选定的线路与工点归属及授权，不能通过直接构造请求绕过候选范围。

操作问题清单及闭环三权移交权限动作
分页查询GET /business/operationDock/problemCloseLoop/listGET /business/operationDock/threeRightsTransfer/listlist
详情读取GET .../problemCloseLoop/{id}GET .../threeRightsTransfer/{id}query
暂存新增/修改POST / PUT 各自业务路径POST / PUT 各自业务路径add / edit
提交审批POST .../problemCloseLoop/submitPOST .../threeRightsTransfer/submitsubmit
批量删除DELETE .../{ids}DELETE .../{ids}remove
流程信息GET .../problemCloseLoop/process-info/{id}GET .../threeRightsTransfer/process-info/{id}query
导出POST .../problemCloseLoop/exportPOST .../threeRightsTransfer/exportexport

控制器的 @SaCheckPermission 与对应页面的 v-hasPermi 使用三段式权限码 operationDock:<resource>:<action>。服务端另校验记录创建者或 manage 权限、记录状态和流程任务归属；前端按钮显隐不构成授权。列表及导出沿用规划管理已确认的同级基线，具备页面查询权限即可查询模块全部记录，不按单位隔离。

3. 业务写入与状态回写 ​

3.1 问题清单及闭环 ​

  • 暂存新增写入 draft，允许尚未完成提交校验；编辑仅允许草稿或退回状态。
  • 问题描述与处理结果上限各为 600 字，接收区段（域）上限为 60 字；Service 在新增、修改及提交共用的表单映射入口检查，不能只依赖 Controller 的 Bean Validation 或页面 maxlength。草稿可缺少提交必填项，但长度约束仍生效。
  • 提交在事务中校验项目、项目关联线路、处理部门、发起人、问题描述、处理结果、三名必选审批人及两组附件；上报时间首次提交时写入，退回重提保留原时间。
  • 流程变量由后端从已校验的记录构造：responsibleDeptLeaderId、initiatingDeptLeaderId、responsibleDeptHandlerId、responsibleDeptDeputyId 和 hasDeputy。未选择副部长时注入 hasDeputy=0，条件网关直接结束；已选择时进入末节点。
  • 退回目标固定为 submit（申请人）。流程节点配置固定目标，办理页只展示该目标；共享流程服务校验请求目标与节点配置一致，不接受伪造的历史节点编码。
  • draft → waiting → back → waiting → finish。审批历史由 Warm-Flow 保留；业务表监听流程事件更新状态和实例标识。

3.2 三权移交 ​

  • 暂存写入 draft；提交必须校验接收线路为工程树 LINE 节点、区段（域）、移交类型、接收时间、填报人、单选审批人及两组附件。
  • 提交流程变量为表单指定的 approverId，由一个“审批人”节点办理。退回目标按规划管理同级流程基线固定为申请人，发起人可修改并沿原流程实例重提；此退回路径尚无端到端验证。
  • draft → waiting → back → waiting → finish。流程事件监听负责将 Warm-Flow 结果写回业务状态；记录只有处于 finish 时才算生效。
  • 审批中的记录仍可通过三权台账查询；业务服务禁止修改或删除审批中的记录。台账在审批完成前不显示审核状态列（列表展示方式按平台同级台账确定），台账可见性不代表记录已生效。

3.3 事务、重提与异常 ​

新增、修改、附件关联、提交及流程启动由业务 Service 的事务覆盖。流程启动失败回滚业务数据和附件引用。退回重提时，OperationDockWorkflowHelper 通过当前登录人查找原业务当前任务，再完成该任务，不另起一个活动流程实例；找不到本人任务时拒绝重提。控制器提交接口使用 @RepeatSubmit，服务端也校验业务状态和已有流程。

4. 流程定义与图形规范 ​

流程图遵循流程图编排规范：设计器选 CLASSICS；办理卡片按 100 × 80 计算四向锚点；边用正交折线，不画 REJECT 退回线；普通 PASS 边无标签，仅条件分支显示短标签。

流程JSON 与发布版本节点顺序与关键配置
问题清单及闭环digital-construction-modules/digital-construction-workflow/src/main/resources/flow/operation-dock/operation_dock_problem.json；V5；定义 ID 2103716067758149633开始 → 申请人 → 责任部门部长 → 发起部门部长 → 责任部门经办人 → 条件网关 →（已选）责任部门副部长 /（未选）结束 → 结束。审批节点固定退回 submit。
三权移交digital-construction-modules/digital-construction-workflow/src/main/resources/flow/operation-dock/operation_dock_transfer.json；V3；定义 ID 2103717320710000642开始 → 申请人 → 审批人 → 结束；审批人取自表单单选值，并固定退回 submit。

两份定义均使用 PASS 主线与边条件，不含 REJECT 连线；问题流程的选填副部长分支在同一局部区域展开。静态坐标按节点四向锚点连接并使用水平、垂直折点；V5/V3 已在流程设计器查看，当前布局无边交叉、穿节点或边标签遮挡。定义发布后，真实办理页分别显示 V5 和 V3。

5. 附件与字段持久化 ​

附件统一保存 OSS 对象引用，不复制文件实体。主业务与附件关联表分别为 BIZ_OPERATION_DOCK_PROBLEM、BIZ_OPERATION_DOCK_PROBLEM_FILE、BIZ_OPERATION_DOCK_TRANSFER、BIZ_OPERATION_DOCK_TRANSFER_FILE。附件组和顺序由 file_group 与 sort_no 保存；问题记录的组为 PROBLEM、RESULT，三权记录的组为 TRANSFER、AGREEMENT。

浏览器上传组件按最大 50MB、格式 doc/docx/xls/xlsx/ppt/pptx/txt/pdf 校验，超限上传被拒绝并提示，页面不常驻展示大小与格式提示；后端通过 OSS 查验文件存在，并按小写后缀校验格式，兼容 OSS 后缀带前导点的返回值。提交时后端再次验证两组附件均非空。实际字段、物理类型、空值、默认值和索引以数据库设计的 MCP 回读矩阵为准。

6. 接口异常与边界 ​

场景服务端处理
必填业务字段或附件缺失抛出业务异常，事务内不产生部分提交
线路不存在或不是 LINE 节点拒绝保存或提交
OSS 文件标识格式无效、文件不存在或后缀不支持拒绝关联并提示对应附件组
非创建人且无 manage 权限的人员编辑/删除拒绝操作
修改或删除状态不允许的记录草稿或退回以外的记录拒绝修改；仅草稿可删除
不是当前办理人或请求退回到非固定节点流程服务拒绝处理
流程启动失败回滚业务提交与附件关联

7. 需求追踪与验证状态 ​

需求编号、用户答复和同级基线推断只在需求分析维护。流程、状态、权限、分页、文件和事务的真实验证记录及尚未覆盖范围只在测试报告维护。当前测试由具备模块访问权限的开发账号执行，其他角色的权限负向、三权退回、导出和跨单位可见范围尚未通过真实角色切换验证。