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

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

@@ -0,0 +1,176 @@
+## 概述
+
+所有工具函数位于 `cloud-module/cloud-module-base/static/js/utils/`，通过 npm 包 `cloud-module-base` 引入。
+
+---
+
+## 工具速查表
+
+| 模块 | 分类 | 场景 |
+|------|------|------|
+| dataFormat.js | 数据格式化 | 日期对象 → 格式化字符串 |
+| form-rules.js | 表单校验 | 12 种正则校验规则（必填/手机/邮箱/身份证/URL/IP 等） |
+| globalValitor.js | 表单校验 | 全局自定义校验器 |
+| preventReClick.js | 安全生产 | 防重复点击，3 秒内禁用 |
+| sm2.js | 加解密 | SM2 非对称加密/解密/签名/验签 |
+| sm4-utils.js | 加解密 | SM4 对称加密/解密 |
+| accessLogs.js | 访问日志 | 页面访问审计记录 |
+
+---
+
+## 1. dataFormat.js — 日期格式化
+
+**导入**: `import dateFormat from 'cloud-module-base/static/js/utils/dataFormat.js'`
+
+### 方法
+
+`formatter(value)` — 将 Date 对象或日期字符串格式化为 `yyyy-MM-dd hh:mm`
+
+```javascript
+import dateFormat from 'cloud-module-base/static/js/utils/dataFormat.js';
+
+// 模板中使用
+<span>{{ dateFormat(row.createTime) }}</span>
+
+// 示例输出
+dateFormat(new Date())       // '2026-04-30 10:30'
+dateFormat('2026-04-30')    // '2026-04-30 00:00'
+```
+
+---
+
+## 2. form-rules.js — 表单校验规则
+
+**导入**: `import FormRules from 'cloud-module-base/static/js/utils/form-rules'`
+
+### 12 种校验规则
+
+| 规则 | 正则 | 错误提示 |
+|------|------|----------|
+| `FormRules.required` | `/^[^\s]*$/` | 不允许输入空格 |
+| `FormRules.nospecial` | `/^[a-zA-Z0-9_]+$/` | 只允许英文字符或数字或_ |
+| `FormRules.noSpecialCode` | `/^[一-龥A-Za-z0-9_]+$/` | 不允许输入特殊字符 |
+| `FormRules.name` | `/^[a-zA-Z0-9\-_一-龥]*$/` | 仅支持数值、中文、英文、下划线、横线 |
+| `FormRules.cellphone` | `/^1[0-9]{10}$/` | 请输入正确的手机号码 |
+| `FormRules.telephone` | `/^[0-9]{3,4}-[0-9]{7,8}$/` | 请输入正确的电话号码 |
+| `FormRules.email` | 标准 Email 正则 | 请输入有效的电子邮件地址 |
+| `FormRules.idcard` | 18 位身份证正则 | 请输入有效的身份证号码 |
+| `FormRules.url` | 标准 URL 正则 | 请输入有效的 URL 地址 |
+| `FormRules.ip` | IPv4 正则 | 请输入有效的 IP 地址 |
+| `FormRules.mac` | MAC 地址正则 | 请输入有效的 MAC 地址 |
+
+### 使用方式（标准写法）
+
+```javascript
+import formRules from 'cloud-module-base/static/js/utils/form-rules';
+
+// el-form rules 中使用
+rules: {
+  code: [
+    { required: true, message: '编码不能为空', trigger: 'blur' },
+    {
+      pattern: formRules.nospecial.pattern,   // 正则
+      message: formRules.nospecial.message,   // 提示
+      trigger: 'blur'
+    }
+  ],
+  name: [
+    { required: true, message: '名称不能为空', trigger: 'blur' },
+    {
+      pattern: formRules.name.pattern,
+      message: formRules.name.message,
+      trigger: 'blur'
+    }
+  ],
+  phone: [
+    { required: true, message: '手机号不能为空', trigger: 'blur' },
+    {
+      pattern: formRules.cellphone.pattern,
+      message: formRules.cellphone.message,
+      trigger: 'blur'
+    }
+  ]
+}
+```
+
+---
+
+## 3. globalValitor.js — 全局校验器
+
+**导入**: `import globalValitor from 'cloud-module-base/static/js/utils/globalValitor'`
+
+自定义全局校验器，用于补充 form-rules.js 之外的校验场景。
+
+---
+
+## 4. preventReClick.js — 防重复点击指令
+
+**导入**: `import { preventReClick } from 'cloud-module-base/static/js/utils/preventReClick'`
+
+Vue 指令，点击后禁用按钮，默认 3 秒后恢复。
+
+### 注册
+
+```javascript
+import { preventReClick } from 'cloud-module-base/static/js/utils/preventReClick';
+Vue.directive('preventReClick', preventReClick);
+```
+
+### 使用
+
+```vue
+<!-- 默认 3 秒防重复 -->
+<el-button @click="submitForm" v-prevent-re-click>提交</el-button>
+
+<!-- 自定义 1 秒 -->
+<el-button @click="submitForm" v-prevent-re-click="1000">快速提交</el-button>
+
+<!-- 配合 disabled 状态 -->
+<el-button type="primary" :disabled="submitting" v-prevent-re-click="2000">
+  {{ submitting ? '提交中...' : '提交' }}
+</el-button>
+```
+
+---
+
+## 5. SM2/SM4 工具
+
+可用模块为 `sm2.js` 和 `sm4-utils.js`。已知 API 名包括 `generateKeyPairHex`、`doEncrypt`、`doDecrypt`、`doSignature`、`doVerifySignature`、`getPublicKeyFromPrivateKey`、`encrypt` 和 `decrypt`。
+
+登录或认证场景必须复用目标项目的既有前后端协议，并从已安装模块版本核对参数和返回值。不要在页面中拼装 SM2/SM4 登录协议、生成或持久化登录密钥，也不要把加密结果命名为私钥。
+
+---
+
+## 7. accessLogs.js — 访问日志记录
+
+**导入**: `import saveAcessLog from 'cloud-module-base/static/js/utils/accessLogs'`
+
+### 方法
+
+`saveAcessLog(bmodule, fmodule)` — 记录用户访问日志
+
+| 参数 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| bmodule | String | 业务模块 | '基础数据'、'在线管理'、'组织机构' |
+| fmodule | String | 功能模块 | '系统日志'、'用户在线时长'、'用户维护' |
+
+### 使用方式
+
+```javascript
+import saveAcessLog from 'cloud-module-base/static/js/utils/accessLogs';
+
+export default {
+  created() {
+    saveAcessLog('基础数据', '系统日志');  // 页面创建时记录
+  }
+};
+```
+
+---
+
+## 工具函数注意事项
+
+1. 所有工具函数通过 npm 包 `cloud-module-base` 引入，确保已安装依赖
+2. `preventReClick` 是 Vue 指令，需通过 `Vue.directive()` 或 `Vue.use()` 注册后使用
+3. 使用 SM2/SM4 前先核对目标项目的认证协议和已安装模块版本，不要以本参考推导登录报文。
+4. `form-rules.js` 中的 `pattern` 和 `message` 需分别取出，不可直接赋值给 rules

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

