主题
路线图与决策记录
现状一句话:底座可用、业务域为零、前端缺失、技术栈已过保质期。这四件事决定了路线图的顺序——先补业务域,再补前端,同时把升级当作一条并行轨道,而不是一次大爆炸。
1. 现状快照
| 维度 | 现状 | 数字 | 状态 |
|---|---|---|---|
| 模块 | Maven 多模块,pmforge-server 唯一入口 | 17 个 Reactor 模块:根聚合 + BOM + framework(15 Starter)+ server + system + infra + 12 个业务模块 | ✅ |
| 预留模块 | 12 个业务模块已全部编译通过 | 12 编译通过 | ⏸ 未接入运行时 |
| 产物 | 可执行单体 jar | 146.5 MB | ✅ |
| 接口 | system 199 + infra 116 | 315 | ✅ |
| 数据表 | system 32 + infra 16(含 5 张演示表) | 48 | ✅ |
| 功能卡 | SYS 27 + INF 13 | 40 | ✅ |
| PM 业务域 | 6 个功能点,尚未编码 | 0/6 | 🚧 |
| 前端 | 仓库内无前端工程 | 0 | 🚧 |
| 运行时 | JDK 8 + Spring Boot 2.7.18 | — | ⏸ 停止维护 |
时间线上的两个节点:2026-09 底座成型(system + infra 可构建运行),2026-11 完成去痕与工程清洗(删除上游痕迹、测试类归位、构建修复),许可由自有许可切换为 Apache-2.0(ADR-009)。
2. 技术债
| 债务 | 表现 | 影响 | 处理方向 |
|---|---|---|---|
| 运行时过期 | JDK 8、Spring Boot 2.7.18 均已停止维护 | 无安全补丁,新依赖不敢升 | 单独一条升级轨道,先评估 Boot 3 + JDK 17 |
| 编译与运行时脱节 | 12 个模块已编译,但库表、菜单、配置都没接,server 也不依赖它们 | 「能编译」被误当成「能用」 | 按模块补 DDL 与菜单 SQL,做接口冒烟;每次改框架后跑全量 compile |
| 无前端 | 只有接口与前端模板,没有可运行的界面 | 产品无法演示,只能靠接口验证 | 先做管理端最小集,接口契约已在 |
| 反射耦合 | 框架通过 SpringUtil.getBean(ClassUtil.loadClass(...)) 调用可选模块 | 模块缺失时抛 ClassNotFoundException,不是优雅降级 | 改为可选依赖 + 空实现,或显式开关 |
| 本地禁用任务 | local profile 排除 Quartz 自动配置 | 定时任务相关功能本地无法验证 | dev 环境开启并纳入冒烟用例 |
| 示例密钥 | 配置里有示例加密密钥与默认口令 | 直接上生产即事故 | 发布前强制替换,加入启动检查 |
| 版本号语义 | revision=2026.06-jdk8-SNAPSHOT | 与「2026-11 去痕」的时间线不一致 | 统一版本策略(日期 + 技术栈标识) |
3. 三阶段路线图
3.1 近期(0–3 个月):把已有资产变成可用的产品说明
| 目标 | 交付物 | 验收标准 |
|---|---|---|
| 知识库成型 | 产品层 6 页 + PM 专题 4 页 + 40 张功能卡 + 12 张模块卡 + 代码索引 | npm run docs:check 通过;无死链;每页 80 行以上 |
| 口径统一 | 能力地图、功能清单、卡片三处数字一致 | 40 / 67 / 6 / 113 四处引用一致 |
| PM 域设计定稿 | 六个实体的表结构、状态机、权限点、错误码段 | 评审通过,可直接交给代码生成器 |
| 任务可观测 | 定时任务在 dev 可跑,任务日志可查 | 手动触发一次 JobLogCleanJob 成功并有日志 |
3.2 中期(3–6 个月):PM 域 P0 落地
| 目标 | 交付物 | 验收标准 |
|---|---|---|
| 项目主数据 | pm_project + CRUD + 成员 + 可见范围 | 租户内可建项目,跨租户不可见(用两个租户验证) |
| 任务 | pm_task + 层级 + 指派 + 状态流转 | 状态机非法流转被拒;按人筛选可用 |
| 迭代与里程碑 | pm_sprint、pm_milestone | 迭代内任务统计正确;里程碑逾期可查 |
| 权限与数据权限 | pm:project:* 等权限点 + 部门范围过滤 | 项目经理只看本部门;租户管理员看全部 |
| 前端最小集 | 登录、项目列表、任务看板 | 能在浏览器完成「建项目 → 建任务 → 改状态」 |
3.3 远期(6–12 个月):从「能用」到「可运营」
| 目标 | 交付物 | 验收标准 |
|---|---|---|
| 工时与审批 | pm_timesheet + 审批流(v1 用状态机,BPM ⏸) | 填报 → 提交 → 通过/驳回 全链路可追 |
| 风险与报表 | pm_risk + 进度/负载/工时报表 | 报表数字与明细对得上 |
| 技术栈升级 | Boot 3 + JDK 17 评估与试点 | 至少一个模块在分支上升级成功 |
| 运行时接入 | 12 个已编译模块逐个决定「接入 server / 继续只编译 / 删除」 | 每个接入模块补齐 DDL、菜单、配置并有冒烟用例 |
| 交付形态 | 前端 + 后端分离部署或一体化打包 | 一条命令构建出可部署产物 |
4. 决策记录
| 编号 | 决策 | 理由 | 代价 |
|---|---|---|---|
| ADR-001 | 采用自有许可,不保留上游版权声明(2026-11 由 ADR-009 取代) | 项目定位为全新自研,许可与品牌需一致 | 上游升级无法直接 merge,要人工比对 |
| ADR-002 | 只启用 5 个模块(dependencies、framework、server、system、infra),13 个默认不参与构建 | 构建快、依赖少、故障面小;先把底座做扎实 | 休眠模块会腐烂,启用成本随时间上升(2026-11-18 由 ADR-009 部分取代) |
| ADR-009 | 把 12 个预留模块纳入 Reactor 做编译验证 | 先消除「腐坏到编不过」的风险,再按业务优先级接运行时;server 依赖保持最小 | 构建时间从 ~55s 升到 ~2.5min;编译通过不等于可运行 |
| ADR-010 | 移除 AI 模块(代码、文档、菜单、配置、前端入口) | 半成品会误导读者;Spring AI 1.x 需 Boot 3 / Jakarta,与主干不兼容 | 后续要做 AI 能力需独立服务或升级主干 |
| ADR-003 | 知识库采用「产品层 + 代码层」双层结构 | 单一视角的文档要么太虚(只有愿景),要么太细(只有代码) | 两层的口径需要人工对齐,靠 ID 与 CI 兜底 |
| ADR-004 | 功能点 ID 作为唯一锚点(如 SYS-TENANT-01) | 避免 PRD、卡片、代码索引三套编号互相对不上 | 新功能必须先申请 ID 才能写文档 |
| ADR-005 | 代码索引脚本生成、CI 校验,不手写 | 328 个接口手工维护必然过期 | 生成器本身要维护,扫描规则要跟着代码结构走 |
| ADR-006 | 业务扩张优先用代码生成器产骨架,而不是手写 CRUD | 单表/树表/主子表三类模板已覆盖大部分管理端场景,能把人力留给状态机与权限 | 生成物需要人工改造,模板不覆盖的场景仍要手写 |
| ADR-007 | 保留 37 篇子 PRD 原件,不合并进卡片 | PRD 记录「当初为什么做」,卡片记录「现在怎么实现」;合并会丢掉决策语境 | PRD 与代码可能漂移,需要在卡片里回链并标注差异 |
| ADR-008 | 自建知识库(VitePress + 同仓),而不是用外部 Wiki | 文档要能被 CI 校验、能按 ID 站内跳转、能与代码同版本 | 需要自己维护构建、导航与生成脚本 |
| ADR-009 | 许可由自有许可切换为 Apache License 2.0 | 开源生态兼容,采用与再分发无摩擦;保留版权与归属即可 | 放弃专有限制,商用与二次分发不再受控 |
5. 风险登记
| 风险 | 概率 | 影响 | 缓解 |
|---|---|---|---|
| PM 域设计反复,拖过窗口期 | 中 | 高 | 先锁 P0 三实体,P1/P2 延后 |
| 前端从零起步,体验不达预期 | 高 | 中 | 先做「能走通」的最小集,不追求组件完备 |
| 升级 Boot 3 引发大面积改动 | 中 | 高 | 单独分支试点,先升 framework 再升模块 |
| 文档与代码再次脱节 | 中 | 中 | 生成物 CI 校验 + 卡片回链源码行号 |
| 休眠模块被误启用导致构建失败 | 中 | 低 | 启用清单写进文档,改动需同步 server 依赖 |
6. 下一步
- 先看能力边界:能力地图
- 再看 PM 域怎么建模:领域模型
- 方法论怎么落到现有能力上:方法论与平台能力映射
- 度量怎么取数:指标与度量