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

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

本文件包含 Crawlful Hub 项目的特定规则和配置

---

1. 数据与存储

• 表前缀: 所有数据库表必须以 cf_ 为前缀（如 cf_product, cf_order）
• 金额字段: 必须使用 decimal(10,2) 或更高精度，禁止使用 float/double
• 物理属性单位: 长度(cm), 重量(kg), 体积(m3)
• 唯一约束: cf_product 平台+productId 唯一约束；避免重复插入
• JSON 字段: images/skus/attributes 入库前序列化；出库解析

---

2. 核心业务规则

• 建议优先原则: 后端 Agent 严禁在未经人工审核的情况下直接修改核心业务数据（如调价、退款、下单）
• 流程门禁: 所有 Agent 决策必须遵循 SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED 状态机
• Console 决策闭环: Agent 仅负责生成“决策建议包”，必须由人工在 Console 端确认后方可执行
• 计价逻辑: 必须收敛于 PricingService，禁止在 Controller 或前端硬编码公式
• 利润红线: B2B 利润率 < 15% 禁止报价；B2C 利润率 < 20% 触发风控预警
• 设备标记: 所有设备必须标记：Commercial Use Only, Non-Returnable
• 订单限制: 严禁处理住宅地址订单（轻B模式）

---

3. 插件消息规范

• 消息类型: 所有 message.type 统一在 src/shared/types/messaging.ts 声明
• 新增类型: 必须在 background 与调用方同时适配，并补充最小冒烟测试

---

4. 安全与权限规范

• 权限模型: RBAC (基于角色的访问控制) + 颗粒度权限点 (如 order:read)
• 预设角色: ADMIN (全权), MANAGER (运营主管), OPERATOR (运营专员), FINANCE (财务主管), SOURCING (采购专家), LOGISTICS (物流专家), ANALYST (数据分析师)
• 权限校验: 路由层必须通过 authorize(permission) 中间件进行拦截，禁止在 Controller 中硬编码 role === 'ADMIN'
• 数据隔离: 非 ADMIN 用户在查询列表时必须根据 parentId 进行层级过滤，仅能看到自身及下属数据

---

5. AI生成代码规范 (AI-Generated Code)

核心原则

• AI优先开发: 99%代码由AI生成，人工仅负责审核和微调
• 智能注释: 每个服务类必须包含完整的JSDoc注释，明确标识任务ID和功能描述
• 自动同步: 代码生成自动更新协作看板，实现代码驱动看板

技术规范

• 服务类命名: 统一使用Service后缀，避免Manager/Helper等后缀
• 代码结构: 遵循标准服务类模式（表初始化 + 核心业务方法）
• 同步机制: 使用ai-sync-engine.js实现自动同步

详细规范

详见：AI生成代码规范

6. 架构与性能边界

基础设施配置

• 数据库: 阿里云 RDS (MySQL 8.0)；禁止在代码中执行 DROP/TRUNCATE；复杂查询必须通过 EXPLAIN 校验索引
• 缓存与队列: 本地 Redis (服务器 6379 端口)；所有异步任务通过 BullMQ 走本地 Redis

单机资源保护

• 内存管理: 后端 Node.js 进程限制 --max-old-space-size=4096；图片处理 (Sharp) 必须开启 sequentialRead
• 并发控制: API 速率限制必须基于本地 Redis 实现；Worker 并发数严禁超过 10

边界隔离

• Domain 间引用: 禁止跨 Domain 直接操作数据库模型，必须通过 Service 暴露接口或 EventBus 异步通信

---

6. 1 (Brain) + 3 (Agents) 指挥与自省协议

• 角色定位: 大脑 (Brain) 负责全局调度与决策；Agent (AI-1, AI-2, AI-3) 负责原子任务包的闭环开发
• Agent 问题显性化: 必须在对话开始、执行中、交付前三个阶段明确上报“自我问题”
• 深度思考与文档反哺: Agent 必须承担“架构思考者”的角色，在任务包闭环后主动更新相关文档
• 任务规格书驱动: 复杂任务必须先在 docs/governance/task-specifications.md 定义原子化规格
• 收益优先原则: 优先实现提升转化率与降低成本的任务
• 变更编年史: 每次完成变更必须在看板追加记录

---

7. AI-First 代码库治理规范

• 补全优先编码: 标准命名、JSDoc 驱动、小函数原则
• 前端方案强制性: 后端 Agent 在完成任何 Service 或 API 逻辑后，必须在 docs/blueprints/frontend-integration/ 下产出对应的详细前端实现方案
• 物理 Schema 唯一源: LegacyTableInitializer.ts 是项目中唯一的物理表初始化入口
• Schema 幂等性: 所有建表语句必须使用 db.schema.hasTable 进行前置校验
• 契约驱动的数据库协作: 新表未完成物理建表前，必须先定义 Zod Schema 作为“逻辑契约”
• 严禁 Mock 数据: 严禁在生产级 Service 或前端 Page/Component 中使用硬编码的模拟数据
• 因果链强制性: 每一个 AGI 建议必须通过 DecisionExplainabilityEngine 记录真实的因果叙述
• 部署即运行: completed 的标志是：数据库表已初始化、核心逻辑已闭环、通过 GetDiagnostics 校验
• 影子测试: AI-2 (Internal) 必须产出该功能的 Shadow-Test（最小冒烟测试）
• 目录职责固化: 后端必须遵循 core/ domains/ workers/ api/ shared 分层，禁止跨层越权调用
• 状态机门禁: 发布、审核、对账流程必须落入统一 FSM，禁止散落在 Controller 中硬编码流程分支
• 追踪四元组必填: 所有任务与日志必须携带 tenantId/shopId/taskId/traceId

---

8. TOB 与套利专项约束

• 套利口径统一: 禁止仅用“售价-采购价”判断套利；必须使用净利公式（含平台费/物流/税费/汇率/售后/广告摊销）
• 利润红线强制执行: B2B <15% 禁止放行，B2C <20% 必须进入风控审核
• 无 API 执行约束: 无 API 平台必须走 No-API Bridge + PENDING_REVIEW，禁止全自动直发
• Win 节点隔离约束: 一店一执行上下文（profileDir/proxy/fingerprintPolicy），同店任务严格串行
• 企业交付底线: 上线前必须具备租户隔离、审计追责、配额治理、SLA 指标可观测四项能力

---

9. 文档管理规范

• 命名规范: 文件名必须使用小写短横线（kebab-case），如 global-business-blueprint.md
• 分类存放: docs/blueprints/ (全局业务蓝图)、docs/benchmarks/ (行业标杆)、docs/quality/ (质量保障)、docs/governance/ (协同看板)
• 引用闭环: 文档内引用必须使用完整 Markdown 链接，并确保 README.md 与 doc-index.md 的导航同步更新
• 原子化更新: 每次功能变更必须同步更新对应的标杆规格或蓝图，确保 AGI “先验知识”的实时性

---

10. 三AI同目录并行执行协议

• 一次性分发原则: 每轮必须一次性下发完整任务包（P0/P1/P2），禁止仅下发单点任务
• 连续执行原则: 每个 AI 在其任务包内必须连续执行到“完成或明确阻塞”才允许结束回合
• 停机条件白名单: 仅允许外部依赖阻塞或已达到任务包验收标准并完成文档归档
• 文件占用锁: 同目录协作时必须先声明文件归属，遵循“谁领取谁编辑”，避免并发覆盖
• 冲突处理: 出现同文件冲突时，后写入方必须先 Read 最新内容并做增量合并，不得回滚他人变更

---

本文件包含 Crawlful Hub 项目的特定规则，与通用编码规范分离管理。