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

package/skills/meritdata-platform-operation-log/references/query-and-export.md

@@ -0,0 +1,218 @@
+# 操作日志查询与导出（operation-log）
+
+> 日志查询 / 多维统计 / 批量导出 / 归档清理。
+
+---
+
+## 1. 日志查询
+
+### 1.1 多维查询
+
+```java
+@GetMapping("/admin/operation-logs")
+public PageResult<OperationLogVO> query(OperationLogQuery query) {
+    return operationLogService.query(query);
+}
+```
+
+```java
+public class OperationLogQuery {
+    private String module;            // 模块筛选
+    private String action;            // 操作类型
+    private String userId;            // 操作人
+    private String bizId;             // 业务 ID
+    private String bizType;           // 业务类型
+    private Boolean sensitive;        // 是否敏感
+    private Boolean success;          // 是否成功
+    private LocalDateTime startTime;  // 时间范围
+    private LocalDateTime endTime;
+    private String keyword;           // 描述模糊搜索
+    private int page = 1;
+    private int size = 20;
+}
+```
+
+### 1.2 业务关联查询
+
+```java
+// 查某订单的所有操作记录
+@GetMapping("/orders/{orderId}/logs")
+public List<OperationLogVO> orderLogs(@PathVariable String orderId) {
+    return operationLogService.queryByBiz("ORDER", orderId);
+}
+```
+
+## 2. 统计
+
+### 2.1 按模块统计
+
+```java
+public List<ModuleStat> statByModule(LocalDate date) {
+    return operationLogRepository.countByModule(date);
+}
+
+public class ModuleStat {
+    private String module;
+    private long totalCount;
+    private long successCount;
+    private long failCount;
+}
+```
+
+### 2.2 按用户统计
+
+```java
+public List<UserStat> statByUser(LocalDate date, String orgId) {
+    return operationLogRepository.countByUser(date, orgId);
+}
+```
+
+### 2.3 异常操作排行
+
+```java
+public List<FailOperation> topFailOperations(LocalDate start, LocalDate end) {
+    return operationLogRepository.topFailOperations(start, end, 10);
+}
+```
+
+## 3. 导出
+
+### 3.1 异步导出（大数据量）
+
+```java
+@PostMapping("/admin/operation-logs/export")
+public Result export(OperationLogQuery query) {
+    String taskId = exportService.submit("operation-log", query);
+    return Result.success(taskId);
+}
+```
+
+导出进度查询：
+
+```java
+@GetMapping("/admin/export-tasks/{taskId}")
+public ExportTaskStatus status(@PathVariable String taskId) {
+    return exportService.status(taskId);
+}
+```
+
+### 3.2 Excel 格式
+
+```
+| 时间 | 模块 | 操作 | 操作人 | 客户端IP | 业务ID | 描述 | 耗时 | 成功 | 错误 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 2026-09-07 10:00 | ORDER | CREATE | 张三 | 192.168.1.1 | ORD001 | 创建订单 | 23ms | 是 | - |
+```
+
+### 3.3 敏感字段处理
+
+- 导出任务自动加 `@DamAudit(sensitive=true)`
+- 导出文件加访问权限控制
+- 文件 30 天后自动清理
+
+## 4. 归档清理
+
+### 4.1 策略
+
+| 等级 | 保留时间 |
+|------|---------|
+| 普通日志 | 90 天 |
+| 敏感日志 | 365 天 |
+| 高危日志 | 3 年（合规）|
+
+### 4.2 定时归档
+
+```java
+@Scheduled(cron = "0 0 3 * * ?")  // 每天凌晨 3 点
+public void archiveOperationLogs() {
+    LocalDate threshold = LocalDate.now().minusDays(90);
+    List<OperationLog> old = operationLogRepository.findByDateBefore(threshold);
+    archiveService.archive(old);
+    operationLogRepository.deleteByDateBefore(threshold);
+}
+```
+
+### 4.3 归档存储
+
+归档到对象存储（如 OSS/S3）：
+
+```yaml
+archive:
+  storage: oss
+  bucket: meritdata-logs
+  prefix: operation-log/
+```
+
+## 5. 性能优化
+
+### 5.1 分区表
+
+```sql
+CREATE TABLE t_operation_log (
+    ...
+    create_time DATETIME
+)
+PARTITION BY RANGE (TO_DAYS(create_time)) (
+    PARTITION p202609 VALUES LESS THAN (TO_DAYS('2026-10-01')),
+    PARTITION p202610 VALUES LESS THAN (TO_DAYS('2026-11-01')),
+    ...
+);
+```
+
+按月分区 → 历史数据快速清理（删分区即可）。
+
+### 5.2 索引设计
+
+```sql
+INDEX idx_module_create (module, create_time),
+INDEX idx_user_create (user_id, create_time),
+INDEX idx_biz (biz_type, biz_id)
+```
+
+### 5.3 大表查询优化
+
+```sql
+-- 避免 SELECT *
+SELECT id, module, action, user_name, create_time, ...
+  FROM t_operation_log
+ WHERE module = ? AND create_time BETWEEN ? AND ?
+ ORDER BY create_time DESC
+ LIMIT 100;
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 无差别保留全部日志
+
+```java
+// ❌ 错：所有日志永久保留
+operationLogRepository.save(log);  // 永不清理
+```
+
+✅ 按等级分级保留。
+
+### 6.2 ❌ 全字段导出
+
+```java
+// ❌ 错：导出包含请求体（含敏感信息）
+EasyExcel.write(out, OperationLogVO.class).doWrite(logs);
+```
+
+✅ 导出 VO 不含 requestParams 明文。
+
+### 6.3 ❌ 查询不限制时间
+
+```java
+// ❌ 错：不限时间 → 扫全表
+public List<OperationLog> queryAll() {
+    return operationLogRepository.findAll();  // 几亿条
+}
+```
+
+✅ 强制时间范围。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 操作日志基础
+- [sensitive-and-async.md](sensitive-and-async.md) — 脱敏与异步
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-operation-log/references/sensitive-and-async.md

@@ -0,0 +1,176 @@
+# 敏感参数与异步写入（operation-log）
+
+> 敏感参数脱敏是合规要求；异步写入是性能要求。
+
+---
+
+## 1. 敏感参数脱敏
+
+### 1.1 字段级脱敏
+
+```java
+@Data
+public class CreateUserRequest {
+    private String username;
+
+    @LogMask(strategy = MaskStrategy.PASSWORD)
+    private String password;          // 日志中显示 ****
+
+    @LogMask(strategy = MaskStrategy.MOBILE)
+    private String phone;             // 138****5678
+
+    @LogMask(strategy = MaskStrategy.ID_CARD)
+    private String idCard;            // 110101********1234
+
+    @LogMask(strategy = MaskStrategy.BANK_CARD)
+    private String bankCard;
+}
+```
+
+### 1.2 全字段脱敏
+
+```java
+@OperationLog(
+    module = "AUTH",
+    action = "RESET_PASSWORD",
+    maskAll = true    // 整个请求全部脱敏
+)
+public Result resetPassword(@RequestBody PasswordResetRequest req) {
+    // ...
+}
+```
+
+### 1.3 自定义脱敏
+
+```java
+@LogMask(strategy = MaskStrategy.CUSTOM, customMasker = ApiKeyMasker.class)
+private String apiKey;
+
+public class ApiKeyMasker implements LogMasker {
+    @Override
+    public String mask(String value) {
+        if (value == null || value.length() < 8) return "****";
+        return value.substring(0, 4) + "****" + value.substring(value.length() - 4);
+    }
+}
+```
+
+## 2. 敏感操作审计
+
+### 2.1 标记
+
+```java
+@OperationLog(
+    module = "PERMISSION",
+    action = "GRANT_ROLE",
+    sensitive = true,                 // 标记为敏感
+    sync = true                       // 敏感操作同步写
+)
+public Result grantRole(@RequestBody GrantRoleRequest req) {
+    return permissionService.grant(req);
+}
+```
+
+### 2.2 审计要求
+
+| 等级 | 行为 |
+|------|------|
+| 普通 | 异步写入，7 天保留 |
+| 敏感 | 同步写入，1 年保留 |
+| 高危 | 同步 + 实时告警 |
+
+```yaml
+operation-log:
+  sensitive-retention-days: 365
+  sensitive-alert: true
+```
+
+## 3. 异步写入机制
+
+### 3.1 流程
+
+```
+业务方法
+    ↓ 返回
+@OperationLog 拦截器（AOP）
+    ↓ 收集日志信息
+内存队列（ArrayBlockingQueue）
+    ↓ 批量消费
+后台线程批量 INSERT
+    ↓
+t_operation_log 表
+```
+
+### 3.2 配置
+
+```yaml
+operation-log:
+  async: true
+  queue-size: 10000              # 队列容量
+  batch-size: 100                # 每批写入条数
+  flush-interval-ms: 1000        # 强制刷新间隔
+  worker-threads: 2              # 消费线程数
+  fallback-sync: true            # 队列满时降级为同步
+```
+
+### 3.3 异常处理
+
+队列满或 DB 写入失败时：
+
+```yaml
+operation-log:
+  fallback-sync: true           # 同步写（降级）
+  fallback-disk: true            # 写到本地文件
+  alert-on-fail: true            # 告警
+```
+
+### 3.4 监控指标
+
+```
+operation_log_queue_size         当前队列大小
+operation_log_write_count_total  总写入条数
+operation_log_write_failed_total 写入失败条数
+operation_log_write_duration_ms  批量写入耗时
+```
+
+## 4. ❌ 反模式
+
+### 4.1 ❌ 密码明文进日志
+
+```java
+// ❌ 错
+@PostMapping("/auth/reset")
+public Result reset(@RequestBody ResetPasswordRequest req) {
+    // req.getNewPassword() 被自动记录 → 明文密码
+    userService.resetPassword(req);
+}
+```
+
+✅ `@LogMask(PASSWORD)`。
+
+### 4.2 ❌ 队列堆积不告警
+
+```yaml
+# ❌ 错：队列满无告警
+operation-log:
+  queue-size: 10000
+  # 没有 alert 配置
+```
+
+✅ 加告警。
+
+### 4.3 ❌ 异步队列无界
+
+```yaml
+# ❌ 错：无限队列 → OOM
+operation-log:
+  queue-size: 999999999
+```
+
+✅ 有界队列 + 降级策略。
+
+## 5. 关联阅读
+
+- [guide.md](guide.md) — 操作日志基础
+- [query-and-export.md](query-and-export.md) — 查询与导出
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-org-user-api/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-org-user-api
+description: |
+  用户与组织 API。IUserClient / IOrgClient / IAssignService 的查询与编排；批量装配避免 N+1；软删除实体唯一性校验穿透。
+  触发场景：二开需要查平台用户/组织数据；业务功能需基于用户/组织列表构建（审批人选择器、组织树）；用户/组织数据反查。
+  何时不用：写操作（新增/修改用户/组织）→ 用平台管理后台；二开自有用户/组织 → 自建表（详见 meritdata-platform-data-access）。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: high
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 用户与组织 API（org-user-api）
+
+## 触发
+- 二开业务需要查平台用户/组织数据
+- 业务功能构建人员选择器、组织树、审批人
+- 业务数据展示中需要"谁"和"哪个部门"（人员/组织 ID 反查名称）
+- 用户/组织的批量查询（避免 N+1）
+
+## 不触发
+- 用户/组织 CRUD 写操作 → 用平台管理后台
+- 二开自有用户/组织数据 → 自建表（详见 `meritdata-platform-data-access`）
+- 权限校验 → 用 `meritdata-platform-permission`
+
+## 前置约束
+- **必须**用 Feign Client + DTO，**禁止**直接 import 平台 Entity（违反 data-boundary §1.3）
+- **必须**批量查询，**禁止**循环逐条 Feign（违反 data-boundary §1.2）
+- 二开**不可写**用户/组织表（只读）
+
+## 路由
+- 用户/组织查询接口 + 批量装配 → [references/guide.md](references/guide.md)
+- 组织树 / 用户选择器 → [references/tree-and-picker.md](references/tree-and-picker.md)
+- 软删除穿透 / 唯一性校验 → [references/soft-delete-pitfalls.md](references/soft-delete-pitfalls.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-org-user-api/references/guide.md

@@ -0,0 +1,230 @@
+# 用户与组织 API 基础指南（org-user-api）
+
+> 平台 User / Org / Role 数据**只读**。二开业务通过 Feign Client 访问，**禁止**直接 import 平台 Entity。
+
+---
+
+## 1. Feign Client 入口
+
+### 1.1 IUserClient
+
+```java
+@FeignClient(name = "cloud-system-manage", path = "/api/v1/users")
+public interface IUserClient {
+
+    @GetMapping("/{userId}")
+    UserDTO getById(@PathVariable String userId);
+
+    @PostMapping("/batch")
+    List<UserDTO> listByIds(@RequestBody List<String> userIds);
+
+    @GetMapping("/by-org/{orgId}")
+    List<UserDTO> listByOrg(@PathVariable String orgId);
+
+    @GetMapping("/by-role/{roleCode}")
+    List<UserDTO> listByRole(@PathVariable String roleCode);
+}
+```
+
+### 1.2 IOrgClient
+
+```java
+@FeignClient(name = "cloud-system-manage", path = "/api/v1/orgs")
+public interface IOrgClient {
+
+    @GetMapping("/{orgId}")
+    OrgDTO getById(@PathVariable String orgId);
+
+    @PostMapping("/batch")
+    List<OrgDTO> listByIds(@RequestBody List<String> orgIds);
+
+    @GetMapping("/children/{parentOrgId}")
+    List<OrgDTO> listChildren(@PathVariable String parentOrgId);
+
+    @GetMapping("/tree")
+    List<OrgTreeDTO> tree();
+}
+```
+
+## 2. ⚠️ 关键铁律（违反即阻断）
+
+### 2.1 ❌ 禁止直接 import 平台 Entity
+
+```java
+// ❌ 违反 data-boundary §1.3
+import com.meritdata.cloud.platform.entity.User;
+```
+
+✅ 用 Feign Client + DTO：
+
+```java
+// ✅ 正确
+import com.example.dto.UserDTO;  // 二开自己的 DTO
+@Autowired IUserClient userClient;
+```
+
+### 2.2 ❌ 禁止循环逐条 Feign
+
+```java
+// ❌ 违反 data-boundary §1.2（N+1）
+for (Order order : orderList) {
+    UserDTO user = userClient.getById(order.getUserId());  // N 次 Feign
+    order.setUserName(user.getName());
+}
+```
+
+✅ 批量装配：
+
+```java
+// ✅ 正确
+List<String> userIds = orderList.stream()
+    .map(Order::getUserId)
+    .distinct()
+    .collect(Collectors.toList());
+
+List<UserDTO> users = userClient.listByIds(userIds);
+Map<String, UserDTO> userMap = users.stream()
+    .collect(Collectors.toMap(UserDTO::getUserId, Function.identity()));
+
+orderList.forEach(order ->
+    order.setUserName(userMap.get(order.getUserId()).getName())
+);
+```
+
+详见 [meritdata-platform-data-access 4-step 决策树](../meritdata-platform-data-access/references/guide.md)。
+
+## 3. UserDTO 字段
+
+```java
+public class UserDTO {
+    private String userId;
+    private String username;
+    private String realName;
+    private String email;
+    private String mobile;
+    private String orgId;
+    private String orgName;          // 冗余字段
+    private List<String> roleCodes;
+    private Boolean enabled;
+    private LocalDateTime createTime;
+    // ... 不暴露 DB 字段
+}
+```
+
+## 4. OrgDTO 字段
+
+```java
+public class OrgDTO {
+    private String orgId;
+    private String orgName;
+    private String orgCode;          // 行政编码
+    private String parentOrgId;
+    private String path;             // 路径（/ROOT/D001/D002）
+    private Integer level;
+    private Integer sort;
+    private Boolean enabled;
+}
+```
+
+## 5. 典型场景
+
+### 5.1 业务列表展示用户姓名
+
+```java
+@Service
+public class OrderListService {
+
+    @Autowired
+    private IUserClient userClient;
+
+    public List<OrderVO> list() {
+        List<Order> orders = orderRepository.findAll();
+
+        // 1. 批量查用户
+        List<String> userIds = orders.stream()
+            .map(Order::getCreateBy)
+            .distinct()
+            .collect(Collectors.toList());
+
+        Map<String, UserDTO> userMap = userClient.listByIds(userIds).stream()
+            .collect(Collectors.toMap(UserDTO::getUserId, Function.identity()));
+
+        // 2. 内存 join
+        return orders.stream().map(order -> {
+            OrderVO vo = OrderVO.from(order);
+            UserDTO user = userMap.get(order.getCreateBy());
+            vo.setCreateByName(user != null ? user.getRealName() : "未知");
+            return vo;
+        }).collect(Collectors.toList());
+    }
+}
+```
+
+### 5.2 审批人选择器
+
+```java
+@GetMapping("/approval/users")
+public List<UserDTO> approvalUsers(@RequestParam String roleCode) {
+    return userClient.listByRole(roleCode);
+}
+```
+
+### 5.3 当前用户
+
+```java
+import com.meritdata.cloud.security.SecurityUtils;
+
+UserDTO current = SecurityUtils.getCurrentUser();
+```
+
+## 6. 缓存策略
+
+### 6.1 二开缓存（推荐）
+
+二开业务缓存用户/组织信息：
+
+```java
+@Cacheable(value = "user", key = "#userId")
+public UserDTO getById(String userId) {
+    return userClient.getById(userId);
+}
+```
+
+### 6.2 平台缓存
+
+平台侧已有自己的缓存（短期），二开**避免**绕过。
+
+## 7. 错误处理
+
+```java
+@FeignClient(name = "cloud-system-manage", fallback = UserClientFallback.class)
+public interface IUserClient { ... }
+
+@Component
+public class UserClientFallback implements IUserClient {
+    @Override
+    public UserDTO getById(String userId) {
+        log.warn("平台用户服务不可用，userId={}", userId);
+        throw new ServiceException("USER_SERVICE_UNAVAILABLE");
+    }
+    // ...
+}
+```
+
+⚠️ **禁止** `catch + return null`（掩盖平台故障，违反 data-boundary §1.4）。
+
+## 8. ❌ 反模式汇总
+
+| 反模式 | 违反铁律 |
+|--------|---------|
+| `import 平台 Entity` | §1.3 |
+| `for + userClient.getById` | §1.2 |
+| `catch + return null/emptyList` | §1.4 |
+| `@TableName("PF_USER")` | §1.1 |
+
+## 9. 关联阅读
+
+- [tree-and-picker.md](tree-and-picker.md) — 组织树 / 用户选择器
+- [soft-delete-pitfalls.md](soft-delete-pitfalls.md) — 软删除穿透
+- [meritdata-platform-data-access](../meritdata-platform-data-access/references/guide.md) — 数据访问决策
+- [SKILL.md](../SKILL.md)