chore: 清理归档文件和文档模板

删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
2026-03-18 01:21:15 +08:00
parent 56b8a2e2f8
commit 72cd7f6f45
147 changed files with 5982 additions and 16716 deletions
--- a/.trae/rules/project-specific-rules.md
+++ b/.trae/rules/project-specific-rules.md
@@ -1,132 +1,199 @@
 # 项目特定规则 (Project-Specific Rules)

-> 本文件包含 Crawlful Hub 项目的特定规则和配置
+> 本文件包含 Crawlful Hub 项目的**硬性约束和配置**，所有代码必须遵守。
+> 
+> 📚 **详细文档请查阅**: `docs/` 目录
+> - 业务蓝图: `docs/00_Business/`
+> - 架构设计: `docs/01_Architecture/`
+> - AI规范: `docs/05_AI/`
+> - 治理规范: `docs/00_Business/Governance_Standards.md`

 ---

-## 1. 数据与存储
+## 1. 数据与存储约束

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

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

- **消息类型**: 所有 message.type 统一在 `src/shared/types/messaging.ts` 声明
- **新增类型**: 必须在 background 与调用方同时适配，并补充最小冒烟测试
+### 3.1 消息类型声明
+- **统一入口**: `src/shared/types/messaging.ts`
+- **新增流程**: 
+  1. 在 messaging.ts 声明类型
+  2. background 与调用方同时适配
+  3. 补充最小冒烟测试

 ---

-## 4. 安全与权限规范
+## 4. 安全与权限

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

 ---

-## 5. AI生成代码规范 (AI-Generated Code)
+## 5. 架构与性能边界

-### 核心原则
- **AI优先开发**: 99%代码由AI生成，人工仅负责审核和微调
- **智能注释**: 每个服务类必须包含完整的JSDoc注释，明确标识任务ID和功能描述
- **自动同步**: 代码生成自动更新协作看板，实现代码驱动看板
+### 5.1 基础设施
+- **数据库**: 阿里云 RDS (MySQL 8.0)
+- **禁止**: 代码中执行 `DROP/TRUNCATE`
+- **要求**: 复杂查询必须通过 `EXPLAIN` 校验索引
+- **缓存**: 本地 Redis (6379 端口)
+- **队列**: 所有异步任务通过 BullMQ 走本地 Redis

-### 技术规范
- **服务类命名**: 统一使用`Service`后缀，避免`Manager`/`Helper`等后缀
- **代码结构**: 遵循标准服务类模式（表初始化 + 核心业务方法）
- **同步机制**: 使用`ai-sync-engine.js`实现自动同步
+### 5.2 单机资源保护
+- **内存**: Node.js 进程限制 `--max-old-space-size=4096`
+- **图片处理**: Sharp 必须开启 `sequentialRead`
+- **并发控制**: 
+  - API 速率限制基于本地 Redis
+  - Worker 并发数 ≤ 10

