主题
工程手续办理 · 详细设计文档
文档版本：1.00 ｜ 最近核对日期：2026-10-15
进展说明：土建年度计划及五阶段手续正式链路已完成真实闭环；运行态土建
V3、机电V2已导入，权限、空条件预路由、附件和页面回归已核验。本轮（2026-10-15）完成录单入口改造与台账对齐：年度计划新增拆分为“新增年度计划（土建）/（机电）”两个入口，土建按“线路-标段-工点”选择工点并带入责任标段（服务端校验管辖关系），机电按“线路-标段”选择标段（标段即办理对象）；年度计划查重按“工点+年度”“标段+年度”区分；推进总台账/导出首列“工点/专业”、完成时间按“已完成/计划完成日期”展示；台账、施工许可证 1:N 同步与权限适配机电标段级（无工点）可见判定。
文档控制
| 项目 | 内容 |
|---|---|
| 模块名称 | 工程手续办理 / v0.27 |
| 关联需求分析 | 需求分析 |
| 关联概要设计 | 概要设计 |
| 关联数据库设计 | 数据库设计 |
| 关联代码版本 | 本次工作区包含工作台体验级重构、办理清单全景面板、单元测试及 1920×911 视口紧凑排版调优 |
| 编写/核对人 | 待补充 |
| 待确认事项 | 退回重办分支和新建可选单位工程不足的浏览器场景待补测；表单字段按原型表达的业务要求实现，组织岗位固定映射仍按实际运行需要选择 |
1. 页面、路由与交互
以下为本模块的路由和资源建设基线。菜单、流程分类和权限沿用已建立的模块资源；两套流程定义已完成资源文件静态核对，运行态最新版本为土建 V3、机电 V2，均已在流程设计器导入且导入结果确认无问题；模块层级和路由职责不再另行拆分。
| 页面/组件 | 路由建议 | 进入条件 | 可见角色 | 主要操作 | 状态/异常反馈 |
|---|---|---|---|---|---|
| 年度计划下达 | /engineeringProcedures/annualPlan | 一级菜单“工程手续办理” | 经办、查看 | 查询、新增（土建/机电两个入口）、编辑、提交、查看流程 | 草稿/审批中/已完成；提交失败保留输入 |
| 规划方案审查意见 | /engineeringProcedures/planningOpinion | 一级菜单“工程手续办理” | 经办、办理、查看 | 台账、查看、去办理、流程图 | 单位工程进度与审批状态分列 |
| 初步设计批复 | /engineeringProcedures/preliminaryDesign | 一级菜单“工程手续办理” | 经办、办理、查看 | 同上 | 同上 |
| 建设工程规划许可证 | /engineeringProcedures/constructionEngineeringPlanningPermit | 一级菜单“工程手续办理” | 经办、办理、查看 | 同上，含对应条件子手续 | 页面名称和相关节点名称按实际业务定义维护，不做全局改名 |
| 施工图审查合格书 | /engineeringProcedures/constructionDrawingReview | 一级菜单“工程手续办理” | 经办、办理、查看 | 同上 | 结果资料未完成时显示未完成 |
| 施工许可证 | /engineeringProcedures/constructionPermit | 一级菜单“工程手续办理” | 经办、办理、查看 | 同上 | 同上 |
| 手续办理推进总台账 | /engineeringProcedures/summary | 一级菜单“工程手续办理” | 管理、查看 | 筛选、查看来源、导出 | 不显示新增/编辑/提交 |
| 共用手续办理工作区 | /engineeringProcedures/flowForm（隐藏） | 当前流程任务 | 当前办理人、查看人 | 按单位工程办理、暂存、就绪诊断、条件决策、提交 | 顶部步骤向导条：年度计划只读 Tab + 主线步骤向导 Tab（土建 5/机电 2）+ 办理清单全景 Tab；当前任务/只读状态由服务端返回 |
1.1 菜单与流程资源
| 资源 | 建设内容 | 关联关系 |
|---|---|---|
| 一级菜单 | “工程手续办理” | 与“工程变更监管”同级 |
| 页面菜单 | 6 个办理/台账页面 + 1 个总台账页面 | 子菜单挂在工程手续办理下 |
| 隐藏菜单 | 共用手续办理工作区 | 由前六页和当前任务进入 |
| 流程分类 | “工程手续办理” | 分类 ID 2110000000000000800；与“工程变更监管”同级 |
| 土建流程定义 | 独立土建流程 | 编码 engineering_procedure_civil；运行态最新版本 V3，已导入且导入结果确认无问题；bidCategory=土建 时启动，生成 5 个实际手续阶段 |
| 机电流程定义 | 独立机电流程 | 编码 engineering_procedure_mep；运行态最新版本 V2，已导入且导入结果确认无问题；bidCategory=机电 时启动，生成 2 个实际手续阶段 |
| 旧流程兼容 | 历史公共流程 | 编码 engineering_procedure 仅兼容在途旧实例，不作为新年度计划的启动定义 |
菜单权限、流程分类和两套流程定义必须实际创建并可被接口引用；只在前端增加路由而不创建平台资源视为交付不完整。旧公共定义不得覆盖或删除，以保证在途实例兼容。
1.2 办理工作区布局与核心组件
- 顶部卡片与流线型步骤向导条（Workflow Stepper Header）：
- 顶部展示计划名称、流程版本、业务编号及返回动作，彻底移除弃用的“查看历史”按钮及轮次弹窗；
- 顶部 Tab 升级为流线型步骤向导条：
- 年度计划：只读 Tab（带出计划与各单位工程阶段计划日期，不办理）；
- 主线手续阶段：土建 5 个、机电 2 个，按 01~05 标注阶段序号；已通过阶段展示绿色
✓及“已办结”徽标；当前待办阶段带有主题色高亮与呼吸微动效（pulse-dot）； - 办理清单：独立全景功能 Tab，挂载
ProcedureChecklistPanel，可查阅五大主体责任要件协调清单及全景流程图； - 在 1920 宽屏视口下单行平铺，绝不折行；
- 单位工程选择吸顶栏与就绪诊断悬浮卡（Diagnosis Checklist Popover）：
- 单位工程选择栏在工作台滚动时固定吸顶，高度紧凑至
padding: 6px 12px;； - 各单位工程及节点卡片头部的状态徽标（已完成/就绪/未就绪）内嵌诊断小图标，悬停即可呼出诊断卡片：
- 实际完成日期：已填报（显示日期） / ❌ 未填报；
- 最终成果附件：已上传（显示数量） / ❌ 未上传；
- 前置子手续闭环：直行推进 / ✔ 已办结归档 / ⚠️ 阻断中（明确列出待办结的子手续名称）；
- 彻底消除填了进度却不知为何仍显示“未就绪”的黑盒感；
- 单位工程选择栏在工作台滚动时固定吸顶，高度紧凑至
- 条件协同决策指引卡片（Condition Decision Guide Card）：
- 替代原先隐蔽的
<el-select>小下拉框，升级为浅色微底卡片（condition-card）； - 顶部配备业务引导文案（说明何时选不需要、何时需启动子手续）；
- 核心决策采用分段胶囊按钮组（Segmented Radio）：
不需要（直行推进）与需要办理（启动子手续），只读模式展示语义化 Tag； - 选中“需要办理”时，卡片内自动联动展现子手续当前完成进展（
已办结/办理中）及证件资料锁定保护提示；
- 替代原先隐蔽的
- 进度跟踪与结果资料区域：
- 进度跟踪表：只读展示进度记录，附件列显示数量（大于 0 可点击打开只读查看框）；通过弹窗进行新增/编辑；
- 结果资料表单：紧凑优化表单项外边距（12px），textarea 设为 2 行自适应，有效压低纵向滚动深度；
- 视口 1920 × 911 紧凑排版：
- 针对 1080p 除去浏览器标签栏、书签栏、任务栏后的 911px 有效视口，进行严格垂直节奏压缩，横向滚动条完全为 0；
- 右侧审批时间线与全宽切换：
- 右侧固定展示审批时间线，支持一键折叠为专注全宽视图。
1.3 关键交互约束
- 未选择单位工程时不显示或不允许写入该单位工程的进度和结果；
- 土建年度计划工程候选使用
GET /business/engineering-tree/tree?maxLevel=site获取线路→标段→工点，机电候选使用maxLevel=bid获取线路→标段；返回树由工程基础服务按当前用户授权过滤。页面不自行拼全库主数据或绕过工程范围服务，授权变更后重新加载候选；共享树查询按可见线路/标段读取，避免逐候选重复查询授权。 - 年度计划下达的单位工程/标段选择器默认隐藏运营节点（含运营根节点），隐藏时把运营根下仍在建设的非运营下级提升到最近可见层级；工具栏提供「显示运营」开关（默认关闭），开关只切换显示层、不构成拒绝，服务端不按运营状态过滤或拒绝；选择层级随录单入口切换（土建“线路-标段-工点”只选工点并带入责任标段，机电“线路-标段”只选标段），责任标段与工点的管辖关系由服务端校验（口径见 R-EP-031/R-EP-050 与需求分析 8.3 变更记录）；
- 进度记录通过独立弹窗新增/编辑，表格只读并在附件列显示文件数量；有附件时数量为可访问的查看控件，打开只读附件查看框，框内使用禁用态
FileUpload；弹窗内使用现有文件上传能力； - 只读结果区直接渲染禁用态
FileUpload；文件名进入现有预览抽屉，下载沿用公共文件下载动作；只读查看不允许上传、删除、修改，也不改变业务附件引用；无附件时显示“—”； FileUpload通过自定义 multipart 请求上传，复用全局鉴权和ossExt，成功回调才写入ossId；请求失败时回收批次计数、关闭加载态并展示可理解的网络/服务提示，不生成空附件；附件列表不使用进入动画，并沿用上传项uid，回显查询时复用已有键值，避免临时项替换引起视觉抖动；- 切换到非当前阶段 Tab 时，表单、进度记录、条件判断、子手续和结果资料均为只读；
- 当前阶段 Tab 也必须由服务端确认当前节点属于该阶段且当前用户是办理人，前端不能单独决定可编辑状态；
- 办理人、审核人和候选岗位统一打开现有
digital-construction-ui/src/components/UserSelect/index.vue选择，不使用el-select等普通下拉框；该组件提供部门树、人员筛选、已选人员维护和多人选择。单人字段提交所选列表的第一名，多人候选字段提交完整用户 ID 列表，显示名称只作为展示值；年度计划首节点和流程动作面板沿用同一规则； - “保存”不改变流程节点和审批状态；
- “暂存”只保存当前单位工程/阶段的字段，不得把其他阶段 Tab 的内容一并提交；
- 同意时统一校验每个适用单位工程：条件子手续已闭环、实际完成日期和最终成果附件齐备；仅有进度记录不算完成；
- “同意”时服务端统一校验本节点全部适用单位工程；父节点存在待办条件时只暂缓待办子手续的单位工程，其余未填全会点名提示并阻止；
- 工程手续通过动作进入 Warm-Flow
GlobalListener.start后，服务端重新校验当前节点并根据数据库条件及子手续完成状态重算网关变量；只有仍有待办理子手续时条件变量才为1，前端提交的条件变量和ignore变量不能绕过业务校验或流程权限； - 节点提交后，当前节点的进度和结果记录只读；
- 流程进入下一阶段后，系统自动打开下一阶段 Tab，上一阶段保持只读；
- 当前条件选择“需要”后，对应子手续表单随即展开（子手续单位工程在建计划时已生成，切换决策不即时建记录、不调接口）；子手续未完成时父手续证件资料区置灰，但可把“需要”改回“不需要”直接跳过；子手续返回后可选择“不需要”结束该条件；再次办理通过流程退回，不再提供“需要再次”；首次默认“不需要”；
- 进度记录在当前节点未锁定前允许物理删除，删除后业务查询不再返回该记录；本模块只保存附件引用并在成果保存时校验
ossId存在，文件生命周期由平台文件服务负责，本模块不扩展清理策略； - 退回前面阶段时，退回目标阶段及其后续阶段的当前完成结果失效并进入待重办，旧进度和结果按轮次只读保留；阶段/阶段-单位工程切换新的
WORK_ROUND_NO，条件记录就地重置后重新保存，不新增条件历史行； - 第七页只能跳转到有权限的来源详情，不能通过汇总行直接修改来源数据。
- 审批动作的业务校验异常由
FlowActionPanel捕获并写入当前对话框错误区；对话框保持打开，流程不推进，避免只依赖全局消息或产生未处理 Promise 异常。 - 年度计划保存/更新时若传入首节点办理人，同步保存
NEXT_HANDLER_ID/NEXT_HANDLER_NAME快照；正式提交仍重新校验办理人有效、具备权限且符合流程要求。 - 待办入口的回退地址固定为
/task/taskWaiting；路由修正不改变待办接口和流程状态。
1.4 流程图资源编排
- 仓库导入资源文件
engineering_procedure_civil_v1.json与engineering_procedure_mep_v1.json分开维护；文件名中的基线编号不代表运行态定义版本，当前运行态以 Warm-Flow 为准：土建V3、机电V2；不能把阶段 Tab、流程图阶段标题或节点内两层操作误建成 Warm-Flow 节点； - 普通办理节点名称精简后每行最多 7 个中文字符、最多 3 行，使用
\n显式换行； - 节点坐标按中心点保存，连线从源节点四向锚点出发并进入目标节点四向锚点，中间点只走水平/垂直正交路径；串行链、分支和子手续位置尽量占满设计器画布；任意两条连线不得共享同一水平/垂直线段，不得交叉、重叠、穿过节点或压住文字，回父节点使用独立外圈通道；
- 不配置静态退回/回退边，使用 Warm-Flow 标准退回动作；子手续完成后回到父节点的 PASS 线是三处条件闭环所必需的业务线，保留该线不等于增加退回节点；
- 导入前静态校验节点、连线、条件和锚点，导入后在流程设计器检查分支标签、节点遮挡和线条交叉；已发布旧定义只保留兼容，不直接覆盖。
1.5 2026-09-14 正式链路验证补充
测试计划 EP-2026-9772154880 已按土建流程真实提交并完成规划方案审查、初步设计批复、建设工程规划许可证、施工图审查合格书和施工许可证五个实际阶段；每阶段结果均回读实际完成日期、成果附件和办理历史，最终 approvalStatus=finish、currentTaskId=null、活动待办为 0。缺少规划阶段计划完成日期时，接口按单位工程点名缺失项并阻止提交；流程办理不依赖前端伪造条件变量，Warm-Flow 可选网关无条件时由 CompletePrepareComponent 受限延后空条件异常，业务全局监听器重新计算条件并推进，其他流程异常继续抛出。退回重办和其他条件组合不因本次主链通过而视为已验收。
2. 接口契约
以下为本轮实现使用的 REST 契约；业务字段仍按原型表达的业务要求逐阶段扩展，两套独立流程共用同一工作区，通过 process-info 读取流程摘要。
| 接口职责 | 方法建议 | 调用方 | 权限 | 请求对象 | 响应对象 | 幂等/事务 |
|---|---|---|---|---|---|---|
| 查询年度计划列表 | GET | 年度计划页 | 查询 | 分页、年度、工程条件、状态 | 计划分页列表 | 只读 |
| 查询年度计划详情 | GET | 年度计划页/工作区 | 查询 | 计划 ID | 计划、单位工程、流程摘要 | 只读 |
| 保存年度计划草稿 | POST/PUT | 年度计划页 | 新增/编辑 | 计划字段、入口通道（TJ/JD）、工点 ID 列表（土建）或标段 ID 列表（机电）、推进单元备注、各阶段计划完成日期、首节点办理人 | 主单摘要 | 校验入口通道合法、选择对象与入口匹配、责任标段与工点存在管辖关系；草稿允许日期暂空；传入办理人时同步保存 ID/名称快照；事务、版本校验 |
| 提交年度计划 | POST | 年度计划页 | 提交 | 计划 ID、各推进单元阶段计划完成日期、首节点办理人/审核人/候选岗位 | 流程关联和状态 | 校验阶段日期完整、所选人员/岗位有效且有权限；按入口启动独立流程；幂等、事务 |
| 查询手续台账 | GET /business/engineeringProcedure/ledger?stageCode= | 5 个手续页 | 查询 | 年度、线路、标段、单位工程、施工单位、审核状态、stageCode | 仅返回当前阶段等于或已经经过 stageCode 的计划，并返回该节点的单位工程×手续台账行（含四色进度状态、办理人/部门、当前待办 id） | 只读 |
| 查询节点工作区 | GET | 共用工作区 | 流程查看 | 实例 ID、节点 ID、阶段、单位工程 ID | 按独立流程返回 6/3 个 Tab（含年度计划只读）状态、当前节点、单位工程、条件、进度、结果 | 只读 |
| 新增进度记录 | POST /business/engineeringProcedure/progress | 共用工作区 | 进度维护 | 单位工程、进度内容、完成日期/总体进度、是否重难卡点、附件 | 进度记录 | 事务；@RepeatSubmit 防重复插入 |
| 修改/删除进度记录 | PUT/DELETE | 共用工作区 | 进度维护 | 记录 ID、版本 | 最新记录/删除结果 | 版本校验；删除物理记录 |
| 保存条件决策 | PUT /business/engineeringProcedure/conditions/{id} | 共用工作区 | 条件维护 | 单位工程×条件×决策值（不需要/需要）批量 | 保存结果 | 随暂存/同意批量落库；就地更新决策，不累积轮次；切换本身不即时调用 |
| 保存阶段表单/结果 | PUT /business/engineeringProcedure/result | 共用工作区 | 阶段表单/结果维护 | 当前阶段、stageUnitId、计划/实际完成日期、备注、附件标识、expectedVersion、syncToAllUnits | 当前阶段摘要 | 计划完成日期以年度计划为只读来源；仅当前阶段可写。施工许可证 syncToAllUnits=true 时限同流程、同阶段、同办理节点的单位工程，逐一校验当前账号可见范围，按 ID 固定顺序 CAS 占用所有目标版本后统一写入；任一越权/版本冲突均事务回滚。false 时仅更新当前单位工程 |
| 同意/提交节点（先校验再推进） | POST /business/engineeringProcedure/validate-node/{id} + 流程动作 | 共用工作区 | 流程提交 | 实例、节点、下一办理人 | 只读校验通过后推进并返回流程状态和下一节点；离开节点时落库就绪单位工程的完成状态 | 幂等；未填全点名单位工程并阻止 |
| 查询总台账 | GET /ledger（不带 stageCode） | 第七页 | 查询 | 年度、线路、标段、单位工程、施工单位、审核状态 | 全部手续台账行，前端按推进单元透视成 8 手续列矩阵（首列“工点/专业”） | 只读；缺失标段快照按当前可见范围批量反查，仅唯一匹配回填；歧义记录留空，不选择任意候选 |
| 导出总台账 | POST /summary/export | 第七页 | 导出 | 年度、线路、标段、单位工程、施工单位、审核状态 | 按线路分 sheet 的 xlsx（两行合并表头、8 手续列 × 完成时间/进展情况；完成时间列已完成显示“已完成”、未完成显示计划完成日期）；页签名按 Excel 规则清理至不超过 31 个字符，并在同一工作簿内追加后缀保持唯一 | 只读导出 |
| 上传附件 | POST /resource/oss/upload | FileUpload | 结果/进度附件 | 浏览器 multipart/form-data 的 file，可选 ossExt，全局鉴权请求头 | 平台 OSS 响应（code、ossId、文件名、地址） | 成功才进入业务附件引用；HTTP/网络/超时/取消失败均回收上传批次并允许重试 |
| 只读附件详情 | 无新增业务接口；复用 FileUpload 内部按 ossId 查询文件详情 | 办理工作区 | 结果直接展示；进度数量点击查看 | 现有 attachmentRefs（逗号分隔 ossId） | 禁用态文件列表，支持既有预览/下载 | 只读查询或预览失败不写回业务数据、不开放编辑 |
所有写接口需要服务端补充：当前登录人、线路/单位工程范围、流程任务归属、状态、版本、必填字段、附件标识和数据权限校验。前端传入的名称、路径、办理人名称不能覆盖服务端根据 ID 生成的快照。
3. 状态与业务动作
| 当前状态 | 动作 | 允许角色 | 前置校验 | 数据变化 | 下一状态 | 失败处理 |
|---|---|---|---|---|---|---|
| 草稿 | 保存 | 计划经办人 | 所选推进单元未被其他同年度有效计划重复纳入；选择对象与入口匹配（土建=工点、机电=标段）；责任标段与工点存在管辖关系；具备对应工程范围权限 | 保存主单和推进单元快照 | 草稿 | 对象重复纳入（点名）、责任标段无管辖关系、标段未关联线路时不保存 |
| 草稿 | 提交 | 计划经办人 | 业务必填、至少一个推进单元、推进单元未被同年度其他计划重复纳入、选择对象与入口匹配、所选人员/岗位有效且有权限 | 按入口创建/关联对应流程实例 | 审批中 | 推进单元重复纳入（点名）、候选人无效或流程关联失败则回滚 |
| 审批中/当前任务 | 保存进度 | 当前办理人 | 节点、单位工程和版本有效 | 新增或修改进度记录 | 办理中 | 保留页面输入，返回冲突/校验信息 |
| 审批中/当前任务 | 删除进度 | 当前办理人 | 记录属于当前节点且未锁定 | 物理删除进度记录；附件引用不在本模块扩展生命周期处理 | 办理中 | 不影响其他记录；删除后不再出现在业务查询 |
| 审批中/当前任务 | 暂存 | 当前办理人 | 当前节点、单位工程和版本有效 | 保存结果/证件数据与条件决策（不标记完成、不推进） | 审批中 | 保留输入，返回校验信息 |
| 审批中/当前任务 | 同意（提交节点） | 当前办理人 | 只读统一校验：普通节点/条件已闭环父节点要求所有适用单位工程数据齐备（实际完成日期+成果附件）；父节点有待办条件时暂缓待办单位工程、其余须齐备 | 校验通过后调用平台流程推进；离开该节点时把数据就绪的单位工程落库为已完成并记完成时间（不提前锁定） | 下一节点审批中 | 未填全时点名单位工程并阻止 |
| 退回修改 | 修改并重提 | 退回接收人 | 退回规则和版本有效 | 目标阶段及后续阶段进入待重办，历史结果保留，沿原实例重提；年度计划阶段计划日期保持只读、不改 | 审批中 | 失败不覆盖历史记录 |
| 已完成/已终止 | 编辑或提交 | 无 | 终态禁止写入 | 无 | 不变 | 返回只读/终态错误 |
4. 权限与数据范围
| 资源/动作 | 菜单权限 | 按钮权限 | 接口权限 | 数据范围 | 越权结果 |
|---|---|---|---|---|---|
| 前六页查询 | 对应页面 | 查询 | 对应 list/get | 线路/单位工程范围 + 业务授权 | 403 或空结果，按平台约定 |
| 计划新增/编辑 | 年度计划页 | add/edit | save | 可选单位工程必须在授权线路/单位工程范围 | 拒绝保存 |
| 进度维护 | 对应手续页 | progress-edit | progress write | 当前任务 + 当前阶段 + 当前单位工程 | 拒绝写入 |
| 进度查看 | 对应手续页/工作区 | progress-read | progress read | 有权限的流程实例、阶段和单位工程 | 拒绝读取 |
| 条件确认 | 对应手续页 | condition-edit | condition write | 当前任务 | 拒绝修改 |
| 阶段表单/结果资料维护 | 对应手续页 | stage-edit/result-edit | stage/result write | 当前任务 + 当前阶段 + 当前单位工程 | 拒绝写入 |
| 节点提交 | 对应手续页 | submit | process submit | 当前办理人 + 当前节点 | 拒绝推进 |
| 总台账导出 | 总台账页 | export | summary export | 过滤后的授权数据 | 拒绝导出 |
流程任务归属和线路/单位工程数据范围必须同时满足。管理员把人员加入流程任务或下一节点办理人列表，不等于自动授予工程树 SITE 范围；缺少范围时详情/写接口必须拒绝，补授范围后再重新加载待办。
5. 异常、事务与并发
| 场景 | 检测位置 | 用户提示 | 回滚/补偿 | 日志与告警 | 测试用例 |
|---|---|---|---|---|---|
| 同意时单位工程未填全 | 服务端 validateNode（同意前） | “以下单位工程尚未填写完整：X、Y” | 不推进流程 | 记录实例、节点和清单 | TC-EP-002 |
| 子手续未完成 | 服务端单位工程完成/节点提交 | “请先完成对应条件子手续” | 不标记完成 | 记录父子关联 | TC-EP-006 |
| 旧版本覆盖/并发写 | saveResult 要求 expectedVersion，按 ID+当前轮次+旧版本原子 CAS 占用，未命中即回滚 | “数据已被其他用户修改，请刷新” | 拒绝保存、不产生重复当前成果 | 记录冲突上下文 | TC-EP-011 |
| 进度重复提交 | /business/engineeringProcedure/progress @RepeatSubmit | 提示重复提交 | 不重复插入进度行 | — | TC-EP-003 |
| 历史轮次进度被改写/删除 | updateProgress/deleteProgress 校验记录 WORK_ROUND_NO==当前轮次 | 拒绝 | 保护退回前的历史进度 | 记录 | TC-EP-012 |
| 重复提交 | 服务端幂等校验 | 返回已处理结果或当前状态 | 不重复创建任务 | 记录幂等命中 | TC-EP-007 |
| 文件服务失败 | 文件关联服务 | “附件上传失败，请重试” | 不保存失效附件 | 记录文件标识和错误 | TC-EP-010 |
| 附件引用失效/伪造 | saveResult 经 OssService.selectByIds 校验 ossId 全部存在 | “存在无效或已失效的附件引用，请重新上传” | 拒绝保存成果 | 记录 ossId | TC-EP-010 |
| 越权访问无权限单位工程计划 | 列表/台账按 EngineeringDataAccessHelper 的有效整线授权或标段×工点组合过滤；详情/写操作逐对象校验 | “无权访问该单位工程”或空结果 | 不返回越权数据 | 记录 | TC-EP-009 |
| 流程推进失败 | 业务事务边界 | “流程提交失败，业务数据未推进” | 回滚节点提交状态 | 记录流程实例和异常 | TC-EP-007 |
| 聚合来源查询失败 | 总台账服务 | “汇总失败，请稍后重试” | 不返回伪造未开始 | 告警并记录条件 | TC-EP-008 |
| 所属标段类型异常 | 年度计划选择/保存/提交 | “基础数据异常，请联系工程基础管理员” | 不写入异常单位工程，不启动流程 | 记录单位工程、标段和原始类型值 | TC-EP-019 |
| 单位工程重复纳入同年度计划 | 年度计划保存/提交（按“单位工程+年度”查重） | “以下单位工程本年度已纳入其他年度计划：X、Y” | 不创建重复流程；不同单位工程可各自下达 | 记录重复单位工程 | TC-EP-021 |
| 退回导致下游重办 | 阶段退回处理 | “退回后续阶段需重新办理” | 下游当前结果转待重办，历史保留 | 记录目标阶段和影响范围 | TC-EP-022 |
| 审批校验异常 | FlowActionPanel 的业务校验回调 | 对话框内显示缺失单位工程和缺失项，保持当前弹窗 | 不调用流程推进；用户补齐后重试 | 记录校验错误上下文 | TC-EP-017 |
| 浏览器/代理层上传状态码 0 | FileUpload 自定义 XHR | “上传文件失败，请检查网络连接后重试”或服务端返回消息 | 不更新业务附件引用；回收计数和 loading | 前端错误及后端是否收到 /resource/oss/upload 可关联核对 | TC-EP-018 |
| 附件成功回显抖动 | FileUpload 列表渲染 | 列表直接稳定更新 | 去掉进入动画，复用 uid，不影响附件引用 | 组件回归 | TC-EP-020 |
| 只读成果附件只显示数量 | 工程手续工作区只读结果区使用了数量函数 | 直接展示禁用态 FileUpload 文件列表；文件名可预览、可下载；无附件显示“—” | 不写入结果或附件引用 | 记录页面、阶段和附件加载结果 | TC-EP-021 |
| 进度附件数量不可查看 | 进度表附件列仅有文本数量 | 有附件时数量为可访问控件，打开只读附件查看框；无附件显示“—”且不可点击 | 查看和关闭不改变 attachmentRefs | 记录行 ID、阶段和查看结果 | TC-EP-022 |
进度保存与附件关联允许分步上传，但单位工程完成和节点提交必须以服务端最终状态为准；不得用前端按钮成功替代流程状态成功。
6. 实现映射与验证
| 责任 | 现有可复用位置 | 状态 |
|---|---|---|
| 工程树和单位工程/标段选择 | digital-construction-ui/src/views/business/engineeringProcedures/components/ProcedureUnitSelector.vue、现有工程树 API | 已接入；按录单入口切换层级（土建=“线路-标段-工点”选工点并带入责任标段；机电=“线路-标段”选标段），运营节点默认隐藏、可切换显示；服务端校验管辖关系与入口一致性 |
| 流程工作区 | digital-construction-ui/src/components/Process/FlowActionPanel.vue、FlowProgressDrawer.vue、FlowTimeline.vue 与工程手续工作区 | 已接入；顶部横向 Tab 含年度计划只读 Tab（土建 6/机电 3），采用左表单/右时间线布局并移除办理规则区域；时间线按“节点名称+审批状态 / 当前办理人 / 时间信息”三段展示，协作标签固定右上角并使用独立色板，名称和办理人支持完整悬停提示，意见可完整换行；进度记录弹窗增删改、条件紧凑一行下拉 |
| 只读附件展示 | 工程手续工作区、公共 FileUpload、FilePreviewDrawer | 已实现；结果区直接渲染禁用态文件列表，进度表有附件时以可访问数量控件打开只读文件列表；预览/下载复用既有能力，不新增接口或字段；组件和内置浏览器页面回归通过 |
| 人员选择 | digital-construction-ui/src/components/UserSelect/index.vue、ProcedureUserSelectField.vue | 已接入；部门树、人员筛选和单/多人选择，不使用普通下拉框 |
| 文件上传 | digital-construction-ui/src/components/FileUpload/index.vue 及现有 OSS API | 已接入；自定义 XHR multipart、错误收敛、稳定列表已实现；内置浏览器土建多节点上传返回 200 并回显 |
| 审批错误反馈 | digital-construction-ui/src/components/Process/FlowActionPanel.vue | 已实现；业务校验异常在审批对话框内展示，定向测试通过 |
| 待办回退路由 | digital-construction-ui/src/views/index.vue | 已修正为 /task/taskWaiting，内置浏览器入口正常加载 |
| 草稿办理人快照 | EngineeringProcedureServiceImpl.add/update | 已实现；保存/更新同步 ID 和名称，提交继续服务端校验，后端单元测试覆盖 |
| 成熟业务工作台 | digital-construction-ui/src/views/business/sqe/、招投标工作区 | 参考交互和状态处理 |
| 后端业务、实体和 Mapper | 工程手续办理专属代码 | 已实现并通过 Maven 编译 |
| 数据库结构 | 工程手续办理 7 张专属表 | 结构已回读；REMARK、PLANNED_DATE、IS_KEY_BLOCKER、CONSTRUCT_UNIT_NAME_SNAPSHOT 已通过 MCP 执行并回读确认 |
| Warm-Flow 定义 | 两套独立流程定义 engineering_procedure_civil/engineering_procedure_mep，共用流程能力和办理工作区；外层框一一对应业务节点，条件菱形只负责分流；节点编号采用原型泳道口径（年度计划=1，手续阶段=2~6，子手续=2.1/4.1/4.1.1），结束前含 7 接收备案归档直通节点 | 土建运行态 V3、机电运行态 V2；资源分别为 15 个节点/17 条连线、6 个节点/5 条连线；土建已按 4 → 4.1 → 4.1.1 嵌套条件和锚点重排；两套定义均已导入，导入结果确认无问题，未覆盖在途旧实例 |
| 手续台账页 | views/business/engineeringProcedures/{planningOpinion,preliminaryDesign,constructionEngineeringPlanningPermit,constructionDrawingReview,constructionPermit} + stage/ProcedureLedgerPage.vue；后端 queryLedger/GET /ledger | 已实现：每行=单位工程，页面只显示当前阶段及已通过阶段的计划，节点仍按明细 NODE_CODE 过滤；四色进度状态、办理人/部门、办理/详情跳转保留 |
| 推进总台账 | views/business/engineeringProcedures/summary/index.vue；后端 GET /ledger（不带 stageCode） | 已实现：推进单元×8 手续列矩阵（首列“工点/专业”，补施工图审查合格书），完成时间按“已完成/计划完成日期”展示，只读、来源详情 |
| 线路级导出 | 后端 exportSummary/POST /summary/export（POI） | 已实现：按线路分 sheet、两行合并表头、8 手续列×完成时间/进展情况；完成时间列已完成显示“已完成”、未完成显示计划完成日期 |
| 台账当前责任人 | WorkflowService.currentTaskAssigneeIds + 台账装配 | 已实现：办理人/部门取流程实际待办办理人，无待办回退主单快照（A12） |
| 台账筛选与施工单位 | BO lineId/bidId/lineName/bidName/unitName/constructUnitName + ProjectNodeInfo.constructUnit + DeptService | 已实现：年度、线路、标段、单位工程、施工单位、审核状态筛选，台账/导出含施工单位中文名称；单位工程名称先按 UNIT_NAME_SNAPSHOT 反查主单 ID，PROJECT_PATH_SNAPSHOT 仅作技术兼容；单位工程表保存 CONSTRUCT_UNIT_NAME_SNAPSHOT，历史空快照读取时补齐（A14） |
| 只读历史 | 后端 queryHistory/GET /{id}/history + 办理页“查看历史”弹窗 | 已实现：跨办理轮次的进度/结果只读展示（A15） |
| 数据范围 | EngineeringDataAccessHelper：土建按整线授权或标段×工点组合，机电标段行按整线授权或受限授权命中标段，在列表/台账/详情/写操作校验 | 已实现（A02）；不建立独立项目权限 |
| 成果附件校验 | saveResult 经 OssService.selectByIds 校验 ossId 存在 | 已实现（A09）；本模块不扩展附件生命周期 |
7. 变更记录
v0.22（2026-09-13）同步：保存标段类型时将顶层字段同步到
projectNodeInfo扩展字段，避免旧值覆盖用户选择；选择器按回读类型解析单位工程，年度计划草稿页面链路已完成真实回归。退回重办仍待浏览器补测。
| 版本 | 日期 | 变更 | 原因/来源 | 确认人 |
|---|---|---|---|---|
| v0.1 | 2026-09-07 | 建立 7 页面、流程工作区、节点内多次进度填报和单位工程完成门槛 | 用户确认、原型、流程图、Excel | 待补充 |
| v0.2 | 2026-09-07 | 补充土建/机电类型校验及两种类型的阶段配置 | 用户补充、流程图核对 | 历史口径，流程定义已由 v0.9 拆分为土建/机电两套 |
| v0.3 | 2026-09-07 | 确认年度计划唯一范围、单位工程完成门槛、标准办理/审核动作、退回后续重办、条件三选项和进度物理删除；取消许可证名称全局改名假设 | 用户确认 | 待补充 |
| v0.4 | 2026-09-07 | 进度跟踪表改为 VXE 行内编辑，不使用新增/编辑弹窗 | 用户确认 | 待补充 |
| v0.5 | 2026-09-07 | 办理人、审核人和候选岗位统一使用通用用户选择器，禁止普通下拉框 | 用户补充 | 待补充 |
| v0.6 | 2026-09-07 | 完成首轮前后端代码、7 张开发库业务表、公共流程分类/定义、菜单和权限注册；补充退回重办轮次处理 | 首轮实现与开发库核验 | 待集成验收 |
| v0.7 | 2026-09-09 | 年度计划独立于工作区阶段；工作区调整为土建 5/机电 2 个实际手续 Tab，采用左侧单位工程表单、右侧审批时间线并优化首屏加载 | 用户确认、首轮实现调整 | 待集成验收 |
| v0.8 | 2026-09-09 | 按最新流程图将阶段 Tab 与外层业务节点分离；补齐 1.1、3.1.1、3.1 子手续节点及父节点返回，明确节点内反复填报与最终提交为两个操作层次 | 用户确认、最新流程图核对 | 待集成验收 |
| v0.9 | 2026-09-09 | 土建/机电改为两套独立流程定义；年度计划补齐单位工程逐行阶段计划日期；流程资源按 7 字换行、四向锚点、正交铺满画布和无静态退回线规范校正 | 用户确认、流程规范、原型核对 | 待集成验收 |
| v0.10 | 2026-09-09 | 按原型泳道图统一节点编号（年度计划=1、手续阶段=2~6、子手续=2.1/4.1/4.1.1），新增结束前 7 接收备案归档直通节点；后端 nodeName()、前端 NODE_LABELS 与 validateNode 同步，土建 15 节点/17 连线、机电 6 节点/5 连线 | 用户确认、原型泳道流程图核对 | 待集成验收 |
| v0.11 | 2026-09-09 | 条件取消“需要再次”，只保留“不需要/需要”，子手续未完成前可回改“不需要”，再次办理走退回；进度表主手续新增“是否重难卡点”、列名对齐“完成日期”，子手续用“总体进度”；办理页保持横向 Tab + 单位工程切换，进度行内编辑修复附件上传与文本框尺寸；要件清单改为悬浮文字 tip；条件进一步简化为纯决策值（本地保存、随保存表单/完成单位工程/提交批量落库、提交时由网关按“任一需要”判断分支，去掉轮次与状态机副作用） | 用户确认、原型办理页核对 | 待集成验收 |
| v0.12 | 2026-09-09 | 进度记录改为独立弹窗新增/编辑/删除、表格只读并显示附件数量；条件压缩为原型式紧凑一行下拉；父手续证件在“需要”子手续未完成前置灰；年度计划查重放宽为按“单位工程+年度”并点名重复单位工程，不再限制同项目同年度一份；办理动作简化为“暂存 + 同意”，去掉“完成单位工程”按钮，同意时统一校验；同意校验只读，完成状态在离开节点时落库（syncProcessEvent/syncTaskEvent 内），避免流程失败时单位工程被提前锁定 | 用户确认、原型办理页核对 | 待集成验收 |
| v0.13 | 2026-09-09 | 落地手续台账页（ProcedureLedgerPage + queryLedger/GET /ledger）、推进总台账（单位工程×8 手续列，补施工图审查合格书）、线路级 Excel 导出（POI，按线路分 sheet、两行合并表头）；四色进度状态与办理人/部门派生 | 用户确认、原型线路级 Excel 核对 | 待集成验收 |
| v0.15 | 2026-09-10 | 修复 EP-A01：在 Warm-Flow GlobalListener.start 接入工程手续业务前置扩展点，服务端校验当前节点并重算条件分支；新增施工单位中文名称快照及历史补齐；台账按“当前阶段及已通过阶段”累计展示；土建流程调整为 4 → 4.1 → 4.1.1 嵌套条件并补充连线不得共享线段规范 | 用户补充、流程图核对、开发实现 | 待集成验收 |
| v0.16 | 2026-09-10 | 确认运行态流程版本为土建 V3、机电 V2；两套流程已在设计器导入且导入结果确认无问题 | 用户确认 | 已确认 |
| v0.17 | 2026-09-10 | 按当前代码反写线路/单位工程权限和台账筛选契约；补充 Excel 页签安全唯一命名；明确条件记录就地重置、不扩展附件生命周期；清理已废弃的重办专用测试项，端到端验收由业务方执行 | 用户确认、当前代码核对 | 待用户端到端验收 |
| v0.18 | 2026-09-10 | 移除年度计划前后端“同项目”限制和页面项目展示；单位工程筛选改用单位工程快照反查并保护无匹配结果；补充跨项目同类型选择、筛选条件和列表空参数回归验证 | 用户确认、当前代码核对 | 待用户端到端验收 |
| v0.19 | 2026-09-12 | 反写本次真实复验和修复：补齐流程任务账号的单位工程范围前置；修复审批校验错误反馈、草稿首节点办理人快照、附件 multipart 上传/失败批次收敛、附件列表稳定键值和无进入动画、待办路由回退；同步记录土建/机电多单位工程多账号流转、条件分支、附件 200 响应和未验证范围 | 内置浏览器端到端复测、前后端自动化测试 | 主要端到端链路已复验；退回重办和新建可选数据场景待补测 |
| v0.23 | 2026-09-14 | 补充土建计划 EP-2026-9772154880 五阶段正式闭环、空计划日期阻断和空条件网关预路由兼容的实现与验收口径；同步流程完成、待办归零、附件和工程数据范围证据 | 内置浏览器/真实接口、DM8 MCP、后端定向回归 | 代表性主链已核验；退回重办及扩展条件分支待专项 |
| v0.20 | 2026-09-12 | 根据用户截图细化只读附件展示：成果/证件资料直接显示文件；进度表保留附件数量并可点击打开只读附件查看框；复用禁用态 FileUpload 的文件名、预览和下载能力，不改变附件接口、字段、权限和生命周期 | 用户截图、成熟只读工作台、界面与交互规范核对；组件、类型/静态检查和内置浏览器回归 | 已实现并通过代码、组件和页面回归 |
| v0.21 | 2026-09-12 | 收口审批时间线最终展示：节点名称后紧跟审批状态；会签/或签/票签固定在卡片右上角并沿用状态标签的尺寸排版但使用独立协作色板；当前办理人行和时间信息区采用紧凑间距；审批意见完整换行，节点名称和办理人支持悬停查看完整值 | 用户最终确认、界面与交互规范核对、FlowTimeline 组件回归和内置浏览器复测 | 已实现并通过定向代码、组件和页面回归 |
| v0.24 | 2026-09-18 | 补入单位工程选择器运营显示口径：默认隐藏运营节点（含运营根节点）、运营根下的非运营下级提升到最近可见层级、工具栏「显示运营」开关默认关闭、只切换显示层、服务端不按运营状态过滤或拒绝 | 用户确认（业务侧选择器默认隐藏运营口径）、当前代码核对、页面回归（有限范围） | 已实现并通过有限范围页面回归 |
| v0.28 | 2026-10-13 | 体验优化与真实推进台账对齐：①年度计划下达搜索栏补充「线路」；②主节点在子手续进行中隐藏结果资料；③表单自上而下顺序统一为 4.1 在 4.1.1 上方；④未保存点击同意弹出拦截提醒；⑤子手续办结归档返回后协同决策默认切换为「不需要（直行推进）」；⑥施工许可证落实 1:N 任务批次办证；⑦手续总台账补充施工标段与责任部门，并通过管辖标段与统包标段动态反查补齐标段与施工单位。 | 用户 2026-10-13 问题清单、前后端实现、测试通过 | 已实现并通过验证 |
| v0.29 | 2026-10-15 | 录单入口改造与台账对齐：①新增年度计划拆分为“新增年度计划（土建）/（机电）”两个入口，BO 增加入口通道与标段 ID 列表，取消逐工点手选办理通道；②土建按“线路-标段-工点”选择工点并保存责任标段（含施工单位快照），服务端校验标段与工点管辖关系；③机电按“线路-标段”选择标段，标段即推进单元，查重按“标段+年度”；④总台账/导出首列“工点/专业”、完成时间按“已完成/计划完成日期”展示；⑤台账、施工许可证 1:N 同步与计划列表权限适配机电标段级（无工点）可见判定 | 用户 2026-10-15 需求确认与逐条拍板、前后端实现与测试 | 待端到端验收 |