交开投数智建管平台

主题

规划管理 · 详细设计文档 ​

文档版本：1.00 ｜ 最近核对日期：2026-09-20

文档控制 ​

项目内容
模块名称规划管理（项目储备：储备清单、状态跟踪；规划报建：线网规划、建设规划、工可研究；专题类型目录）
关联需求分析需求分析
关联概要设计概要设计
关联数据库设计数据库设计：13 张 biz_planning_* 表的字段矩阵与核对范围见该文
关联代码版本2026-09-20 技术核对的工作区；端到端受测代码状态见测试与验证报告
编写/核对人ZCode 文档 Agent（只读核对：6 个 Controller、服务实现、流程监听器、前端接口与路由、开发库菜单/权限/流程定义/字典数据）
受测代码状态本文技术核对本身未执行测试、构建或页面操作；对应页面与接口证据见测试与验证报告，不代表当前工作区已复验
待确认事项见第 9.2 节（会签后确认节点办理人取值、导出列口径等）

本文档口径说明：下述技术实现映射依据 2026-09-20 的后端代码核对，菜单路径、权限行、流程定义与字典依据当日开发库只读回读；与设计稿的技术差异在第 9.1 节列明。业务规则仍以需求分析为准，代码差异不能静默改写业务基线；当前代码状态和完成范围需以新的实现及验证证据复核。

1. 页面、路由与交互 ​

1.1 页面与路由清单 ​

普通页面由后端菜单驱动（SYS_MENU.COMPONENT），办理页族、项目历史数据由前端静态注册；两类页面都必须通过角色授权或接口权限才可查看业务内容。

页面/组件路由进入条件可见角色主要操作状态/异常反馈
储备清单（列表 + 任务台账 + 项目台账）/planning/projectReserve/reserve菜单「规划管理 / 项目储备 / 储备清单」授权（planning:reserve:list）规划管理发起人、审批人、管理员（授权范围内）查询（项目名称、填报单位、审核状态、任务名称）、开投集团新增、二级单位新增、修改、删除、导出、任务台账/项目台账切换、行操作（编辑/详情/办理/删除）草稿可编辑与删除、退回可编辑后重提、进行中仅发起人可编辑且仅当前办理人可办理、已通过只读；请求失败由全局拦截器提示，页面清空数据并结束加载
状态跟踪（列表 + 任务台账 + 项目台账）/planning/projectReserve/statusTracking菜单「规划管理 / 项目储备 / 状态跟踪」授权（planning:statusTracking:list）同上同上；专题类型（多选）为必填；项目台账另展示「规划报建阶段」「专题类型」列并提供「历史数据」入口自动引用记录为已通过且无流程实例，不提供编辑；其余同储备清单
线网规划（列表）/planning/planningSubmission/networkPlan菜单「规划管理 / 规划报建 / 线网规划」授权（planning:networkPlan:list）同上查询、开投集团新增、二级单位新增、修改、删除、导出、行操作；不提供任务台账/项目台账切换（页面结构按平台台账模式确定）同储备清单
建设规划（列表 + 任务台账 + 项目台账）/planning/planningSubmission/constructionPlan菜单「规划管理 / 规划报建 / 建设规划」授权（planning:constructionPlan:list）同上查询（含工作阶段）、双发起方式新增、专题类型目录入口、修改、删除、导出、台账切换、行操作编制/报审/批复各为独立任务，按任务展示；项目台账按项目聚合本模块历史任务
工可研究（列表 + 任务台账 + 项目台账）/planning/planningSubmission/feasibilityStudy菜单「规划管理 / 规划报建 / 工可研究」授权（planning:feasibilityStudy:list）同上同建设规划（moduleType 独立）同建设规划
专题类型目录/planning/planningSubmission/topicType隐藏菜单「规划管理 / 规划报建 / 专题类型目录」授权（planning:topicType:list），由建设规划/工可研究工具栏按钮进入配置管理员（planning:topicType:* 授权角色）查询（业务阶段、专题名称、启用状态）、新增、修改、删除、详情、关联项目（多选）同一业务阶段下同名专题拒绝；被任务引用的专题不可删除（提示改为停用）；关联项目按差量维护
项目历史数据/planning/projectHistory（固定路由，不依赖菜单）项目台账行「历史数据」跳转并携带 moduleType/projectId/projectName 查询参数具备该模块 query 权限的授权角色按项目汇总同一模块历史任务；行操作「详情」「办理」复用办理页固定路由缺少 projectId 或越权时列表为空并提示

办理页族（9 条 flowCode，静态注册于前端，菜单中为隐藏菜单「流程定义名称 + 办理」）：

办理页路由对应 flowCode进入条件可见角色主要操作状态/异常反馈
储备清单办理/planning/projectReserve/reserve/flowFormplanning_reserve待办、列表「详情/办理」、项目历史数据跳转（?id=&type=&taskId=）当前办理人及授权查看人员只读表单、成果明细与附件、流程图、审批时间线、同意/退回；意见征求节点使用「是否需要各部门意见征求 + 四部门接收人」面板；可重启实例无 id 参数不加载；加载失败显示错误态；非当前办理人无办理面板；type=view 为只读详情
状态跟踪办理/planning/projectReserve/statusTracking/flowFormplanning_status_tracking同上同上同储备清单（无意见征求节点）同上
线网规划办理/planning/planningSubmission/networkPlan/flowFormplanning_network_plan同上同上同上同上
建设规划编制阶段办理/planning/planningSubmission/constructionPlan/compilation/flowFormplanning_construction_compilation同上同上同上（含意见征求：四个部门并行节点，全部完成后汇聚）同上
建设规划报审阶段办理/planning/planningSubmission/constructionPlan/submission/flowFormplanning_construction_submission同上同上同上（无意见征求）同上
建设规划批复阶段办理/planning/planningSubmission/constructionPlan/approval/flowFormplanning_construction_approval同上同上同上同上
工可研究编制阶段办理/planning/planningSubmission/feasibilityStudy/compilation/flowFormplanning_feasibility_compilation同上同上同上（含意见征求：四个部门并行节点，全部完成后汇聚）同上
工可研究报审阶段办理/planning/planningSubmission/feasibilityStudy/submission/flowFormplanning_feasibility_submission同上同上同上同上
工可研究批复阶段办理/planning/planningSubmission/feasibilityStudy/approval/flowFormplanning_feasibility_approval同上同上同上同上

菜单结构（开发库回读）：规划管理（目录）→ 项目储备（目录：储备清单、储备清单办理、状态跟踪、状态跟踪办理）与 规划报建（目录：线网规划、线网规划办理、建设规划、建设规划编制/报审/批复阶段办理、工可研究、工可研究编制/报审/批复阶段办理、专题类型目录）；流程实例重启 为挂在 规划管理 下的按钮权限行。办理页菜单 PATH 与静态注册路由一致，前端按 flowFormPaths 路径集合跳过重复注册（见第 6.3 节）。

