文档同步规则

本站描述的是当前代码的事实。文档一旦与代码脱节，就会把人引向错误的落位和过期的写法，因此约定：架构、技术栈、目录、流程发生变化时，同一次改动必须把本站改到与代码一致，不允许「先改代码，文档以后补」。

规则文件的仓库权威版本：.trae/rules/developer-docs-sync.md。

什么算需要同步的变更

图 1 · 改完代码后的文档判定
变更类型触发例子
新引入 / 升级技术栈新增第三方依赖、替换框架或组件库、升级 JDK / Spring Boot / React / antd / VuePress 主版本
架构调整新增或拆分 Maven 模块、模块依赖方向变化、请求处理链路（鉴权、统一响应、异常、限流）改动、新增中间件或外部服务
目录结构变化新增顶层目录、改变包约定、移动文档或部署物料、新增业务域页面目录
开发流程变化新增或修改编码规范、提交规范、分支与合并约定、本地启动方式、禁用 API 清单
部署与运维变化flow.yaml 阶段或镜像构建方式改动、容器与端口调整、配置项 / Profile 结构变化、健康检查路径变更
数据模型变化新增表、改列、改 DDL 存放位置、调整 role_scope 这类结构性字段语义

变更 → 页面映射

你的改动必须同步的页面
新增后端依赖 / 升级版本技术栈（总览表 + 后端依赖清单 + 版本管理规则）
新增前端依赖 / 升级 React、antd、UmiJS技术栈、前端规范（禁用写法表）
新增 / 拆分 Maven 模块项目架构、目录结构、新增业务域
新增顶层目录或改变包约定目录结构、新增功能
调整鉴权、统一响应、异常、限流链路项目架构（请求处理链路 / 鉴权与授权模型）、新增接口
新增配置项或改 Profile 装配项目架构（多环境与配置装配）、本地启动、部署
表结构变更数据库（表清单、约定）与 docs/public/1-ddl.sql
新增定时任务 / 导出 / 渠道接入方式变化其他常见改动
修改编码规则或 .trae/rules/*开发规范 对应子页 + 规范索引 的规则文件对照表
修改 flow.yaml、Dockerfile、容器端口部署
新增文档工程 / 移动文档目录结构（文档与部署物料）、技术栈（文档工具链）、相关文档

执行要求

  1. 同批提交：文档改动与代码改动放在同一次提交或同一批提交里，type 按改动意图取（多数情况是 docs 或与功能提交并列），scope 用 docs。
  2. 就地改写：直接改受影响的段落和表格，不留「已废弃」「新增于某版本」这类历史注释；演进历史交给 git log。
  3. 删旧留新：被实现取代、不再成立的内容删除而不是标注废弃。
  4. 不确定就核实：版本以 asone-server/pom.xml 的 <properties> 与 asone-front/package.json 为准；配置项以实际 application*.yml 与 config/*.ts 为准；不要照抄旧文档或旧博客示例。
  5. 不写敏感信息：服务器地址、账号口令、私钥路径、AK/SK、access-token 一律不进本站，只留在 .trae/rules/deployment.md。
  6. 规则双向一致：.trae/rules/ 与本站规范页描述同一套约束，改了其中一边必须改另一边，冲突时以规则文件与当前代码为准。
  7. 图形与正文同批改：请求链路、状态流转、流水线阶段、表关系这类被图描述的流程变化时，同批更新对应 Mermaid / 金字塔图，图形和正文必须描述同一事实；语法与写作约定见图表语法。
  8. 新页面挂导航：新增页面要在 docs/.vuepress/config.js 的 navbar 或对应 sidebar 分组登记，非 index 页面链接用 .html 后缀。

提交前自查清单

# 1. 本次改动的文件清单，判断命中上表哪几类变更
git diff --name-only HEAD~1

# 2. 文档里引用的依赖版本是否仍与构建文件一致
grep -RnE 'Spring Boot|MyBatis-Plus|React|antd|UmiJS' docs/developer-docs/docs/tech-stack/
grep -nE '<(java\.version|mybatis-plus\.version|xxl-job\.version|flowable\.version|redisson\.version|springdoc\.version)>' asone-server/pom.xml

# 3. 文档里写到的路径是否仍然存在
grep -RoE 'asone-[a-z-]+/[A-Za-z0-9_./-]+' docs/developer-docs/docs/ | sort -u
ls asone-server asone-front docs xxl-job

# 4. DDL 是否与文档描述一致（表数量、DDL 文件位置）
grep -c '^CREATE TABLE' docs/developer-docs/docs/public/1-ddl.sql

# 5. 站点能正常构建（死链、sidebar 配置错误在这里暴露）
cd docs/developer-docs && pnpm build
  • [ ] 命中的每一类变更都已在映射表对应页面落地
  • [ ] 页面之间没有指向已删除文件 / 已改路径的死链
  • [ ] pnpm build 通过，新增页面已在 .vuepress/config.js 的 navbar / sidebar 挂载
  • [ ] 没有把凭据、内网地址写进文档
  • [ ] 涉及 .trae/rules/ 的约束变化已同步到规范页

本地预览与构建

cd docs/developer-docs
pnpm install
pnpm dev      # 本地预览
pnpm build    # 产物在 docs/.vuepress/dist

内容根是 docs/developer-docs/docs/，站点配置在 docs/developer-docs/docs/.vuepress/config.js：新增页面必须同时在 navbar 或对应 sidebar 分组登记，否则页面能构建出来但导航进不去。非 index 页面在 sidebar 中使用 .html 后缀链接。public/ 下的文件（如 1-ddl.sql）会被原样拷贝到站点根，可用 /文件名 直接引用。