# 电商订单管理系统 — 工程规范文档

> 本文档由订单研发团队维护，最后更新于 2026 年 7 月。

## 项目背景

本项目是一个面向 B 端商家的电商订单管理系统，日均订单量约 50 万单。系统采用微服务架构，包含订单服务、支付服务、库存服务和物流服务四个核心模块。

技术栈：
- 后端：Java 17 + Spring Boot 3.2 + MyBatis-Plus
- 前端：React 18 + TypeScript 5.3 + Vite
- 数据库：MySQL 8.0 + Redis 7
- 消息队列：RocketMQ 5.x

## 团队介绍

订单研发团队目前有 12 人：
- 后端 6 人（含 1 名 Tech Lead）
- 前端 3 人
- QA 2 人
- DevOps 1 人

团队代码仓库：`git@company.com:order-team/oms.git`

## 一、安全相关规范

在 2026 Q2 的安全审计中，我们发现线上代码中存在硬编码的数据库密码，导致一次严重的安全事件。因此制定以下规范：

### 1.1 禁止硬编码凭证

severity: error
适用语言：JavaScript、TypeScript、Java

禁止在源码中硬编码密码、令牌、API Key 等敏感凭证。检测到疑似硬编码凭证时，请使用环境变量或密钥管理服务注入。

以下是一个**反面示例**（请勿模仿）：

```java
// ❌ 错误做法
public class DatabaseConfig {
    private String password = "Admin@123456";
    private String apiKey = "sk-abc123xyz";
}

// ✅ 正确做法
public class DatabaseConfig {
    @Value("${db.password}")
    private String password;
    
    @Value("${api.key}")
    private String apiKey;
}
```

### 1.2 禁止使用 eval()

severity: error
适用语言：JavaScript、TypeScript

上周代码审查中发现前端模块有 `eval()` 调用，存在代码注入风险。eval() 存在安全风险，请使用 JSON.parse() 或 Function 构造器替代。

```javascript
// ❌ 错误：使用 eval 解析用户输入
const data = eval(request.body);

// ✅ 正确：使用 JSON.parse
const data = JSON.parse(request.body);
```

### 1.3 禁止直接赋值 innerHTML

severity: warning

这是一条通用规则，适用于所有语言（因为各端都可能涉及 DOM 操作）。避免直接操作 innerHTML，请使用 textContent 或 DOMPurify 清洗。