1.2 列表、台账与只读详情交互 ​

  • 五个业务页面共用 PlanningTaskPage.vue，差异只在模块标识与开关：储备清单（showLedger + 发起方式列）、状态跟踪（showLedger + 专题类型 + 台账阶段列）、线网规划（无台账）、建设规划与工可研究（工作阶段 + 专题类型 + 专题目录入口 + 台账）。
  • 行操作与状态联动：草稿 → 编辑、删除；退回 → 编辑（重新提交）；进行中 → 详情、办理（有当前待办时）；已通过 → 详情。编辑按钮同时要求服务端返回的 canEdit（创建人或具备 manage 权限），删除在后端复核「仅草稿可删除」。
  • 列表「详情」不打开只读弹窗，而是跳转办理页固定路由的只读视图（type=view），流程图、审批时间线与重启入口在该页面内；草稿没有流程实例，项目台账的草稿行仍回退只读业务弹窗。
  • 项目台账为项目维度实时聚合视图，不建副本表；行取该分组内最新任务回填，操作按该行自己的模块类型调用接口（状态跟踪台账会混入建设规划/工可研究的任务行）。
  • 新增/编辑弹窗（PlanningTaskForm.vue）：项目名称（多选，必填；线网规划不显示该项目名且不校验）、任务名称（必填）、工作阶段（建设规划/工可研究必填）、专题类型（模板库下拉引用 + 自定义名称输入 + 卡片内改名，状态跟踪至少引用 1 个模板专题）、填报单位、填报人员、填报时间（必填）、成果明细表（主要内容 + 附件）；已按 2026-10-09 清单去掉备注字段。提交未被选中审核人时先弹出「选择下一步审核人」弹窗（提示多人按或签处理）。
  • 提交校验：项目（线网规划不校验）、任务名称、工作阶段（按模块）、专题类型（状态跟踪至少 1 个模板专题）、填报时间为空时前端拦截；提交时额外要求至少一条成果明细且主要内容非空，附件不校验。后端 validateSaveBo 对同样字段复核，并在提交时要求 nextHandlerIds 非空。
  • 失败反馈统一沿用平台：请求失败由全局拦截器提示，列表清空数据并结束加载；表单保存/提交失败保留弹窗与输入内容。

2. 接口契约 ​

前缀 /business/planning，资源段与 @RequestMapping 逐字对应：reserve、statusTracking、networkPlan、constructionPlan、feasibilityStudy、topicType。除 process/restart 与两个台账视图接口外，各接口权限码按资源逐字替换（见 2.2）；台账视图接口使用跨模块共用权限码 planning:ledger:task / planning:ledger:project。五个业务任务控制器结构完全一致，正文以 {module} 表示资源段。

2.1 业务任务接口总表（{module} ∈ 五个业务资源段） ​

接口方法调用方权限请求对象响应对象幂等/事务
/business/planning/{module}/listGET列表页planning:{module}:listPlanningTaskQueryBo（分页、projectId/projectName、fillOrgName、businessStatus、workStage、taskName、initiatorType、topicTypeId、beginTime/endTime）PageResult<PlanningTaskVo>只读；@Transactional 不适用；按 createTime 倒序
/business/planning/{module}/ledger/taskGET任务台账视图planning:ledger:task（跨模块共用）同列表PageResult<PlanningTaskVo>只读；实现直接复用列表口径（任务维度，不按项目合并历史任务）
/business/planning/{module}/ledger/projectGET项目台账视图planning:ledger:project（跨模块共用）PlanningLedgerQueryBo（projectId/projectName、fillOrgName、businessStatus、workStage、taskName、分页）PageResult<PlanningLedgerRowVo>只读；按项目分组聚合后在内存分页，按 fillTime 倒序
/business/planning/{module}/get/{id}GET详情/编辑回填/办理页planning:{module}:query路径参数：业务任务 ID 或业务标识 {阶段记录ID}#{实例序号}PlanningTaskDetailVo只读；id 两种格式兼容，阶段记录不存在时抛业务异常
/business/planning/{module}/process-info/{id}GET办理页/详情页planning:{module}:query同上PlanningProcessInfoVo只读
/business/planning/{module}/history/{id}GET详情页（审批历史）planning:{module}:query同上List<PlanningApprovalRecordVo>只读；按主键升序，含发起单位区分字段
/business/planning/{module}/add/secondary-unitPOST二级单位新增planning:{module}:addUnitPlanningTaskSaveBo（initiatorType 由后端常量覆盖）Long（任务 ID）@RepeatSubmit；事务；仅创建草稿（draft）
/business/planning/{module}/add/groupPOST开投集团新增planning:{module}:addGroup同上Long@RepeatSubmit；事务；仅创建草稿
/business/planning/{module}/editPUT修改/退回重提（暂存）planning:{module}:edit含 id 与 initiatorType 的 PlanningTaskSaveBoLong@RepeatSubmit；事务；仅草稿/退回可改；校验发起方式不可变更
/business/planning/{module}/submitPOST暂存后提交/退回重提planning:{module}:submit含 id、nextHandlerIds 的 PlanningTaskSaveBoLong@RepeatSubmit；事务；草稿启动流程、退回完成申请人节点任务
/business/planning/{module}/remove/{ids}DELETE列表/项目台账删除planning:{module}:remove路径参数：任务 ID 列表（逗号分隔）Void事务；逐条校验归属与「仅草稿可删」，逻辑删除任务、阶段记录、项目关联与专题关联；成果版本、成果明细与附件引用引用不在级联范围内（草稿未提交，仅产生无引用残留）；无 @RepeatSubmit
/business/planning/{module}/consultation/decidePOST意见征求决定节点planning:{module}:processPlanningConsultationDecideBo（taskId 为流程任务 ID、needConsultation 必填、message、fileId、items[{deptType,deptId,deptName,handlerUserId,handlerUserName}]）Void@RepeatSubmit；事务；运营/资产/建设三部门接收人必填，OTHER 选填；接收人重复拒绝；写入实际选择的部门任务后完成当前节点，并为未选择的 OTHER 分支传 needOtherConsultation=0
/business/planning/{module}/consultation/opinionPOST部门意见节点planning:{module}:processPlanningConsultationOpinionBo（taskId 为流程任务 ID、message、fileId、result 必填 AGREE/REJECT）Void@RepeatSubmit；事务；先完成任务再按登录人回写本人待办明细
/business/planning/{module}/process/restartPOST详情页重启实例planning:process:restart（五个控制器共用）PlanningProcessRestartBo（taskId 为业务任务 ID、reason 必填、nextHandlerIds）Void@RepeatSubmit；事务；原实例置 SUPERSEDED、新实例 instanceSeq+1 并记录 originalInstanceId
/business/planning/{module}/exportPOST列表/台账导出planning:{module}:export同列表筛选（表单参数）xlsx（ExcelBuilder，sheet 名即模块名）只读；导出列见 2.5

2.2 各资源权限码对照 ​

