@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-frontend/references/http-client/acceptance.md

@@ -0,0 +1,348 @@
+# HTTP Client 验收（acceptance）
+
+> **目的**：前端多服务 HTTP 客户端 8 项验收标准（HC-01 ~ HC-08），含自动化测试方法。
+> **来源**：石油 `merit-cloud-http-client/acceptance.md` + `scripts/validate-client.mjs`
+> **警告**：仅"HTTP 200"不算成功，必须通过角色和业务场景验收。
+
+---
+
+## 一、HC-01 ~ HC-08 验收清单
+
+| ID | 标准 | 自动化 | 测试方法 |
+|----|------|:------:|---------|
+| HC-01 | 业务 + system-manager + bpm-engine alias 都已注册 | ✅ | registry 扫描 |
+| HC-02 | 跨 service 并发请求不串 baseURL | ✅ | 集成测试 |
+| HC-03 | 平台 header 存在且包装器未覆盖插件生成值 | ✅ | header 探针 |
+| HC-04 | JSON/form/multipart/blob 并发 50 次不互相污染 | ✅ | 压测 |
+| HC-05 | 4 种响应按 schema 唯一解包 | ✅ | 单元测试 |
+| HC-06 | session-expired/nouser 只触发一次跳转 | ✅ | mock 测试 |
+| HC-07 | 人员选择走 system-manager，回填稳定 ID+名称 | ✅ | E2E 测试 |
+| HC-08 | system-manager 不可用时业务 CRUD 仍可用 | ✅ | 故障注入 |
+
+---
+
+## 二、HC-01：所有 alias 都已注册
+
+### 测试场景
+
+```js
+// 业务页面 + 人员选择 + 流程审批 + 附件下载 4 个场景
+// 验证每个场景用到的 service 都已注册
+
+// 测试代码
+import registry from '@/api/registry';
+
+const required = ['business', 'system-manager', 'bpm-engine', 'enclosure'];
+for (const svc of required) {
+  expect(registry.services[svc]).toBeDefined();
+}
+```
+
+### 通过标准
+
+- ✅ 业务 + system-manager + bpm-engine + enclosure 4 个 service 全部注册
+- ✅ 所有用到的 endpoint 都在 registry
+- ✅ alias 拼写正确（无 `cloud-leave` 这种 typo）
+
+---
+
+## 三、HC-02：跨 service 并发不串 baseURL
+
+### 测试场景
+
+```js
+// 业务 + system-manager + bpm-engine 并发
+const [r1, r2, r3] = await Promise.all([
+  http.call('order.getById', { id: 1 }),         // business
+  http.call('user.getById', { userId: 'u1' }),   // system-manager
+  http.call('bpm.history', { bizKey: 'PO:1' })   // bpm-engine
+]);
+
+// 验证 baseURL 互不污染
+expect(r1).toBeDefined();  // 业务数据
+expect(r2).toBeDefined();  // 用户数据
+expect(r3).toBeDefined();  // 流程数据
+```
+
+### 通过标准
+
+- ✅ 3 个 service 并发，全部成功返回
+- ✅ 响应数据互不混淆（不会出现"用户数据当成订单"）
+- ✅ 任意一个失败不影响其他
+
+---
+
+## 四、HC-03：平台 header 存在 + 包装器未覆盖
+
+### 测试场景
+
+```js
+// 1. mock 平台 plugin，记录所有 header
+const capturedHeaders = [];
+http.plugin.interceptors.request.use(config => {
+  capturedHeaders.push(config.headers);
+  return config;
+});
+
+// 2. 发请求
+await http.call('order.getById', { id: 1 });
+
+// 3. 验证平台 header 全部存在
+const h = capturedHeaders[0];
+expect(h['Cloud-Sign']).toBeDefined();
+expect(h['Cloud-Time-Stamp']).toBeDefined();
+expect(h['qinLang']).toBeDefined();
+expect(h['x-requested-with']).toBe('XMLHttpRequest');
+expect(h['Request-Csrf-Token']).toBeDefined();
+
+// 4. 验证业务代码未覆盖
+expect(h['Cloud-Sign']).not.toContain('business-override');
+```
+
+### 通过标准
+
+- ✅ 7 个平台 header 全部自动生成（见 [http-plugin.md](http-plugin.md) §一）
+- ✅ 业务代码未覆盖（特别是 Cloud-Sign / Cloud-Time-Stamp / Request-Csrf-Token）
+- ✅ resourceId 与当前路由匹配
+
+---
+
+## 五、HC-04：并发 50 次不互相污染
+
+### 测试场景
+
+```js
+// 并发 50 个不同 contentType 的请求
+const requests = [];
+for (let i = 0; i < 50; i++) {
+  if (i % 4 === 0) requests.push(http.call('order.getById', { id: i }));           // JSON GET
+  if (i % 4 === 1) requests.push(http.call('order.approve', { id: i, action: 'agree' })); // JSON POST
+  if (i % 4 === 2) requests.push(http.call('enclosure.upload', formData));         // multipart
+  if (i % 4 === 3) requests.push(http.call('enclosure.download', { fileId: 1 }));   // blob
+}
+
+await Promise.all(requests);
+
+// 验证 defaults 前后不变
+expect(http.plugin.defaults.headers).not.toHaveProperty('Content-Type');
+```
+
+### 通过标准
+
+- ✅ 50 次请求全部成功
+- ✅ 每个请求的 content type 与 endpoint schema 一致
+- ✅ `Axios.defaults.headers` 不被业务修改
+
+---
+
+## 六、HC-05：4 种响应按 schema 唯一解包
+
+### 测试场景
+
+```js
+describe('responseShape 解包', () => {
+  test('result-body + body', async () => {
+    mockResultBody({ code: 200, data: { id: 1 }, message: 'success' });
+    const data = await http.call('order.getById', { id: 1 });
+    expect(data).toEqual({ id: 1 });  // 直接拿到 data
+  });
+
+  test('result-body + data', async () => {
+    mockResultBody({ code: 200, data: { id: 1 }, message: 'success' });
+    const result = await http.call('order.batchImport', { ... });
+    expect(result.code).toBe(200);  // 完整 ResultBody
+  });
+
+  test('raw-array', async () => {
+    mockRawArray([{ code: 'a', name: 'A' }]);
+    const list = await http.call('dict.listAll', {});
+    expect(Array.isArray(list)).toBe(true);
+  });
+
+  test('blob', async () => {
+    mockBlob(new Blob(['pdf content']));
+    const blob = await http.call('enclosure.download', { fileId: 1 });
+    expect(blob).toBeInstanceOf(Blob);
+  });
+
+  test('blob + JSON 错误体', async () => {
+    mockBlob(new Blob([JSON.stringify({ code: 'FILE_NOT_FOUND' })]));
+    try {
+      await http.call('enclosure.download', { fileId: 999 });
+    } catch (e) {
+      expect(e.code).toBe('FILE_NOT_FOUND');
+    }
+  });
+});
+```
+
+### 通过标准
+
+- ✅ 4 种 responseShape 各自正确解包
+- ✅ 业务代码不写 `res.data?.data || res.data` 猜测
+- ✅ blob JSON 错误体能被识别为业务错误而非文件下载
+
+---
+
+## 七、HC-06：session-expired 只触发一次跳转
+
+### 测试场景
+
+```js
+// mock 服务端响应：merit-session-expired header
+mockResponse(401, { message: 'session expired' }, {
+  'merit-session-expired': 'true'
+});
+
+// 监听 router.push
+const pushSpy = jest.spyOn(router, 'push');
+await http.call('order.getById', { id: 1 });
+
+// 验证
+expect(pushSpy).toHaveBeenCalledTimes(1);
+expect(pushSpy).toHaveBeenCalledWith('/login?returnUrl=...');
+```
+
+### 通过标准
+
+- ✅ session-expired 触发一次 router.push('/login')
+- ✅ 业务 catch 不再重复跳转
+- ✅ 多个并发请求都返回 401 → 也只跳转一次（plugin 内部防抖）
+
+---
+
+## 八、HC-07：人员选择走 system-manager，回填稳定 ID+名称
+
+### 测试场景
+
+```js
+// 用户在"采购订单"页面选择"审批人"
+// 验证请求走 system-manager 而不是 business
+
+const requestUrl = captureUrl();
+await http.call('user.searchByName', { keyword: '张三' });
+
+// 验证 URL 是 system-manager
+expect(requestUrl).toMatch(/\/gateway\/cloud-system-manage\/user\/search/);
+expect(requestUrl).not.toMatch(/\/cloud-project\//);  // 不是 business
+
+// 验证回填：稳定 ID（userId）+ 名称（userName）
+const selected = await http.call('user.searchByName', { keyword: '张三' });
+expect(selected).toEqual([
+  { userId: 'u10001', userName: '张三', deptName: '采购部' }
+]);
+```
+
+### 通过标准
+
+- ✅ 人员选择请求走 `system-manager`（不是 `business`）
+- ✅ 回填 `userId` + `userName`（不是只回填姓名）
+- ✅ ID 用于后续审批，不用于姓名匹配
+
+---
+
+## 九、HC-08：system-manager 不可用时业务 CRUD 仍可用
+
+### 测试场景
+
+```js
+// 1. mock system-manager 503
+mockServiceUnavailable('system-manager');
+
+// 2. 业务 CRUD 仍可用
+const order = await http.call('order.getById', { id: 1 });
+expect(order).toBeDefined();  // 业务不受影响
+
+// 3. 人员选择明确报错（不阻塞页面）
+try {
+  await http.call('user.searchByName', { keyword: '张三' });
+} catch (e) {
+  expect(e.code).toBe('SERVICE_UNAVAILABLE');
+}
+
+// 4. 访问日志按 non-blocking 记录
+// （即使 system-manager 不可用，访问日志失败也不影响主流程）
+```
+
+### 通过标准
+
+- ✅ system-manager 503 → 业务 CRUD 正常返回
+- ✅ 人员选择明确报错（用户可理解）
+- ✅ 访问日志 non-blocking（不阻塞业务）
+- ✅ 页面不白屏
+
+---
+
+## 十、负例扫描（CI 阻断）
+
+```bash
+# 运行 scripts/validate-client.mjs
+node scripts/validate-client.mjs --project src/ --registry src/api/registry.js
+```
+
+### 10.1 扫描项
+
+| 扫描 | 阻断条件 |
+|------|---------|
+| `Axios.defaults.headers.*` 写入 | ❌ 任何全局 header 修改 |
+| 括号/点号访问的未注册 alias | ❌ `axios['xxx']` / `axios.xxx` / `_vm.xxx` / `$http.xxx` |
+| endpoint 缺 responseShape | ❌ 必填 |
+| 原生 Axios 绕过平台 plugin | ❌ `import axios from 'axios'`（必须 `from '@cloud-module-base/httpConfig/http-plugin'`）|
+| service path 含 `/gateway` | ❌ |
+| endpoint path 含完整 URL | ❌ |
+
+### 10.2 阻断错误示例
+
+```
+❌ [src/views/order/detail.vue:23] Axios.defaults.headers.post['Content-Type']
+   → 跨 service header 污染风险
+
+❌ [src/views/user/list.vue:45] this.axios['cloud-leave'].postJson
+   → cloud-leave 未在 registry 注册
+
+❌ [src/api/endpoints.js:78] endpoint 'order.getById' 缺 responseShape
+   → 解包行为未定义
+
+❌ [src/utils/http.js:1] import axios from 'axios'
+   → 绕过平台 plugin，应改为 http-plugin
+```
+
+---
+
+## 十一、性能验收
+
+| 指标 | 标准 |
+|------|------|
+| 50 并发 JSON/form/multipart/blob | ≤ 3 秒 |
+| 单 endpoint 响应 | ≤ 1 秒（P95）|
+| registry 加载 | ≤ 50ms |
+| 5 段路径拼接 | ≤ 1ms / 次 |
+
+---
+
+## 十二、上线前 Checklist
+
+- [ ] 8 项验收（HC-01 ~ HC-08）全部通过
+- [ ] registry 所有 endpoint 注册完毕
+- [ ] 4 种 responseShape 各覆盖至少 1 个 endpoint
+- [ ] 会话过期测试通过（不双跳转）
+- [ ] 故障注入测试通过（system-manager 不可用）
+- [ ] 负例扫描 0 阻断项
+- [ ] 性能验收达标
+
+---
+
+## 十三、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| 后端 Java Feign | `meritdata-platform-data-access/references/outbound/feign-guide.md` |
+| 同 JVM Service | `meritdata-platform-data-access/references/outbound/service-catalog.md` |
+| 平台对外 API | `meritdata-platform-data-access/references/outbound/webapi.md` |
+| V6.13.2 平台实例 | `meritdata-dev-docs-file-finder/references/dev-docs/` |
+
+---
+
+**最后更新**：2026-09-08（v2.6.0 P1-A 整合）
+**来源**：石油 `merit-cloud-http-client/acceptance.md` + scripts/validate-client.mjs
+**整合位置**：`meritdata-platform-frontend/references/http-client/acceptance.md`

