Skip to content

文档规范:术语、结构、格式与 ID ​

本文件是知识库的「宪法」:术语、结构、格式、ID 与校验方式都以这里为准。新增或修改任何页面,先对照第 9 节的检查清单。

1. 术语与用词 ​

1.1 产品与定位 ​

场景统一写法说明
产品全称PMForge 项目管理平台首次出现用全称,之后可用「PMForge」或「本平台」
产品定位面向项目管理(PM)方向的企业级后端平台,配套一套双层知识库一句话定位,各处引用必须与此一致
知识库PMForge 知识库指本站,不叫「文档站」「知识中心」
工程形态平台底座 + 预留业务模块 + PM 业务域(规划)描述现状时的固定三段式

禁用词(出现即视为不一致,需改写):

禁用改为原因
研学 / 研学平台 / 研学课程项目 / 项目管理平台 / 项目交付物旧定位残留,容易被读成教育产品
学习平台 / 教学平台 / 实训平台平台同上
教研 / 教务 / 学员 / 讲师项目成员 / 培训对象 / 客户 / 讲师(仅限正文举例)只在举例里按语境替换,不作为产品定位
中台 / 一站式解决方案 / 全栈解决方案直接写覆盖范围营销词,无信息量
芋道 / 若依 / yudao / ruoyi / iocoderPMForge上游来源词,一律不再出现

平台底座 是本库的正式术语(见 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平台底座(框架、安全、构建)✅ 已实现
PMPM 业务域(规划)🚧 规划中

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/ 等)允许全篇用表格/列表组织、## 不编号;同一页内不要混用「编号 + 不编号」
PRDprd/**## 文档信息 固定不编号(元数据表随其后,表前留空行),正文从 ## 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/配置项速查.mdpmforge-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. 版本与变更 ​

版本日期变更
v12026-11初版:ID、front-matter、目录、生成物
v22026-11-17重写为「文档宪法」:新增术语表与禁用词、页面骨架、元数据表、格式细则、检查清单;统一为「PMForge 项目管理平台」定位
v2.12026-11-17术语与禁用词表修正(平台底座不再是禁用词,新增上游来源词);生成物补齐 13 张模块卡;交叉链接《生成物漂移与自查》
v2.22026-11-18状态口径细分:12 个预留模块已纳入 Reactor(标注「已编译」);模块码表同步
v2.32026-11-18明确三类页面的编号规则;收紧代码引用规则(完整路径 / 唯一文件名 / 唯一后缀 / 显式示例);补计数口径与方法级多路径映射说明
v2.42026-11-18PRD 基准化:12 个模块逐篇对齐代码,新增质量分级 A/B/C 与「代码对齐」生成章节;模块码表拆分 MP/RPT;PRD 总数 38→39

9. 新增或修改文档的检查清单 ​

  1. front-matter 六个字段齐全,id 未与既有页面重复。
  2. 标题层级只用 #、##、###,编号为 1. / 1.1 形式。
  3. 出现产品名与定位的句子,与 1.1 节的写法逐字一致。
  4. 无禁用词(研学、学习平台、中台、上游来源词等,见 1.1 节)。
  5. 代码围栏都带语言标记;没有位图。
  6. 站内链接是 / 开头的绝对路径,指向目录时带尾斜杠。
  7. 每条代码断言都能在 code: 或正文里给出 路径#L行号,且路径存在;省略前缀时全仓唯一,示例路径显式标注「示例」。
  8. 状态标记只用 ✅/⏸/🚧,文档状态只用三个词。
  9. 日期为 YYYY-MM-DD,版本为 vX.Y。
  10. PRD 质量分级(A/B/C)与 实施状态 不矛盾;接口路径取自代码,规划形态单独成段;新增 PRD 后重跑 npm run prd:align。
  11. 跑一遍 npm run docs:gen && npm run prd:align && npm run docs:check && npm run docs:build,四项都通过再提交。