动作reservestatusTrackingnetworkPlanconstructionPlanfeasibilityStudy
listplanning:reserve:listplanning:statusTracking:listplanning:networkPlan:listplanning:constructionPlan:listplanning:feasibilityStudy:list
query（get/process-info/history）planning:reserve:queryplanning:statusTracking:queryplanning:networkPlan:queryplanning:constructionPlan:queryplanning:feasibilityStudy:query
addUnitplanning:reserve:addUnitplanning:statusTracking:addUnitplanning:networkPlan:addUnitplanning:constructionPlan:addUnitplanning:feasibilityStudy:addUnit
addGroupplanning:reserve:addGroupplanning:statusTracking:addGroupplanning:networkPlan:addGroupplanning:constructionPlan:addGroupplanning:feasibilityStudy:addGroup
edit（暂存）planning:reserve:editplanning:statusTracking:editplanning:networkPlan:editplanning:constructionPlan:editplanning:feasibilityStudy:edit
submitplanning:reserve:submitplanning:statusTracking:submitplanning:networkPlan:submitplanning:constructionPlan:submitplanning:feasibilityStudy:submit
removeplanning:reserve:removeplanning:statusTracking:removeplanning:networkPlan:removeplanning:constructionPlan:removeplanning:feasibilityStudy:remove
process（意见征求/部门意见）planning:reserve:processplanning:statusTracking:processplanning:networkPlan:processplanning:constructionPlan:processplanning:feasibilityStudy:process
exportplanning:reserve:exportplanning:statusTracking:exportplanning:networkPlan:exportplanning:constructionPlan:exportplanning:feasibilityStudy:export
任务台账planning:ledger:taskplanning:ledger:taskplanning:ledger:taskplanning:ledger:taskplanning:ledger:task
项目台账planning:ledger:projectplanning:ledger:projectplanning:ledger:projectplanning:ledger:projectplanning:ledger:project
manage（仅记录级权限判定，无接口）planning:reserve:manageplanning:statusTracking:manageplanning:networkPlan:manageplanning:constructionPlan:manageplanning:feasibilityStudy:manage

模块类型常量与资源段对应：RESERVE、STATUS_TRACKING、NETWORK_PLAN、CONSTRUCTION_PLAN、FEASIBILITY_STUDY（PlanningModuleType）。列表/详情接口不接收 moduleType 参数，模块由请求路径决定；保存请求中的 moduleType 字段仅作必填校验，实际写库值取控制器常量。

2.3 专题类型目录接口（/business/planning/topicType） ​

接口方法权限请求要点响应要点特殊行为
/listGETplanning:topicType:listPlanningTopicTypeQueryBo（planBizStage、topicName、enabled、分页）PageResult<PlanningTopicTypeVo>排序 planBizStage → sortNo → id 升序
/optionsGETplanning:topicType:listplanBizStage 选填List<PlanningTopicTypeVo>只返回 enabled=1，供表单多选下拉
/get/{id}GETplanning:topicType:query路径参数：专题类型 IDPlanningTopicTypeVo（含 projectList）不存在抛业务异常
/addPOSTplanning:topicType:addPlanningTopicTypeBo（planBizStage、topicName 必填；enabled 默认 1；projectIds）Long@RepeatSubmit；事务；同一业务阶段下同名拒绝；新增后同步关联项目
/editPUTplanning:topicType:edit含 id 的 PlanningTopicTypeBoLong@RepeatSubmit；事务；projectIds 非空时按差量维护关联
/remove/{ids}DELETEplanning:topicType:remove路径参数：ID 列表Void事务；被任务主表 topicTypeId 引用时拒绝并提示改为停用；级联逻辑删除项目关联
/relatePOSTplanning:topicType:relate查询参数 topicTypeId 必填 + 请求体 List<projectIds>Void@RepeatSubmit；事务；已存在的逻辑删除关联做恢复，不做快照名称回填（projectName/projectCode 由项目主数据侧维护，当前实现未写入）

2.4 复用的平台接口 ​

能力接口说明
审批办理（同意/退回/转办等）/workflow/task/completeTask、/workflow/task/backProcess、/workflow/task/getBackTaskNode/{taskId}/{nowNodeCode}由平台 FlowActionPanel 调用；规划管理不自定义办理接口（意见征求两节点除外）
流程图与审批时间线/workflow/instance/flowHisTaskList/{businessId}业务标识含 #，调用处已对路径段做 encodeURIComponent
附件上传与预览/resource/oss/upload、/resource/oss/listByIds/{ossIds}业务侧只保存 ossId 引用
项目主数据business:project:query 相关项目查询发起时项目/线路选择（权威口径为已解耦的 BIZ_PROJECT）

2.5 返回要点与导出列 ​

  • PlanningTaskVo：id、moduleType、taskName、workStage、topicTypeId/topicTypeName/topicTypes/topicTypeNames、sourceType/sourceTaskId/sourceStageRecordId、initiatorType/initiatorOrgName/initiatorDeptName/initiatorUserName、fillOrgName/fillUserName/fillTime、businessStatus、instanceId、currentNodeCode/currentNodeName/currentHandlerIds/currentHandlerNames、remark、projects/projectNames、currentTaskId、canEdit。其中 currentTaskId 为当前登录人在该业务标识下的待办流程任务 ID（无待办为 null），列表「办理」按钮据此显示；canEdit 为创建人或具备 manage 权限。
  • PlanningLedgerRowVo：projectId、projectNames、taskId（该行最新任务）、moduleType（行进模块，状态跟踪台账内可能为建设规划/工可研究）、taskName、workStage、topicTypeName/topicTypeNames、mainContent、fillOrgName/fillUserName/fillTime、businessStatus、recordCount（该项目在本查询范围内的任务数）、currentTaskId、canEdit。
  • PlanningTaskDetailVo：任务平铺字段 + projects、topicTypes、stageRecords、versions（版本号倒序）、currentItems（当前版本明细与附件）、consultations（部门意见任务）。
  • PlanningProcessInfoVo：businessId（{阶段记录ID}#{实例序号}）、instanceId、flowCode/flowName/flowVersion、businessStatus（任务状态；存在阶段记录时以阶段记录为准）、businessTitle（项目名称 + 任务名称（工作阶段））、currentNodeCode/currentNodeName/currentHandlerNames、canProcess（当前登录人在该业务标识下有待办）、currentTaskId、consultationDecide（当前节点是否为意见征求决定节点）、consultationSign（当前节点是否为部门意见会签节点）。
  • PlanningApprovalRecordVo：nodeCode/nodeName、handlerUserId/handlerUserName/handlerDeptId/handlerDeptName、handlerOrgName（发起单位名称快照）、initiatorType/initiatorOrgName、opinion、result（AGREE/REJECT）、handleTime、flowCode/flowVersion、engineTaskId。
  • 导出（PlanningExportVo，sheet 名为模块名）：项目名称、任务名称、工作阶段、专题类型、填报单位、填报人员、填报时间、审核状态、发起方式，共 9 列；成果明细不展开，工作阶段/审核状态/发起方式输出英文枚举值（未做字典转换，见第 9.1 节差异 7）。

2.6 首页会商待办个人聚合口径（决策记录） ​

个人中心工作台的「会商待办」取数采用口径 B：biz_planning_consultation_task 中 status = PENDING 且（handler_user_id = 当前登录人，或 handler_user_id 为空且 dept_id = 当前登录人部门）的任务，按创建时间倒序；计数与封顶 5 条明细经登录级聚合接口 GET /business/homepage/todo-summary 的 consultationPending / consultationItems 返回，不挂菜单权限，实现见 PlanningTaskServiceImpl#listMyPendingConsultations。

  • 采用口径 B 的理由：会签任务创建时允许只派到部门不指人（PlanningTaskServiceImpl 批次创建对 handlerUserId 判空收集），若仅按指人口径统计，部门级会商任务将不进入任何人的首页待办；意见提交门禁本为功能权限（planning:{module}:process）而非身份校验，部门内成员均可办理，口径 B 与该语义一致。
  • 备选口径 A（记录未采用）：仅统计 handler_user_id = 当前登录人 的 PENDING 任务。语义最严格、无重复计数，但会使"只派到部门"的会商任务在首页不可见；若后续业务明确部门任务须先指人再办理，可切换回口径 A，改动仅限 listMyPendingConsultations 的查询条件。
  • 口径 B 的已知特性：同部门多名成员会同时看到同一条部门级会商待办（计数按人重复、办理后同步消失），与会签"部门内任一成员可办"的语义相符。

