# @pac/docs

PAC 的对外文档站,基于 [Fumadocs](https://fumadocs.dev)(Next.js App Router)。

## 开发

```bash
pnpm --filter @pac/docs dev    # http://localhost:3200
```

## 结构

| 路径 | 说明 |
|---|---|
| `content/docs/**` | 手写文档源(MDX)。`meta.json` 控制侧栏顺序/分组。 |
| `content/docs/decisions/` | ADR(架构决策记录),只追加。 |
| `openapi/pac.json` | **生成物**:PAC 的 OpenAPI spec(勿手改,见下)。 |
| `lib/openapi.ts` | fumadocs-openapi server(读 `openapi/pac.json`)。 |
| `lib/source.ts` | 多源 loader:手写 docs + 由 spec 派生的虚拟 API 页(`/docs/api`)。 |
| `lib/shared.ts` | 站点名、路由、GitLab 源链接配置。 |
| `source.config.ts` | 内容集合 + frontmatter schema。 |

## API 参考(自动同步,零漂移)

`/docs/api/**` 下的端点页**不是手写的** —— 由 NestJS 的 OpenAPI spec 渲染。
spec 来自 pac-service 的代码(nestjs-zod DTO),「文档 = 代码」:

```bash
# API 改了之后,重新导出 spec(preview 模式,不连 DB):
pnpm docs:openapi          # 根目录;= pnpm --filter @pac/service openapi:dump
```

它会刷新 `apps/pac-docs/openapi/pac.json`,文档站下次 build/dev 自动重渲。
建议把这步纳入 CI:导出后 `git diff --exit-code` 该文件,有差异即提示「spec 未同步」。

## 写文档

- 新页面:在 `content/docs/` 下加 `.mdx`,frontmatter 写 `title` / `description`,
  在对应 `meta.json` 的 `pages` 里登记顺序。
- 新 ADR:`content/docs/decisions/NNNN-<slug>.mdx`,沿用四段结构(背景/决策/后果/状态)。
- 维护原则见文档首页(`content/docs/index.mdx`)的「文档怎么维护」。

## 校验

```bash
pnpm --filter @pac/docs type-check   # fumadocs-mdx + next typegen + tsc
pnpm --filter @pac/docs build        # 生产构建
```
