npm - @alanwang-merit/meritdata-platform-skill-package - Versions diffs - 1.0.10 → 1.0.11 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (631) hide show

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

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

package/skills/meritdata-platform-frontend/references/project-structure.md DELETED Viewed

@@ -1,318 +0,0 @@
-# 前端工程结构（project-structure）
-> 平台二开前端标准工程结构。
----
-## 1. 目录结构
-```
-your-2nd-frontend/
-├── public/                       # 静态资源
-│   ├── favicon.ico
-│   └── index.html
-├── src/
-│   ├── api/                      # API 接口定义
-│   │   ├── order.js
-│   │   ├── user.js
-│   │   └── index.js
-│   ├── assets/                   # 静态资源（图、字体）
-│   ├── components/               # 业务组件
-│   │   ├── OrderForm.vue
-│   │   └── OrderTable.vue
-│   ├── views/                    # 页面（路由直接对应）
-│   │   ├── order/
-│   │   │   ├── List.vue
-│   │   │   ├── Detail.vue
-│   │   │   └── Create.vue
-│   │   └── Home.vue
-│   ├── router/                   # 路由
-│   │   └── index.js
-│   ├── store/                    # 全局状态（Pinia）
-│   │   ├── user.js
-│   │   └── permission.js
-│   ├── utils/                    # 工具类
-│   │   ├── request.js            # axios 封装
-│   │   ├── auth.js               # Token 管理
-│   │   └── constants.js
-│   ├── styles/                   # 全局样式
-│   │   ├── index.scss
-│   │   └── variables.scss
-│   ├── App.vue
-│   └── main.js
-├── .env.development              # 开发环境配置
-├── .env.production               # 生产环境配置
-├── package.json
-└── vite.config.js                # 或 vue.config.js
-```
----
-## 2. 路由配置
-### 2.1 标准路由
-```javascript
-// src/router/index.js
-import { createRouter, createWebHistory } from 'vue-router';
-const routes = [
-  {
-    path: '/',
-    name: 'Home',
-    component: () => import('@/views/Home.vue'),
-    meta: { requiresAuth: true }
-  },
-  {
-    path: '/orders',
-    name: 'OrderList',
-    component: () => import('@/views/order/List.vue'),
-    meta: {
-      requiresAuth: true,
-      permission: 'purchase_order:view'
-    }
-  },
-  {
-    path: '/orders/create',
-    name: 'OrderCreate',
-    component: () => import('@/views/order/Create.vue'),
-    meta: {
-      requiresAuth: true,
-      permission: 'purchase_order:create'
-    }
-  }
-];
-export default createRouter({
-  history: createWebHistory(),
-  routes
-});
-```
-### 2.2 路由命名约定
-| 路径 | 名称 | 说明 |
-|------|------|------|
-| `/orders` | `OrderList` | 列表页 |
-| `/orders/create` | `OrderCreate` | 创建页 |
-| `/orders/:id` | `OrderDetail` | 详情页 |
-| `/orders/:id/edit` | `OrderEdit` | 编辑页 |
-**关键约定**：
-- URL 复数 + 小写 + 连字符（与后端 API 一致）
-- 名称 PascalCase
----
-## 3. API 调用（request.js）
-### 3.1 axios 封装
-```javascript
-// src/utils/request.js
-import axios from 'axios';
-import { getToken } from './auth';
-const request = axios.create({
-  baseURL: import.meta.env.VITE_API_BASE_URL,
-  timeout: 15000
-});
-// 请求拦截器
-request.interceptors.request.use(
-  config => {
-    config.headers['Authorization'] = `Bearer ${getToken()}`;
-    return config;
-  },
-  error => Promise.reject(error)
-);
-// 响应拦截器
-request.interceptors.response.use(
-  response => {
-    const { code, data, message } = response.data;
-    if (code === 200) {
-      return data;
-    }
-    // 业务错误
-    ElMessage.error(message || '请求失败');
-    return Promise.reject(new Error(message));
-  },
-  error => {
-    if (error.response?.status === 401) {
-      // 未登录，跳转登录
-      window.location.href = '/login';
-    } else if (error.response?.status === 403) {
-      ElMessage.error('无权限');
-    } else {
-      ElMessage.error('网络错误');
-    }
-    return Promise.reject(error);
-  }
-);
-export default request;
-```
-### 3.2 API 模块
-```javascript
-// src/api/order.js
-import request from '@/utils/request';
-export function listOrders(query) {
-  return request({
-    url: '/api/v1/purchase-orders',
-    method: 'get',
-    params: query
-  });
-}
-export function getOrder(id) {
-  return request({
-    url: `/api/v1/purchase-orders/${id}`,
-    method: 'get'
-  });
-}
-export function createOrder(data) {
-  return request({
-    url: '/api/v1/purchase-orders',
-    method: 'post',
-    data
-  });
-}
-export function updateOrder(id, data) {
-  return request({
-    url: `/api/v1/purchase-orders/${id}`,
-    method: 'put',
-    data
-  });
-}
-export function deleteOrder(id) {
-  return request({
-    url: `/api/v1/purchase-orders/${id}`,
-    method: 'delete'
-  });
-}
-```
----
-## 4. 状态管理（Pinia）
-### 4.1 用户状态
-```javascript
-// src/store/user.js
-import { defineStore } from 'pinia';
-import { getToken, setToken, removeToken } from '@/utils/auth';
-export const useUserStore = defineStore('user', {
-  state: () => ({
-    token: getToken(),
-    userInfo: null
-  }),
-  actions: {
-    async login(credentials) {
-      const data = await loginApi(credentials);
-      this.token = data.token;
-      this.userInfo = data.userInfo;
-      setToken(data.token);
-    },
-    async fetchUserInfo() {
-      this.userInfo = await getUserInfoApi();
-    },
-    logout() {
-      this.token = '';
-      this.userInfo = null;
-      removeToken();
-    }
-  }
-});
-```
-### 4.2 使用
-```vue
-<script setup>
-import { useUserStore } from '@/store/user';
-const userStore = useUserStore();
-</script>
-```
----
-## 5. 环境变量
-### 5.1 .env.development
-```
-VITE_API_BASE_URL=http://localhost:8080
-VITE_APP_TITLE=采购订单二开（开发）
-```
-### 5.2 .env.production
-```
-VITE_API_BASE_URL=https://api.example.com
-VITE_APP_TITLE=采购订单二开
-```
-### 5.3 使用
-```javascript
-console.log(import.meta.env.VITE_API_BASE_URL);
-```
----
-## 6. ❌ 反模式
-### 6.1 ❌ URL 包含动词
-```javascript
-// ❌ 错
-url: '/api/getOrders'
-url: '/api/createOrder'
-// ✅ 正确
-url: '/api/v1/orders'
-url: '/api/v1/orders', method: 'post'
-```
-### 6.2 ❌ Token 放在 URL
-```javascript
-// ❌ 错：泄露 + 日志留痕
-url: `/api/orders?token=${token}`
-// ✅ 正确：Header 传
-headers: { Authorization: `Bearer ${token}` }
-```
-### 6.3 ❌ 业务错误用 HTTP 状态码
-```javascript
-// ❌ 错：用 404 表示"业务校验失败"
-if (validationFailed) {
-  return new Response('参数错误', { status: 404 });
-}
-// ✅ 正确：HTTP 200 + 业务 code
-return { code: 400, message: '参数错误' };
-```
----
-## 7. 关联阅读
-- [components.md](components.md) — 平台组件
-- [auth-and-api.md](auth-and-api.md) — 权限与 API
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-frontend-deploy/SKILL.md DELETED Viewed

