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

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

@@ -0,0 +1,318 @@
+# 前端工程结构（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

@@ -0,0 +1,45 @@
+---
+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)

package/skills/meritdata-platform-frontend-deploy/references/cdn-https-cache.md

@@ -0,0 +1,222 @@
+# CDN + HTTPS + 缓存策略（frontend-deploy）
+
+> CDN 加速 / HTTPS 配置 / 多级缓存。
+
+---
+
+## 1. CDN 配置
+
+### 1.1 阿里云 / 腾讯云 CDN
+
+源站：你的服务器 / OSS bucket。
+
+加速域名：`cdn.example.com`（CNAME 到 CDN）。
+
+### 1.2 缓存规则
+
+```
+/assets/*           → 缓存 365 天（hash 文件名）
+/assets/index.html  → 不缓存
+/api/*              → 不缓存（动态）
+*.html              → 不缓存
+*.js, *.css, *.png  → 缓存 30 天
+```
+
+### 1.3 回源策略
+
+```
+用户请求 → CDN 节点
+   ↓ miss
+CDN 回源服务器
+   ↓
+缓存到 CDN
+   ↓
+返回用户
+```
+
+### 1.4 HTTPS on CDN
+
+- CDN 支持 HTTPS 回源
+- 客户端 → CDN：HTTPS（CDN 证书）
+- CDN → 源站：HTTP / HTTPS（可选）
+
+## 2. 缓存策略
+
+### 2.1 文件名 hash + 长缓存
+
+```
+dist/
+├── index.html              ← 不缓存
+└── assets/
+    ├── js/
+    │   ├── main.abc123.js  ← 缓存 1 年（hash 文件名）
+    │   └── vendor.def456.js
+    └── css/
+        └── main.abc123.css
+```
+
+文件 hash 变了 → 新 URL → 用户拉新文件。
+
+### 2.2 配置（Nginx）
+
+```nginx
+# HTML 不缓存
+location = /index.html {
+    add_header Cache-Control "no-cache, no-store, must-revalidate";
+    expires 0;
+}
+
+# 静态资源长缓存
+location ~* \.(js|css|png|jpg|svg|woff2)$ {
+    expires 1y;
+    add_header Cache-Control "public, immutable";
+}
+```
+
+### 2.3 配置（CDN）
+
+在 CDN 控制台配置缓存规则：
+
+```
+/index.html              0 秒（不缓存）
+/assets/*.js             365 天
+/assets/*.css            365 天
+/assets/*.png            365 天
+/api/*                   0 秒（不缓存）
+```
+
+## 3. HTTPS 全面启用
+
+### 3.1 证书获取
+
+- Let's Encrypt（免费，90 天续期）
+- 阿里云 / 腾讯云 SSL 证书（付费）
+- 自签名（仅内部使用）
+
+### 3.2 Nginx 配置
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name app.example.com;
+
+    ssl_certificate     /etc/nginx/ssl/app.crt;
+    ssl_certificate_key /etc/nginx/ssl/app.key;
+
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
+    ssl_prefer_server_ciphers on;
+
+    ssl_session_cache   shared:SSL:10m;
+    ssl_session_timeout 1d;
+    ssl_session_tickets off;
+
+    # HSTS
+    add_header Strict-Transport-Security "max-age=63072000" always;
+}
+```
+
+### 3.3 强制 HTTPS
+
+```nginx
+server {
+    listen 80;
+    server_name app.example.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+### 3.4 HSTS Preload
+
+将域名加入 HSTS Preload List → 浏览器硬编码强制 HTTPS。
+
+## 4. 多级缓存
+
+### 4.1 浏览器缓存
+
+```
+强缓存（Cache-Control / Expires）→ 不发请求
+   ↓ 失效
+协商缓存（ETag / Last-Modified）→ 304 Not Modified
+   ↓ 不匹配
+服务器返回新内容
+```
+
+### 4.2 CDN 缓存
+
+CDN 节点缓存静态资源。
+
+### 4.3 Nginx 缓存
+
+```nginx
+proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app_cache:10m;
+
+location /api/static/ {
+    proxy_cache app_cache;
+    proxy_cache_valid 200 5m;
+    proxy_pass http://backend;
+}
+```
+
+## 5. 缓存失效
+
+### 5.1 主动刷新（CDN）
+
+```bash
+# 阿里云
+aliyun cdn RefreshObjectCaches --ObjectPath https://app.example.com/index.html
+
+# 腾讯云
+tccli cdn PurgePathCache --Paths https://app.example.com/index.html
+```
+
+### 5.2 主动刷新（业务触发）
+
+```typescript
+// 部署完成 → 调用 CDN 刷新接口
+await fetch('https://cdn-api.example.com/refresh', {
+  method: 'POST',
+  body: JSON.stringify({ url: 'https://app.example.com/index.html' })
+});
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ HTML 缓存
+
+```nginx
+# ❌ 错：HTML 缓存 1 天
+location / {
+    expires 1d;
+}
+```
+
+✅ HTML 不缓存。
+
+### 6.2 ❌ 静态资源短期缓存
+
+```nginx
+# ❌ 错
+location ~* \.js$ {
+    expires 1h;  # 用户每小时重新下载
+}
+```
+
+✅ hash 文件名 + 1 年。
+
+### 6.3 ❌ 混合 HTTP / HTTPS
+
+```nginx
+# ❌ 错：HTTP 也开放
+server {
+    listen 80;  # 没强制跳转
+}
+```
+
+✅ 80 → 443 重定向。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 前端部署基础
+- [gray-and-rollback.md](gray-and-rollback.md) — 灰度 + 回滚
+- [SKILL.md](../SKILL.md)