root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

在前后端开发联调前 的提交20260223

Browse Source
This commit is contained in:
Neo
2026-02-23 23:02:20 +08:00
parent 254ccb1e77
commit fafc95e64c
1142 changed files with 10366960 additions and 36957 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
apps/etl/connectors/feiqiu/docs/database/ODS/changes/.gitkeep Normal file
View File

96
apps/etl/connectors/feiqiu/docs/database/ODS/changes/2026-02-13_ddl_sync_ods.md
View File

@@ -1,96 +0,0 @@
# ODS 层 DDL 同步修正 — 变更记录
> 结构性变更：修正 4 项差异（删除 2 个冗余字段、修正 1 个字段类型、补充 1 个缺失字段）
## 溯源
- 日期：2026-02-13（Asia/Shanghai）
- 工具：`scripts/compare_ddl_db.py --schema ods --ddl-path database/schema_ODS_doc.sql`
- Direct cause：DDL 对比脚本发现 `database/schema_ODS_doc.sql` 与数据库 `ods` schema 实际状态存在 4 项差异，以数据库为准修正 DDL 文件。
## 变更内容
| Schema | 表名 | 操作 | 字段 | DDL 原定义 | 数据库实际 | 说明 |
|--------|------|------|------|-----------|-----------|------|
| `ods` | `recharge_settlements` | DDL 删除字段 | `settlelist` | `jsonb` | — | DDL 中有但数据库中不存在，属冗余定义 |
| `ods` | `settlement_records` | DDL 删除字段 | `settlelist` | `jsonb` | — | DDL 中有但数据库中不存在，属冗余定义 |
| `ods` | `tenant_goods_master` | DDL 修正类型 | `not_sale` | `BOOLEAN` | `INTEGER` | 字段类型不匹配，以数据库为准 |
| `ods` | `refund_transactions` | DDL 补充字段 | `check_status` | — | `INTEGER` | 数据库中有但 DDL 中未定义 |
## 变更原因
1. `recharge_settlements.settlelist` 和 `settlement_records.settlelist`：DDL 文件中残留的字段定义，数据库中已在先前迁移（`20260214_drop_ods_settlelist.sql`）中删除，DDL 未同步清理
2. `tenant_goods_master.not_sale`：DDL 定义为 `BOOLEAN`，但数据库实际为 `INTEGER`（0/1 表示是否停售），以数据库为准修正
3. `refund_transactions.check_status`：数据库中存在的审核状态字段，DDL 文件中遗漏未定义
## 影响范围
| 影响对象 | 影响程度 | 说明 |
|----------|----------|------|
| ETL 加载任务 | 无影响 | 本次仅修正 DDL 文档，不涉及数据库结构变更 |
| 后端 API | 无影响 | DDL 文件为文档性质，不影响运行时 |
| 小程序字段映射 | 无影响 | 小程序不直接读 ODS 层 |
| ODS 表级文档 | ⚠️ 需同步 | 后续生成 ODS 表级文档时应以修正后的 DDL 为准 |
| DWD 加载映射 | 无影响 | `refund_transactions.check_status` 已在 DWD 层有对应映射 |
**注意**：本次变更仅修正 DDL 文件（文档同步），数据库结构未发生任何变更。数据库是"源头"，DDL 文件是"文档"。
## 回滚策略
本次为 DDL 文件修正（文档同步），无需数据库回滚。若需恢复 DDL 文件，使用 Git 回退即可：
```bash
git checkout HEAD~1 -- database/schema_ODS_doc.sql
```
若未来需要将数据库结构回退到 DDL 修正前的状态（不推荐）：
```sql
-- 1) 恢复 settlelist 列（数据不可恢复）
ALTER TABLE ods.recharge_settlements ADD COLUMN settlelist JSONB;
ALTER TABLE ods.settlement_records ADD COLUMN settlelist JSONB;
-- 2) 将 not_sale 改回 BOOLEAN（需数据转换）
ALTER TABLE ods.tenant_goods_master
ALTER COLUMN not_sale TYPE BOOLEAN USING (not_sale::INTEGER != 0);
-- 3) 删除 check_status 列
ALTER TABLE ods.refund_transactions DROP COLUMN check_status;
```
## 验证 SQL
```sql
-- 1) 确认 settlelist 列在数据库中确实不存在
SELECT column_name
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name IN ('recharge_settlements', 'settlement_records')
AND column_name = 'settlelist';
-- 预期：0 行
-- 2) 确认 tenant_goods_master.not_sale 实际类型为 integer
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'tenant_goods_master'
AND column_name = 'not_sale';
-- 预期：data_type = 'integer'
-- 3) 确认 refund_transactions.check_status 存在且类型为 integer
SELECT column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'refund_transactions'
AND column_name = 'check_status';
-- 预期：1 行，data_type = 'integer'
-- 4) 确认修正后 DDL 与数据库零差异（通过对比脚本验证）
-- python scripts/compare_ddl_db.py --schema ods --ddl-path database/schema_ODS_doc.sql
-- 预期：0 项差异
```
## 关联文件
- DDL 文件：`database/schema_ODS_doc.sql`
- 对比结果：`docs/database/ddl_compare_results.md`

