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

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

@@ -0,0 +1,293 @@
+# 平台 HTTP Plugin 行为（http-plugin）
+
+> **目的**：理解 MeritData Cloud V6.13.2 平台 HTTP 插件（`@cloud-module-base/httpConfig/http-plugin`）自动处理哪些事情，业务方不用重复实现。
+> **来源**：石油 `merit-cloud-http-client/contracts.md` + V6.13.2 平台 manage 前端验证
+
+---
+
+## 一、平台 plugin 自动处理的 7 件事
+
+| # | 处理 | 实现位置 | 业务方要求 |
+|--|------|---------|----------|
+| 1 | `qinLang` header（语言）| plugin request interceptor | 无 |
+| 2 | `Cloud-Sign` 签名 | plugin request interceptor | ❌ **禁止自实现** |
+| 3 | `Cloud-Time-Stamp` 时间戳 | plugin request interceptor | ❌ 禁止自加 |
+| 4 | `x-requested-with: XMLHttpRequest` | plugin request interceptor | 无 |
+| 5 | `resourceId`（当前路由资源 ID）| plugin request interceptor | 无 |
+| 6 | `smPrivate`（国密会话密钥）| plugin request interceptor | ❌ 禁止覆盖 |
+| 7 | `Request-Csrf-Token` CSRF 防护 | plugin request interceptor | ❌ 禁止覆盖 |
+
+**业务方结论**：所有 header 都由 plugin 自动处理，业务代码只需要声明 endpoint schema + 传入 payload。
+
+---
+
+## 二、会话过期处理
+
+平台 plugin 监听响应 header：
+
+| header 值 | 触发动作 |
+|---------|---------|
+| `merit-session-expired` | 跳转到登录页（保留 returnUrl） |
+| `merit-session-nouser` | 跳转到登录页（保留 returnUrl） |
+
+### 关键约束
+
+- ❌ **禁止**业务代码自实现会话跳转（会导致双跳转）
+- ❌ **禁止**业务 catch 里检测 401 后再跳转（plugin 已处理）
+- ✅ **允许**业务代码在 catch 里做"业务级"提示（如"用户无权限"），但不要重复全局跳转
+
+```js
+// ❌ 错误：业务代码重复跳转
+try {
+  const data = await http.call('order.getById', { id });
+} catch (e) {
+  if (e.response?.status === 401) {
+    router.push('/login');  // ❌ plugin 已处理
+  }
+}
+
+// ✅ 正确：只关心业务错误
+try {
+  const data = await http.call('order.getById', { id });
+} catch (e) {
+  if (e.code === 'ORDER_NOT_FOUND') {
+    this.$message.error('订单不存在');
+  }
+  // 401/会话过期：plugin 已自动跳转，业务不要管
+}
+```
+
+---
+
+## 三、签名与会话
+
+### 3.1 Cloud-Sign 签名
+
+- 算法：平台内部（**业务方不要知道也不要实现**）
+- 密钥：服务端持有，浏览器无密钥
+- 字段：基于 request body + timestamp + secret
+- 时效：5 分钟（防重放）
+
+**为什么业务方不能自实现**：
+1. 算法版本不一致 → 服务端验签失败 → 401
+2. 密钥泄露到浏览器 → 完全无安全意义
+3. 绕过平台时间戳策略 → 重放攻击风险
+
+### 3.2 Session 透传
+
+- `Cookie: JSESSIONID + MERIT_SESSION`（自动）
+- 登录后由 server set，plugin 自动带上
+- 退出登录由 server clear
+
+### 3.3 多租户
+
+- `X-Tenant: t001`（自动）
+- 登录后由 server set，根据用户绑定租户
+- 切换租户：plugin 监听切换事件重新设置
+
+---
+
+## 四、响应解包规则
+
+### 4.1 V6.13.2 plugin 已返回 `response.data`
+
+```js
+// axios 原始：response = { data, status, headers, ... }
+// V6.13.2 plugin 已 unWrap：返回的就是 response.data
+```
+
+### 4.2 业务代码不要二次解包
+
+```js
+// ❌ 错误：res.data 已是 ResultBody，再取 .data 得到 undefined
+client.get('/api/project/get/' + id).then(res => res.data.data)
+
+// ✅ 正确：endpoint schema 声明 return: 'body'，plugin 自动取 data.data
+registerEndpoint('project.getById', {
+  service: 'business', method: 'GET', path: '/project/{id}',
+  responseShape: 'result-body', return: 'body'
+});
+// 业务代码：
+const project = await http.call('project.getById', { id: 1 });
+//  → project 已经是 ResultBody.data 里的对象
+```
+
+### 4.3 不同 responseShape 的解包规则
+
+| responseShape | plugin 返回 |
+|--------------|------------|
+| `result-body` | 成功：`body.data`；失败：reject BusinessApiError |
+| `raw-array` | 直接是数组（不解包）|
+| `blob` | Blob 对象 |
+
+详见 [service-registry.md](service-registry.md) §四。
+
+---
+
+## 五、错误分类
+
+### 5.1 业务错误（BusinessApiError）
+
+```js
+{
+  code: 'ORDER_NOT_FOUND',
+  message: '订单不存在',
+  httpStatus: 200  // 业务失败但 HTTP 成功
+}
+```
+
+```js
+// 业务代码捕获
+try {
+  const order = await http.call('order.getById', { id });
+} catch (e) {
+  if (e.name === 'BusinessApiError') {
+    // 业务错误
+    if (e.body.code === 'ORDER_NOT_FOUND') {
+      this.$message.error('订单不存在');
+    }
+  }
+}
+```
+
+### 5.2 传输错误（NetworkError）
+
+```js
+{
+  message: 'Network Error',
+  httpStatus: 0
+}
+```
+
+- 超时 → reject with timeout error
+- 服务不可达 → reject with ECONNREFUSED
+- CORS → reject（一般不会出现，gateway 已配）
+
+### 5.3 HTTP 状态码错误
+
+| 状态码 | 含义 | 业务处理 |
+|:------:|------|---------|
+| 401 | 未登录 | plugin 自动跳转登录 |
+| 403 | 无权限 | plugin 自动提示 |
+| 404 | 资源不存在 | 业务 catch 处理 |
+| 409 | 状态冲突 | 业务 catch 处理 |
+| 500 | 服务异常 | plugin 统一提示"系统繁忙" |
+
+---
+
+## 六、并发隔离
+
+### 6.1 plugin 内部并发模型
+
+- 每个 service 独立 axios 实例（不共享）
+- header/config 当次生效，不污染
+- 单 service 失败不影响其他 service
+
+### 6.2 业务代码并发
+
+```js
+// ✅ 正确：3 个 service 并发，互不影响
+const [order, approver, history] = await Promise.all([
+  http.call('order.getById', { id }),
+  http.call('user.getById', { userId }),
+  http.call('bpm.history', { bizKey })
+]);
+
+// 即便 bpm-engine 503，order 和 approver 也正常返回
+```
+
+### 6.3 一个 service 不可用不影响其他
+
+**验收 HC-08**：
+- `system-manager` 不可用 → 业务 CRUD 仍可用，人员/字典报错但不阻塞
+- 访问日志 → 按 non-blocking 策略记录（不阻塞业务）
+
+---
+
+## 七、上传与下载
+
+### 7.1 上传
+
+```js
+// ✅ 正确：传 FormData，boundary 由 plugin 自动生成
+const formData = new FormData();
+formData.append('file', file);
+formData.append('joinId', 'purchaseOrder:12345');
+
+await http.call('enclosure.upload', formData);
+
+// ❌ 错误：手写 multipart boundary
+const boundary = '----WebKitFormBoundary' + Math.random();
+const body = `--${boundary}\r\nContent-Disposition: form-data...`;
+//  → 服务端解析失败
+```
+
+### 7.2 下载（blob）
+
+```js
+// 1. 下载到 Blob
+const blob = await http.call('enclosure.download', { fileId: 10001 });
+
+// 2. 识别是否为 JSON 错误体（plugin 已识别但业务要二次确认）
+if (blob.type === 'application/json') {
+  const text = await blob.text();
+  const errorBody = JSON.parse(text);
+  // errorBody.code === 'FILE_NOT_FOUND' 等
+}
+
+// 3. 触发浏览器下载
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename.pdf';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+### 7.3 临时 URL 方式（推荐）
+
+```js
+// 1. 拿临时 URL（带 token + 过期时间）
+const tmpUrl = await http.call('enclosure.downloadUrl', { fileId: 10001 });
+//  → https://gateway/enclosure/file/xxx?token=临时token&expire=...
+
+// 2. 直接 window.open（token 自动带过去）
+window.open(tmpUrl);
+```
+
+---
+
+## 八、CSRF 防护
+
+- 平台 plugin 自动加 `Request-Csrf-Token` header
+- 服务端校验：token 必须匹配 session
+- 业务代码不要手动加 CSRF token（plugin 处理）
+
+---
+
+## 九、与 service-catalog 的协作
+
+| 场景 | 协作 |
+|------|------|
+| Java 后端如何暴露接口给前端 | → `meritdata-platform-data-access/references/outbound/feign-guide.md` |
+| 同 JVM Service 直接注入 | → `meritdata-platform-data-access/references/outbound/service-catalog.md` |
+| 前端组件 props/events | → `meritdata-platform-frontend/references/`（UI 组件层）|
+| 前端路由 + 资源权限 | → `meritdata-platform-frontend/references/`（前端架构层）|
+
+---
+
+## 十、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 业务自实现 Cloud-Sign | 401 + 密钥泄露 | 只用 platform plugin |
+| 业务在 catch 里再跳登录 | 双跳转 | plugin 已自动跳 |
+| 二次解包 `res.data.data` | undefined | 用 endpoint schema 的 `return` |
+| 手写 multipart boundary | 服务端解析失败 | 传 FormData |
+| 下载 blob 后不识别 JSON 错误 | 错误体被当文件下载 | 先识别 content-type |
+| 业务方写 `Axios.defaults.headers.xxx` | 跨 service 污染 | 当次 config |
+
+---
+
+**最后更新**：2026-09-08（v2.6.0 P1-A）
+**来源**：石油 `merit-cloud-http-client/contracts.md` + V6.13.2 平台 manage 前端验证

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

@@ -0,0 +1,281 @@
+# Service Registry & Endpoint Schema（service-registry）
+
+> **目的**：声明式注册 services（后端服务）+ endpoints（接口），调用方只关心业务，不关心路径/签名/header。
+> **来源**：石油 `merit-cloud-http-client/contracts.md` + `client-implementation.md`
+
+---
+
+## 一、Registry 最小结构
+
+```json
+{
+  "services": {
+    "business":        { "path": "/cloud-project" },
+    "system-manager":  { "path": "/cloud-system-manage" },
+    "bpm-engine":      { "path": "/cloud-system-bpm-engine" }
+  },
+  "endpoints": {
+    "saveProject": {
+      "service":       "business",
+      "method":        "POST",
+      "contentType":   "json",
+      "responseShape": "result-body",
+      "return":        "body"
+    }
+  }
+}
+```
+
+---
+
+## 二、Service 注册（按调用方向）
+
+### 2.1 业务 CRUD
+
+```js
+registerService('business', {
+  gatewayPrefix: '/cloud-project',
+  contextPath: '',
+  contentType: 'application/json',
+  responseShape: 'ResultBody'
+});
+```
+
+### 2.2 平台 system-manager（人员/部门/角色/字典/资源权限/访问日志）
+
+```js
+registerService('system-manager', {
+  gatewayPrefix: '/cloud-system-manage',
+  contextPath: '',
+  contentType: 'application/json',
+  responseShape: 'ResultBody'
+});
+```
+
+### 2.3 流程 bpm-engine
+
+```js
+registerService('bpm-engine', {
+  gatewayPrefix: '/cloud-system-bpm-engine',
+  contextPath: '',
+  contentType: 'application/json',
+  responseShape: 'ResultBody'
+});
+```
+
+### 2.4 附件 enclosure
+
+```js
+registerService('enclosure', {
+  gatewayPrefix: '/cloud-enclosure',
+  contextPath: '',
+  contentType: 'multipart/form-data',
+  responseShape: 'Raw'  // 附件下载不是 ResultBody 包装
+});
+```
+
+### 2.5 自定义业务服务
+
+```js
+registerService('custom-erp', {
+  gatewayPrefix: '/erp-service',
+  contextPath: '/api/v1',
+  contentType: 'application/json',
+  responseShape: 'ResultBody'
+});
+```
+
+---
+
+## 三、Endpoint Schema 字段
+
+| 字段 | 必填 | 取值 | 含义 |
+|------|:----:|------|------|
+| `service` | ✅ | 已注册的 service 名 | 路由到哪个 service |
+| `method` | ✅ | `GET` / `POST` / `PUT` / `DELETE` | HTTP 方法 |
+| `path` | ✅ | `/purchaseOrder/{id}` | controller 路径（含路径参数）|
+| `contentType` | ✅ | `json` / `form` / `multipart` / `blob` | 请求体格式 |
+| `responseShape` | ✅ | `result-body` / `raw-array` / `blob` | 响应结构 |
+| `return` | ✅ | `body` / `data` | 返回值字段（见 §四）|
+| `params` | ❌ | `{ key: 'required:string' }` | Query 参数 schema |
+| `body` | ❌ | `{ key: 'optional:number' }` | Body 参数 schema |
+| `timeout` | ❌ | `30000` | 超时（ms，默认 30s）|
+| `errors` | ❌ | `{ 409: '状态冲突' }` | 业务错误码 → 中文提示 |
+
+---
+
+## 四、`responseShape` × `return` 组合矩阵
+
+| responseShape | return | 适用场景 | 实际返回值 |
+|--------------|--------|---------|----------|
+| `result-body` | `body` | 业务对象（订单/用户/角色）| `body.data` |
+| `result-body` | `data` | 完整 ResultBody（含 code/message）| `body` |
+| `raw-array` | — | 直接返回数组（旧服务）| `body` 数组 |
+| `blob` | — | 文件下载 / 二进制 | `body` Blob |
+
+### 4.1 `result-body` + `body`（最常见）
+
+```js
+registerEndpoint('order.getById', {
+  service: 'business',
+  method: 'GET',
+  path: '/purchaseOrder/{id}',
+  responseShape: 'result-body',
+  return: 'body'
+});
+// 响应：{ code:200, data:{ id, title, ... }, message:'success' }
+// 业务代码拿到：{ id, title, ... }
+```
+
+### 4.2 `result-body` + `data`（需要完整 code）
+
+```js
+registerEndpoint('order.batchImport', {
+  service: 'business',
+  method: 'POST',
+  path: '/purchaseOrder/batchImport',
+  responseShape: 'result-body',
+  return: 'data'
+});
+// 业务代码判断 code 做不同分支
+```
+
+### 4.3 `raw-array`（旧服务）
+
+```js
+registerEndpoint('dict.listAll', {
+  service: 'system-manager',
+  method: 'GET',
+  path: '/dict/all',
+  responseShape: 'raw-array',
+  return: 'data'  // raw-array 时 return 忽略
+});
+// 响应：[ { code, name }, ... ]
+// 业务代码拿到：数组
+```
+
+### 4.4 `blob`（文件下载）
+
+```js
+registerEndpoint('enclosure.download', {
+  service: 'enclosure',
+  method: 'GET',
+  path: '/file/{fileId}/download',
+  responseShape: 'blob',
+  return: 'data'
+});
+// 响应：Blob 二进制
+```
+
+---
+
+## 五、完整示例：采购订单详情页
+
+```js
+// src/api/registry.js
+import { registerService, registerEndpoint } from '@cloud-module-base/httpConfig/http-plugin';
+
+// ============== service 注册 ==============
+registerService('business',       { gatewayPrefix: '/cloud-project',            responseShape: 'ResultBody' });
+registerService('system-manager', { gatewayPrefix: '/cloud-system-manage',      responseShape: 'ResultBody' });
+registerService('bpm-engine',     { gatewayPrefix: '/cloud-system-bpm-engine',  responseShape: 'ResultBody' });
+registerService('enclosure',      { gatewayPrefix: '/cloud-enclosure',          responseShape: 'Raw' });
+
+// ============== 业务 endpoint ==============
+registerEndpoint('order.getById', {
+  service: 'business', method: 'GET',
+  path: '/purchaseOrder/{id}',
+  responseShape: 'result-body', return: 'body',
+  errors: { 404: '订单不存在' }
+});
+
+registerEndpoint('order.approve', {
+  service: 'business', method: 'POST',
+  path: '/purchaseOrder/{id}/approve',
+  responseShape: 'result-body', return: 'body',
+  errors: { 409: '订单状态不允许审批' }
+});
+
+// ============== 人员 endpoint ==============
+registerEndpoint('user.getById', {
+  service: 'system-manager', method: 'GET',
+  path: '/user/{userId}',
+  responseShape: 'result-body', return: 'body',
+  errors: { 404: '用户不存在' }
+});
+
+// ============== 流程 endpoint ==============
+registerEndpoint('bpm.history', {
+  service: 'bpm-engine', method: 'GET',
+  path: '/processInstance/history',
+  params: { bizKey: 'required:string' },
+  responseShape: 'result-body', return: 'body'
+});
+
+registerEndpoint('bpm.completeTask', {
+  service: 'bpm-engine', method: 'POST',
+  path: '/task/{taskId}/complete',
+  body: { action: 'required:string', comment: 'optional:string' },
+  responseShape: 'result-body', return: 'body'
+});
+
+// ============== 附件 endpoint ==============
+registerEndpoint('enclosure.downloadUrl', {
+  service: 'enclosure', method: 'GET',
+  path: '/file/{fileId}/downloadUrl',
+  responseShape: 'result-body', return: 'body'
+});
+```
+
+```js
+// src/views/purchase-order/detail.vue
+import http from '@cloud-module-base/httpConfig/http-plugin';
+
+export default {
+  async mounted() {
+    // 1. 业务：拉订单
+    this.order = await http.call('order.getById', { id: this.orderId });
+
+    // 2. 人员：拉审批人（跨 service，header 自动隔离）
+    this.approver = await http.call('user.getById', { userId: this.order.approverUserId });
+
+    // 3. 流程：拉历史
+    const bizKey = `purchaseOrder:${this.orderId}`;
+    this.history = await http.call('bpm.history', { bizKey });
+
+    // 4. 并发：人员 + 流程 同时拉
+    await Promise.all([
+      this.loadApprover(),
+      this.loadHistory()
+    ]);
+  }
+};
+```
+
+---
+
+## 六、与平台 plugin 协作
+
+registry 只声明"调哪个服务/哪个端点"，实际 HTTP 调用由平台 `http-plugin` 完成：
+- 路径拼接（5 段）→ 见 [gateway-paths.md](gateway-paths.md)
+- Cloud-Sign 签名 → 见 [http-plugin.md](http-plugin.md)
+- 会话/租户 header → 见 [http-plugin.md](http-plugin.md)
+- 响应解包 → 见 [http-plugin.md](http-plugin.md)
+- 错误分类 → 见 [http-plugin.md](http-plugin.md)
+
+---
+
+## 七、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| endpoint 没注册 `responseShape` | 解析失败 | 4 种之一必填 |
+| 跨 service 用全局 defaults | header 串服务 | 当次 config |
+| endpoint.path 写完整 URL（含 gateway）| 路径错乱 | 只写 controller 路径 |
+| service.alias 拼写错（`cloud-leave` 而非 `bpm-engine`）| 运行期 undefined | registry 预检 |
+| 上传手写 multipart boundary | 服务端解析失败 | 传 FormData，boundary 由 plugin 自动生成 |
+
+---
+
+**最后更新**：2026-09-08（v2.6.0 P1-A）
+**来源**：石油 `merit-cloud-http-client/contracts.md` + `client-implementation.md`