主题
文档规范:术语、结构、格式与 ID
本文件是知识库的「宪法」:术语、结构、格式、ID 与校验方式都以这里为准。新增或修改任何页面,先对照第 9 节的检查清单。
1. 术语与用词
1.1 产品与定位
| 场景 | 统一写法 | 说明 |
|---|---|---|
| 产品全称 | PMForge 项目管理平台 | 首次出现用全称,之后可用「PMForge」或「本平台」 |
| 产品定位 | 面向项目管理(PM)方向的企业级后端平台,配套一套双层知识库 | 一句话定位,各处引用必须与此一致 |
| 知识库 | PMForge 知识库 | 指本站,不叫「文档站」「知识中心」 |
| 工程形态 | 平台底座 + 预留业务模块 + PM 业务域(规划) | 描述现状时的固定三段式 |
禁用词(出现即视为不一致,需改写):
| 禁用 | 改为 | 原因 |
|---|---|---|
| 研学 / 研学平台 / 研学课程 | 项目 / 项目管理平台 / 项目交付物 | 旧定位残留,容易被读成教育产品 |
| 学习平台 / 教学平台 / 实训平台 | 平台 | 同上 |
| 教研 / 教务 / 学员 / 讲师 | 项目成员 / 培训对象 / 客户 / 讲师(仅限正文举例) | 只在举例里按语境替换,不作为产品定位 |
| 中台 / 一站式解决方案 / 全栈解决方案 | 直接写覆盖范围 | 营销词,无信息量 |
| 芋道 / 若依 / yudao / ruoyi / iocoder | PMForge | 上游来源词,一律不再出现 |
平台底座 是本库的正式术语(见 1.1 节「工程形态」),不在禁用之列;课程、教学 若出现在正文举例里,改写为 项目、业务 语境,不用于描述产品定位。
1.2 角色与状态
- 角色统一:项目经理、PMO、项目成员、研发、系统管理员、访客。
- 状态标记只用三种:
✅已实现(参与 Maven 构建且已接入pmforge-server运行时)、⏸预留(代码在库、未接入运行时;其中已纳入构建的可在文字里注明「已编译」)、🚧规划中(无代码)。 - 文档状态只用三种:
草案、已评审、已定稿;实施状态只用三种:已实现、预留、规划中。
1.3 模块码
| 模块码 | 模块 | 状态 |
|---|---|---|
| SYS | 系统管理 | ✅ 已实现 |
| INF | 基础设施 | ✅ 已实现 |
| BPM | 工作流 | ⏸ 预留(已编译) |
| PAY | 支付 | ⏸ 预留(已编译) |
| MBR | 会员 | ⏸ 预留(已编译) |
| MALL | 商城 | ⏸ 预留(已编译) |
| CRM / ERP / WMS / MES / IOT | 企业应用 | ⏸ 预留(已编译) |
| IM | 即时通讯 | ⏸ 预留(已编译) |
| MP | 微信公众号 | ⏸ 预留(已编译) |
| RPT | 数据报表(GoView 集成) | ⏸ 预留(已编译) |
| PLAT | 平台底座(框架、安全、构建) | ✅ 已实现 |
| PM | PM 业务域(规划) | 🚧 规划中 |
2. 功能点 ID
规则:<模块码>-<子域>-<两位序号>,全局唯一、一经分配不再复用;预留模块若只有模块级信息,用 <模块码>-00 表示模块级条目(如 BPM-00)。
示例:SYS-USER-01(用户管理-用户列表)、INF-CODEGEN-01(代码生成-导入表结构)、BPM-00(工作流模块总览)。
3. front-matter
每个 .md 必须有 front-matter,字段固定:
yaml
---
id: SYS-USER-01 # 页面唯一 ID,全局不重复
title: 用户管理 # 与正文 H1 一致(首页除外)
module: system # system | infra | bpm | ... | guide | product | meta
status: done # done ✅ | reserved ⏸ | planned 🚧
code: # 该页断言对应的代码位置,可多条;无代码可省
- pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java#L52
prd: /prd/01-系统管理/01-02-用户管理 # 关联需求原件(可选)
generated: false # true = 脚本生成,禁止手改
---首页 docs/index.md 例外:保留 layout/hero/features,但必须同时有 id、title、module、status、generated。
4. 页面骨架
4.1 通用页(指南、产品、模块、代码、卡片)
text
# 标题(与 title 一致)
一句话结论(这页解决什么问题)
## 1. 第一节
## 2. 第二节
...- 正文用
##与###两级,编号统一1./1.1;不再使用「一、二、」。 - 单页控制在 200 行内,超了拆页。
- 每节第一句先给结论,再展开。
按页面角色分三类,编号要求不同:
| 页面类型 | 典型文件 | 编号规则 |
|---|---|---|
| 内容页 | guide/、product/、modules/<m>/、code/ 子页、pm-domain/、reference/ 手写页、cards/<ID> | 第一节可作导语不编号,其余 ## 一律从 1. 起 |
| 索引页 | 各目录的 index.md(/cards/、/code/、/modules/ 等) | 允许全篇用表格/列表组织、## 不编号;同一页内不要混用「编号 + 不编号」 |
| PRD | prd/** | ## 文档信息 固定不编号(元数据表随其后,表前留空行),正文从 ## 1. 功能概述 起 |
4.2 PRD 元数据表
docs/prd/** 的每篇在 H1 后紧跟「文档信息」表,字段与顺序固定为:
| 项目 | 内容 |
|---|---|
| 文档编号 | PRD-01-02(与文件相对路径对应) |
| 文档名称 | 用户管理 |
| 产品名称 | PMForge 项目管理平台 |
| 所属模块 | system |
| 文档版本 | v2.2 |
| 最后更新 | YYYY-MM-DD |
| 文档状态 | 草案 / 已评审 / 已定稿 |
| 实施状态 | 已实现 / 预留 / 规划中(括号内写模块名) |
| 优先级 | P0 / P1 / P2 / P3 |
每篇 PRD 的 front-matter 另带 quality(A/B/C)与 aligned(接口命中率整数),由 script/docs/prd-align.mjs 自动写入;正文 H1 下方的「文档质量」引用块与文末「## 代码对齐(自动生成)」章节同样由脚本维护,禁止手工编辑(重跑 npm run prd:align 会覆盖)。质量分级定义:
| 级别 | 判定 | 用途 |
|---|---|---|
| A | 命中率 ≥85% 且模块已接入 server | 可直接作为需求基线与验收依据 |
| B | 命中率 ≥40%(或 ≥85% 但未接入运行时) | 可读可用,接口以代码为准 |
| C | 命中率 <40% | 仅表达设计意图,不能作为实现说明 |
PRD 正文章节也统一为 ## 1. 功能概述 … ## 7. 附录(原「一、功能概述」在重写时替换)。总纲 00-产品概述.md 保留其十章结构,但元数据表同字段。
5. 格式细则
| 项 | 规则 |
|---|---|
| 代码围栏 | 必须带语言标记:text、bash、sql、java、yaml、json、http;不确定用 text |
| 图 | 不使用位图,结构图统一用 ```text 代码块;需要截图时贴链接不贴文件 |
| 表格 | 必须有表头与 --- 分隔行;状态列只用 ✅/⏸/🚧 |
| 站内链接 | 以 / 开头的绝对路径(/cards/SYS-USER-01),指向目录时补 /(/modules/) |
| 代码引用 | 反引号内写 仓库相对路径#L12 或 #L12-L20;路径必须存在、行号不得越界,由 docs:lint 校验。规则:① 指向真实文件时写带目录的完整路径;② 只有全仓唯一的标准文件名(如 pom.xml、package-info.java)可只写文件名;③ 省略前缀的引用必须能在全仓唯一匹配到后缀;④ 示例/通配必须显式带 *、{}、<db> 或写成「示例:」,不得伪装成真实路径 |
| 日期 | 一律 YYYY-MM-DD,不写「2026年11月17日」 |
| 版本 | 一律 v主.次,如 v2.1;只升次版本号,除非重构 |
| 数字 | 千位可用空格分组(2 392),与生成物一致 |
| 中英混排 | 中文与英文/数字之间留一个空格;专有名词保留原拼写 |
6. 目录约定
| 目录 | 内容 | 维护方式 |
|---|---|---|
guide/ | 使用说明、阅读路径、术语表、练习、走读 | 手写 |
product/ | 定位、角色场景、能力地图、领域模型、流程、路线图 | 手写 |
pm-domain/ | 项目管理知识框架与平台能力映射 | 手写 |
modules/ | 每个后端模块的总览(含 reserved/ 下的预留模块) | 手写(统计数字来自生成物) |
code/ | 架构、框架组件、横切机制、接口与数据索引 | 架构/机制手写,接口/数据生成 |
cards/ | 功能卡(一个功能一页,含预留模块) | 数据表 + 脚本渲染 |
reference/ | 依赖版本、配置项、错误码、枚举、反向索引、发布、质量自检、漂移自查 | 混合 |
prd/ | 需求原件(39 篇:10 个模块组) | 手写正文 + prd:align 维护质量块与代码对齐章节 |
_templates/ | 页面模板 | 手写 |
_meta/ | 本规范 | 手写 |
7. 生成物与 CI 校验
script/docs/scan-knowledge.mjs(Node 20+,零依赖)从源码生成下列文件,顶部带 <!-- auto-generated -->:
| 生成物 | 数据来源 |
|---|---|
docs/code/api/index.md、docs/code/api/*.md(每个模块一页) | @RestController + @XxxMapping + @PreAuthorize + @Operation |
docs/code/data/index.md、docs/code/data/*.md(每个模块一页) | DO 的 @TableName 与 sql/mysql/pmforge.sql 的 CREATE TABLE |
docs/reference/配置项速查.md | pmforge-server/src/main/resources/application*.yaml |
docs/reference/枚举字典.md | **/enums/*Enum.java |
docs/reference/索引-按代码找功能.md | 权限点 → 接口、表 → DO 的反查 |
docs/prd/** 的质量块与「代码对齐」章节 | docs/.generated/code-index.json + 各 PRD 的 /admin-api 引用 |
docs/cards/*.md(40 张功能卡 + 13 张模块卡) | script/docs/cards.data.mjs、script/docs/cards.reserved.mjs + 接口索引 |
bash
npm run docs:gen # 改动代码后重新生成
npm run prd:align # 重算 PRD 命中率、质量分级与「代码对齐」章节
npm run docs:check # 校验生成物/PRD 对齐是否最新 + 结构/链接/引用
npm run docs:lint # 只做结构与引用校验docs/.generated/code-index.json 是带时间戳的中间缓存,已列入 .gitignore,不参与校验。
当前覆盖(npm run docs:gen 实测):441 个控制器、2 392 个接口、1 072 个权限点、388 张实体表;其中默认构建的 system + infra 为 51 个控制器、328 个接口、137 个权限点、48 张表。
计数口径:只统计 modules/* 与 framework/*;pmforge-server 的 DefaultController(1 个控制器、13 个方法级 @RequestMapping 兜底路由)不计入,在全仓清单里单独标注。方法级映射支持单路径、{"/a", "/b"} 数组与 value = {...} 写法,每个路径计一个接口。
控制器与 DO 按注解识别(@RestController / @TableName),不依赖包路径——pmforge-module-iot 的包结构与其它模块不同(admin/、dataobject/ 直接挂在模块包下),按路径扫描会漏,这是 M2 修过的坑。
CI 位于 .github/workflows/docs.yml:PR 与 main 的改动路径命中源码/文档时,依次执行 npm ci → docs:check → docs:build,产物作为 artifact 留存 7 天。CI 不发布。
漂移的发现与修复流程见生成物漂移与自查;该页含一次真实演练(加一行 @GetMapping 后门禁失败、还原后通过)。
发布:Cloudflare Pages,生产分支 main、根目录 /、构建命令 npm run docs:build、输出 docs/.vitepress/dist、NODE_VERSION=20。推送即触发重建,PR 生成预览域名。Pages 默认可经 *.pages.dev 公开,仓库私有不代表站点私有;需要限制时加 Cloudflare Zero Trust Access。
8. 版本与变更
| 版本 | 日期 | 变更 |
|---|---|---|
| v1 | 2026-11 | 初版:ID、front-matter、目录、生成物 |
| v2 | 2026-11-17 | 重写为「文档宪法」:新增术语表与禁用词、页面骨架、元数据表、格式细则、检查清单;统一为「PMForge 项目管理平台」定位 |
| v2.1 | 2026-11-17 | 术语与禁用词表修正(平台底座不再是禁用词,新增上游来源词);生成物补齐 13 张模块卡;交叉链接《生成物漂移与自查》 |
| v2.2 | 2026-11-18 | 状态口径细分:12 个预留模块已纳入 Reactor(标注「已编译」);模块码表同步 |
| v2.3 | 2026-11-18 | 明确三类页面的编号规则;收紧代码引用规则(完整路径 / 唯一文件名 / 唯一后缀 / 显式示例);补计数口径与方法级多路径映射说明 |
| v2.4 | 2026-11-18 | PRD 基准化:12 个模块逐篇对齐代码,新增质量分级 A/B/C 与「代码对齐」生成章节;模块码表拆分 MP/RPT;PRD 总数 38→39 |
9. 新增或修改文档的检查清单
- front-matter 六个字段齐全,
id未与既有页面重复。 - 标题层级只用
#、##、###,编号为1./1.1形式。 - 出现产品名与定位的句子,与 1.1 节的写法逐字一致。
- 无禁用词(研学、学习平台、中台、上游来源词等,见 1.1 节)。
- 代码围栏都带语言标记;没有位图。
- 站内链接是
/开头的绝对路径,指向目录时带尾斜杠。 - 每条代码断言都能在
code:或正文里给出路径#L行号,且路径存在;省略前缀时全仓唯一,示例路径显式标注「示例」。 - 状态标记只用 ✅/⏸/🚧,文档状态只用三个词。
- 日期为
YYYY-MM-DD,版本为vX.Y。 - PRD 质量分级(A/B/C)与
实施状态不矛盾;接口路径取自代码,规划形态单独成段;新增 PRD 后重跑npm run prd:align。 - 跑一遍
npm run docs:gen && npm run prd:align && npm run docs:check && npm run docs:build,四项都通过再提交。