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

package/skills/meritdata-platform-frontend/references/auth-and-api.md

@@ -0,0 +1,300 @@
+# 前端权限与 API 调用（auth-and-api）
+
+> 前端按钮权限 / 路由权限 / 数据权限 + 与后端 API 的调用约定。
+
+---
+
+## 1. 三层权限
+
+| 层级 | 控制内容 | 实现 |
+|------|---------|------|
+| 路由权限 | 哪些页面可访问 | 路由守卫 + meta.permission |
+| 按钮权限 | 页面内哪些按钮可见 | `v-permission` 指令 |
+| 数据权限 | 列表/详情看到哪些数据 | 后端控制，前端按权限过滤展示 |
+
+---
+
+## 2. 路由权限
+
+### 2.1 路由 meta 配置
+
+```javascript
+const routes = [
+  {
+    path: '/orders',
+    component: () => import('@/views/order/List.vue'),
+    meta: {
+      requiresAuth: true,
+      permission: 'purchase_order:view'
+    }
+  }
+];
+```
+
+### 2.2 全局路由守卫
+
+```javascript
+// src/router/index.js
+import { useUserStore } from '@/store/user';
+import { hasPermission } from '@/utils/permission';
+
+router.beforeEach(async (to, from, next) => {
+  const userStore = useUserStore();
+
+  // 1. 不需要登录
+  if (!to.meta.requiresAuth) {
+    return next();
+  }
+
+  // 2. 未登录跳转登录
+  if (!userStore.token) {
+    return next('/login');
+  }
+
+  // 3. 已登录但没加载用户信息
+  if (!userStore.userInfo) {
+    await userStore.fetchUserInfo();
+    await userStore.fetchPermissions();
+  }
+
+  // 4. 校验权限
+  if (to.meta.permission && !hasPermission(to.meta.permission)) {
+    ElMessage.error('无访问权限');
+    return next('/403');
+  }
+
+  next();
+});
+```
+
+---
+
+## 3. 按钮权限
+
+### 3.1 v-permission 指令
+
+```vue
+<template>
+  <el-button v-permission="'purchase_order:create'" @click="handleCreate">
+    新建采购订单
+  </el-button>
+
+  <el-button v-permission="'purchase_order:delete'" @click="handleDelete">
+    删除
+  </el-button>
+</template>
+
+<script setup>
+// 全局注册（在 main.js）
+app.directive('permission', {
+  mounted(el, binding) {
+    const required = binding.value;
+    const userStore = useUserStore();
+    if (!userStore.permissions.includes(required)) {
+      el.parentNode && el.parentNode.removeChild(el);
+    }
+  }
+});
+</script>
+```
+
+### 3.2 ❌ 反例：前端写死角色
+
+```vue
+<!-- ❌ 错：写死角色 -->
+<el-button v-if="userStore.userInfo.role === 'admin'">
+  删除
+</el-button>
+
+<!-- ✅ 正确：用权限点 -->
+<el-button v-permission="'purchase_order:delete'">
+  删除
+</el-button>
+```
+
+---
+
+## 4. 数据权限
+
+### 4.1 原则
+
+**前端不控制数据权限，只控制展示**。
+
+```vue
+<!-- ✅ 正确：调后端 API，由后端按用户权限过滤 -->
+<template>
+  <el-table :data="orderList">
+    <el-table-column prop="orderNo" label="订单号" />
+    <el-table-column prop="amount" label="金额" />
+    <!-- 列表内容由后端按当前用户权限过滤后返回 -->
+  </el-table>
+</template>
+```
+
+### 4.2 ❌ 反例：前端过滤敏感字段
+
+```vue
+<!-- ❌ 错：前端隐藏字段 -->
+<el-table :data="orderList">
+  <el-table-column v-if="canSeeAmount" prop="amount" label="金额" />
+</el-table>
+
+<!-- 攻击者可以直接调 API 拿到 amount -->
+```
+
+---
+
+## 5. API 调用约定
+
+### 5.1 URL 规范
+
+```
+GET    /api/v1/purchase-orders           列表
+GET    /api/v1/purchase-orders/{id}      详情
+POST   /api/v1/purchase-orders           创建
+PUT    /api/v1/purchase-orders/{id}      更新
+DELETE /api/v1/purchase-orders/{id}      删除
+POST   /api/v1/purchase-orders/{id}/submit  自定义动作
+```
+
+详见 [rules/api-design-rules.md](../../rules/api-design-rules.md)。
+
+### 5.2 请求 / 响应格式
+
+**请求**：
+
+```json
+POST /api/v1/purchase-orders
+Content-Type: application/json
+Authorization: Bearer eyJhbGc...
+
+{
+  "orderNo": "PO20260907001",
+  "applicantUserId": "10001",
+  "items": [...]
+}
+```
+
+**响应**：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 12345,
+    "orderNo": "PO20260907001",
+    "status": "DRAFT"
+  },
+  "message": "success"
+}
+```
+
+### 5.3 错误处理
+
+| HTTP | code | 含义 | 前端处理 |
+|------|------|------|---------|
+| 200 | 400 | 业务校验失败 | ElMessage.error(message) |
+| 200 | 401 | 未登录 | 跳转登录 |
+| 200 | 403 | 无权限 | ElMessage.error("无权限") |
+| 401 | - | Token 过期 | 清 token + 跳转登录 |
+| 500 | - | 服务器错误 | ElMessage.error("服务异常") |
+
+---
+
+## 6. Token 管理
+
+### 6.1 存储
+
+```javascript
+// src/utils/auth.js
+const TOKEN_KEY = 'meritdata_token';
+
+export function getToken() {
+  return localStorage.getItem(TOKEN_KEY);
+}
+
+export function setToken(token) {
+  localStorage.setItem(TOKEN_KEY, token);
+}
+
+export function removeToken() {
+  localStorage.removeItem(TOKEN_KEY);
+}
+```
+
+### 6.2 ❌ 反例
+
+- ❌ Token 存 cookie（无 httpOnly → XSS 可盗）
+- ❌ Token 存 sessionStorage（关闭浏览器就丢）
+- ❌ Token 明文存 localStorage + 无加密（高风险场景）
+
+**生产环境建议**：Token 存 httpOnly cookie + 前端用 Refresh Token 机制。
+
+### 6.3 Token 刷新
+
+```javascript
+// request.js 响应拦截器
+request.interceptors.response.use(
+  response => response.data,
+  async error => {
+    const originalRequest = error.config;
+
+    // 401 + 不是刷新接口 + 没重试过
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      originalRequest._retry = true;
+
+      try {
+        const newToken = await refreshTokenApi();
+        setToken(newToken);
+        originalRequest.headers['Authorization'] = `Bearer ${newToken}`;
+        return request(originalRequest);  // 重试原请求
+      } catch (refreshError) {
+        removeToken();
+        window.location.href = '/login';
+        return Promise.reject(refreshError);
+      }
+    }
+
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## 7. 表单提交约定
+
+### 7.1 提交前校验
+
+```vue
+<template>
+  <el-form :model="form" :rules="rules" ref="formRef">
+    <el-form-item label="订单号" prop="orderNo">
+      <el-input v-model="form.orderNo" />
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+const rules = {
+  orderNo: [
+    { required: true, message: '请输入订单号', trigger: 'blur' },
+    { min: 5, max: 64, message: '长度 5-64', trigger: 'blur' }
+  ]
+};
+</script>
+```
+
+### 7.2 ❌ 反例：仅前端校验
+
+前端校验**仅用于 UX**，**不能作为安全屏障**。后端必须再次校验。
+
+---
+
+## 8. 关联阅读
+
+- [components.md](components.md) — 平台组件
+- [project-structure.md](project-structure.md) — 工程结构
+- [rules/api-design-rules.md](../../rules/api-design-rules.md) — API 设计
+- [rules/security-rules.md](../../rules/security-rules.md) — 安全规范
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-frontend/references/components.md

@@ -0,0 +1,284 @@
+# 平台前端组件清单（components）
+
+> 平台提供的 Vue/React 组件，按需引入，不全量打包。
+
+---
+
+## 1. 选择类组件
+
+### 1.1 人员选择（UserSelector）
+
+```vue
+<template>
+  <UserSelector
+    v-model="selectedUserIds"
+    :multiple="true"
+    :show-org="true"
+    @change="handleChange"
+  />
+</template>
+
+<script setup>
+import { UserSelector } from '@meritdata/platform-ui';
+
+const selectedUserIds = ref([]);
+function handleChange(users) {
+  console.log('已选用户：', users);
+  // users: [{ id, name, orgName, ... }]
+}
+</script>
+```
+
+**Props**：
+
+| prop | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `v-model` | `string[]` | - | 选中用户 ID 列表 |
+| `multiple` | `boolean` | `false` | 是否多选 |
+| `showOrg` | `boolean` | `true` | 是否显示组织信息 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `placeholder` | `string` | `"请选择人员"` | 占位文本 |
+
+---
+
+### 1.2 组织树选择（OrgTreeSelector）
+
+```vue
+<template>
+  <OrgTreeSelector
+    v-model="selectedOrgId"
+    :multiple="false"
+    :show-root="true"
+  />
+</template>
+
+<script setup>
+import { OrgTreeSelector } from '@meritdata/platform-ui';
+const selectedOrgId = ref('');
+</script>
+```
+
+---
+
+### 1.3 部门选择（DeptSelector）
+
+```vue
+<template>
+  <DeptSelector
+    v-model="selectedDeptIds"
+    :org-id="currentOrgId"
+    :multiple="true"
+  />
+</template>
+```
+
+---
+
+### 1.4 角色选择（RoleSelector）
+
+```vue
+<template>
+  <RoleSelector
+    v-model="selectedRoleCodes"
+    :org-id="currentOrgId"
+  />
+</template>
+```
+
+---
+
+### 1.5 字典下拉（LookupSelect）
+
+```vue
+<template>
+  <LookupSelect
+    v-model="status"
+    lookup-type="ORDER_STATUS"
+    placeholder="请选择状态"
+  />
+</template>
+
+<script setup>
+import { LookupSelect } from '@meritdata/platform-ui';
+const status = ref('');
+</script>
+```
+
+**Props**：
+
+| prop | 类型 | 说明 |
+|------|------|------|
+| `lookup-type` | `string` | 字典类型 code |
+| `v-model` | `string` | 选中 code（不是 name）|
+
+---
+
+## 2. 表单类组件
+
+### 2.1 资源选择（ResourceSelector）
+
+```vue
+<template>
+  <ResourceSelector
+    v-model="selectedResourceIds"
+    resource-type="MENU"
+    :multiple="true"
+  />
+</template>
+```
+
+### 2.2 文件上传（FileUpload）
+
+```vue
+<template>
+  <FileUpload
+    v-model="fileIds"
+    biz-type="PURCHASE_ORDER_CONTRACT"
+    :biz-id="orderId"
+    :max-size="50"
+    :accept="['.pdf', '.docx']"
+  />
+</template>
+```
+
+### 2.3 富文本编辑器（RichEditor）
+
+```vue
+<template>
+  <RichEditor
+    v-model="content"
+    :height="300"
+    :toolbar="['bold', 'italic', 'link', 'image']"
+  />
+</template>
+```
+
+---
+
+## 3. 展示类组件
+
+### 3.1 审批流图（ProcessViewer）
+
+```vue
+<template>
+  <ProcessViewer
+    :process-instance-id="processInstanceId"
+    :highlight-task-id="currentTaskId"
+  />
+</template>
+```
+
+### 3.2 操作日志（OperationLogList）
+
+```vue
+<template>
+  <OperationLogList
+    :biz-id="orderId"
+    :biz-type="'PURCHASE_ORDER'"
+  />
+</template>
+```
+
+### 3.3 用户头像（UserAvatar）
+
+```vue
+<template>
+  <UserAvatar :user-id="userId" :size="32" />
+</template>
+```
+
+---
+
+## 4. 业务组件
+
+### 4.1 通用列表页（ListPage）
+
+```vue
+<template>
+  <ListPage
+    :query="query"
+    :fetch="fetchList"
+    :columns="columns"
+  >
+    <template #toolbar>
+      <el-button @click="handleCreate">新建</el-button>
+    </template>
+  </ListPage>
+</template>
+
+<script setup>
+import { ListPage } from '@meritdata/platform-ui';
+
+const query = ref({ keyword: '', status: '' });
+const columns = [
+  { prop: 'orderNo', label: '订单号', width: 180 },
+  { prop: 'applicantName', label: '申请人', width: 120 },
+  { prop: 'statusName', label: '状态', width: 100 },
+  { prop: 'createTime', label: '创建时间', width: 180 }
+];
+</script>
+```
+
+### 4.2 通用详情页（DetailPage）
+
+```vue
+<template>
+  <DetailPage :data="detail" :fields="fields" />
+</template>
+
+<script setup>
+import { DetailPage } from '@meritdata/platform-ui';
+
+const fields = [
+  { prop: 'orderNo', label: '订单号' },
+  { prop: 'applicantName', label: '申请人' },
+  { prop: 'statusName', label: '状态' }
+];
+</script>
+```
+
+---
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 全量引入组件库
+
+```javascript
+// ❌ 错：打包体积大
+import * as PlatformUI from '@meritdata/platform-ui';
+app.use(PlatformUI);
+
+// ✅ 正确：按需引入
+import { UserSelector, LookupSelect } from '@meritdata/platform-ui';
+```
+
+### 5.2 ❌ 自己实现选择弹框
+
+```vue
+<!-- ❌ 错：自己写弹框 + 树形 + 搜索 -->
+<el-dialog v-model="visible">
+  <el-tree :data="orgTree" />
+  <el-input v-model="keyword" />
+  ...
+</el-dialog>
+```
+
+✅ 用 `UserSelector` / `OrgTreeSelector`，平台组件已经处理了搜索/分页/权限。
+
+### 5.3 ❌ 字典 value 用 name
+
+```vue
+<!-- ❌ 错：value 存中文 -->
+<LookupSelect v-model="statusName" />  <!-- "审批中" -->
+
+<!-- ✅ 正确：value 存 code -->
+<LookupSelect v-model="status" lookup-type="ORDER_STATUS" />  <!-- "PENDING" -->
+```
+
+---
+
+## 6. 关联阅读
+
+- [project-structure.md](project-structure.md) — 工程结构
+- [auth-and-api.md](auth-and-api.md) — 权限与 API 调用
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,85 @@
+# 前端多服务 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/`