347 lines
8.8 KiB
Markdown
347 lines
8.8 KiB
Markdown
|
# 代码审查报告
|
|||
|
|
|
|||
|
|
**项目名称**: 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 问题后进行复查
|