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

package/skills/meritdata-platform-nacos-config/references/env-and-gray.md

@@ -1,178 +0,0 @@
-# Nacos 多环境隔离与灰度发布（nacos-config）
-
-> 多环境（dev/test/prod）配置隔离；灰度发布（部分实例应用新配置）。
-
----
-
-## 1. 多环境隔离
-
-### 1.1 Namespace 机制
-
-每个环境一个 Namespace：
-
-| 环境 | Namespace ID | 说明 |
-|------|--------------|------|
-| dev | `dev-namespace-id` | 开发 |
-| test | `test-namespace-id` | 测试 |
-| staging | `staging-namespace-id` | 预发 |
-| prod | `prod-namespace-id` | 生产 |
-
-### 1.2 配置
-
-```yaml
-# bootstrap.yml
-spring:
-  cloud:
-    nacos:
-      config:
-        namespace: ${NACOS_NAMESPACE:dev}  # 通过环境变量切换
-```
-
-部署时：
-
-```bash
-# 开发环境
-NACOS_NAMESPACE=dev-namespace-id java -jar app.jar
-
-# 生产环境
-NACOS_NAMESPACE=prod-namespace-id java -jar app.jar
-```
-
-### 1.3 Group 机制
-
-同一 Namespace 内，可用 Group 区分：
-
-| Group | 用途 |
-|-------|------|
-| `DEFAULT_GROUP` | 默认配置 |
-| `FEATURE_GROUP` | 新功能开关 |
-| `BUSINESS_GROUP` | 业务配置 |
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      config:
-        group: ${NACOS_GROUP:DEFAULT_GROUP}
-```
-
-## 2. Profile 机制（推荐）
-
-### 2.1 spring.profiles.active
-
-```yaml
-# application.yml
-spring:
-  profiles:
-    active: dev   # 切换为 dev / test / prod
-```
-
-### 2.2 dataId 命名
-
-平台约定：
-
-```
-{service-name}-{profile}.yaml
-```
-
-例：
-- `your-2nd-service-dev.yaml`
-- `your-2nd-service-test.yaml`
-- `your-2nd-service-prod.yaml`
-
-激活 prod profile 时，自动加载 `your-2nd-service-prod.yaml`。
-
-### 2.3 配置优先级
-
-```
-Nacos 配置（prod.yaml）          ← 最高优先级
-   ↓
-本地配置（application-prod.yml）
-   ↓
-本地配置（application.yml）      ← 最低优先级
-```
-
-## 3. 灰度发布（部分实例生效）
-
-### 3.1 场景
-
-某配置变更想在 10% 实例上验证，确认无问题后推全量。
-
-### 3.2 方案 1：通过 Group
-
-```yaml
-# 灰度实例：使用灰度 Group
-spring:
-  cloud:
-    nacos:
-      config:
-        group: GRAY_GROUP
-```
-
-正常实例继续用 DEFAULT_GROUP。
-
-### 3.3 方案 2：自定义 dataId
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      config:
-        extension-configs[0]:
-          data-id: feature-gray.yaml
-          group: DEFAULT_GROUP
-          refresh: true
-```
-
-只在灰度实例上配置这个 extension。
-
-### 3.4 方案 3：标签路由
-
-在 Nacos 控制台给指定实例打 tag（如 `gray=true`），编辑配置时选择"推送到 tag 实例"。
-
-## 4. 环境隔离检查清单
-
-- [ ] Namespace 隔离（不能一个 namespace 跨环境）
-- [ ] 敏感配置（数据库密码、密钥）只在 prod namespace
-- [ ] 配置命名清晰（`your-2nd-service-prod.yaml`）
-- [ ] 配置变更审计（Nacos 提供变更历史）
-- [ ] 灰度发布策略（先灰度 → 监控 → 推全）
-
-## 5. ❌ 反模式
-
-### 5.1 ❌ 所有环境用同一个 Namespace
-
-```yaml
-# ❌ 错：dev 和 prod 共享 namespace
-namespace: default
-```
-
-✅ 每个环境独立 namespace。
-
-### 5.2 ❌ 灰度无监控
-
-```bash
-# ❌ 错：推灰度后不监控
-推灰度 → 等待 → 推全
-```
-
-✅ 推灰度后密切监控：
-- 错误率
-- 响应时间
-- 业务指标
-
-### 5.3 ❌ 灰度直接推全
-
-```bash
-# ❌ 错：跳过灰度
-修改配置 → 推全
-```
-
-✅ 流程：开发 → 测试 → 灰度 → 全量。
-
-## 6. 关联阅读
-
-- [guide.md](guide.md) — Nacos 配置基础
-- [dynamic-refresh.md](dynamic-refresh.md) — 动态刷新
-- [encryption.md](encryption.md) — 敏感配置加密
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-nacos-config/references/guide.md

