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

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

@@ -0,0 +1,178 @@
+# 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

@@ -0,0 +1,127 @@
+# 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

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

@@ -0,0 +1,175 @@
+# 操作日志基础指南（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)