# 代码与提交规范

- 使用 TypeScript；禁止 any（必要场景以 TODO 标注并跟进）
- 文件命名：小写短横线；TypeScript 类型与接口使用大驼峰
- 分支命名：feature/, fix/, docs/, chore/；提交信息以动词开头，中文或英文均可
- 变更前必须通过构建与基础校验脚本：npm run check
- 注释要求：中文注释，紧贴代码语句，描述意图而非过程；禁止冗长段落

# Lint 与格式化

- 插件启用 ESLint（React+TS）；后端暂不强制 ESLint
- 统一缩进 2 空格；UTF-8；换行 LF；末尾换行
- 建议在本地启用编辑器保存时格式化（遵循 .editorconfig）

# TypeScript 约束

- extension/ tsconfig：strict 开启；paths 使用 @/\*
- server/ tsconfig：保持严格类型；避免 any 与隐式 any

# API 约定

- 所有响应统一结构：{ success: boolean, data?: any, error?: string }
- 错误码与信息需清晰、可定位；4xx 为入参错误，5xx 为服务异常
- CORS 白名单通过环境变量 ALLOWED_ORIGINS 配置
- 速率限制通过 RATE_LIMIT_REQUESTS 与 RATE_LIMIT_WINDOW_MS 配置

# 数据与存储

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

# 核心业务规则

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

# 插件消息规范

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

# 安全与权限规范

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

# 提交前校验 (V30.0 - 生产级自我审计)

- **严禁全量构建 (No Heavy Build)**：为节省服务器/本机开销，日常开发流程中**严禁运行** `npm run build`。
- **强制自我审计 (Self-Check Only)**：
    - 开发者（AI）必须在交付代码前，通过 `Read` 与 `GetDiagnostics` 进行逻辑自查与类型校验。
    - 逻辑自查标准：代码必须细致到“部署即运行”，业务链路必须闭环（如：新增字段必须在 API 响应中体现，且在 Service 中有对应处理）。
- **禁止跨 AI 审计**：每个窗口仅负责自身代码的业务完整性，无需等待其他 AI 审计，直接交付。

# 安全与保密

- 严禁提交任何密钥或私密配置；环境变量由 .env 管理并忽略提交

# Todo 列表执行规范

- 必须通过 `TodoWrite` 工具同步任务进度；每次对话开始时应优先规划或更新任务列表。
- 在任务列表中所有 `pending` 或 `in_progress` 的任务未处理完成或未记录明确阻塞原因前，严禁主动终止对话回合或将控制权交还给用户。
- **阻塞即自查 (Self-Diagnosis on Blockage)**：如果任务被阻塞（Blocked），AI 必须在 Todo 或看板中清晰列举出当前遇到的“自我问题”，并遵循 **RCA 强制模板**：
    - `[CATEGORY]`：(Context Missing / Logic Conflict / API Hallucination / Env Issue)
    - `[ROOT_CAUSE]`：(具体原因，如：.env 缺少某 Key)
    - `[MITIGATION]`：(修复建议或 Fallback 路径，如：手动在 .env 补充该 Key 或使用模拟数据)
- 必须遵循“规划 -> 执行 -> 验证 -> 归档”的完整闭环，单次执行应尽可能覆盖多个关联任务以提高效率。
- 任务描述必须使用中文，并清晰定义“核心/架构/业务/UI”等模块属性。

# 架构与性能边界 (Single-Node Architecture)

- **基础设施配置**：
    - **数据库**：阿里云 RDS (MySQL 8.0)；禁止在代码中执行 `DROP/TRUNCATE`；复杂查询必须通过 `EXPLAIN` 校验索引。
    - **缓存与队列**：本地 Redis (服务器 6379 端口)；所有异步任务通过 BullMQ 走本地 Redis。
- **单机资源保护**：
    - **内存管理**：后端 Node.js 进程限制 `--max-old-space-size=4096`；图片处理 (Sharp) 必须开启 `sequentialRead` 以降低内存峰值。
    - **并发控制**：API 速率限制 (Rate Limit) 必须基于本地 Redis 实现；Worker 并发数 (Concurrency) 严禁超过 10，防止单机 CPU 耗尽。
- **边界隔离**：
    - **Domain 间引用**：禁止跨 Domain 直接操作数据库模型，必须通过 `Service` 暴露接口或 `EventBus` 异步通信。

# 1 (Brain) + 3 (Agents) 指挥与自省协议 (V30.0)