@@ -1,127 +0,0 @@
-# Nacos 配置中心接入指南（nacos-config）
-
-> 平台使用 Nacos 作为配置中心。支持动态刷新、多环境隔离、敏感配置加密。
-
----
-
-## 1. 引入依赖
-
-```xml
-<dependency>
-    <groupId>com.alibaba.cloud</groupId>
-    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
-</dependency>
-<dependency>
-    <groupId>org.springframework.cloud</groupId>
-    <artifactId>spring-cloud-starter-bootstrap</artifactId>
-</dependency>
-```
-
-## 2. bootstrap.yml
-
-```yaml
-spring:
-  application:
-    name: your-2nd-service
-  cloud:
-    nacos:
-      config:
-        server-addr: ${NACOS_SERVER:localhost:8848}
-        namespace: ${NACOS_NAMESPACE:dev}
-        file-extension: yaml
-        group: DEFAULT_GROUP
-        refresh-enabled: true
-```
-
-## 3. @NacosValue 用法
-
-### 3.1 基本读配置
-
-```java
-@NacosValue(value = "${order.timeout:30}", autoRefreshed = true)
-private int orderTimeout;
-
-@NacosValue(value = "${sms.enabled:false}", autoRefreshed = true)
-private boolean smsEnabled;
-```
-
-### 3.2 @NacosConfigurationProperties（推荐）
-
-```java
-@NacosConfigurationProperties(dataId = "your-2nd-service.yaml", autoRefreshed = true)
-@Data
-public class AppConfig {
-    private int timeout = 30;
-    private boolean smsEnabled = false;
-    private String apiUrl;
-    private List<String> allowedOrigins;
-}
-```
-
-注入使用：
-
-```java
-@Service
-public class OrderService {
-    @Autowired
-    private AppConfig appConfig;
-
-    public void doSomething() {
-        if (appConfig.isSmsEnabled()) {
-            // ...
-        }
-    }
-}
-```
-
-## 4. 动态刷新
-
-详见 [dynamic-refresh.md](dynamic-refresh.md)。
-
-## 5. 多环境隔离
-
-详见 [env-and-gray.md](env-and-gray.md)。
-
-## 6. 敏感配置加密
-
-详见 [encryption.md](encryption.md)。
-
-## 7. ❌ 反模式
-
-### 7.1 ❌ 把所有配置都放 Nacos
-
-```yaml
-# ❌ 错：不变的配置也放 Nacos
-@NacosValue(value = "${spring.application.name}")
-private String appName;
-```
-
-✅ 静态配置放 application.yml，动态配置放 Nacos。
-
-### 7.2 ❌ 敏感配置明文存 Nacos
-
-```yaml
-# ❌ 错：明文密码
-spring:
-  datasource:
-    password: mySecretPassword123
-```
-
-✅ 用 Nacos 加密配置（详见 [encryption.md](encryption.md)）。
-
-### 7.3 ❌ 配置项命名不规范
-
-```yaml
-# ❌ 错：无业务前缀
-order.timeout: 30
-
-# ✅ 正确：业务前缀
-your-service.order.timeout: 30
-```
-
-## 8. 关联阅读
-
-- [dynamic-refresh.md](dynamic-refresh.md) — 动态刷新
-- [env-and-gray.md](env-and-gray.md) — 多环境
-- [encryption.md](encryption.md) — 加密
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-operation-log/SKILL.md

