wurenzhi
2b86715c09
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
420 lines
14 KiB
Markdown
420 lines
14 KiB
Markdown
# 术语标准
|
||
|
||
> **定位**：本文档定义 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*
|