makemd/.trae/README.md

# Trae 配置

> 📚 **详细文档请查阅**: `docs/` 目录
> - 业务蓝图: `docs/ARCHIVE/00_Business/` 或 `docs/LOOPS/`
> - 架构设计: `docs/ARCHIVE/01_Architecture/`
> - AI规范: `docs/ARCHIVE/05_AI/`
> - 治理规范: `docs/ARCHIVE/00_Business/Governance_Standards.md`

## 🚀 快速索引

### 项目特定规则 (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                      # 本文件
```

## 🔧 快速参考

| 规则类别 | 关键约束 | 违反后果 |
|---------|---------|---------|
| 数据存储 | 表前缀 `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. **协作必须声明占用**：先声明者优先

## 🤝 贡献

欢迎贡献规则配置和提出建议！请先阅读项目文档，然后提交 Pull Request。