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>
127 lines
7.6 KiB
Markdown
127 lines
7.6 KiB
Markdown
# 变更审计记录：P18 任务引擎运营看板实施
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 日期 | 2026-03-24 07:44:01 |
|
||
| Prompt-ID | P20260324-072446 |
|
||
| Session-ID | — |
|
||
| Session 路径 | — |
|
||
|
||
## 操作摘要
|
||
|
||
基于已评审通过的 P18 PRD（v2.1-reviewed），实施管理后台任务引擎运营看板。新增 3 个前端页面（转移日志、待审核任务、参数管理）、9 个后端 API 端点、12 个 Pydantic Schema、1 个 DDL 迁移（trigger_jobs.last_stats + cfg_task_generator_params.updated_by）。
|
||
|
||
## 变更文件清单
|
||
|
||
### DDL 迁移
|
||
- `db/zqyy_app/migrations/2026-03-24__p18_task_engine_dashboard.sql` — trigger_jobs 新增 last_stats JSONB；cfg_task_generator_params 新增 updated_by BIGINT
|
||
- `docs/database/ddl/zqyy_app__biz.sql` — DDL 基线合并
|
||
|
||
### 后端（新建）
|
||
- `apps/backend/app/schemas/admin_task_engine.py` — 12 个 Pydantic v2 模型
|
||
- `apps/backend/app/routers/admin_task_engine.py` — 9 个端点（转移日志分页+历史、待审核任务分页+重新分配+关闭、参数管理 CRUD）
|
||
|
||
### 后端（修改）
|
||
- `apps/backend/app/main.py` — 追加 admin_task_engine router 注册
|
||
|
||
### 前端（新建）
|
||
- `apps/admin-web/src/api/taskEngine.ts` — API 调用模块（类型定义 + 9 个 API 函数）
|
||
- `apps/admin-web/src/pages/TransferLog.tsx` — 客户转移日志页面
|
||
- `apps/admin-web/src/pages/PendingReview.tsx` — 待审核任务页面
|
||
- `apps/admin-web/src/pages/TaskEngineConfig.tsx` — 参数管理页面
|
||
|
||
### 前端（修改）
|
||
- `apps/admin-web/src/App.tsx` — 新增任务引擎菜单组 + 3 个路由 + defaultOpenKeys
|
||
|
||
### 一次性脚本
|
||
- `scripts/ops/_p18_migrate.py` — DDL 迁移执行脚本（已执行完毕）
|
||
|
||
## 本次对话文件变更
|
||
|
||
### 新增文件
|
||
- `docs/audit/prompt_logs/prompt_log_20260324_072446.md`
|
||
- `docs/audit/session_logs/2026-03/24/29_3bf23309_071526/main_01_83361313.md`
|
||
|
||
## 风险点与待办
|
||
|
||
1. ⚠️ sites 表 JOIN 条件已修复（`s.site_id = t.site_id`），但需联调验证
|
||
2. ⚠️ FDW 姓名关联（member_name/assistant_name）尚未实现，当前返回空字符串，前端降级显示 ID
|
||
3. ⚠️ 权重参数联合校验依赖数据库事务，需验证并发场景
|
||
4. ⚠️ DDL 基线已合并（`docs/database/ddl/zqyy_app__biz.sql`）
|
||
|
||
## DDL/迁移状态
|
||
|
||
- 迁移文件：`db/zqyy_app/migrations/2026-03-24__p18_task_engine_dashboard.sql`
|
||
- 新增字段：`biz.trigger_jobs.last_stats` (JSONB)、`biz.cfg_task_generator_params.updated_by` (BIGINT)
|
||
- 迁移脚本使用 `ADD COLUMN IF NOT EXISTS`，幂等安全
|
||
- DDL 基线：已合并到 `docs/database/ddl/zqyy_app__biz.sql`
|
||
|
||
|
||
## 改动注解
|
||
|
||
### `db/zqyy_app/migrations/2026-03-24__p18_task_engine_dashboard.sql`
|
||
- 变更类型：新增
|
||
- 原始原因：P18 运营看板需要 trigger_jobs 表记录最近一次执行统计（last_stats JSONB），以及 cfg_task_generator_params 表记录修改人（updated_by BIGINT）用于审计追溯
|
||
- 思路分析：使用 `ADD COLUMN IF NOT EXISTS` 保证幂等性；last_stats 为 JSONB 类型，灵活存储 created/replaced/skipped/transferred 等统计数字；updated_by 为 BIGINT 对应 user_id
|
||
- 修改结果：trigger_jobs 表新增 1 字段，cfg_task_generator_params 表新增 1 字段，均可空，不影响现有查询
|
||
|
||
### `apps/backend/app/schemas/admin_task_engine.py`
|
||
- 变更类型：新增
|
||
- 原始原因：P18 运营看板 9 个 API 端点需要请求/响应数据模型
|
||
- 思路分析：12 个 Pydantic v2 模型，按功能分组（转移日志 2 个、待审核任务 6 个、参数管理 4 个）。所有模型使用 `str | None` 联合类型语法，字段默认值合理（如 member_name 默认空字符串，兼容 FDW 姓名未关联场景）
|
||
- 修改结果：为 admin_task_engine router 提供完整的类型安全数据模型
|
||
|
||
### `apps/backend/app/routers/admin_task_engine.py`
|
||
- 变更类型：新增
|
||
- 原始原因：P18 运营看板需要 9 个管理端 API 端点，覆盖转移日志查看、待审核任务管理、参数配置 CRUD
|
||
- 思路分析：路由前缀 `/api/admin/task-engine`，写操作通过 `_require_super_admin()` 限制仅超级管理员；读操作通过 `_filter_site_id()` 实现门店管理员数据隔离。SQL 使用参数化查询防注入，sites 表 JOIN 使用 `s.site_id`（已修复原 `s.id` 错误）。权重参数更新后做联合校验（w_rs + w_ms + w_ml = 1.0）
|
||
- 修改结果：9 个端点全部注册，含完整的权限校验、门店隔离、事务管理和错误处理
|
||
|
||
### `apps/backend/app/main.py`
|
||
- 变更类型：修改
|
||
- 原始原因：新增的 admin_task_engine router 需要在 FastAPI 应用中注册
|
||
- 思路分析：在 import 行和 `app.include_router()` 调用中追加 admin_task_engine，保持与现有 router 注册模式一致
|
||
- 修改结果：admin_task_engine router 已注册，9 个端点可通过 /docs 访问
|
||
|
||
### `apps/admin-web/src/api/taskEngine.ts`
|
||
- 变更类型：新增
|
||
- 原始原因：前端 3 个页面需要与后端 9 个 API 端点通信
|
||
- 思路分析：定义 TypeScript 接口（TransferLogItem/Page、PendingReviewItem/Page、ConfigParam/List）和 9 个 API 函数，使用 apiClient（Axios 实例）统一处理 JWT 认证和错误
|
||
- 修改结果：前端 API 层完整覆盖后端所有端点
|
||
|
||
### `apps/admin-web/src/pages/TransferLog.tsx`
|
||
- 变更类型：新增
|
||
- 原始原因：运营团队需要查看客户转移日志，按门店/时间/助教筛选
|
||
- 思路分析：Ant Design Table 分页表格 + RangePicker 日期筛选 + InputNumber 门店/助教 ID 筛选。guard_checks JSON 渲染为彩色标签（通过/未通过）。transfer_reason 映射中文标签
|
||
- 修改结果：转移日志页面完整可用，支持分页、筛选、guard_checks 可视化
|
||
|
||
### `apps/admin-web/src/pages/PendingReview.tsx`
|
||
- 变更类型：新增
|
||
- 原始原因：运营团队需要审核 pending_review 状态的任务，执行重新分配或关闭操作
|
||
- 思路分析：分页表格 + 重新分配弹窗（输入目标助教 ID）+ 关闭弹窗（填写原因）+ 转移历史抽屉（点击客户名查看）。操作列仅超级管理员可见（`isSuperAdmin` 判断）
|
||
- 修改结果：待审核任务页面完整可用，含权限控制和完整的操作流程
|
||
|
||
### `apps/admin-web/src/pages/TaskEngineConfig.tsx`
|
||
- 变更类型：新增
|
||
- 原始原因：运营团队需要按门店调整任务生成参数，监控参数配置
|
||
- 思路分析：全局默认 + 门店覆盖参数表格，行内编辑单个参数值。权重参数（w_rs/w_ms/w_ml）使用独立的卡片编辑弹窗，前端预校验三者之和 = 1.0。新增门店覆盖通过 Select 选择参数名 + InputNumber 输入值。全局默认参数禁止删除
|
||
- 修改结果：参数管理页面完整可用，含行内编辑、权重卡片编辑、新增/删除门店覆盖
|
||
|
||
### `apps/admin-web/src/App.tsx`
|
||
- 变更类型：修改
|
||
- 原始原因：新增的 3 个页面需要在侧边栏导航和路由中注册
|
||
- 思路分析：新增 ApartmentOutlined 图标 import、3 个页面 import、task-engine-group 菜单组（含 3 个子菜单）、3 个 Route、defaultOpenKeys 补充 task-engine-group（当路径以 /task-engine/ 开头时自动展开）
|
||
- 修改结果：侧边栏新增「任务引擎」菜单组，3 个子页面路由正常工作
|
||
|
||
### `scripts/ops/_p18_migrate.py`
|
||
- 变更类型：新增
|
||
- 原始原因：DDL 迁移需要执行脚本
|
||
- 思路分析：一次性脚本，连接测试库执行迁移 SQL
|
||
- 修改结果：迁移已执行完毕，脚本保留用于记录
|
||
|
||
## 验证建议
|
||
|
||
1. 启动后端 `uvicorn app.main:app --reload`，访问 /docs 确认 9 个端点注册
|
||
2. 启动前端 `pnpm dev`，验证侧边栏「任务引擎」菜单组和 3 个页面路由
|
||
3. 用 super_admin JWT 测试写操作，用 site_admin JWT 验证 403
|