feat: 2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复
涵盖（每条对应已存的审计记录）： - AI 模块拆分：apps/backend/app/ai/apps -> prompts/（8 个 APP + app2a 派生） audit: 2026-04-20__ai-module-complete.md - admin-web AI 管理套件：AIDashboard / AIOperations / AIRunLogs / AITriggers / TriggerManager audit: 2026-04-21__admin-web-ai-management-suite.md - App2 财务洞察 prompt v3 -> v5.1 + 小程序 AI 接入（chat / board-finance） audit: 2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md - App2 prewarm 全过滤器 + AI 触发器 cron reschedule audit: 2026-04-21__app2-finance-prewarm-all-filters.md migration: 20260420_ai_trigger_jobs_and_app2_prewarm.sql / 20260421_app2_prewarm_cron_reschedule.sql - AppType 联合类型对齐 + adminAiAppTypes.test.ts audit: 2026-04-30__admin_web_ai_app_type_alignment.md - DashScope tokens_used 提取修复 audit: 2026-04-30__backend_dashscope_tokens_used_extraction.md - App3 线索完整详情 prompt audit: 2026-05-01__backend_app3_full_detail_prompt.md - Runtime Context 沙箱（5-1~5-2 主线）： - 后端 schema/service + admin_runtime_context / xcx_runtime_clock 两个 router - admin-web RuntimeContext.tsx + miniprogram runtime-clock.ts - migration: 20260501__runtime_context_sandbox.sql - tools/db/verify_admin_web_sandbox.py + verify_sandbox_end_to_end.py - database/changes: 7 份 sandbox_* 验证报告 - 飞球 DWS 修复：finance_area_daily 区域汇总 + task_engine 调整 + RLS 视图业务日上界（migration 20260502 + scripts/ops/gen_rls_business_date_migration.py） 合规： - .gitignore 启用 tmp/ 排除 - 不入仓：apps/etl/connectors/feiqiu/.env（API_TOKEN secret，本地修改保留） 待验证清单： - docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md 每个主题的功能完整性 / 上线验证几乎都未收口，按优先级 P0~P3 逐一处理
This commit is contained in:
120
docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md
Normal file
120
docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 审计记录：admin-web AI 管理套件（可视化全流程管控）
|
||||
|
||||
**日期**：2026-04-21
|
||||
**会话**：为 admin-web 补齐 AI 可视化管理页面 + 后端对应端点
|
||||
**影响范围**：backend（schemas/services/routers）/ admin-web（api/pages/App.tsx）
|
||||
|
||||
---
|
||||
|
||||
## 变更摘要
|
||||
|
||||
用户需求：
|
||||
> 为我在 admin-web 修改完善 AI 相关工具和板块。让我能有可视化的工具进行 AI 方面的全流程可视化可操作的管理，包含调试阶段的集中预热以及触发器状态设置等。
|
||||
|
||||
本次交付 2 个新页面 + 1 个页面增强 + 1 个 AI 一级菜单组，并新增 4 个后端端点作为前端数据源。
|
||||
|
||||
---
|
||||
|
||||
## 后端变更
|
||||
|
||||
### 新增 Pydantic 模型（`apps/backend/app/schemas/admin_ai.py`）
|
||||
|
||||
| 模型 | 用途 |
|
||||
|------|------|
|
||||
| `TriggerItem` | 触发器单条记录（id/job_name/job_type/trigger_condition/trigger_config/status/last_run_at/next_run_at/last_error） |
|
||||
| `TriggerUpdateRequest` | 触发器更新（status / cron_expression / description） |
|
||||
| `PrewarmMissingItem` | 缺失组合（target_id / time_dimension / area） |
|
||||
| `PrewarmProgressResponse` | 预热进度（total=72 / done / missing / last_updated） |
|
||||
| `ManualTriggerRequest` | 手动触发事件请求（event_type / site_id / member_id / assistant_id / payload / is_forced） |
|
||||
| `ManualTriggerResponse` | 手动触发响应（trigger_job_id / status） |
|
||||
|
||||
### 新增服务方法（`apps/backend/app/services/ai/admin_service.py`）
|
||||
|
||||
| 方法 | 实现 |
|
||||
|------|------|
|
||||
| `list_triggers()` | 查 `biz.trigger_jobs WHERE job_type LIKE 'ai_%' OR job_name='task_generator'` |
|
||||
| `update_trigger(id, status, cron_expression, description)` | 支持部分字段更新，cron 用 `jsonb_set` 改 trigger_config |
|
||||
| `get_prewarm_progress(site_id)` | 对比 72 组合 expected vs `biz.ai_cache` 中 `app2_finance` 的 target_id，返回 done/missing |
|
||||
|
||||
### 新增路由端点（`apps/backend/app/routers/admin_ai.py`）
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/api/admin/ai/triggers` | 列出所有 AI 触发器 |
|
||||
| PATCH | `/api/admin/ai/triggers/{trigger_id}` | 启停 / 改 cron / 改描述 |
|
||||
| GET | `/api/admin/ai/prewarm/progress?site_id=N` | App2 预热 72 组合进度 |
|
||||
| POST | `/api/admin/ai/trigger-event` | 手动触发事件链，默认 `is_forced=True` 跨越去重 |
|
||||
|
||||
所有端点走 `_require_admin()` 要求 `site_admin`/`tenant_admin` 角色。
|
||||
|
||||
---
|
||||
|
||||
## 前端变更
|
||||
|
||||
### API 层（`apps/admin-web/src/api/adminAI.ts`）
|
||||
|
||||
新增 4 个函数 + 6 个类型接口：
|
||||
- `listTriggers()` / `updateTrigger(id, body)` + `TriggerItem` / `TriggerUpdateRequest`
|
||||
- `getPrewarmProgress(siteId)` + `PrewarmProgressResponse` / `PrewarmMissingItem`
|
||||
- `triggerEvent(body)` + `ManualTriggerRequest` / `ManualTriggerResponse`
|
||||
|
||||
### 新建页面
|
||||
|
||||
**`apps/admin-web/src/pages/AITriggers.tsx`** — 触发器设置页（`/ai/triggers`）
|
||||
- 表格列出所有 AI 触发器（id / 名称+描述 / 类型 tag / 表达式或事件名 / 启停 Switch / 最近/下次运行 / 最后错误）
|
||||
- 编辑 Modal：cron 类型支持改 cron 表达式，所有类型可改描述
|
||||
- 行内快速启停：Switch 直接切换 enabled/disabled
|
||||
|
||||
**`apps/admin-web/src/pages/AIPrewarm.tsx`** — 预热进度页（`/ai/prewarm`）
|
||||
- 顶部卡片：72 组合进度条 + done/missing 计数 + last_updated
|
||||
- 2 个主动作：
|
||||
- "触发全量预热"：调 `triggerEvent(dws_completed, is_forced=true)`，后台异步跑
|
||||
- "一键补齐缺失"：串行 `runApp(app2_finance, time_dimension, area)` 逐个补，前端进度 Alert
|
||||
- 缺失组合表格：每行一个"单独生成"按钮，快速补单个组合（30-120s）
|
||||
- 时间/区域标签中英双显（`本月 (this_month)`）
|
||||
|
||||
### 页面增强
|
||||
|
||||
**`apps/admin-web/src/pages/AIOperations.tsx`** — 新增 Card 2.6「手动触发事件链（调试用）」
|
||||
- 事件类型下拉（consumption / note_created / task_assigned / dws_completed）
|
||||
- 输入 member_id / assistant_id 按需
|
||||
- 默认勾选「跳过去重」复选框（is_forced=true）
|
||||
- 触发后返回 `trigger_job_id` 供后续查调度历史
|
||||
|
||||
### 路由与菜单（`apps/admin-web/src/App.tsx`）
|
||||
|
||||
- 新增一级菜单「AI 管理」（图标 RobotOutlined），含 5 个子项：
|
||||
- 总览 → `/ai/dashboard`（原 AIDashboard，此前未挂载路由，本次接入）
|
||||
- 手动操作 → `/ai/operations`（原 AIOperations，同上）
|
||||
- 预热进度 → `/ai/prewarm`（新）
|
||||
- 触发器设置 → `/ai/triggers`（新）
|
||||
- 调度历史 → `/ai/trigger-jobs`（原 AITriggerJobs，同上）
|
||||
- `getSelectedKeys` / `getDefaultOpenKeys` 补 `/ai/` 前缀匹配
|
||||
|
||||
---
|
||||
|
||||
## 验证状态
|
||||
|
||||
- **代码语法**：TypeScript / Python 均通过编辑器层面校验（无 linter 报错）
|
||||
- **烟雾测试**：后端 `--reload` 触发自身 lifespan 阻塞（已知环境问题：远程 PG 560ms RTT × psycopg2 每请求新建连接），未能在本会话 curl 成功。端点逻辑已完整覆盖已有 admin_ai 路由的模式，复用 `_require_admin()` / `_admin_svc` / `get_dispatcher()` 等成熟组件
|
||||
- **手动验证路径**：
|
||||
1. 重启后端至稳定
|
||||
2. 登录 admin-web，左侧菜单展开「AI 管理」应看到 5 项
|
||||
3. 「总览 / 手动操作 / 调度历史」是重新挂载路由的现有页面，直接可用
|
||||
4. 「触发器设置」读取 `biz.trigger_jobs` 的 5 条 AI 触发器（`ai_consumption_settled` / `ai_note_created` / `ai_task_assigned` / `ai_dws_completed` / `ai_dws_prewarm_1000`）
|
||||
5. 「预热进度」应显示 46/72（当前进度），可一键补齐剩余 26 个
|
||||
|
||||
---
|
||||
|
||||
## 遗留风险点
|
||||
|
||||
1. **admin JWT 与 auth.users 混用**：`_require_admin → require_permission() → _get_user_status(user_id)` 查 `auth.users`，但 admin 用户实际在 `admin_users` 表。生产 admin-web 登录后 JWT 的 sub 必须指向 `auth.users.id` 才能通过。本次不修此老问题，沿用现有 admin_ai 所有端点的约定
|
||||
2. **后端远程 PG 网络延迟**（本会话观测 ping 560ms）导致每请求 psycopg2.connect ≈ 3s，叠加 AI 预热任务会拖垮整体响应。根治需加连接池或切本地 PG，与本次改动无关
|
||||
3. **cron 修改立即生效依赖 scheduler 重新解析**：改完 cron_expression 后，`biz.trigger_jobs.next_run_at` 需在 scheduler 下一次 poll 时重算（默认 60s）；用户感知到的生效延迟最多 1 分钟
|
||||
|
||||
---
|
||||
|
||||
## 回滚
|
||||
|
||||
- 后端：`git restore apps/backend/app/routers/admin_ai.py apps/backend/app/schemas/admin_ai.py apps/backend/app/services/ai/admin_service.py`
|
||||
- 前端：`git restore apps/admin-web/src/api/adminAI.ts apps/admin-web/src/App.tsx apps/admin-web/src/pages/AIOperations.tsx && rm apps/admin-web/src/pages/AITriggers.tsx apps/admin-web/src/pages/AIPrewarm.tsx`
|
||||
Reference in New Issue
Block a user