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

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

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

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

@@ -1,293 +0,0 @@
-# 平台 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 前端验证