wurenzhi
037e412aad
新增广告计划、用户资产、B2B交易、合规规则等核心模型 实现爬虫工作器、贸易服务、现金流预测等业务服务 添加RBAC权限测试、压力测试等测试用例 完善扩展程序的消息处理与内容脚本功能 重构应用入口与文档生成器 更新项目规则与业务闭环分析文档
282 lines
8.2 KiB
Markdown
282 lines
8.2 KiB
Markdown
# 项目特定规则 (Project-Specific Rules)
|
||
|
||
> 本文件包含 Crawlful Hub 项目的**硬性约束和配置**，所有代码必须遵守。
|
||
>
|
||
> 📚 **详细文档请查阅**: `docs/` 目录
|
||
> - 业务蓝图: `docs/00_Business/`
|
||
> - 架构设计: `docs/01_Architecture/`
|
||
> - AI规范: `docs/05_AI/`
|
||
> - 治理规范: `docs/00_Business/Governance_Standards.md`
|
||
|
||
---
|
||
|
||
## 1. 数据与存储约束
|
||
|
||
### 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.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.1 消息类型声明
|
||
- **统一入口**: `src/shared/types/messaging.ts`
|
||
- **新增流程**:
|
||
1. 在 messaging.ts 声明类型
|
||
2. background 与调用方同时适配
|
||
3. 补充最小冒烟测试
|
||
|
||
---
|
||
|
||
## 4. 安全与权限
|
||
|
||
### 4.1 RBAC 模型
|
||
- **预设角色**:
|
||
- `ADMIN` - 全权
|
||
- `MANAGER` - 运营主管
|
||
- `OPERATOR` - 运营专员
|
||
- `FINANCE` - 财务主管
|
||
- `SOURCING` - 采购专家
|
||
- `LOGISTICS` - 物流专家
|
||
- `ANALYST` - 数据分析师
|
||
|
||
### 4.2 权限校验
|
||
- **强制**: 路由层使用 `authorize(permission)` 中间件
|
||
- **禁止**: Controller 中硬编码 `role === 'ADMIN'`
|
||
- **数据隔离**: 非 ADMIN 用户查询必须根据 `parentId` 层级过滤
|
||
|
||
---
|
||
|
||
## 5. 架构与性能边界
|
||
|
||
### 5.1 基础设施
|
||
- **数据库**: 阿里云 RDS (MySQL 8.0)
|
||
- **禁止**: 代码中执行 `DROP/TRUNCATE`
|
||
- **要求**: 复杂查询必须通过 `EXPLAIN` 校验索引
|
||
- **缓存**: 本地 Redis (6379 端口)
|
||
- **队列**: 所有异步任务通过 BullMQ 走本地 Redis
|
||
|
||
### 5.2 单机资源保护
|
||
- **内存**: Node.js 进程限制 `--max-old-space-size=4096`
|
||
- **图片处理**: Sharp 必须开启 `sequentialRead`
|
||
- **并发控制**:
|
||
- API 速率限制基于本地 Redis
|
||
- Worker 并发数 ≤ 10
|
||
|
||
### 5.3 边界隔离
|
||
- **禁止**: 跨 Domain 直接操作数据库模型
|
||
- **必须**: 通过 `Service` 暴露接口或 `EventBus` 异步通信
|
||
|
||
---
|
||
|
||
## 6. TOB 与套利专项约束
|
||
|
||
### 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 协作协议
|
||
|
||
### 7.1 角色定位
|
||
- **Brain**: 全局调度与决策
|
||
- **Agent (AI-1/2/3)**: 原子任务包闭环开发
|
||
|
||
### 7.2 自省要求
|
||
Agent 必须在以下阶段上报"自我问题"：
|
||
1. 对话开始时
|
||
2. 执行过程中
|
||
3. 交付前
|
||
|
||
### 7.3 执行原则
|
||
- **一次性分发**: 每轮下发完整任务包（P0/P1/P2）
|
||
- **连续执行**: 任务包内连续执行到"完成或明确阻塞"
|
||
- **文件占用锁**: 同目录协作先声明归属，"谁领取谁编辑"
|
||
- **冲突处理**: 后写入方必须先 Read 最新内容，增量合并
|
||
|
||
### 7.4 任务包领取机制（强制执行）
|
||
|
||
**核心原则**: 一次领取完整任务包，避免碎片化等待
|
||
|
||
#### 任务包定义
|
||
```
|
||
任务包 = 同一闭环的连续任务 + 依赖链完整 + 文件归属明确
|
||
```
|
||
|
||
#### 领取规则
|
||
1. **优先领取任务包**: 必须优先领取同一闭环的完整任务链
|
||
2. **最小粒度**: 单次领取不少于 2 个相关任务
|
||
3. **依赖自包含**: 领取的任务包内依赖必须闭环
|
||
|
||
#### 任务包类型
|
||
| 包类型 | 包含任务 | 示例 |
|
||
|--------|----------|------|
|
||
| 🔗 闭环包 | 同一业务闭环的全部任务 | BE-TOB001 + BE-TOB002 + BE-TOB003 |
|
||
| 📦 模块包 | 同一模块的连续任务 | FE-AD001 + FE-AD002 + FE-AD003 |
|
||
| 🔗 依赖链包 | 有依赖关系的任务链 | BE-P001 → BE-P002 → BE-P003 |
|
||
|
||
### 7.5 协作防撞车机制（强制执行）
|
||
|
||
#### 方案一：模块分区锁定
|
||
```
|
||
领取任务时，必须同时声明：
|
||
1. 占用的模块/闭环名称
|
||
2. 涉及的主要文件路径
|
||
3. 预计完成时间
|
||
```
|
||
|
||
#### 方案二：文件占用声明
|
||
在 Task_Overview.md 顶部维护 **🔒 当前占用区**：
|
||
```markdown
|
||
## 🔒 当前任务占用状态
|
||
|
||
| Agent | 占用模块 | 涉及任务 | 主要文件 | 开始时间 | 状态 |
|
||
|-------|----------|----------|----------|----------|------|
|
||
| AI-Backend-1 | B2B贸易闭环 | BE-TOB001~003 | B2BTradeService.ts | 2025-03-18 10:00 | 🔒 进行中 |
|
||
```
|
||
|
||
#### 方案三：冲突检测流程
|
||
```
|
||
Step 1: 领取前检查 Task_Overview.md 的 🔒占用区
|
||
Step 2: 确认目标模块未被占用
|
||
Step 3: 声明占用并更新状态
|
||
Step 4: 执行任务
|
||
Step 5: 完成后释放占用
|
||
```
|
||
|
||
#### 撞车处理优先级
|
||
1. **先声明者优先**: 先在 Task_Overview.md 声明占用的 Agent 拥有优先权
|
||
2. **后到者避让**: 后到的 Agent 必须选择其他模块
|
||
3. **协商解决**: 如有争议，由 Brain 协调分配
|
||
|
||
### 7.6 任务包领取模板
|
||
|
||
领取任务时，必须在 Task_Overview.md 更新以下信息：
|
||
|
||
```markdown
|
||
### 🔒 当前占用声明
|
||
|
||
**Agent**: [你的标识，如 AI-Backend-1]
|
||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||
**任务包**: [任务ID列表，如 BE-TOB001, BE-TOB002, BE-TOB003]
|
||
**占用模块**: [模块名称，如 B2B贸易闭环]
|
||
**涉及文件**:
|
||
- server/src/services/B2BTradeService.ts
|
||
- server/src/models/B2B.ts
|
||
- server/src/api/routes/trade.ts
|
||
**预计完成**: [预计完成时间]
|
||
```
|
||
|
||
### 7.7 禁止行为
|
||
|
||
- ❌ **禁止**: 单独领取任务包内的部分任务
|
||
- ❌ **禁止**: 不声明占用直接开始开发
|
||
- ❌ **禁止**: 跨模块同时占用多个任务包
|
||
- ❌ **禁止**: 占用超过 24 小时未释放
|
||
|
||
---
|
||
|
||
## 8. 追踪与日志
|
||
|
||
### 8.1 五元组必填
|
||
所有任务与日志必须携带：
|
||
```typescript
|
||
{
|
||
tenantId: string;
|
||
shopId: string;
|
||
taskId: string;
|
||
traceId: string;
|
||
businessType: 'TOC' | 'TOB';
|
||
}
|
||
```
|
||
|
||
### 8.2 状态机门禁
|
||
- 发布、审核、对账流程必须落入统一 FSM
|
||
- **禁止**: Controller 中硬编码流程分支
|
||
|
||
---
|
||
|
||
## 9. 代码质量门禁
|
||
|
||
### 9.1 命名规范
|
||
- **服务类**: 统一使用 `Service` 后缀
|
||
- **禁止**: `Manager`/`Helper` 等后缀
|
||
|
||
### 9.2 注释规范
|
||
- **必须**: 每个服务类包含完整 JSDoc
|
||
- **必须**: 明确标识任务ID和功能描述
|
||
|
||
### 9.3 部署标准
|
||
`completed` 的标志：
|
||
1. ✅ 数据库表已初始化
|
||
2. ✅ 核心逻辑已闭环
|
||
3. ✅ 通过 `GetDiagnostics` 校验
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
| 规则类别 | 关键约束 | 违反后果 |
|
||
|---------|---------|---------|
|
||
| 数据存储 | 表前缀 `cf_`, 金额 `decimal(10,2)` | 数据不一致 |
|
||
| 业务决策 | 必须 `PENDING_REVIEW` | 直接修改生产数据 |
|
||
| 利润红线 | B2B<15%禁止, B2C<20%预警 | 财务风险 |
|
||
| 安全权限 | 使用 `authorize()` 中间件 | 权限漏洞 |
|
||
| 性能边界 | Worker并发≤10, 内存≤4GB | 系统崩溃 |
|
||
| 追踪日志 | 五元组必填 | 无法追溯 |
|
||
| **任务领取** | **优先领任务包，最小2个任务** | **碎片化等待** |
|
||
| **协作防撞** | **必须声明占用，先声明优先** | **重复开发** |
|
||
|
||
---
|
||
|
||
*本文件仅包含硬性约束，详细规范请查阅 `docs/` 目录。*
|