# ┌─────────────────────────────────────────────────────────────────┐
# │  电商订单管理系统 — 工程规范文档                                    │
# │  团队：订单研发团队（后端6人 + 前端3人 + QA2人 + DevOps1人）        │
# │  最后更新：2026-07-15                                             │
# │  仓库：git@company.com: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]