makemd/.trae/rules/project-specific-rules.md

# 项目特定规则 (Project-Specific Rules)

> 本文件包含 Crawlful Hub 项目的**硬性约束和配置**，所有代码必须遵守。
> 
> 📚 **详细文档请查阅**: `docs/` 目录
> - 业务蓝图: `docs/ARCHIVE/00_Business/` 或 `docs/LOOPS/`
> - 架构设计: `docs/ARCHIVE/01_Architecture/`
> - AI规范: `docs/ARCHIVE/05_AI/`
> - 治理规范: `docs/ARCHIVE/00_Business/Governance_Standards.md`

---

## 1. 数据与存储约束

### 1.1 表命名规范
- **表前缀**: 所有表必须以 `cf_` 开头（如 `cf_product`, `cf_order`）
- **金额字段**: 必须使用 `decimal(10,2)`，禁止 float/double
- **物理属性单位**: 长度(cm), 重量(kg), 体积(m³)

### 1.2 数据完整性
- **唯一约束**: `cf_product` 表必须保证 (platform, productId) 唯一
- **JSON 处理**: images/skus/attributes 入库前序列化，出库解析
- **幂等性**: 所有建表语句必须使用 `db.schema.hasTable` 前置校验

---

## 2. 核心业务规则（硬性约束）

### 2.1 决策流程门禁
```
SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED
```
- **严禁**: Agent 直接修改核心业务数据（调价、退款、下单）
- **必须**: 人工在 Console 端确认后方可执行

### 2.2 计价与利润红线
- **计价收敛**: 所有价格计算必须走 `PricingService`
- **利润红线**:
  - B2B 利润率 < 15% → **禁止报价**
  - B2C 利润率 < 20% → **触发风控预警**
- **禁止**: Controller 或前端硬编码价格公式

### 2.3 订单限制
- **设备标记**: 所有设备必须标记 `Commercial Use Only`, `Non-Returnable`
- **地址限制**: 严禁处理住宅地址订单（轻B模式）

---

## 3. 插件技术规范

### 3.1 消息类型声明
- **统一入口**: `src/shared/types/messaging.ts`
- **新增流程**: 
  1. 在 messaging.ts 声明类型
  2. background 与调用方同时适配
  3. 补充最小冒烟测试

---

## 4. 安全与权限

### 4.1 RBAC 模型
- **预设角色**:
  - `ADMIN` - 全权
  - `MANAGER` - 运营主管
  - `OPERATOR` - 运营专员
  - `FINANCE` - 财务主管
  - `SOURCING` - 采购专家
  - `LOGISTICS` - 物流专家
  - `ANALYST` - 数据分析师

### 4.2 权限校验
- **强制**: 路由层使用 `authorize(permission)` 中间件
- **禁止**: Controller 中硬编码 `role === 'ADMIN'`
- **数据隔离**: 非 ADMIN 用户查询必须根据 `parentId` 层级过滤

---

## 5. 架构与性能边界

### 5.1 基础设施
- **数据库**: 阿里云 RDS (MySQL 8.0)
- **禁止**: 代码中执行 `DROP/TRUNCATE`
- **要求**: 复杂查询必须通过 `EXPLAIN` 校验索引
- **缓存**: 本地 Redis (6379 端口)
- **队列**: 所有异步任务通过 BullMQ 走本地 Redis

### 5.2 单机资源保护
- **内存**: Node.js 进程限制 `--max-old-space-size=4096`
- **图片处理**: Sharp 必须开启 `sequentialRead`
- **并发控制**: 
  - API 速率限制基于本地 Redis
  - Worker 并发数 ≤ 10

### 5.3 边界隔离
- **禁止**: 跨 Domain 直接操作数据库模型
- **必须**: 通过 `Service` 暴露接口或 `EventBus` 异步通信

---

## 6. TOB 与套利专项约束

