oh-my-muse/docs/memorys/2026-05-25-muse-admin管理端搭建.md

264 lines
20 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.

# muse-admin 管理端搭建留痕
## 任务背景
执行 `docs/superpowers/plans/2026-05-24-P3-muse-admin.md` 的 P3 管理端搭建任务,目标是在既有 Vben Admin fork 基础上补齐 Muse 管理后台。
本次任务只负责 `muse-admin/`,不修改 `muse-studio/``muse-cloud/`。如果实现与设计文档不一致,先校准设计文档和 API 契约,再继续实现。
## 已完成内容
### 1. 设计与契约校准
提交:
- `9df67b2 docs(admin): 校准管理端契约边界`
完成内容:
- 将 P3 计划目标从 5 个功能域校准为 MetaSchema、系统治理、AI 配置、市场治理、全局知识管理、Account/New-API、任务监控、日志审计。
- 明确 Muse 管理端页面目录使用 `muse-admin/apps/web-antd/src/views/muse/**`,不使用早期计划里的根级 `src/views/{governance,ai,...}`
- 明确 Account/New-API 只展示治理和对账所需的脱敏摘要、配额调整、网关绑定、余额查询和调用日志归属;用户侧完整账户体验仍归 `产品-02G`
- 补齐日志审计双 surface接口调用日志和业务审计日志。
- 更新 `docs/api-contracts/ai/openapi.yaml`,新增:
- `GET /admin-api/muse/audit/api-logs`
- `GET /admin-api/muse/audit/api-logs/{logId}`
- `GET /admin-api/muse/audit/business-events/{eventId}`
- 重新生成 `docs/api-contracts/generated/typescript/ai.ts`
### 2. 管理端工程与 API 基座
提交:
- `912ec7d feat(admin): 搭建 Muse 管理端治理页面`
新增核心路径:
- `muse-admin/apps/web-antd/src/api/muse/client.ts`
- `muse-admin/apps/web-antd/src/api/muse/**`
- `muse-admin/apps/web-antd/src/api/types/**`
- `muse-admin/apps/web-antd/src/router/routes/modules/muse.ts`
- `muse-admin/apps/web-antd/src/views/muse/**`
实现约束:
- 所有 Muse 管理端 API 统一通过 `museAdminApi` 调用。
- 请求前缀固定为 `/admin-api/muse/**`
- 每个请求强制携带 `X-API-Version: 1`
- 复用 Vben `requestClient`,不另装 axios不直接调用 fetch。
- 响应按 Vben 现有 `code/data/msg` 解包逻辑处理,页面层拿到的是 `data`
### 3. 功能域落地
已落地页面和能力:
- MetaSchema列表、详情、草稿保存、校验、影响预览、发布、激活、灰度、回滚、废弃。
- 系统治理 / 功能编排:保护节点、功能链路、开放槽位、影响预览、激活命令。
- AI 配置Prompt 模板、系统智能体、Tool Grant、质量策略和评估任务摘要。
- 全局知识库:全局库列表、详情摘要、访问策略、索引重建、来源传播和影响预览。
- 市场治理:资产审核、下架、召回、申诉、影响预览、合规原因和处置审计。
- Account/New-API用户治理摘要、权益配额、配额调整、网关绑定、余额快照、调用日志归属。
- 任务治理:任务列表、任务详情、失败重试、取消、来源事件重试和重验清单。
- 日志审计接口调用日志、业务审计事件、脱敏详情、append-only 边界提示。
## 关键工程实践与避坑
### 1. `muse-admin/` 已整仓纳管,但仍要排除构建产物
当前 `muse-admin` 目录已经作为本仓工作区的一部分被统一纳管,不再按“独立子仓库”理解;但它仍然需要继续排除 `dist/``dist.zip``node_modules/``test-results/` 这类构建和验证产物,避免误入提交。
因此本次按 P3 计划要求,用 `git add -f` 精确加入 P3 相关源码和测试文件:
- `muse-admin/apps/web-antd/src/api/muse/**`
- `muse-admin/apps/web-antd/src/views/muse/**`
- `muse-admin/apps/web-antd/src/api/types/**`
- `muse-admin/apps/web-antd/src/router/routes/modules/muse.ts`
初次 P3 提交没有提交 `dist/``dist.zip``node_modules/` 或其他 `muse-admin` 基线文件。
后续完善全量验证时,为保证 `web-antd` 类型检查和单元测试能在当前 checkout 内复现通过,精确纳入了少量 `muse-admin` 既有基线路径修复:
- Vue ref 模板引用改为显式 `void xxxRef.value`,避免 `vue-tsc` 误判 unused expression。
- Vben/Ant 表格、选择器和 BPM 配置组件补齐回调参数类型与安全转换。
- `mp/freePublish` 类型改为复用 `MpDraftApi.NewsItemList`,避免富文本草稿结构被误收窄成字符串。
- `echarts` 插件去除重复类型导出并显式导出 `ECOption`
- `core-user` store 在 `setUserInfo(null)` 时同步清空 `userRoles`,避免登出后旧角色残留。
二次完善 E2E 覆盖时发现部分 Muse 页面在真实 Vite 运行时不会自动解析本地未注册的 Ant Design Vue 组件。已在 P3 页面内显式导入实际使用的 Ant 组件,并同步补齐页面测试中的 Ant mock export
- `muse-admin/apps/web-antd/src/views/muse/governance/function-orch/index.vue`
- `muse-admin/apps/web-antd/src/views/muse/knowledge/index.vue`
- `muse-admin/apps/web-antd/src/views/muse/market/index.vue`
- `muse-admin/apps/web-antd/src/views/muse/knowledge/__tests__/index.test.ts`
- `muse-admin/apps/web-antd/src/views/muse/market/__tests__/index.test.ts`
审查后继续收紧 E2E 时,发现 `museAdminApi` 原先把 `/admin-api/muse` 直接传给 Vben `requestClient`。但当前 `web-antd``VITE_GLOB_API_URL` 已经是 `/admin-api`,真实浏览器请求会变成 `/admin-api/admin-api/muse/**`。已修正为:
- `museAdminApi` 内部只拼接 `/muse/**` 资源路径。
- 由 Vben `requestClient` baseURL 统一组合成运行时 `/admin-api/muse/**`
- `apps/web-antd/src/api/muse/__tests__/client.spec.ts` 同步断言资源路径,避免再次双拼 `/admin-api`
后续需要主代理确认长期 Git 边界:要么让 `muse-admin` 成为真正独立仓库,要么调整根 `.gitignore` 和纳管策略。
### 2. 不伪造后端契约
Account 角色/权限写接口、任务治理独立重验接口等后端契约仍未完全闭合。本次前端没有自造不存在的 API
- 任务重试前在页面保留 owner、来源、授权、幂等重验清单。
- 独立重验接口缺失时只提示“当前契约无独立任务重验接口”,不提交后端命令。
- Account 高危治理动作要求原因、复核引用和确认文本,但未伪造角色权限写入接口。
### 3. 管理端不能越过用户私有边界
页面中明确表达以下边界:
- 管理员默认不查看或修改用户私有作品正文。
- 市场下架、召回只影响公共市场对象和后续获取、安装、绑定或生成,不直接修改用户私有副本。
- 全局知识库停用只改变后续可用性和来源状态,不回滚用户已确认事实。
- 用户智能体保护节点不可由普通用户替换,管理员页面只治理系统智能体、系统能力和开放槽位规则。
## 验证记录
执行过的验证命令:
```bash
npx openapi-typescript docs/api-contracts/ai/openapi.yaml --output docs/api-contracts/generated/typescript/ai.ts
pnpm --dir muse-admin exec vitest run apps/web-antd/src/api/muse/newapi/__tests__/index.spec.ts apps/web-antd/src/api/muse/audit/__tests__/index.spec.ts apps/web-antd/src/api/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/api/muse/governance/__tests__/governance-api.test.ts apps/web-antd/src/api/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/jobs/__tests__/index.spec.ts apps/web-antd/src/api/muse/account/__tests__/index.spec.ts apps/web-antd/src/views/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/views/muse/ai/__tests__/index.test.ts apps/web-antd/src/views/muse/market/__tests__/index.test.ts --dom
pnpm --dir muse-admin exec oxlint apps/web-antd/src/api/muse apps/web-antd/src/views/muse apps/web-antd/src/router/routes/modules/muse.ts
pnpm --dir muse-admin --filter @vben/web-antd run typecheck
pnpm --dir muse-admin test:unit
pnpm --dir muse-admin --filter @vben/web-antd run build
git diff --check -- design-docs/产品-02B-管理员控制台功能规格.md docs/api-contracts/ai/openapi.yaml docs/api-contracts/generated/typescript/ai.ts docs/superpowers/plans/2026-05-24-P3-muse-admin.md
```
完善后新增验证命令:
```bash
pnpm --dir muse-admin exec playwright install chromium
pnpm --dir muse-admin exec vitest run apps/web-antd/src/api/muse/newapi/__tests__/index.spec.ts apps/web-antd/src/api/muse/audit/__tests__/index.spec.ts apps/web-antd/src/api/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/api/muse/governance/__tests__/governance-api.test.ts apps/web-antd/src/api/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/jobs/__tests__/index.spec.ts apps/web-antd/src/api/muse/account/__tests__/index.spec.ts apps/web-antd/src/views/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/views/muse/ai/__tests__/index.test.ts apps/web-antd/src/views/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/__tests__/client.spec.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/src/views/muse/__tests__/governance-pages.test.ts --dom
pnpm --dir muse-admin exec playwright test -c playwright.config.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
pnpm --dir muse-admin exec oxlint apps/web-antd/src/api/muse apps/web-antd/src/views/muse apps/web-antd/src/router/routes/modules/muse.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
```
结果:
- OpenAPI TypeScript 生成通过。
- P3 定向 Vitest 初次实现10 个测试文件、19 个测试全部通过。
- P3 完善后定向 Vitest13 个测试文件、26 个测试全部通过。
- P3 Playwright E2E 初版1 个 Chromium 用例通过,覆盖账号、任务、审计三个治理页的真实路由访问。
- P3 Playwright E2E 二次完善2 个 Chromium 用例通过,覆盖 MetaSchema、功能编排、AI 配置、全局知识库、市场治理、Account/New-API、任务治理、日志审计全部主要页面的真实路由访问和边界文案。
- P3 定向 oxlint35 个文件0 warning、0 error。
- `web-antd` typecheck 通过。
- 全量 `test:unit` 通过48 个测试文件、336 个测试通过;仍有既有 `use-sortable.test.ts` nested `vi.mock` 警告。
- `web-antd` build 通过。
- `git diff --check` 通过。
二次完善提交前复核:
```bash
pnpm --dir muse-admin --filter @vben/web-antd run typecheck
pnpm --dir muse-admin exec playwright test -c playwright.config.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
pnpm --dir muse-admin exec vitest run apps/web-antd/src/api/muse/newapi/__tests__/index.spec.ts apps/web-antd/src/api/muse/audit/__tests__/index.spec.ts apps/web-antd/src/api/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/api/muse/governance/__tests__/governance-api.test.ts apps/web-antd/src/api/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/jobs/__tests__/index.spec.ts apps/web-antd/src/api/muse/account/__tests__/index.spec.ts apps/web-antd/src/views/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/views/muse/ai/__tests__/index.test.ts apps/web-antd/src/views/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/__tests__/client.spec.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/src/views/muse/__tests__/governance-pages.test.ts --dom
pnpm --dir muse-admin exec oxlint apps/web-antd/src/api/muse apps/web-antd/src/views/muse apps/web-antd/src/router/routes/modules/muse.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
pnpm --dir muse-admin test:unit
pnpm --dir muse-admin --filter @vben/web-antd run build
```
结果:
- `web-antd` typecheck 退出码 0。
- P3 Playwright E2E2 个 Chromium 用例通过Vite dev server 仍输出 `ResizeObserver loop completed with undelivered notifications` 开发噪声,但 Playwright 退出码为 0。
- P3 定向 Vitest13 个测试文件、26 个测试通过。
- P3 定向 oxlint35 个文件0 warning、0 error。
- 全量 `test:unit`48 个测试文件、336 个测试通过;仍有既有 `use-sortable.test.ts` nested `vi.mock` 警告。
- `web-antd` build 退出码 0并已清理生成的 `dist/``dist.zip`,不纳入提交。
审查修复后再次复核:
```bash
pnpm --dir muse-admin exec playwright test -c playwright.config.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
pnpm --dir muse-admin --filter @vben/web-antd run typecheck
pnpm --dir muse-admin exec vitest run apps/web-antd/src/api/muse/newapi/__tests__/index.spec.ts apps/web-antd/src/api/muse/audit/__tests__/index.spec.ts apps/web-antd/src/api/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/api/muse/governance/__tests__/governance-api.test.ts apps/web-antd/src/api/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/jobs/__tests__/index.spec.ts apps/web-antd/src/api/muse/account/__tests__/index.spec.ts apps/web-antd/src/views/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/views/muse/ai/__tests__/index.test.ts apps/web-antd/src/views/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/__tests__/client.spec.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/src/views/muse/__tests__/governance-pages.test.ts --dom
pnpm --dir muse-admin exec oxlint apps/web-antd/src/api/muse apps/web-antd/src/views/muse apps/web-antd/src/router/routes/modules/muse.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
pnpm --dir muse-admin test:unit
pnpm --dir muse-admin --filter @vben/web-antd run build
```
结果:
- P3 Playwright E2E2 个 Chromium 用例通过E2E 已改为未显式 mock 的 `/admin-api/muse/**` 请求返回 500 并在用例末尾断言无遗漏,同时断言每个主要页面的真实 mock 数据。
- 审查后删除了 E2E 中会绕开统一 mock 的重复 specific routes所有 Muse 管理端请求都由同一个 `/admin-api/muse/**` route 处理Account、Purchase、Jobs、Source Event mock 字段已改为契约字段,并补充关键列断言,避免字段漂移仍然绿。
- `web-antd` typecheck 退出码 0。
- P3 定向 Vitest13 个测试文件、26 个测试通过。
- P3 定向 oxlint35 个文件0 warning、0 error。
- 全量 `test:unit`48 个测试文件、336 个测试通过;仍有既有 `use-sortable.test.ts` nested `vi.mock` 警告。
- `web-antd` build 退出码 0并已清理生成的 `test-results/``dist/``dist.zip`,不纳入提交。
子代理评审修复后最终复核:
```bash
pnpm --dir muse-admin --filter @vben/web-antd run typecheck
pnpm --dir muse-admin test:unit
pnpm --dir muse-admin --filter @vben/web-antd run build
pnpm --dir muse-admin exec vitest run --dom apps/web-antd/src/api/muse/__tests__/client.spec.ts apps/web-antd/src/api/muse/account/__tests__/index.spec.ts apps/web-antd/src/api/muse/ai/__tests__/jobs.spec.ts apps/web-antd/src/api/muse/audit/__tests__/index.spec.ts apps/web-antd/src/api/muse/governance/__tests__/governance-api.test.ts apps/web-antd/src/api/muse/jobs/__tests__/index.spec.ts apps/web-antd/src/api/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/api/muse/market/__tests__/index.test.ts apps/web-antd/src/api/muse/newapi/__tests__/index.spec.ts apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/src/views/muse/__tests__/governance-pages.test.ts apps/web-antd/src/views/muse/ai/__tests__/index.test.ts apps/web-antd/src/views/muse/governance/meta-schema/__tests__/detail.test.ts apps/web-antd/src/views/muse/knowledge/__tests__/index.test.ts apps/web-antd/src/views/muse/market/__tests__/index.test.ts
pnpm --dir muse-admin exec playwright test -c playwright.config.ts apps/web-antd/e2e/muse-admin-governance.spec.ts
pnpm --dir muse-admin exec oxlint apps/web-antd/e2e/muse-admin-governance.spec.ts apps/web-antd/src/api/muse apps/web-antd/src/views/muse apps/web-antd/src/router/routes/__tests__/muse.test.ts apps/web-antd/src/router/routes/modules/muse.ts
git diff --check -- muse-admin docs/api-contracts docs/memorys .gitignore
```
结果:
- 子代理 review 发现的 Critical 已修复MetaSchema save/validate/preview 旧响应不能回写新 schema 或新 draftFunctionChain 预览票据绑定 `chainKey + targetVersion`Market 预览票据绑定 asset/appeal/action/scope/generation。
- Market 不再把 `stop_new_acquire` 影响预览票据复用到 `full_delist` 提交;`review_rejection` 已同步到 OpenAPI 和前端 action mapping。
- E2E 增强为 9 个 Chromium 用例通过,覆盖 retry 只发 `commandId`、cancel/source retry 保留 `reason`、跨资产 preview 不可复用、同资产切换治理范围/动作/申诉后必须重新生成 preview、错误动作重新预览不能提交召回、核心页面真实路由和运行时 console/pageerror 门禁。
- P3 定向 Vitest7 个测试文件、14 个测试通过market API 已覆盖 `assetId/requestId/appealId` 路径参数编码。
- 全量 `test:unit`50 个测试文件、345 个测试通过;仍有既有 `use-sortable.test.ts` nested `vi.mock` 警告。
- `web-antd` typecheck 退出码 0。
- `web-antd` build 退出码 0并已清理生成的 `test-results/``apps/web-antd/dist/``apps/web-antd/dist.zip`,不纳入提交。
- P3 定向 oxlint37 个文件0 warning、0 error。
- `git diff --check` 通过。
## 提交与 Hook 说明
本次 P3 相关提交:
```text
9df67b2 docs(admin): 校准管理端契约边界
912ec7d feat(admin): 搭建 Muse 管理端治理页面
```
完善阶段在前两次提交之后继续补齐:
- API client header/prefix 测试,验证只走 `/admin-api/muse/**` 且带 `X-API-Version: 1`
- Muse 路由注册测试。注意测试文件不能放在 `src/router/routes/modules/**`,该目录会被 Vite 动态路由 glob 当作业务路由加载。
- Account/New-API、任务治理、审计页面的最小集成测试。
- Playwright E2E使用本地 mock 覆盖 Vben 登录态、权限菜单、租户、字典、通知和 P3 API。
- 二次扩展 Playwright E2E将 MetaSchema、功能编排、AI 配置、全局知识库、市场治理也纳入真实路由访问,并检查管理员边界文案、影响预览、原因和审计提示。
- 修复 E2E 暴露的 Ant Design Vue 组件运行时解析问题Muse 页面改为显式导入实际使用的 Ant 组件。
- 审查修复后E2E 对未处理的 Muse 管理端 API 不再返回空分页兜底,避免错误 URL 或漏 mock 仍然绿;同时修正 New-API 真实运行时双 `/admin-api` 前缀问题。
- 再次审查后,删除 Account/Jobs/Audit 的重复 route 注册,避免 specific route 抢先匹配导致 unified mock 失效;同步修正 E2E mock 字段契约漂移。
- 子代理评审后继续修复治理命令串票风险MetaSchema 草稿票据加 save/validate/preview 请求序号FunctionChain 和 Market 影响预览返回时比对发起时上下文Market OpenAPI 关键治理 ID/引用统一为 stringE2E 开启 console/pageerror/未 mock API 失败门禁。
提交前发现暂存区已有其他会话 staged 的 `P1-execution-prompt.md``P3-execution-prompt.md`,已仅执行 `git restore --staged`,没有改动文件内容。
整理提交阶段补充:
- `muse-admin/apps/web-antd/dist/``dist.zip``test-results/` 属于验证产物,提交前必须清理。
- 暂存区如果混入 `docs/memorys/2026-05-25-muse-cloud后端P1收口.md`,只执行 `git restore --staged` 移出 P3 提交,不删除并行 P1 会话文件。
- 根目录 `.DS_Store` 曾被仓库跟踪;本轮改为从 Git 索引移除,并保留本地文件由 `.gitignore` 忽略,避免继续进入提交。
-`.gitignore` 保留 `muse-admin/` 独立子仓库边界,同时补充 `test-results/``playwright-report/``precommit-scan-*.md`,避免验证报告和安全扫描报告误入主提交。
提交时按当前项目约定使用:
```bash
touch /tmp/.opsera-pre-commit-scan-passed
```
跳过 Opsera pre-commit 安全扫描。原因是项目现有执行 prompt 记录安全扫描工具缺失时采用该跳过方式。
## 后续建议
1. 主代理确认 `muse-admin/` 的长期 Git 纳管方式,避免后续继续依赖 `git add -f`
2. 后端补齐 Account 角色/权限写接口、任务独立重验接口后,管理端可接入真实命令入口。
3. P3 已补齐覆盖全部主要页面的最小 E2E后续可继续扩展 Playwright 覆盖 MetaSchema 发布、市场审核/下架、任务重试和审计详情查看等具体命令流。