package/skills/meritdata-platform-frontend/references/http-client/gateway-paths.md

@@ -0,0 +1,281 @@
+# 5 段路径拼接（gateway-paths）
+
+> **目的**：理解 MeritData Cloud 平台前端 HTTP 请求的 5 段路径组成，避免双斜杠、双 gateway 前缀、contextPath 缺失等拼接错误。
+> **来源**：石油 `merit-cloud-http-client/contracts.md`
+
+---
+
+## 一、5 段路径模型
+
+```
+完整 URL = gatewayOrigin + gatewayPrefix + serviceName + contextPath + controllerPath
+```
+
+| 段 | 来源 | 示例 |
+|----|------|------|
+| 1. `gatewayOrigin` | 部署环境 | `https://gateway.meritdata.com` |
+| 2. `gatewayPrefix` | 部署环境（固定） | `/gateway` |
+| 3. `serviceName` | service 配置 `gatewayPrefix` 字段 | `/cloud-project` |
+| 4. `contextPath` | service 配置 `contextPath` 字段（默认空）| `/api/v1` |
+| 5. `controllerPath` | endpoint schema `path` 字段 | `/purchaseOrder/12345` |
+
+完整示例：
+```
+https://gateway.meritdata.com/gateway/cloud-project/api/v1/purchaseOrder/12345
+└─1─┘                       └2┘  └────3────┘  └4┘ └──────5───────┘
+```
+
+---
+
+## 二、各段取法
+
+### 2.1 gatewayOrigin
+
+- 开发环境：`http://localhost:8080`（代理到 gateway）
+- 测试环境：`https://gateway-test.meritdata.com`
+- 生产环境：`https://gateway.meritdata.com`
+
+由 `PREFIXURL` 环境变量注入，**禁止**硬编码。
+
+### 2.2 gatewayPrefix
+
+- 平台固定为 `/gateway`
+- 每个部署环境都有，但只有一段
+- **禁止**在 service path 或 controller path 里再加 `/gateway`
+
+### 2.3 serviceName
+
+- 取自 service 配置的 `gatewayPrefix` 字段
+- 例：`registerService('business', { gatewayPrefix: '/cloud-project' })`
+- **禁止**带协议、域名、query、`/gateway` 重复
+
+### 2.4 contextPath
+
+- 取自 service 配置的 `contextPath` 字段
+- 默认空字符串
+- 当服务有 `server.servlet.context-path=/api/v1` 时填 `/api/v1`
+
+### 2.5 controllerPath
+
+- 取自 endpoint schema 的 `path` 字段
+- 例：`/purchaseOrder/{id}`
+- 路径参数 `{id}` 由 http.call 的 payload 自动替换
+
+---
+
+## 三、拼接函数（参考实现）
+
+```js
+function join(servicePath, endpointPath) {
+  return `${prefixUrl || ''}/gateway${servicePath}/${String(endpointPath || '').replace(/^\/+/, '')}`
+    .replace(/([^:]\/)\/+/g, '$1');  // 归一化 // → /
+}
+
+// 使用
+const url = join('/cloud-project', '/purchaseOrder/12345');
+//  → https://gateway.meritdata.com/gateway/cloud-project/purchaseOrder/12345
+```
+
+**关键点**：
+- `servicePath` 前缀 `/` 必须有
+- `endpointPath` 前缀 `/` 会被去掉（避免 `//`）
+- `//` 自动归一化为 `/`
+
+---
+
+## 四、典型场景
+
+### 4.1 标准业务服务
+
+```js
+// service
+registerService('business', {
+  gatewayPrefix: '/cloud-project',
+  contextPath: ''
+});
+
+// endpoint
+registerEndpoint('order.getById', {
+  service: 'business', method: 'GET', path: '/purchaseOrder/{id}',
+  responseShape: 'result-body', return: 'body'
+});
+
+// 调用
+const url = join('/cloud-project', '/purchaseOrder/12345');
+//  → https://gateway.meritdata.com/gateway/cloud-project/purchaseOrder/12345
+```
+
+### 4.2 带 contextPath 的服务
+
+```js
+// service（Spring 配置 server.servlet.context-path=/api/v1）
+registerService('custom-erp', {
+  gatewayPrefix: '/erp-service',
+  contextPath: '/api/v1'
+});
+
+// endpoint
+registerEndpoint('erp.queryStock', {
+  service: 'custom-erp', method: 'GET', path: '/stock/{sku}',
+  responseShape: 'result-body', return: 'body'
+});
+
+// 调用
+const url = join('/erp-service/api/v1', '/stock/SKU123');
+//  → https://gateway.meritdata.com/gateway/erp-service/api/v1/stock/SKU123
+```
+
+### 4.3 路径参数替换
+
+```js
+// endpoint
+registerEndpoint('order.getById', {
+  service: 'business', method: 'GET', path: '/purchaseOrder/{id}',
+  responseShape: 'result-body', return: 'body'
+});
+
+// 调用
+const order = await http.call('order.getById', { id: 12345 });
+//  → http-plugin 自动替换 {id} → 12345
+//  → GET /gateway/cloud-project/purchaseOrder/12345
+```
+
+---
+
+## 五、网关前缀前检（避免重复 gateway）
+
+### 5.1 反模式
+
+```js
+// ❌ 错误 1：service path 含 /gateway
+registerService('business', { gatewayPrefix: '/gateway/cloud-project' });
+//  → 最终 URL 变成 /gateway/gateway/cloud-project/...
+
+// ❌ 错误 2：endpoint path 含完整 URL
+registerEndpoint('order.getById', {
+  service: 'business',
+  path: 'https://gateway.meritdata.com/gateway/cloud-project/purchaseOrder/{id}'
+});
+//  → 失去 service 切换能力
+
+// ❌ 错误 3：双斜杠
+const url = '/gateway/cloud-project//purchaseOrder/12345';
+//  → 部分网关按路径错乱处理
+```
+
+### 5.2 正模式
+
+```js
+// ✅ 正确：service path 干净（不含 gateway）
+registerService('business', { gatewayPrefix: '/cloud-project' });
+
+// ✅ 正确：endpoint path 只写 controller
+registerEndpoint('order.getById', {
+  service: 'business', method: 'GET', path: '/purchaseOrder/{id}'
+});
+
+// ✅ 正确：用 join() 拼接，自动归一化
+const url = join('/cloud-project', '/purchaseOrder/12345');
+//  → /gateway/cloud-project/purchaseOrder/12345
+```
+
+---
+
+## 六、5 段来源记录（必填）
+
+每个 endpoint 生成时记录 5 段来源，缺任一证据则输出 GAP：
+
+```js
+registerEndpoint('order.getById', {
+  service: 'business',
+  method: 'GET',
+  path: '/purchaseOrder/{id}',
+  // ===== 5 段来源记录（CI 校验）=====
+  pathProvenance: {
+    gatewayOrigin: 'PREFIXURL env',           // ✅ 环境变量
+    gatewayPrefix: 'platform /gateway fixed', // ✅ 平台固定
+    serviceName: 'cloud-project spring.application.name', // ✅ 服务配置
+    contextPath: 'empty (server.servlet.context-path unset)', // ✅ 显式声明
+    controllerPath: 'PurchaseOrderController@GetMapping("/purchaseOrder/{id}")', // ✅ Controller 注解
+    authContext: 'session+CSRF',  // ✅ 认证上下文
+    responseShape: 'ResultBody<PurchaseOrderDTO>'  // ✅ 响应结构
+  }
+});
+```
+
+CI 检查：缺任一段来源 → 输出 GAP，阻断发布。
+
+---
+
+## 七、开发代理配置
+
+### 7.1 前端 dev proxy
+
+```js
+// vue.config.js
+module.exports = {
+  devServer: {
+    proxy: {
+      '/gateway': {
+        target: 'http://localhost:8080',  // → gateway origin
+        changeOrigin: true,
+        // 保留 /gateway 前缀（不 rewrite）
+        pathRewrite: undefined
+      }
+    }
+  }
+};
+```
+
+**关键点**：
+- proxy target 只指向 `gatewayOrigin`
+- 保留 `gatewayPrefix`（**不**用 pathRewrite 去掉）
+- 直连服务端口仅限用户明确要求的本地调试
+
+### 7.2 直连 vs 走 gateway
+
+| 场景 | 是否走 gateway |
+|------|:-------------:|
+| 开发联调 | ✅ 走 gateway（生产一致）|
+| 单元测试 mock | ❌ 可直连（mock 服务）|
+| 本地断网调试 | ⚠️ 仅用户明确要求时 |
+| 生产部署 | ✅ **必须**走 gateway |
+
+---
+
+## 八、典型错误排查
+
+| 现象 | 根因 | 修复 |
+|------|------|------|
+| 404 NOT FOUND | 路径错乱 / 双 gateway | 检查 join() 拼接 |
+| 401 UNAUTHORIZED | 缺 Cloud-Sign | 走 platform plugin |
+| 跨域 CORS | 直连服务 IP | 改走 gateway |
+| 会话丢失（页面刷新）| token 没透传 | 检查 Cookie 域 |
+| 403 FORBIDDEN | X-Tenant 不匹配 | 检查当前租户 |
+
+---
+
+## 九、与 dev-docs 的协作
+
+| 场景 | 文档 |
+|------|------|
+| V6.13.2 manage 前端实例 | `meritdata-dev-docs-file-finder/references/dev-docs/工作流程应用开发.pdf` 第 31-32 页 |
+| 平台 plugin 源码 | `meritdata-dev-docs-file-finder/references/dev-docs/cloud-module-base/packages/httpConfig/` |
+| gateway 路由配置 | 平台运维文档（不在 skill 范围）|
+
+---
+
+## 十、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| service path 含 `/gateway` | 双前缀 | service path 干净 |
+| endpoint path 含完整 URL | 失去 service 切换 | 只写 controller path |
+| 双斜杠 `//` | 网关路径错乱 | join() 归一化 |
+| 缺任一段来源记录 | CI 阻断 | 显式声明 pathProvenance |
+| 直连服务 IP 调试 | 生产失效 | 走 gateway proxy |
+
+---
+
+**最后更新**：2026-09-08（v2.6.0 P1-A）
+**来源**：石油 `merit-cloud-http-client/contracts.md`