Neo-ZQYY/docs/audit/changes/2026-02-26__p1-p2-p3-fullstack-integration.md

变更审计：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）