Files

wurenzhi 2748456d8a refactor(services): 重构服务文件结构，将服务按功能分类到不同目录

- 将服务文件按功能分类到core、ai、analytics、security等目录
- 修复logger导入路径问题，统一使用相对路径
- 更新相关文件的导入路径引用
- 添加新的批量操作组件导出文件
- 修复dashboard页面中的类型错误
- 添加dotenv依赖到package.json

2026-03-25 13:46:26 +08:00

19 KiB

Raw Permalink Blame History

项目特定规则 (Project-Specific Rules)

本文件包含 Crawlful Hub 项目的硬性约束和配置，所有代码必须遵守。

📚 详细文档请查阅: docs/ 目录

业务蓝图: docs/ARCHIVE/00_Business/ 或 docs/LOOPS/

架构设计: docs/ARCHIVE/01_Architecture/

AI规范: docs/ARCHIVE/05_AI/

治理规范: docs/ARCHIVE/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 必须在以下阶段上报"自我问题"：

对话开始时
执行过程中
交付前

7.3 执行原则

一次性分发: 每轮下发完整任务包（P0/P1/P2）
连续执行: 任务包内连续执行到"完成或明确阻塞"
文件占用锁: 同目录协作先声明归属，"谁领取谁编辑"
冲突处理: 后写入方必须先 Read 最新内容，增量合并

7.4 任务包领取机制（强制执行）

核心原则: 一次领取完整任务包，避免碎片化等待

任务包定义

任务包 = 同一闭环的连续任务 + 依赖链完整 + 文件归属明确

领取规则

优先领取任务包: 必须优先领取同一闭环的完整任务链
最小粒度: 单次领取不少于 2 个相关任务
依赖自包含: 领取的任务包内依赖必须闭环

任务包类型

包类型	包含任务	示例
🔗 闭环包	同一业务闭环的全部任务	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 顶部维护 🔒 当前占用区：

## 🔒 当前任务占用状态

| 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: 完成后释放占用

撞车处理优先级

先声明者优先: 先在 Task_Overview.md 声明占用的 Agent 拥有优先权
后到者避让: 后到的 Agent 必须选择其他模块
协商解决: 如有争议，由 Brain 协调分配

7.6 任务包领取模板

领取任务时，必须在 Task_Overview.md 更新以下信息：

### 🔒 当前占用声明

**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 小时未释放

7.8 任务ID格式

格式: [模块]-[子模块][序号]
模块: FE(前端), BE(后端), PL(插件), AI(AI), DT(数据), OP(运维)
子模块: P(商品), O(订单), F(财务), I(库存), C(采集), A(广告) 等
示例: BE-P001, FE-O001, PL-C001

8. 逻辑集中化原则（硬性约束）

8.1 核心原则

逻辑集中化 → 服务驱动：所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。

8.2 逻辑分散的表现（禁止行为）

❌ Controller 中写业务逻辑：Controller 只负责请求/响应和权限校验
❌ 前端直接写业务规则：复杂计算、权限判断、状态流转禁止在 React 组件中实现
❌ 数据库操作分散：不同模块禁止直接调用数据库，必须通过 Service 层
❌ 脚本或工具处理逻辑：AI 任务或异步脚本必须通过 Service 层统一调用

8.3 逻辑分散的后果

维护成本高：AI 或开发者需要理解多个模块才能做一件改动
修改容易出错：改动一处可能引起其他模块逻辑不一致
难以快速迭代：新功能闭环难以接入，因为逻辑散落在各处
收费闭环风险：分散逻辑导致支付、权限、账单、状态不一致，直接影响收益
AI 维护困难：AI 无法一次性理解完整闭环，状态不一致，修改风险高

8.4 服务层职责（强制执行）

Controller 层职责

接收 HTTP 请求和参数验证
调用 Service 层处理业务逻辑
返回响应给前端
权限校验（通过 authorize() 中间件）

Service 层职责（核心）

业务逻辑编排和状态流转
多模块协同和数据一致性保证
事务管理和异常处理
调用 Repository 层或外部 API

Repository 层职责

数据库 CRUD 操作
数据模型映射
查询优化

8.5 状态管理统一

前端状态：使用全局 Model 或状态管理库（Umi Model、Redux 等）
后端状态：统一使用 STATE_MACHINE 定义的状态机
状态流转：所有状态更新必须通过 Service 层，禁止在 Controller 或前端直接修改

8.6 核心逻辑复用

