295 lines
8.9 KiB
Markdown
295 lines
8.9 KiB
Markdown
# 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 新发现 |