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

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

本文件包含 Crawlful Hub 项目的硬性约束和配置，所有代码必须遵守。

📚 详细文档请查阅: docs/ 目录

• 业务蓝图: docs/00_Business/
• 架构设计: docs/01_Architecture/
• AI规范: docs/05_AI/
• 治理规范: docs/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 顶部维护 🔒 当前占用区：

## 🔒 当前任务占用状态

| 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 更新以下信息：

### 🔒 当前占用声明

**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 小时未释放

---

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 五元组必填

所有任务与日志必须携带：

{
  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 校验

---

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

11.1 Mock数据原则

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

❌ 禁止做法

• 硬编码Mock数据: 在业务组件中直接写死数据

  // 禁止！
  const data = [{ id: 1, name: 'Mock商品' }]
  

• if判断切换: 在业务代码中通过if判断切换Mock/真实数据

  // 禁止！
  if (isDev) return mockData
  

✅ 正确做法

• DataSource抽象层: 通过数据源抽象层获取数据

  // 正确！
  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文件必须包含以下标记:

/**
 * [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架构设计
• 前端DataSource实现

---

快速参考

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

---

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