Files

T

CI / docs-build (push) Successful in 41s

Details

docs: backend-modules 补 creation 与 patbond-ai + 新建本仓 README

- backend-modules.md：速览图补 patbond-creation(:8085) 与独立的 patbond-ai
  仓；新增两节职责说明（含 V6 两处偏离目标模型的原因、队列不引入 broker
  的依据、服务身份 JWT 用独立密钥对的事实依据、以及骨架阶段刻意未实现项）；
  关键纪律第 2 条补「谁拥有 schema」与「迁移文件放哪」是分开的（pet/
  community/creation 代码各在自己模块，迁移全在 patbond-user），第 3 条补
  两套内部鉴权并存的原因。并注明 patbond-creation 尚未入 compose 及其原因。
- 新建本仓 README（此前四仓中唯一没有的）：权威文档索引、本地构建与门禁、
  以及三条写作纪律——常设文档不写死本机路径、迭代报告是时点存档不回改
  （结论失效时追加带日期注记）、不要引用别的报告的转述结论（附本项目
  已因此把规模预估高估一整档的实例）。

验证：secret-scan exit 0；mkdocs build --strict exit 0。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-18 17:37:35 +08:00

3.2 KiB

Raw Permalink Blame History

Patbond Doc

Patbond 的契约、架构决策与开发过程文档。用 MkDocs 构建成站点。

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

权威文档在哪

文档	位置	说明
对外契约	`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/`	按迭代归档。存档不回改，结论失效时追加带日期的修正注记

本地构建

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

本地门禁

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

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

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

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

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

3.2 KiB Raw Permalink Blame History Unescape Escape