msw-find-diff

msw-find-diff

Overview

接受 Swagger / OpenAPI / Postman，结合前端项目中的 MSW、API 模块、request 封装与测试，找出接口与字段差异，输出 msw-plan.md。执行前读取项目约定，并按 Vue / React 目录速查 加速定位（见 project-layouts.md）。

包入口：msw-api。改代码用 msw-update-code，验收用 msw-verify-plan。

When to Use

• 用户提供 Swagger / OpenAPI / Postman
• 需要生成或更新 msw-plan.md
• 契约升级、mock 与文档对齐

When NOT to use：已有完整 msw-plan.md 且只需改代码 → msw-update-code

项目约定（必读顺序）

1. msw-plan.config.json（项目根，可选）

若存在则 优先于 默认启发式；可复制 msw-plan.config.example.json 到业务仓库根目录。

字段	作用
framework	vue | react — 选用 project-layouts.md 对应表
projectRoot	monorepo 子包路径，如 apps/web
handlersAggregate	总文件：命中后只在此文件内查字段
globs	按角色覆盖 mocks / api / request / unitTests / e2e
searchOrder	搜索顺序，默认：handlers → mocks → api → request → types → unitTests → e2e
pathPrefix / baseURLFromEnv	文档 path 与项目 URL 对齐
docAuthorityDefault	默认权威：document（见下方）
scope.includeDocPaths	只对比部分 path（增量）
verifyCommands	供 msw-verify-plan 使用

2. 无 config 时：框架对号入座

1. package.json：vue → Vue 表；react → React 表
2. 按 searchOrder 角色搜，不要一上来 grep 全仓库
3. 见 路径 → 角色

在 plan「搜索记录」写：config: yes|no、framework、handlersAggregate。

权威来源（写入 plan 必填）

值	含义
document	以接口文档为准改 mock/类型（默认）
project	项目故意偏离文档，不建议自动改为文档值
user-confirmed	用户确认以哪侧为准

表格增加列 权威。project 项勿让 msw-update-code 强改文档方向。

寻找方式（必须遵守）

1. 文档索引：method + path + schema 字段
2. 总文件优先：handlersAggregate → 仅在该文件完成字段对比
3. 按 searchOrder 扩散
4. 禁止总文件已命中仍全仓库乱搜

执行步骤

解析文档 → 映射到项目 → 对比字段 → 写入 msw-plan.md（格式见 msw-plan.template.md）。

输出要求

• 不改代码，只产出 plan
• 汇报：匹配数、未匹配、plan 路径

衔接

用户确认 plan → msw-update-code → 可选 msw-verify-plan

Common Mistakes

mistake	修复
忽略 config / layouts	先读 msw-plan.config.json
只写「字段不对」	必须 从 / 变为