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

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-job/references/scheduler-ref}//346/224/273/347/225/245-10-/345/256/232/346/227/266/350/260/203/345/272/246-/347/253/240/350/212/20205_/350/260/203/345/272/246/345/212/237/350/203/275/344/275/277/347/224/250.md

@@ -37,19 +37,19 @@ http://ip地址:8080/portal
 <dependency>
     <groupId>com.meritdata.cloud</groupId>
     <artifactId>cloud-starter-job</artifactId>
-    <version>${meritdata-cloud.version}</version>
+    <version>${meritdata-platform-cloud.version}</version>
 </dependency>
 ```
 
 同时需要在工程下的bootstrap.properties中找到spring.profiles.include并添加cloud-system-job，如下图：
 
-![image](/imgs/定时调度任务/2-4.png)
+[IMG: image]
 
 
 
 执行器客户端服务启动完后，访问执行器管理页面可在页面发现该客户端已注册
 
-![image](/imgs/定时调度任务/1-1.png)
+[IMG: image]
 
 ### 3.2. 客户端应用内新增调度任务
 
@@ -85,10 +85,10 @@ public class HelloWorldJob extends IJobHandler {
 新增中的 JobHandler 值为@JobHandler 注解的 Value 值，参考样例如下图：
 
 - 调度任务管理界面如下：
-  ![image](/imgs/定时调度任务/1-2.png)
+  [IMG: image]
   
 - 调度任务维护界面如下：
-  ![image](/imgs/定时调度任务/1-2-1.png)
+  [IMG: image]
   
 - 新增调度任务
 

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-job/references/scheduler-ref}//346/224/273/347/225/245-10-/345/256/232/346/227/266/350/260/203/345/272/246-/347/253/240/350/212/20206_/350/260/203/345/272/246/344/273/273/345/212/241_API_/346/216/245/345/217/243.md

@@ -11,4 +11,4 @@ source-file: 应用开发平台-基础平台-使用攻略（十）：定时调
 
 平台提供调度任务接口供维护调度任务数据，接口详情访问 http://ip:8080/gateway/swagger-ui.html
 
-![image](/imgs/定时调度任务/1-3.png)
+[IMG: image]

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-job/references/scheduler-ref}//346/224/273/347/225/245-10-/345/256/232/346/227/266/350/260/203/345/272/246-/347/253/240/350/212/20207_/345/257/271/345/244/226/350/260/203/345/272/246/344/273/273/345/212/241_API_/346/216/245/345/217/243.md

@@ -193,7 +193,7 @@ public class HelloWorldJob extends IJobHandler {
 ## 附录 A. https 方式的执行器注册
 
 - 获取执行器微服务中的服务名，参考样例如下图：
-  ![image](/imgs/定时调度任务/2-3.png)
+  [IMG: image]
 
 - 在 nacos 中，新增配置文件 common.properties，参考样例如下图：
 
@@ -204,10 +204,10 @@ public class HelloWorldJob extends IJobHandler {
   meritdata.cloud.web-server-gateway=http://${meritdata.cloud.server.ip}:8081
   ```
 
-  ![image](/imgs/定时调度任务/2-2.png)
+  [IMG: image]
 
 - 修改执行器微服务中的配置文件，参考样例如下图：
-  ![image](/imgs/定时调度任务/2-1.png)
+  [IMG: image]
 
 - 重启执行器微服务
 

package/skills/meritdata-platform-job/references/scheduler.md

@@ -0,0 +1,13 @@
+## 调度编排
+
+仅在目标项目已提供并使用 `ICloudClient` 时调用编排能力。先从现有 Feign 定义确认方法签名、服务名、认证 Header 和返回值；不要根据示例猜测 REST 路径。
+
+## 高影响操作
+
+提交、取消、冻结、发布和创建工作流前，确认：
+
+1. 目标环境、任务或工作流标识。
+2. 调用方授权，以及 `app-key`、`app-token` 的受管存储方式。
+3. 操作是否可重试、可回滚，以及失败后的状态查询方式。
+
+检查远程调用结果并记录可追踪的任务 ID。不得把令牌或请求体中的敏感字段写入日志。

