# 审计记录：admin-web AI 手动执行 app_type 对齐

**日期**：2026-04-30
**会话**：处理文档台账 `A1-01`，修复 admin-web 手动执行 APP6 与后端 app_type 不一致问题
**影响范围**：`apps/admin-web/src/api/adminAI.ts`、`apps/admin-web/src/pages/AIOperations.tsx`、`apps/admin-web/src/pages/AIRunLogs.tsx`、`apps/admin-web/src/__tests__/adminAiAppTypes.test.ts`

---

## 变更背景

`docs/ai/ai_apps_feature_acceptance_spec.md` 与接管台账记录了一个局部功能问题：

- 前端手动执行 APP6 使用 `app6_note_analysis`
- 后端 `/api/admin/ai/run/{app_type}` 只支持 `app6_note`
- 结果是 admin-web 手动执行 APP6 会被后端 `_SUPPORTED_APP_TYPES` 拒绝并返回 400

调研时进一步发现同一组前端选项被同时用于“缓存失效”和“按需执行/批量执行”，两者语义不同：

- 缓存失效应使用 `ai_cache.cache_type`，例如 `app6_note_analysis`
- 按需执行应使用 dispatcher 支持的 `app_type`，例如 `app6_note`

因此本次修复不直接把所有值替换成 `app6_note`，而是拆分两套选项，避免破坏缓存管理。

---

## 变更摘要

### `apps/admin-web/src/api/adminAI.ts`

- 新增 `RUN_APP_TYPES` 常量，作为 `/api/admin/ai/run/{app_type}` 的前端权威列表。
- 将 `AppType` 改为从 `RUN_APP_TYPES` 推导。
- 将 APP6/APP7/APP8 手动执行类型对齐为：
  - `app6_note`
  - `app7_customer`
  - `app8_consolidation`

### `apps/admin-web/src/pages/AIOperations.tsx`

- 将原 `APP_TYPE_OPTIONS` 拆为两组：
  - `CACHE_TYPE_OPTIONS`：缓存失效继续使用 cache_type，例如 `app6_note_analysis`
  - `RUN_APP_TYPE_OPTIONS`：按需执行和批量执行使用后端 app_type，例如 `app6_note`
- 将批量执行 state 类型收紧为 `AppType[]`。

### `apps/admin-web/src/pages/AIRunLogs.tsx`

- 新增 `RUN_LOG_APP_TYPE_OPTIONS`。
- 调用记录筛选改为包含真实写入 `ai_run_logs.app_type` 的值：
  - `app6_note`
  - `app7_customer`
  - `app8_consolidate`
  - `app8_consolidation`

### `apps/admin-web/src/__tests__/adminAiAppTypes.test.ts`

- 新增回归测试，覆盖：
  - 手动执行选项使用后端支持的 app_type
  - 缓存失效继续使用 cache_type
  - run log 筛选包含真实日志 app_type

---

## 验证

已执行：

```powershell
cd apps/admin-web
pnpm test -- src/__tests__/adminAiAppTypes.test.ts
pnpm lint
```

结果：

- 目标回归测试：3/3 通过。
- TypeScript 检查：通过。

另外执行了全量 `pnpm test`，结果失败，但失败项与本次修改无关，集中在既有测试债：

- 菜单测试仍按 7 个一级菜单断言，但当前已有 `AI 管理` 后为 8 个。
- 侧边栏高亮测试仍期待 `/triggers?tab=ai` 选中 `/triggers`，但当前选中 `ai-group`。
- e2e helper 使用 `btoa` 处理中文 payload，触发 `InvalidCharacterError`。
- `tabStatePreservation.property.test.tsx` 中 `TaskManager` mock 缺 `QueueTab` export。

---

## 风险与影响

| 风险 | 结论 |
|------|------|
| 缓存失效是否被破坏 | 未破坏。缓存失效继续走 `CACHE_TYPE_OPTIONS`，保留 `app6_note_analysis` 等 cache_type |
| 手动执行是否仍可能 400 | APP6/APP7/APP8 已改为后端支持的 app_type；仍需真实后端联调验证接口返回 |
| run log 旧数据筛选 | 新筛选值覆盖当前 dispatcher 写入值；历史中如果已存在旧 cache_type 风格日志，需要临时手工查库 |
| 批量执行 | 前端提交的 app_type 已收紧到后端运行类型；后端批量执行当前仍主要是预估/异步占位，未改变服务端行为 |

---

## 回滚

如需回滚本次修复：

```powershell
git restore apps/admin-web/src/api/adminAI.ts `
  apps/admin-web/src/pages/AIOperations.tsx `
  apps/admin-web/src/pages/AIRunLogs.tsx

Remove-Item -LiteralPath apps/admin-web/src/__tests__/adminAiAppTypes.test.ts
```

回滚后 admin-web 手动执行 APP6 会恢复为发送 `app6_note_analysis`，该路径仍会被后端拒绝。
