迁移 Claude/Codex/Cursor 开发环境与追溯资产

Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

db/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md - Database (DDL / Migrations / Seeds)
+
+进入本目录时自动加载。
+
+## Schema 变更规则
+
+修改任何影响 PostgreSQL schema 的内容（迁移脚本/DDL/表定义）时，必须同步更新 `docs/database/`：
+
+1. **变更说明**：新增/修改/删除的表、字段、约束、索引
+2. **兼容性**：对 ETL、后端 API、小程序字段映射的影响
+3. **回滚策略**：如何撤销（DDL 回滚 / 数据回填）
+4. **验证步骤**：至少 3 条校验 SQL
+
+## RLS 视图双 Schema 规则
+
+新建 DWS/DWD 表的 RLS 视图必须同时在原 schema（如 `dws`）和 `app` schema 创建：
+
+```sql
+-- 1. 原 schema
+CREATE VIEW dws.v_xxx AS SELECT ... WHERE site_id = current_setting('app.current_site_id')::int;
+
+-- 2. app schema（后端通过此路径访问）
+CREATE VIEW app.v_xxx AS SELECT ... WHERE site_id = current_setting('app.current_site_id')::int;
+```
+
+回滚需逆序 DROP 两个 schema 的视图。只在原 schema 创建会导致后端查询失败。
+
+## 目录结构
+
+```text
+db/
+├── etl_feiqiu/
+│   ├── schemas/          # 权威 DDL — 六层完整定义（meta/ods/dwd/core/dws/app）
+│   ├── migrations/       # 未来增量迁移（v1 已全部归档）
+│   ├── ods/              # ODS 补充脚本
+│   └── scripts/          # 测试数据库脚本
+├── zqyy_app/
+│   ├── schemas/          # 权威 DDL — 三层完整定义（public/auth/biz）
+│   ├── migrations/       # 未来增量迁移（v1 已全部归档）
+│   └── scripts/          # 测试数据库脚本
+├── fdw/                  # FDW 跨库只读映射（正向 + 反向 + 测试环境）
+└── _archived/            # 归档（v1 迁移 39 个、旧基线）
+```
+
+v1 阶段种子数据已合并进 `schemas/` 对应 DDL 文件末尾，不再单独维护。
+
+## DDL 刷新
+
+修改 schema 后，重新生成完整 DDL：
+
+```bash
+PYTHONUTF8=1 python tools/db/gen_consolidated_ddl.py
+```
+
+输出到 `docs/database/ddl/`，然后复制到 `db/*/schemas/` 保持同步。
+
+## 测试规范
+
+- 数据库操作使用测试库（`TEST_DB_DSN` / `TEST_APP_DB_DSN`），禁止连正式库
+- 迁移脚本在测试库执行后需验证表结构