### 6.1 套利计算口径
- **禁止**: 仅用 "售价 - 采购价" 判断套利
- **必须**: 使用净利公式（含平台费/物流/税费/汇率/售后/广告摊销）

### 6.2 利润红线强制执行
- B2B `<15%` → **禁止放行**
- B2C `<20%` → **必须进入风控审核**

### 6.3 无 API 平台约束
- **必须**: 走 `No-API Bridge` + `PENDING_REVIEW`
- **禁止**: 全自动直发

### 6.4 Win 节点隔离
- **一店一上下文**: profileDir/proxy/fingerprintPolicy
- **同店任务**: 严格串行执行

### 6.5 企业交付底线
上线前必须具备：
- ✅ 租户隔离
- ✅ 审计追责
- ✅ 配额治理
- ✅ SLA 指标可观测

---

## 7. AI 协作协议

### 7.1 角色定位
- **Brain**: 全局调度与决策
- **Agent (AI-1/2/3)**: 原子任务包闭环开发

### 7.2 自省要求
Agent 必须在以下阶段上报"自我问题"：
1. 对话开始时
2. 执行过程中
3. 交付前

### 7.3 执行原则
- **一次性分发**: 每轮下发完整任务包（P0/P1/P2）
- **连续执行**: 任务包内连续执行到"完成或明确阻塞"
- **文件占用锁**: 同目录协作先声明归属，"谁领取谁编辑"
- **冲突处理**: 后写入方必须先 Read 最新内容，增量合并

### 7.4 任务包领取机制（强制执行）

**核心原则**: 一次领取完整任务包，避免碎片化等待

#### 任务包定义
```
任务包 = 同一闭环的连续任务 + 依赖链完整 + 文件归属明确
```

#### 领取规则
1. **优先领取任务包**: 必须优先领取同一闭环的完整任务链
2. **最小粒度**: 单次领取不少于 2 个相关任务
3. **依赖自包含**: 领取的任务包内依赖必须闭环

#### 任务包类型
| 包类型 | 包含任务 | 示例 |
|--------|----------|------|
| 🔗 闭环包 | 同一业务闭环的全部任务 | BE-TOB001 + BE-TOB002 + BE-TOB003 |
| 📦 模块包 | 同一模块的连续任务 | FE-AD001 + FE-AD002 + FE-AD003 |
| 🔗 依赖链包 | 有依赖关系的任务链 | BE-P001 → BE-P002 → BE-P003 |

### 7.5 协作防撞车机制（强制执行）

#### 方案一：模块分区锁定
```
领取任务时，必须同时声明：
1. 占用的模块/闭环名称
2. 涉及的主要文件路径
3. 预计完成时间
```

#### 方案二：文件占用声明
在 Task_Overview.md 顶部维护 **🔒 当前占用区**：
```markdown
## 🔒 当前任务占用状态

| Agent | 占用模块 | 涉及任务 | 主要文件 | 开始时间 | 状态 |
|-------|----------|----------|----------|----------|------|
| AI-Backend-1 | B2B贸易闭环 | BE-TOB001~003 | B2BTradeService.ts | 2025-03-18 10:00 | 🔒 进行中 |
```

#### 方案三：冲突检测流程
```
Step 1: 领取前检查 Task_Overview.md 的 🔒占用区
Step 2: 确认目标模块未被占用
Step 3: 声明占用并更新状态
Step 4: 执行任务
Step 5: 完成后释放占用
```

#### 撞车处理优先级
1. **先声明者优先**: 先在 Task_Overview.md 声明占用的 Agent 拥有优先权
2. **后到者避让**: 后到的 Agent 必须选择其他模块
3. **协商解决**: 如有争议，由 Brain 协调分配

### 7.6 任务包领取模板

领取任务时，必须在 Task_Overview.md 更新以下信息：

