wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
15ee1758f5dcd8227306e310fb55ea22548f30ad
makemd/docs/10_Documents_Global/TERMINOLOGY_STANDARDS.md

336 lines
11 KiB
Markdown
Raw Normal View History

refactor(terminology): 统一术语标准并优化代码类型安全 - 将B2B统一为TOB术语 - 将状态值统一为大写格式 - 优化类型声明，避免使用any - 将float类型替换为decimal以提高精度 - 新增术语标准化文档 - 优化路由结构和菜单分类 - 添加TypeORM实体类 - 增强加密模块安全性 - 重构前端路由结构 - 完善任务模板和验收标准
2026-03-20 09:43:50 +08:00
# 📚 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*
Reference in New Issue Copy Permalink