39
apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260213_align_ods_with_api.md
View File

@@ -1,39 +0,0 @@
# ODS 表与 API JSON 字段对齐 — 变更记录
> 无结构性变更
## 溯源
- 日期：2026-02-13（Asia/Shanghai）
- Prompt：P20260213-210000 — 用新梳理的 API 返回 JSON 文档比对数据库 ODS 层
- Direct cause：`scripts/compare_api_ods.py` 自动比对 22 张 ODS 表与 `docs/api-reference/` 文档中的 JSON 字段，结论为全部对齐，无需 ALTER
## 说明
迁移文件 `database/migrations/20260213_align_ods_with_api.sql` 为比对结论记录，不包含任何 DDL 语句。
- 比对范围：`ods` schema 下 22 张表
- 比对逻辑：camelCase → snake_case 归一化匹配 + 去下划线纯小写兜底
- 结论：所有 ODS 表列已与 API JSON 响应字段完全对齐
- `stock_goods_category_tree` 的 `goodsCategoryList`/`total` 为响应包装层字段，ODS 表已正确展开存储数组内的记录级字段，无需额外列
## 验证 SQL
```sql
-- 1) 确认 ods schema 下表数量
SELECT count(*) FROM information_schema.tables
WHERE table_schema = 'ods' AND table_type = 'BASE TABLE';
-- 2) 确认迁移文件未引入新列（对比前后列数应一致）
SELECT table_name, count(*) AS col_count
FROM information_schema.columns
WHERE table_schema = 'ods'
GROUP BY table_name
ORDER BY table_name;
-- 3) 确认无待执行的 pending migration（迁移文件为纯注释，不应产生任何变更）
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'ods' AND table_name = 'assistant_accounts_master'
ORDER BY ordinal_position;
```

111
apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260214_drop_ods_option_name_able_site_transfer.md
View File

