root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
7b1cfadc2ea5867c40e419dd329cf3ffadc964bd
Neo-ZQYY/docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md
Neo caf179a5da 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 逐一处理
2026-05-04 02:30:19 +08:00

121 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 审计记录：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 View Git Blame Copy Permalink