主题
工程投资管理 · 概要设计文档
文档版本：0.11 ｜ 最近核对日期：2026-11-09
本文面向设计评审、实现和验收，确定模块在平台中的定位、模块边界与相邻模块关系、模块分解、页面与路由、数据模型概览、流程概览、权限方案和关键技术决策，不展开字段级、参数级与类级实现；字段矩阵、接口参数与流程定义 JSON 细节进入数据库设计与详细设计。
本文为概要设计基线：用户已授权未决项按推荐默认确定。代码、开发库结构、菜单与流程已按本文件及需求分析第 8.2 节实施；业务主链路与真实页面的验收边界见测试报告。
文档控制
| 项目 | 内容 |
|---|---|
| 模块名称 | 工程投资管理 |
| 实现进度说明 | 页面、接口、流程和数据库设计资料已完成；验证证据及剩余范围见测试报告 |
| 编写日期 | 2026-09-21 |
| 受测代码状态 | 2026-09-27 main 工作区；后端编译与 21 项 API 端到端检查通过；真实浏览器页面未验收 |
| 业务确认人 | 用户授权按推荐默认确定（2026-09-27） |
| 关联需求分析 | 工程投资管理需求分析 |
1. 模块在平台中的定位与复用
工程投资管理是工程投资业务的一级业务模块，与规划管理、工程变更监管、招投标监管、开投安质环监管同级，挂在「工程投资管理」一级菜单下，下设「投资计划」与「投资实施」两类入口（原型菜单层级）。模块不新建用户、组织、权限、文件或工作流体系，全部沿用平台既有能力：
| 复用能力 | 复用内容 | 本模块的使用方式 |
|---|---|---|
| Warm-Flow | 流程实例、任务、退回、流程图与办理工作台 | 三条流程对应计划上报、计划下发修改、实施上报；各链路及选填节点跳过规则见第 6 节。红头台账维护和分配提交不另启流程 |
| 流程事件与回写 | 流程状态事件、任务事件 | 业务单据监听流程事件回写 draft/waiting/back/finish；审批历史以流程引擎记录为准。实施实际仅在审批通过时计入台账 |
| 权限体系 | 三段式权限码、菜单与按钮权限、角色授权 | investment:<资源>:<动作>；后端注解、菜单权限串与前端指令三处逐字一致，按模块岗位授权，不新增单位/部门数据隔离 |
| 文件服务 | 文件上传与对象引用、文件预览与查询 | 红头文件与明细批量上传附件保存文件服务对象引用，单份红头文件限制 50MB 与限定格式 |
| 字典 | 行业、建设阶段、是否市级重点、业务状态、审批结果 | 行业先沿用截图观察值；阶段「续建、开工」标为暂定选项；标识用「是/否」。状态使用稳定编码映射为中文 |
| 项目主数据 | 业务项目（含线路口径） | 复用已解耦业务项目/线路选项，业务 ID 与显示名称、编码均留快照 |
| 组织与用户 | SYS_DEPT 组织树、平台用户 | 发起单位、发起部门、责任部门各引用所选组织节点并保存 ID+名称快照；发起部门默认当前用户部门，发起单位沿用户部门向上解析最近业主集团/公司/分公司/合资公司（orgType=group/company/branch/joint_venture）；部门不作单位，审批与接收人通过平台用户选择器选择 |
| 平台页面与组件 | 列表页模板、用户选择、文件上传、字典标签、分页与导出 | 台账、表单、上报记录与按月展开的明细列按既有模式组装 |
模块自身承担的部分：年度投资计划及项目明细、责任单位/部门金额分解、上报确认标记、版本化计划调整、年度红头文件台账与下发对象分配、投资实施月度上报和计划实际对照。审批任务和审批历史复用 Warm-Flow，不重复维护平台已有流程账本。
2. 模块边界与相邻模块关系
本模块负责：
- 投资计划上报单、项目明细、责任单位/部门分解与次年月度计划金额；
- 投资计划确认（是否上报一致标识、调整计划）与投资计划下发（下发记录与红头文件台账）；
- 下发计划修改的明细与金额调整；
- 投资实施月度上报记录、计划与实际对照、月度与累计完成率；
- 业务提交校验、流程启动与办理、状态回写、审批记录；
- 台账查询、六个年度汇总指标、合计行、明细内联编辑与导出；
- 菜单、字典、权限码、角色授权、流程定义与办理页路由注册。
本模块不负责：
- 用户、角色、部门、岗位与权限授权维护；
- 项目主数据与工程结构树（线路、包段、标段、单位工程）的维护；
- 通用待办、委托、转办、加签、减签与流程引擎本身；
- 财务、资金支付、合同与造价系统的对接；
- 待办提醒（站内信/短信）与图形化看板。
与相邻模块的关系：
| 相邻对象 | 关系 |
|---|---|
| 规划管理 / 工程变更监管 / 招投标监管 / 开投安质环监管 | 同级业务模块，互不调用；共用平台流程工作台与台账模板 |
| 平台流程中心（待办、流程图、流程定义） | 待办与办理入口由平台提供，本模块提供办理页与业务办理接口；办理页按流程定义注册 |
| 项目主数据 | 只读引用项目与线路，保存名称/编码快照，不做维护 |
| 文件服务 | 只读引用文件对象标识，不管理文件实体生命周期 |
| 组织与用户 | 只读引用部门与用户，用于发起单位解析与审批人选择 |
3. 模块分解
| 子模块/能力 | 职责 | 上游输入 | 下游输出 |
|---|---|---|---|
| 投资计划上报 | 年度上报单头部、项目明细、责任部门分解与次年月度计划金额 | 上报年度、发起单位/部门/经办人、明细与月度金额 | 草稿或已提交的上报单 |
| 计划汇总与合计 | 头部只读汇总值、阶段金额与完成率、责任部门小计与两类合计行 | 明细与月度金额 | 头部汇总值、合计行 |
| 明细批量导入 | 下载 .xlsx 模板，批量上传、整批校验与错误行反馈 | 模板文件 | 全部明细或带行号的失败报告（失败批次不落部分数据） |
| 上报确认与调整 | 是否上报一致标识、调整计划 | 上报结果与确认判定 | 确认结果与调整后的计划数据 |
| 投资计划下发 | 下发记录（计划项目、责任单位/部门、分公司经办人、备注）与红头文件台账 | 计划项目、年度与文件 | 下发记录与红头文件清单 |
| 下发计划修改 | 沿用上报结构的明细与金额调整 | 台账带出金额与调整值 | 修改后的下发计划 |
| 投资实施上报 | 月度计划与实际完成填报、累计口径计算 | 上报月份、计划本月投资、实际完成投资 | 月度上报记录与台账回写 |
| 实施对照台账 | 按月对照计划与实际，计算月度、累计与年度完成率 | 月度上报记录与计划分解 | 台账列值与当前上报月份 |
| 审批记录与流程登记 | 逐节点审批记录快照与流程实例查询 | 流程事件与引擎办理记录 | 审批记录、流程历史 |
| 页面与路由 | 三个台账、上报/下发表单、下发修改、实施上报与上报记录 | 菜单与路由注册 | 可操作的业务页面 |
4. 页面与路由清单
业务确认三类台账和对应的表单/记录页面，审批页面共三类。普通业务菜单由 SYS_MENU 动态注册；流程办理入口为跨业务的静态路由，路由与流程定义的办理路径固定一致（Q-EI-016）。
| 菜单/入口 | 路由 | 组件 | 说明 |
|---|---|---|---|
| 工程投资管理（目录） | /investment | — | 一级菜单 |
| 投资计划（目录） | /investment/plan | — | 二级目录 |
| 投资计划上报 | /investment/plan/report | business/investment/plan/report/index | 台账 + 六个汇总指标 + 明细与次年月度分解列；项目字段在草稿/退回时按权限内联维护 |
| 投资计划确认 | /investment/plan/confirm | business/investment/plan/confirm/index | 同上口径 + 是否上报一致 + 调整与下发入口；调整在台账内编辑 |
| 投资计划下发（红头文件台账） | /investment/issue | business/investment/issue/index | 目标年度查询、年度多附件列表、分摊填报对话框；提交即生效 |
| 投资实施 | /investment/implementation | business/investment/implementation/index | 台账 + 月度计划/完成/完成率列 + 实施上报/上报记录入口 |
| 投资实施上报记录 | /investment/implementation/records | business/investment/implementation/records/index | 历史上报列表与详情/修改/删除；新建或修改表单从列表入口打开 |
| 计划上报办理页 | /investment/plan/report/flowForm | business/investment/flowForm/planReport | 静态路由；investment_plan_report |
| 计划下发修改办理页 | /investment/plan/issueModify/flowForm | business/investment/flowForm/issueModify | 静态路由；investment_plan_issue_modify |
| 实施上报办理页 | /investment/implementation/report/flowForm | business/investment/flowForm/implementationReport | 静态路由；investment_implementation_report |
页面职责分工：三个台账共用查询条件与六个汇总指标，其中投资计划上报台账与确认台账共用明细列组（次年建设阶段与次年月度分解），投资实施台账改用本年建设阶段与月度计划/完成列组；投资计划上报与下发计划修改表单共用明细网格组件（责任部门行内新增、阶段汇总公式）；审批人员选择区按链路配置字段（三条链路的人员集合不同）。
5. 数据模型概览（概要级设计）
模块业务数据采用结构化表，具体字段、约束、索引和实际建表状态以数据库设计文档及项目 MCP 回读为准。本表表达已确定的实体边界；七张业务表结构已在开发库建立。
| 表 | 职责（一句话） |
|---|---|
BIZ_INVEST_PLAN | 投资计划主表：基准上报年度、目标年度（上报年+1）、发起组织/人员快照、汇总值、REPORT/MODIFY 类型、来源/前版本/版本号/当前版本关系、一致标记、业务状态与流程业务标识 |
BIZ_INVEST_PLAN_ITEM | 计划项目明细：项目/线路引用与快照、行业、建设阶段、市级重点标识与四项金额 |
BIZ_INVEST_PLAN_SPLIT | 责任单位/部门分解：引用项目明细，保存组织 ID+名称快照、责任金额及目标年度 1—12 月金额列；完成率动态派生 |
BIZ_INVEST_ISSUE | 目标年度红头文件台账头：每年一条，可附多份文件 |
BIZ_INVEST_ISSUE_FILE | 年度红头文件附件引用：文件服务对象 ID、名称快照与上传时间 |
BIZ_INVEST_ISSUE_ALLOCATION | 计划分解下发记录：年度台账、当前计划拆分、接收用户 ID+名称快照、备注、提交生效状态；每个分解行单条当前分配 |
BIZ_INVEST_IMPLEMENTATION | 月度实施记录：下发分解关联、目标年度、月份、计划/实际金额、申请人与业务状态；每个分解行/年/月至多一条 |
设计要点（字段矩阵与实现证据在数据库设计资料中记录）：
- 三层计划结构：上报单 → 项目明细 → 责任单位/部门分解 → 月度金额。明细与分解为一对多，分解与月份为一年 12 个金额，避免把月度金额横向铺平到明细行而丢失责任部门维度。
- 计划与实施分离：基准年 N 上报，计划与实施落在目标年度 N+1；实施记录绑定当前已下发的责任部门拆分，计划月金额从 12 个月列读取，仅已通过实际计入台账。
- 下发的文件与对象分离：每个目标年度一条红头台账，可引用多份平台文件；每个计划拆分单独绑定接收人并即时生效。
MODIFY流程通过后，主表切换到新版本，并将有效下发关联重绑到新版本对应拆分，旧版本与审批历史保留。 - 结构化落库：项目明细、拆分、附件引用、下发分配与实施月报均为结构化表；审批历史与实例以 Warm-Flow 为准，不新增与引擎重复的审批/实例表。
- 逻辑删除与唯一性：同一计划内项目唯一；当前版本每个计划拆分一条下发分配；实施上报按计划拆分+目标年度+月份唯一，并在服务端事务内保证并发下唯一。
- 金额口径：全部金额单位亿元、
DECIMAL(18,2)，完成率动态派生为实际/计划并保留两位小数，零分母显示「—」。
6. 流程概览
原型在投资计划上报、下发计划修改和投资实施上报三张表单中显示审批人员选择区；按推荐默认确定为三条 Warm-Flow 流程。红头文件年度台账的提交保存台账记录；下发分配表单提交即生效，均不另启审批流程。
| # | 流程编码 | 所属页面 | 节点链路 | 状态 |
|---|---|---|---|---|
| 1 | investment_plan_report | 投资计划上报 | 申请人 → 经办部门副部长（选填）→ 经办部门负责人（必填）→ 交建公司经办人（必填） | 已按推荐默认确定 |
| 2 | investment_plan_issue_modify | 下发计划修改 | 申请人 → 工程管理部经办人（必填）→ 工程管理部副部长（选填）→ 工程管理部部长（必填）→ 工程管理部分管领导（必填）→ 交建公司经办人（必填） | 已按推荐默认确定 |
| 3 | investment_implementation_report | 投资实施上报 | 申请人 → 工程管理部经办人（选填）→ 工程管理部副部长（选填）→ 工程管理部部长（必填） | 已按推荐默认确定 |
以下为业务链路；图示未展开可选节点的路由判断细节。未选择选填人员时通过互斥条件跳过该节点，避免生成无人可办任务。退回由流程引擎按实例历史处理，退回申请人后修改并沿用原实例重提。
流程设计遵循的原则：
- 审核节点一律「选人」：节点办理人由表单或办理时的「选择审批人员」确定并注入引擎变量，不使用部门/角色待办池。
- 非必填审批人员未选择时跳过该节点；选择时按表格中的原顺序办理。工程管理部经办人和副部长在实施上报中为选填，在下发计划修改中按各自页面红色必填标记分别处理。
- 退回不画固定连线：流程引擎按实例历史退回申请人节点；业务状态置
back，发起人修改后沿用原实例重新提交。 - 幂等：提交接口声明重复提交拦截，业务侧在启动前校验既有实例并加锁；审批记录按引擎办理记录幂等。
- 流程定义资产以 JSON 形式随代码维护，导入后发布并回读节点与连线核对；办理页路径同时登记在流程定义中。
7. 核心运行流程与状态模型
下图和状态表为已采用的需求基线；三条流程、年度映射、下发时点与实施回写均按需求分析第 8.2 节的推荐默认执行。业务状态与流程实例状态分别管理。
| 业务状态 | 进入条件 | 允许角色 | 可执行动作 | 离开条件 |
|---|---|---|---|---|
| 草稿 | 暂存，未启动流程 | 创建者或具备管理权限者 | 编辑、删除、提交 | 提交校验通过并启动流程 |
| 进行中 | 流程已启动或退回后重新提交 | 当前节点办理人（其余人只读） | 按节点办理、退回、查看流程图与审批历史 | 全部节点通过；或退回申请人节点 |
| 退回 | 流程退回至申请人节点 | 创建者或具备重新办理权限者 | 修改、重新提交 | 重新提交后回到进行中 |
| 已通过 | 该单据流程结束 | 授权查看人员 | 查看、导出；计划进入确认/下发，实施实际计入台账 | 终态；计划调整通过新 MODIFY 版本留痕，不覆盖本版本 |
业务状态使用 draft/waiting/back/finish，中文在表单和详情中展示；原型台账未展示状态列，故不额外增加。当前节点与办理人从 Warm-Flow 有效任务解析；红头文件台账和下发分配无流程状态。
8. 接口职责概览
| 能力 | 调用方 | 接口职责 | 关键输入/输出 | 权限边界 |
|---|---|---|---|---|
| 台账查询 | 上报/确认/实施台账 | 按查询条件分页返回明细与阶段/月度列组 | 查询条件、分页 | 各台账查询权限 |
| 年度汇总指标 | 三个台账 | 返回六个年度汇总指标 | 查询条件（年度） | 各台账查询权限 |
| 明细维护 | 上报表单、下发表单、下发修改 | 明细行、责任部门分解行与月度金额的新增/修改/删除 | 上报单标识、明细集合 | 新增/修改权限 |
| 明细批量导入 | 上报表单 | 解析模板文件并返回导入结果 | 模板文件 | 新增权限 |
| 模板下载 | 上报表单 | 下载明细模板 | — | 查询权限 |
| 暂存与提交 | 计划上报、下发修改、实施上报、红头台账与下发分配 | 暂存保存草稿；三类业务申请提交时启动 Warm-Flow；红头台账提交保存，接收分配提交即生效 | 业务表单、选人变量（适用时） | 对应新增/修改/提交权限及状态/任务校验 |
| 审批办理 | 办理页 | 由平台流程接口完成节点办理，业务侧回写审批记录与状态 | 流程任务、意见 | 审批办理权限 + 任务归属校验 |
| 计划确认与调整 | 确认台账 | 确认人员显式维护一致标志；计划调整以 MODIFY 新版本保存 | 上报单、一致标记、新版本内容 | 一致维护/调整权限；「是」才允许下发 |
| 计划下发 | 确认台账、下发页 | 为年度红头台账的计划责任部门分解创建唯一接收分配，提交即生效 | 目标年度、计划拆分 ID、接收用户、文件 | 下发权限；一致标记必须为「是」 |
| 红头文件台账 | 下发页 | 年度维度的文件查询、修改与删除 | 年度、文件标识 | 下发权限 |
| 实施上报 | 实施台账、上报页 | 按计划拆分 ID+计划年度+月份唯一保存，审批通过时计入计划/实际对照与累计统计 | 下发分解标识、计划年度、月份、实际金额 | 实施上报权限与流程任务校验 |
| 上报记录 | 上报记录页 | 按月份倒序返回历史上报，支持详情/修改/删除 | 项目标识、月份 | 实施上报/查询权限 |
| 导出 | 三个台账 | 按当前查询与数据范围导出 | 查询条件 | 导出权限 |
接口路径、字段校验与流程办理细节在详细设计中展开。
9. 权限与安全边界
- 权限码采用
investment:<资源>:<动作>三段式，资源为planReport、planConfirm、planIssue、implementation、implementationRecord，动作使用list/add/edit/delete/submit/approve/export/consistency/issue/adjust；Controller 以StpUtil.checkPermission(...)校验、菜单权限串与前端指令逐字一致，前端隐藏按钮不代替鉴权。 - 沿用本模块岗位权限，不新增单位/部门数据隔离；单位和部门仅为用户可指定的查询条件。服务端仍验证每个动作的业务权限、单据状态与 Warm-Flow 当前任务归属。
- 记录级权限：草稿仅创建者或管理权限者可编辑删除；进行中仅当前处理人可办理节点动作；终态只读。
- 当前节点办理资格以引擎有效任务与业务标识校验为准，前端不传办理人决定归属。
- 模块依赖的平台权限（项目查询、流程实例与流程图查询、文件查询）需随角色一并授予；权限按用户缓存，补授必须经角色授权保存触发缓存失效。
- 敏感数据处理：文档与页面不出现账号口令；红头文件与附件保存对象引用，接口与日志不输出完整文件地址与外部凭据；批量上传模板与文件名不落敏感信息。
10. 异常、事务与幂等
- 草稿保存与流程启动分离：暂存允许数据不完整，提交必须完成全量业务校验（含明细必填项与审批人员必填项）。
- 提交在事务内完成业务保存、流程启动或继续与状态回写；流程启动失败回滚业务提交。
- 明细批量导入按批次原子校验：任一非法行都拒绝整批，返回行号与原因，不写部分业务数据。
- 实施上报按下发拆分行+目标年度+月份唯一，在同一事务内保存月报与流程业务状态；只有流程通过时实际才进入台账累计，修改草稿/退回记录时重算对应月与后续累计。
- 流程事件幂等更新业务状态，审批历史读取 Warm-Flow 原始办理记录，不重复写一套流程账本。
- 年度红头台账与文件引用在同一事务内写入；文件上传失败不产生仅含元数据的下发分配。
- 外部依赖（文件服务、项目主数据、组织数据）不可用时拒绝相应操作并给出提示，不写入占位成功记录。
- 日志包含业务标识、流程实例、节点、操作者与结果，不记录凭据或完整敏感附件地址。
11. 关键设计来源与决策依据
| 来源 | 用途 |
|---|---|
| 《工程投资管理原型截图》21 张页面图（2026-09-20） | 业务内容：页面职责、查询与汇总口径、明细与月度业务字段、下发表单业务字段、审批人员集合与必要操作；页面布局、列顺序和控件形态按平台规范设计 |
| 原功能架构图历史规划（工程部讨论版，2026-08-26） | 模块归属（工程投资监管：投资计划、投资实施）与建设批次（12 月批次） |
| 业务地图、公共开发约定 | 工程主数据、权限模型、工作流口径与跨模块约束 |
| 规划管理需求分析、规划管理概要设计 | 同级模块先例：项目/线路按已解耦业务项目关联、状态口径、流程选人与幂等做法、页面与路由注册方式 |
| 代码库核对（2026-09-21） | 后端无投资相关包、前端无投资相关页面，git 工作区无本模块实现痕迹 |
| 开发库核对（2026-09-21，项目 MCP） | SYS_MENU 无投资相关菜单（对照：菜单总数 460，按「规划管理」可正常命中）；库内无 INVEST 相关表（对照：ALL_TABLES 227 张、BIZ% 57 张）；无投资相关字典类型（对照：字典类型 60 条）；无投资相关流程定义与流程分类（对照：流程定义 68 条、流程分类 21 条）；SYS_ROLE 12 条中无投资相关角色（既有超级管理员、测试角色、E2E 验证角色、规划管理三类、工程变更测试两类等）；工程管理部等测试部门存在但与本模块无关 |
已采用的推荐默认（完整事项及理由见需求分析第 8.2 节）：
- 菜单命名采用多数原型页一致的「工程投资管理」；普通业务菜单动态注册，三类流程办理页静态注册。
- 发起单位、发起部门与责任部门取平台
SYS_DEPT组织节点并分别保存 ID 与名称快照，发起部门默认当前用户部门；项目/线路沿用已解耦业务项目，并保存业务 ID 与名称快照。 - 上报基准年 N，计划和实施落在 N+1；月计划按计划分解行的 12 个金额列保存，实施实际按下发分解行、年度和月份唯一。
- 三条流程按已确认的人员与必填要求排序，选填节点未选时跳过；状态统一使用
draft/waiting/back/finish，引擎维护审批历史。 - 金额单位亿元、
DECIMAL(18,2)，完成率使用实际/计划，零分母显示「—」，保留两位小数。 - 年度红头台账每年一条、可挂多个文件；计划调整以
MODIFY新版本保留来源和审批历史；一致标记由授权人员维护，只有「是」允许下发。 - 沿用投资岗位权限、不新增单位/部门数据隔离；单位与部门是显式筛选。市级重点合计只计实际标记，全部项目月度值按责任分解求和，项目级指标按项目去重。
阶段选项「续建、开工」是原型中观察到的示例值，当前作为暂定字典项；缺少完整正式枚举来源，但不阻塞本模块按上述范围实现。其余字段级设计、接口参数、数据库约束以及实施验收结果仍分别进入后续设计与交付资料，不属于业务待确认项。
12. 决策状态与后续资料
未解决业务事项为零。曾列为待确认的 Q-EI-001—020 已依用户授权按推荐默认确定；决定内容和依据统一维护于需求分析第 8.2 节，本概要设计按该基线执行。本文件与需求分析仍是设计资料，以下工作状态必须分开核实，不得从本文件推断完成：
| 阶段 | 状态 | 证据与后续位置 |
|---|---|---|
| 需求与概要决策 | 已确定推荐默认 | 本文及需求分析第 8.2 节 |
| 字段级详细设计与数据库矩阵 | 已完成/已回读 | 详细设计、数据库设计；7 表 159 列 |
| 代码、流程导入与菜单/角色落库 | 已完成 | 后端和前端代码、菜单权限行、流程分类已建立；三条流程第二版已发布，第一版保留未发布 |
| 自动化与真实页面端到端验收 | API 主链路通过、页面待验收 | 测试报告：主链路与计划调整共 21 项 API 检查通过；浏览器工具未允许向本地页面传递私有凭据，登录后页面操作未验收 |