@@ -1,111 +0,0 @@
# ODS 层删除 option_name / able_site_transfer 冗余列 — 变更记录
> 结构性变更：删除 2 张表各 1 个冗余列（API JSON 中不存在，ODS 全 NULL）
## 溯源
- 日期：2026-02-14（Asia/Shanghai）
- Prompt：P20260214-070000 — 删除 ODS 层 store_goods_sales_records.option_name 和 member_stored_value_cards.able_site_transfer
- Direct cause：API vs ODS 比对报告（v3-fixed）中这两列被标注为"ODS 独有"，经查证 API JSON 响应中从未返回这两个字段，ODS 中全部为 NULL（0 条非空数据），属于冗余列，应清理。
## 变更内容
| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
|--------|------|------|------|--------|------|
| `ods` | `store_goods_sales_records` | DROP COLUMN | `option_name` | `text` | API 后续版本新增字段，实际从未返回数据，全 NULL |
| `ods` | `member_stored_value_cards` | DROP COLUMN | `able_site_transfer` | `integer` | API 后续版本新增字段，实际从未返回数据，全 NULL |
### Before / After
**store_goods_sales_records**：
- Before：52 个业务列 + 5 个 meta 列（含 `option_name text`）
- After：51 个业务列 + 5 个 meta 列（`option_name` 已移除）
**member_stored_value_cards**：
- Before：76 个业务列 + 5 个 meta 列（含 `able_site_transfer integer`）
- After：75 个业务列 + 5 个 meta 列（`able_site_transfer` 已移除）
## 变更原因
1. v3-fixed 比对报告显示 `option_name` 和 `able_site_transfer` 为"ODS 独有"字段
2. 全量 JSON 刷新审计（100 条/接口）确认 API 响应中从未包含这两个字段
3. 数据库查询确认两列全部为 NULL，无实际业务数据
4. 保留全 NULL 的冗余列会误导后续开发和数据分析
## 影响范围
| 影响对象 | 影响程度 | 说明 |
|----------|----------|------|
| ODS 抓取任务 | ⚠️ 需确认 | ODS 入库 INSERT/UPSERT 语句中若包含这两列需移除 |
| DWD 加载任务 | 无影响 | DWD 层未映射这两个字段（全 NULL 无法产生有意义的 DWD 数据） |
| API 契约 | 无影响 | API 响应结构不变，这两个字段本就不在 API 返回中 |
| 小程序 | 无影响 | 小程序不直接读 ODS 层 |
| 比对报告 | 需更新 | `docs/reports/api_ods_comparison_v3_fixed.md` 中两表的 ODS 独有字段需移除 |
## 回滚策略
```sql
-- 恢复列结构（数据不可恢复，因原始数据全为 NULL）
ALTER TABLE ods.store_goods_sales_records ADD COLUMN option_name TEXT;
ALTER TABLE ods.member_stored_value_cards ADD COLUMN able_site_transfer INTEGER;
```
**注意事项**：
- 回滚后两列数据均为 NULL（与删除前一致），无数据丢失风险
- 若未来 API 版本开始返回这两个字段，需重新 ADD COLUMN 并更新 ODS 入库逻辑
## 验证 SQL
```sql
-- 1) 确认 option_name 列已不存在
SELECT column_name
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'store_goods_sales_records'
AND column_name = 'option_name';
-- 预期：0 行
-- 2) 确认 able_site_transfer 列已不存在
SELECT column_name
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'member_stored_value_cards'
AND column_name = 'able_site_transfer';
-- 预期：0 行
-- 3) 确认两表当前列数
SELECT table_name, count(*) AS total_columns
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name IN ('store_goods_sales_records', 'member_stored_value_cards')
GROUP BY table_name;
-- 预期：store_goods_sales_records = 56（51 业务 + 5 meta），member_stored_value_cards = 80（75 业务 + 5 meta）
-- 4) 确认删除前数据确实全 NULL（回溯验证，迁移执行前运行）
-- SELECT count(*) FROM ods.store_goods_sales_records WHERE option_name IS NOT NULL;
-- SELECT count(*) FROM ods.member_stored_value_cards WHERE able_site_transfer IS NOT NULL;
-- 预期：均为 0
```
## 迁移文件
`database/migrations/20260214_drop_ods_option_name_able_site_transfer.sql`
---
## 补充记录：schema_ODS_doc.sql AI_CHANGELOG 标注
- 日期：2026-02-14（Asia/Shanghai）
- Prompt：P20260214-070000（同上）
- 变更内容：在 `database/schema_ODS_doc.sql` 末尾追加 AI_CHANGELOG 注释块，记录 option_name / able_site_transfer 两列在 DDL 文档中的注释化处理
- 结论：**无结构性变更**（仅追加 SQL 注释，不涉及 DDL 操作）
<!--
AI_CHANGELOG:
- 日期: 2026-02-14
- Prompt: P20260214-070000 — ODS 清理与文档标注（5 项任务）
- 直接原因: DB schema 变更（删除 2 列）必须同步 BD Manual
- 变更摘要: 新建 ODS 层变更记录文档，记录 option_name 和 able_site_transfer 的删除原因、影响、回滚策略和验证 SQL
- 风险与验证: 纯文档；验证：验证 SQL 执行结果与预期一致
-->

102
apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260214_drop_ods_settlelist.md
View File