```markdown
### 🔒 当前占用声明

**Agent**: [你的标识，如 AI-Backend-1]
**领取时间**: [YYYY-MM-DD HH:MM]
**任务包**: [任务ID列表，如 BE-TOB001, BE-TOB002, BE-TOB003]
**占用模块**: [模块名称，如 B2B贸易闭环]
**涉及文件**: 
- server/src/services/B2BTradeService.ts
- server/src/models/B2B.ts
- server/src/api/routes/trade.ts
**预计完成**: [预计完成时间]
```

### 7.7 禁止行为

- ❌ **禁止**: 单独领取任务包内的部分任务
- ❌ **禁止**: 不声明占用直接开始开发
- ❌ **禁止**: 跨模块同时占用多个任务包
- ❌ **禁止**: 占用超过 24 小时未释放

### 7.8 任务ID格式
- **格式**: `[模块]-[子模块][序号]`
- **模块**: FE(前端), BE(后端), PL(插件), AI(AI), DT(数据), OP(运维)
- **子模块**: P(商品), O(订单), F(财务), I(库存), C(采集), A(广告) 等
- **示例**: BE-P001, FE-O001, PL-C001

---

## 8. 逻辑集中化原则（硬性约束）

### 8.1 核心原则
> **逻辑集中化 → 服务驱动**：所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。

### 8.2 逻辑分散的表现（禁止行为）
- ❌ **Controller 中写业务逻辑**：Controller 只负责请求/响应和权限校验
- ❌ **前端直接写业务规则**：复杂计算、权限判断、状态流转禁止在 React 组件中实现
- ❌ **数据库操作分散**：不同模块禁止直接调用数据库，必须通过 Service 层
- ❌ **脚本或工具处理逻辑**：AI 任务或异步脚本必须通过 Service 层统一调用

### 8.3 逻辑分散的后果
1. **维护成本高**：AI 或开发者需要理解多个模块才能做一件改动
2. **修改容易出错**：改动一处可能引起其他模块逻辑不一致
3. **难以快速迭代**：新功能闭环难以接入，因为逻辑散落在各处
4. **收费闭环风险**：分散逻辑导致支付、权限、账单、状态不一致，直接影响收益
5. **AI 维护困难**：AI 无法一次性理解完整闭环，状态不一致，修改风险高

### 8.4 服务层职责（强制执行）
#### Controller 层职责
- 接收 HTTP 请求和参数验证
- 调用 Service 层处理业务逻辑
- 返回响应给前端
- 权限校验（通过 `authorize()` 中间件）

#### Service 层职责（核心）
- 业务逻辑编排和状态流转
- 多模块协同和数据一致性保证
- 事务管理和异常处理
- 调用 Repository 层或外部 API

#### Repository 层职责
- 数据库 CRUD 操作
- 数据模型映射
- 查询优化

### 8.5 状态管理统一
- **前端状态**：使用全局 Model 或状态管理库（Umi Model、Redux 等）
- **后端状态**：统一使用 STATE_MACHINE 定义的状态机
- **状态流转**：所有状态更新必须通过 Service 层，禁止在 Controller 或前端直接修改

### 8.6 核心逻辑复用
- **公共函数**：权限、价格、库存、账单等逻辑必须封装为公共函数或工具库
- **服务接口**：AI 只需调用 Service 接口，不直接处理业务逻辑
- **避免重复**：不同模块禁止重复实现相同逻辑

### 8.7 可视化业务流程
- **流程图**：为每个业务闭环绘制流程图，便于 AI 理解
- **状态机图**：使用 STATE_MACHINE 记录完整闭环
- **服务地图**：完善 SERVICE_MAP，明确服务调用链

### 8.8 违反逻辑集中化原则的后果
- **代码审查不通过**：任何违反逻辑集中化原则的代码将被拒绝合并
- **AI 任务失败**：AI 无法维护分散的逻辑，导致任务执行失败
- **生产环境风险**：分散逻辑导致数据不一致，直接影响系统稳定性

---

## 9. 追踪与日志

