团队文档协作规范

本站是 cikio 的跨团队文档枢纽：对外是接入方读接口文档的唯一权威来源，对内是各团队发布自己领域规范的地方。

一、本站的定位

作用	说明
对外	接入方（CCU、论坛、机器人、未来的第三方）从这里读接口文档
对内	各团队从这里发布自己领域的开发规范、接口协议
不强加	各团队的内部设计文档仍放在各自的子项目目录（如 `ccu/DESIGN.md`），不搬进来

一句话边界：本站只承载「对外可见」的部分，不取代各团队的内部文档。

二、你能在哪写：目录归属

团队	目录（写在这里）	对应 URL
AuthServer	`docs/content/authserver/`	`/authserver/`
CCU	`docs/content/ccu/`	`/ccu/`
forum（论坛）	`docs/content/forum/`	`/forum/`
message（消息中心）	`docs/content/message/`	`/message/`
共享包	`docs/content/shared/`	`/shared/`
文档站维护者	`docs/content/` 根级页面、`guides/`、`dev/`	`/`、`/guides/`、`/dev/`

URL 由文件路径决定（本站不支持 frontmatter 覆盖 slug），所以目录不只是归类：content/ccu/assets.md 就是 /ccu/assets/。分区一旦发布，改名即换地址，需要走评审。

本节之外的根级页面（首页、条款与政策等）由文档站维护者负责，团队需要改动时走下面的汇报流程。

三、能写什么、不能写什么

能写

你自己目录（见上表）下的内容
已定稿、不再变动的设计决策
严谨的接口说明：请求格式、响应格式、错误码、示例
分步骤、可执行的对接流程
术语表（避免跨团队歧义）

不能写

❌ 情形	说明
大白话注释	如「这里我们搞了个 xxx」
讨论与聊天记录	如「昨天和 XX 团队讨论后决定……」——结论可以写，过程不写
未定稿的草案	如「可能在考虑 A 或 B，还没定」
TODO 式占位	如「待补充」「稍后完善」
修改其他团队的文档	见第六节，走汇报流程
复制其他团队的内容	见第五节，只引链接

判断标准：一个没参与过讨论的外部人，只读这份文档，能不能正确接入。

写不完的页面可以提交到仓库，但 frontmatter 必须标 draft: true —— 它在生产构建里不输出、本地 dev 仍可见，不会把半成品推给读者。定稿后删掉这一行即可。

四、文档结构约定

分区长出第二篇文档时，就把单文件改成同名目录 + index.md：

docs/content/
├─ index.mdx                   # 首页（不进侧栏）
├─ authserver/                 # AuthServer 团队
│  ├─ index.md                 # 概览
│  ├─ api-contract.md          # 对外 API 协议
│  ├─ oidc-integration.md      # OIDC 接入指南
│  └─ errors.md                # 错误码表
├─ ccu/                        # CCU 团队
├─ forum/                      # forum 团队
├─ message/                    # message 团队
├─ shared/                     # 共享包团队
├─ policy/                     # 条款与政策（维护者）
├─ guides/                     # 跨团队的接入指南与规范（维护者）
└─ dev/                        # 开发说明：monorepo 与各子项目（维护者）

各团队只写自己目录下的内容。

五、跨团队引用规则

只引用链接，不复制内容 —— 复制就会变成双源，A 更新了、B 的副本没更新。

场景	写法
CCU 要引用 AuthServer 的接口	`参见 [AuthServer 的 OIDC 接入指南](/authserver/oidc-integration)`
forum 要引用 CCU 的资产字段	`参见 [CCU 的资产库字段定义](/ccu/assets#字段清单)`
任何团队要引用共享包	`参见 [共享包文档](/shared/packages)`

引用时不要链接到还没发布的页面：先确认目标已经存在（本地 pnpm --filter docs dev 能打开），否则线上是死链——构建期的链接校验会直接报错。

六、发现别的团队文档有错怎么办

① 不修改对方文档
② 整理问题（引用具体段落 + 说明为什么错 + 影响范围）
③ 向项目负责人汇报
④ 项目负责人转交对应团队
⑤ 对应团队修正

这个流程的意义：避免一个团队擅自改另一个团队的文档、保留修改痕迹（谁改的、为什么改）、让问题有统一入口。

同样适用于「发现别的团队的接口和自己对接不上」——不自己改对方文档，汇报后由项目负责人协调。

七、新增一篇文档要做的事

在你的目录下建 .md / .mdx 文件（内容写全，别留 TODO 占位）
如果目标分区目前是单文件：建成同名目录、把原文件挪成 index.md
侧栏由目录自动跟进的部分（当前是 policy/）不用管；其他位置需要在 docs/astro.config.mjs 的 sidebar 加一条，并在 docs/scripts/fetch-content.mjs 的 PUBLISHED_SLUGS 加同一 slug，少一步构建会失败
尚未定稿 → frontmatter 标 draft: true

正文、侧栏、构建校验的更多细节见开发文档与仓库里的 docs/README.md。