data: 自定义规则导入验证（3 场景 23 轮）+ 团队风格规则演示（5 规则全检出）

2026-09-08 19:51:34 +08:00
parent 4efe8ea512
commit ad576e807f
41 changed files with 2946 additions and 0 deletions
@@ -0,0 +1,225 @@
+# ┌─────────────────────────────────────────────────────────────────┐
+# │  电商订单管理系统 — 工程规范文档                                    │
+# │  团队：订单研发团队（后端6人 + 前端3人 + QA2人 + DevOps1人）        │
+# │  最后更新：2026-07-15                                             │
+# │  仓库：[email protected]:order-team/oms.git                        │
+# └─────────────────────────────────────────────────────────────────┘
+#
+# 项目背景：
+#   面向 B 端商家的电商订单管理系统，日均订单量约 50 万单。
+#   微服务架构：订单服务、支付服务、库存服务、物流服务。
+#   技术栈：Java 17 + Spring Boot 3.2 + React 18 + TypeScript 5.3
+#
+# 架构说明：
+#   订单服务采用 CQRS 模式，写操作走主库，读操作走从库。
+#   消息队列使用 RocketMQ 5.x。
+#
+# 2026-07-15 会议纪要：
+#   - 讨论了 Node.js 事件循环阻塞问题
+#   - 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API
+#   - 下个 Sprint 开始 Code Review 时执行
+#
+# 部署流程：
+#   每周二、四发布，发布窗口 14:00-16:00。
+#   CI/CD Pipeline 详见 Jenkins 配置。
+#
+# 代码审查 Checklist：
+#   [ ] 安全规范是否遵守
+#   [ ] 命名规范是否一致
+#   [ ] 性能是否有明显瓶颈
+#   [ ] 代码风格是否统一
+#   [ ] 团队约定是否遵循
+#
+# ── 安全类 ──────────────────────────────────────────────────────────
+#
+# 反面示例（请勿模仿）：
+#
+#   // Java: 硬编码密码
+#   public class DatabaseConfig {
+#       private String password = "Admin@123456";
+#   }
+#
+#   // JavaScript: 使用 eval
+#   const data = eval(request.body);
+#
+#   // JavaScript: innerHTML 赋值
+#   element.innerHTML = userInput;
+#
+# 正确做法：
+#
+#   @Value("${db.password}")
+#   private String password;
+#
+#   const data = JSON.parse(request.body);
+#
+#   element.textContent = userInput;
+#
+
+- id: no-hardcoded-credentials
+  severity: error
+  description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证
+  message: 检测到疑似硬编码凭证，请使用环境变量或密钥管理服务注入
+  languages: [javascript, typescript, java]
+
+- id: no-eval-usage
+  severity: error
+  description: 禁止使用 eval() 函数，存在代码注入风险
+  message: eval() 存在安全风险，请使用 JSON.parse() 或 Function 构造器替代
+  languages: [javascript, typescript]
+
+- id: no-innerhtml-assignment
+  severity: warning
+  description: 禁止直接赋值 innerHTML，可能导致 XSS
+  message: 避免直接操作 innerHTML，请使用 textContent 或 DOMPurify 清洗
+
+# ── 命名规范类 ──────────────────────────────────────────────────────
+#
+# 参考规范：
+#   - Google Java Style Guide
+#   - Airbnb JavaScript Style Guide
+#
+# 反面示例：
+#
+#   // 常量未使用大写
+#   static final int maxRetry = 3;
+#   static final String DbHost = "localhost";
+#
+#   // 布尔变量无前缀
+#   let active = true;
+#   function check(): boolean { ... }
+#
+# 正确做法：
+#
+#   static final int MAX_RETRY = 3;
+#   static final String DB_HOST = "localhost";
+#
+#   let isActive = true;
+#   function canCheck(): boolean { ... }
+#
+
+- id: require-constant-case
+  severity: warning
+  description: 常量命名必须使用全大写加下划线（SCREAMING_SNAKE_CASE）
+  message: 常量应使用全大写命名，如 MAX_RETRY_COUNT
+  languages: [javascript, typescript, java]
+
+- id: require-boolean-prefix
+  severity: info
+  description: 布尔变量和方法名应以 is/has/can/should 开头
+  message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性
+  languages: [javascript, typescript]
+
+# ── 性能类 ──────────────────────────────────────────────────────────
+#
+# 架构说明：
+#   订单服务采用 CQRS 模式，写操作走主库，读操作走从库。
+#   在高并发场景下，以下性能规范尤为重要。
+#
+# 反面示例：
+#
+#   // O(n³) 的订单匹配逻辑
+#   for (const order of orders) {
+#       for (const item of order.items) {
+#           for (const warehouse of warehouses) {
+#               // 匹配逻辑...
+#           }
+#       }
+#   }
+#
+# 正确做法：
+#
+#   const warehouseMap = new Map(warehouses.map(w => [w.id, w]));
+#   for (const order of orders) {
+#       for (const item of order.items) {
+#           const wh = warehouseMap.get(item.warehouseId);
+#       }
+#   }
+#
+
+- id: no-nested-loops-deep
+  severity: warning
+  description: 禁止三层及以上嵌套循环，时间复杂度过高
+  message: 检测到深层嵌套循环（≥3层），建议重构为扁平结构或使用查找表优化
+  languages: [javascript, typescript, java]
+
+- id: no-sync-in-async
+  severity: warning
+  description: 异步函数内禁止调用同步阻塞 API
+  message: 在 async 函数中调用同步 API 会阻塞事件循环，请改用异步版本
+  languages: [javascript, typescript]
+
+# ── 代码风格类 ──────────────────────────────────────────────────────
+#
+# 反面示例：
+#
+#   // 无类型注解
+#   function createOrder(data) {
+#       return api.post('/orders', data);
+#   }
+#
+#   // 魔法数字
+#   if (order.status === 3) { ... }
+#   setTimeout(retry, 5000);
+#
+# 正确做法：
+#
+#   function createOrder(data: CreateOrderDTO): Promise<OrderResponse> {
+#       return api.post('/orders', data);
+#   }
+#
+#   const ORDER_STATUS_SHIPPED = 3;
+#   const RETRY_DELAY_MS = 5000;
+#   if (order.status === ORDER_STATUS_SHIPPED) { ... }
+#   setTimeout(retry, RETRY_DELAY_MS);
+#
+
+- id: require-type-annotation
+  severity: info
+  description: 函数参数和返回值应显式标注 TypeScript 类型
+  message: 建议为函数添加显式类型注解，提升类型安全性
+  languages: [typescript]
+
+- id: no-magic-numbers
+  severity: info
+  description: 禁止在代码中直接使用魔法数字，应提取为命名常量
+  message: 检测到魔法数字，建议提取为具名常量以提升可维护性
+  languages: [javascript, typescript]
+
+# ── 团队约定类 ──────────────────────────────────────────────────────
+#
+# 部署流程说明：
+#   每周二、四发布，发布窗口 14:00-16:00。
+#
+# 反面示例：
+#
+#   throw new RuntimeException("失败");
+#   throw new Error("error");
+#
+# 正确做法：
+#
+#   throw new OrderNotFoundException("订单不存在, orderId=" + orderId);
+#   throw new PaymentFailedException("支付失败", cause);
+#
+# 版本历史：
+#   v1.0  2026-06-01  张三  初版
+#   v1.1  2026-07-15  李四  新增性能规范
+#   v1.2  2026-08-01  王五  补充代码示例
+#
+
+- id: require-error-context
+  severity: warning
+  description: throw 语句必须携带错误上下文信息
+  message: throw 时应提供足够的上下文信息，便于问题定位
+  languages: [javascript, typescript, java]
+
+- id: no-todo-in-production
+  severity: info
+  description: 生产代码中不应遗留 TODO/FIXME/HACK 注释
+  message: 代码中发现 TODO/FIXME/HACK 注释，请在发布前处理
+  excludeLanguages: [sql]
+
+- id: require-function-doc
+  severity: info
+  description: 公共函数应添加文档注释（JSDoc / Javadoc）
+  message: 公共函数缺少文档注释，建议补充说明用途、参数和返回值
+  languages: [javascript, typescript, java]