相关讨论参见 [内部 Wiki: XSS 防护指南](https://wiki.internal/security/xss)

## 二、命名规范

> 以下命名规范参考了 Google Java Style Guide 和 Airbnb JavaScript Style Guide，根据团队实际情况做了调整。

### 2.1 常量命名

severity: warning
适用语言：JavaScript、TypeScript、Java

常量命名必须使用全大写加下划线（SCREAMING_SNAKE_CASE）。常量应使用全大写命名，如 MAX_RETRY_COUNT。

```java
// ❌ 错误
static final int maxRetry = 3;
static final String DbHost = "localhost";

// ✅ 正确
static final int MAX_RETRY = 3;
static final String DB_HOST = "localhost";
```

### 2.2 布尔变量前缀

severity: info
适用语言：JavaScript、TypeScript

布尔变量和方法名应以 is/has/can/should 开头。布尔变量建议添加 is/has/can/should 前缀以提升可读性。

```typescript
// ❌ 错误
let active = true;
let user = { verified: true };
function check(): boolean { ... }

// ✅ 正确
let isActive = true;
let user = { isVerified: true };
function canCheck(): boolean { ... }
```

## 三、性能规范

### 架构说明

订单服务采用 CQRS 模式，写操作走主库，读操作走从库。在高并发场景下，以下性能规范尤为重要。

### 3.1 禁止深层嵌套循环

severity: warning
适用语言：JavaScript、TypeScript、Java

禁止三层及以上嵌套循环，时间复杂度过高。检测到深层嵌套循环（≥3层）时，建议重构为扁平结构或使用查找表优化。

```javascript
// ❌ 错误：O(n³) 的订单匹配逻辑
for (const order of orders) {
    for (const item of order.items) {
        for (const warehouse of warehouses) {
            // 匹配逻辑...
        }
    }
}

// ✅ 正确：使用 Map 优化为 O(n)
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);
    }
}
```

### 3.2 异步函数内禁止同步 API

severity: warning
适用语言：JavaScript、TypeScript

异步函数内禁止调用同步阻塞 API。在 async 函数中调用同步 API 会阻塞事件循环，请改用异步版本。

### 2026-07-15 会议纪要

- 讨论了 Node.js 事件循环阻塞问题
- 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API
- 下个 Sprint 开始 Code Review 时执行

## 四、代码风格

### 4.1 函数显式类型注解

severity: info
适用语言：TypeScript

函数参数和返回值应显式标注 TypeScript 类型。建议为函数添加显式类型注解，提升类型安全性。

```typescript
// ❌ 错误
function createOrder(data) {
    return api.post('/orders', data);
}

// ✅ 正确
function createOrder(data: CreateOrderDTO): Promise<OrderResponse> {
    return api.post('/orders', data);
}
```

### 4.2 禁止魔法数字

severity: info
适用语言：JavaScript、TypeScript

禁止在代码中直接使用魔法数字，应提取为命名常量。检测到魔法数字，建议提取为具名常量以提升可维护性。

```javascript
// ❌ 错误
if (order.status === 3) { ... }
setTimeout(retry, 5000);

// ✅ 正确
const ORDER_STATUS_SHIPPED = 3;
const RETRY_DELAY_MS = 5000;
if (order.status === ORDER_STATUS_SHIPPED) { ... }
setTimeout(retry, RETRY_DELAY_MS);
```

## 五、团队约定

### 部署流程说明

部署流程参考 CI/CD Pipeline 文档。每周二、四发布，发布窗口为 14:00-16:00。

### 5.1 throw 语句携带上下文

severity: warning
适用语言：JavaScript、TypeScript、Java

throw 语句必须携带错误上下文信息。throw 时应提供足够的上下文信息，便于问题定位。

```java
// ❌ 错误
throw new RuntimeException("失败");
throw new Error("error");

// ✅ 正确
throw new OrderNotFoundException("订单不存在, orderId=" + orderId);
throw new PaymentFailedException("支付失败", cause);
```

### 5.2 禁止遗留 TODO 注释

severity: info
排除语言：SQL

生产代码中不应遗留 TODO/FIXME/HACK 注释。代码中发现 TODO/FIXME/HACK 注释，请在发布前处理。

> 注：SQL 脚本中允许临时性的 TODO 标记，因为数据库迁移脚本的生命周期与代码不同。

### 5.3 公共函数文档注释

severity: info
适用语言：JavaScript、TypeScript、Java

公共函数应添加文档注释（JSDoc / Javadoc）。公共函数缺少文档注释，建议补充说明用途、参数和返回值。

```java
/**
 * 创建订单
 * @param request 订单创建请求
 * @return 订单创建结果
 * @throws InsufficientStockException 库存不足时抛出
 */
public OrderResult createOrder(CreateOrderRequest request) { ... }
```

```typescript
/**
 * 获取用户订单列表
 * @param userId 用户ID
 * @param page 分页参数
 * @returns 订单列表
 */
function getUserOrders(userId: string, page: Pagination): Promise<Order[]> { ... }
```

## 附录

### A. 代码审查 Checklist

- [ ] 安全规范是否遵守
- [ ] 命名规范是否一致
- [ ] 性能是否有明显瓶颈
- [ ] 代码风格是否统一
- [ ] 团队约定是否遵循

### B. 相关链接

- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
- [TypeScript ESLint Rules](https://typescript-eslint.io/rules/)

### C. 版本历史

| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2026-06-01 | 张三 | 初版 |
| 1.1 | 2026-07-15 | 李四 | 新增性能规范 |
| 1.2 | 2026-08-01 | 王五 | 补充代码示例 |