一句话定位：以"页面"为核心视角，自动梳理前端项目所有页面的接口依赖关系，并提供透明代理实现一键场景切换。
工程形态：一个独立的 Node.js 全栈项目，一个端口同时提供代理引擎 + 管理界面。
一、产品形态
1.1 解决什么问题
前端的痛：
- 新人接手不知道页面调了哪些接口
- 测异常场景要改代码或等后端配合
- 后端改接口不知道影响哪些页面
- 联调阶段频繁等后端
测试的痛：
- 边界场景（500、空数据、超时）完全依赖后端
- 不清楚页面的接口全景图
- 环境不稳定导致测试阻塞
- 无法独立验证前端容错逻辑
1.2 核心能力
能力一：页面维度接口地图
自动梳理每个页面使用了哪些接口、URL、方法、来源文件。菜单结构一比一对照业务系统。
能力二：一键场景切换
透明代理请求到后端。需要 Mock 时按规则篡改响应------不改代码、不重启、实时生效。
1.3 跟别人有什么不同
| 维度 | Apifox / Postman | MSW | PageProxy |
|---|---|---|---|
| 接口来源 | 手动录入 | 手动写 handler | AI 扫描代码自动生成 |
| 核心视角 | 接口维度 | 接口维度 | 页面×接口交叉维度 |
| 代码侵入 | 无（需手动维护） | 需写 mock handler | 零侵入，独立服务 |
| 场景切换 | 切规则集 | 改代码重编译 | Web界面一键切换 |
| 部署方式 | SaaS（数据上云） | 嵌入前端项目 | 内网私有部署 |
核心差异：别人是"管接口"的工具，我们是"管页面和接口关系"的中间层。用户不需要知道 URL 是什么，只需要选"订单详情页"→"退款场景"→ 开。
1.4 用户角色
| 角色 | 使用场景 | 核心收益 |
|---|---|---|
| 前端开发 | 查接口依赖、Mock联调、测异常 | 不等后端、不改代码测场景 |
| QA 测试 | 边界测试、回归定位、独立验证 | 不依赖环境、不求人 |
| 后端开发 | 查谁在用我的接口、评估变更影响 | 改接口前知道影响范围 |
二、技术架构
2.1 工程形态
一个独立的 Node.js 全栈项目（新仓库），与业务项目没有代码依赖，只通过网络连接。一个端口同时提供代理引擎 + 管理 API + 前端界面。
项目结构：
pageproxy/
├── server/ ← 后端（Express + TypeScript）
│ ├── app.ts ← 入口：启动服务
│ ├── proxy/ ← 代理引擎
│ │ ├── engine.ts ← 请求拦截 + 规则匹配
│ │ ├── rules.ts ← 规则加载/匹配/应用
│ │ └── forward.ts ← 转发到真实后端
│ ├── api/ ← 管理接口
│ │ ├── projects.ts ← 项目 CRUD
│ │ ├── pages.ts ← 页面×接口索引
│ │ └── rules.ts ← 规则 CRUD
│ └── data/ ← JSON 文件存储
│ ├── projects.json
│ └── my-admin/
│ ├── index.json ← 页面×接口索引
│ └── rules.json ← Mock 规则
│
├── web/ ← 前端（React + Ant Design + Vite）
│ └── src/pages/
│ ├── Home/ ← 首页：项目列表
│ └── Project/ ← 项目内页：菜单+接口管理
│
├── Dockerfile
└── package.json一个端口三个职责：
| 路径 | 职责 | 谁在用 |
|---|---|---|
/proxy/* |
代理引擎：转发/篡改请求 | 前端项目 axios |
/api/* |
管理接口：规则/索引 CRUD | 管理界面 |
/* |
前端静态文件托管（管理界面） | 浏览器访问 |
2.2 代理引擎原理
前端请求 → PageProxy（:3456/proxy/）
│
├─ 查规则表：这个接口有匹配的规则吗？
│
├─ 没有规则 → 原封不动转发给后端网关 → 原封不动返回
│ （等于 PageProxy 不存在）
│
└─ 有规则 → 按动作类型处理：
├─ merge：请求后端 → 拿到真实返回 → 改指定字段 → 返回
├─ replace：不请求后端 → 直接返回预设数据
├─ delay：请求后端 → 延迟 N 秒 → 返回
└─ error：不请求后端 → 返回指定 HTTP 状态码规则示例（存在 JSON 文件中）：
json
[
{
"name": "订单详情-已退款场景",
"pattern": "/api/order/detail",
"action": "merge",
"patch": {"data.status": 65}
},
{
"name": "订单列表-空数据",
"pattern": "/api/order/list",
"action": "replace",
"response": {"code": "0000", "data": [], "msg": "success"}
}
]2.3 代理开关机制
分两步落地：
第一步：本地开发
改 rsbuild proxy target 指向 localhost:3456/proxy。只改配置，业务代码零改动。
第二步：测试环境
axios 拦截器加环境判断 + 页面悬浮球开关。QA 点一下开关，请求就走代理。
测试环境开关代码（仅测试环境生效）：
typescript
// axios 请求拦截器中
if (process.env.NODE_ENV !== 'production' && localStorage.getItem('__pageproxy__') === '1') {
config.baseURL = 'http://pageproxy.内网:3456/proxy'
}页面右下角悬浮球：灰色=关闭，绿色=开启，点击切换 + 自动刷新。生产环境不渲染、不执行。
2.4 接口索引机制
索引更新方式：在 AI IDE 中说"更新接口索引"，AI Skill 自动扫描代码生成最新的页面×接口映射。
| 来源 | 说明 | 触发场景 |
|---|---|---|
| AI Skill 扫描 | AI 读路由+service+view 文件，输出索引 JSON | 需要时手动触发 |
| Swagger 导入 | 后端出了文档，导入补充索引 | 前端代码还没写时 |
| 手动录入 | Web 界面添加/修改 | AI 扫描遗漏时 |
| 代理录制 | 运行时发现未登记接口，提示加入 | 日常使用自动补全 |
2.5 技术选型
| 模块 | 选型 | 理由 |
|---|---|---|
| 后端 | Express + TypeScript | 轻量快出活，后续可迁移 NestJS |
| 代理核心 | http-proxy-middleware | webpack/rsbuild 底层库，成熟稳定 |
| 前端 | React + Ant Design + Vite | 团队技术栈一致 |
| 存储 | JSON 文件 | 数据量小，零外部依赖 |
| 部署 | Docker | 一个镜像一条命令启动 |
三、用户界面
3.1 页面流程
首页（选项目）→ 项目内页（菜单 + 接口管理 + 规则编辑）3.2 首页：项目列表
┌──────────────────────────────────────────────────────────────┐
│ PageProxy [全局开关: ON] │
├──────────────────────────────────────────────────────────────┤
│ │
│ 我的项目 [+ 添加项目] │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │
│ │ 运营后台 │ │ H5 商城 │ │ 管理后台 │ │
│ │ 38 模块 │ │ 12 模块 │ │ 8 模块 │ │
│ │ 267 接口 │ │ 85 接口 │ │ 43 接口 │ │
│ │ 活跃规则: 2 │ │ 活跃规则: 0 │ │ 活跃规则: 0 │ │
│ │ [进入管理] │ │ [进入管理] │ │ [进入管理] │ │
│ └────────────────┘ └────────────────┘ └──────────────┘ │
└──────────────────────────────────────────────────────────────┘添加项目时填写：项目名称 + 后端网关地址 + headers 配置。
3.3 项目内页：菜单 + 接口管理
左侧菜单一比一对照业务系统的真实菜单，右侧展示接口列表和规则编辑：
┌──────────────────────────────────────────────────────────────┐
│ PageProxy / 运营后台 [← 返回] [项目开关: ON] │
├──────────────────┬───────────────────────────────────────────┤
│ │ │
│ 📁 订单管理 │ 订单详情页 │
│ ├ 订单列表 │ │
│ ├ 订单详情 ← │ 接口列表: │
│ └ 退款记录 │ POST /api/order/detail [🟢 ON] │
│ 📁 会员中心 │ POST /api/order/benefits [⚪ OFF] │
│ ├ 会员列表 │ POST /api/delivery/info [⚪ OFF] │
│ ├ 等级管理 │ │
│ └ 会员画像 │ 规则编辑: /order/query/v2/detail │
│ 📁 营销管理 │ 动作: [ merge ▼ ] │
│ 📁 渠道管理 │ 场景: [已退款] [已取消] [空] [超时] [500]│
│ 📁 门店管理 │ │
│ 📁 商品管理 │ { "data.status": 65 } │
│ 📁 财务结算 │ │
│ │ [保存] [删除] [录制真实数据] │
│ 🔍 搜索接口... │ │
└──────────────────┴───────────────────────────────────────────┘3.4 关键操作示例
QA 测试"订单已退款场景"：
- 打开 PageProxy → 选"运营后台"
- 左侧选：订单管理 > 订单详情
- 点击
/api/order/detail→ 选"已退款" → 开关打开 - 回到业务页面刷新 → 看到退款状态
- 测完关掉开关，恢复正常
录制功能：点"录制真实数据"→ 代理下次请求时保存后端真实返回 → 在此基础上改几个字段 → 保存为场景规则。
四、具体实施与分步
4.1 Phase 1：MVP --- 本地可用（2 周）
目标：自己本地能跑起来，验证代理转发 + 规则篡改的核心流程。
- 后端：Express 代理引擎，支持 4 种动作（merge/replace/delay/error）
- 后端：规则 CRUD API，数据存 JSON 文件
- 前端：简易管理界面（项目列表 + 接口列表 + JSON 编辑器）
- 接入：改 rsbuild proxy target 指向 PageProxy 验证
- AI Skill：写一个 Skill 用于扫描当前项目生成索引 JSON
验收标准：本地启动 PageProxy，在界面上给一个接口配一条 merge 规则，刷新业务页面能看到修改后的数据。
4.2 Phase 2：测试环境推广（1 周）
目标：部署到内网，QA 能用。
- Docker 部署到内网服务器
- 业务项目加开关：axios 拦截器 + 悬浮球组件（仅测试环境）
- 管理界面完善：菜单结构一比一对照业务系统
- 场景快捷：内置空数据/500/超时等常用模板
验收标准：QA 在测试环境打开悬浮球开关，在 PageProxy 界面选页面、选场景，业务页面展示 Mock 数据。
4.3 Phase 3：体验优化（2 周）
- 录制功能：代理层抓真实返回，一键保存为规则基准
- 多项目支持完善：各工程的菜单和索引独立管理
- 规则共享：团队可见公共场景库
- 搜索：输入接口 URL 片段，反查所有关联页面
4.4 Phase 4：生态扩展（持续）
- AI Skill 增强：支持增量扫描、diff 报告
- 接口变更通知：扫描发现变更时飞书推送
- Swagger 导入：支持从接口文档批量导入
- 多人隔离：支持按用户独立管理规则（互不影响）
五、总结
PageProxy 是什么：一个前端团队的接口认知基础设施------用页面维度管理接口关系，用透明代理实现场景切换。
对团队的价值：
- 前端：不等后端、不改代码就能测任何场景
- 测试：点一个按钮就能覆盖边界场景，不求人
- 团队：接口依赖关系透明可视，变更影响一目了然
对个人的价值：
- 这是一个完整的全栈项目------Node.js 后端 + 代理网关 + React 管理界面 + Docker 部署
- 从前端切入后端/基础设施方向的实战练兵场