@@ -1,41 +1,76 @@
 ---
 name: meritdata-platform-impexp
-description: |
-  导入导出（Excel/CSV）。模板设计、EasyExcel 集成、导入校验、异步处理、大文件分片、错误行收集、模板下载。
-  触发场景：业务模块需要 Excel 导入（批量录入）；Excel 导出（报表）；模板下载。
-  何时不用：纯展示 → 用 frontend；文件存储 → L3 平台上传（待建）。
+description: Meritdata Cloud 数据 IO 能力入口，专注于 Excel 导入导出、文件附件、模板、校验、批量保存等场景。
 metadata:
   version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
   risk: medium
-  layer: L2
-  sub-layer: L2-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
+  allowed-tools: Read, Grep, Glob
 ---
 
-# 导入导出（impexp）
+## ⭐ MUST DO
 
-## 触发
-- 业务模块需要 Excel 导入（批量录入/初始化）
-- 业务模块需要 Excel 导出（报表/对账）
-- 需要模板下载（导入模板/导出模板）
-- 大文件异步处理
+**导入导出复用平台已验证框架与响应头，敏感字段日志必须脱敏；批量保存必须事务控制 + 幂等 + 错误明细。**
 
-## 不触发
-- 纯展示（前端直接渲染）→ 用 `meritdata-platform-frontend`
-- 文件存储/上传（附件）→ L3 平台上传（待建）
-- 单条数据录入 → 纯表单
+## 触发条件 / 不适用
 
