# 项目特定规则 (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生成代码规范](../docs/ai-generated-code-specification.md)

## 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 项目的特定规则，与通用编码规范分离管理。*