### 9.1 五元组必填
所有任务与日志必须携带：
```typescript
{
  tenantId: string;
  shopId: string;
  taskId: string;
  traceId: string;
  businessType: 'TOC' | 'TOB';
}
```

### 9.2 状态机门禁
- 发布、审核、对账流程必须落入统一 FSM
- **禁止**: Controller 中硬编码流程分支

---

## 10. 代码质量门禁

### 10.1 命名规范
- **服务类**: 统一使用 `Service` 后缀
- **禁止**: `Manager`/`Helper` 等后缀

### 10.2 注释规范
- **必须**: 每个服务类包含完整 JSDoc
- **必须**: 明确标识任务ID和功能描述

### 10.3 部署标准
`completed` 的标志：
1. ✅ 数据库表已初始化
2. ✅ 核心逻辑已闭环
3. ✅ 通过 `GetDiagnostics` 校验

### 10.4 文件规模限制
- **单文件**: ≤ 1500 行
- **单函数**: ≤ 120 行
- **UI 组件**: ≤ 300 行

---

## 11. Mock数据规范（AI上下文安全）

### 11.1 Mock数据原则

**核心目标**: 实现"不污染代码、AI上下文安全"的Mock方案

#### ❌ 禁止做法
- **硬编码Mock数据**: 在业务组件中直接写死数据
  ```typescript
  // 禁止！
  const data = [{ id: 1, name: 'Mock商品' }]
  ```
- **if判断切换**: 在业务代码中通过if判断切换Mock/真实数据
  ```typescript
  // 禁止！
  if (isDev) return mockData
  ```

#### ✅ 正确做法
- **DataSource抽象层**: 通过数据源抽象层获取数据
  ```typescript
  // 正确！
  const data = await certificateDataSource.list()
  ```
- **环境变量控制**: 通过 `REACT_APP_USE_MOCK` 环境变量控制
- **目录隔离**: 所有Mock文件必须放在 `/mock` 目录

### 11.2 Mock文件规范

#### 目录结构
```
/dashboard/src
  /mock                   ← 所有Mock相关
    /data                 ← Mock数据定义
    msw.ts                ← MSW配置
    browser.ts            ← 浏览器入口
    README.md             ← Mock使用说明
  /services               ← DataSource抽象层
    *DataSource.ts
```

#### 文件标记
所有Mock文件必须包含以下标记:
```typescript
/**
 * [MOCK-XXX] 功能描述
 * AI注意: 这是Mock实现，不是真实业务逻辑
 * 仅在USE_MOCK=true时启用
 */

// 或者

// [MOCK] 此文件为Mock数据，AI请勿当作真实业务逻辑
```

### 11.3 AI识别规则

AI在分析代码时:
- ✅ **忽略** `/mock` 目录下所有文件
- ✅ **忽略** 包含 `[MOCK]` 标记的文件
- ✅ **忽略** `__MOCK__` 变量为真的代码路径
- ✅ **优先** 分析 `/services` 下的DataSource层

### 11.4 环境变量

| 变量名 | 开发环境 | 生产环境 | 说明 |
|--------|----------|----------|------|
| REACT_APP_USE_MOCK | `true` | `false` | 前端Mock开关 |
| USE_MOCK | `true` | `false` | 后端Mock开关 |

### 11.5 参考文档

- [Mock架构设计](../../docs/01_Architecture/Mock_Architecture.md)
- [前端DataSource实现](../../dashboard/src/services/certificateDataSource.ts)

---

## 12. TypeScript 编译与类型安全（强制约束）

### 12.1 核心原则
- **禁止 any**: 所有代码禁止使用 `any` 类型，使用 `unknown` + 类型守卫
- **函数必须声明返回类型**: 所有函数必须显式声明返回类型
- **API 必须定义类型**: 所有 API 调用必须定义请求和响应类型
- **类型边界分层**: 接口层 → DTO层 → 业务层（Domain）