公共函数：权限、价格、库存、账单等逻辑必须封装为公共函数或工具库
服务接口：AI 只需调用 Service 接口，不直接处理业务逻辑
避免重复：不同模块禁止重复实现相同逻辑

8.7 可视化业务流程

流程图：为每个业务闭环绘制流程图，便于 AI 理解
状态机图：使用 STATE_MACHINE 记录完整闭环
服务地图：完善 SERVICE_MAP，明确服务调用链

8.8 违反逻辑集中化原则的后果

代码审查不通过：任何违反逻辑集中化原则的代码将被拒绝合并
AI 任务失败：AI 无法维护分散的逻辑，导致任务执行失败
生产环境风险：分散逻辑导致数据不一致，直接影响系统稳定性

9. 追踪与日志

9.1 五元组必填

所有任务与日志必须携带：

{
  tenantId: string;
  shopId: string;
  taskId: string;
  traceId: string;
  businessType: 'TOC' | 'TOB';
}

9.2 状态机门禁

发布、审核、对账流程必须落入统一 FSM
禁止: Controller 中硬编码流程分支

10. 代码质量门禁

10.1 命名规范

服务类: 统一使用 Service 后缀
禁止: Manager/Helper 等后缀

10.2 注释规范

必须: 每个服务类包含完整 JSDoc
必须: 明确标识任务ID和功能描述

10.3 部署标准

completed 的标志：

✅ 数据库表已初始化
✅ 核心逻辑已闭环
✅ 通过 GetDiagnostics 校验

10.4 文件规模限制

单文件: ≤ 1500 行
单函数: ≤ 120 行
UI 组件: ≤ 300 行

11. Mock数据规范（AI上下文安全）

11.1 Mock数据原则

核心目标: 实现"不污染代码、AI上下文安全"的Mock方案

❌ 禁止做法

硬编码Mock数据: 在业务组件中直接写死数据

// 禁止！
const data = [{ id: 1, name: 'Mock商品' }]

if判断切换: 在业务代码中通过if判断切换Mock/真实数据
```
// 禁止！
if (isDev) return mockData
```

✅ 正确做法

DataSource抽象层: 通过数据源抽象层获取数据

// 正确！
const data = await certificateDataSource.list()

环境变量控制: 通过 REACT_APP_USE_MOCK 环境变量控制
目录隔离: 所有Mock文件必须放在 /mock 目录

11.2 Mock文件规范

目录结构

/dashboard/src
  /mock                   ← 所有Mock相关
    /data                 ← Mock数据定义
    msw.ts                ← MSW配置
    browser.ts            ← 浏览器入口
    README.md             ← Mock使用说明
  /services               ← DataSource抽象层
    *DataSource.ts

文件标记

所有Mock文件必须包含以下标记:

/**
 * [MOCK-XXX] 功能描述
 * AI注意: 这是Mock实现，不是真实业务逻辑
 * 仅在USE_MOCK=true时启用
 */

// 或者

// [MOCK] 此文件为Mock数据，AI请勿当作真实业务逻辑

11.3 AI识别规则

AI在分析代码时:

✅ 忽略 /mock 目录下所有文件
✅ 忽略包含 [MOCK] 标记的文件
✅ 忽略 __MOCK__ 变量为真的代码路径
✅ 优先分析 /services 下的DataSource层

11.4 环境变量

变量名	开发环境	生产环境	说明
REACT_APP_USE_MOCK	`true`	`false`	前端Mock开关
USE_MOCK	`true`	`false`	后端Mock开关

11.5 参考文档

12. TypeScript 编译与类型安全（强制约束）

12.1 核心原则

禁止 any: 所有代码禁止使用 any 类型，使用 unknown + 类型守卫
函数必须声明返回类型: 所有函数必须显式声明返回类型
API 必须定义类型: 所有 API 调用必须定义请求和响应类型
类型边界分层: 接口层 → DTO层 → 业务层（Domain）

12.2 类型定义规范

禁止裸对象: 所有对象必须有类型定义
Schema 驱动: 类型必须从 Schema（zod）推导，禁止手动定义
统一类型中心: 所有类型只从 /types 目录导入，禁止各模块重复定义

12.3 类型转换流程

API 返回数据 → Schema 验证 → DTO 转换 → Domain 模型

接口返回 = 不可信: 必须经过 Schema 验证才能进入业务层
禁止直接使用: 禁止在业务层直接使用 API 返回的原始数据

12.4 编译检查

编译错误 = 构建失败: TypeScript 编译错误必须阻断 CI/CD
提交前检查: 必须通过 tsc --noEmit 检查才能提交
ESLint 强制: 必须通过 @typescript-eslint 规则检查