3. 状态与业务动作 ​

统一业务状态复用平台 BusinessStatusEnum 稳定编码：draft（草稿）、waiting（进行中）、back（退回）、finish（已通过），中文映射由字典 planning_business_status 提供。

当前状态动作允许角色前置校验数据变化下一状态失败处理
—新增（二级单位/开投集团）addUnit / addGroup 授权人（两注解按 OR 任一即可，发起方式由所点按钮对应的端点固定，不再校验用户部门归属）解析发起单位（集团取根部门；二级单位优先取部门链上已配置的所属单位 affiliated/secondary，未配置时记实际所在部门，不拦截）写任务（draft）+ 项目关联 + 专题关联 + 1 条阶段记录（seqNo=1）+ 1 条成果版本（versionNo=1, approvalResult=draft）+ 成果明细与附件引用草稿事务回滚并提示
草稿/退回暂存创建人或具备 manage 权限者任务名称、项目非空；状态跟踪另需专题类型；发起方式与记录一致全量重建项目/专题关联与当前版本明细；不启动流程草稿/退回事务回滚并提示
草稿提交创建人或具备 manage 权限者状态为 draft；nextHandlerIds 非空；提交校验同保存 + 成果明细至少一条且主要内容非空以 {阶段记录ID}#1 启动流程；写实例登记（instanceSeq=1、isCurrent=1）；版本置 waiting 并记录提交人与时间；阶段记录与任务置 waiting进行中启动失败整体回滚；当前状态不支持提交时明确提示
退回提交（重提）同上状态为 back；当前登录人须为该实例的申请人节点待办人完成申请人节点任务继续流转（沿用原实例与版本，不新增版本）进行中「您不是当前办理人，无权提交」
进行中同意（普通节点）当前待办人引擎任务归属、节点字段校验引擎推进；流程事件回写任务/阶段记录/版本状态与实例登记；任务事件写入审批记录进行中/已通过工作流失败不回写业务状态
进行中退回当前待办人退回节点 + 意见退出到申请人节点时状态置 back，历史记录不删除、不覆盖；会签节点任一部门退回由引擎 oneVoteVeto 使其余待办失效退回「未找到可退回的节点」等前端提示
进行中意见征求决定决定节点待办人needConsultation 必填；为「需要」时四个部门接收人必填且互不相同写批次（roundNo 递增、IN_PROGRESS）与部门任务（PENDING）；回写阶段记录 needConsultation；注入四个部门办理人变量并完成当前节点进行中缺部门或接收人重复时拒绝并提示
进行中提交部门意见部门意见节点接收人result 必填；任务归属校验完成本人任务；按登录人回写本人 PENDING 明细（意见、结果、DONE、完成时间）；四个并行分支全部完成触发汇聚与流程事件，会签路径由最后一人完成触发进行中「该任务不是您的待办，无法办理」
进行中拒绝/退回部门意见部门意见节点接收人退回意见必填退回后批次置 REJECTED（流程事件按 back 回写），已完成部门意见保留；并行分支的其余待办由引擎失效退回同上
已通过/退回（及其他终态）重启实例planning:process:restart 授权（当前仅规划管理管理员）任务与阶段记录存在；重启原因必填原实例登记置 SUPERSEDED、isCurrent=0、记录结束时间；新建实例（instanceSeq+1、originalInstanceId）并重新启动流程；阶段记录与任务置 waiting；原实例与历史保留进行中「阶段记录不存在」等业务异常
草稿删除创建人或具备 manage 权限者状态为 draft逻辑删除任务、阶段记录、项目关联、专题关联—「仅草稿状态的任务可以删除」
已通过（建设规划/工可研究）系统自动系统内部模块为分阶段管理且工作阶段非空；按来源阶段记录幂等生成状态跟踪引用任务（finish），复制项目与专题关联；不建阶段记录、不建版本、不启动流程已通过重复触发不重复生成

前端「重启实例」入口的显示条件为业务状态属于 finish/back/termination/invalid，并额外显示在只读详情页；后端 restart 不校验业务状态，但要求阶段记录存在（见第 9.1 节差异 10）。

成果版本取用规则（editableVersion）：默认取该阶段记录下版本号最大的一条并就地更新（新增任务时已建 versionNo=1），因此退回重提与重启实例复用同一条版本；仅当该最新版本的 approvalResult 已是 finish 时才新插入 versionNo+1 的版本。当前页面入口下「已通过」任务不提供编辑与提交入口，该分支属于代码保留的兜底路径（见第 9.1 节差异 11）。

4. 流程接入 ​

4.1 flowCode 解析口径 ​

PlanningFlowConstant.flowCodeOf(PlanningModuleType, PlanningWorkStage, PlanningInitiatorType)：储备清单/状态跟踪/线网规划按模块取基础编码后加发起方式后缀；建设规划与工可研究按工作阶段映射编制/报审/批复三条，其中编制阶段无发起方式网关不拆分（supportsGroupInitiator 对两条编制流程返回 false，直接用基础编码），needConsultation 不参与模板选择，而是流程内互斥网关的变量条件。前端 planningFlowCode 同口径解析，未传发起方式（且非编制阶段）时返回空，弹窗流程图入口据此在点击时提示先选工作阶段。

2026-09-30 起含发起方式网关的 7 条基础定义已删除，运行定义如下（16 条拆分/编制定义均为 V2 已发布；V1 已随发布失活，仅作历史保留）：

#flowCode流程定义名称模块 / 工作阶段发起方式意见征求
1planning_reserve_group / planning_reserve_unit储备清单（开投集团/二级单位）RESERVE按发起方式拆分有（部门负责人审核后判断）
2planning_status_tracking_group / planning_status_tracking_unit状态跟踪（开投集团/二级单位）STATUS_TRACKING按发起方式拆分无
3planning_network_plan_group / planning_network_plan_unit线网规划（开投集团/二级单位）NETWORK_PLAN按发起方式拆分无
4planning_construction_compilation建设规划编制阶段CONSTRUCTION_PLAN / COMPILATION仅二级单位（不拆分）有
5planning_construction_submission_group / planning_construction_submission_unit建设规划报审阶段（开投集团/二级单位）CONSTRUCTION_PLAN / SUBMISSION按发起方式拆分无
6planning_construction_approval_group / planning_construction_approval_unit建设规划批复阶段（开投集团/二级单位）CONSTRUCTION_PLAN / APPROVAL按发起方式拆分无
7planning_feasibility_compilation工可研究编制阶段FEASIBILITY_STUDY / COMPILATION仅二级单位（不拆分）有
8planning_feasibility_submission_group / planning_feasibility_submission_unit工可研究报审阶段（开投集团/二级单位）FEASIBILITY_STUDY / SUBMISSION按发起方式拆分无
9planning_feasibility_approval_group / planning_feasibility_approval_unit工可研究批复阶段（开投集团/二级单位）FEASIBILITY_STUDY / APPROVAL按发起方式拆分无