-## 前置约束
-- 大文件（>10MB）必须**异步处理**，禁止同步阻塞
-- 导入校验失败必须**收集错误行**，不能直接中断
-- 导入走平台公共校验，**不重复实现**校验逻辑
+**适用**：
+- Excel 导入导出
+- 文件上传下载
+- 附件生命周期
+- 导入模板设计
+- 字段校验、错误明细、字典转换
+- 批量保存
 
-## 路由
-- 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)
+**不适用**：
+- 简单数据展示 → `meritdata-platform-frontend`
+- 单条数据保存 → `meritdata-platform-cloud-dev`
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+
+## 工作方式（Step 1/2/3/4）
+
+### Step 1：明确模板列与校验
+
+- 设计 Excel 模板列（字段名、类型、是否必填、字典转换）
+- 明确校验规则（长度、范围、正则）
+- 准备错误明细格式（行号、字段、错误信息）
+
+### Step 2：读取 reference
+
+按主题路由读取对应 md 文件。
+
+### Step 3：实现
+
+- 导入：解析 Excel → 校验 → 错误明细 → 批量保存
+- 导出：构建查询 → 写入 Excel → 流式响应
+- 文件上传：分块上传 / 断点续传 / 校验类型大小
+
+### Step 4：测试
+
+- 导入：100行 / 1万行 / 10万行
+- 导出：空数据 / 大量数据 / 特殊字符
+- 上传：超限文件 / 错误类型
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 导入无错误明细 | 用户排查困难 | 逐行错误反馈 |
+| 批量保存无事务 | 部分失败数据不一致 | 整批事务 + 错误回滚 |
+| 上传无类型校验 | 安全风险 | 校验 Content-Type + 后缀 |
+| 导出无流式响应 | OOM | 大数据流式输出 |
+| 敏感字段明文日志 | 安全风险 | 脱敏后记录 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 单条数据保存 → `meritdata-platform-cloud-dev`
+  - BPM 附件 → `meritdata-platform-bpm`
+- **强制要求**：所有导入导出必须含错误明细和事务控制

package/skills/meritdata-platform-impexp/agents/openai.yaml

@@ -0,0 +1,33 @@
+display_name: "MeritData 数据导入导出"
+short_description: "Excel 导入导出、文件附件、模板、校验、批量保存"
+default_prompt: |
+  meritdata-platform-impexp 处理数据导入导出和文件附件场景。
+
+  适用场景：
+  - Excel 导入导出（含模板、校验、错误明细）
+  - 文件上传下载（分块/断点续传）
+  - 附件生命周期管理
+  - 字典转换、批量保存、事务控制
+
+  使用方式：
+  ```
+  meritdata-platform-impexp <导入导出需求>
+  ```
+
+  工作方式：
+  1. 设计 Excel 模板（列/类型/必填/字典）
+  2. 按主题路由读取 references/ 中的专题 md
+  3. 实现：解析→校验→错误明细→批量保存
+  4. 事务控制 + 幂等键
+  5. 敏感字段脱敏
+
+  3 个 references：
+  - import-workflow.md（导入流程）
+  - export-workflow.md（导出流程）
+  - file.md（文件/附件）
+
+  强制约束：
+  - 必须含错误明细（行号/字段/错误）
+  - 必须事务控制 + 幂等
+  - 必须校验 Content-Type + 后缀
+  - 敏感字段日志脱敏

