@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

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

@@ -1,85 +0,0 @@
-# 前端多服务 HTTP 客户端（http-client）
-
-> **目的**：Vue2 前端通过统一的平台 HTTP 插件（axios wrapper），安全、可诊断、可隔离地调用多个后端微服务（business / system-manager / bpm-engine / enclosure / ...）。
-> **来源**：石油 `merit-cloud-dev/modules/merit-cloud-http-client/`（v2.6.0 P1-A 整合）
-> **平台版本**：MeritData Cloud V6.13.2（其他版本需要做 header/response probe 后单独 adapter）
-
----
-
-## 触发场景
-
-- 新建前端页面要调多个后端服务（业务 + 人员 + BPM + 附件）
-- 已有页面要新增 endpoint，但 baseURL 不知道写在哪儿
-- 页面有 `Axios.defaults.headers.xxx = ...` 这种全局污染代码
-- 出现 `res.data?.data || res.data` 猜测式解包
-- 出现"bpm-engine 接口返回 401 但用户已登录"（session header 串服务）
-- 附件下载直连服务 IP（绕过 gateway + token）
-- 一个服务 500 导致整个页面崩溃（无并发隔离）
-
-## 不触发
-
-- 内部微服务调用（Java 进程内）→ 用 `meritdata-platform-data-access/references/outbound/`
-- 平台对外发布 API → 用 `meritdata-platform-data-access/references/outbound/webapi.md`
-- 第三方 HTTP 调用（无平台认证）→ 走 Nacos + 自定义 axios
-- Node SSR / 后端渲染 → 不在 Vue2 前端栈范围
-
----
-
-## 前置约束
-
-- **必须用平台 http-plugin**（`@cloud-module-base/httpConfig/http-plugin`），禁止自建 axios 实例
-- **必须声明式注册** services + endpoints（registry 模式），禁止调用方手写完整 URL
-- **必须显式声明** `responseShape` + `return`，禁止猜测式解包
-- **禁止**修改 `Axios.defaults.headers.*`（会污染所有 service）
-- **禁止**业务代码自行实现 `Cloud-Sign` 签名（算法不一致 + 密钥泄露）
-- **禁止**绕过 gateway 直连服务 IP（生产环境无法路由 + 缺签名）
-
----
-
-## 路由
-
-### Step 1：识别要调几个后端服务
-
-| 场景 | service 注册 |
-|------|------------|
-| 业务 CRUD | `business` |
-| 人员 / 部门 / 角色 / 字典 / 资源权限 / 访问日志 | `system-manager` |
-| 流程表单 / 待办 / 追踪 | `bpm-engine` |
-| 附件上传下载 | `enclosure` |
-| 自定义业务服务 | `<custom-service>` |
-
-### Step 2：注册 services + endpoints
-
-→ [service-registry.md](service-registry.md)
-
-### Step 3：理解平台 plugin 行为
-
-→ [http-plugin.md](http-plugin.md)
-
-### Step 4：理解 5 段路径拼接
-
-→ [gateway-paths.md](gateway-paths.md)
-
-### Step 5：验收
-
-→ [acceptance.md](acceptance.md)（HC-01 ~ HC-08）
-
----
-
-## 关键反模式速查
-
-| 反模式 | 后果 | 正确做法 |
-|--------|------|---------|
-| `Axios.defaults.headers.xxx = ...` | 跨 service header 污染 | 用当次 config 或 endpoint schema |
-| `res.data?.data || res.data` 猜测式解包 | 旧服务无 ResultBody 包装就崩 | endpoint schema 声明 `responseShape` |
-| `this.axios['cloud-leave'].post(...)` 未注册 alias | 运行期 `undefined` | registry 注册 + alias 预检 |
-| 业务代码自实现 `Cloud-Sign` | 算法不一致 + 密钥泄露 | 只用平台 plugin 生成 |
-| URL 拼接双斜杠 `//` | 部分网关路径错乱 | 用 `join()` 函数归一化 |
-| 附件直连服务 IP + 无 token | 重开页面会话丢失 | 走临时 URL（带 token + 过期）|
-| 4 个独立 axios 实例 | 绕过 gateway + 签名 + 会话 | 1 个平台 plugin + 多 service 注册 |
-
----
-
-**最后更新**：2026-09-08（v2.6.0 P1-A 整合）
-**来源**：石油 `merit-cloud-http-client`（contracts.md / client-implementation.md / anti-patterns.md / acceptance.md）
-**整合位置**：`meritdata-platform-frontend/references/http-client/`

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

@@ -1,348 +0,0 @@
-# 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`