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

package/skills/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

@@ -0,0 +1,132 @@
+---
+name: 攻略-10-定时调度-章节05_调度功能使用
+description: 调度功能使用 — 美林平台 XXL-JOB 定时调度任务开发（JobHandler + Cron + API）
+keywords: [XXL-JOB, 定时任务, 调度, JobHandler, Cron, API, 调度功能使用]
+use-cases: [定时任务开发, JobHandler 编写, 调度 API 调用]
+source-section: 3. 调度功能使用
+source-file: 应用开发平台-基础平台-使用攻略（十）：定时调度任务.md
+---
+
+# 3.调度功能使用
+
+## 📋 API 契约（机器可读）
+
+```json
+{
+  "apiName": "JobHandler",
+  "type": "java",
+  "signature": "class JobHandler",
+  "functionDesc": "XXL-JOB JobHandler 实现（@JobHandler 注解）",
+  "module": "platform",
+  "methods": [
+    "execute()"
+  ],
+  "bestPractice": "确保方法抛出的异常已被 Service 层 catch 或全局异常处理器处理"
+}
+```
+
+完成系统环境搭建
+启动完后可访问 job 管理页面 ,8080 端口为前端应用 nginx 的启动端口
+http://ip地址:8080/portal
+
+### 3.1. 调度任务客户端注册
+
+新建一个 project-business-sso 执行器客户端样例服务，参考《微服务使用攻略（一）：系统环境搭建》后端工程创建，添加依赖包至客户端应用的 pom.xml 的 dependencies 节点
+
+```xml
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-starter-job</artifactId>
+    <version>${meritdata-platform-cloud.version}</version>
+</dependency>
+```
+
+同时需要在工程下的bootstrap.properties中找到spring.profiles.include并添加cloud-system-job，如下图：
+
+[IMG: image]
+
+
+
+执行器客户端服务启动完后，访问执行器管理页面可在页面发现该客户端已注册
+
+[IMG: image]
+
+### 3.2. 客户端应用内新增调度任务
+
+```java
+import com.xxl.job.core.biz.model.ReturnT;
+import com.xxl.job.core.handler.IJobHandler;
+import com.xxl.job.core.handler.annotation.JobHandler;
+import com.xxl.job.core.log.XxlJobLogger;
+import org.springframework.stereotype.Component;
+/**
+ 任务 Handler 示例（Bean 模式）
+ 开发步骤：
+ 1、继承"IJobHandler"：“com.xxl.job.core.handler.IJobHandler”；
+ 2、注册到 Spring 容器：添加“@Component”注解，被 Spring 容器扫描为 Bean 实例；
+ 3、注册到执行器工厂：添加“@JobHandler(value="自定义 jobhandler 名称")”注解，注解 value 值对应的是调度中心新建任务的 JobHandler 属性的值。
+ 4、执行日志：需要通过 "XxlJobLogger.log" 打印执行日志；
+*/
+@Component(value="demoJobHandler")
+@JobHandler(value="demoJobHandler")
+public class HelloWorldJob extends IJobHandler {
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+    System.out.println("demoJobHandler");
+    XxlJobLogger.log("demoJobHandler");
+    return SUCCESS;
+    }
+}
+
+```
+
+### 3.3. 调度任务管理页面新增调度任务
+
+新增中的 JobHandler 值为@JobHandler 注解的 Value 值，参考样例如下图：
+
+- 调度任务管理界面如下：
+  [IMG: image]
+  
+- 调度任务维护界面如下：
+  [IMG: image]
+  
+- 新增调度任务
+
+  - 执行器：服务名称
+
+  - 路由策略：执行器集群部署时提供的路由策略
+
+    - 第一个：固定选择第一个机器
+    - 最后一个： 固定选择最后一个机器
+    - 轮询：负载均衡+故障转移（根据jobId和路由地址数量求余，进行轮询，超过24小时，清零，从头开始）
+    - 随机：随机选择一个在线机器
+    - 一致性hash：主要解决集群增加或者减少节点
+    - 最不经常使用：
+    - 最近最久未使用：
+    - 故障转移：按照顺序依次进行心跳检测，第一个心跳检测成功的机器选为目标执行器并发起调度
+    - 忙碌转移：广播出发对应机器中所有机器执行一次任务，同时系统自动传递分片参数；可以根据分片参数开发分片任务
+
+  - cron表达式：是一个字符串，字符串以5或6个空格隔开，分为6或7个域，每一个域代表一个含义  
+  参见附录1 cron表达式
+
+
+
+  - JobHandler：这里填的是后端编写的调度任务JobHandler中注解名称
+
+  - 阻塞处理策略：
+
+    - 单机串行：以队列的形式，顺序执行
+    - 丢弃后续调度：如果有运行的调度任务，则新加入的直接返回失败。
+    - 覆盖之前调度：如果有运行的调度任务，则停止现有的调度任务，执行最新的调度任务。
+
+  - 子任务ID
+
+  - 任务超时时间
+
+  - 失败重试次数
+
+  - 负责人
+
+  - 报警邮件
+
+  - 任务参数

