wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 将服务文件按功能分类到core、ai、analytics、security等目录
- 修复logger导入路径问题，统一使用相对路径
- 更新相关文件的导入路径引用
- 添加新的批量操作组件导出文件
- 修复dashboard页面中的类型错误
- 添加dotenv依赖到package.json
This commit is contained in:
wurenzhi
2026-03-25 13:46:26 +08:00
parent e59d7c6620
commit 2748456d8a
598 changed files with 74404 additions and 9576 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
.trae/README.md
View File

@@ -1,30 +1,66 @@
# Trae 配置
## 📋 项目简介
> 📚 **详细文档请查阅**: `docs/` 目录
> - 业务蓝图: `docs/ARCHIVE/00_Business/` 或 `docs/LOOPS/`
> - 架构设计: `docs/ARCHIVE/01_Architecture/`
> - AI规范: `docs/ARCHIVE/05_AI/`
> - 治理规范: `docs/ARCHIVE/00_Business/Governance_Standards.md`
本目录包含 Trae IDE 相关的配置文件，主要用于项目特定规则的定义。
## 🚀 快速索引
## 🚀 核心文件
### 项目特定规则 (rules/project-specific-rules.md)
### 1. 项目特定规则
- **文件**: `rules/project-specific-rules.md`
- **功能**: 定义项目的硬性约束和配置
- **内容**: 数据存储约束、业务规则、技术规范、安全权限等
本文件包含 **Crawlful Hub** 项目的硬性约束和配置，所有代码必须遵守：
| 章节 | 关键约束 |
|------|---------|
| **1. 数据与存储约束** | 表前缀 `cf_`, 金额 `decimal(10,2)`, 物理单位 |
| **2. 核心业务规则** | 决策门禁 `PENDING_REVIEW`, 利润红线 B2B<15%/B2C<20% |
| **3. 插件技术规范** | 消息类型统一入口 `messaging.ts` |
| **4. 安全与权限** | RBAC模型, `authorize()` 中间件, 数据隔离 |
| **5. 架构与性能边界** | 单机 Worker≤10, 内存≤4GB, BullMQ队列 |
| **6. TOB与套利专项** | 净利公式, No-API Bridge + PENDING_REVIEW |
| **7. AI协作协议** | 任务包领取(最小2个), 防撞车机制, 文件占用锁 |
| **8. 逻辑集中化原则** | 所有业务逻辑必须在Service层 |
| **9. 追踪与日志** | 五元组必填 (tenantId/shopId/taskId/traceId/businessType) |
| **10. 代码质量门禁** | 服务类 `Service` 后缀, 单文件≤1500行 |
| **11. Mock数据规范** | 禁止硬编码Mock, DataSource抽象层 |
| **12. TypeScript类型安全** | 禁止any, 函数声明返回类型, Schema驱动 |
| **13. 错误处理与异常** | 统一错误码, 全局异常处理, 事务回滚 |
| **14. 日志管理** | 日志级别(DEBUG/INFO/WARN/ERROR), 格式, 存储策略 |
## 📁 项目结构
```
.trae/
├── rules/ # 规则配置
│ └── project-specific-rules.md # 项目特定规则
└── README.md # 项目说明
├── rules/
│ └── project-specific-rules.md # 项目特定规则（硬性约束）
└── README.md # 本文件
```
## 🔧 使用规范
## 🔧 快速参考
- 所有代码必须遵守项目特定规则
- 规则文件应定期更新以适应项目需求
- 新加入项目的开发者应仔细阅读规则文件
| 规则类别 | 关键约束 | 违反后果 |
|---------|---------|---------|
| 数据存储 | 表前缀 `cf_`, 金额 `decimal(10,2)` | 数据不一致 |
| 业务决策 | 必须 `PENDING_REVIEW` | 直接修改生产数据 |
| 利润红线 | B2B<15%禁止, B2C<20%预警 | 财务风险 |
| 安全权限 | 使用 `authorize()` 中间件 | 权限漏洞 |
| 性能边界 | Worker并发≤10, 内存≤4GB | 系统崩溃 |
| 追踪日志 | 五元组必填 | 无法追溯 |
| **逻辑集中化** | **所有业务逻辑必须在Service层** | **AI维护困难，数据不一致** |
| **任务领取** | **优先领任务包，最小2个任务** | **碎片化等待** |
| **协作防撞** | **必须声明占用，先声明优先** | **重复开发** |
| **Mock规范** | **Mock数据必须隔离，禁止硬编码** | **AI上下文污染** |
| **TypeScript** | **禁止any，函数必须声明返回类型** | **类型安全丧失** |
| **错误处理** | **统一错误码，全局异常处理** | **错误扩散，难以追踪** |
| **日志管理** | **日志级别/格式/存储策略** | **日志混乱，难以分析** |
## ⚠️ AI 必读
1. **所有代码必须遵守 project-specific-rules.md 中的硬性约束**
2. **逻辑集中化是核心原则**：业务逻辑必须集中在 Service 层
3. **任务领取必须完整**：单次领取不少于 2 个相关任务
4. **协作必须声明占用**：先声明者优先
## 🤝 贡献

97
.trae/rules/project-specific-rules.md
View File

@@ -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导入，禁止重复定义** | **类型重复，不一致** |
| **错误处理** | **统一错误码，全局异常处理** | **错误扩散，难以追踪** |
| **日志管理** | **日志级别/格式/存储策略** | **日志混乱，难以分析** |
---