# 变更审计：P1/P2/P3 全栈集成（DB 基础 + ETL DWS 扩展 + 小程序鉴权）

- **日期**: 2026-02-26
- **Prompt-ID**: P20260226-061159 → P20260226-062329（审计收口）
- **风险等级**: 🔴 高（DB schema + 鉴权 + ETL 调度逻辑 + 资金精度）
- **触发原因**: root-file, dir:backend, dir:etl, dir:db, db-schema-change

---

## 1. 变更概览

本次变更横跨 3 个 spec 阶段，涉及 117 个文件（+2326 / -31961 行），核心逻辑改动分 5 大领域。

## 2. 核心逻辑变更

### 2.1 ETL 拓扑排序：隐含层级依赖注入
- **文件**: `apps/etl/connectors/feiqiu/orchestration/topological_sort.py`
- **变更**: Kahn 算法新增隐含层级依赖（ODS→DWD→DWS→INDEX），修复管理后台全选任务时不按层级顺序执行的 bug
- **影响**: 所有 ETL 批量执行路径；同层任务无隐含互依赖
- **风险**: 中——新增边可能引入循环依赖（已有 cycle 检测兜底）

### 2.2 ETL FlowRunner + TaskExecutor 健壮性
- **文件**: `orchestration/flow_runner.py`, `orchestration/task_executor.py`
- **变更**:
  - FlowRunner: 前端传入的 task_codes 也经过 topological_sort 排序
  - TaskExecutor: 任务失败后执行 `db.rollback()` 防止 InFailedSqlTransaction 级联
- **影响**: 所有增量 ETL 执行路径
- **风险**: 低——rollback 为防御性编程，sort 已有单测覆盖

### 2.3 DWS 助教日报：定档折算惩罚检测
- **文件**: `tasks/dws/assistant_daily_task.py`
- **变更**:
  - 新增 `PENALTY_AREAS` 常量（大厅 A/B/C/S/TV + 麻将房 M1-M7）
  - 新增 `detect_overlap_violations()` 扫描线算法检测同台超 2 人挂台
  - 新增 `compute_penalty_minutes()` 惩罚分钟计算（阈值 24 元/小时）
  - transform 阶段注入惩罚字段：penalty_minutes, penalty_reason, is_exempt, per_hour_contribution
  - SQL 提取新增 start_use_time, last_use_time, table_area_name 字段
- **影响**: dws.dws_assistant_daily 表结构 + 助教薪资计算链路
- **风险**: 🔴 高——涉及资金精度（Decimal ROUND_HALF_UP）和业务口径变更

### 2.4 DWS 新增任务 + 会员消费扩展
- **文件**: `tasks/dws/assistant_order_contribution_task.py`（新增）, `tasks/dws/member_consumption_task.py`
- **变更**:
  - 新增 DWS_ASSISTANT_ORDER_CONTRIBUTION 任务（助教订单贡献度）
  - MemberConsumptionTask 新增充值统计（30/60/90 天窗口）+ 次均消费计算
  - task_registry 注册新任务 + DWS_MAINTENANCE depends_on 更新
- **影响**: DWS 层任务 DAG 拓扑 + 会员消费宽表字段
- **风险**: 中——新任务需验证 DDL 已执行

### 2.5 后端鉴权：双令牌体系（P3 小程序认证）
- **文件**: `apps/backend/app/auth/dependencies.py`, `auth/jwt.py`, `routers/xcx_auth.py`（新增）, `schemas/xcx_auth.py`（新增）, `services/wechat.py`（新增）, `services/role.py`（新增）, `services/application.py`（新增）, `services/matching.py`（新增）
- **变更**:
  - CurrentUser 扩展：新增 roles, status, limited 字段
  - JWT: create_access_token 支持 roles 参数；新增 create_limited_token_pair（pending 用户受限令牌）
  - 新增 get_current_user_or_limited 依赖（允许 pending 用户访问申请端点）
  - get_current_user 拒绝 limited 令牌（完整端点保护）
  - 新增微信小程序登录路由 + 角色/申请/匹配服务
- **影响**: 所有 API 鉴权路径 + 小程序登录流程
- **风险**: 🔴 高——鉴权权限变更，limited 令牌边界需严格测试

## 3. DB Schema 变更

| 迁移文件 | 库 | 类型 | 说明 |
|---|---|---|---|
| `2025-02-24__alter_assistant_daily_add_penalty_fields.sql` | etl_feiqiu | ALTER | 助教日报新增惩罚字段 |
| `2025-02-24__alter_member_consumption_add_recharge_fields.sql` | etl_feiqiu | ALTER | 会员消费新增充值统计字段 |
| `2025-02-24__create_dws_assistant_order_contribution.sql` | etl_feiqiu | CREATE | 助教订单贡献度表 |
| `2025-02-24__create_rls_view_assistant_order_contribution.sql` | etl_feiqiu | CREATE | 贡献度 RLS 视图 |
| `2026-02-24__add_goods_stock_warning_info.sql` | etl_feiqiu | ALTER | 库存预警字段 |
| `2026-02-24__cleanup_assistant_abolish_residual.sql` | etl_feiqiu | DROP | 清理 assistant_abolish 残留 |
| `2026-02-24__p1_create_app_schema_rls_views.sql` | etl_feiqiu | CREATE | app schema RLS 视图 |
| `2026-02-24__p1_create_auth_biz_schemas.sql` | zqyy_app | CREATE | auth + biz schema |
| `2026-02-24__p1_setup_fdw_etl.sql` | zqyy_app | CREATE | FDW 连接 ETL 库 |
| `2025-02-24__add_fdw_dws_extensions.sql` | zqyy_app | CREATE | FDW DWS 扩展 |
| `2026-02-25__p3_create_auth_tables.sql` | zqyy_app | CREATE | 鉴权表（users/roles/permissions） |
| `2026-02-25__p3_seed_roles_permissions.sql` | zqyy_app | SEED | 角色权限种子数据 |

## 4. 种子数据变更
- `seed_ods_tasks.sql`: 移除 ODS_ASSISTANT_ABOLISH（全链路已清理）
- `seed_scheduler_tasks.sql`: 移除 ASSISTANT_ABOLISH

## 5. 防御性修复
- `quality/consistency_checker.py`: 异常后 rollback 防级联
- `tasks/dws/member_visit_task.py`: FDW 查询失败后 rollback 再 fallback
- `orchestration/task_executor.py`: 任务失败后 rollback

## 6. 其他变更
- `.gitignore`: 更新排除规则
- `docs/database/ddl/`: 多个 DDL 基线文件同步更新
- `docs/h5_ui/`: UI 原型页面更新（非逻辑改动）
- `docs/prd/specs/`: PRD 文档更新
- 根目录 PNG 文件：UI 截图（非逻辑改动）
- `export/` 下旧报告批量清理（-31961 行主要来源）

## 7. 验证建议
1. ETL 拓扑排序：运行 `pytest apps/etl/connectors/feiqiu/tests/unit/test_topological_sort.py`
2. 助教惩罚计算：验证 `detect_overlap_violations` + `compute_penalty_minutes` 边界
3. 鉴权系统：验证 limited 令牌不能访问完整端点、完整令牌不受影响
4. DB migration：确认 12 个迁移脚本在测试库已执行
5. 属性测试：`pytest tests/ -v`（test_auth_system_properties, test_dws_contribution_properties）