zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/superpowers/plans/2026-05-24-P4-集成切换.md

8.9 KiB
Raw Blame History

P4: 集成切换 + 质量加固 — 执行计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.

目标: 按模块将前端从 Mock API 切换到真实后端 API，完成端到端联调，修复契约缺陷，实现全量质量加固（测试/CI/安全）。

架构: 按依赖顺序逐个模块切换：content+account → meta → ai+knowledge → market。每模块切换后更新 OpenAPI 契约。最后进行全量质量加固。

涉及仓库: muse-cloud, muse-studio, muse-admin, muse-design-docs

Phase 1: 集成切换

时间线总览

阶段 内容 周次
Switch S1 content + account 集成切换 Week 11-12
Switch S2 meta 集成切换 Week 13
Switch S3 ai + knowledge 集成切换 Week 14-15
Switch S4 market 集成切换 Week 16-17
Quality G1-G4 质量加固 Week 18-19

各模块 API 数量（OpenAPI SSOT）

模块 App 接口 Admin 接口 总计
Content ~35 ~15 ~50
AI ~25 ~15 ~40
Knowledge ~34 ~23 ~57
Market ~21 ~11 ~32
Account ~20 ~13 ~33
Meta 0 ~16 ~16
总计 ~135 ~93 ~228

Switch S1: content + account 集成切换

前置条件检查:

  • P1 content+account API 全部集成测试通过 → 可开始 S1

依赖: muse-cloud content + account API 自测通过

  • Step 1: 后端契约测试通过
cd muse-cloud && mvn test -pl muse-module-content,muse-module-account

验证: Content (50 接口) + Account (33 接口) 全部集成测试通过。

  • Step 2: 移除前端 Content MSW handlers
// muse-studio/src/test/mocks/browser.ts
// 注释掉 contentHandlers，保留其他模块的 Mock
export const worker = setupWorker(
  // ...contentHandlers,  // ← 切换真实 API
  ...aiHandlers,
  ...knowledgeHandlers,
  ...marketHandlers,
  ...accountHandlers
);
  • Step 3: 前端联调验证
cd muse-studio && pnpm dev

测试流程:

  1. 作品列表加载正常
  2. 创建新作品 → 自动跳转
  3. 章节列表 + 创建章节
  4. Block 编辑器加载 → 自动保存 → 验证 IndexedDB 安全网
  • Step 4: 修正接口不一致

联调中发现的契约缺陷:

  1. 记录具体差异（字段名/类型/状态码不一致）
  2. 决定修后端还是修 OpenAPI
  3. 更新 OpenAPI 契约文件
  4. 重新生成 TS 类型包
  5. 前端更新类型引用
  • Step 5: 冒烟测试（写作流程）

Playwright E2E:

// muse-studio/e2e/writing-flow.spec.ts
import { test, expect } from '@playwright/test';

test('完整写作流程', async ({ page }) => {
  await page.goto('http://localhost:5173');
  
  // 1. 查看作品列表
  await expect(page.locator('h1')).toContainText('我的作品');
  
  // 2. 创建新作品
  await page.click('button:has-text("新建作品")');
  await page.fill('input[name="title"]', 'E2E 测试作品');
  await page.click('button:has-text("创建")');
  
  // 3. 进入编辑器
  await expect(page.locator('.ProseMirror')).toBeVisible();
  
  // 4. 输入文本
  await page.locator('.ProseMirror').fill('第一段测试文字');
  
  // 5. 等待自动保存
  await page.waitForTimeout(3000);
  await expect(page.locator('[data-testid="save-indicator"]')).toContainText('已保存');
});
  • Step 6: Account API 切换（同时）

类似流程：移除 account MSW handlers → 联调验证个人中心/用量/配额 → 修正不一致 → 更新契约

  • Step 7: 提交契约更新
git add docs/api-contracts/
git commit -m "fix(api): content+account 联调后契约修正"
  • Step 8: 更新 OpenAPI 契约（如有不一致）
# 编辑对应的 openapi.yaml 修正
git add docs/api-contracts/
git commit -m "fix(api): content+account 联调后契约修正"
# 重新生成 TypeScript 类型
npx openapi-typescript docs/api-contracts/content/openapi.yaml --output docs/api-contracts/generated/typescript/content.ts
npx openapi-typescript docs/api-contracts/account/openapi.yaml --output docs/api-contracts/generated/typescript/account.ts

Switch S2: meta API 集成切换

前置条件检查:

  • P1 meta API 全部集成测试通过 → 可开始 S2

依赖: muse-cloud meta API 自测通过

  1. MetaSchema 管理页面切换到真实 API
  2. 验证 CRUD + 草稿/发布/版本管理流程
  3. 修正不一致，更新 OpenAPI
  • 更新 OpenAPI 契约（如有不一致）
