From 6ca0ff8184ae4e989e7ebbfd1974c65ca10ba6a3 Mon Sep 17 00:00:00 2001 From: longsizhuo Date: Sun, 19 Jul 2026 10:17:59 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=8A=A0=20backend/AGENTS.md?= =?UTF-8?q?=E2=80=94=E2=80=94=E6=94=B9=20DB=20schema=20=E5=89=8D=E5=BF=85?= =?UTF-8?q?=E6=9F=A5=E5=85=A8=E6=96=B0=E8=B4=A1=E7=8C=AE=E8=80=85=E8=83=BD?= =?UTF-8?q?=E5=90=A6=E5=90=AF=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把 M0 踩的坑固化成硬约束：三处 schema（schema.sql / docker/init-db/init.sql / test-schema.sql）必须同步（CREATE TABLE IF NOT EXISTS 补不上已存在表的缺列）、 schema.sql 的 DML 必须幂等、不许把 SPRING_SQL_INIT_MODE 改成 never、不许直接 敲生产库；附一次性 throwaway 容器跑 init→schema 两遍的验证配方，杜绝"我这能跑" 式自证。 --- AGENTS.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..185a6d4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# AGENTS.md — backend 给 AI / contributor 的硬约束 + +配合根 `CLAUDE.md`（三仓库架构总览）与 `SECURITY.md`（INV-001.. 安全不变量）阅读。 +这里只写**已经踩过、且对新人是毁灭性打击**的反模式。 + +## 改数据库前，先问"全新的人还能启动吗" + +改 DB schema（新增表/列、写回填 DML、动 `schema.sql`）时，**默认受害者不是你**—— +你的服务器/本地库早就有那些表和列，任何缺列/缺表的问题在你这儿都看不见。真正 +会被打穿的是**第一次 clone 下来、`docker compose up` 的新贡献者**。改动前必须逐条过： + +1. **三处 schema 必须同步改**，缺一即分裂： + - `src/main/resources/schema.sql` — 唯一真相源，后端启动时执行（`SPRING_SQL_INIT_MODE=always`） + - `docker/init-db/init.sql` — **只在数据卷首次创建时跑一次**，给全新 docker 贡献者建库 + - `src/test/resources/test-schema.sql` — H2（PostgreSQL MODE）测试镜像，`TIMESTAMPTZ→TIMESTAMP`、`JSONB→VARCHAR` + + 致命点：`CREATE TABLE IF NOT EXISTS` 对**已存在的表是 no-op，补不上缺的列**。 + 所以 `init.sql` 建的表若比 `schema.sql` 少列，schema.sql 永远修不好它—— + 全新 docker 库会带着残缺表跑，登录 INSERT / 回填 SELECT 直接报 + `column "x" does not exist`。init.sql 的每张表列集必须与 schema.sql 逐列一致 + （这条正是 INV-004 `user_follows` 事故的教训扩展）。 + +2. **schema.sql 里的任何 DML 必须幂等**：它每次启动都重跑。回填用 + `INSERT ... ON CONFLICT DO NOTHING`，seed 用 `ON CONFLICT DO NOTHING/UPDATE`。 + 非幂等语句会在第二次启动 `spring.sql.init` 报错、后端拒绝启动。 + +3. **绝不建议把 `SPRING_SQL_INIT_MODE` 改成 `never`**。schema.sql 幂等，`always` + 是安全默认（`.env.example` 默认即是）。改 never 后：docker 卷已存在 → init.sql + 不再跑，mode=never → schema.sql 不跑，别人**新加的表在你本地既不建也不报**， + 直到某个登录路径 500。曾经踩过，别把这条建议写回文档。 + +4. **不要把 DDL 直接敲进正在跑的（尤其生产）数据库**。把改动提交进上面三个 schema + 文件，让启动时 reconcile。核查生产只能只读（`to_regclass`、`SELECT`）， + 写操作走代码 + 重启。 + +## DB 改动的验证配方（必须做，不能只信"我这能跑"） + +用**一次性 throwaway 容器**模拟全新贡献者，跑完即弃，绝不碰真实库： + +```bash +docker rm -f ih-fresh-test 2>/dev/null +docker run -d --name ih-fresh-test -e POSTGRES_USER=t -e POSTGRES_PASSWORD=t -e POSTGRES_DB=t \ + -v "$PWD/docker/init-db:/docker-entrypoint-initdb.d:ro" postgres:18-alpine +# 等 init.sql 跑完（pg_isready 轮询），再把 schema.sql 拷进去执行两遍： +docker cp src/main/resources/schema.sql ih-fresh-test:/tmp/schema.sql +docker exec ih-fresh-test psql -U t -d t -v ON_ERROR_STOP=1 -q -f /tmp/schema.sql # 应 exit 0，无缺列崩溃 +docker exec ih-fresh-test psql -U t -d t -v ON_ERROR_STOP=1 -q -f /tmp/schema.sql # 再跑一遍验证幂等 +docker rm -f ih-fresh-test +``` + +通过标准：两遍都 `exit 0`、无 `does not exist`、目标表/列存在。**只在既有服务器库上 +测不算数**——它已有那些列，恰好把 init.sql 的分裂藏住。 + +## 备份 + +改数据前确认 `involution-pg-backup` 日备在跑（`@daily`，保留 30 天 + 8 周 + 12 月）。 +破坏性迁移留回滚兜底；`docker compose down -v` 只在**本地**开发库用（会清空数据）。 From 1c0ba44a273f5e9bacdd95d57fc42a0a4164c1fc Mon Sep 17 00:00:00 2001 From: longsizhuo Date: Sun, 19 Jul 2026 11:38:57 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E5=8A=A0=20backend/CLAUDE.md=20?= =?UTF-8?q?=E8=BD=AC=E5=8F=91=E5=88=B0=20AGENTS.md=EF=BC=8C=E8=AE=A9=20Cla?= =?UTF-8?q?ude=20Code=20=E5=9C=A8=E5=85=A8=E6=96=B0=20clone=20=E4=B9=9F?= =?UTF-8?q?=E5=90=83=E5=88=B0=20DB=20=E5=AE=88=E5=8D=AB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4cbb15c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,12 @@ +# CLAUDE.md — backend + +Claude Code 加载本文件；其它 agent 加载 `AGENTS.md`。两者的硬约束以 +**`AGENTS.md` 为准**，本文件只做转发，避免双份维护漂移。 + +**动手前必读：** + +- `AGENTS.md` — 改 DB schema 前的三处同步 + 全新贡献者启动检查等硬约束 +- `SECURITY.md` — INV-001.. 安全不变量（改 auth/角色/密码/关注/端口前必读） +- 根 `../CLAUDE.md`（本机存在时）— 三仓库架构总览与跨服务边界 + +backend 架构目前在根 `CLAUDE.md` 里成篇覆盖。