@@ -1,42 +0,0 @@
----
-name: meritdata-platform-operation-log
-description: |
-  操作日志。@OperationLog 注解自动记录 / 异步写入 / 敏感操作审计 / 日志查询与导出。
-  触发场景：新增/修改/删除业务数据需要审计 / 敏感操作（权限变更、密钥导出）需要留痕 / 排查问题需要操作轨迹。
-  何时不用：访问日志（nginx/网关层记录）→ 不归本 skill；调试日志（log4j）→ 不归本 skill。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: medium
-  layer: L3
-  sub-layer: L3-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 操作日志（operation-log）
-
-## 触发
-- 业务写操作（新增/修改/删除/审批）需要留痕
-- 敏感操作（权限变更、密钥导出、配置修改）需审计
-- 事后追溯（谁在什么时间改了订单状态？）
-- 满足合规（等保、SOC2 要求操作可追溯）
-
-## 不触发
-- 性能监控/访问日志 → 用 APM 工具（SkyWalking/CAT）
-- 程序调试日志 → 用 SLF4J/Log4j
-- 业务变更历史（版本号、变更人）→ 用实体字段 `create_by/update_by`
-
-## 前置约束
-- 异步写入，**禁止**同步阻塞业务
-- 敏感参数**必须脱敏**（密码、token、身份证）
-- 关联请求链路 traceId 便于排查
-
-## 路由
-- @OperationLog 注解 + 自动记录 → [references/guide.md](references/guide.md)
-- 敏感参数脱敏 + 异步写入 → [references/sensitive-and-async.md](references/sensitive-and-async.md)
-- 日志查询 / 导出 / 统计 → [references/query-and-export.md](references/query-and-export.md)
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-operation-log/references/guide.md