# 编辑对应的 openapi.yaml 修正
git add docs/api-contracts/
git commit -m "fix(api): meta 联调后契约修正"
# 重新生成 TypeScript 类型
npx openapi-typescript docs/api-contracts/meta/openapi.yaml --output docs/api-contracts/generated/typescript/meta.ts

Switch S3: ai + knowledge API 集成切换

前置条件检查:

  • P1 ai+knowledge API 全部集成测试通过 → 可开始 S3

依赖: muse-cloud ai + knowledge API 自测通过

  1. AI 生成 SSE 流验证（断线重连、超时）
  2. 候选接受/拒绝流程验证
  3. 知识库文档上传/解析/确认流程
  4. 知识绑定/解绑跨模块测试
  5. SSE 端点专项验证：
    • AI 生成 SSE 流
      • 连接 AI 生成 SSE 端点，接收完整 chunk 序列
      • 模拟断线后使用 lastEventId 重连，验证断点续传
      • 验证超时处理（服务端无响应时客户端行为）
    • 事件流 SSE
      • 连接事件流端点，接收通知事件
      • 使用 lastEventId 验证断线后事件不丢失
      • 验证心跳保活机制
    • 错误状态处理
      • 网络断开时客户端降级提示
      • 服务端 5xx 错误时重试策略
      • 超时后的自动重连
  6. 修正不一致，更新 OpenAPI
  • 更新 OpenAPI 契约（如有不一致）
# 编辑对应的 openapi.yaml 修正
git add docs/api-contracts/
git commit -m "fix(api): ai+knowledge 联调后契约修正"
# 重新生成 TypeScript 类型
npx openapi-typescript docs/api-contracts/ai/openapi.yaml --output docs/api-contracts/generated/typescript/ai.ts
npx openapi-typescript docs/api-contracts/knowledge/openapi.yaml --output docs/api-contracts/generated/typescript/knowledge.ts

Switch S4: market API 集成切换

前置条件检查:

  • P1 market API 全部集成测试通过 + S1/S2/S3 全部完成 → 可开始 S4

依赖: 前面所有模块已切换

  1. 市场浏览/推荐验证
  2. Handoff 跨空间跳转测试
  3. 发布/审核流程验证
  4. 修正不一致，更新 OpenAPI
  • 更新 OpenAPI 契约（如有不一致）
# 编辑对应的 openapi.yaml 修正
git add docs/api-contracts/
git commit -m "fix(api): market 联调后契约修正"
# 重新生成 TypeScript 类型
npx openapi-typescript docs/api-contracts/market/openapi.yaml --output docs/api-contracts/generated/typescript/market.ts

Phase 2: 质量加固

Quality G1: 后端全量测试

  • 单元测试补充

    • Domain 层 edge case 覆盖
    • Service 层 mock 测试（JUnit 5 + Mockito）
    • 目标: Domain ≥90%, Application ≥80%

  • 集成测试补充

    • Testcontainers + PostgreSQL
    • 跨模块事务边界测试（内容保存 → 知识提取 → AI 候选）
    • 并发冲突测试（乐观锁）

  • 契约测试

    • Spring Cloud Contract 或 Pact
    • 验证 API 响应与 OpenAPI 定义一致

Quality G2: 前端全量测试

  • muse-studio 单元测试补充

    • 组件测试 (Testing Library) ≥75%
    • Hook 测试 ≥80%

  • muse-admin 单元测试补充

    • 组件测试 (Vue Test Utils) ≥70%
    • Composable 测试 ≥75%

  • E2E 测试

    • Playwright 覆盖核心流程
    • studio: 写作流程、作品管理、知识确认
    • admin: MetaSchema 管理、资产审核

Quality G3: CI/CD

  • 后端 CI 流水线 (GitHub Actions / Jenkins)

    # .github/workflows/muse-cloud.yml
steps:
  - compile (Maven)
  - unit-test (JUnit + Mockito)
  - integration-test (Testcontainers)
  - lint (Checkstyle + SpotBugs)
  - build-image (Docker)

  • 前端 CI 流水线

    # .github/workflows/muse-studio.yml
steps:
  - typecheck (tsc --noEmit)
  - lint (ESLint + Prettier)
  - test (Vitest)
  - build (Vite)

Quality G4: 安全加固

  • 依赖漏洞扫描 (npm audit, OWASP Dependency Check)
  • XSS 防护 + CSP 头配置
  • 敏感数据脱敏（日志中 token/密码脱敏）
  • SSRF 防护（Knowledge linkUrl allowlist + 私网拦截）
  • AI 安全（Prompt injection 防护、输出合规检查）

完成标准

  • 6 个模块全部切换真实 API
  • 全量端到端冒烟测试通过
  • 后端测试覆盖率达标: Domain ≥90%, Application ≥80%
  • 前端测试覆盖率达标: Studio ≥75%, Admin ≥70%
  • CI 流水线全部通过
  • OpenAPI 契约与实现一致
  • 安全扫描无 Critical/High 新发现