refactor(terminology): 统一术语标准并优化代码类型安全
- 将B2B统一为TOB术语 - 将状态值统一为大写格式 - 优化类型声明，避免使用any - 将float类型替换为decimal以提高精度 - 新增术语标准化文档 - 优化路由结构和菜单分类 - 添加TypeORM实体类 - 增强加密模块安全性 - 重构前端路由结构 - 完善任务模板和验收标准
This commit is contained in:
346
docs/06_Reports/Code_Review_Report_2026-03-20.md
Normal file
346
docs/06_Reports/Code_Review_Report_2026-03-20.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# 代码审查报告
|
||||
|
||||
**项目名称**: Crawlful Hub - 全球电商增长中台
|
||||
**审查日期**: 2026-03-20
|
||||
**审查范围**: 全项目源代码（Server / Dashboard / Extension / Client / Node-Agent）
|
||||
**审查标准**: 项目编码规范、TypeScript 最佳实践、安全标准、性能优化
|
||||
|
||||
---
|
||||
|
||||
## 执行摘要
|
||||
|
||||
本次审查覆盖了项目的 5 个主要模块，共审查了约 200+ 个源代码文件。发现以下关键问题：
|
||||
|
||||
| 类别 | 问题数量 | 严重程度 |
|
||||
|------|----------|----------|
|
||||
| TypeScript 编译错误 | 400+ | 🔴 严重 |
|
||||
| 数据类型违规（float/double） | 51 | 🔴 严重 |
|
||||
| 使用 `any` 类型 | 43 | 🟡 中等 |
|
||||
| TODO/FIXME 遗留 | 30 | 🟡 中等 |
|
||||
| 混合使用 console.log | 86 | 🟢 轻微 |
|
||||
| 安全密钥硬编码 | 1 | 🔴 严重 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 严重问题（需立即修复）
|
||||
|
||||
### 1.1 TypeScript 编译错误
|
||||
|
||||
**问题描述**: Server 模块存在 400+ 个 TypeScript 编译错误，导致项目无法正常构建。
|
||||
|
||||
**影响文件**:
|
||||
- `src/services/*.ts` (100+ 文件)
|
||||
- `src/domains/**/*.ts` (50+ 文件)
|
||||
- `src/core/**/*.ts` (30+ 文件)
|
||||
|
||||
**错误类型分布**:
|
||||
```
|
||||
- 类型不匹配错误: ~40%
|
||||
- 缺少类型声明: ~30%
|
||||
- 导入/导出错误: ~20%
|
||||
- 其他语法错误: ~10%
|
||||
```
|
||||
|
||||
**整改建议**:
|
||||
1. 运行 `npm run check` 获取完整错误列表
|
||||
2. 按模块分批修复，优先修复核心服务（Trade/Billing/Arbitrage）
|
||||
3. 添加缺失的类型声明文件
|
||||
4. 统一模块导入规范
|
||||
|
||||
### 1.2 金额字段使用 float/double（违反项目规范）
|
||||
|
||||
**问题描述**: 根据项目规则 1.1，金额字段必须使用 `decimal(10,2)`，但发现多处使用 `float`/`double`。
|
||||
|
||||
**违规文件列表**:
|
||||
| 文件路径 | 行号 | 违规代码 |
|
||||
|----------|------|----------|
|
||||
| `src/services/ProductService.ts` | 53 | `table.double('rating')` |
|
||||
| `src/core/runtime/LegacyTableInitializer.ts` | 321-322 | `table.float('daily_budget')` |
|
||||
| `src/domains/Arbitrage/ArbitrageService.ts` | 98-99 | `table.float('initial_profit_rate')` |
|
||||
| `src/domains/Billing/SLAGovernanceService.ts` | 108 | `table.float('p95_latency_ms')` |
|
||||
| `src/services/FXHedgingService.ts` | 40 | `table.float('volatility')` |
|
||||
|
||||
**整改建议**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
table.float('price')
|
||||
table.double('amount')
|
||||
|
||||
// ✅ 正确
|
||||
table.decimal('price', 10, 2)
|
||||
table.decimal('amount', 10, 2)
|
||||
```
|
||||
|
||||
### 1.3 安全密钥硬编码
|
||||
|
||||
**问题描述**: `VaultCrypto.ts` 中存在默认主密钥硬编码。
|
||||
|
||||
**文件**: `server/src/utils/VaultCrypto.ts`
|
||||
**行号**: 9
|
||||
```typescript
|
||||
private static MASTER_KEY = process.env.VAULT_MASTER_KEY || 'crawlful_default_master_key_32chars_';
|
||||
```
|
||||
|
||||
**风险**: 如果环境变量未设置，将使用可预测的默认密钥，严重危及凭证安全。
|
||||
|
||||
**整改建议**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
private static MASTER_KEY = process.env.VAULT_MASTER_KEY || 'default_key';
|
||||
|
||||
// ✅ 正确
|
||||
private static getMasterKey(): string {
|
||||
const key = process.env.VAULT_MASTER_KEY;
|
||||
if (!key) {
|
||||
throw new Error('VAULT_MASTER_KEY environment variable is required');
|
||||
}
|
||||
return key.padEnd(32).substring(0, 32);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 中等问题（建议修复）
|
||||
|
||||
### 2.1 过度使用 `any` 类型
|
||||
|
||||
**问题描述**: Dashboard 模块中存在 43 处 `any` 类型使用，削弱了 TypeScript 的类型安全。
|
||||
|
||||
**典型违规模式**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
const [dateRange, setDateRange] = useState(null as any);
|
||||
status: status as any,
|
||||
const response = await fetch(`${url}?${new URLSearchParams(params as any)}`);
|
||||
```
|
||||
|
||||
**整改建议**:
|
||||
```typescript
|
||||
// ✅ 正确
|
||||
import type { Dayjs } from 'dayjs';
|
||||
const [dateRange, setDateRange] = useState<[Dayjs, Dayjs] | null>(null);
|
||||
|
||||
// 定义明确的类型
|
||||
interface QueryParams {
|
||||
page: number;
|
||||
pageSize: number;
|
||||
status?: string;
|
||||
}
|
||||
const response = await fetch(`${url}?${new URLSearchParams(params as unknown as Record<string, string>)}`);
|
||||
```
|
||||
|
||||
### 2.2 TODO/FIXME 遗留项
|
||||
|
||||
**问题描述**: 发现 30 个 TODO/FIXME 注释，部分涉及核心功能缺失。
|
||||
|
||||
**关键遗留项**:
|
||||
| 文件 | 行号 | 描述 | 优先级 |
|
||||
|------|------|------|--------|
|
||||
| `OperationAgentService.ts` | 118 | 商品同步到数据库 | P0 |
|
||||
| `OperationAgentService.ts` | 167 | 订单同步到数据库 | P0 |
|
||||
| `PlatformApiService.ts` | 204-214 | Amazon SP-API 同步 | P1 |
|
||||
| `dynamicPricing.ts` | 261 | analyzeCompetitorPrices 方法 | P1 |
|
||||
| `SummaryAggregationService.ts` | 125-126 | 真实成本/利润接入 | P1 |
|
||||
|
||||
### 2.3 混合使用 console.log
|
||||
|
||||
**问题描述**: 86 个文件混合使用 `console.log/warn/error`，与统一的 logger 服务并存。
|
||||
|
||||
**整改建议**:
|
||||
统一使用项目提供的 logger 服务：
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
console.log('[INFO] Message', data);
|
||||
console.error('[ERROR] Message', error);
|
||||
|
||||
// ✅ 正确
|
||||
import { logger } from '../utils/logger';
|
||||
logger.info('Message', data);
|
||||
logger.error('Message', error);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 代码风格问题
|
||||
|
||||
### 3.1 命名规范
|
||||
|
||||
**总体情况**: 命名规范执行良好，符合项目规则。
|
||||
|
||||
**亮点**:
|
||||
- 服务类统一使用 `Service` 后缀 ✅
|
||||
- 表名统一使用 `cf_` 前缀 ✅
|
||||
- 数据库字段使用下划线命名 ✅
|
||||
|
||||
**改进空间**:
|
||||
- 部分接口命名不一致（如 `PurchaseOrder` vs `SalesOrder`）
|
||||
- 建议统一使用 PascalCase 命名接口
|
||||
|
||||
### 3.2 注释规范
|
||||
|
||||
**亮点**:
|
||||
- 核心业务服务包含 JSDoc 注释 ✅
|
||||
- 任务 ID 标记清晰（如 `[BIZ_TRADE_01]`）✅
|
||||
|
||||
**改进空间**:
|
||||
- 部分工具函数缺少注释
|
||||
- 建议复杂算法添加实现说明
|
||||
|
||||
### 3.3 文件组织
|
||||
|
||||
**亮点**:
|
||||
- Mock 数据隔离在 `/mock` 目录 ✅
|
||||
- 类型定义集中在 `types/` 目录 ✅
|
||||
- 领域驱动设计分层清晰 ✅
|
||||
|
||||
---
|
||||
|
||||
## 4. 架构合规性审查
|
||||
|
||||
### 4.1 逻辑集中化原则
|
||||
|
||||
**审查结果**: 整体符合逻辑集中化原则
|
||||
|
||||
**符合项**:
|
||||
- 业务逻辑集中在 Service 层 ✅
|
||||
- Controller 只负责请求/响应 ✅
|
||||
- 通过 Service 暴露接口 ✅
|
||||
|
||||
**建议**:
|
||||
- 部分 Controller 中仍有少量业务逻辑，建议迁移到 Service
|
||||
|
||||
### 4.2 数据完整性
|
||||
|
||||
**审查结果**: 基本符合规范
|
||||
|
||||
**符合项**:
|
||||
- 使用 `hasTable` 前置校验 ✅
|
||||
- JSON 字段序列化处理 ✅
|
||||
|
||||
**违规项**:
|
||||
- 金额字段使用 float/double（见 1.2）
|
||||
|
||||
### 4.3 RBAC 权限控制
|
||||
|
||||
**审查结果**: 符合规范
|
||||
|
||||
**符合项**:
|
||||
- 使用 `requirePermission` 中间件 ✅
|
||||
- 路由层权限控制 ✅
|
||||
- 无硬编码 `role === 'ADMIN'` ✅
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全审查
|
||||
|
||||
### 5.1 认证与授权
|
||||
|
||||
**审查结果**: 符合规范
|
||||
|
||||
- JWT Token 验证 ✅
|
||||
- MFA 双因素认证 ✅
|
||||
- OAuth2 支持 ✅
|
||||
|
||||
### 5.2 数据加密
|
||||
|
||||
**审查结果**: 存在风险
|
||||
|
||||
- VaultCrypto 实现正确 ✅
|
||||
- 默认密钥硬编码 ❌（见 1.3）
|
||||
|
||||
### 5.3 输入验证
|
||||
|
||||
**审查结果**: 需要加强
|
||||
|
||||
- 部分 API 缺少输入参数校验
|
||||
- 建议统一使用 Zod 进行参数验证
|
||||
|
||||
---
|
||||
|
||||
## 6. 性能审查
|
||||
|
||||
### 6.1 数据库查询
|
||||
|
||||
**审查结果**: 需要优化
|
||||
|
||||
**建议**:
|
||||
- 复杂查询需通过 `EXPLAIN` 校验索引
|
||||
- 批量操作建议分批处理（见 TODO 项）
|
||||
|
||||
### 6.2 缓存使用
|
||||
|
||||
**审查结果**: 符合规范
|
||||
|
||||
- Redis 缓存使用正确 ✅
|
||||
- 本地缓存策略合理 ✅
|
||||
|
||||
### 6.3 并发控制
|
||||
|
||||
**审查结果**: 符合规范
|
||||
|
||||
- Worker 并发数 ≤ 10 ✅
|
||||
- API 速率限制 ✅
|
||||
|
||||
---
|
||||
|
||||
## 7. 整改建议优先级
|
||||
|
||||
### P0（立即修复）
|
||||
1. 修复 TypeScript 编译错误（400+）
|
||||
2. 修复金额字段类型（51 处 float/double → decimal）
|
||||
3. 移除 VaultCrypto 默认密钥硬编码
|
||||
|
||||
### P1（本周修复）
|
||||
4. 完成核心 TODO 项（商品/订单同步）
|
||||
5. 减少 `any` 类型使用（43 处）
|
||||
6. 统一 logger 使用（86 处 console.log）
|
||||
|
||||
### P2（本月修复）
|
||||
7. 完善输入参数验证
|
||||
8. 优化数据库查询索引
|
||||
9. 补充单元测试覆盖率
|
||||
|
||||
---
|
||||
|
||||
## 8. 附录
|
||||
|
||||
### 8.1 项目结构统计
|
||||
|
||||
```
|
||||
server/src/
|
||||
├── api/routes/ 40+ 路由文件
|
||||
├── domains/ 8+ 领域模块
|
||||
├── services/ 100+ 服务文件
|
||||
├── core/ 30+ 核心模块
|
||||
├── utils/ 20+ 工具文件
|
||||
└── tests/ 15+ 测试文件
|
||||
|
||||
dashboard/src/
|
||||
├── pages/ 40+ 页面组件
|
||||
├── services/ 20+ 数据源服务
|
||||
├── components/ 15+ UI组件
|
||||
└── types/ 类型定义
|
||||
|
||||
extension/src/
|
||||
├── background/ 10+ 后台服务
|
||||
├── content/ 内容脚本
|
||||
└── utils/ 工具类
|
||||
```
|
||||
|
||||
### 8.2 合规检查清单
|
||||
|
||||
| 检查项 | 状态 | 备注 |
|
||||
|--------|------|------|
|
||||
| 表前缀 `cf_` | ✅ | 全部符合 |
|
||||
| 金额字段 `decimal(10,2)` | ❌ | 51 处违规 |
|
||||
| 服务类 `Service` 后缀 | ✅ | 全部符合 |
|
||||
| 权限 `authorize()` 中间件 | ✅ | 全部符合 |
|
||||
| 五元组追踪 | ✅ | 核心服务已实施 |
|
||||
| 状态机 FSM | ✅ | 核心流程已实施 |
|
||||
| 逻辑集中化 | ✅ | 整体符合 |
|
||||
|
||||
---
|
||||
|
||||
**报告生成时间**: 2026-03-20
|
||||
**审查工具**: TypeScript Compiler, ESLint, 人工审查
|
||||
**下次审查建议**: 修复 P0 问题后进行复查
|
||||
Reference in New Issue
Block a user