feat: 实现服务层核心功能与文档更新

refactor(ProductService): 修复createProduct方法和其他方法错误
fix(InventoryAgingService): 修复AGING_THRESHOLD_DAYS引用问题
fix(InventoryService): 修复predictSKUDemand方法
refactor(ChatBotController): 从tsoa风格改为Express风格
fix(CommandCenterController): 修复类型问题
fix(AdAutoService): 修复stock可能为undefined的问题
docs: 更新SERVICE_MAP、DOMAIN_MODEL等架构文档
chore: 启动前端服务(运行在http://localhost:8000)
This commit is contained in:
2026-03-18 12:35:52 +08:00
parent 2ad40da777
commit 5cfd0c4c89
55 changed files with 6077 additions and 1733 deletions

View File

@@ -1,6 +1,6 @@
# 📌 Crawlful Hub 业务闭环TOC + TOB Unified Business Loops
> **说明**:本闭环文档是战略层业务流程,关注"做什么、为什么做、顺序和决策点"为下层模块功能和系统实现提供指引。TOC零售/前端)和 TOBB2B贸易共享通用模块特有流程用 `businessType` 标记。共 **35个业务闭环**。
> **说明**:本闭环文档是战略层业务流程,关注"做什么、为什么做、顺序和决策点"为下层模块功能和系统实现提供指引。TOC零售/前端)和 TOBB2B贸易共享通用模块特有流程用 `businessType` 标记。共 **45个业务闭环**。
## 📑 目录
@@ -35,16 +35,26 @@
29. [用户/客户资产闭环](#2⃣9⃣-用户客户资产闭环usercustomer-asset-loop)
30. [A/B测试与策略优化闭环](#3⃣0⃣-ab测试与策略优化闭环ab-testing--strategy-optimization-loop)
31. [多商户入驻与认证闭环](#3⃣1⃣-多商户入驻与认证闭环merchant-registration--authentication-loop)
32. [功能模块化与权限控制闭环](#3⃣2⃣-功能模块化与权限控制闭环feature-modularization--permission-control-loop)
33. [功能开通与支付闭环](#3⃣3⃣-功能开通与支付闭环feature-activation--payment-loop)
34. [多商户结算与财务闭环](#3⃣4⃣-多商户结算与财务闭环multi-merchant-settlement--finance-loop)
35. [多商户商品与订单管理闭环](#3⃣5⃣-多商户商品与订单管理闭环multi-merchant-product--order-management-loop)
36. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
37. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
38. [关键绩效指标](#📊-关键绩效指标kpi)
39. [追踪与审计](#🔍-追踪与审计)
40. [业务审核状态机](#📋-业务审核状态机)
41. [说明](#💡-说明)
32. [商户店铺管理闭环](#3⃣2⃣-商户店铺管理闭环merchant-store-management-loop)
33. [多商户订单闭环](#3⃣3⃣-多商户订单闭环multi-merchant-order-loop)
34. [多商户库存同步闭环](#3⃣4⃣-多商户库存同步闭环multi-merchant-inventory-sync-loop)
35. [多商户结算与财务闭环](#3⃣5⃣-多商户结算与财务闭环multi-merchant-settlement--finance-loop)
36. [商户权限与角色闭环](#3⃣6⃣-商户权限与角色闭环merchant-roles--permissions-loop)
37. [商户数据与分析闭环](#3⃣7⃣-商户数据与分析闭环merchant-analytics--reporting-loop)
38. [异常处理闭环](#3⃣8⃣-异常处理闭环exception--dispute-loop)
39. [功能模块化与权限控制闭环](#3⃣9⃣-功能模块化与权限控制闭环feature-modularization--permission-control-loop)
40. [功能开通与支付闭环](#4⃣0⃣-功能开通与支付闭环feature-activation--payment-loop)
41. [恶意买家黑名单闭环](#4⃣1⃣-恶意买家黑名单闭环malicious-buyer-blacklist-loop)
42. [高退货率SKU自动下架/改进建议闭环](#4⃣2⃣-高退货率sku自动下架改进建议闭环high-return-rate-sku-auto-delist--improvement-loop)
43. [商业化与增长闭环](#4⃣3⃣-商业化与增长闭环monetization--growth-loop)
44. [服务编排与执行闭环](#4⃣4⃣-服务编排与执行闭环service-orchestration-loop)
45. [增长飞轮闭环](#4⃣5⃣-增长飞轮闭环growth-flywheel-loop)
41. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
42. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
43. [关键绩效指标](#📊-关键绩效指标kpi)
44. [追踪与审计](#🔍-追踪与审计)
45. [业务审核状态机](#📋-业务审核状态机)
46. [说明](#💡-说明)
***
@@ -1039,6 +1049,26 @@
| 超卖率 | 库存超卖的比例 | TOC + TOB |
| 物流轨迹覆盖率 | 可追踪物流的订单比例 | TOC + TOB |
#### 恶意买家黑名单闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ----------- | --------- |
| 黑名单识别准确率 | 正确识别恶意买家的比例 | TOC + TOB |
| 风险评估准确率 | 风险等级评估的准确性 | TOC + TOB |
| 黑名单共享有效率 | 共享黑名单的有效利用比例 | TOC + TOB |
| 风险预警及时率 | 及时发出风险预警的比例 | TOC + TOB |
| 误报率 | 误判为恶意买家的比例 | TOC + TOB |
#### 高退货率SKU自动下架/改进建议闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ----------- | --------- |
| 退货率监控准确率 | 退货率计算的准确性 | TOC + TOB |
| 自动下架准确率 | 正确下架高风险SKU的比例 | TOC + TOB |
| 改进建议有效性 | 改进建议被采纳并实施的比例 | TOC + TOB |
| 重新上架成功率 | 改进后重新上架的成功比例 | TOC + TOB |
| 退货率改善率 | 改进后退货率下降的比例 | TOC + TOB |
***
## 3⃣1⃣ 多商户入驻与认证闭环Merchant Registration & Authentication Loop
@@ -1049,24 +1079,200 @@
- 商户自助注册(邮箱/手机/企业信息)
- 资质文件上传(营业执照、法人身份证等)
- 账户类型选择(企业/个人)
- 初始密码设置和安全验证
2. **资质认证**
- 自动审核 + 人工复核
- 企业信息验证、信用检查
- 行业资质合规检查
- 审核进度实时更新
3. **店铺创建**
- 店铺基础信息配置
- 店铺基础信息配置名称、LOGO、描述
- 绑定平台店铺Amazon、Shopee等
- 支付账户配置
- 支付账户配置(收款方式、结算周期)
- 店铺运营设置(退换货政策、客服信息)
4. **权限分配**
- 初始角色设置(管理员、运营、财务)
- 权限范围配置(可访问模块、操作权限)
- 数据隔离设置(商户级数据隔离)
- **决策点**
- 资质审核标准(行业合规、信用评级)
- 商户等级划分(普通/优质/战略)
- 入驻门槛设置
- 入驻门槛设置(不同等级商户的要求)
- 审核通过/拒绝的条件和流程
- **输入**:商户注册信息、资质文件、企业证明
- **输出**商户ID、认证状态、店铺ID
- **输出**商户ID、认证状态、店铺ID、权限配置
- **状态机**`SUBMITTED` → `PENDING_REVIEW` → `APPROVED`/`REJECTED` → `ACTIVE`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 商户管理 | `MerchantService.ts` | BE-M001 |
| 后端 | 资质验证 | `VerificationService.ts` | BE-M002 |
| 后端 | 权限管理 | `RBACService.ts` | BE-M003 |
| 前端 | 注册页面 | `MerchantRegistration.vue` | FE-M001 |
| 前端 | 状态查询 | `MerchantStatus.vue` | FE-M002 |
***
## 3⃣2功能模块化与权限控制闭环Feature Modularization & Permission Control Loop
## 3⃣2商户店铺管理闭环Merchant Store Management Loop
- **目标**:支持商户管理自己的商品、库存、促销活动。
- **流程**
1. 商户创建店铺或子店铺。
2. 前端提供商品管理界面(新增、编辑、上下架)。
3. 后端管理库存、价格、SKU、分类。
4. 支持商户自定义促销规则(折扣、满减、优惠券)。
- **决策点**
- 库存不足 → 阻止下架或自动提醒。
- 促销策略冲突 → 系统自动合并或提示调整。
- **输入**:商户店铺信息、商品信息
- **输出**:管理的店铺和商品数据
- **状态机**`CREATED` → `CONFIGURING` → `ACTIVE` → `INACTIVE`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 店铺管理 | `StoreService.ts` | BE-S001 |
| 后端 | 商品管理 | `ProductService.ts` | BE-P001 |
| 后端 | 库存管理 | `InventoryService.ts` | BE-I001 |
| 前端 | 店铺管理页面 | `StoreManagement.vue` | FE-S001 |
| 前端 | 商品管理页面 | `ProductManagement.vue` | FE-P001 |
***
## 3⃣3⃣ 多商户订单闭环Multi-Merchant Order Loop
- **目标**:支持多个商户订单独立处理,同时平台统一监控。
- **流程**
1. 客户下单 → 系统拆分订单至各商户。
2. 前端商户端显示新订单 → 可确认、拒单、修改发货信息。
3. 后端记录订单状态(待处理、已发货、完成、异常)。
4. 平台监控整体订单履约情况。
- **决策点**
- 商户拒单 → 系统可触发退款或自动分配给其他商户。
- 超时未处理 → 系统提醒或自动处理。
- **输入**:客户订单数据
- **输出**:拆分后的商户子订单,包含状态更新
- **状态机**`PENDING` → `ACCEPTED` → `SHIPPED` → `COMPLETED` → `REFUNDED`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 订单管理 | `OrderService.ts` | BE-O001 |
| 后端 | 订单拆分 | `OrderSplitService.ts` | BE-O002 |
| 前端 | 商户订单页面 | `MerchantOrderPage.vue` | FE-O001 |
| 前端 | 平台订单监控 | `OrderMonitoringPage.vue` | FE-O002 |
***
## 3⃣4⃣ 多商户库存同步闭环Multi-Merchant Inventory Sync Loop
- **目标**:确保平台和商户端库存实时同步。
- **流程**
1. 商户上传库存信息API/手动)。
2. 平台统一汇总并分发给前端展示。
3. 当客户下单 → 自动扣减对应商户库存。
- **决策点**
- 库存不足 → 阻止下单或显示缺货。
- 库存异常 → 系统报警。
- **输入**:商户库存数据、订单数据
- **输出**:实时同步的库存状态
- **状态机**`SYNCED` → `UPDATING` → `SYNCED` → `ERROR`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 库存管理 | `InventoryService.ts` | BE-I001 |
| 后端 | 库存同步 | `InventorySyncService.ts` | BE-I002 |
| 前端 | 库存管理页面 | `InventoryManagement.vue` | FE-I001 |
***
## 3⃣5⃣ 多商户结算与财务闭环Multi-Merchant Settlement & Finance Loop
- **目标**:自动计算商户收入、平台佣金、手续费及结算周期。
- **流程**
1. 后端计算订单收入、退款、佣金分成。
2. 系统生成结算账单 → 商户可查询。
3. 支持多结算方式(银行、电子钱包)。
4. 自动发起付款(周期结算或即时结算)。
- **决策点**
- 异常订单 → 暂停结算并标记。
- 多币种结算 → 汇率实时更新。
- **输入**:订单数据、支付数据
- **输出**:结算账单、付款记录
- **状态机**`PENDING` → `CALCULATED` → `APPROVED` → `PAID`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 结算服务 | `SettlementService.ts` | BE-S002 |
| 后端 | 财务管理 | `FinanceService.ts` | BE-F001 |
| 前端 | 结算管理页面 | `SettlementManagement.vue` | FE-S002 |
***
## 3⃣6⃣ 商户权限与角色闭环Merchant Roles & Permissions Loop
- **目标**:控制商户内部操作权限,支持多角色管理。
- **流程**
1. 商户创建角色(管理员、仓库、客服等)。
2. 后端配置每个角色的访问权限。
3. 前端动态显示可操作模块。
- **决策点**
- 权限冲突 → 系统提示。
- 异常操作 → 记录日志和告警。
- **输入**:商户角色配置
- **输出**:权限配置,访问控制
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 权限服务 | `RBACService.ts` | BE-R001 |
| 前端 | 权限管理页面 | `PermissionManagement.vue` | FE-R001 |
***
## 3⃣7⃣ 商户数据与分析闭环Merchant Analytics & Reporting Loop
- **目标**:提供独立商户数据分析,同时平台可汇总整体业务指标。
- **流程**
1. 后端收集订单、流量、库存、评价数据。
2. 生成商户专属数据报表和趋势分析。
3. 平台可生成多商户对比分析。
- **决策点**
- 数据异常 → 自动报警。
- 需要合规报表 → 自动生成符合财务/税务规范的报表。
- **输入**:商户业务数据
- **输出**:商户报表、平台分析报告
- **状态机**`RAW` → `PROCESSED` → `GENERATED` → `DISTRIBUTED`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 报表服务 | `ReportService.ts` | BE-R002 |
| 后端 | 数据分析 | `AnalyticsService.ts` | BE-A002 |
| 前端 | 商户报表页面 | `MerchantReportPage.vue` | FE-R002 |
| 前端 | 平台分析页面 | `PlatformAnalyticsPage.vue` | FE-A001 |
***
## 3⃣8⃣ 异常处理闭环Exception & Dispute Loop
- **目标**:处理商户异常、客户投诉、退款退货。
- **流程**
1. 客户发起投诉/退货 → 系统分配给对应商户。
2. 商户处理 → 平台监控处理时效。
3. 处理结果同步前端和财务结算。
- **决策点**
- 超时未处理 → 系统自动介入。
- 争议订单 → 暂停结算,人工复核。
- **输入**:投诉/退货请求
- **输出**:处理结果,财务调整
- **状态机**`SUBMITTED` → `PROCESSING` → `RESOLVED` → `ESCALATED`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 异常处理 | `ExceptionService.ts` | BE-E001 |
| 后端 | 争议解决 | `DisputeResolverService.ts` | BE-D001 |
| 前端 | 异常管理页面 | `ExceptionManagement.vue` | FE-E001 |
***
## 3⃣9⃣ 功能模块化与权限控制闭环Feature Modularization & Permission Control Loop
- **目标**:将系统功能模块化,支持按商户收费,精细化权限控制。
- **流程**
@@ -1122,30 +1328,49 @@
## 3⃣4⃣ 多商户结算与财务闭环Multi-Merchant Settlement & Finance Loop
- **目标**:多商户资金结算、收益分润、账务核对。
- **目标**:多商户资金结算、收益分润、账务核对,确保资金安全和透明
- **流程**
1. **交易清算**
- 订单收入汇总
- 平台服务费扣除
- 商户应得收益计算
- 订单收入汇总(按商户维度)
- 平台服务费扣除(根据合同约定)
- 商户应得收益计算(扣除各项费用后)
- 税费计算与代扣
2. **结算周期**
- 按日/周/月结算
- 按日/周/月结算(商户可选择)
- 自动打款或申请提现
- 结算单生成
- 结算单生成(包含明细和汇总)
- 结算状态跟踪
3. **分润管理**
- 分润规则配置
- 分润规则配置(百分比、固定金额等)
- 多级分销/代理分润
- 分润计算与发放
- 分润报表生成
4. **财务对账**
- 商户账户流水核对
- 异常交易处理
- 财务报表生成
- 异常交易处理(退款、纠纷等)
- 财务报表生成(商户级、平台级)
- 税务报表准备
5. **资金安全**
- 资金流向监控
- 异常资金预警
- 资金冻结与解冻
- **决策点**
- 结算门槛(最低提现金额)
- 手续费规则
- 账期调整
- **输入**:交易数据、商户结算规则、分润配
- **输出**:结算单、账户余额、财务报表
- 手续费规则(提现、转账等)
- 账期调整(根据商户等级)
- 分润比例设
- 异常交易处理流程
- **输入**:交易数据、商户结算规则、分润配置、银行账户信息
- **输出**:结算单、账户余额、财务报表、分润记录
- **状态机**`PENDING` → `PROCESSING` → `COMPLETED` → `FAILED`
- **📋 技术实现指引**
| 层级 | 实现模块 | 关键文件 | 任务ID |
| -- | ------- | -------- | ------ |
| 后端 | 结算服务 | `MerchantSettlementService.ts` | BE-F001 |
| 后端 | 财务管理 | `FinanceService.ts` | BE-F002 |
| 后端 | 分润管理 | `ProfitSharingService.ts` | BE-F003 |
| 前端 | 结算管理 | `SettlementManagement.vue` | FE-F001 |
| 前端 | 财务报表 | `FinanceReport.vue` | FE-F002 |
***
@@ -1178,6 +1403,188 @@
***
## 3⃣6⃣ 恶意买家黑名单闭环Malicious Buyer Blacklist Loop
- **目标**:识别、管理和共享恶意买家信息,降低交易风险。
- **流程**
1. **黑名单管理**
- 手动添加恶意买家(欺诈、拒付、滥用等)
- 自动识别高风险买家(基于行为模式)
- 黑名单等级划分(低/中/高风险)
2. **风险评估**
- 基于买家行为的综合风险评分
- 多维度风险因素分析(退货率、投诉率、拒付率等)
- 实时风险预警
3. **黑名单共享**
- 跨租户黑名单共享机制
- 共享规则配置(自动接受/人工审核)
- 共享状态同步
- **决策点**
- 黑名单阈值设定
- 共享范围控制
- 风险等级判定标准
- **输入**:买家信息、交易记录、行为数据
- **输出**:黑名单记录、风险评分、共享结果
- **状态机**`SUGGESTED` → `PENDING_REVIEW` → `ACTIVE` / `REJECTED` → `EXPIRED`
***
## 3⃣7⃣ 高退货率SKU自动下架/改进建议闭环High Return Rate SKU Auto-Delist & Improvement Loop
- **目标**监控高退货率SKU自动下架风险商品并提供改进建议。
- **流程**
1. **退货率监控**
- 实时计算SKU退货率
- 多维度分析(按平台/店铺/类目)
- 趋势监控和预警
2. **自动下架**
- 阈值触发自动下架
- 多平台下架支持Amazon/Shopee/Lazada/TikTok
- 自动重新上架功能
3. **改进建议**
- 基于退货原因的智能分析
- 分类建议生成(质量/描述/图片/包装/物流等)
- 实施步骤指导和ROI预估
- **决策点**
- 退货率阈值设定
- 自动下架规则配置
- 改进优先级排序
- **输入**订单数据、退货记录、SKU信息
- **输出**高风险SKU列表、下架结果、改进建议
- **状态机**`MONITORED` → `HIGH_RISK` → `AUTO_DELISTED` → `IMPROVEMENT_SUGGESTED` → `RE_LISTED`
***
## 3⃣8⃣ 商业化与增长闭环Monetization & Growth Loop
- **目标**实现系统持续盈利与收入增长非SaaS模式
### 收费模型
#### 1. 功能收费Feature-based
- 高级分析
- 自动化能力
- API调用
#### 2. 交易抽成Transaction-based
- TOC订单抽佣3~10%
- TOB大单服务费
#### 3. 服务收费Service-based
- 代发货
- 仓储服务
- 数据服务
#### 4. 资金沉淀Deposit Float
- 押金沉淀收益
- 账期资金
### 收费触发点
- 功能调用
- 订单完成
- 商家使用服务
- API请求
### 收入放大机制
- ROI分析 → 推荐开功能
- 利润分析 → 推荐加广告
- 订单增长 → 引导升级套餐
### 决策点
- 免费 vs 付费边界
- 抽成比例
- 功能定价策略
### 输入
- 用户行为
- 订单数据
- 利润数据
### 输出
- 收入增长
- 用户付费转化
***
## 3⃣9⃣ 服务编排与执行闭环Service Orchestration Loop
- **目标**:将业务闭环转化为可执行的后端服务流
### 核心原则
- 每个业务闭环必须对应一个 Service Flow
- 所有逻辑必须走 Service 层
### 执行流程
Frontend
→ Controller
→ Service核心编排
→ Repository / External API
→ 返回结果
### 示例
#### 功能开通
Controller
→ FeatureService.openFeature
→ PaymentService.create
→ PaymentCallback
→ PermissionService.grant
### 决策点
- 服务拆分粒度
- 是否异步(消息队列)
- 是否需要补偿机制
### 输出
- 可执行后端服务
- 业务状态流转
***
## 4⃣0⃣ 增长飞轮闭环Growth Flywheel Loop
- **目标**:让系统自动变强、自动赚钱
### 飞轮逻辑
数据 → 利润分析 → 推荐 → 用户行动 → 收入 → 更多数据
### 核心路径
1. 商品数据 → 利润分析
2. 利润高 → 推广广告
3. 广告带订单
4. 订单产生数据
5. 数据优化策略
### TOB路径
询盘 → 报价 → 成交 → 复购 → 信用提升 → 更大订单
### 决策点
- 推荐策略
- 自动化程度
- AI参与程度
### 输出
- GMV增长
- ROI提升
- 用户粘性
***
### 🔍 追踪与审计
- **追踪五元组**