makemd/archive/handover/project_rules.md

代码与提交规范

• 使用 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 是项目中唯一的物理表初始化入口（禁止新增其它初始化文件）。
  • 任何 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 批（上午分发、下午回收），回收后立即进行下一批一次性分发。