package/skills/meritdata-platform-job/references/xxl-job.md

@@ -0,0 +1,30 @@
+## 版本选择
+
+先在目标项目中定位现有 Handler 和依赖：
+
+- 已使用 `IJobHandler` 与 `@JobHandler` 时，沿用该旧式模式。
+- 已使用 `@XxlJob` 时，沿用注解式模式。
+- 未找到任一模式时，先确认平台版本和调度 starter；不要同时生成两套代码。
+
+## Handler 约束
+
+- 为每次执行定义幂等键或业务唯一约束，重复触发不得重复写入或重复通知。
+- 使用平台任务日志记录开始、输入摘要、结果和失败原因；不要记录凭据或完整敏感数据。
+- 任务参数必须有结构化格式或显式校验。不要用逗号切分后直接执行启动、停止或删除操作。
+- 任务必须设置可接受的超时、重试和日志保留策略；具体配置名称以目标版本为准。
+
+## 策略选择
+
+| 场景 | 并发/阻塞 | 幂等 | 重试 |
+| --- | --- | --- | --- |
+| 数据同步 | 同一业务键串行 | 同步批次或游标 | 仅瞬时外部失败 |
+| 统计或对账 | 避免重叠执行 | 统计周期唯一 | 可重试，保留失败明细 |
+| 导出 | 单任务实例 | 导出任务 ID | 不自动重复发送文件 |
+| 清理 | 串行且限批 | 删除条件可重放 | 谨慎重试，记录影响范围 |
+
+## 最小验收
+
+1. 编译并确认 Handler 已注册。
+2. 在非生产环境手动触发一次。
+3. 连续触发两次，验证没有重复副作用。
+4. 验证失败日志、告警和恢复路径。

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

@@ -0,0 +1,54 @@
+---
+name: meritdata-platform-logging
+description: MeritData 日志专项。用于 SLF4J 日志门面、日志级别规范、敏感字段脱敏、审计日志、ELK 集成。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: low
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**使用 SLF4J 日志门面；敏感字段（password/keytab/token/身份证/手机号）必须脱敏；异步日志避免阻塞主流程。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 日志级别使用（ERROR/WARN/INFO/DEBUG）
+- 敏感字段脱敏
+- 审计日志设计
+- ELK 集成
+
+**不适用**：
+- 平台操作日志（@LogOperation）→ `meritdata-platform-core/references/logging.md`
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+
+## 工作方式
+
+1. 使用 SLF4J：`private static final Logger log = LoggerFactory.getLogger(Xxx.class);`
+2. 日志级别：ERROR（业务异常）/WARN（降级处理）/INFO（关键流程）/DEBUG（调试）
+3. 敏感字段必须脱敏后记录
+4. 使用 Logback 异步 appender 避免阻塞
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 日志明文打印密码 | 安全风险 | 脱敏后记录 |
+| 生产环境开 DEBUG | 性能 + 信息泄露 | 生产关闭 |
+| 日志中打印大对象 | 性能 | 只打印关键字段 |
+| 同步日志阻塞 | 响应慢 | 异步 appender |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 平台 @LogOperation → `meritdata-platform-core`
+- **强制要求**：敏感字段脱敏

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

@@ -0,0 +1,16 @@
+display_name: "MeritData 日志"
+short_description: "SLF4J 日志规范、敏感字段脱敏、审计日志、ELK"
+default_prompt: |
+  meritdata-platform-logging 处理日志规范场景。
+
+  适用场景：
+  - SLF4J 日志门面使用
+  - 日志级别规范
+  - 敏感字段脱敏
+  - 审计日志设计
+
+  强制约束：
+  - 使用 SLF4J 日志门面
+  - 敏感字段（password/keytab/token/身份证/手机号）必须脱敏
+  - 异步日志避免阻塞
+  - 生产环境关闭 DEBUG