历史回读（2026-09-30）：16 条定义 VERSION=2、IS_PUBLISH=1 已发布启用，FORM_PATH 与静态办理路由一致。2026-10-14 项目 MCP 发布前核对无活动 V2 在途实例；集团版 V3（定义 ID 2110056848893235202）和二级单位版 V3（定义 ID 2110056906149679105）现均为 IS_PUBLISH=1、ACTIVITY_STATUS=1、MODEL_VALUE=CLASSICS。节点/连线数分别为 13/16、16/19，重复节点与重复连线检查均为 0；集团版 V3 无会签页面办理已结束，历史 V2 定义保留。

4.2 节点链路要点 ​

各流程节点顺序严格按设计稿第 4.2 节（原型第 4 页整体审批流程图），本文不重复抄录；节点编码在 PlanningFlowConstant 中集中定义，代码核对结论如下：

节点编码节点名称办理人配置说明
start / submit开始 / 申请人申请人submit 为退回目标与退回后重提节点
initiator_gateway（互斥网关）—条件 `eq@@initiatorType
unit_dept_leader_audit建设单位部门负责人审核${nextHandlerId}二级单位路线
center_window开投集团项目中心部门窗口${nextHandlerId}选人实现，不使用待办池
center_handler_audit开投集团项目中心经办人审核${nextHandlerId}—
center_leader_audit开投集团项目中心部门负责人审核${nextHandlerId}含「是否需要意见征求」判断（决定节点，仅储备清单/两条编制流程）
group_leader_audit开投集团项目中心部门负责人审核（集团发起路线）${nextHandlerId}集团发起下的审核/决定节点
consult_gateway（互斥网关）—条件 `eq@@needConsultation
parallel_consult_split（包含网关）—V3 源文件：运营/资产/建设三个必选分支并行；dept_other_opinion 仅在 needOtherConsultation=1 时创建
dept_operation_opinion / dept_asset_opinion / dept_construction_opinion / dept_other_opinion运营管理部/资产管理部/建设管理部/其他部门提出意见${deptOperationHandlerId} / ${deptAssetHandlerId} / ${deptConstructionHandlerId} / ${deptOtherHandlerId}已选择部门分别办理；服务端只为实际选择的部门创建记录和办理人变量
parallel_consult_merge（并行汇聚网关）—等待实际生成的分支完成后汇聚；OTHER 未选择时不等待该分支
center_handler_confirm开投集团项目中心经办人确认${centerHandlerUserId} / 自动绑定原经办人意见征求汇聚后的确认节点，后台在发起征求时动态反查原经办人审核人并注入变量绑定，确保前后为同一人办理
center_leader_confirm开投集团项目中心部门负责人确认${nextHandlerId}同上
end结束——

4.3 2026-10-14 流程与表单细节完善 ​

  1. 流程定义版本：已发布的 planning_reserve_*_v2.json 保持不变；_v3.json 以包含网关按 needOtherConsultation=1 创建 OTHER 分支。项目 MCP 已完成版本/在途/重复行核验并导入发布集团与二级单位 V3；集团版 V3 无会签路线真实页面办结，需会签路线尚未运行；
  2. 经办人动态绑定：通过 workflowQueryMapper.selectApproverByInstanceIdAndNodeCode 获取初审 center_handler_audit 办理人，注入 pass:center_handler_confirm 和 centerHandlerUserId；
  3. 会签附件持久化与回显：submitConsultationOpinion 保存附件至 PlanningAttachmentRef（bizType="CONSULTATION"），在详情 consultations 列表与页面表格中展示真实文件名并支持预览；
  4. 决策面板与流转弹窗：PlanningConsultPanel 去除平铺的审批意见与附件输入框，选择「是/否」后点击提交流转，通过标准对话框录入意见；运营/资产/建设三部门接收人必选，其他部门接收人选填；
  5. 成果附件安全预览：详情只返回 ossId 与文件名，不把短期签名 URL 暴露给业务详情调用方；用户预览时由共享预览抽屉通过带权限校验的文件查询重新取得访问地址，PDF 使用原生在线预览；元数据查询失败不影响业务详情加载。
  6. 状态跟踪阶段显示：PlanningTaskPage.vue 依据来源模块类型将建设规划映射为「建设规划阶段」、工可研究映射为「工可研究阶段」。

流程定义中不含 REJECT 连线（只读核对 planning_reserve_v1.json 等定义文件 REJECT 计数为 0），退回目标由引擎按实例历史任务与前置节点关系动态计算，符合设计稿第 4.3 节结论。

4.3 意见征求与会签 ​

  • 决定节点（center_leader_audit / group_leader_audit，且流程属于储备清单、建设规划编制、工可研究编制）在办理页选择「是否需要各部门意见征求」；选择「是」时运营管理部、资产管理部、建设管理部各选 1 名接收人，其他部门可选；接收人不得重复，提交 POST /{module}/consultation/decide。
  • 后端按已选部门写 biz_planning_consultation_batch 与 biz_planning_consultation_task（状态 PENDING；节点编码按所选部门保存），接收人姓名按用户 ID 补齐；V3 流程变量 needOtherConsultation 决定是否创建 OTHER 分支，未选择时不注入兜底办理人。
  • 储备清单 V3 流程定义在 consult_gateway 的「需要」分支后接包含网关：三个必选部门分支并行，OTHER 仅在 needOtherConsultation=1 时创建；汇聚等待实际产生的分支完成后进入 center_handler_confirm。集团/二级单位 V3 已发布；集团版「否」分支真实办理通过。需会签分支及其汇聚办理仍待页面验收。
  • 部门接收人在同一办理页的部门意见面板提交本人意见（result 固定 AGREE，退回走流程退回）：POST /{module}/consultation/opinion 的 taskId 统一为流程任务 ID（前端取 processInfo.currentTaskId），后端先完成任务、再按登录人回写本人 PENDING 明细为 DONE。此为「非最后一名会签接收人不触发流程事件」的补偿路径。
  • 部门接收人在同一办理页的部门意见面板提交本人意见（result 固定 AGREE，退回走流程退回）：POST /{module}/consultation/opinion 的 taskId 统一为流程任务 ID（前端取 processInfo.currentTaskId），后端先完成任务、再按登录人回写本人 PENDING 明细为 DONE。此为「非最后一名会签接收人不触发流程事件」的补偿路径。
  • 全部部门完成 → 批次 FINISHED → 汇聚节点继续；任一部门退回 → 批次 REJECTED，流程回到申请人节点，已完成部门意见保留在历史记录中。
  • 接口 taskId 语义：consultation/decide、consultation/opinion 为流程任务 ID；process/restart 为业务任务 ID。业务侧先由流程任务 ID 反查实例登记，再复核业务记录属于当前模块路径。

