From b0482ec157cc7b5b14ef0d6411fa8e879dc249a6 Mon Sep 17 00:00:00 2001
From: guke <guke@autohome.com.cn>
Date: Wed, 8 Jul 2026 19:13:51 +0800
Subject: [PATCH] =?UTF-8?q?docs(dev):=20=E8=AE=B0=E5=BD=95=E6=9C=AC?=
 =?UTF-8?q?=E5=9C=B0=20Docker=20PostgreSQL=20=E7=94=A8=E6=B3=95,=E5=8C=BA?=
 =?UTF-8?q?=E5=88=86=E7=94=9F=E4=BA=A7=E5=8E=9F=E7=94=9F=20PG=20=E8=B7=AF?=
 =?UTF-8?q?=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- postgres-migration.md 增「1.0 Docker 一键起」推荐节
- CLAUDE.md 订正 Dev/Test 已切 Docker PG(不再 SQLite)+ conftest 描述
- init_postgres.py docstring 标明其面向生产原生 PG,本地改用 compose

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                           |  6 +++---
 docs/database/postgres-migration.md | 16 +++++++++++++++-
 scripts/init_postgres.py            |  4 +++-
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index df80e80..6e812d5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -76,8 +76,8 @@ Endpoints under `app/api/internal/` are for server-to-server communication (pric
 
 ## Database
 
-- **Dev**: SQLite (`sqlite:///./data/app.db`), `check_same_thread=False`, no connection pool.
-- **Prod**: PostgreSQL — just change `DATABASE_URL` in `.env`. Pool size 10 + max overflow 20, pool_recycle 3600.
+- **Dev/Test**: Docker PostgreSQL 16 — `run.sh`/`run.bat` auto-start it via `scripts/ensure_pg.py` + `docker-compose.yml`; `.env.example` ships the PG URL by default; pytest uses the same container's `shaguabijia_test` DB. **Local no longer uses SQLite** (the SQLite branch in `db/session.py` is retained as a fallback only).
+- **Prod**: native PostgreSQL — bootstrap with `scripts/init_postgres.py` (no Docker). Pool size 10 + max overflow 20, pool_recycle 3600.
 - **Migrations**: Alembic with `render_as_batch` for SQLite compatibility. ~60+ migration files in `alembic/versions/` (filenames are descriptive, not hex prefixes). Migration chain uses `down_revision` within each file.
 - **New models**: Define in `app/models/`, import in `app/models/__init__.py`, then run `alembic revision --autogenerate`.
 
@@ -89,7 +89,7 @@ All config via `pydantic-settings` in `app/core/config.py`. Single `Settings` cl
 
 ## Testing
 
-- `tests/conftest.py`: Sets env vars BEFORE imports, creates temp SQLite file, builds all tables with `Base.metadata.create_all()`, tears down with `drop_all()` + unlink.
+- `tests/conftest.py`: Sets env vars BEFORE imports, ensures the Docker PG `shaguabijia_test` DB via `scripts/ensure_pg.py`, builds all tables with `Base.metadata.create_all()` (drop+create for a clean start), tears down with `drop_all()`.
 - External integrations are monkeypatched in tests (e.g., WeChat Pay, Jiguang, Pangle callbacks) — tests never make real HTTP calls.
 - `TestClient` from FastAPI is used for all tests. Rate limiting is disabled globally in tests.
 
diff --git a/docs/database/postgres-migration.md b/docs/database/postgres-migration.md
index 84f6567..658ec6b 100644
--- a/docs/database/postgres-migration.md
+++ b/docs/database/postgres-migration.md
@@ -27,7 +27,21 @@ PG 默认上 16 版(工具链最齐),驱动用 **psycopg3**(SQLAlchemy 2.0 时
 
 ## 1. 本地起 PG + 跑通空库(半天)
 
-### 1.1 装 PG
+### 1.0 推荐:Docker 一键起(本地开发/测试)
+
+本地开发不必手动装 PG。已提供 `docker-compose.yml` + `scripts/ensure_pg.py`:
+
+```bash
+cp .env.example .env    # DATABASE_URL 默认已是 Docker PG 连接串
+./run.sh                # 或 run.bat;会自动:探测 PG → 没起则启 Docker → 起 PG 容器 → 建库 → alembic → uvicorn
+pytest                  # conftest 自动引导同一容器的 shaguabijia_test 库
+```
+
+容器:`postgres:16-alpine`(名 `shaguabijia-pg`,端口 5432,命名卷 `pgdata` 持久化),
+首启即建业务库 `shaguabijia` 与测试库 `shaguabijia_test`。下面 1.1-1.5 的手动装 PG 步骤仅在
+不用 Docker 时才需要;生产仍走 §4 的原生 PG。
+
+### 1.1 装 PG(不用 Docker 时的手动方式)
 
 macOS:
 ```bash
diff --git a/scripts/init_postgres.py b/scripts/init_postgres.py
index 0890dbc..082efaf 100644
--- a/scripts/init_postgres.py
+++ b/scripts/init_postgres.py
@@ -1,6 +1,8 @@
 """Bootstrap PostgreSQL: 建用户 + 建库 + 授权 + 写 .env + 跑迁移。
 
-新机器初始化用。前置:已装 PostgreSQL 16 + 知道 postgres 超级用户密码。
+新机器初始化用(面向【生产原生 PG】:apt/systemd 装好的 PostgreSQL)。
+本地开发/测试请改用 docker-compose.yml + scripts/ensure_pg.py(run.sh/run.bat 自动拉起),不必跑本脚本。
+前置:已装 PostgreSQL 16 + 知道 postgres 超级用户密码。
 
 用法:
     python scripts/init_postgres.py