@@ -1,175 +0,0 @@
-# 操作日志基础指南（operation-log）
-
-> @OperationLog 注解方式记录操作日志。异步写入，不阻塞业务。
-
----
-
-## 1. 引入依赖
-
-平台已默认集成，无需额外引入。
-
-## 2. 基本用法
-
-### 2.1 @OperationLog 注解
-
-```java
-@PostMapping("/orders")
-@OperationLog(
-    module = "ORDER",
-    action = "CREATE",
-    description = "创建订单",
-    sensitive = false
-)
-public Result<OrderDTO> create(@RequestBody OrderDTO order) {
-    return Result.success(orderService.create(order));
-}
-```
-
-### 2.2 注解参数
-
-| 参数 | 必填 | 含义 |
-|------|------|------|
-| module | ✅ | 模块名（如 ORDER/USER/PROJECT）|
-| action | ✅ | 操作类型（CREATE/UPDATE/DELETE/APPROVE 等）|
-| description | 否 | 操作描述 |
-| sensitive | 否 | 是否敏感（敏感会额外审计）|
-| recordParams | 否 | 是否记录请求参数（默认 true）|
-
-### 2.3 自动记录的字段
-
-平台自动获取：
-
-| 字段 | 来源 |
-|------|------|
-| userId | SecurityUtils.getCurrentUserId() |
-| userName | SecurityUtils.getCurrentUserName() |
-| tenantId | SecurityUtils.getCurrentTenantId() |
-| clientIp | HttpServletRequest.getRemoteAddr() |
-| userAgent | HttpServletRequest.getHeader("User-Agent") |
-| requestUrl | HttpServletRequest.getRequestURI() |
-| requestMethod | @RequestMapping |
-| requestParams | 注解 + 参数 |
-| responseData | 默认不记录（可能很大）|
-| traceId | TraceId（用于排查）|
-| costMs | 方法执行耗时 |
-| success | 是否成功 |
-| errorMsg | 失败时的错误消息 |
-
-## 3. 高级用法
-
-### 3.1 SpEL 自定义记录字段
-
-```java
-@PostMapping("/orders/{orderId}/approve")
-@OperationLog(
-    module = "ORDER",
-    action = "APPROVE",
-    description = "审批订单 #{#orderId}",
-    bizId = "#orderId",       // 业务 ID（用于关联）
-    bizType = "ORDER"
-)
-public Result approve(@PathVariable String orderId, @RequestBody ApproveRequest req) {
-    return Result.success(orderService.approve(orderId, req));
-}
-```
-
-### 3.2 异步写入
-
-```yaml
-# application.yml
-operation-log:
-  async: true
-  queue-size: 10000
-  batch-size: 100
-  flush-interval-ms: 1000
-```
-
-异步队列 + 批量写入 → 业务 RT 不受影响。
-
-### 3.3 同步写入（敏感操作）
-
-```java
-@PostMapping("/admin/users")
-@OperationLog(
-    module = "USER",
-    action = "CREATE_ADMIN",
-    sensitive = true,
-    sync = true    // 敏感操作同步写
-)
-public Result createAdmin(@RequestBody AdminDTO admin) {
-    return userService.createAdmin(admin);
-}
-```
-
-## 4. 日志表结构
-
-```sql
-CREATE TABLE t_operation_log (
-    id BIGINT PRIMARY KEY AUTO_INCREMENT,
-    module VARCHAR(50),              -- 模块
-    action VARCHAR(50),              -- 操作类型
-    description VARCHAR(500),        -- 描述
-    biz_id VARCHAR(100),             -- 业务 ID
-    biz_type VARCHAR(50),            -- 业务类型
-    user_id VARCHAR(50),             -- 操作人
-    user_name VARCHAR(100),
-    tenant_id VARCHAR(50),
-    client_ip VARCHAR(50),
-    user_agent VARCHAR(500),
-    request_url VARCHAR(500),
-    request_method VARCHAR(10),
-    request_params TEXT,             -- 请求参数（已脱敏）
-    response_data TEXT,              -- 响应（一般不记）
-    trace_id VARCHAR(50),
-    cost_ms INT,
-    success TINYINT,
-    error_msg TEXT,
-    sensitive TINYINT,
-    create_time DATETIME,
-    INDEX idx_module_create (module, create_time),
-    INDEX idx_user_create (user_id, create_time),
-    INDEX idx_biz (biz_type, biz_id)
-);
-```
-
-## 5. ❌ 反模式
-
-### 5.1 ❌ 写操作不记日志
-
-```java
-// ❌ 错：删除订单无日志
-@DeleteMapping("/orders/{id}")
-public Result delete(@PathVariable String id) {
-    orderService.delete(id);  // 谁删的？什么时候？不可追溯
-    return Result.success();
-}
-```
-
-✅ 加 `@OperationLog`。
-
-### 5.2 ❌ 同步阻塞写入
-
-```java
-// ❌ 错：每次操作同步写日志表 → 影响业务 RT
-logService.save(log);  // 同步 INSERT
-```
-
-✅ 异步队列批量写。
-
-### 5.3 ❌ 记录敏感参数
-
-```java
-// ❌ 错：日志里明文记录密码
-@OperationLog(module = "USER", action = "CREATE")
-public Result create(@RequestBody UserDTO user) {
-    // user.getPassword() 被自动记录 → 明文密码进日志
-}
-```
-
-✅ 用脱敏注解（详见 [sensitive-and-async.md](sensitive-and-async.md)）。
-
-## 6. 关联阅读
-
-- [sensitive-and-async.md](sensitive-and-async.md) — 脱敏与异步
-- [query-and-export.md](query-and-export.md) — 查询与导出
-- [SKILL.md](../SKILL.md)