# 变更审计记录：card_type_id 年卡/月卡映射文档同步

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-19 18:46:00 |
| Prompt-ID | P20260319-174017 |
| Session-ID | 5164ca4c |
| Session 路径 | docs/audit/session_logs/2026-03/19/46_68666f1c_165708 |

## 操作摘要

用户确认 card_type_id 映射：`2791987095408517` = 年卡、`2793306611533637` = 月卡。将此映射信息同步到所有涉及 card_type_id 的文档中（API 参考、ETL 任务文档、DWS 手册）。同时发现 ETL 代码 `_extract_card_balances()` 中年卡/月卡余额未被统计的问题，已在 P12 PRD 中记录。

本次为纯文档同步，无代码/逻辑变更。

## 改动注解

### `apps/etl/connectors/feiqiu/docs/api-reference/endpoints/member_stored_value_cards.md`
- 变更类型：修改
- 原始原因：card_type_id 枚举原为纯文本列表，缺少年卡/月卡两种卡型
- 思路分析：将 card_type_id 枚举改为表格形式，补充年卡（2791987095408517）和月卡（2793306611533637）的 ID 与名称映射
- 修改结果：card_type_id 枚举从四种扩展为六种，表格形式更清晰

### `apps/etl/connectors/feiqiu/docs/api-reference/endpoints/member_balance_changes.md`
- 变更类型：修改
- 原始原因：card_type_id 枚举缺少年卡/月卡，文档描述"四种卡型"与实际不符
- 思路分析：补充年卡/月卡枚举值，修正"四种卡型"为"六种卡型"
- 修改结果：枚举完整覆盖所有已知卡型，描述文字与实际一致

### `apps/etl/connectors/feiqiu/docs/api-reference/summary/member_balance_changes.md`
- 变更类型：修改
- 原始原因：summary 文档中 card_type_id 和 memberCardTypeName 枚举同样缺少年卡/月卡
- 思路分析：同步补充两个字段的枚举值，保持与 endpoints 文档一致
- 修改结果：card_type_id 和 memberCardTypeName 枚举均已补全

### `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_recharge_summary.md`
- 变更类型：修改
- 原始原因：DWS 充值汇总表文档未说明年卡/月卡在统计中的处理方式
- 思路分析：新增"其他卡类型"段落，明确标注年卡/月卡未被 `_extract_card_balances()` 统计，导致 total_card_balance 可能偏低
- 修改结果：文档如实反映当前 ETL 代码的统计口径限制，为后续 P12 修复提供参考

### `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md`
- 变更类型：修改
- 原始原因：ETL 任务文档中两处卡类型映射表缺少年卡/月卡行
- 思路分析：在映射表中补充年卡和月卡的 card_type_id → 名称映射
- 修改结果：映射表完整覆盖六种卡型

### `docs/prd/specs/P12-gift-card-breakdown.md`
- 变更类型：新增
- 原始原因：用户要求编写 P1-6 礼品卡矩阵细分数据的 SPEC 任务 PRD
- 思路分析：基于 card_type_id 映射确认结果，编写 PRD 文档，包含卡类型表、当前 ETL 统计口径问题、待确认项
- 修改结果：P12 PRD 已创建，记录了年卡/月卡余额未被统计的问题及后续修复方向

## 本次对话文件变更

### 新增文件
- `docs/audit/changes/2026-03-19__level-map-hardcode-fix.md` — P2-9 等级映射硬编码修复审计记录
- `docs/audit/prompt_logs/prompt_log_20260319_174017.md` — Prompt 日志
- `docs/audit/session_logs/2026-03/19/46_68666f1c_165708/main_01_673610cb.md` — Session 日志（主）
- `docs/audit/session_logs/2026-03/19/46_68666f1c_165708/sub_01_673610cb.md` — Session 日志（子）
- `docs/audit/session_logs/2026-03/19/51_72888837_172821/main_01_f5f6b669.md` — Session 日志（主）
- `docs/prd/specs/P12-gift-card-breakdown.md` — P12 礼品卡矩阵细分 PRD

### 删除文件
- `docs/audit/session_logs/2026-03/19/46_68666f1c_165708/main_01_e979b0b8.md` — Session 日志替换
- `docs/audit/session_logs/2026-03/19/51_72888837_172821/main_01_654b0e80.md` — Session 日志替换

## 附带发现

ETL 代码 `_extract_card_balances()` 中年卡（2791987095408517）和月卡（2793306611533637）的余额未被统计——既不在 `cash_card_balance` 也不在 `gift_card_balance`，导致 `total_card_balance` 偏低。此问题已在 P12 PRD（`docs/prd/specs/P12-gift-card-breakdown.md`）中记录，待后续迭代修复。

## 合规检查

| 检查项 | 状态 |
|--------|------|
| 新增迁移 SQL | 无 |
| DDL 基线 | ⚠️ 待合并（has_ddl_baseline=false，但本次无新迁移） |
| OpenAPI spec | 无需同步（api_changed=false） |
| 文档同步 | `fdw_queries.py` 需同步 API-REFERENCE.md + README.md（见下方） |

### 待补文档
- `apps/backend/app/services/fdw_queries.py` 变更（新增 `get_level_map()`）需同步到：
  - `apps/backend/docs/API-REFERENCE.md`
  - `apps/backend/README.md`

## 文件清单

| 文件 | 操作 |
|------|------|
| `apps/etl/connectors/feiqiu/docs/api-reference/endpoints/member_stored_value_cards.md` | 修改 |
| `apps/etl/connectors/feiqiu/docs/api-reference/endpoints/member_balance_changes.md` | 修改 |
| `apps/etl/connectors/feiqiu/docs/api-reference/summary/member_balance_changes.md` | 修改 |
| `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_recharge_summary.md` | 修改 |
| `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md` | 修改 |
| `docs/prd/specs/P12-gift-card-breakdown.md` | 新增 |
| `apps/backend/app/services/fdw_queries.py` | 修改（P2-9 level 映射修复） |
