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

package/skills/meritdata-platform-code-review/references/guide.md

@@ -0,0 +1,173 @@
+# 代码审查基础指南（code-review）
+
+> Java 代码 4 维度审查：正确性 / 性能 / 安全 / 可维护性。
+
+---
+
+## 1. 4 维度清单
+
+### 1.1 正确性
+
+- [ ] 业务逻辑正确（边界、空值、状态机）
+- [ ] 异常处理完整（不吞异常 / 不空 catch）
+- [ ] 事务边界正确（@Transactional 范围）
+- [ ] 并发安全（线程安全集合、锁）
+
+### 1.2 性能
+
+- [ ] 无 N+1 查询
+- [ ] 无循环 DB / Feign
+- [ ] SQL 走索引
+- [ ] 缓存合理（key 带用户/租户）
+- [ ] 大对象不序列化
+
+### 1.3 安全
+
+- [ ] 无 SQL 拼接
+- [ ] 无 XSS（HTML 渲染转义）
+- [ ] 无越权（资源 + 数据权限）
+- [ ] 敏感数据脱敏（日志、响应）
+- [ ] 无硬编码密钥
+
+### 1.4 可维护性
+
+- [ ] 命名规范（类/方法/常量）
+- [ ] 方法长度 ≤ 50 行
+- [ ] 无重复代码
+- [ ] 注释解释"为什么"
+- [ ] 测试覆盖核心路径
+
+---
+
+## 2. 审查流程
+
+```
+PR 创建
+   ↓
+1. 自动 CI（编译、扫描、测试）
+   ↓
+2. Reviewer 审查
+   ↓ 评审
+3. 评论（必须含：行号 + 问题 + 建议）
+   ↓
+4. 修改 → 重新审查
+   ↓
+5. 批准 → 合并
+```
+
+### 2.1 评审评论模板
+
+```markdown
+**问题**：<具体问题>
+**位置**：<文件:行号>
+**影响**：<严重程度>
+**建议**：<修复方案 + 代码示例>
+**优先级**：🔴 阻断 / 🟠 必须 / 🟢 建议
+```
+
+## 3. 严重度
+
+| 等级 | 处理 | 例子 |
+|------|------|------|
+| 🔴 阻断 | 必须修复才能合并 | 内存泄漏、数据丢失、安全漏洞 |
+| 🟠 必须 | 必须修复（可在 follow-up）| 性能问题、命名错误 |
+| 🟢 建议 | 后续重构 | 重复代码、注释不全 |
+
+## 4. 评审检查清单
+
+### 4.1 Controller 层
+
+- [ ] URL 命名规范（名词、复数、连字符）
+- [ ] HTTP 方法正确（GET/POST/PUT/DELETE）
+- [ ] 响应包装（`Result.success(data)`）
+- [ ] 参数校验（@Valid + JSR-303）
+- [ ] 权限校验（@PreAuthorize）
+- [ ] 异常处理（@ExceptionHandler）
+- [ ] 文档注解（@OpenAPIDefinition）
+
+### 4.2 Service 层
+
+- [ ] 接口和实现分离（IXxxService / XxxServiceImpl）
+- [ ] 事务边界（@Transactional）
+- [ ] 业务校验（前置 + 后置）
+- [ ] 不在循环内调用外部资源
+- [ ] 不吞异常
+- [ ] 不返回 null（用空集合 / Optional）
+
+### 4.3 Repository 层
+
+- [ ] 方法命名（findXxx / listXxx / saveXxx）
+- [ ] 无 SQL 拼接
+- [ ] 无 N+1
+- [ ] 索引走通（EXPLAIN）
+- [ ] 软删除穿透（findXxxIncludingDeleted）
+
+### 4.4 通用
+
+- [ ] 无硬编码常量
+- [ ] 无死代码
+- [ ] 无过度嵌套（≤ 3 层）
+- [ ] 日志规范（INFO/WARN/ERROR 正确）
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 评审无依据
+
+```markdown
+// ❌ 错
+这段代码有问题。
+```
+
+```markdown
+// ✅ 正确
+**问题**：N+1 查询
+**位置**：OrderService.list():42
+**影响**：1000 订单 → 1000 次 Feign，RT 30s
+**建议**：用 userClient.listByIds 批量装配
+**优先级**：🔴
+```
+
+### 5.2 ❌ 评审不区分严重度
+
+```markdown
+// ❌ 错
+这个变量名不好。这段代码有 SQL 注入。这两个都得改。
+```
+
+✅ 区分 🔴 阻断 / 🟠 必须 / 🟢 建议。
+
+### 5.3 ❌ 评审不写建议
+
+```markdown
+// ❌ 错
+这个方法太长了。
+```
+
+```markdown
+// ✅ 正确
+**问题**：方法 80 行（>50）
+**建议**：拆成 validate + calculate + save 三个方法
+**优先级**：🟢
+```
+
+## 6. 评审效率
+
+### 6.1 时间
+
+- 简单 PR（< 200 行）：15-30 分钟
+- 中等 PR（200-500 行）：30-60 分钟
+- 复杂 PR（> 500 行）：拆分或多次评审
+
+### 6.2 多人评审
+
+大型 PR 可指定 2-3 个 Reviewer 分维度评审：
+
+- Reviewer A：正确性 + 性能
+- Reviewer B：安全 + 可维护性
+
+## 7. 关联阅读
+
+- [performance.md](performance.md) — 性能审查
+- [security.md](security.md) — 安全审查
+- [rules/code-dev-rules.md](../../rules/code-dev-rules.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-code-review/references/performance.md

@@ -0,0 +1,263 @@
+# 性能审查（code-review）
+
+> 性能维度审查清单：SQL / 缓存 / Feign / 循环 / 大对象。
+
+---
+
+## 1. SQL 性能
+
+### 1.1 必须走索引
+
+```sql
+-- ❌ 错：status 没建索引
+SELECT * FROM t_order WHERE status = 'PAID';
+
+-- ✅ 正确：建索引
+CREATE INDEX idx_t_order_status ON t_order(status);
+```
+
+### 1.2 ❌ SELECT *
+
+```java
+// ❌ 错
+@Query("SELECT o FROM Order o WHERE o.id = :id")
+Order findById(@Param("id") String id);
+
+// ✅ 正确：只查需要的字段
+@Query("SELECT new OrderDTO(o.id, o.orderNo, o.amount) FROM Order o WHERE o.id = :id")
+OrderDTO findDTOById(@Param("id") String id);
+```
+
+### 1.3 ❌ 大表全表扫描
+
+```sql
+-- ❌ 错：100 万行表，全表扫描
+SELECT * FROM t_order WHERE description LIKE '%关键词%';
+
+-- ✅ 正确：全文索引
+ALTER TABLE t_order ADD FULLTEXT INDEX ft_description(description);
+SELECT * FROM t_order WHERE MATCH(description) AGAINST('关键词');
+```
+
+### 1.4 EXPLAIN 验证
+
+```sql
+EXPLAIN SELECT * FROM t_order WHERE user_id = '10001';
+```
+
+关注：
+- `type`：ALL（扫表）→ ref/range（走索引）
+- `key`：实际使用的索引
+- `rows`：扫描行数
+- `Extra`：避免 Using filesort / Using temporary
+
+## 2. N+1 查询
+
+### 2.1 ❌ JPA 关联懒加载
+
+```java
+// ❌ 错：OneToMany 默认懒加载，循环访问触发 N+1
+@Entity
+public class Order {
+    @OneToMany
+    private List<OrderItem> items;
+}
+
+List<Order> orders = orderRepository.findAll();
+for (Order o : orders) {
+    o.getItems().size();  // 每次触发 SQL
+}
+```
+
+### 2.2 ✅ JOIN FETCH
+
+```java
+@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.userId = :userId")
+List<Order> findByUserIdWithItems(@Param("userId") String userId);
+```
+
+### 2.3 ✅ @EntityGraph
+
+```java
+@EntityGraph(attributePaths = {"items"})
+List<Order> findByUserId(String userId);
+```
+
+## 3. 循环内外部资源
+
+### 3.1 ❌ 循环内 DB
+
+```java
+// ❌ 错
+for (String id : ids) {
+    userRepository.findById(id);  // 100 次 SQL
+}
+
+// ✅ 正确
+userRepository.findAllById(ids);  // 1 次 SQL
+```
+
+### 3.2 ❌ 循环内 Feign
+
+```java
+// ❌ 错
+for (Order o : orders) {
+    o.setUserName(userClient.getById(o.getUserId()).getRealName());
+}
+
+// ✅ 正确：批量装配
+List<String> ids = orders.stream().map(Order::getUserId).distinct().collect(toList());
+Map<String, UserDTO> userMap = userClient.listByIds(ids).stream()
+    .collect(Collectors.toMap(UserDTO::getUserId, e -> e));
+orders.forEach(o -> o.setUserName(userMap.get(o.getUserId()).getRealName()));
+```
+
+### 3.3 ❌ 循环内 HTTP
+
+```java
+// ❌ 错：循环内发 HTTP
+for (String url : urls) {
+    httpClient.get(url);  // 100 次 HTTP
+}
+
+// ✅ 正确：并行
+List<CompletableFuture<String>> futures = urls.stream()
+    .map(url -> CompletableFuture.supplyAsync(() -> httpClient.get(url)))
+    .collect(toList());
+List<String> results = futures.stream().map(CompletableFuture::join).collect(toList());
+```
+
+## 4. 缓存
+
+### 4.1 ❌ 缓存 key 无隔离
+
+```java
+// ❌ 错：不同租户数据混淆
+@Cacheable(value = "user", key = "#userId")
+public UserDTO getById(String userId) { ... }
+
+// ✅ 正确
+@Cacheable(value = "user", key = "#userId + ':' + #tenantId")
+public UserDTO getById(String userId) { ... }
+```
+
+### 4.2 ❌ 缓存无 TTL
+
+```java
+// ❌ 错
+redisTemplate.opsForValue().set("key", "value");  // 永不过期
+
+// ✅ 正确
+redisTemplate.opsForValue().set("key", "value", Duration.ofMinutes(10));
+```
+
+### 4.3 ❌ 缓存大对象
+
+```java
+// ❌ 错：缓存 10MB 对象
+@Cacheable(value = "report", key = "#reportId")
+public List<Report> getReport(String reportId) {
+    return reportRepository.findAll();  // 10 万行
+}
+
+// ✅ 正确：分页 + 压缩
+@Cacheable(value = "report", key = "#reportId + ':' + #page")
+public Page<Report> getReportPage(String reportId, int page) { ... }
+```
+
+## 5. 大对象
+
+### 5.1 ❌ 序列化大对象到日志
+
+```java
+// ❌ 错
+log.info("订单详情：{}", JSON.toJSONString(order));  // 含 items / payment / log
+
+// ✅ 正确：只记录关键字段
+log.info("订单创建：orderNo={}, amount={}", order.getOrderNo(), order.getAmount());
+```
+
+### 5.2 ❌ 返回大对象
+
+```java
+// ❌ 错：返回全字段
+@GetMapping("/orders/{id}")
+public Order getById(@PathVariable String id) {
+    return orderRepository.findById(id).orElseThrow();
+}
+
+// ✅ 正确：返回 VO
+@GetMapping("/orders/{id}")
+public OrderVO getById(@PathVariable String id) {
+    return orderRepository.findById(id).map(OrderVO::from).orElseThrow();
+}
+```
+
+### 5.3 ❌ 在循环内创建大对象
+
+```java
+// ❌ 错
+for (int i = 0; i < 10000; i++) {
+    StringBuilder sb = new StringBuilder();  // 创建 1 万次
+}
+
+// ✅ 正确
+StringBuilder sb = new StringBuilder();
+for (int i = 0; i < 10000; i++) {
+    sb.append(i);
+}
+```
+
+## 6. 异步
+
+### 6.1 ❌ 同步阻塞
+
+```java
+// ❌ 错：审批后等消息发送
+@PostMapping("/approve")
+public Result approve(@RequestBody ApproveRequest req) {
+    orderService.approve(req);
+    smsClient.send(req.getMobile(), "审批通过");  // 等短信返回
+    emailClient.send(req.getEmail(), "审批通过");  // 等邮件返回
+    return Result.success();
+}
+
+// ✅ 正确
+@PostMapping("/approve")
+public Result approve(@RequestBody ApproveRequest req) {
+    orderService.approve(req);
+    // 异步发送
+    CompletableFuture.allOf(
+        CompletableFuture.runAsync(() -> smsClient.send(...)),
+        CompletableFuture.runAsync(() -> emailClient.send(...))
+    );
+    return Result.success();
+}
+```
+
+## 7. 监控指标
+
+审查后建议监控：
+- P50 / P95 / P99 响应时间
+- QPS / TPS
+- DB 连接池使用率
+- 缓存命中率
+- JVM 堆使用 / GC 暂停
+
+## 8. ❌ 反模式清单
+
+| 反模式 | 影响 |
+|--------|------|
+| N+1 查询 | 性能雪崩 |
+| 循环内 DB | 100x 慢 |
+| 循环内 Feign | 100x 慢 |
+| 缓存 key 无隔离 | 数据泄露 |
+| 缓存无 TTL | 内存泄漏 |
+| 大对象序列化 | GC 抖动 |
+| 同步阻塞 | 响应慢 |
+
+## 9. 关联阅读
+
+- [guide.md](guide.md) — 代码审查基础
+- [security.md](security.md) — 安全审查
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-code-review/references/security.md

@@ -0,0 +1,278 @@
+# 安全审查（code-review）
+
+> 安全维度审查清单：注入 / 越权 / 敏感 / CSRF / 上传。
+
+---
+
+## 1. SQL 注入
+
+### 1.1 ❌ 字符串拼接
+
+```java
+// ❌ 错：SQL 注入
+String sql = "SELECT * FROM t_user WHERE name = '" + name + "'";
+entityManager.createNativeQuery(sql).getResultList();
+```
+
+### 1.2 ✅ 预编译
+
+```java
+// ✅ 正确
+@Query("SELECT u FROM User u WHERE u.name = :name")
+List<User> findByName(@Param("name") String name);
+```
+
+### 1.3 ✅ MyBatis #{} 
+
+```xml
+<!-- ✅ 正确 -->
+<select id="findByName" resultType="User">
+    SELECT * FROM t_user WHERE name = #{name}
+</select>
+
+<!-- ❌ 错：${} 是字符串替换，有注入风险 -->
+<select id="findByName" resultType="User">
+    SELECT * FROM t_user WHERE name = '${name}'
+</select>
+```
+
+### 1.4 LIKE 特殊字符
+
+```java
+// ❌ 错：% 和 _ 没处理
+@Query("SELECT u FROM User u WHERE u.name LIKE :pattern")
+List<User> findByNameLike(@Param("pattern") String pattern);  // pattern = "%abc_%" 会匹配所有
+
+// ✅ 正确：转义
+String safe = pattern.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_");
+```
+
+## 2. XSS
+
+### 2.1 ❌ 不转义输出
+
+```html
+<!-- ❌ 错：用户输入直接渲染 -->
+<div th:utext="${user.comment}"></div>
+
+<!-- ✅ 正确 -->
+<div th:text="${user.comment}"></div>  <!-- th:text 自动转义 -->
+```
+
+### 2.2 前端转义
+
+```typescript
+// ❌ 错
+element.innerHTML = userInput;
+
+// ✅ 正确
+element.textContent = userInput;
+```
+
+## 3. 越权
+
+### 3.1 ❌ 不校验资源归属
+
+```java
+// ❌ 错：A 能删 B 的订单
+@DeleteMapping("/orders/{id}")
+public Result delete(@PathVariable String id) {
+    orderRepository.deleteById(id);  // 无权限校验
+    return Result.success();
+}
+
+// ✅ 正确
+@DeleteMapping("/orders/{id}")
+@PreAuthorize("hasAuthority('order:delete') and @orderAuth.canDelete(#id, authentication)")
+public Result delete(@PathVariable String id) {
+    orderRepository.deleteById(id);
+    return Result.success();
+}
+```
+
+### 3.2 ❌ 水平越权
+
+```java
+// ❌ 错：用户能查其他人的订单
+@GetMapping("/orders/{id}")
+public Order getById(@PathVariable String id) {
+    return orderRepository.findById(id).orElseThrow();  // 无归属校验
+}
+
+// ✅ 正确
+@GetMapping("/orders/{id}")
+public Order getById(@PathVariable String id) {
+    Order order = orderRepository.findById(id).orElseThrow();
+    if (!order.getUserId().equals(SecurityUtils.getCurrentUserId())) {
+        throw new ForbiddenException("无权查看");
+    }
+    return order;
+}
+```
+
+### 3.3 数据行级权限（用 DAM）
+
+详见 [data-classification](../meritdata-platform-data-classification/references/guide.md)。
+
+## 4. CSRF
+
+### 4.1 Spring Security CSRF
+
+```yaml
+security:
+  csrf:
+    enabled: true    # 默认开启
+```
+
+前端必须带 token：
+
+```typescript
+axios.post('/api/orders', data, {
+  headers: { 'X-CSRF-TOKEN': getCsrfToken() }
+});
+```
+
+### 4.2 状态修改必须非幂等方法
+
+```java
+// ❌ 错：用 GET 删除（CSRF 风险）
+@GetMapping("/delete/{id}")
+public Result delete(@PathVariable String id) { ... }
+
+// ✅ 正确：用 DELETE / POST
+@DeleteMapping("/{id}")
+public Result delete(@PathVariable String id) { ... }
+```
+
+## 5. 敏感信息
+
+### 5.1 ❌ 日志打印密码
+
+```java
+// ❌ 错
+log.info("用户登录：username={}, password={}", username, password);
+
+// ✅ 正确
+log.info("用户登录：username={}", username);
+```
+
+### 5.2 ❌ 硬编码密钥
+
+```java
+// ❌ 错
+private static final String SECRET_KEY = "mySecretKey123";
+
+// ✅ 正确
+@NacosValue(value = "${app.secret-key}", autoRefreshed = true)
+private String secretKey;
+```
+
+### 5.3 ❌ URL 传敏感信息
+
+```java
+// ❌ 错
+@GetMapping("/reset-password?token={token}")
+
+// ✅ 正确
+@PostMapping("/reset-password")
+public Result resetPassword(@RequestBody ResetPasswordRequest req) { ... }
+```
+
+### 5.4 ❌ 响应明文密码
+
+```java
+// ❌ 错
+@Data
+public class UserVO {
+    private String password;  // 明文密码
+}
+
+// ✅ 正确
+@Data
+public class UserVO {
+    private String username;
+    // 不返回 password
+}
+```
+
+## 6. 文件上传
+
+### 6.1 ❌ 不校验类型
+
+```java
+// ❌ 错：用户上传 .jsp 就能执行
+@PostMapping("/upload")
+public Result upload(@RequestParam MultipartFile file) {
+    file.transferTo(new File("/var/www/upload/" + file.getOriginalFilename()));
+    return Result.success();
+}
+
+// ✅ 正确
+@PostMapping("/upload")
+public Result upload(@RequestParam MultipartFile file) {
+    // 1. 校验大小
+    if (file.getSize() > 50 * 1024 * 1024) throw new BizException("文件过大");
+
+    // 2. 校验类型
+    String contentType = file.getContentType();
+    if (!ALLOWED_TYPES.contains(contentType)) throw new BizException("类型不允许");
+
+    // 3. 校验文件名
+    String safeName = sanitizeFilename(file.getOriginalFilename());
+
+    // 4. 存储
+    String url = storageService.upload(file.getBytes(), safeName);
+    return Result.success(url);
+}
+```
+
+### 6.2 ❌ 路径遍历
+
+```java
+// ❌ 错
+String path = "/var/www/upload/" + filename;  // filename = "../../etc/passwd"
+
+// ✅ 正确
+String baseName = FilenameUtils.getName(filename);  // 取文件名部分
+```
+
+## 7. 认证
+
+### 7.1 ❌ 失败提示过于详细
+
+```java
+// ❌ 错
+throw new BizException("用户不存在");  // 攻击者可枚举用户名
+throw new BizException("密码错误");    // 攻击者知道密码错了
+
+// ✅ 正确
+throw new BizException("用户名或密码错误");
+```
+
+### 7.2 ❌ Token 在 URL
+
+```java
+// ❌ 错
+@GetMapping("/api?token={token}")
+
+// ✅ 正确
+@RequestMapping(value = "/api", headers = "Authorization=Bearer xxx")
+```
+
+## 8. ❌ 反模式清单
+
+| 反模式 | 风险 |
+|--------|------|
+| SQL 拼接 | 注入 → 数据泄露 |
+| HTML 不转义 | XSS → 用户被攻击 |
+| 无权限校验 | 越权 → 数据泄露 |
+| 日志打印密码 | 凭据泄露 |
+| URL 传 token | token 被记录到日志 |
+| 文件上传不校验 | 木马 / WebShell |
+
+## 9. 关联阅读
+
+- [guide.md](guide.md) — 代码审查基础
+- [performance.md](performance.md) — 性能审查
+- [rules/security-rules.md](../../rules/security-rules.md)
+- [SKILL.md](../SKILL.md)