@@ -1,45 +0,0 @@
----
-name: meritdata-platform-frontend-deploy
-description: |
-  前端部署。构建打包 / Nginx 配置 / CDN / HTTPS / 域名 / 缓存策略 / 灰度发布。
-  触发场景：前端项目上线部署 / 配置 Nginx 反向代理 / 启用 CDN / 配置 HTTPS / 灰度新版本。
-  何时不用：后端部署 → 用 meritdata-platform-backend-deploy；纯本地开发 → 不涉及部署。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: medium
-  layer: L3
-  sub-layer: L3-F
-  stack: frontend
-allowed-tools: Read, Grep, Glob, Bash
----
-# 前端部署（frontend-deploy）
-## 触发
-- 前端项目构建打包（npm run build）
-- 配置 Nginx 反向代理（/api → 后端）
-- 启用 CDN 加速（静态资源）
-- 配置 HTTPS 证书
-- 灰度发布新版本
-- 缓存策略配置（HTML 不缓存 / 静态资源长缓存）
-## 不触发
-- 后端部署 → 用 `meritdata-platform-backend-deploy`
-- CI/CD 流程 → 用 `meritdata-platform-cicd`（如有）
-- 开发环境启动 → 用 npm run dev / vite
-## 前置约束
-- 静态资源**必须**走 CDN
-- API 请求**必须**走 Nginx 反向代理
-- HTML 不缓存，静态资源长缓存
-- HTTPS 全站启用
-## 路由
-- 构建 + Nginx 配置 → [references/guide.md](references/guide.md)
-- CDN + HTTPS + 缓存策略 → [references/cdn-https-cache.md](references/cdn-https-cache.md)
-- 灰度发布 + 回滚 → [references/gray-and-rollback.md](references/gray-and-rollback.md)
-- [SKILL.md](../SKILL.md)