refactor(services): 重构服务文件结构，将服务按功能分类到不同目录

- 将服务文件按功能分类到core、ai、analytics、security等目录 - 修复logger导入路径问题，统一使用相对路径 - 更新相关文件的导入路径引用 - 添加新的批量操作组件导出文件 - 修复dashboard页面中的类型错误 - 添加dotenv依赖到package.json
2026-03-25 13:46:26 +08:00
parent e59d7c6620
commit 2748456d8a
598 changed files with 74404 additions and 9576 deletions
--- a/.trae/rules/project-specific-rules.md
+++ b/.trae/rules/project-specific-rules.md
@@ -3,10 +3,10 @@
 > 本文件包含 Crawlful Hub 项目的**硬性约束和配置**，所有代码必须遵守。
 > 
 > 📚 **详细文档请查阅**: `docs/` 目录
-> - 业务蓝图: `docs/00_Business/`
-> - 架构设计: `docs/01_Architecture/`
-> - AI规范: `docs/05_AI/`
-> - 治理规范: `docs/00_Business/Governance_Standards.md`
+> - 业务蓝图: `docs/ARCHIVE/00_Business/` 或 `docs/LOOPS/`
+> - 架构设计: `docs/ARCHIVE/01_Architecture/`
+> - AI规范: `docs/ARCHIVE/05_AI/`
+> - 治理规范: `docs/ARCHIVE/00_Business/Governance_Standards.md`

 ---

@@ -467,11 +467,86 @@ npx tsc --noEmit 2>&1 | Select-String -Pattern "^src/" | Measure-Object
 ```

 ### 12.6 详细文档
- [TypeScript 编译规约](../../docs/01_Architecture/13_TypeScript_Standards.md)
- [代码质量规范](../../docs/01_Architecture/14_Code_Quality_Standards.md)
- [Schema 驱动开发](../../docs/01_Architecture/15_Schema_Driven_Development.md)
- [统一类型管理](../../docs/01_Architecture/16_Unified_Type_Management.md)
- [TypeScript 错误修复方案](../../docs/05_AI/07_TypeScript_Error_Fix_Guide.md)
+
+- [Mock架构设计](../../docs/ARCHIVE/01_Architecture/Mock_Architecture.md)
+- [TypeScript 编译规约](../../docs/ARCHIVE/01_Architecture/13_TypeScript_Standards.md)
+- [代码质量规范](../../docs/ARCHIVE/01_Architecture/14_Code_Quality_Standards.md)
+- [Schema 驱动开发](../../docs/ARCHIVE/01_Architecture/15_Schema_Driven_Development.md)
+- [统一类型管理](../../docs/ARCHIVE/01_Architecture/16_Unified_Type_Management.md)
+- [TypeScript 错误修复方案](../../docs/ARCHIVE/05_AI/07_TypeScript_Error_Fix_Guide.md)
+
+---
+
+## 13. 错误处理与异常管理
+
+### 13.1 全局异常处理
+- **统一错误格式**: 所有 API 必须返回统一错误格式
+  ```typescript
+  interface ApiError {
+    code: string;      // 错误码，如 'ORDER_NOT_FOUND'
+    message: string;   // 错误信息
+    details?: unknown; // 详细信息
+    traceId: string;  // 追踪ID
+  }
+  ```
+- **HTTP状态码映射**:
+  - `400` - 参数错误
+  - `401` - 未授权
+  - `403` - 禁止访问
+  - `404` - 资源不存在
+  - `500` - 服务器内部错误
+
+### 13.2 错误码规范
+- **格式**: `[模块]_[类型]_[序号]`，如 `ORDER_PAYMENT_TIMEOUT_001`
+- **禁止**: 业务逻辑中直接 throw generic Error
+- **必须**: 使用自定义业务异常类
+
+### 13.3 事务回滚机制
+- **重要操作**: 订单创建、支付、退款等必须使用事务
+- **回滚策略**: 失败时必须回滚，确保数据一致性
+- **禁止**: 在事务外执行不可回滚的操作
+
+### 13.4 异常日志记录
+- **必须记录**: 异常堆栈、traceId、五元组信息
+- **禁止**: 在日志中记录敏感信息（密码、token等）
+
+---
+
+## 14. 日志管理
+
+### 15.1 日志级别
+| 级别 | 使用场景 |
+|------|---------|
+| DEBUG | 开发调试，，详细执行路径 |
+| INFO | 正常业务流程，如订单创建、状态流转 |
+| WARN | 潜在问题，如重试、熔断触发 |
+| ERROR | 错误异常，如API调用失败、数据库异常 |
+
+### 15.2 日志格式
+```typescript
+{
+  timestamp: string;      // ISO 8601
+  level: string;         // DEBUG/INFO/WARN/ERROR
+  traceId: string;       // 追踪ID
+  tenantId: string;
+  shopId: string;
+  taskId?: string;
+  service: string;       // 服务名称
+  method: string;        // 方法名
+  message: string;       // 日志消息
+  duration?: number;     // 执行时长(ms)
+  error?: ErrorInfo;     // 错误信息
+}
+```
+
+### 15.3 日志存储策略
+- **本地开发**: 控制台输出
+- **测试/生产**: 写入文件，按天轮转
+- **保留周期**: 测试环境 7 天，生产环境 30 天
+
+### 15.4 敏感信息保护
+- **禁止**: 在日志中记录密码、token、信用卡号
+- **脱敏**: 敏感字段必须脱敏后记录

 ---

@@ -490,8 +565,8 @@ npx tsc --noEmit 2>&1 | Select-String -Pattern "^src/" | Measure-Object
 | **协作防撞** | **必须声明占用，先声明优先** | **重复开发** |
 | **Mock规范** | **Mock数据必须隔离，禁止硬编码** | **AI上下文污染，维护困难** |
 | **TypeScript** | **禁止any，函数必须声明返回类型** | **类型安全丧失，运行时错误** |
-| **Schema驱动** | **类型从Schema推导，禁止手动定义** | **类型不一致，维护困难** |
-| **类型中心** | **所有类型从/types导入，禁止重复定义** | **类型重复，不一致** |
+| **错误处理** | **统一错误码，全局异常处理** | **错误扩散，难以追踪** |
+| **日志管理** | **日志级别/格式/存储策略** | **日志混乱，难以分析** |

 ---