# 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: 后端契约测试通过**

```bash
cd muse-cloud && mvn test -pl muse-module-content,muse-module-account
```

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

- [ ] **Step 2: 移除前端 Content MSW handlers**

```typescript
// muse-studio/src/test/mocks/browser.ts
// 注释掉 contentHandlers，保留其他模块的 Mock
export const worker = setupWorker(
  // ...contentHandlers,  // ← 切换真实 API
  ...aiHandlers,
  ...knowledgeHandlers,
  ...marketHandlers,
  ...accountHandlers
);
```

- [ ] **Step 3: 前端联调验证**

```bash
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:
```typescript
// 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: 提交契约更新**

```bash
git add docs/api-contracts/
git commit -m "fix(api): content+account 联调后契约修正"
```

- [ ] **Step 8: 更新 OpenAPI 契约（如有不一致）**

```bash
# 编辑对应的 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 契约（如有不一致）**

```bash
# 编辑对应的 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 契约（如有不一致）**

```bash
# 编辑对应的 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 契约（如有不一致）**

```bash
# 编辑对应的 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)
  ```yaml
  # .github/workflows/muse-cloud.yml
  steps:
    - compile (Maven)
    - unit-test (JUnit + Mockito)
    - integration-test (Testcontainers)
    - lint (Checkstyle + SpotBugs)
    - build-image (Docker)
  ```

- [ ] **前端 CI 流水线**
  ```yaml
  # .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 新发现