wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
132 lines
7.4 KiB
Markdown
132 lines
7.4 KiB
Markdown
# 项目特定规则 (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 项目的特定规则，与通用编码规范分离管理。* |