### 12.2 类型定义规范
- **禁止裸对象**: 所有对象必须有类型定义
- **Schema 驱动**: 类型必须从 Schema（zod）推导，禁止手动定义
- **统一类型中心**: 所有类型只从 `/types` 目录导入，禁止各模块重复定义

### 12.3 类型转换流程
```
API 返回数据 → Schema 验证 → DTO 转换 → Domain 模型
```
- **接口返回 = 不可信**: 必须经过 Schema 验证才能进入业务层
- **禁止直接使用**: 禁止在业务层直接使用 API 返回的原始数据

### 12.4 编译检查
- **编译错误 = 构建失败**: TypeScript 编译错误必须阻断 CI/CD
- **提交前检查**: 必须通过 `tsc --noEmit` 检查才能提交
- **ESLint 强制**: 必须通过 `@typescript-eslint` 规则检查

### 12.5 编译错误修复（当前 613 个错误）

#### 错误分布
| 错误类型 | 占比 | 优先级 |
|---------|------|--------|
| 类型不匹配 | 40% | 🔴 最高 |
| any 类型 | 25% | 🔴 最高 |
| 模块导入 | 15% | 🟡 中 |
| undefined/null | 10% | 🟡 中 |
| 配置问题 | 5% | 🟢 低 |
| 路径问题 | 5% | 🟢 低 |

#### 修复策略（分阶段）
1. **阶段 1（配置）**: 检查并修复 tsconfig.json 配置
2. **阶段 2（any）**: 消除所有 any 类型，使用 unknown + 类型守卫
3. **阶段 3（类型）**: 修复类型不匹配，确保所有函数声明返回类型
4. **阶段 4（模块）**: 统一模块导入导出，修复路径别名
5. **阶段 5（空值）**: 正确处理 undefined 和 null

#### 强制约束
- ❌ **禁止**: 使用 `// @ts-ignore` 忽略错误
- ❌ **禁止**: 使用 `// @ts-nocheck` 禁用检查
- ❌ **禁止**: 将类型改为 `any` 来"解决"错误
- ✅ **必须**: 每次修复后运行测试
- ✅ **必须**: 保持代码风格一致

#### 进度追踪
```bash
# 检查剩余错误数
npx tsc --noEmit 2>&1 | Select-String -Pattern "^src/" | Measure-Object
```

### 12.6 详细文档

- [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、信用卡号
- **脱敏**: 敏感字段必须脱敏后记录

---

## 快速参考

| 规则类别 | 关键约束 | 违反后果 |
|---------|---------|---------|
| 数据存储 | 表前缀 `cf_`, 金额 `decimal(10,2)` | 数据不一致 |
| 业务决策 | 必须 `PENDING_REVIEW` | 直接修改生产数据 |
| 利润红线 | B2B<15%禁止, B2C<20%预警 | 财务风险 |
| 安全权限 | 使用 `authorize()` 中间件 | 权限漏洞 |
| 性能边界 | Worker并发≤10, 内存≤4GB | 系统崩溃 |
| 追踪日志 | 五元组必填 | 无法追溯 |
| **逻辑集中化** | **所有业务逻辑必须在Service层** | **AI维护困难，数据不一致** |
| **任务领取** | **优先领任务包，最小2个任务** | **碎片化等待** |
| **协作防撞** | **必须声明占用，先声明优先** | **重复开发** |
| **Mock规范** | **Mock数据必须隔离，禁止硬编码** | **AI上下文污染，维护困难** |
| **TypeScript** | **禁止any，函数必须声明返回类型** | **类型安全丧失，运行时错误** |
| **错误处理** | **统一错误码，全局异常处理** | **错误扩散，难以追踪** |
| **日志管理** | **日志级别/格式/存储策略** | **日志混乱，难以分析** |

---

*本文件仅包含硬性约束，详细规范请查阅 `docs/` 目录。*