package/skills/meritdata-platform-logging/references/api-quick-ref.md

@@ -0,0 +1,90 @@
+# ILogPostService + 4 注解 API 速查
+
+## ILogPostService（2 方法）
+
+| 方法 | 签名 |
+|------|------|
+| `log` | `void log(LogDTO logDTO)` |
+| `logBatch` | `void logBatch(List<LogDTO> logDTOs)` |
+
+## LogDTO 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `module` | String | ✅ | 模块名（如 "合同管理"）|
+| `operation` | String | ✅ | 操作类型（新增/修改/删除/查询）|
+| `userId` | String | ✅ | 当前用户 ID（从 SessionUtils 取）|
+| `content` | String | ✅ | 操作内容 |
+| `result` | String | ✅ | SUCCESS / FAIL |
+| `bizId` | String | ❌ | 业务 ID |
+| `ip` | String | ❌ | 操作 IP |
+| `params` | Map | ❌ | 操作参数 |
+| `createTime` | Date | ❌ | 默认 now |
+
+## 4 个注解
+
+### @LogOperation（方法级）
+
+```java
+@LogOperation(type = "合同管理-新增合同")
+public Result addContract(...) { ... }
+```
+
+### @LogDesc（字段级）
+
+```java
+@LogDesc("合同编号")
+private String contractNo;
+```
+
+### @AddDesc（新增时记该字段）
+
+```java
+@AddDesc
+private Date createTime;  // 新增时记到日志
+```
+
+### @DelDesc（删除时记该字段）
+
+```java
+@DelDesc
+private String reason;  // 删除时记到日志
+```
+
+## 典型用法
+
+### 注解方式（推荐）
+
+```java
+@LogOperation(type = "合同管理-审批通过")
+@PostMapping("/contract/approve/{id}")
+public Result approve(@PathVariable String id) {
+    // 平台 AOP 自动记录
+    return contractService.approve(id);
+}
+```
+
+### 手动方式
+
+```java
+public void batchApprove(List<String> ids) {
+    for (String id : ids) {
+        try {
+            approveOne(id);
+            logPostService.log(buildLog(id, "SUCCESS"));
+        } catch (Exception e) {
+            logPostService.log(buildLog(id, "FAIL"));
+        }
+    }
+}
+
+private LogDTO buildLog(String bizId, String result) {
+    LogDTO log = new LogDTO();
+    log.setModule("合同审批");
+    log.setOperation("审批");
+    log.setUserId(SessionUtils.getUserId());
+    log.setBizId(bizId);
+    log.setResult(result);
+    return log;
+}
+```

package/skills/meritdata-platform-logging/references/logging.md

