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

package/skills/meritdata-platform-frontend-deploy/references/gray-and-rollback.md

@@ -0,0 +1,236 @@
+# 灰度发布与回滚（frontend-deploy）
+
+> 灰度策略 / 版本回滚 / 蓝绿部署。
+
+---
+
+## 1. 灰度发布策略
+
+### 1.1 用户灰度
+
+按用户 ID / 租户 ID 取模：
+
+```
+userId % 100 < 10  → 新版本
+其他                → 旧版本
+```
+
+### 1.2 地域灰度
+
+按 IP 地域：
+
+```
+华北 → 旧版本
+华东 → 新版本
+```
+
+### 1.3 浏览器灰度
+
+按 User-Agent / Cookie：
+
+```
+Chrome + cookie=beta → 新版本
+其他                  → 旧版本
+```
+
+## 2. 实现方案
+
+### 2.1 方案 1：双版本目录
+
+```nginx
+server {
+    listen 80;
+    server_name app.example.com;
+
+    # 旧版本
+    location /v1/ {
+        alias /var/www/app/v1.0.0/;
+        try_files $uri $uri/ /v1/index.html;
+    }
+
+    # 新版本
+    location /v2/ {
+        alias /var/www/app/v2.0.0/;
+        try_files $uri $uri/ /v2/index.html;
+    }
+
+    # 灰度路由
+    location / {
+        set $version 'v1';
+        if ($http_cookie ~* "beta=true") {
+            set $version 'v2';
+        }
+        # 按 IP hash
+        if ($remote_addr ~ "^192\.168\.1\.") {
+            set $version 'v2';
+        }
+        return 302 /$version$request_uri;
+    }
+}
+```
+
+### 2.2 方案 2：路径分流（CDN）
+
+CDN 配置：
+
+```
+/v1/*  → 旧版本 bucket
+/v2/*  → 新版本 bucket
+```
+
+前端按用户分流到 /v1 或 /v2。
+
+### 2.3 方案 3：前端判断
+
+```typescript
+// 前端代码
+async function getVersion() {
+  const userId = getCurrentUserId();
+  if (userId % 100 < 10) {
+    return 'v2';
+  }
+  return 'v1';
+}
+
+// 根据版本加载不同资源
+const manifest = await import(`/manifest-${version}.json`);
+```
+
+## 3. 蓝绿部署
+
+### 3.1 流程
+
+```
+蓝色（当前版本）  ← 100% 流量
+绿色（新版本）    ← 0% 流量
+   ↓ 切换
+蓝色               ← 0% 流量
+绿色               ← 100% 流量
+   ↓ 出问题
+蓝色               ← 100% 流量（回滚）
+```
+
+### 3.2 Nginx 配置
+
+```nginx
+upstream blue {
+    server blue-1.example.com;
+    server blue-2.example.com;
+}
+
+upstream green {
+    server green-1.example.com;
+    server green-2.example.com;
+}
+
+server {
+    listen 80;
+    server_name app.example.com;
+
+    # 默认 blue
+    location / {
+        proxy_pass http://blue;
+    }
+
+    # 灰度切到 green
+    # proxy_pass http://green;
+}
+```
+
+切换 → 改一行配置 → nginx reload。
+
+## 4. 版本回滚
+
+### 4.1 保留历史版本
+
+```bash
+/var/www/app/
+├── v1.0.0/
+├── v1.1.0/
+├── v1.2.0/  ← 当前
+└── v1.3.0/  ← 新版本（出问题）
+```
+
+### 4.2 一键回滚脚本
+
+```bash
+#!/bin/bash
+# rollback.sh
+CURRENT=$(readlink /var/www/app/current)
+PREVIOUS=$(ls -t /var/www/app/ | grep -E '^v[0-9]+\.' | sed -n '2p')
+
+echo "Rollback from $CURRENT to $PREVIOUS"
+
+rm /var/www/app/current
+ln -s /var/www/app/$PREVIOUS /var/www/app/current
+
+nginx -s reload
+echo "Rollback complete"
+```
+
+### 4.3 数据库版本兼容
+
+⚠️ **前端回滚 ≠ 数据库回滚**
+
+数据库变更要兼容旧版本：
+
+```sql
+-- 加列要 nullable
+ALTER TABLE t_order ADD COLUMN new_field VARCHAR(50) NULL;
+```
+
+新版本用新字段；旧版本忽略新字段（不报错）。
+
+## 5. 监控与告警
+
+### 5.1 灰度监控
+
+```yaml
+# Prometheus 指标
+http_requests_total{version="v1", status="200"}  1000
+http_requests_total{version="v2", status="200"}  50     # 灰度中
+http_requests_total{version="v2", status="500"}  10     # 错误率 20%
+```
+
+### 5.2 告警阈值
+
+```yaml
+# 灰度 v2 错误率 > 5% → 自动回滚
+- alert: GrayVersionHighErrorRate
+  condition: rate(http_requests_total{version="v2", status="500"}[5m]) > 0.05
+  action: rollback_to_v1
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 全量上线
+
+```bash
+# ❌ 错：直接全量推 → 出问题全部用户受影响
+rsync dist/ user@app:/var/www/app/
+```
+
+✅ 先灰度 5% → 监控 → 推全。
+
+### 6.2 ❌ 无回滚预案
+
+```bash
+# ❌ 错：上线后没准备回滚方案
+```
+
+✅ 保留历史版本 + 回滚脚本 + 数据库兼容。
+
+### 6.3 ❌ 数据库变更与版本不兼容
+
+```sql
+-- ❌ 错：新版本加非空列，旧版本报错
+ALTER TABLE t_order ADD COLUMN new_field INT NOT NULL;
+```
+
+✅ 加 nullable，或拆多次上线。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 前端部署基础
+- [cdn-https-cache.md](cdn-https-cache.md) — CDN + HTTPS + 缓存
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-frontend-deploy/references/guide.md

@@ -0,0 +1,199 @@
+# 前端部署基础指南（frontend-deploy）
+
+> 构建 / Nginx 反向代理 / 静态资源。
+
+---
+
+## 1. 构建
+
+### 1.1 构建命令
+
+```bash
+# Vite
+npm run build
+
+# 产物输出到 dist/
+# - index.html（不缓存）
+# - assets/js/*.js（hash 文件名，长缓存）
+# - assets/css/*.css（hash 文件名，长缓存）
+# - assets/img/*（hash 文件名，长缓存）
+```
+
+### 1.2 环境变量
+
+```bash
+# .env.production
+VITE_API_BASE_URL=https://api.example.com
+VITE_APP_TITLE=MeritData
+VITE_USE_CDN=true
+```
+
+构建时注入到 bundle。
+
+### 1.3 构建优化
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'react-vendor': ['react', 'react-dom'],
+          'antd-vendor': ['antd'],
+          'platform-vendor': ['@meritdata/platform-ui-components'],
+        },
+      },
+    },
+    chunkSizeWarningLimit: 1500,
+  },
+});
+```
+
+分包 → 首屏加载更快。
+
+## 2. Nginx 配置
+
+### 2.1 基础配置
+
+```nginx
+server {
+    listen 80;
+    server_name app.example.com;
+
+    root /var/www/app/dist;
+    index index.html;
+
+    # SPA fallback（所有路径回 index.html）
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API 反向代理
+    location /api/ {
+        proxy_pass http://backend.example.com/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_connect_timeout 30s;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 60s;
+    }
+
+    # 静态资源（长缓存）
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        access_log off;
+    }
+
+    # HTML 不缓存
+    location = /index.html {
+        add_header Cache-Control "no-cache, no-store, must-revalidate";
+        expires 0;
+    }
+}
+```
+
+### 2.2 Gzip / Brotli
+
+```nginx
+gzip on;
+gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
+gzip_min_length 1000;
+
+# Brotli（需编译 brotli 模块）
+brotli on;
+brotli_types text/plain text/css application/json application/javascript;
+```
+
+### 2.3 HTTPS
+
+```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         HIGH:!aNULL:!MD5;
+
+    # 其他配置同 80 端口
+}
+
+# 80 → 443 重定向
+server {
+    listen 80;
+    server_name app.example.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+## 3. 部署流程
+
+```bash
+# 1. 构建
+npm run build
+
+# 2. 上传到服务器
+rsync -avz dist/ user@app.example.com:/var/www/app/dist/
+
+# 3. Nginx 重新加载（无需重启）
+ssh user@app.example.com 'nginx -s reload'
+
+# 或用 docker
+docker build -t app:v1.2.3 .
+docker push registry.example.com/app:v1.2.3
+```
+
+## 4. ❌ 反模式
+
+### 4.1 ❌ HTML 缓存
+
+```nginx
+# ❌ 错
+location / {
+    expires 1d;  # HTML 也缓存 → 部署新版本用户看不到
+}
+```
+
+✅ HTML 不缓存，静态资源长缓存。
+
+### 4.2 ❌ 静态资源不缓存
+
+```nginx
+# ❌ 错
+location /assets/ {
+    expires off;  # 每次都重新下载
+}
+```
+
+✅ 长缓存 + immutable。
+
+### 4.3 ❌ 反向代理超时太短
+
+```nginx
+# ❌ 错
+proxy_read_timeout 5s;  # 慢请求直接断
+```
+
+✅ 60s + 业务超时控制。
+
+### 4.4 ❌ API 跨域硬编码
+
+```javascript
+// ❌ 错
+fetch('http://backend.example.com/api/orders')
+// → 跨域
+```
+
+✅ Nginx 反向代理，前端同源。
+
+## 5. 关联阅读
+
+- [cdn-https-cache.md](cdn-https-cache.md) — CDN + HTTPS + 缓存
+- [gray-and-rollback.md](gray-and-rollback.md) — 灰度 + 回滚
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-impexp/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: meritdata-platform-impexp
+description: |
+  导入导出（Excel/CSV）。模板设计、EasyExcel 集成、导入校验、异步处理、大文件分片、错误行收集、模板下载。
+  触发场景：业务模块需要 Excel 导入（批量录入）；Excel 导出（报表）；模板下载。
+  何时不用：纯展示 → 用 frontend；文件存储 → L3 平台上传（待建）。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: medium
+  layer: L2
+  sub-layer: L2-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 导入导出（impexp）
+
+## 触发
+- 业务模块需要 Excel 导入（批量录入/初始化）
+- 业务模块需要 Excel 导出（报表/对账）
+- 需要模板下载（导入模板/导出模板）
+- 大文件异步处理
+
+## 不触发
+- 纯展示（前端直接渲染）→ 用 `meritdata-platform-frontend`
+- 文件存储/上传（附件）→ L3 平台上传（待建）
+- 单条数据录入 → 纯表单
+
+## 前置约束
+- 大文件（>10MB）必须**异步处理**，禁止同步阻塞
+- 导入校验失败必须**收集错误行**，不能直接中断
+- 导入走平台公共校验，**不重复实现**校验逻辑
+
+## 路由
+- EasyExcel 接入 + 模板设计 → [references/excel-guide.md](references/excel-guide.md)
+- 异步处理 + 错误行收集 → [references/async-and-validate.md](references/async-and-validate.md)
+- 典型场景（人员导入/订单导出） → [references/scenarios.md](references/scenarios.md)