package/skills/meritdata-platform-impexp/examples/excel-export/README.md

@@ -0,0 +1,146 @@
+# Impexp 示例：Excel 流式导出
+
+## 场景
+
+用户导出大量业务数据到 Excel（如订单列表 10 万行）。
+
+## 用户输入
+
+```text
+$meritdata-platform-impexp 实现订单列表 Excel 导出，支持流式输出、字典转换、敏感字段脱敏
+```
+
+## 完整实现
+
+### 1. Controller
+
+```java
+@RestController
+@RequestMapping("/api/order/export")
+public class OrderExportController {
+
+    @Autowired
+    private OrderExportService exportService;
+
+    @GetMapping("/excel")
+    public void exportOrders(OrderQueryParam query, HttpServletResponse response) throws IOException {
+        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
+        response.setCharacterEncoding("utf-8");
+        String fileName = URLEncoder.encode("订单列表.xlsx", "UTF-8");
+        response.setHeader("Content-disposition", "attachment;filename=" + fileName);
+
+        exportService.exportOrders(query, response.getOutputStream());
+    }
+}
+```
+
+### 2. Service（流式输出）
+
+```java
+@Service
+public class OrderExportService {
+
+    @Autowired
+    private OrderRepository orderRepository;
+
+    public void exportOrders(OrderQueryParam query, OutputStream os) {
+        // 流式写入，避免 OOM
+        ExcelWriter writer = EasyExcel.write(os, OrderExportRow.class).build();
+        WriteSheet sheet = EasyExcel.writerSheet("订单列表").build();
+
+        // 分页查询，每页 1000 条
+        int pageSize = 1000;
+        int pageNum = 1;
+
+        while (true) {
+            Page<OrderDO> page = orderRepository.findPage(query, pageNum, pageSize);
+            List<OrderExportRow> rows = convertToExportRows(page.getRecords());
+
+            writer.write(rows, sheet);
+
+            if (!page.hasNext()) {
+                break;
+            }
+            pageNum++;
+        }
+
+        writer.finish();
+    }
+
+    private List<OrderExportRow> convertToExportRows(List<OrderDO> orders) {
+        return orders.stream().map(order -> {
+            OrderExportRow row = new OrderExportRow();
+            row.setOrderNo(order.getOrderNo());
+            row.setUserName(maskUserName(order.getUserName()));  // 敏感字段脱敏
+            row.setAmount(order.getAmount());
+            row.setStatus(DictCache.getLabel("ORDER_STATUS", order.getStatus()));  // 字典转换
+            row.setCreateTime(order.getCreateTime());
+            return row;
+        }).collect(Collectors.toList());
+    }
+
+    private String maskUserName(String name) {
+        if (name == null || name.length() <= 1) return name;
+        return name.charAt(0) + "*".repeat(name.length() - 1);
+    }
+}
+```
+
+### 3. Export Row
+
+```java
+@Data
+public class OrderExportRow {
+
+    @ExcelProperty("订单号")
+    @ColumnWidth(20)
+    private String orderNo;
+
+    @ExcelProperty("客户姓名")
+    @ColumnWidth(15)
+    private String userName;
+
+    @ExcelProperty("金额（元）")
+    @ColumnWidth(15)
+    private BigDecimal amount;
+
+    @ExcelProperty("订单状态")
+    @ColumnWidth(15)
+    private String status;
+
+    @ExcelProperty("下单时间")
+    @ColumnWidth(20)
+    private Date createTime;
+}
+```
+
+## 关键决策
+
+1. **流式输出**：避免 OOM（10 万行不爆内存）
+2. **分页查询**：每页 1000 条，循环到末尾
+3. **字典转换**：状态码 → 中文标签
+4. **敏感脱敏**：姓名 mask
+5. **EasyExcel 写入**：流式 API 支持
+
+## 性能指标
+
+| 数据量 | 内存占用 | 导出耗时 |
+|--------|---------|---------|
+| 1000 行 | < 10 MB | < 1 秒 |
+| 1 万行 | < 30 MB | < 5 秒 |
+| 10 万行 | < 50 MB | < 30 秒 |
+| 100 万行 | < 100 MB | < 5 分钟 |
+
+## 测试场景
+
+- 空数据：导出空 Excel（含表头）
+- 100 行：基础导出
+- 10 万行：流式验证
+- 特殊字符：UTF-8 编码
+- 字典转换：枚举值映射
+- 敏感字段：脱敏验证
+
+## 相关 References
+
+- [`export-workflow.md`](../../references/export-workflow.md)
+- [`import-workflow.md`](../../references/import-workflow.md)

