# Patbond Doc

Patbond 的契约、架构决策与开发过程文档。用 [MkDocs](https://www.mkdocs.org/) 构建成站点。

**本仓是四仓中唯一的「正典」所在**：契约、数据模型、架构决策以此为准。其余仓库中的同类内容都是副本或实现，冲突时以本仓为准。

## 权威文档在哪

| 文档 | 位置 | 说明 |
| --- | --- | --- |
| 对外契约 | `docs/api/openapi.yaml` | 客户端可见的全部端点。升版须与 `patbond-api` 内的四份快照同步 |
| 数据模型正典 | `docs/database/patbond_postgresql.sql` | 已评审的目标模型。Flyway 迁移从中逐列摘取，任何偏离都必须在迁移文件头写明原因 |
| 架构决策 | `docs/architecture/decisions.md` | ADR-001 起累积。**改动实现前先读相关 ADR** |
| 后端模块结构 | `docs/architecture/backend-modules.md` | 各模块职责与边界 |
| 发布记录 | `docs/development/releases.md` | 每次发布追加一条，含门禁结果与生效的流程纪律 |
| 功能清单 | `docs/development/feature-checklist.md` | 逐条功能的完成状态 |
| Git 与门禁 | `docs/development/git-workflow.md` | 分支、提交、CI 门禁与凭证防泄漏规范 |
| 真机验证清单 | `docs/development/device-verification.md` | 桌面不可替代的验证项，含逐项步骤与通过标准 |
| 服务器暴露面 | `docs/development/server-exposure.md` | 生产主机的端口、常驻服务与处置记录 |
| 迭代报告 | `docs/development/iterations/` | 按迭代归档。**存档不回改**，结论失效时追加带日期的修正注记 |

## 本地构建

```bash
pip install mkdocs
mkdocs serve   # http://127.0.0.1:8000
```

## 本地门禁

与 CI 同一套命令（`.gitea/workflows/ci.yml`）：

```bash
sh scripts/check-secrets.sh --all              # 凭证防泄漏（ADR-021）
mkdocs build --strict                           # 必须 exit 0 且零 warning
```

`--strict` 会把死链和未挂导航的孤立文档判为失败，所以**新增文档必须同时挂进 `mkdocs.yml` 的 `nav`**。

**每人每仓启用一次** pre-commit 钩子：

```bash
git config core.hooksPath scripts/hooks
```

`scripts/check-secrets.sh` 是四仓同构副本，调整规则时四仓同步提交。

## 写作纪律

- **常设文档不写死本机绝对路径**，用 `<你的工作区>/patbond-xxx` 之类的参数化写法；迭代报告存档豁免。
- **迭代报告是时点存档，不回改**。结论后来被推翻时，在原文下方追加带日期的修正注记并指向新依据——改掉原文等于销毁历史记录，而追加注记同样能掐断转述链。
- **不要引用别的报告的转述结论**。本项目已多次因此误判：某报告写「无 nickname 字段」实指「契约未暴露」，被下游当成「缺列需迁移」，规模预估高估一整档。凡「XX 不存在 / XX 缺失」的判断，请打开原始 SQL、原始契约、原始源码确认，并注明核实的文件与行号。
- `site/` 是构建产物，已被 `.gitignore` 排除，不要提交。

## 相关仓库

| 仓库 | 内容 |
| --- | --- |
| `patbond-api` | Spring Boot 多模块后端 |
| `patbond-flutter` | Flutter 客户端 |
| `patbond-ai` | AI 生成服务（Python），只调服务商 API |