4.4 退回口径 ​

  • 普通审批节点：前端弹出引擎返回的候选节点（getBackTaskNode），默认选中第一条候选（最近前置节点），即「退回到上一节点」。
  • 决定节点与部门意见节点（PlanningConsultPanel）：优先在候选中选择申请人节点 submit，候选缺失时回退第一条候选；确认文案分别提示「流程回到业务发起人，历史意见保留」与「本轮意见征求视为未通过，流程回到业务发起人，已完成意见保留」。
  • 退回申请人节点后业务状态置 back，发起人在列表通过「编辑 → 提交」重新提交，沿用原实例与原成果版本，不新增阶段记录或版本。

4.5 审批记录与状态回写 ​

  • 流程事件（ProcessEvent）：按业务标识中 # 前的阶段记录 ID 定位业务记录；submit=true 时统一取 waiting，否则取事件状态；回写阶段记录（状态、实例、当前节点、完成时间）与任务（状态、实例、当前节点），版本状态随阶段记录同步，实例登记状态映射为 RUNNING/BACK/FINISHED/DRAFT，终态补结束时间；批次状态按 finish/back 置 FINISHED/REJECTED。
  • 任务事件（ProcessTaskEvent）：事件携带的是新生成的下一节点，因此当前节点取事件节点；审批记录取该实例最近一条已办理历史（含引擎任务 ID、节点、意见、办理人），skipType=REJECT 记 REJECT，否则 AGREE；按 engine_task_id 幂等（重复发布不重复写入）。办理人与部门以办理记录为准，取不到再回退当前登录人；发起单位取任务上的发起单位快照。
  • 会签节点的最后一名办理人完成任务时，任务事件会额外把该办理人对应的部门意见明细置为 DONE。

4.6 自动引用生成规则 ​

  • 触发条件：任务模块为分阶段管理（建设规划/工可研究）且工作阶段非空，流程状态回写为 finish 时。
  • 生成内容：状态跟踪模块的任务（businessStatus=finish），sourceType 取来源模块编码（CONSTRUCTION_PLAN/FEASIBILITY_STUDY），sourceTaskId/sourceStageRecordId 指向来源任务与来源阶段记录，复制项目关联与专题关联，remark 形如「自动引用自建设规划报审阶段」。
  • 幂等：按「状态跟踪模块 + 来源阶段记录 ID」判重。
  • 限制：不创建阶段记录、不创建成果版本、不启动流程；因此引用记录详情页无流程图与时间线数据，见第 9.1 节差异 10。

5. 权限与数据范围 ​

5.1 三段式权限码清单 ​

资源/动作菜单权限（SYS_MENU.PERMS）按钮权限（v-hasPermi）接口权限（@SaCheckPermission）数据范围越权结果
五个业务模块 list页面菜单行 planning:{module}:list—同名不做单位隔离，有页面权限即可查全部台账403
query按钮行 planning:{module}:query详情按钮同名同名（get/process-info/history）同上403
addUnit / addGroup按钮行 planning:{module}:addUnit / :addGroup工具栏「二级单位新增」「开投集团新增」（2026-09-30 起两按钮均按任一动作权限显示，发起方式由所点按钮决定）两个端点均按 SaMode.OR 接受 addUnit/addGroup 任一发起方式由端点固定；发起单位记录规则见第 3 节状态表，不再做部门归属拦截403
edit / submit / remove / export / process按钮行同名修改、提交、删除、导出、办理面板同名记录级权限见 5.3403 或业务异常
任务台账 / 项目台账按钮行 planning:ledger:task / planning:ledger:projectplanning:ledger:task / planning:ledger:project（5 个列表页共用）同名（5 个业务控制器共用）同上403
manage按钮行 planning:{module}:manage—无接口记录级权限判定（StpUtil.hasPermission）不适用
专题类型目录页面菜单行 planning:topicType:list新增/修改/删除/详情/关联项目同名同名全局配置数据403
流程实例重启按钮行 planning:process:restart（挂 规划管理 下）详情页「重启实例」按钮同名（5 个控制器共用）当前仅规划管理管理员角色被授权403

5.2 角色 ​

开发库已建立三个规划管理角色并按菜单/按钮授权：规划管理发起人（planning_initiator，64 条规划管理菜单）、规划管理审批人（planning_approver，42 条）、规划管理管理员（planning_admin，77 条，含 planning:process:restart）。角色与账号的其他范围（如部门归属）见设计稿第 5.3、6.3 节。

按角色划分的实际能力：发起人负责新增、暂存、提交与退回重提；审批人按节点办理（含意见征求决定与部门意见）；管理员额外具备重启实例与全部台账/配置能力。查看人员由 list/query 授权范围决定。

5.3 记录级权限 ​

场景判定实现位置结果
草稿编辑/删除创建人（initiatorUserId 等于当前登录人）或具备 planning:{module}:manage，且状态为 draftassertOwnership + 状态校验不满足抛「仅创建人或具备管理权限的人员可以…」/「仅草稿状态的任务可以删除」
退回编辑/重提同上归属校验，状态为 backassertOwnership + 状态校验不满足同上
进行中编辑列表/台账返回 canEdit（创建人或 manage），前端只在 waiting && canEdit 时显示编辑enrichList / 项目台账后端仍按上述归属与状态校验兜底
进行中办理平台按任务归属：currentTaskId 由「业务标识 + 当前登录人」查询得到，无待办不显示「办理」；意见征求接口另做 assertCurrentTaskPlanningWorkflowHelper非当前办理人：无办理面板、接口拒绝
已通过只读业务表单页面只读，编辑入口不显示；后端拒绝非草稿/退回状态的修改前端行操作 + 后端状态校验403/业务异常

5.4 数据范围与依赖 ​

  • 默认不做单位隔离：具备页面权限即可查询全部台账；发起单位/填报单位字段用于展示与审批记录区分（是否按二级单位隔离仍为待澄清项，见设计稿第 6.3 节）。
  • 未启用工程范围（UserDataScopeHelper）过滤；项目关联按 biz_project 项目 ID + 名称快照存储，查询时经关联表按项目过滤。
  • 运行期权限依赖（设计稿第 5.3 节已实测）：business:project:query（项目下拉）、workflow:instance:query（流程图与审批时间线）、workflow:definition:list（流程图定义）、system:oss:query（时间线附件）。补授权限须经「角色管理 → 授权保存」触发权限缓存失效，直接写库不生效。

6. 前端约定 ​

6.1 业务标识与 URL 编码 ​

  • 引擎业务标识为 {阶段记录ID}#{实例序号}（businessIdOf），保证同一阶段记录的重启实例不产生 business_id 歧义；状态跟踪自动引用记录不产生实例。
  • 标识含 #，前端查询流程历史/时间线的路径段必须 URL 编码：api/workflow/instance/index.ts 中 flowHisTaskList 使用 encodeURIComponent(String(businessId))，否则时间线恒为空。
  • 详情接口同时接受业务任务 ID 与业务标识：列表/详情入口传任务 ID，办理页只读视图与时间线传业务标识。

6.2 大整数 ID ​

  • 后端统一 BigNumberSerializer（超出 JavaScript 安全范围输出字符串）；前端 ID 类型保持 string | number，不得使用 Number()、parseInt() 或一元 +。
  • 详情回填时保留列表中的原始 ID（编辑请求按当前记录完整主键提交）；办理页跳转参数以 String(id) 传递。

6.3 固定路由注册三处 ​

