# 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`
