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

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

@@ -1,263 +0,0 @@
-# 性能审查（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

@@ -1,278 +0,0 @@
-# 安全审查（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)

package/skills/meritdata-platform-code-spec/SKILL.md

@@ -1,36 +0,0 @@
----
-name: meritdata-platform-code-spec
-description: |
-  代码规范方法论（编码层）。写完二开 Java/SQL/接口代码后做强制规范自查；PR review 时逐项打钩。仅当"刚写完/要改一段二开代码、需要做规范门禁"时加载。
-  何时不用：写第一行代码前不知道从哪里开始（用 playbook）；阅读他人代码理解逻辑（用对应业务 skill）。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: low
-  layer: L2
-  sub-layer: L2-M
-  stack: methodology
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 代码规范方法论（code-spec）
-
-## 触发
-- 写完一段二开 Java 代码，提交前自查
-- PR review 需要逐项打钩
-- 准备生成 SQL / 接口代码，需要命名规范检查
-
-## 不触发
-- 写第一行代码前不知道从哪里开始 → 用 `meritdata-platform-playbook`
-- 阅读他人代码理解逻辑（不需要门禁）→ 用对应业务 skill
-- 纯前端样式 → 用 `meritdata-platform-frontend`
-
-## 前置约束
-- 所有铁律见 [rules/code-dev-rules.md §8.3](../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层)
-
-## 路由
-- 反模式案例 + 正模式代码 → [references/anti-patterns.md](references/anti-patterns.md)
-- CI 检测命令（bash / GitHub Actions）→ [references/validate-rules.md](references/validate-rules.md)