Neo
14a12342b5
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。
按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。
涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
DDL 基线合并 / Kiro 到 Claude Code 迁移
阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
101 lines
5.9 KiB
Markdown
101 lines
5.9 KiB
Markdown
# 变更审计：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）
|