-### 详细规范
-> 详见：[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` 异步通信
+### 5.3 边界隔离
+- **禁止**: 跨 Domain 直接操作数据库模型
+- **必须**: 通过 `Service` 暴露接口或 `EventBus` 异步通信

 ---

-## 6. 1 (Brain) + 3 (Agents) 指挥与自省协议
+## 6. TOB 与套利专项约束

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

- **补全优先编码**: 标准命名、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`
+### 7.1 角色定位
+- **Brain**: 全局调度与决策
+- **Agent (AI-1/2/3)**: 原子任务包闭环开发
+
+### 7.2 自省要求
+Agent 必须在以下阶段上报"自我问题"：
+1. 对话开始时
+2. 执行过程中
+3. 交付前
+
+### 7.3 执行原则
+- **一次性分发**: 每轮下发完整任务包（P0/P1/P2）
+- **连续执行**: 任务包内连续执行到"完成或明确阻塞"
+- **文件占用锁**: 同目录协作先声明归属，"谁领取谁编辑"
+- **冲突处理**: 后写入方必须先 Read 最新内容，增量合并

 ---

-## 8. TOB 与套利专项约束
+## 8. 追踪与日志

- **套利口径统一**: 禁止仅用“售价-采购价”判断套利；必须使用净利公式（含平台费/物流/税费/汇率/售后/广告摊销）
- **利润红线强制执行**: B2B `<15%` 禁止放行，B2C `<20%` 必须进入风控审核
- **无 API 执行约束**: 无 API 平台必须走 `No-API Bridge` + `PENDING_REVIEW`，禁止全自动直发
- **Win 节点隔离约束**: 一店一执行上下文（profileDir/proxy/fingerprintPolicy），同店任务严格串行
- **企业交付底线**: 上线前必须具备租户隔离、审计追责、配额治理、SLA 指标可观测四项能力
+### 8.1 五元组必填
+所有任务与日志必须携带：
+```typescript
+{
+  tenantId: string;
+  shopId: string;
+  taskId: string;
+  traceId: string;
+  businessType: 'TOC' | 'TOB';
+}
+```
+
+### 8.2 状态机门禁
+- 发布、审核、对账流程必须落入统一 FSM
+- **禁止**: Controller 中硬编码流程分支

 ---

-## 9. 文档管理规范
+## 9. 代码质量门禁

- **命名规范**: 文件名必须使用小写短横线（kebab-case），如 `global-business-blueprint.md`
- **分类存放**: `docs/blueprints/` (全局业务蓝图)、`docs/benchmarks/` (行业标杆)、`docs/quality/` (质量保障)、`docs/governance/` (协同看板)
- **引用闭环**: 文档内引用必须使用完整 Markdown 链接，并确保 `README.md` 与 `doc-index.md` 的导航同步更新
- **原子化更新**: 每次功能变更必须同步更新对应的标杆规格或蓝图，确保 AGI “先验知识”的实时性
+### 9.1 命名规范
+- **服务类**: 统一使用 `Service` 后缀
+- **禁止**: `Manager`/`Helper` 等后缀
+
+### 9.2 注释规范
+- **必须**: 每个服务类包含完整 JSDoc
+- **必须**: 明确标识任务ID和功能描述
+
+### 9.3 部署标准
+`completed` 的标志：
+1. ✅ 数据库表已初始化
+2. ✅ 核心逻辑已闭环
+3. ✅ 通过 `GetDiagnostics` 校验

 ---

-## 10. 三AI同目录并行执行协议
+## 快速参考

- **一次性分发原则**: 每轮必须一次性下发完整任务包（P0/P1/P2），禁止仅下发单点任务
- **连续执行原则**: 每个 AI 在其任务包内必须连续执行到“完成或明确阻塞”才允许结束回合
- **停机条件白名单**: 仅允许外部依赖阻塞或已达到任务包验收标准并完成文档归档
- **文件占用锁**: 同目录协作时必须先声明文件归属，遵循“谁领取谁编辑”，避免并发覆盖
- **冲突处理**: 出现同文件冲突时，后写入方必须先 `Read` 最新内容并做增量合并，不得回滚他人变更
+| 规则类别 | 关键约束 | 违反后果 |
+|---------|---------|---------|
+| 数据存储 | 表前缀 `cf_`, 金额 `decimal(10,2)` | 数据不一致 |
+| 业务决策 | 必须 `PENDING_REVIEW` | 直接修改生产数据 |
+| 利润红线 | B2B<15%禁止, B2C<20%预警 | 财务风险 |
+| 安全权限 | 使用 `authorize()` 中间件 | 权限漏洞 |
+| 性能边界 | Worker并发≤10, 内存≤4GB | 系统崩溃 |
+| 追踪日志 | 五元组必填 | 无法追溯 |

 ---

-*本文件包含 Crawlful Hub 项目的特定规则，与通用编码规范分离管理。*
+*本文件仅包含硬性约束，详细规范请查阅 `docs/` 目录。*