wurenzhi
48a78137c5
- 将B2B统一为TOB术语 - 将状态值统一为大写格式 - 优化类型声明，避免使用any - 将float类型替换为decimal以提高精度 - 新增术语标准化文档 - 优化路由结构和菜单分类 - 添加TypeORM实体类 - 增强加密模块安全性 - 重构前端路由结构 - 完善任务模板和验收标准
336 lines
11 KiB
Markdown
336 lines
11 KiB
Markdown
# 📚 Crawlful Hub 术语标准化规范
|
||
|
||
> **定位**：本文档定义 Crawlful Hub 项目全文档体系的标准术语，确保跨文档语义一致性。
|
||
> **更新日期**: 2026-03-20
|
||
> **适用范围**: 所有项目文档、代码注释、API 接口
|
||
|
||
---
|
||
|
||
## 1. 业务类型术语 (Business Type)
|
||
|
||
### 1.1 标准定义
|
||
|
||
| 标准术语 | 英文全称 | 使用场景 | 禁止使用 |
|
||
|---------|---------|---------|---------|
|
||
| **TOC** | To Consumer | 零售业务、B2C电商 | B2C（仅技术文档可用）、零售 |
|
||
| **TOB** | To Business | 企业业务、B2B贸易 | B2B（仅技术文档可用）、企业 |
|
||
|
||
### 1.2 使用规范
|
||
|
||
```typescript
|
||
// ✅ 正确用法
|
||
businessType: 'TOC' | 'TOB'
|
||
|
||
// ❌ 错误用法
|
||
businessType: 'B2C' | 'B2B'
|
||
businessType: '零售' | '企业'
|
||
```
|
||
|
||
### 1.3 例外情况
|
||
- 对外商务文档中可使用 `B2B/B2C` 以便理解
|
||
- 代码内部枚举值使用 `TOC/TOB`
|
||
|
||
---
|
||
|
||
## 2. 业务模块术语 (Business Modules)
|
||
|
||
### 2.1 标准模块命名
|
||
|
||
| 标准术语 | 英文缩写 | 中文全称 | 使用场景 | 禁止使用 |
|
||
|---------|---------|---------|---------|---------|
|
||
| **商品管理** | PIM | Product Information Management | 商品主数据、SKU管理 | 产品管理、货品管理 |
|
||
| **订单管理** | OMS | Order Management System | 订单履约、售后处理 | 订单系统、交易管理 |
|
||
| **库存管理** | WMS | Warehouse Management System | 仓储、库存、补货 | 仓储管理、存货管理 |
|
||
| **财务管理** | FIN | Financial Management | 对账、结算、利润 | 财务系统、资金系统 |
|
||
| **营销管理** | MKT | Marketing Management | 广告、投放、推广 | 推广管理、市场管理 |
|
||
| **供应链管理** | SCM | Supply Chain Management | 供应商、采购、补货 | 供应管理、采购管理 |
|
||
| **客户管理** | CRM | Customer Relationship Management | 客户、用户、资产 | 用户管理、会员管理 |
|
||
|
||
### 2.2 模块引用规范
|
||
|
||
```markdown
|
||
<!-- ✅ 正确用法 -->
|
||
## 商品管理 (PIM)
|
||
订单管理 (OMS) 模块负责...
|
||
|
||
<!-- ❌ 错误用法 -->
|
||
## 产品管理
|
||
OMS系统负责...
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 系统组件术语 (System Components)
|
||
|
||
### 3.1 核心组件命名
|
||
|
||
| 标准术语 | 英文名称 | 定义 | 禁止使用 |
|
||
|---------|---------|------|---------|
|
||
| **前端控制台** | Frontend Console | 用户操作界面，基于 UmiJS + Ant Design | Console、前端、dashboard、中控台 |
|
||
| **后端服务** | Backend Service | 业务逻辑处理层，Node.js + TypeScript | Hub、服务端、API服务 |
|
||
| **浏览器插件** | Browser Extension | 数据采集与自动化执行插件 | Plugin、插件、扩展程序 |
|
||
| **运营代理** | Operation Agent | 轻量化守护进程，执行采集和自动化任务 | Agent、运营端、执行器 |
|
||
| **系统编排器** | System Orchestrator | 全局决策与资源分配中心 | 系统大脑、调度中心 |
|
||
|
||
### 3.2 组件引用规范
|
||
|
||
```markdown
|
||
<!-- ✅ 正确用法 -->
|
||
前端控制台通过 API 与后端服务通信
|
||
浏览器插件负责数据采集
|
||
|
||
<!-- ❌ 错误用法 -->
|
||
Console 通过 API 与 Hub 通信
|
||
Plugin 负责数据采集
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 状态机术语 (State Machine)
|
||
|
||
### 4.1 状态命名规范
|
||
|
||
所有状态值必须使用 **大写蛇形命名法 (UPPER_SNAKE_CASE)**
|
||
|
||
| 状态类型 | 标准值 | 说明 |
|
||
|---------|-------|------|
|
||
| **初始状态** | `PENDING` | 待处理 |
|
||
| **审核状态** | `PENDING_REVIEW` | 待审核 |
|
||
| **执行状态** | `IN_PROGRESS` | 执行中 |
|
||
| **成功状态** | `COMPLETED` / `SUCCESS` | 已完成 |
|
||
| **失败状态** | `FAILED` / `REJECTED` | 失败/拒绝 |
|
||
| **活跃状态** | `ACTIVE` | 活跃/启用 |
|
||
| **非活跃状态** | `INACTIVE` | 非活跃/停用 |
|
||
|
||
### 4.2 标准状态流转
|
||
|
||
```
|
||
// 订单状态机
|
||
PENDING → CONFIRMED → PROCESSING → SHIPPED → DELIVERED → COMPLETED
|
||
|
||
// 审核状态机
|
||
SUBMITTED → PENDING_REVIEW → APPROVED/REJECTED
|
||
|
||
// 任务状态机
|
||
PENDING → RUNNING → SUCCESS/FAILED
|
||
```
|
||
|
||
### 4.3 状态使用规范
|
||
|
||
```typescript
|
||
// ✅ 正确用法
|
||
status: 'PENDING_REVIEW' | 'EXECUTED' | 'REJECTED'
|
||
|
||
// ❌ 错误用法
|
||
status: 'pending_review' | 'executed' | 'rejected'
|
||
status: '待审核' | '已执行' | '已拒绝'
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 角色与权限术语 (Roles & Permissions)
|
||
|
||
### 5.1 标准角色定义
|
||
|
||
| 标准术语 | 英文全称 | 职责描述 | 禁止使用 |
|
||
|---------|---------|---------|---------|
|
||
| **ADMIN** | Administrator | 系统管理员，全权 | Admin、管理员 |
|
||
| **MANAGER** | Manager | 运营主管，审核中低风险操作 | Manager、主管 |
|
||
| **OPERATOR** | Operator | 运营专员，执行日常操作 | Operator、操作员 |
|
||
| **FINANCE** | Finance Manager | 财务主管，审核财务操作 | Finance、财务 |
|
||
| **SOURCING** | Sourcing Specialist | 采购专家，管理供应商 | Sourcing、采购 |
|
||
| **LOGISTICS** | Logistics Specialist | 物流专家，管理仓储物流 | Logistics、物流 |
|
||
| **ANALYST** | Data Analyst | 数据分析师，查看报表 | Analyst、分析师 |
|
||
|
||
### 5.2 角色使用规范
|
||
|
||
```typescript
|
||
// ✅ 正确用法
|
||
role: 'ADMIN' | 'MANAGER' | 'OPERATOR'
|
||
minReviewerRole: 'OPERATOR' | 'MANAGER' | 'FINANCE'
|
||
|
||
// ❌ 错误用法
|
||
role: 'admin' | 'manager' | 'operator'
|
||
role: '管理员' | '主管' | '操作员'
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 追踪字段术语 (Tracking Fields)
|
||
|
||
### 6.1 五元组标准命名
|
||
|
||
| 标准字段名 | 数据类型 | 说明 | 禁止使用 |
|
||
|-----------|---------|------|---------|
|
||
| **tenantId** | string | 租户 ID，业务隔离 | tenant_id, tenantID, 租户ID |
|
||
| **shopId** | string | 店铺 ID，平台/店铺隔离 | shop_id, shopID, 店铺ID |
|
||
| **taskId** | string | 任务 ID，任务/规则触发归档 | task_id, taskID, 任务ID |
|
||
| **traceId** | string | 链路追踪 ID，全链路唯一 | trace_id, traceID, 追踪ID |
|
||
| **businessType** | 'TOC' \| 'TOB' | 业务类型 | business_type, type |
|
||
|
||
### 6.2 字段使用规范
|
||
|
||
```typescript
|
||
// ✅ 正确用法
|
||
interface TrackingContext {
|
||
tenantId: string;
|
||
shopId: string;
|
||
taskId: string;
|
||
traceId: string;
|
||
businessType: 'TOC' | 'TOB';
|
||
}
|
||
|
||
// ❌ 错误用法
|
||
interface TrackingContext {
|
||
tenant_id: string;
|
||
shop_id: string;
|
||
task_id: string;
|
||
trace_id: string;
|
||
business_type: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 任务标识术语 (Task Identification)
|
||
|
||
### 7.1 任务 ID 格式
|
||
|
||
标准格式：`[模块]-[子模块][序号]`
|
||
|
||
| 模块代码 | 含义 | 子模块代码 | 含义 |
|
||
|---------|------|-----------|------|
|
||
| **FE** | Frontend (前端) | P | Product (商品) |
|
||
| **BE** | Backend (后端) | O | Order (订单) |
|
||
| **PL** | Plugin (插件) | F | Finance (财务) |
|
||
| **AI** | AI (人工智能) | I | Inventory (库存) |
|
||
| **DT** | Data (数据) | C | Collection (采集) |
|
||
| **OP** | Operation (运维) | A | Advertisement (广告) |
|
||
|
||
### 7.2 任务 ID 示例
|
||
|
||
```
|
||
FE-P001 → 前端商品模块任务001
|
||
BE-O005 → 后端订单模块任务005
|
||
PL-C002 → 插件采集模块任务002
|
||
AI-A001 → AI广告模块任务001
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 技术术语 (Technical Terms)
|
||
|
||
### 8.1 架构术语
|
||
|
||
| 标准术语 | 说明 | 禁止使用 |
|
||
|---------|------|---------|
|
||
| **Service** | 服务层，业务逻辑集中地 | 服务、Manager、Helper |
|
||
| **Repository** | 数据访问层 | DAO、Mapper、存储层 |
|
||
| **Controller** | 控制器层，处理HTTP请求 | 控制层、接口层 |
|
||
| **Domain** | 领域层，核心业务实体 | 领域模型、实体层 |
|
||
| **Event Bus** | 事件总线，异步通信机制 | 消息总线、事件中心 |
|
||
|
||
### 8.2 数据库术语
|
||
|
||
| 标准术语 | 说明 | 禁止使用 |
|
||
|---------|------|---------|
|
||
| **表前缀** | `cf_` (Crawlful) | 无前缀、其他前缀 |
|
||
| **金额字段** | `decimal(10,2)` | float、double |
|
||
| **JSON 字段** | 序列化存储，出库解析 | text、varchar |
|
||
|
||
---
|
||
|
||
## 9. 财务与利润术语 (Financial Terms)
|
||
|
||
### 9.1 利润计算术语
|
||
|
||
| 标准术语 | 定义 | 计算公式 |
|
||
|---------|------|---------|
|
||
| **净利润** | 扣除所有成本后的利润 | 售价 - 采购 - 平台费 - 物流 - 税费 - 汇率对冲 - 售后损耗 - 广告摊销 |
|
||
| **利润率** | 净利润占售价的比例 | 净利润 / 售价 × 100% |
|
||
| **ROI** | 投资回报率 | (收益 - 成本) / 成本 × 100% |
|
||
| **ROAS** | 广告支出回报率 | 广告带来的收入 / 广告支出 |
|
||
|
||
### 9.2 利润红线
|
||
|
||
| 业务类型 | 利润率阈值 | 处理方式 |
|
||
|---------|-----------|---------|
|
||
| **TOC** | < 20% | 触发风控预警 |
|
||
| **TOB** | < 15% | 禁止报价 |
|
||
|
||
---
|
||
|
||
## 10. 文档格式术语 (Documentation Format)
|
||
|
||
### 10.1 文档状态标记
|
||
|
||
| 标记 | 含义 | 使用场景 |
|
||
|-----|------|---------|
|
||
| ⏳ | pending | 待办 |
|
||
| 🔒 | claimed | 已认领 |
|
||
| 🚧 | in_progress | 进行中 |
|
||
| ✅ | completed | 已完成 |
|
||
| ❌ | blocked | 阻塞 |
|
||
|
||
### 10.2 优先级标记
|
||
|
||
| 标记 | 含义 | 说明 |
|
||
|-----|------|------|
|
||
| **P0** | Critical | 阻塞性任务，必须立即处理 |
|
||
| **P1** | High | 高优先级，影响核心功能 |
|
||
| **P2** | Medium | 中优先级，优化类任务 |
|
||
| **P3** | Low | 低优先级，可延后处理 |
|
||
|
||
---
|
||
|
||
## 11. 术语替换速查表 (Quick Reference)
|
||
|
||
### 11.1 必须替换的旧术语
|
||
|
||
| 旧术语 | 新术语 | 替换范围 |
|
||
|-------|-------|---------|
|
||
| B2C | TOC | 所有代码、配置、数据库 |
|
||
| B2B | TOB | 所有代码、配置、数据库 |
|
||
| 产品管理 | 商品管理 | 所有文档、代码 |
|
||
| Console | 前端控制台 | 所有文档 |
|
||
| Hub | 后端服务 | 所有文档 |
|
||
| Plugin | 浏览器插件 | 所有文档 |
|
||
| pending (状态) | PENDING | 状态机定义 |
|
||
| active (状态) | ACTIVE | 状态机定义 |
|
||
| tenant_id | tenantId | 所有代码 |
|
||
| shop_id | shopId | 所有代码 |
|
||
| Admin | ADMIN | 角色定义 |
|
||
| Manager | MANAGER | 角色定义 |
|
||
|
||
---
|
||
|
||
## 12. 术语审核清单 (Review Checklist)
|
||
|
||
在提交文档或代码前，请检查以下项目：
|
||
|
||
- [ ] 业务类型使用 `TOC/TOB` 而非 `B2B/B2C`
|
||
- [ ] 模块名称使用标准术语（商品管理、订单管理等）
|
||
- [ ] 系统组件使用标准术语（前端控制台、后端服务等）
|
||
- [ ] 状态值使用大写蛇形命名（`PENDING_REVIEW`）
|
||
- [ ] 角色使用大写（`ADMIN`, `MANAGER`）
|
||
- [ ] 追踪字段使用驼峰命名（`tenantId`, `shopId`）
|
||
- [ ] 任务 ID 符合标准格式（`FE-P001`）
|
||
- [ ] 表名使用 `cf_` 前缀
|
||
- [ ] 金额字段使用 `decimal(10,2)`
|
||
|
||
---
|
||
|
||
## 13. 相关文档
|
||
|
||
| 文档 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 业务蓝图 | [../00_Business/Business_Blueprint.md](../00_Business/Business_Blueprint.md) | 业务模块定义 |
|
||
| 状态机规范 | [../01_Architecture/06_State_Machine.md](../01_Architecture/06_State_Machine.md) | 状态定义 |
|
||
| 治理标准 | [../00_Business/Governance_Standards.md](../00_Business/Governance_Standards.md) | 开发规范 |
|
||
| 项目规则 | [../../.trae/rules/project-specific-rules.md](../../.trae/rules/project-specific-rules.md) | 硬性约束 |
|
||
|
||
---
|
||
|
||
*本文档为 Crawlful Hub 术语标准，所有项目成员必须遵守。*
|
||
*最后更新: 2026-03-20*
|