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

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

@@ -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

@@ -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

@@ -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)