Files

T

1445043649 240c6bd0e2 docs(mt): 统一 multi-tenant-redesign 命名约定 + README 补执行层索引

命名统一为 .zh-CN.md 后缀（与既有 17 个文件 + README 一致）：
- 03-impl/{pr1-8,STATUS}.md → *.zh-CN.md
- Stage 1 spec 去日期前缀、加 .zh-CN，对齐 01-redesign 语义命名

README.zh-CN.md 修复 4 处不统一：
- 顶部加进度指引（现状只信 STATUS，本文是设计/路线导航）
- §0 文档总图补 03-impl 层 + Stage 1 spec + 命名约定注
- §1 表加 Stage 1 spec 行；新增 §1.1 执行记录层（STATUS + 8 impl note 索引）
- §7 阅读路径首次进项目/Stage 1 均加 STATUS + spec 入口

同步更新所有交叉链接（STATUS/pr/spec 自引用、database-schema-as-built、
根 README_zh.md、Stage 0 master plan）；全树相对链接校验可达。

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

2026-06-28 10:40:42 +08:00

4.5 KiB

Raw Blame History

PR2 · 默认 backend 切到 Postgres

实现笔记。对应 docs/superpowers/plans/2026-05-10-stage-0-multi-tenant-foundation.md PR2（T2.1-T2.10）。

状态：已落地，7 commits 提交在 branch feat/stage-0-pr2-postgres-default。

范围

让 Postgres 成为 dev + 生产的默认 backend，SQLite 沦为可选 fallback——但不破坏 SQLite 路径（Stage 0 期间 dev 仍可走 SQLite）。

具体动作：

config.example.yaml database 段：postgres 活跃、SQLite 注释；bump config_version 9→10
.env.example：DATABASE_URL 行从注释改为活值（指向本地 docker postgres）
docker-compose-dev.yaml gateway depends_on postgres healthcheck（生产 compose 不动——prod 用远程 RDS）
scripts/check.py 加 check_postgres_preflight()：make dev 链上 PG 不通时 FAIL 阻断启动
README.md Quick Start 加 Step 3 "Database backend"
2 个 regression test 锁定：(a) 显式 sqlite 仍工作 (b) config.example.yaml 默认 postgres

验收

全套 pytest tests/ 3087 passed + 23 skipped + 0 failed（PR1 基线 3085；diff = 2 新 default-backend 测试）
test_explicit_sqlite_backend_still_works PASS（SQLite regression 防线）
test_config_example_default_backend_is_postgres PASS
python scripts/check.py 在 sqlite 配置下 silent skip postgres preflight（无破坏现有用户）
make doctor 在 postgres 配置 + DATABASE_URL 不可达时给可执行 fix（指向 docker compose 命令）
docker compose -f docker/docker-compose-dev.yaml config 校验通过（postgres + gateway depends_on healthcheck 都合法）
live：make dev 在 postgres 模式下 preflight + 服务启动——待 docker daemon 起后由用户实测
live：CI workflow backend-postgres-tests 跑通——PR push 后验证

关键决策（lock 项）

项	选择	理由
默认 backend	postgres	Stage 0 不可逆决策（plan §不可逆决策一览）；省 Stage 1 重 ALTER 4 张表的返工
SQLite 处理	注释保留为 fallback，不删	offline dev / 单元测试场景仍需要
`config_version` bump	9 → 10	默认行为变化属于 schema 变更，触发 `AppConfig.from_file()` 旧版 warning
`DATABASE_URL` 形态	`postgresql+asyncpg://` 而非 `postgresql://`	与 SQLAlchemy 异步 dialect 对齐，避免 dialect 推断警告
`depends_on` 仅 dev compose	prod compose 无 postgres service	生产用远程 RDS，不在 compose 内
PG preflight 加在 check.py	不在 serve.sh 加 bash 版	Makefile 已串 check.py → serve.sh，避免双重实现
preflight FAIL vs WARN	FAIL（阻断启动）	配了 PG 但不通就一定崩，preflight 早死好过 runtime 崩
sqlite→pg 数据迁移工具	不实现（plan T2.8 marked optional）	Stage 0 没有生产数据需要迁；follow-up

跟进项（不在 PR2 范围）

PR3+：在新建的 PG 上跑 workspace 表 schema
backend/CLAUDE.md 更新：plan T2.9 包括 backend/CLAUDE.md，本 PR 仅做了 README；CLAUDE.md follow-up
scripts/migrate_sqlite_to_postgres.py（plan T2.8 optional）：如果将来有用户从 SQLite dev 迁 PG 的需求，再写
prod compose postgres service：当前 docker-compose.yaml（生产）无 postgres service；如果将来不用远程 RDS，可补上

涉及文件

类别	文件
配置	`config.example.yaml`、`.env.example`
Docker	`docker/docker-compose-dev.yaml`（gateway depends_on postgres）
脚本	`scripts/check.py`（postgres preflight）
测试	`backend/tests/test_default_database_backend.py`
文档	`README.md`

提交记录

7 commits（每条 1 task）：

404135a1 feat(config): default database backend to postgres                   T2.1
7d3d3560 feat(env): activate DATABASE_URL with local-dev default              T2.2
d312bdf9 test(config): pin default postgres backend + sqlite regression       T2.3 + T2.4
3e62a0f6 feat(docker): gateway depends_on postgres healthcheck (dev only)     T2.5
83b680b2 feat(check): postgres preflight in scripts/check.py                  T2.6
745a33e0 chore: T2.7 acknowledgement (covered by T1.8)                        T2.7（empty）
c53295df docs(readme): add Database backend section in Quick Start            T2.9

T2.10（impl doc）是这份文档本身。 T2.8（sqlite→pg 迁移工具）跳过——plan marked optional + Stage 0 无生产数据。

4.5 KiB Raw Blame History Unescape Escape