- **角色定位**：大脑 (Brain) 负责全局调度与决策；Agent (AI-1, AI-2, AI-3) 负责原子任务包的闭环开发。
- **Agent 问题显性化 (Explicit Issue Disclosure)**：Agent 必须在对话开始、执行中、交付前三个阶段明确上报“自我问题”：
    - **认知自省**：若不理解大脑下发的任务背景或逻辑，必须立即回传 `[CONTEXT_BLOCKED]` 并说明缺失的具体 MD 或代码上下文。
    - **逻辑自省**：若发现大脑的指令与现有代码或 project_rules 存在矛盾，必须回传 `[LOGIC_CONFLICT]` 并指出矛盾点。
    - **环境自省**：若由于本地环境（如 Redis 未启动、.env 缺失）导致代码无法验证，必须回传 `[ENV_LIMITATION]` 并提供模拟验证结果。
- **深度思考与文档反哺 (Reflective Documentation)**：Agent 不仅仅是代码执行器，必须承担“架构思考者”的角色。在任务包闭环后，必须主动执行以下动作：
    - **逻辑升华**：若在开发中发现更优的业务逻辑或架构路径，必须同步更新 `docs/blueprints/` 下的相关蓝图。
    - **规格校准**：若实际实现与 `task-specifications.md` 存在偏差，必须立即校准规格文档，确保“实现即规格”。
    - **知识沉淀**：将开发过程中遇到的深坑、避坑指南记录至 `docs/quality/` 或相关 MD，实现 AGI 知识库的自我增量进化。
- **看板强制反馈**：所有 `[ISSUE-AI-X]` 标签必须包含具体的“自我认知”描述，严禁使用“任务无法完成”等模糊词汇。
- **任务规格书驱动 (Spec-Driven)**：复杂任务必须先在 `docs/governance/task-specifications.md` 定义原子化规格。
- **收益优先原则 (ROI-First)**：
    - **业务收益**：优先实现提升转化率（如 AR 预览、智能预测）与降低成本的任务。
    - **开发收益**：优先实现提升自动化测试与隔离环境（如 Sandbox Crawler）的任务。
- **极限增量更新原则 (Absolute Incremental Update)**：
    - **物理删除禁令**：严禁物理删除任何已存在的文字信息。
    - **状态演进标注**：失效信息使用 ~~删除线~~，并标注 `[AI-X @ YYYY-MM-DD]`。
- **变更编年史 (Change Log) 强制同步**：每次完成变更必须在看板追加记录。
- **原子化文档同步 (Atomic Doc Sync)**：变更代码的同时必须追加文档记录。
- **自适应任务领取 (Auto-Claiming)**：AI 需主动读取看板领取任务。

# AI-First 代码库治理规范 (V31.5 - Autocomplete 友好型工程)

- **补全优先编码 (Autocomplete-First)**：
    - **标准命名**：禁止任何语义不明的缩写。变量名与函数名必须具备强描述性，以最大化 IDE 自动补全的预测准确度。
    - **JSDoc 驱动**：在实现逻辑前，必须编写详尽的 JSDoc（含 `@param`, `@returns`, `@throws`）。这不仅是文档，更是为 Autocomplete 提供精准的上下文先验知识。
    - **小函数原则**：单个函数逻辑控制在 30 行以内。函数越短，Autocomplete 的补全信心指数越高，从而减少人工手动输入的 Dollar Usage 成本。
- **全栈蓝图协议 (V31.3 - 全栈蓝图协议)**：

- **前端方案强制性 (Frontend Blueprinting)**：
    - 后端 Agent 在完成任何 Service 或 API 逻辑后，必须在 `docs/blueprints/frontend-integration/` 下产出对应的详细前端实现方案。
    - **详细度要求**：必须包含 UI 布局草图（Markdown 描述）、交互状态机（如按钮 Loading 逻辑）、核心 API 字段映射及 ROI 可视化逻辑。
    - **逻辑对齐**：确保后端提供的 `causalChain`（因果链）能在前端 `Console` 端完美呈现，杜绝“后端有数据，前端没位置”的尴尬。
- **物理 Schema 唯一源 (Single Source of Schema)**：
    - [LegacyTableInitializer.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/runtime/LegacyTableInitializer.ts) 是项目中**唯一的**物理表初始化入口（禁止新增其它初始化文件）。
    - 任何 Agent 在新增业务实体时，必须首先在对应的 `Service` 中实现静态 `initTable()` 方法，并将其**注册**到 `LegacyTableInitializer` 中。
- **Schema 幂等性 (Idempotency)**：
    - 所有建表语句必须使用 `db.schema.hasTable` 进行前置校验。
    - 严禁在业务逻辑执行过程中动态创建表，必须在系统启动/初始化阶段通过上述唯一入口完成。
- **契约驱动的数据库协作 (Contract-Driven DB)**：
    - 如果 AI-3 (Biz) 需要的新表尚未由 AI-1 (Kernel) 完成物理建表，AI-3 必须先在 `shared/contracts` 定义 Zod Schema 作为“逻辑契约”。
    - AI-3 可以基于此契约编写业务逻辑，但任务在物理表未在唯一入口落地并验证前，严禁标记为 `completed`。