package/skills/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

@@ -0,0 +1,14 @@
+---
+name: 攻略-10-定时调度-章节06_调度任务_API_接口
+description: 调度任务 API 接口 — 美林平台 XXL-JOB 定时调度任务开发（JobHandler + Cron + API）
+keywords: [XXL-JOB, 定时任务, 调度, JobHandler, Cron, API, 调度任务 API 接口]
+use-cases: [定时任务开发, JobHandler 编写, 调度 API 调用]
+source-section: 4. 调度任务 API 接口
+source-file: 应用开发平台-基础平台-使用攻略（十）：定时调度任务.md
+---
+
+# 4. 调度任务 API 接口
+
+平台提供调度任务接口供维护调度任务数据，接口详情访问 http://ip:8080/gateway/swagger-ui.html
+
+[IMG: image]

package/skills/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

@@ -0,0 +1,245 @@
+---
+name: 攻略-10-定时调度-章节07_对外调度任务_API_接口
+description: 对外调度任务 API 接口 — 美林平台 XXL-JOB 定时调度任务开发（JobHandler + Cron + API）
+keywords: [XXL-JOB, 定时任务, 调度, JobHandler, Cron, API, 对外调度任务 API 接口]
+use-cases: [定时任务开发, JobHandler 编写, 调度 API 调用]
+source-section: 5. 对外调度任务 API 接口
+source-file: 应用开发平台-基础平台-使用攻略（十）：定时调度任务.md
+---
+
+# 5. 对外调度任务 API 接口
+
+```java
+/**
+* 获取任务信息
+*/
+@RequestMapping(value = "/jobinfo/get", method = RequestMethod.POST)
+ReturnT<CloudJobInfo> getJob(@RequestParam(name = "id") int id);
+
+/**
+* 获取任务信息列表
+*/
+ @RequestMapping(value = "/jobinfo/pageList", method = RequestMethod.POST)
+ Map<String, Object>  pageList(@RequestParam(name = "param") Map param);
+
+/**
+* 执行调度任务
+*/
+@RequestMapping(value = "/jobinfo/trigger", method = RequestMethod.POST)
+ReturnT<String> triggerJob(@RequestParam(name = "id") int id,
+                               @RequestParam(name = "executorParam", required = false) String executorParam);
+
+/**
+* 启动调度任务
+*@Param id 任务Id
+*/
+ @RequestMapping(value = "/jobinfo/start", method = RequestMethod.POST)
+ ReturnT<String> startJob(@RequestParam(name = "id") int id);
+
+/**
+* 停止调度任务
+*@Param id 任务Id
+*/
+@RequestMapping(value = "/jobinfo/stop", method = RequestMethod.POST)
+ReturnT<String> stopJob(@RequestParam(name = "id") int id);
+
+/**
+* 新增调度任务
+*/
+@RequestMapping(value = "/jobinfo/add", method = RequestMethod.POST)
+ReturnT<String> add(@SpringQueryMap CloudJobInfo jobInfo);
+
+/**
+* 更新调度任务
+*/
+@RequestMapping(value = "/jobinfo/update", method = RequestMethod.POST)
+ReturnT<String> update(@SpringQueryMap CloudJobInfo jobInfo);
+
+/**
+* 删除调度任务
+*@Param id 任务Id
+*/
+ @RequestMapping(value = "/jobinfo/remove", method = RequestMethod.POST)
+ ReturnT<String> remove(@RequestParam(name = "id") int id);
+
+/**
+* 根据应用名获取执行器
+*@Param appName 应用名
+*/
+@RequestMapping(value = "/jobgroup/getByAppName", method = RequestMethod.POST)
+CloudJobGroup getByAppName(@RequestParam(name = "appName") String appName);
+
+/**
+* 根据执行器名称获取job信息
+*/
+@RequestMapping(value = "/jobinfo/getHandler", method = RequestMethod.POST)
+ReturnT<CloudJobInfo> getHandler(@RequestParam(name = "handlerName") String handlerName);
+```
+
+```java
+import com.meritdata.cloud.job.api.IJobApi;
+import com.meritdata.cloud.job.model.CloudJobInfo;
+import com.xxl.job.core.biz.model.ReturnT;
+import com.xxl.job.core.handler.IJobHandler;
+import com.xxl.job.core.handler.annotation.JobHandler;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ 任务 Handler 示例（Bean 模式）
+ 开发步骤：
+ 1、继承"IJobHandler"：“com.xxl.job.core.handler.IJobHandler”；
+ 2、注册到 Spring 容器：添加“@Component”注解，被 Spring 容器扫描为 Bean 实例；
+ 3、注册到执行器工厂：添加“@JobHandler(value="自定义 jobhandler 名称")”注解，注解 value 值对应的是调度中心新建任务的 JobHandler 属性的值。
+ 4、执行日志：需要通过 "XxlJobLogger.log" 打印执行日志；
+ */
+@Component(value="demoJobHandler")
+@JobHandler(value="demoJobHandler")
+public class HelloWorldJob extends IJobHandler {
+
+    @Autowired
+    IJobApi webServerJobService;
+
+    /**
+    *   调用新增: param(1.动作，2.执行器Id，3.调度任务名称，4.路由策略，
+    *   5.运行模式，6.cron表达式，7.jobHandler名称，8.阻塞处理策略，9.负责人，10.任务周期类型，11.任务类型) 
+    *   create,1,测试新增,FIRST,BEAN,0 1/1 * * * ?,
+    *   helloWorldHandler,SERIAL_EXECUTION,张三
+    *
+    *   调用更新param（1.动作，2.Id，3.执行器Id，4.调度任务名称，5.路由策略，
+    *   6.运行模式，7.cron表达式，8.jobHandler名称，9.阻塞处理策略，10.负责人，11.任务周期类型，12.任务类型）
+    *   update,22,1,测试新增,FIRST,BEAN,0 1/1 * * * ?,
+    *   helloWorldHandler,SERIAL_EXECUTION,张三
+    *
+    *   调用启动任务param(1.动作，2.Id) start,22
+    *
+    *   调用停止任务param(1.动作，2.Id) stop,22
+    *
+    *   调用执行任务param(1.动作，2.Id) trigger,22
+    *
+    *   调用删除任务param(1.动作，2.Id) delete,22
+    *
+    */
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        String [] paramArr = param.split(",");
+        String type = paramArr[0];
+        Map map = new HashMap<>();
+        CloudJobInfo cloudJobInfo = new CloudJobInfo();
+        switch (type){
+            case "create" :
+
+                cloudJobInfo.setJobGroup(Integer.parseInt(paramArr[1]));
+                cloudJobInfo.setJobDesc(paramArr[2]);
+                cloudJobInfo.setExecutorRouteStrategy(paramArr[3]);
+                cloudJobInfo.setGlueType(paramArr[4]);
+                cloudJobInfo.setJobCron(paramArr[5]);
+
+                cloudJobInfo.setExecutorHandler(paramArr[6]);
+                cloudJobInfo.setExecutorBlockStrategy(paramArr[7]);
+                cloudJobInfo.setAuthor(paramArr[8]);
+                //任务的周期类型：{"7:年任务", "6:季度任务", "5:月任务", "4:周任务", "3:天任务", "2:小时任务", "1:分钟任务", "0:秒任务"}
+                cloudJobInfo.setPeroid(paramArr[9]);
+                //任务创建的产品类型
+                cloudJobInfo.setType(paramArr[10]);
+                webServerJobService.add(cloudJobInfo);
+                break;
+            case "update" :
+                cloudJobInfo.setId(Integer.parseInt(paramArr[1]));
+                cloudJobInfo.setJobGroup(Integer.parseInt(paramArr[2]));
+                cloudJobInfo.setJobDesc(paramArr[3]);
+                cloudJobInfo.setExecutorRouteStrategy(paramArr[4]);
+                cloudJobInfo.setGlueType(paramArr[5]);
+                cloudJobInfo.setJobCron(paramArr[6]);
+
+                cloudJobInfo.setExecutorHandler(paramArr[7]);
+                cloudJobInfo.setExecutorBlockStrategy(paramArr[8]);
+                cloudJobInfo.setAuthor(paramArr[9]);
+                //任务的周期类型：{"7:年任务", "6:季度任务", "5:月任务", "4:周任务", "3:天任务", "2:小时任务", "1:分钟任务", "0:秒任务"}
+                cloudJobInfo.setPeroid(paramArr[10]);
+                //任务创建的产品类型
+                cloudJobInfo.setType(paramArr[11]);
+                webServerJobService.update(cloudJobInfo);
+                break;
+            case "start" :
+                map.put("id",paramArr[1]);
+                webServerJobService.startJob(Integer.parseInt(paramArr[1]));
+                break;
+            case "stop" :
+                map.put("id",paramArr[1]);
+                webServerJobService.stopJob(Integer.parseInt(paramArr[1]));
+                break;
+            case "trigger":
+                map.put("id",paramArr[1]);
+                webServerJobService.triggerJob(Integer.parseInt(paramArr[1]),"");
+                break;
+            case "delete":
+                map.put("id",paramArr[1]);
+                webServerJobService.remove(Integer.parseInt(paramArr[1]));
+                break;
+            default:
+        }
+        return SUCCESS;
+    }
+}
+```
+
+
+
+## 附录 A. https 方式的执行器注册
+
+- 获取执行器微服务中的服务名，参考样例如下图：
+  [IMG: image]
+
+- 在 nacos 中，新增配置文件 common.properties，参考样例如下图：
+
+  ```shell
+  #前端工程部署的ip和端口号 如果前端工程也是集群模式 此处配置为系统的入口的ip和端口号 单机默认和后端的服务器一致
+  meritdata.cloud.web-server=http://${meritdata.cloud.server.ip}:8080
+  #调用gateway的ip和端口号 用于服务之间的互相调用（跳过nginx）
+  meritdata.cloud.web-server-gateway=http://${meritdata.cloud.server.ip}:8081
+  ```
+
+  [IMG: image]
+
+- 修改执行器微服务中的配置文件，参考样例如下图：
+  [IMG: image]
+
+- 重启执行器微服务
+
+
+## 附录 1. cron表达式
+  - 结构：从左到右： 秒  分  时  日  月  周   年
+
+  - 各字段含义：
+
+      | 字段               | 允许值                         | 允许特殊字符                                     |
+      | ------------------ | ------------------------------ | ------------------------------------------------ |
+      | 秒（second）       | 0~59的整数                     | ,    -    *    /   四个字符                      |
+      | 分（minute）       | 0~59的整数                     | ,    -    *    /   四个字符                      |
+      | 时（hour）         | 0~59的整数                     | ,    -    *    /   四个字符                      |
+      | 日（dayOfMonth）   | 1~31的整数（需要考虑月的天数） | ,    -    *    /    ?    L    W    C   八个字符  |
+      | 月（month）        | 1~12的整数                     | ,    -    *    /   四个字符                      |
+      | 周（weekOfMonth）  | 1~7的整数  或者 SUN~SAT(1=SUN) | ,    -    *    /    ?    L    C    #    八个字符 |
+      | 年（year）可以不填 | 1970~2099                      | ,    -    *    /   四个字符                      |
+
+  - 特殊字符含义：
+      - *: 表示匹配该域的任意值，加入在minute域中使用，表示每分钟都会触发事件。
+      - ?: 智能用在dayOfMonth和dayOfWeek两个域。它也匹配域的任意值，但实际不会。因为dayOfMonth和dayOfWeek会互相影响。例如想在每月的20日触发调度任务，不管20日是星期几，则只能用如下写法：13 13 15 20 * ?,其中最后一位只能用? ,而不能使用*，如果使用*表示不管在星期几都会触发，并不是我们想要的效果。
+      - -: 表示范围，例如在minute域中使用5-20，表示从5分钟到20分钟，每分钟执行一次。
+      - /: 表示起始时间开始触发，然后每隔固定时间触发一次。例如在minute域中使用5/20，则意味着每5分钟触发一次，而25，45等分钟分别触发一次。
+      - ,: 表示列举出枚举值，例如：在minute域中使用5,20 则表示在5和20分钟各触发一次。
+      - L: 表示最后，只能出现在dayOfMonth和dayOfWeek域。如果在dayOfWeek域使用5L,意味着在最后一个的星期四触发。
+      - W: 表示有效工作日（周一到周五），只能出现在dayOfMonth域，系统将在离指定日期的最近的有效工作日触发。例如：在dayOfMonth使用5W，如果5日是星期六，则将在最近的工作日：星期五，即4日触发。如果5日是星期天，则在6日（周一）触发。如果5日在星期一到星期五中的某一天，则就在5日触发。另外一点，W的最近寻找不会跨月。
+      - LW: 这两个字符可以连用，表示在某个月的最后一个工作日，即最后一个星期五。
+      - #: 用于确定每个月第几个星期几，只能出现在dayOfMonth，例如在4#2，表示某月的第二个星期三。
+  - 常用表达式：
+
+      - 0  0  2  1   * ？ *  每月1日 凌晨2点 执行
+      - 0 15 10 ？* MON-FRI  周一到周五 10点15分  执行
+      - 0  0  10,14,16  * * ? 每天10点 14点  16点 执行
+      - 0 0/5 14,18  *  *  ?  每天下午2点到2点55，下午6点到6点55 每五分钟执行一次

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;
+}
+```