makemd/docs/RULES/TERMINOLOGY.md

# 术语标准

> **定位**：本文档定义 Crawlful Hub 项目全文档体系的标准术语，确保跨文档语义一致性。  
> **更新日期**: 2026-03-23  
> **适用范围**: 所有项目文档、代码注释、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. 商品管理术语 (Product Management Terms)

### 13.1 商品层级术语

| 标准术语 | 英文 | 定义 | 禁止使用 |
|---------|------|------|---------|
| **SPU** | Standard Product Unit | 标准产品单元，商品的最小聚合单位 | 产品、商品主数据 |
| **SKU** | Stock Keeping Unit | 库存单元，SPU的变体 | 变体、规格 |
| **Listing** | Platform Listing | 平台商品，SKU在平台的刊登实例 | 平台商品、刊登商品 |

### 13.2 商品操作术语

| 标准术语 | 英文 | 定义 | 禁止使用 |
|---------|------|------|---------|
| **商品映射** | Product Mapping | 绑定系统SKU与平台商品的关系 | 商品绑定、关联 |
| **商品刊登** | Product Listing | 创建新商品并发布到平台 | 商品发布、上架 |

**核心判断公式**：
> 这个动作有没有在平台创建新商品？
> - 有 → 刊登
> - 没有 → 映射

**业务场景对比**：

| 场景 | 操作 | 用途 |
|------|------|------|
| 平台已有商品需要统一管理 | 映射 | 统一库存、利润分析、AI调价 |
| 新品上架、批量铺货 | 刊登 | 上新、自动铺货、跨平台分发 |

### 13.3 价格体系术语

| 标准术语 | 英文 | 定义 | 禁止使用 |
|---------|------|------|---------|
| **基准价** | Base Price | SKU层的参考价格锚点 | 成本价、原价 |
| **策略价** | Strategy Price | 价格规则计算后的价格 | 规则价、计算价 |
| **最终价** | Final Price | Listing层的实际销售价格 | 售价、成交价 |

**三层价格体系**：

```
┌─────────────────────────────────────────┐
│ 1️⃣ 基准价层（Base Price Layer）         │
│    SKU.base_price                       │
│    用途：统一锚点、人工理解               │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│ 2️⃣ 策略层（Strategy Layer）             │
│    PriceStrategy:                        │
│    - scope: 平台/店铺/Listing            │
│    - type: multiplier/fixed/dynamic     │
│    用途：规则定义、批量控制               │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│ 3️⃣ Listing层（Final Price Layer）       │
│    PlatformListing.price                │
│    用途：真正赚钱的地方                   │
└─────────────────────────────────────────┘
```

**最终价格计算公式**：
```
最终价格 = override_price || strategy计算结果 || AI计算结果
```

### 13.4 组织权限术语

| 标准术语 | 英文 | 定义 | 禁止使用 |
|---------|------|------|---------|
| **组织层级** | Organization Hierarchy | 公司/部门/团队的树形结构 | 组织架构、部门结构 |
| **数据范围** | Data Scope | 用户可访问的数据边界 | 数据权限、可见范围 |
| **店铺授权** | Shop Authorization | 用户对店铺的操作权限 | 店铺权限、店铺绑定 |

**数据范围类型**：

| 范围类型 | 英文 | 说明 |
|---------|------|------|
| **SELF** | Self | 只看自己 |
| **TEAM** | Team | 看自己组 |
| **DEPT** | Department | 看自己部门 |
| **ORG** | Organization | 看整个公司 |
| **ALL** | All | 全平台（超管） |

### 13.5 授权类型术语

| 标准术语 | 适用平台 | 存储内容 |
|---------|----------|----------|
| **API授权** | Shopify、Amazon | access_token, refresh_token, expire_time |
| **Agent授权** | TikTok、Shopee | cookies, proxy, device_id, user_agent |

---

*本文档为 Crawlful Hub 术语标准，所有项目成员必须遵守。*  
*最后更新: 2026-03-23*