npm - @alanwang-merit/meritdata-platform-skill-package - Versions diffs - 1.0.10 → 1.0.12 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (631) hide show

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

@@ -1,218 +0,0 @@
-# 操作日志查询与导出（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 DELETED Viewed

@@ -1,176 +0,0 @@
-# 敏感参数与异步写入（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 DELETED Viewed

@@ -1,42 +0,0 @@
----
-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 DELETED Viewed

@@ -1,230 +0,0 @@
-# 用户与组织 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)