package/skills/meritdata-platform-impexp/examples/excel-import/README.md

@@ -0,0 +1,246 @@
+# Impexp 示例：Excel 批量导入
+
+## 场景
+
+用户上传 Excel 文件批量导入员工信息。
+
+## 用户输入
+
+```text
+$meritdata-platform-impexp 实现一个 Excel 批量导入员工功能，含模板下载、校验、错误明细、批量保存
+```
+
+## 完整实现
+
+### 1. Controller
+
+```java
+@RestController
+@RequestMapping("/api/employee/import")
+public class EmployeeImportController {
+
+    @Autowired
+    private EmployeeImportService importService;
+
+    @PostMapping("/upload")
+    public ResultBody<ImportResult> upload(@RequestParam("file") MultipartFile file) {
+        try {
+            ImportResult result = importService.importEmployees(file);
+            return ResultBody.success(result);
+        } catch (BusinessException e) {
+            return ResultBody.failure(e.getCode(), e.getMessage());
+        }
+    }
+
+    @GetMapping("/template")
+    public void downloadTemplate(HttpServletResponse response) throws IOException {
+        importService.downloadTemplate(response);
+    }
+}
+```
+
+### 2. Service
+
+```java
+@Service
+public class EmployeeImportService {
+
+    @Autowired
+    private EmployeeRepository employeeRepository;
+
+    @Transactional(rollbackFor = Exception.class)
+    public ImportResult importEmployees(MultipartFile file) {
+        ImportResult result = new ImportResult();
+
+        // 1. 解析 Excel
+        List<EmployeeRow> rows = parseExcel(file);
+
+        // 2. 校验
+        List<ImportError> errors = validate(rows);
+        if (!errors.isEmpty()) {
+            result.setSuccess(false);
+            result.setErrors(errors);
+            return result;
+        }
+
+        // 3. 批量保存（每 100 条一批）
+        int saved = 0;
+        for (int i = 0; i < rows.size(); i += 100) {
+            List<EmployeeRow> batch = rows.subList(i, Math.min(i + 100, rows.size()));
+            employeeRepository.batchInsert(batch);
+            saved += batch.size();
+        }
+
+        result.setSuccess(true);
+        result.setTotal(rows.size());
+        result.setSaved(saved);
+        return result;
+    }
+
+    private List<EmployeeRow> parseExcel(MultipartFile file) {
+        try {
+            return EasyExcel.read(file.getInputStream())
+                .head(EmployeeRow.class)
+                .sheet()
+                .doReadSync();
+        } catch (IOException e) {
+            throw new BusinessException("Excel 解析失败", e);
+        }
+    }
+
+    private List<ImportError> validate(List<EmployeeRow> rows) {
+        List<ImportError> errors = new ArrayList<>();
+        Set<String> employeeNos = new HashSet<>();
+
+        for (int i = 0; i < rows.size(); i++) {
+            EmployeeRow row = rows.get(i);
+
+            // 1. 必填校验
+            if (StringUtils.isEmpty(row.getName())) {
+                errors.add(new ImportError(i + 2, "姓名", "不能为空"));
+            }
+
+            // 2. 唯一性校验
+            if (!employeeNos.add(row.getEmployeeNo())) {
+                errors.add(new ImportError(i + 2, "工号", "重复"));
+            }
+
+            // 3. 长度校验
+            if (row.getName().length() > 64) {
+                errors.add(new ImportError(i + 2, "姓名", "超过 64 字符"));
+            }
+
+            // 4. 字典校验
+            if (!isValidGender(row.getGender())) {
+                errors.add(new ImportError(i + 2, "性别", "字典值无效"));
+            }
+        }
+        return errors;
+    }
+
+    public void downloadTemplate(HttpServletResponse response) throws IOException {
+        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
+        response.setCharacterEncoding("utf-8");
+        String fileName = URLEncoder.encode("员工导入模板.xlsx", "UTF-8");
+        response.setHeader("Content-disposition", "attachment;filename=" + fileName);
+
+        List<EmployeeRow> template = new ArrayList<>();
+        EmployeeRow example = new EmployeeRow();
+        example.setEmployeeNo("E001");
+        example.setName("张三");
+        example.setGender("M");
+        template.add(example);
+
+        EasyExcel.write(response.getOutputStream(), EmployeeRow.class)
+            .sheet("员工信息")
+            .doWrite(template);
+    }
+}
+```
+
+### 3. Row（Excel 数据行）
+
+```java
+@Data
+public class EmployeeRow {
+
+    @ExcelProperty("工号")
+    private String employeeNo;
+
+    @ExcelProperty("姓名")
+    private String name;
+
+    @ExcelProperty("性别")
+    private String gender;
+
+    @ExcelProperty("手机号")
+    private String phone;
+
+    @ExcelProperty("邮箱")
+    private String email;
+}
+```
+
+### 4. 错误明细模型
+
+```java
+@Data
+public class ImportError {
+    private Integer row;     // 行号
+    private String column;   // 字段名
+    private String message;  // 错误信息
+}
+```
+
+### 5. 结果模型
+
+```java
+@Data
+public class ImportResult {
+    private Boolean success;
+    private Integer total;     // 总行数
+    private Integer saved;     // 成功保存
+    private List<ImportError> errors;  // 错误明细
+}
+```
+
+### 6. 前端调用
+
+```vue
+<template>
+  <div>
+    <ImportButton
+      :upload-url="'/api/employee/import/upload'"
+      :template-url="'/api/employee/import/template'"
+      @success="handleSuccess"
+      @error="handleError" />
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    handleSuccess(result) {
+      if (result.success) {
+        this.$message.success(`导入成功，共 ${result.saved} 条`)
+        this.$emit('refresh')
+      } else {
+        this.showErrors(result.errors)
+      }
+    },
+
+    handleError(error) {
+      this.$message.error(error.message)
+    },
+
+    showErrors(errors) {
+      // 显示错误明细表格
+    }
+  }
+}
+</script>
+```
+
+## 关键决策
+
+1. **EasyExcel**：阿里开源 Excel 处理库（流式，低内存）
+2. **每 100 条批量插入**：平衡性能和事务粒度
+3. **错误明细返回行号**：用户可精确定位问题
+4. **下载模板**：避免用户手动建表格式错误
+5. **敏感字段脱敏**：手机号/邮箱脱敏后日志
+
+## 测试场景
+
+- 100 行：正常导入
+- 1 万行：批量保存性能
+- 10 万行：流式处理
+- 必填空：触发必填校验
+- 重复工号：触发唯一性校验
+- 超长字段：触发长度校验
+- 错误格式：触发字典校验
+
+## 相关 References
+
+- [`import-workflow.md`](../../references/import-workflow.md)
+- [`export-workflow.md`](../../references/export-workflow.md)
+- [`file.md`](../../references/file.md)