Files

wurenzhi 2b86715c09 refactor: 优化代码结构并修复类型问题

- 移除未使用的TabPane组件
- 修复类型定义和导入方式
- 优化mock数据源的环境变量判断逻辑
- 更新文档结构并归档旧文件
- 添加新的UI组件和Memo组件
- 调整API路径和响应处理

2026-03-23 12:41:35 +08:00

14 KiB

Raw Blame History

术语标准

定位：本文档定义 Crawlful Hub 项目全文档体系的标准术语，确保跨文档语义一致性。
更新日期: 2026-03-23
适用范围: 所有项目文档、代码注释、API 接口

1. 业务类型术语 (Business Type)

1.1 标准定义

标准术语	英文全称	使用场景	禁止使用
TOC	To Consumer	零售业务、B2C电商	B2C（仅技术文档可用）、零售
TOB	To Business	企业业务、B2B贸易	B2B（仅技术文档可用）、企业

1.2 使用规范

// ✅ 正确用法
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 模块引用规范

<!-- ✅ 正确用法 -->
## 商品管理 (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 组件引用规范

<!-- ✅ 正确用法 -->
前端控制台通过 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 状态使用规范

// ✅ 正确用法
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 角色使用规范

// ✅ 正确用法
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 字段使用规范

// ✅ 正确用法
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

14 KiB Raw Blame History Unescape Escape