新增或调整 flowCode 时，以下三处必须同时登记，漏登会导致待办点「办理」报「当前流程未配置办理页面」或落到 404：

  1. digital-construction-ui/src/router/flowFormRoutes.ts：静态路由定义（path、懒加载组件、title 使用「流程定义名称 + 办理」、name 唯一，规划管理 9 条 FlowFormPlanning*）；
  2. digital-construction-ui/src/router/flowFormPaths.ts：路径集合，供权限路由跳过重复注册（菜单中同名办理页不再注册）；
  3. digital-construction-ui/src/api/workflow/workflowCommon/index.ts 的 flowCodeFormPathMap：flowCode → 办理路径 映射，供工作台 routerJump 解析。

另外两处固定注册（不依赖菜单授权）：src/router/index.ts 中的 /planning/projectHistory（项目历史数据）与流程设计器、代码生成内部地址；办理页族的注册入口见 flowFormRoutes.ts。

6.4 组件与文案 ​

  • 列表页共用 PlanningTaskPage.vue；新增/编辑共用 PlanningTaskForm.vue；办理页共用 PlanningFlowForm.vue + usePlanningFlowWorkspace.ts；意见征求共用 PlanningConsultPanel.vue。
  • 模块编码 ↔ 请求路径段、flowCode、成果明细列名集中在 views/business/planning/planningFlow.ts；成果明细列名按模块与阶段取值（前期储备研究成果文件 / 进度成果文件 / 线网规划成果文件 / 建设规划编制阶段文件 / 建设规划报审成果文件 / 建设规划批复成果文件 / 工可研究编制阶段文件 / 工可研究报审成果文件 / 工可研究批复成果文件）。
  • 快捷意见统一为 请审核. 无意见. 拟同意. 同意.（PLANNING_APPROVAL_OPINIONS），仅在规划管理办理页生效。
  • 办理页：左表单只读（含成果明细、成果版本表、附件预览；线网规划不显示项目名称；已按 2026-10-09 清单去掉备注），右审批时间线；type=view 为只读详情，type=approval 且为当前办理人时展示办理面板；意见征求决定节点与部门意见节点不显示通用办理面板，改为意见征求面板（PlanningConsultPanel.vue），全部部门意见在「各部门意见征求情况」卡片中只读展示。

7. 异常、事务与并发 ​

场景检测位置用户提示回滚/补偿日志与告警测试用例
重复提交控制器 @RepeatSubmit + 服务层状态校验（draft/back 之外拒绝）+ FlwTaskServiceImpl.startWorkFlow 的 @Lock4j(flowCode + businessId)「当前状态不支持提交」或重复提交拦截提示事务回滚，不产生第二个实例@Log 操作日志PlanningTaskServiceImplTest（本机执行受阻，见第 8.3 节）
并发修改修改/提交前重新读取任务并校验状态与归属「仅草稿或退回状态的任务可以修改」不覆盖已变更记录操作日志同上
发起方式伪造后端端点为 add/secondary-unit 与 add/group，服务端常量决定 initiatorType；edit/submit 校验与记录一致「发起方式不可变更」事务回滚操作日志同上
流程启动/办理失败PlanningWorkflowHelper 对返回 false 抛业务异常「流程发起失败」/「任务办理失败」事务回滚，业务状态不倒挂工作流日志同上
非当前办理人操作currentTaskId + assertCurrentTask（意见征求接口）「该任务不是您的待办，无法办理」无数据变化操作日志同上
会签部门意见漏回写提交入口按登录人回写本人 PENDING 明细（不依赖流程事件）；事件回写作为最后一名办理人的补充路径无提示（正常完成）明细状态不一致时以本人明细为准无PlanningProcessEventListenerTest（本机执行受阻）
专题类型被引用后删除PlanningTopicTypeServiceImpl.remove 统计任务主表引用「专题类型「…」已被任务引用，不能删除，可改为停用」事务回滚操作日志待补（无自动化覆盖）
引用重复生成createStatusTrackingReference 按「状态跟踪模块 + 来源阶段记录」判重无提示幂等返回无同上
重启实例服务层校验阶段记录存在；事务内先置旧实例 SUPERSEDED 再新建「阶段记录不存在」等事务回滚，旧实例保留原状态操作日志同上

8. 实现映射与验证 ​

8.1 实现位置 ​