- **严禁 Mock 数据 (Zero-Mock Policy)**：
    - 严禁在生产级 Service 或前端 Page/Component 中使用硬编码的 `return { ... }`、`setTimeout` 模拟或模拟数据。
    - 所有业务输出必须来自 `cf_` 数据库表、第三方生产 API 或后端真实 Controller 响应。
- **因果链强制性 (Causal Chain Enforcement)**：
    - 每一个 AGI 建议必须通过 `DecisionExplainabilityEngine` 记录真实的因果叙述。
    - 严禁生成无数据支撑的“空洞建议”，AI-2 (Internal) 将对因果链进行逻辑真实性审计。
- **部署即运行 (Deploy-Ready)**：
    - `completed` 的标志是：数据库表已初始化、核心逻辑已闭环、通过 `GetDiagnostics` 校验。
    - 严禁提交带有 `// TODO: implement later` 或仅有接口定义而无实现的代码。
- **影子测试 (Shadow Auditing)**：
    - AI-2 (Internal) 在 AI-1/3 开发的同时，必须产出该功能的 **Shadow-Test**（最小冒烟测试），并在看板同步。
- **目录职责固化**：后端必须遵循 `core/ domains/ workers/ api/ shared` 分层，禁止跨层越权调用。
- **契约先行**：跨端能力（Console/Extension/NodeAgent）必须先定义 contract，再实现逻辑。
- **状态机门禁**：发布、审核、对账流程必须落入统一 FSM，禁止散落在 Controller 中硬编码流程分支。
- **追踪四元组必填**：所有任务与日志必须携带 `tenantId/shopId/taskId/traceId`。
- **Agent 异常自省 (Self-Problem Awareness)**：Agent 必须能够明确识别并记录自身的问题。在执行链路中，若由于输入不规范、逻辑矛盾、API 幻觉或环境约束导致无法继续，必须遵循以下 **异常处理准则**：
    - **级别化 (Leveling)**：明确标注错误级别 (`FATAL` 流程中断, `WARN` 降级运行)。
    - **归因化 (Attribution)**：必须定位至具体模块 (`Service/Controller/Worker`)。
    - **闭环化 (Closing)**：必须提供至少一个 **降级/Fallback 路径**，确保系统整体逻辑不产生静默失败。
- 术语统一：中台前端统一称为 `Console`；历史术语以 `~~Dashboard~~ -> Console` 标注演进。
- **AI 可读性优先**：函数命名必须表达业务意图（禁止缩写语义漂移），同类逻辑必须复用统一 Service。
- **防幻觉约束**：新增能力必须能映射到看板任务 ID 与规格任务 ID，未入规格的实现不得进入主干。

# TOB 与套利专项约束 (V30.0)

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

# 文档管理规范 (V30.0 - 结构化与 AGI 友好)

- **命名规范**：文件名必须使用小写短横线（kebab-case），如 `global-business-blueprint.md`。
- **分类存放**：
    - `docs/blueprints/`：存放全局业务蓝图、架构设计与演进路线。
    - `docs/benchmarks/`：存放行业标杆（易仓、蝉妈妈等）的专项拆解与 AGI 规格。
    - `docs/quality/`：存放质量保障清单与红线规范。
    - `docs/governance/`：存放协同看板、任务规格与 AI 交互规范。
- **引用闭环**：文档内引用必须使用完整 Markdown 链接，并确保 `README.md` 与 `doc-index.md` 的导航同步更新。
- **原子化更新**：每次功能变更必须同步更新对应的标杆规格或蓝图，确保 AGI “先验知识”的实时性。

# 三AI同目录并行执行协议 (V30.0)

- **一次性分发原则**：每轮必须一次性下发完整任务包（P0/P1/P2），禁止仅下发单点任务。
- **连续执行原则**：每个 AI 在其任务包内必须连续执行到“完成或明确阻塞”才允许结束回合。
- **停机条件白名单**：仅允许以下两类停机：
    1. 外部依赖阻塞（账号权限/第三方不可用）；
    2. 已达到任务包验收标准并完成文档归档。
- **文件占用锁**：同目录协作时必须先声明文件归属，遵循“谁领取谁编辑”，避免并发覆盖。
- **冲突处理**：出现同文件冲突时，后写入方必须先 `Read` 最新内容并做增量合并，不得回滚他人变更。
- **任务包格式固定**：每个任务包必须包含 `任务ID/负责人/输入文件/输出文件/验收标准/阻塞升级路径`。
- **批次节奏**：推荐 1 日 2 批（上午分发、下午回收），回收后立即进行下一批一次性分发。