@@ -0,0 +1,256 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入。
+
+**服务调用方式**: Feign 远程调用，服务名 `cloud-system-manage`，基础路径 `/api/basic/log`。
+
+引入 Feign 依赖后注入使用：
+
+```java
+@Autowired
+private ILogPostService logPostService;
+```
+
+**完整包路径**: `com.meritdata.cloud.log.service.ILogPostService`
+
+---
+
+## 快速开始：新增日志
+
+```java
+Message msg = new Message(
+    Message.TYPE_OPT,          // 日志类型：0-操作日志
+    "组织机构",                  // 业务模块
+    "人员维护",                  // 功能模块
+    "新增人员",                  // 操作描述
+    "新增人员[张三]",            // 日志内容
+    Message.STATUS_SUCESS       // 状态：1-成功
+);
+logPostService.postLog(msg);
+```
+
+输出日志：`[用户1:user1] 新增人员[张三]`
+
+---
+
+## 日志类型
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `Message.TYPE_OPT` | 0 | 操作日志 |
+| `Message.TYPE_VISIT` | 1 | 访问日志 |
+| `Message.TYPE_LOGIN` | 2 | 登录日志 |
+| `Message.TYPE_ERROR` | 3 | 错误日志 |
+| `Message.TYPE_SAFE` | 5 | 安全日志 |
+| `Message.TYPE_SERVER` | 6 | 服务日志 |
+| `Message.TYPE_LOGOUT` | 7 | 登出日志 |
+
+---
+
+## Message 对象
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| type | String | 是 | 日志类型 |
+| bmodule | String | 是 | 业务模块 |
+| fmodule | String | 是 | 功能模块 |
+| operation | String | 是 | 操作描述 |
+| message | String | 否 | 日志内容/变更详情 |
+| status | String | 是 | 操作状态：1-成功 |
+
+可选字段：`ip`, `fullname`, `userid`, `tenantId`, `grade`, `code`, `operationType`, `startTime`, `endTime`, `executeTime`
+
+---
+
+## 日志模板配置
+
+在 `src/main/resources/logs/{module}.logs.properties` 中配置：
+
+```properties
+# 业务模块
+ou.org.bmodule=组织机构
+# 功能模块
+ou.emp.fmodule=人员维护
+# 操作描述
+ou.emp.create=新增人员
+# 操作信息模板（{}为占位符）
+ou.emp.create.message=新增人员[{}]
+ou.emp.update=编辑人员
+ou.emp.delete=删除人员
+ou.emp.delete.message=删除人员{}
+```
+
+读取配置：
+
+```java
+LogPattenUtils.getProperty("ou.org.bmodule")
+```
+
+---
+
+## @LogDesc — 实体字段注解
+
+**完整包路径**: `com.meritdata.cloud.base.LogDesc`
+
+注解在实体类上，配合 `CompareUtils` 自动生成变更日志。
+
+```java
+@LogDesc(value = "人员", keyField = "name")  // 类注解：实体描述 + 日志主键字段
+@Entity
+public class Emp extends CloudBaseEntity {
+
+    @LogDesc("姓名")        // 普通字段：变更显示"姓名"由[旧值]变更为[新值]
+    @DelDesc               // 删除时记录此字段
+    @AddDesc               // 新增时记录此字段
+    private String name;
+
+    @LogDesc(value = "性别", lookupType = "sex")  // lookupType 自动转换数据字典
+    private Integer sex;
+
+    @LogDesc(value = "手机号", changeFlag = true)  // changeFlag=true 显示"手机号变更"
+    private String handset;
+}
+```
+
+| 属性 | 说明 |
+|------|------|
+| `value` | 字段中文描述 |
+| `keyField` | 日志前缀字段名（类上使用） |
+| `lookupType` | 数据字典类型，自动转换编码为中文 |
+| `changeFlag` | true → 打印"XX变更"，不显示具体值（敏感信息） |
+| `booleanFlag` | 布尔类型转换 |
+
+**配套注解**：
+- `@AddDesc` — 标记新增时记录此字段
+- `@DelDesc` — 标记删除时记录此字段
+
+---
+
+## CompareUtils — 自动变更日志
+
+**完整包路径**: `com.meritdata.cloud.log.compare.CompareUtils`
+
+```java
+Emp empDb = service.getEmpById(emp.getId());
+// 自动生成："姓名"由[张三]变更为[李四], "性别"由[男]变更为[女], "手机号"变更
+String compareLog = CompareUtils.getCompareLog(empDb, emp);
+```
+
+---
+
+## 完整 CRUD 日志示例
+
+### 新增
+
+```java
+@LogOperation(type = "add")
+public boolean create(Emp emp) {
+    boolean flag = service.insertEmp(emp);
+    if (flag) {
+        Message msg = new Message(Message.TYPE_OPT,
+            LogPattenUtils.getProperty("ou.org.bmodule"),
+            LogPattenUtils.getProperty("ou.emp.fmodule"),
+            LogPattenUtils.getProperty("ou.emp.create"),
+            StrUtil.format(LogPattenUtils.getProperty("ou.emp.create.message"), emp.getName()),
+            Message.STATUS_SUCESS);
+        logPostService.postLog(msg);
+    }
+    return flag;
+}
+```
+
+### 编辑
+
+```java
+@LogOperation(type = "edit")
+public boolean update(Emp emp) {
+    Emp empDb = service.getEmpById(emp.getId());
+    String compareLog = CompareUtils.getCompareLog(empDb, emp);
+    boolean flag = service.updateEmp(emp);
+    if (flag && StrUtil.isNotBlank(compareLog)) {
+        Message msg = new Message(Message.TYPE_OPT,
+            LogPattenUtils.getProperty("ou.org.bmodule"),
+            LogPattenUtils.getProperty("ou.emp.fmodule"),
+            LogPattenUtils.getProperty("ou.emp.update"),
+            compareLog,
+            Message.STATUS_SUCESS);
+        logPostService.postLog(msg);
+    }
+    return flag;
+}
+```
+
+### 删除
+
+删除日志必须在删除前或删除结果中取得已删除对象的可审计摘要。不要复制使用未定义变量的“完整示例”；沿用目标项目已存在的删除日志实现，并避免记录密码、令牌或完整敏感字段。
+
+---
+
+## @LogOperation — 方法注解
+
+**完整包路径**: `com.meritdata.cloud.log.aspect.LogOperation`
+
+标记方法操作类型，框架自动记录操作时间。
+
+| type 值 | 说明 |
+|---------|------|
+| `add` | 新增 |
+| `edit` | 修改 |
+| `delete` | 删除 |
+| `select` | 查询 |
+| `visit` | 访问 |
+| `loginIn` | 登录 |
+| `loginOut` | 登出 |
+| `import` | 导入 |
+| `export` | 导出 |
+| `download` | 下载 |
+| `upload` | 上传 |
+| `assign` | 分配/变更 |
+
+```java
+@LogOperation(type = "add")
+public ReturnT<String> add(@Valid CloudJobInfo jobInfo) {
+    Message msg = new Message(...);
+    msg.setStartTime(System.currentTimeMillis());
+    msg.setEndTime(System.currentTimeMillis());
+    logPostService.postLog(msg);
+    return CloudJobService.add(jobInfo);
+}
+```
+
+---
+
+## 自定义日志 (postDiyLog)
+
+**接口**: `POST /post-diy`
+
+```java
+private void postLoginLog(User user, Long startTime) {
+    Long executeTime = System.currentTimeMillis() - startTime;
+    Message msg = new Message(Message.TYPE_LOGOUT,
+        LogPattenUtils.getProperty("common.basic.bmodule"),
+        LogPattenUtils.getProperty("common.logout.fmodule"),
+        LogPattenUtils.getProperty("common.logout.fmodule"),
+        StrUtil.format(LogPattenUtils.getProperty("common.loginout.user")),
+        Message.STATUS_SUCESS);
+    msg.setIp(user.getLoginIp());
+    msg.setFullname(user.getUsername());
+    msg.setUserid(user.getUserId());
+    msg.setTenantId(user.getTenantId());
+    msg.setCode(user.getCode());
+    msg.setOperationType("loginOut");
+    msg.setExecuteTime(executeTime);
+    logPostService.postDiyLog(msg);
+}
+```
+
+---
+
+## 日志注意事项
+
+1. 日志服务是 Feign 远程调用，需要确保 `cloud-system-manage` 服务可用
+2. 日志模板文件必须放在 `src/main/resources/logs/` 目录
+3. `@LogDesc` 的 `changeFlag=true` 用于敏感字段，不暴露具体值
+4. `@LogOperation` 不自动记录日志内容，只辅助记录时间和类型
+
+---