责任代码位置验证方式证据
后端控制器digital-construction-business/src/main/java/com/bokun/business/planning/controller/（6 个：5 个模块 + 专题类型）本轮只读核对（路径、方法、权限码、@Log、@RepeatSubmit）逐方法比对结果见第 2 节；未执行接口调用
后端服务service/impl/PlanningTaskServiceImpl.java、PlanningTopicTypeServiceImpl.java只读核对业务规则与校验；端到端验证见设计稿第 6.2 节规则条文见第 3、5 节
流程接入workflow/PlanningFlowConstant.java、PlanningWorkflowHelper.java、PlanningProcessEventListener.java只读核对；流程定义与库内状态由开发库回读9 条定义 VERSION=1/IS_PUBLISH=1，REJECT 连线数为 0
枚举与辅助enums/（模块类型、工作阶段、发起方式、部门类别）、helper/PlanningInitiatorResolver.java只读核对—
前端接口与映射digital-construction-ui/src/api/business/planning/{index.ts,types.ts}、views/business/planning/planningFlow.ts只读核对（URL 与后端逐字一致）82 条接口调用与权限码比对结果见第 2 节
前端页面与路由views/business/planning/**、router/flowFormRoutes.ts、router/flowFormPaths.ts、api/workflow/workflowCommon/index.ts、router/index.ts只读核对三处注册齐全；/planning/projectHistory 已静态注册
数据库与注册数据13 张 biz_planning_* 表、77 条规划管理菜单/按钮行（1 个一级目录 + 2 个子目录 + 1 个重启按钮行 + 5 个业务页面 + 9 个办理页 + 1 个专题类型目录 + 58 个按钮行）、6 个字典类型、9 条流程定义、3 个角色开发库只读回读（MCP dcp-dm8-dev）回读结果见第 5.1、5.2、6.3 节与设计稿第 5.3 节；角色在本模块的授权行数为 64（发起人）/42（审批人）/77（管理员）

8.2 验证结论（按范围表述） ​

  • 本文档为只读核对产物：接口路径、权限码、菜单路径、流程定义与角色授权以代码与开发库回读为准，未执行测试、构建或页面操作。
  • 主链路验证结论沿用设计稿第 6.2 节（2026-09-20 端到端复验）：五个模块与阶段变体走到「已通过」、逐条审批记录齐全、会签部门意见各自落库、退回重提与会签退回按口径生效、自动引用生成 5 条。该结论属 Agent 验证通过范围，不构成业务验收通过。

8.3 验证受阻与未覆盖 ​

  • 后端 13 项规划测试（PlanningTaskServiceImplTest 5 项、PlanningProcessEventListenerTest 8 项）在本机因 Mockito 插件加载失败报错，属验证受阻，不得记为通过；受影响结论以端到端页面与真实接口验证替代。
  • 附件上传交互在内置浏览器不可验证（不支持文件选择）；附件随办理提交写入流程历史 ext（已用真实 ossId 验证），附件展示依赖 system:oss:query。
  • 本文档未验证：跨浏览器表现、导出文件实际内容、会签 nodeRatio=100 的全签语义与退回候选在运行时的实际返回内容、自动引用记录详情页的空流程表现（只读核对结论，见第 9.1 节差异 10）。

9. 与设计稿的不一致及待确认项 ​

9.1 设计稿与代码不一致（按代码记录，含已修复项） ​

  1. 流程编码解析签名：设计稿第 4.1 节写 flowCodeOf(moduleType + workStage + initiatorType)；代码为 PlanningFlowConstant.flowCodeOf(PlanningModuleType, PlanningWorkStage)，不含发起方式——发起方式由流程内 initiator_gateway 互斥网关按变量分流，与「一张图同时画两种发起方式」的确认口径一致。
  2. 台账权限码（已修复）：原代码（后端 @SaCheckPermission 与前端 v-hasPermi）使用 planning:{module}:taskLedger / planning:{module}:projectLedger，与 SYS_MENU 及角色授权中的 planning:ledger:task / planning:ledger:project 不一致，且菜单中不存在前者。2026-09-20 已按菜单与角色授权口径统一为 planning:ledger:task / planning:ledger:project：后端 5 个控制器注解与前端 PlanningTaskPage.vue 两处指令均改为该口径，菜单、注解与指令三处逐字一致（改动随本次一并提交）。
  3. 暂存接口：设计稿第 2.3 节列 POST /{module}/draft；实际新增/暂存走 POST /{module}/add/secondary-unit、POST /{module}/add/group，编辑/退回暂存走 PUT /{module}/edit，无独立 draft 接口。
  4. 成果版本查询接口：设计稿第 2.3 节列 GET /{module}/version/list/{stageRecordId}；实际未提供该接口，版本随 GET /{module}/get/{id} 的 versions 字段返回。
  5. 退回口径：设计稿第 4.3 节表述为「退回到上一节点」；代码在决定节点与部门意见节点优先选择申请人节点 submit，仅当候选中不存在 submit 时回退第一条候选，确认文案与设计稿「任一部门退回 → 回到业务发起人」一致。
  6. 详情页意见征求信息（已修复）：PlanningFlowForm.vue 已补充渲染「各部门意见征求情况」明细卡片与表格，直观展示各部门名称、办理人、办理状态、结果标签、意见说明与办理时间，与用户确认的业务口径一致。
  7. 导出列枚举转换（已修复）：后端 PlanningTaskServiceImpl.listForExport 已统一将工作阶段、审核状态、发起方式由英文枚举（COMPILATION/waiting/GROUP 等）转换为规范业务中文（「编制阶段」、「进行中」、「开投集团发起」等）。
  8. 专题类型目录路由（已修复）：已在 src/router/index.ts 静态注册 /planning/planningSubmission/topicType 固定路由，与 /planning/projectHistory 口径一致，避免隐藏菜单未授权时按钮跳转 404。
  9. 状态跟踪项目台账范围：设计稿第 2.2 节表述为「汇总引用建设规划、工可研究的项目台账数据（含状态跟踪新建的项目任务数据）」；实现按 moduleType IN (STATUS_TRACKING, CONSTRUCTION_PLAN, FEASIBILITY_STUDY) 聚合，即展示建设规划/工可研究的全部任务（不限已通过或已产生引用的任务）。范围比文案更宽，需业务确认。
  10. 自动引用记录的详情与重启（已加固）：usePlanningFlowWorkspace.ts 中的 canRestart 计算属性已增加 Boolean(processInfo.businessId || processInfo.instanceId) 校验，针对自动引用记录等无流程实例任务不再展示重启入口，从前端根绝了点击重启报「阶段记录不存在」的问题。
  11. 成果版本的兜底新增分支：设计稿第 3 节表述为「退回重提、重启实例复用同一条版本，不新增版本行」；代码 editableVersion 在实际取用的最新版本 approvalResult=finish 时会插入 versionNo+1 的新版本。当前页面入口不支持「已通过」后再编辑或提交，该分支在现有入口下不可达，属代码保留的兜底路径（见第 3 节末段）。
  12. 菜单行数：设计稿第 5.3 节按当时口径记录菜单/按钮行数量；本轮开发库回读为 77 行（构成见第 8.1 节），以回读结果为准。

9.2 待确认项 ​

  • 会签后确认节点办理人：center_handler_confirm / center_leader_confirm 的办理人为流程变量 ${nextHandlerId}；决定节点提交（completeWithConsultation）不写该变量，确认节点沿用上一标准办理节点选择的「下一办理人」残留值，是否符合业务预期待确认。
  • 非最后一名会签接收人的任务事件缺失：已通过「提交入口按登录人回写本人明细」解决（submitConsultationOpinion 先完成任务再回写 PENDING 明细）；历史上仅靠流程事件回写产生的数据是否需要补偿，待确认。
  • 「其他部门」征求意见的选择范围与数量上限（代码未设限，默认按设计稿：任意启用部门、上限 3）。
  • 导出列最终口径与枚举是否需要中文转换。
  • 状态跟踪项目台账是否应收窄为「引用记录 + 状态跟踪任务」，以及自动引用记录的详情/重启入口处理方式。
  • 是否需要正式环境启用运营管理部、资产管理部、项目中心等部门（沿用设计稿第 6.3 节）。
  • 13 张 biz_planning_* 表的字段矩阵已见数据库设计；后续结构变化按实际代码与项目 MCP 回读核对。

已关闭项：台账权限码口径于 2026-09-20 统一为共用权限码 planning:ledger:task / planning:ledger:project（后端注解与前端指令已对齐菜单与角色授权口径），不再列为待确认；本条保留以保留变更痕迹。

10. 变更记录 ​

版本日期变更原因/来源确认人
v0.12026-09-20建立规划管理详细设计：页面与路由清单（5 个列表页含台账视图、专题类型目录、9 条办理页固定路由、项目历史数据）、82 条接口契约（业务任务 75 + 专题类型 7，按资源逐项核对权限码与方法）、流程接入（flowCode 解析、节点编码、意见征求会签、退回、审批记录回写、自动引用、重启）、权限与数据范围、前端约定（业务标识 URL 编码、大整数 ID、三处固定路由注册），并记录 10 项设计稿差异与 7 项待确认模块简报与设计稿基线 + 只读核对当前代码与开发库菜单/权限/流程定义/字典数据待业主确认
v0.22026-09-20复核修正：菜单/按钮行数按开发库回读更正为 77 行并列出构成与角色授权行数；删除接口的级联范围明确为任务、阶段记录与两张关联表（成果版本/明细/附件不级联）；补充 editableVersion 在最新版本已通过时新增版本号的兜底分支及其当前不可达结论；差异清单由 10 项扩为 12 项6 个 Controller、服务实现、流程监听器、前端接口与路由逐项只读核对，以及开发库 MCP 回读（菜单树、角色授权、9 条流程定义、6 个字典类型、13 张业务表）待业主确认
v0.32026-09-20同步台账权限码口径修复：第 2.1、2.2、5.1 节改为跨模块共用权限码 planning:ledger:task / planning:ledger:project；第 9.1 节差异 2 改为「已修复」，第 9.2 节移出该待确认项；另按代码更正测试用例数为 5 项 + 8 项代码核对（5 个控制器注解与 PlanningTaskPage.vue 指令口径已统一）、需求分析与概要设计同步口径待业主确认