主题
工程投资管理 · 详细设计文档
文档版本：0.10 ｜ 最近核对日期：2026-09-27
文档控制
| 项目 | 内容 |
|---|---|
| 模块名称 | 工程投资管理 |
| 关联需求分析 | 需求分析 |
| 关联概要设计 | 概要设计 |
| 关联数据库设计 | 数据库设计 |
| 关联代码版本 | main 工作区（本轮任务改动，提交前）；后端编译及 API 端到端回归通过 |
| 编写/核对人 | Codex |
| 待确认事项 | 无阻塞项；需求未给出且会改变实现的事项按推荐默认处理，见需求分析决策记录 |
1. 页面、路由与交互
| 页面/组件 | 路由 | 进入条件 | 可见角色 | 主要操作 | 状态/异常反馈 |
|---|---|---|---|---|---|
| 投资计划上报台账 | /investment/plan/report | 动态菜单与 investment:planReport:list | 有计划上报查看权限的用户 | 筛选、查看、新增、编辑、暂存、提交、删除、Excel 导入、模板下载、导出 | 显示草稿/流转/退回/办结；校验失败保留输入并定位项目行 |
| 投资计划确认台账 | /investment/plan/confirm | 动态菜单与 investment:planConfirm:list | 有计划确认查看权限的用户 | 筛选、维护一致标志、调整计划、删除、导出、进入下达文件台账 | 一致标志为明确维护的“是”前允许下达；调整单独生成版本 |
| 投资计划上报流程表单 | /investment/plan/report/flowForm | 上报页进入；办理入口携带流程参数 | 发起人或当前办理人 | 草稿保存、提交、查看流程/办理意见、退回后续提 | 流程提交经 Warm-Flow；业务状态由流程事件更新 |
| 计划调整流程表单 | /investment/plan/issueModify/flowForm | 确认台账中的调整计划 | 被授权的调整发起人或当前办理人 | 复制当前版本、修改项目与分摊、暂存或提交 | 办结后更新当前版本指针和未归档下达分摊关联；旧版本及流程历史保留 |
| 投资计划下达文件台账 | /investment/issue | 由一致计划进入的隐藏菜单路由 | 有计划下达权限的用户 | 年度文件维护、附件管理、责任分摊下达 | 每年一个台账行，可有多个附件；文件记录没有单独审批流 |
| 投资实施台账 | /investment/implementation | 动态菜单与 investment:implementation:list | 有实施台账查看权限的用户 | 年度/项目/部门筛选、查看 12 个月计划与实绩、导出、进入月报记录/填报 | 展示已办结月报；月度、累计与年度完成率由服务端重算 |
| 投资实施月报记录 | /investment/implementation/records | 从实施台账选项目责任分摊进入 | 有月报记录权限的用户 | 新增、编辑、暂存、提交、查看、删除草稿或退回记录 | 一个责任分摊、计划年、月份最多一条有效记录；只计办结记录 |
| 投资实施月报流程表单 | /investment/implementation/report/flowForm | 月报新增或流程办理入口 | 发起人或当前办理人 | 月份实际填报、暂存、提交、查看流程/办理意见 | 月计划从下达分摊带出，累计值只读并按有效办结记录计算 |
页面沿用项目筛选卡、列表卡、工具栏、分页及水平滚动表格。宽表按月份横向滚动；必填和金额错误在页面上提示；批量导入错误包含行号与字段。文件附件限原型列出的格式，单个文件不超过 50MB。加载、空态、接口失败和重试按项目 UI 规范实现。
2. 接口契约
统一前缀 /business/investment。业务 ID 按 string | number 传输，前端不转换为 JS Number；金额以亿元为单位，库内与接口均使用十进制精确值，比例为百分数，两位小数，分母为零时返回 null。
| 接口 | 方法 | 调用方 | 权限 | 请求对象 | 响应对象 | 幂等/事务 |
|---|---|---|---|---|---|---|
/business/investment/plan/page、/summary | GET | 两个计划台账 | investment:planReport:list 或 investment:planConfirm:list | mode、年度、项目名、发起单位、责任部门、行业/阶段/重点标记、线路、投资/预备费、分页 | 分页台账与六项汇总 | 只读；筛选与导出使用同一条件，项目筛选按当前有效版本 |
/business/investment/plan/{id}、/process-info/{id} | GET | 计划台账/流程表单 | investment:planReport:query 或 investment:planConfirm:query | 原始 ID | 单据、项目、部门拆分、月份与流程信息 | 只读 |
/business/investment/plan | POST / PUT | 上报/调整表单 | investment:planReport:add/edit 或 investment:planConfirm:adjust | 计划头、项目、部门拆分、12 月计划与选定审批人 | 保存后的 ID/单据 | 单事务写入头、明细、拆分；重复 ID 与非草稿状态拒绝 |
/plan/{id}/project/{itemId}/metadata | PUT | 投资计划上报台账 | investment:planReport:edit | 行业、建设阶段、市级重点与拟申报市级重点 | 无 | 仅草稿/退回的发起人可改，且项目明细必须属于该计划 |
/business/investment/plan/{id}/submit、/consistency | POST / PUT | 上报/确认页 | investment:planReport:submit、investment:planConfirm:consistency | 节点人员或一致标志/说明 | 更新结果与业务状态 | 重复提交保护；流程启动与状态写入同事务 |
/business/investment/plan/{id}/modification、/plan/modification/{id}/process-info | POST / GET | 确认台账/流程表单 | investment:planConfirm:adjust/query | 来源计划 ID 与审批人 | 新版本单据或流程信息 | 克隆旧版本并启动流程；办结才切换当前版本/下达关联 |
/plan/template、/plan/import、/plan/export | GET / POST / GET | 计划台账 | investment:planReport:export/import、investment:planConfirm:export | 模式、筛选条件或 xlsx 文件 | xlsx 下载或逐行校验结果 | 导入全部校验通过后一个事务保存；失败不写入部分项目 |
/issue/page、/issue/{id}、/issue/{ids} | GET / POST / PUT / DELETE | 下达文件台账 | investment:planIssue:list/query/add/edit/delete | 年份、标题/文号/日期、附件 ID 集合 | 年度文件行及分摊信息 | 年度唯一；无已下达责任分摊时允许软删除 |
/issue/{id}/plan-options?year=...、/issue/{id}/allocation、/issue/allocation/{id}/submit | GET / POST | 下达文件台账 | investment:planIssue:issue | 计划拆分 ID、接收用户 ID、备注 | 可选计划/责任部门或下达结果 | 同一有效拆分不可重复下达；提交直接生效，无额外流程 |
/implementation/page、/implementation/summary、/implementation/export | GET | 实施台账 | investment:implementation:list/export | 上报年度、计划年度、项目名、发起单位、责任部门、行业/阶段/重点标记、线路、投资/预备费、分页 | 项目/责任部门行、12 月指标、汇总 | 只读；数据按当前下达版本及筛选范围聚合 |
/implementation/allocation/{allocationId}/report?month=... | GET | 月报表单 | investment:implementation:add | 下达拆分 ID 与月份 | 月计划、期初累计、期末累计、既有月报 | 只读预填，计划来自有效下达拆分 |
/implementation/record/page、/implementation/record/{id}、/implementation/record/process-info/{id} | GET | 月报记录 | investment:implementation:record | 拆分 ID、年月、分页或月报 ID | 记录列表、明细或流程信息 | 只读 |
/implementation/record、/implementation/record/{id}/submit、/implementation/record/{ids} | POST / PUT / POST / DELETE | 月报表单/记录 | investment:implementation:add/edit/submit/delete | 实际额、说明、附件、审批人 | 月报记录与状态 | 按拆分行加锁检查年度月份唯一；提交时启动或续接流程 |
所有写接口在服务层校验当前状态、当前用户、组织/项目/拆分关系、金额范围和目标流程审批人；删除使用逻辑删除，并拒绝影响已下达关系或流程历史的级联删除。所有 Long ID 序列化遵循项目 BigNumber 处理。
3. 状态与业务动作
| 当前状态 | 动作 | 允许角色 | 前置校验 | 数据变化 | 下一状态 | 失败处理 |
|---|---|---|---|---|---|---|
| 草稿/退回 | 保存 | 有新增/编辑权限的发起人 | 当前用户有权维护该单；字段和子表有效 | 头、项目、分摊原子更新 | 草稿或退回 | 校验失败不保留部分变更 |
| 草稿/退回 | 提交上报/调整/月报 | 对应提交权限的发起人 | 必填字段、金额、月份唯一、所选办理人完整 | Warm-Flow 启动或完成退回后的申请人节点 | 流转中 | 重复点击及流程服务失败时回滚业务写入 |
| 流转中 | 办理/退回 | 引擎当前办理人 | Warm-Flow 校验任务归属和流程定义 | 引擎记录意见/任务历史；监听器更新状态、节点与办理人 | 流转中/退回/办结 | 非当前办理人由引擎拒绝；业务侧不伪造审批 |
| 计划办结 | 维护一致标志 | 有 investment:planConfirm:consistency 权限者 | 单据是当前版本且已办结 | 更新一致标志与说明 | 办结 | 失败保持旧标志 |
| 一致计划 | 下达 | 有 investment:planIssue:issue 权限者 | 当前版本已办结且一致为是；拆分未下达 | 年度台账附件与责任拆分接收人绑定；保存快照 | 下达完成 | 任一拆分无效则整次下达失败 |
| 月报草稿/退回 | 删除 | 有删除权限的发起人 | 当前人有权维护；记录尚未办结 | 逻辑删除，不计入完成额 | 已删除 | 失败不改变流程历史 |
计划状态及流程节点以 Warm-Flow 为准。调整单是新的业务 ID，保留前序计划 ID、版本号与克隆来源；办结事件将来源当前版本切到新版本，并把活动分摊绑定到新版本对应拆分。原计划与原流程历史不删除。
4. 权限与数据范围
| 资源/动作 | 菜单权限 | 按钮权限 | 接口权限 | 数据范围 | 越权结果 |
|---|---|---|---|---|---|
| 计划上报 | investment:planReport:list | query/add/edit/submit/delete/import/export | 同名三段式权限 | 无公司/部门数据隔离；通过筛选及业务状态限制 | 后端返回无权错误 |
| 计划确认 | investment:planConfirm:list | query/adjust/consistency/delete/export | 同名三段式权限 | 同上；只允许一致且办结的当前版本进入下达 | 后端拒绝未满足状态的动作 |
| 计划下达 | 隐藏动态菜单 investment:planIssue:list | query/add/edit/delete/issue | 同名三段式权限 | 只读取当前年度办结且已维护为一致的计划拆分 | 后端拒绝重复或不一致拆分 |
| 投资实施 | investment:implementation:list | record/add/edit/submit/delete/export | 同名三段式权限 | 按已下达责任拆分显示，不另按用户/部门隔离 | 后端拒绝无效拆分、他人无权维护的单据或非当前流程任务 |
列表菜单权限和按钮权限只控制页面可见性；Controller 通过 StpUtil.checkPermission(...) 校验接口权限，Service 再校验状态、计划发起人及记录归属。角色菜单权限行已在开发库建立，生产部署需按实际角色授权。
5. 异常、事务与并发
| 场景 | 检测位置 | 用户提示 | 回滚/补偿 | 日志与告警 | 测试用例 |
|---|---|---|---|---|---|
| 重复提交 | Controller 防重复提交、Service 状态检查 | 单据状态已变化，请刷新后重试 | 流程与业务更新事务回滚 | 应用审计日志 | TC-提交重复 |
| 同年红头记录并发新增 | 年度唯一索引与 Service upsert | 已存在该年度台账 | 读取并返回唯一年度行 | 唯一索引冲突由服务层转业务提示 | TC-年度唯一 |
| 同拆分年度月份并发月报 | Service 锁定 allocation 行并检查有效记录 | 该责任部门该月份已有上报 | 插入/更新在同一事务完成 | 记录事务失败 | TC-月报并发/重复 |
| 导入文件部分错误 | 上传解析与逐行服务校验 | 返回行号、列名、错误原因 | 校验完整后事务批量保存；任一保存失败全回滚 | 仅记录文件名及错误摘要，不记录凭据 | TC-导入退回 |
| Warm-Flow 不可用/流程失败 | 流程辅助类 | 流程暂不可用，请稍后重试 | 启动/续流失败时回滚单据状态 | 异常栈留服务端日志 | TC-流程失败 |
| 文件引用缺失或不支持 | 文件 ID 校验/前端文件控件 | 附件格式或大小不符合要求 | 不保存文件引用 | 记录校验失败 | TC-附件边界 |
6. 实现映射与验证
| 责任 | 代码位置 | 验证方式 | 证据 |
|---|---|---|---|
| 后端 | digital-construction-modules/digital-construction-business/src/main/java/com/bokun/business/investment/ | Maven 编译、计算单测、接口与流程事件回归 | 编译通过；3 项计算单测通过；计划保存、计划调整、下达、月报及审批回写 API 主链路通过 |
| 前端 | digital-construction-ui/src/views/business/investment/ 与 src/api/business/investment/ | 构建、格式/静态检查、真实页面端到端操作 | 构建、格式和定向 lint 通过；真实登录后的页面交互未验收 |
| 流程 | digital-construction-modules/digital-construction-workflow/src/main/resources/flow/investment/ | JSON 静态几何核验、Warm-Flow 导入发布、流程图 JSON 回读 | 静态核验、三条流程导入发布和审批事件回归通过；开发库保留一版未发布旧定义 |
| 数据库 | BIZ_INVEST_* 七张业务表、流程分类与 SYS_MENU | dcp-dm8-dev MCP 查询、写后回读 | 结构、流程分类、菜单及计划/调整/下达/月报数据均回读；验收行数见测试报告 |
7. 变更记录
| 版本 | 日期 | 变更 | 原因/来源 | 确认人 |
|---|---|---|---|---|
| v0.1 | 2026-09-27 | 按原型、现有平台契约和推荐默认建立详细设计 | 用户授权按推荐默认完成模块实施 | 待业务验收 |
| v0.2 | 2026-09-27 | 补充实现映射、验证边界与 BO 映射修复记录 | 计划上报接口端到端尝试定位到缺少项目实体转换器；修复已编译，复测受本机 NIO selector 异常阻断 | 待业务验收 |
| v0.3 | 2026-09-27 | 更新主链路与调整版本端到端结果，记录标记值、月份列映射修复及累计口径实测结果 | 21 项 API 检查通过；真实浏览器页面操作仍待验收 | 待页面验收 |