12.5 编译错误修复（当前 613 个错误）

错误分布

错误类型	占比	优先级
类型不匹配	40%	🔴 最高
any 类型	25%	🔴 最高
模块导入	15%	🟡 中
undefined/null	10%	🟡 中
配置问题	5%	🟢 低
路径问题	5%	🟢 低

修复策略（分阶段）

阶段 1（配置）: 检查并修复 tsconfig.json 配置
阶段 2（any）: 消除所有 any 类型，使用 unknown + 类型守卫
阶段 3（类型）: 修复类型不匹配，确保所有函数声明返回类型
阶段 4（模块）: 统一模块导入导出，修复路径别名
阶段 5（空值）: 正确处理 undefined 和 null

强制约束

❌ 禁止: 使用 // @ts-ignore 忽略错误
❌ 禁止: 使用 // @ts-nocheck 禁用检查
❌ 禁止: 将类型改为 any 来"解决"错误
✅ 必须: 每次修复后运行测试
✅ 必须: 保持代码风格一致

进度追踪

# 检查剩余错误数
npx tsc --noEmit 2>&1 | Select-String -Pattern "^src/" | Measure-Object

12.6 详细文档

13. 错误处理与异常管理

13.1 全局异常处理

统一错误格式: 所有 API 必须返回统一错误格式

interface ApiError {
  code: string;      // 错误码，如 'ORDER_NOT_FOUND'
  message: string;   // 错误信息
  details?: unknown; // 详细信息
  traceId: string;  // 追踪ID
}

HTTP状态码映射:
- 400 - 参数错误
- 401 - 未授权
- 403 - 禁止访问
- 404 - 资源不存在
- 500 - 服务器内部错误

13.2 错误码规范

格式: [模块]_[类型]_[序号]，如 ORDER_PAYMENT_TIMEOUT_001
禁止: 业务逻辑中直接 throw generic Error
必须: 使用自定义业务异常类

13.3 事务回滚机制

重要操作: 订单创建、支付、退款等必须使用事务
回滚策略: 失败时必须回滚，确保数据一致性
禁止: 在事务外执行不可回滚的操作

13.4 异常日志记录

必须记录: 异常堆栈、traceId、五元组信息
禁止: 在日志中记录敏感信息（密码、token等）

14. 日志管理

15.1 日志级别

级别	使用场景
DEBUG	开发调试，，详细执行路径
INFO	正常业务流程，如订单创建、状态流转
WARN	潜在问题，如重试、熔断触发
ERROR	错误异常，如API调用失败、数据库异常

15.2 日志格式

{
  timestamp: string;      // ISO 8601
  level: string;         // DEBUG/INFO/WARN/ERROR
  traceId: string;       // 追踪ID
  tenantId: string;
  shopId: string;
  taskId?: string;
  service: string;       // 服务名称
  method: string;        // 方法名
  message: string;       // 日志消息
  duration?: number;     // 执行时长(ms)
  error?: ErrorInfo;     // 错误信息
}

15.3 日志存储策略

本地开发: 控制台输出
测试/生产: 写入文件，按天轮转
保留周期: 测试环境 7 天，生产环境 30 天

15.4 敏感信息保护

禁止: 在日志中记录密码、token、信用卡号
脱敏: 敏感字段必须脱敏后记录

快速参考

规则类别	关键约束	违反后果
数据存储	表前缀 `cf_`, 金额 `decimal(10,2)`	数据不一致
业务决策	必须 `PENDING_REVIEW`	直接修改生产数据
利润红线	B2B<15%禁止, B2C<20%预警	财务风险
安全权限	使用 `authorize()` 中间件	权限漏洞
性能边界	Worker并发≤10, 内存≤4GB	系统崩溃
追踪日志	五元组必填	无法追溯
逻辑集中化	所有业务逻辑必须在Service层	AI维护困难，数据不一致
任务领取	优先领任务包，最小2个任务	碎片化等待
协作防撞	必须声明占用，先声明优先	重复开发
Mock规范	Mock数据必须隔离，禁止硬编码	AI上下文污染，维护困难
TypeScript	禁止any，函数必须声明返回类型	类型安全丧失，运行时错误
错误处理	统一错误码，全局异常处理	错误扩散，难以追踪
日志管理	日志级别/格式/存储策略	日志混乱，难以分析

本文件仅包含硬性约束，详细规范请查阅 docs/ 目录。

19 KiB Raw Permalink Blame History Unescape Escape