@@ -1,102 +0,0 @@
# ODS 层删除 settlelist 冗余列 — 变更记录
> 结构性变更：删除 2 张表的 1 个 jsonb 列
## 溯源
- 日期：2026-02-14（Asia/Shanghai）
- Prompt：P20260214-023000 — 删除 ODS 层 settlement_records / recharge_settlements 的 settlelist jsonb 列
- Direct cause：`settlelist` 列与 `payload` 列数据完全重复（`payload` 存储完整 API 响应 JSON，已包含 `settleList` 对象），属于冗余存储。DWD 加载逻辑已改为从 `payload` 提取 `settleList`，该列不再被任何下游消费。
## 变更内容
| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
|--------|------|------|------|--------|------|
| `ods` | `settlement_records` | DROP COLUMN | `settlelist` | `jsonb` | 存储原始 settleList 对象，与 payload 重复 |
| `ods` | `recharge_settlements` | DROP COLUMN | `settlelist` | `jsonb` | 存储原始 settleList 对象，与 payload 重复 |
### Before / After
**settlement_records**：
- Before：67 个业务列 + 5 个 meta 列（含 `settlelist jsonb`）
- After：66 个业务列 + 5 个 meta 列（`settlelist` 已移除）
**recharge_settlements**：
- Before：67 个业务列 + 5 个 meta 列（含 `settlelist jsonb`）
- After：66 个业务列 + 5 个 meta 列（`settlelist` 已移除）
## 变更原因
1. `payload` 列（jsonb）已存储完整的 API 响应 JSON，其中包含 `settleList` 对象
2. `settlelist` 列是 ETL 入库时从 `payload` 中额外提取并单独存储的副本，属于冗余
3. API vs ODS 比对报告（v3-fixed）中已标注 `settlelist` 为"ODS jsonb 列（存储原始 settleList 对象）"
4. DWD 加载逻辑已修改为直接从 `payload->'settleList'` 提取数据
## 影响范围
| 影响对象 | 影响程度 | 说明 |
|----------|----------|------|
| DWD 加载任务 | ⚠️ 需确认 | DWD 加载必须已改为从 `payload` 提取 settleList，不再读 `settlelist` 列 |
| ODS 抓取任务 | ⚠️ 需确认 | ODS 入库逻辑需移除对 `settlelist` 列的写入（INSERT/UPSERT 语句） |
| API 契约 | 无影响 | API 响应结构不变，仅 ODS 存储方式调整 |
| 小程序 | 无影响 | 小程序不直接读 ODS 层 |
| 比对报告 | 需更新 | `docs/reports/api_ods_comparison_v3.md` 和 `scripts/ods_columns.json` 中 settlement_records / recharge_settlements 的列清单需移除 `settlelist` |
| 比对脚本 | 需更新 | `scripts/run_compare_v3_fixed.py` 中 `classify_ods_only()` 对 `settlelist` 的特殊处理可移除 |
## 回滚策略
```sql
-- 1) 恢复列结构
ALTER TABLE ods.settlement_records ADD COLUMN settlelist jsonb;
ALTER TABLE ods.recharge_settlements ADD COLUMN settlelist jsonb;
-- 2) 从 payload 回填数据（回滚后列为 NULL，需重新提取）
UPDATE ods.settlement_records
SET settlelist = payload->'settleList'
WHERE payload IS NOT NULL;
UPDATE ods.recharge_settlements
SET settlelist = payload->'settleList'
WHERE payload IS NOT NULL;
```
**注意事项**：
- 回滚后 `settlelist` 列数据为 NULL，必须执行回填 UPDATE
- 若历史数据中存在 `payload IS NULL` 的行，这些行的 `settlelist` 将永久丢失（无法恢复）
- 回填前建议先统计 `payload IS NULL` 的行数，评估数据损失范围
## 验证 SQL
```sql
-- 1) 确认 settlelist 列已不存在
SELECT column_name
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name IN ('settlement_records', 'recharge_settlements')
AND column_name = 'settlelist';
-- 预期：0 行
-- 2) 确认 payload 列仍存在且包含 settleList 数据
SELECT count(*)
FROM ods.settlement_records
WHERE payload IS NOT NULL AND payload->'settleList' IS NOT NULL;
-- 预期：> 0（确认 payload 中有 settleList 数据可用）
-- 3) 确认两表当前列数（排除 meta 列后应为 66）
SELECT table_name, count(*) AS total_columns
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name IN ('settlement_records', 'recharge_settlements')
GROUP BY table_name;
-- 预期：settlement_records = 71（66 业务 + 5 meta），recharge_settlements = 71
-- 4) 确认 DWD 加载可从 payload 正常提取 settleList
SELECT id, (payload->'settleList') IS NOT NULL AS has_settle_list
FROM ods.settlement_records
LIMIT 5;
-- 预期：has_settle_list = true（至少对 payload 非空的行）
```
## 迁移文件
`database/migrations/20260214_drop_ods_settlelist.sql`