wurenzhi
e47beffaf9
- 重构前端导入和组件结构，优化代码组织 - 添加Java后端基础框架和API实现 - 修复类型定义和接口兼容性问题 - 新增测试页面和工具函数 - 优化国际化支持和错误处理 - 更新依赖配置和构建脚本 新增Java后端模块： - 实现基础认证、订单、支付等服务 - 添加Swagger API文档支持 - 配置数据库连接和缓存 - 实现国际化消息处理 - 添加安全过滤器和限流控制
944 lines
24 KiB
Markdown
944 lines
24 KiB
Markdown
# 项目同步清单
|
||
|
||
> 本文档记录了整个项目中需要同步的所有内容，确保前后端一致性
|
||
|
||
---
|
||
|
||
## 1. 类型定义同步
|
||
|
||
### 1.1 前后端类型共享
|
||
- **前端类型导入**：`dashboard/src/types/index.ts` 从后端导入共享类型
|
||
- **后端类型定义**：`server/src/shared/types/` 目录下的类型定义
|
||
- **类型边界**：遵循 Schema 驱动开发，确保 API 返回数据经过 Schema 验证
|
||
|
||
### 1.2 类型定义文件
|
||
- **前端本地类型**：
|
||
- `certificate.ts`
|
||
- `dataSourceMap.ts`
|
||
- `datasource.ts`
|
||
- `order.ts`
|
||
- `platform.ts`
|
||
- `procurement.ts`
|
||
- `product.ts`
|
||
- `productManagement.ts`
|
||
- `productSelection.ts`
|
||
- `user.ts`
|
||
- `warehouse.ts`
|
||
|
||
- **后端共享类型**：
|
||
- `domain/User.ts`
|
||
- `domain/Product.ts`
|
||
- `domain/Order.ts`
|
||
- `domain/Inventory.ts`
|
||
- `domain/ShopInfo.ts`
|
||
- `domain/Certificate.ts`
|
||
- `domain/ProductSelection.ts`
|
||
- `batch-operation.ts`
|
||
- `enums/index.ts`
|
||
- `dto/index.ts`
|
||
- `shared/index.ts`
|
||
|
||
### 1.3 类型转换流程
|
||
```
|
||
API 返回数据 → Schema 验证 → DTO 转换 → Domain 模型
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 图标管理同步
|
||
|
||
### 2.1 统一图标导出
|
||
- **图标文件**：`dashboard/src/imports/icons.ts`
|
||
- **图标库**：Ant Design Icons
|
||
- **使用原则**：确保整个项目中图标使用的一致性
|
||
|
||
### 2.2 图标使用规范
|
||
- 避免重复导入图标
|
||
- 避免使用不同版本的图标
|
||
- 统一图标命名和引用方式
|
||
|
||
---
|
||
|
||
## 3. 服务层同步
|
||
|
||
### 3.1 数据源服务
|
||
- **服务导出文件**：`dashboard/src/services/index.ts`
|
||
- **数据源服务列表**：
|
||
- abTestDataSource
|
||
- adOptimizationDataSource
|
||
- afterSalesDataSource
|
||
- aiActionTaskDataSource
|
||
- aiSuggestionDataSource
|
||
- analyticsDataSource
|
||
- arbitrageDataSource
|
||
- auditDataSource
|
||
- autoExecutionDataSource
|
||
- b2bTradeDataSource
|
||
- baseDataSource
|
||
- batchOperationDataSource
|
||
- blacklistDataSource
|
||
- certificateDataSource
|
||
- chatbotDataSource
|
||
- clientDataSource
|
||
- commandDataSource
|
||
- creativeDataSource
|
||
- crossBorderIntegrationDataSource
|
||
- customerDataSource
|
||
- dashboardDataSource
|
||
- dynamicPricingDataSource
|
||
- exchangeDataSource
|
||
- executionResultDataSource
|
||
- financeDataSource
|
||
- governanceDataSource
|
||
- humanApprovalDataSource
|
||
- independentSiteDataSource
|
||
- instanceDataSource
|
||
- inventoryDataSource
|
||
- leaderboardDataSource
|
||
- logisticsDataSource
|
||
- marketingDataSource
|
||
- materialProcessingDataSource
|
||
- merchantDataSource
|
||
- monitoringDataSource
|
||
- nlpDataSource
|
||
- omnichannelCommunicationDataSource
|
||
- omnichannelDataSource
|
||
- omnichannelMarketingDataSource
|
||
- operationAgentDataSource
|
||
- operationLogDataSource
|
||
- orderDataSource
|
||
- orderManagementDataSource
|
||
- platformAuthDataSource
|
||
- procurementDataSource
|
||
- productDataSource
|
||
- productManagementDataSource
|
||
- productSelectionDataSource
|
||
- recommendationDataSource
|
||
- reportsDataSource
|
||
- returnDataSource
|
||
- roleDataSource
|
||
- saasTenantDataSource
|
||
- serviceManagerDataSource
|
||
- settingsDataSource
|
||
- shopDataSource
|
||
- shopReportDataSource
|
||
- sovereigntyDataSource
|
||
- storeCreationDataSource
|
||
- suppliersDataSource
|
||
- syncDataSource
|
||
- systemStatusDataSource
|
||
- taskCenterDataSource
|
||
- telemetryDataSource
|
||
- traceDataSource
|
||
- unifiedFulfillmentDataSource
|
||
- userAssetDataSource
|
||
- userDataSource
|
||
- vaultDataSource
|
||
- warehouseDataSource
|
||
- webhookDataSource
|
||
|
||
### 3.2 API 服务
|
||
- **前端 API 服务**：`dashboard/src/services/api/`
|
||
- **后端 API 接口**：`server/src/api/`
|
||
- **同步要求**：确保前端 API 服务与后端 API 接口保持一致
|
||
|
||
### 3.3 服务调用链
|
||
- 确保服务层的调用链清晰
|
||
- 避免跨 Domain 直接操作数据库模型
|
||
- 通过 Service 层暴露接口或 EventBus 异步通信
|
||
|
||
---
|
||
|
||
## 4. 导入配置同步
|
||
|
||
### 4.1 统一导入
|
||
- **导入配置文件**：`dashboard/src/imports/index.ts`
|
||
- **导入模块**：
|
||
- react
|
||
- antd
|
||
- icons
|
||
- charts
|
||
- utils
|
||
- datasources
|
||
- constants
|
||
- types
|
||
|
||
### 4.2 模块依赖
|
||
- 确保模块之间的依赖关系清晰
|
||
- 避免循环依赖
|
||
- 统一模块导入方式
|
||
|
||
---
|
||
|
||
## 5. 业务闭环同步
|
||
|
||
### 5.1 商品域
|
||
- **数据采集与清洗闭环**
|
||
- 状态变化：`RAW_DATA` → `CLEANED` → `ANALYZED` → `READY_FOR_LISTING`
|
||
- 触发条件：定时任务、手动触发、事件触发
|
||
|
||
- **商品刊登闭环**
|
||
- 状态变化：`READY_FOR_LISTING` → `LISTING_IN_PROGRESS` → `LISTED` → `MONITORING` → `NEED_UPDATE` → `UPDATED`
|
||
- 决策点：前置套利/利润分析、TOB阶梯价审批策略
|
||
|
||
- **素材管理闭环**
|
||
- 状态机：`UPLOADED` → `PROCESSING` → `PENDING_REVIEW` → `APPROVED` → `IN_USE` → `ARCHIVED`/`REJECTED`
|
||
|
||
- **商品主数据闭环**
|
||
- 流程：数据采集 → 标准化处理 → 主数据维护 → 数据分发
|
||
|
||
- **SKU变体与结构闭环**
|
||
- 流程：SPU创建 → SKU生成 → 平台SKU映射 → 同步管理
|
||
|
||
- **多平台商品管理闭环**
|
||
- 状态机：`PRODUCT_CREATED` → `PLATFORM_MAPPED` → `SYNCHRONIZED` → `UPDATED`
|
||
|
||
### 5.2 订单域
|
||
- **订单履约闭环**
|
||
- 状态机：`PULLED` → `PENDING_REVIEW` → `CONFIRMED` → `ALLOCATED` → `READY_TO_SHIP` → `SHIPPED` → `DELIVERED` → `CLOSED`
|
||
|
||
- **售后逆向闭环**
|
||
- 流程：售后请求处理 → 退货处理 → 退款处理
|
||
|
||
- **订单集中管理闭环**
|
||
- 状态流转：`available → requested → shipped → completed`
|
||
|
||
- **一站式订单履约闭环**
|
||
- 状态机：`ORDER_RECEIVED` → `ORDER_PROCESSED` → `IN_FULFILLMENT` → `SHIPPED` → `DELIVERED` → `SYNCHRONIZED`
|
||
|
||
- **订单拆分与合并闭环**
|
||
- 流程：订单分析 → 拆分/合并决策 → 子订单生成 → 履约执行
|
||
|
||
- **异常订单处理闭环**
|
||
- 流程：异常检测 → 分类处理 → 解决方案执行 → 结果反馈
|
||
|
||
### 5.3 库存域
|
||
- 库存管理
|
||
- 库存同步
|
||
- 库存预警
|
||
|
||
### 5.4 财务域
|
||
- 财务核算
|
||
- 对账
|
||
- 结算
|
||
|
||
---
|
||
|
||
## 6. 多平台数据同步
|
||
|
||
### 6.1 平台集成
|
||
- **支持平台**：
|
||
- TikTok
|
||
- Shopee
|
||
- Amazon
|
||
- eBay
|
||
- AliExpress
|
||
- Temu
|
||
- Shopify
|
||
- Walmart
|
||
- MercadoLibre
|
||
- Lazada
|
||
- Coupang
|
||
- SHEIN
|
||
|
||
### 6.2 跨平台数据
|
||
- 跨平台商品数据一致性
|
||
- 跨平台订单数据一致性
|
||
- 跨平台库存数据一致性
|
||
|
||
### 6.3 平台状态
|
||
- 平台商品状态实时同步
|
||
- 平台订单状态实时同步
|
||
- 平台库存状态实时同步
|
||
|
||
---
|
||
|
||
## 7. 权限和组织架构同步
|
||
|
||
### 7.1 RBAC 模型
|
||
- **预设角色**：
|
||
- ADMIN - 全权
|
||
- MANAGER - 运营主管
|
||
- OPERATOR - 运营专员
|
||
- FINANCE - 财务主管
|
||
- SOURCING - 采购专家
|
||
- LOGISTICS - 物流专家
|
||
- ANALYST - 数据分析师
|
||
|
||
### 7.2 组织层级结构
|
||
```
|
||
平台（Platform）
|
||
↓
|
||
商户/公司（Tenant/Organization）
|
||
↓
|
||
组织结构（Org Tree）
|
||
├── 部门A（主管）
|
||
│ ├── 组A1（组长）
|
||
│ │ ├── 员工1
|
||
│ │ └── 员工2
|
||
│ └── 组A2（组长）
|
||
│ └── 员工3
|
||
└── 部门B（主管）
|
||
└── ...
|
||
```
|
||
|
||
### 7.3 数据范围类型
|
||
- **SELF** - 只看自己
|
||
- **TEAM** - 看自己组
|
||
- **DEPT** - 看自己部门
|
||
- **ORG** - 看整个公司
|
||
- **ALL** - 全平台（超管）
|
||
|
||
### 7.4 店铺角色权限
|
||
- **owner** - 拥有者
|
||
- **admin** - 管理员
|
||
- **operator** - 运营
|
||
- **viewer** - 只读
|
||
|
||
### 7.5 授权模型
|
||
- **API授权**：Shopify、Amazon
|
||
- **Agent授权**：TikTok、Shopee
|
||
|
||
---
|
||
|
||
## 8. 状态机同步
|
||
|
||
### 8.1 状态定义
|
||
- 确保各个业务闭环的状态机定义在整个系统中保持一致
|
||
- 状态机定义文件：`server/src/core/engine/`
|
||
|
||
### 8.2 状态流转
|
||
- 确保状态流转的规则和触发条件在整个系统中保持一致
|
||
- 状态流转必须通过 Service 层
|
||
|
||
### 8.3 状态监控
|
||
- 确保状态变更的监控和通知机制同步
|
||
- 状态变更必须记录日志
|
||
|
||
---
|
||
|
||
## 9. 配置管理同步
|
||
|
||
### 9.1 配置驱动
|
||
- 确保配置驱动的设计在整个系统中保持一致
|
||
- 配置文件：`server/src/config/`
|
||
|
||
### 9.2 环境变量
|
||
- 前端环境变量：
|
||
- `REACT_APP_USE_MOCK` - 前端Mock开关
|
||
- 后端环境变量：
|
||
- `USE_MOCK` - 后端Mock开关
|
||
|
||
### 9.3 Mock 配置
|
||
- Mock 文件目录：`dashboard/src/mock/`
|
||
- Mock 数据定义：`dashboard/src/mock/data/`
|
||
- Mock 配置：`dashboard/src/mock/msw.ts`
|
||
|
||
---
|
||
|
||
## 10. 日志和监控同步
|
||
|
||
### 10.1 日志格式
|
||
```typescript
|
||
{
|
||
timestamp: string;
|
||
level: string;
|
||
traceId: string;
|
||
tenantId: string;
|
||
shopId: string;
|
||
taskId?: string;
|
||
service: string;
|
||
method: string;
|
||
message: string;
|
||
duration?: number;
|
||
error?: ErrorInfo;
|
||
}
|
||
```
|
||
|
||
### 10.2 日志级别
|
||
- **DEBUG** - 开发调试
|
||
- **INFO** - 正常业务流程
|
||
- **WARN** - 潜在问题
|
||
- **ERROR** - 错误异常
|
||
|
||
### 10.3 监控指标
|
||
- 确保监控指标的定义和采集在整个系统中保持一致
|
||
- 监控服务：`server/src/core/monitoring/MonitoringService.ts`
|
||
|
||
### 10.4 告警机制
|
||
- 确保告警机制的配置和触发条件在整个系统中保持一致
|
||
- 告警类型：系统告警、业务告警、性能告警
|
||
|
||
---
|
||
|
||
## 11. 国际化同步
|
||
|
||
### 11.1 语言文件
|
||
- **中文**：`dashboard/src/locales/zh-CN.ts`
|
||
- **英文**：`dashboard/src/locales/en-US.ts`
|
||
|
||
### 11.2 国际化策略
|
||
- 确保国际化的实现策略在整个系统中保持一致
|
||
- 支持的语言：中文、英文
|
||
|
||
---
|
||
|
||
## 12. 插件系统同步
|
||
|
||
### 12.1 插件注册
|
||
- 插件注册文件：`dashboard/src/plugins/`
|
||
- 插件管理器：`server/src/core/runtime/PluginManager.ts`
|
||
|
||
### 12.2 插件接口
|
||
- 确保插件接口的定义和实现在整个系统中保持一致
|
||
- 插件类型定义：`dashboard/src/plugins/FeatureTypes.ts`
|
||
|
||
### 12.3 扩展点
|
||
- 确保扩展点的定义与前端扩展机制保持一致
|
||
- 扩展点注册：`dashboard/src/plugins/FeatureRegistry.ts`
|
||
|
||
---
|
||
|
||
## 13. 数据模型同步
|
||
|
||
### 13.1 三层商品模型
|
||
```
|
||
SPU（产品层）
|
||
│
|
||
├── SKU-001（库存单元层）
|
||
│ ├── Listing-A（平台商品层）
|
||
│ ├── Listing-B（平台商品层）
|
||
│ └── Listing-C（平台商品层）
|
||
│
|
||
├── SKU-002（库存单元层）
|
||
│ └── Listing-D（平台商品层）
|
||
│
|
||
└── SKU-003（库存单元层）
|
||
└── Listing-E（平台商品层）
|
||
```
|
||
|
||
### 13.2 订单模型
|
||
- 订单模型的定义和使用在整个系统中保持一致
|
||
- 订单状态机：`server/src/core/engine/OrderStateMachine.ts`
|
||
|
||
### 13.3 用户模型
|
||
- 用户模型的定义和使用在整个系统中保持一致
|
||
- 用户类型定义：`server/src/shared/types/domain/User.ts`
|
||
|
||
---
|
||
|
||
## 14. 价格体系同步
|
||
|
||
### 14.1 三层价格体系
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 1️⃣ 基准价层（Base Price Layer） │
|
||
│ SKU.base_price │
|
||
│ 用途：统一锚点、人工理解 │
|
||
└──────────────┬──────────────────────────┘
|
||
│
|
||
↓
|
||
┌─────────────────────────────────────────┐
|
||
│ 2️⃣ 策略层（Strategy Layer） │
|
||
│ PriceStrategy: │
|
||
│ - scope: 平台/店铺/Listing │
|
||
│ - type: multiplier/fixed/dynamic │
|
||
│ 用途：规则定义、批量控制 │
|
||
└──────────────┬──────────────────────────┘
|
||
│
|
||
↓
|
||
┌─────────────────────────────────────────┐
|
||
│ 3️⃣ Listing层（Final Price Layer） │
|
||
│ PlatformListing.price │
|
||
│ 用途：真正赚钱的地方 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 14.2 价格策略类型
|
||
- **MULTIPLIER** - 倍率定价
|
||
- **FIXED** - 固定定价
|
||
- **DYNAMIC** - 动态定价
|
||
|
||
### 14.3 价格计算公式
|
||
```
|
||
最终价格 = override_price || strategy计算结果 || base_price
|
||
```
|
||
|
||
### 14.4 多平台定价
|
||
- 确保多平台定价的策略和执行在整个系统中保持一致
|
||
- 价格服务：`server/src/api/controllers/PricingController.ts`
|
||
|
||
---
|
||
|
||
## 15. 数据同步策略
|
||
|
||
### 15.1 同步频率
|
||
- 确保数据同步的频率和触发条件在整个系统中保持一致
|
||
- 同步服务：`dashboard/src/services/syncDataSource.ts`
|
||
|
||
### 15.2 冲突处理
|
||
- 确保数据同步的冲突处理机制在整个系统中保持一致
|
||
- 冲突处理策略：先声明者优先、后到者避让、协商解决
|
||
|
||
### 15.3 同步状态
|
||
- 确保数据同步的状态监控和异常处理在整个系统中保持一致
|
||
- 同步状态监控：实时同步状态、异常状态及时处理
|
||
|
||
---
|
||
|
||
## 16. 枚举类型同步
|
||
|
||
### 16.1 前端枚举
|
||
- 确保前端使用的枚举类型与后端保持一致
|
||
- 枚举定义：`dashboard/src/types/` 下的枚举类型
|
||
|
||
### 16.2 后端枚举
|
||
- **枚举定义文件**：`server/src/shared/types/enums/`
|
||
- `PlatformType.ts`
|
||
- `StoreStatus.ts`
|
||
- `BusinessEnums.ts`
|
||
|
||
### 16.3 枚举值
|
||
- 确保枚举值的命名和数值在整个系统中保持一致
|
||
- 枚举值的使用必须统一
|
||
|
||
---
|
||
|
||
## 17. 配置文件同步
|
||
|
||
### 17.1 依赖版本
|
||
- **前端依赖**：`dashboard/package.json`
|
||
- **后端依赖**：`server/package.json`
|
||
- 确保前后端依赖版本保持一致
|
||
|
||
### 17.2 环境配置
|
||
- **前端环境配置**：
|
||
- `.env.development`
|
||
- `.env.production`
|
||
- **后端环境配置**：
|
||
- 对应的环境配置文件
|
||
- 确保环境配置保持一致
|
||
|
||
### 17.3 构建配置
|
||
- **前端构建配置**：`dashboard/.umirc.ts`
|
||
- **后端构建配置**：`server/` 下的构建配置
|
||
- 确保构建配置保持一致
|
||
|
||
---
|
||
|
||
## 18. 平台连接器同步
|
||
|
||
### 18.1 连接器实现
|
||
- **连接器目录**：`server/src/core/connectors/`
|
||
- **支持平台**：
|
||
- AliExpressConnector.ts
|
||
- Alibaba1688Connector.ts
|
||
- AmazonConnector.ts
|
||
- FacebookAdsConnector.ts
|
||
- GoogleAdsConnector.ts
|
||
- ShopeeConnector.ts
|
||
- ShopifyConnector.ts
|
||
- TemuConnector.ts
|
||
- TikTokAdsConnector.ts
|
||
- TikTokConnector.ts
|
||
|
||
### 18.2 适配器同步
|
||
- **适配器目录**：`server/src/core/operation/adapters/`
|
||
- **适配器列表**：
|
||
- AliExpressAdapter.ts
|
||
- AmazonAdapter.ts
|
||
- EbayAdapter.ts
|
||
- GenericAdapter.ts
|
||
- ShopeeAdapter.ts
|
||
- TikTokAdapter.ts
|
||
|
||
### 18.3 平台API
|
||
- 确保平台API的调用方式和参数在前后端保持一致
|
||
- API文档：`docs/api/` 目录下的平台API文档
|
||
|
||
---
|
||
|
||
## 19. 核心引擎同步
|
||
|
||
### 19.1 状态机
|
||
- **状态机目录**：`server/src/core/engine/`
|
||
- **状态机列表**：
|
||
- CoreEngineService.ts
|
||
- DataStateMachine.ts
|
||
- OrderStateMachine.ts
|
||
- ProductStateMachine.ts
|
||
- RuleEngineService.ts
|
||
- WorkflowEngineService.ts
|
||
|
||
### 19.2 工作流引擎
|
||
- 工作流引擎的定义和执行需要与前端流程保持一致
|
||
- 工作流服务：`server/src/core/engine/WorkflowEngineService.ts`
|
||
|
||
### 19.3 规则引擎
|
||
- 规则引擎的规则定义和执行需要与前端业务逻辑保持一致
|
||
- 规则服务：`server/src/core/engine/RuleEngineService.ts`
|
||
|
||
---
|
||
|
||
## 20. 数据隔离同步
|
||
|
||
### 20.1 店铺隔离
|
||
- **店铺隔离服务**：`server/src/core/isolation/ShopIsolationService.ts`
|
||
- 确保与前端店铺管理保持一致
|
||
|
||
### 20.2 租户隔离
|
||
- 租户隔离的实现需要与前端租户管理保持一致
|
||
- 租户控制器：`server/src/api/controllers/TenantController.ts`
|
||
|
||
### 20.3 数据范围
|
||
- 数据范围的定义和验证需要与前端权限管理保持一致
|
||
- 数据范围类型：SELF, TEAM, DEPT, ORG, ALL
|
||
|
||
---
|
||
|
||
## 21. 安全服务同步
|
||
|
||
### 21.1 认证服务
|
||
- **认证控制器**：`server/src/api/controllers/AuthController.ts`
|
||
- 确保与前端登录和授权保持一致
|
||
|
||
### 21.2 授权服务
|
||
- **RBAC引擎**：`server/src/core/auth/RBACEngine.ts`
|
||
- 确保与前端权限管理保持一致
|
||
|
||
### 21.3 安全配置
|
||
- 安全配置的定义需要与前端安全措施保持一致
|
||
- 安全服务：`server/src/core/security/`
|
||
|
||
---
|
||
|
||
## 22. 监控和日志同步
|
||
|
||
### 22.1 监控服务
|
||
- **监控服务**：`server/src/core/monitoring/MonitoringService.ts`
|
||
- 确保与前端监控保持一致
|
||
|
||
### 22.2 日志服务
|
||
- 日志服务的实现需要与前端日志记录保持一致
|
||
- 日志格式和级别统一
|
||
|
||
### 22.3 告警机制
|
||
- 告警机制的定义需要与前端通知保持一致
|
||
- 告警类型和触发条件统一
|
||
|
||
---
|
||
|
||
## 23. 数据治理同步
|
||
|
||
### 23.1 数据质量
|
||
- **数据质量服务**：`server/src/core/data/DataQualityService.ts`
|
||
- 确保与前端数据管理保持一致
|
||
|
||
### 23.2 数据合规
|
||
- **数据合规服务**：`server/src/core/governance/DataComplianceService.ts`
|
||
- 确保与前端合规管理保持一致
|
||
|
||
### 23.3 数据集成
|
||
- **数据集成平台**：`server/src/core/data/DataIntegrationPlatform.ts`
|
||
- 确保与前端数据同步保持一致
|
||
|
||
---
|
||
|
||
## 24. 服务编排同步
|
||
|
||
### 24.1 服务注册
|
||
- **服务注册表**：`server/src/core/orchestrator/ServiceRegistry.ts`
|
||
- 确保与前端服务调用保持一致
|
||
|
||
### 24.2 服务监控
|
||
- **服务监控**：`server/src/core/orchestrator/ServiceMonitor.ts`
|
||
- 确保与前端服务状态保持一致
|
||
|
||
### 24.3 服务编排
|
||
- **服务编排器**：`server/src/core/orchestrator/ServiceOrchestrator.ts`
|
||
- 确保与前端业务流程保持一致
|
||
|
||
---
|
||
|
||
## 25. 部署和迁移同步
|
||
|
||
### 25.1 部署脚本
|
||
- 前端和后端的部署脚本需要保持一致
|
||
- CI/CD 配置：`.github/workflows/ci-cd.yml`
|
||
|
||
### 25.2 数据库迁移
|
||
- 数据库迁移的实现需要与前端数据模型保持一致
|
||
- 数据库配置：`server/src/config/database.ts`
|
||
|
||
### 25.3 版本管理
|
||
- 版本管理的实现需要与前端版本控制保持一致
|
||
- 版本号统一管理
|
||
|
||
---
|
||
|
||
## 26. 插件和扩展同步
|
||
|
||
### 26.1 插件管理器
|
||
- **插件管理器**：`server/src/core/runtime/PluginManager.ts`
|
||
- 确保与前端插件系统保持一致
|
||
|
||
### 26.2 扩展点
|
||
- 扩展点的定义需要与前端扩展机制保持一致
|
||
- 扩展点注册统一
|
||
|
||
### 26.3 插件接口
|
||
- 插件接口的定义需要与前端插件实现保持一致
|
||
- 插件类型定义统一
|
||
|
||
---
|
||
|
||
## 27. 测试同步
|
||
|
||
### 27.1 测试用例
|
||
- 前端和后端的测试用例需要保持一致
|
||
- 测试目录：`server/src/__tests__/`
|
||
|
||
### 27.2 测试数据
|
||
- 测试数据的定义需要与前端和后端测试保持一致
|
||
- Mock 数据：`dashboard/src/mock/data/`
|
||
|
||
### 27.3 测试环境
|
||
- 测试环境的配置需要与前端和后端测试保持一致
|
||
- 测试配置：`dashboard/jest.config.js`, `server/jest.config.js`
|
||
|
||
---
|
||
|
||
## 28. 文档同步
|
||
|
||
### 28.1 API文档
|
||
- API文档的定义需要与前端和后端实现保持一致
|
||
- API文档目录：`docs/api/`
|
||
|
||
### 28.2 架构文档
|
||
- 架构文档的定义需要与前端和后端架构保持一致
|
||
- 架构文档目录：`docs/ARCH/`, `docs/archive/01_Architecture/`
|
||
|
||
### 28.3 业务文档
|
||
- 业务文档的定义需要与前端和后端业务逻辑保持一致
|
||
- 业务文档目录：`docs/loops/`
|
||
|
||
---
|
||
|
||
## 29. TypeScript 编译同步
|
||
|
||
### 29.1 编译配置
|
||
- **前端编译配置**：`dashboard/tsconfig.json`
|
||
- **后端编译配置**：`server/tsconfig.json`
|
||
- 确保编译配置保持一致
|
||
|
||
### 29.2 类型检查
|
||
- 确保前后端类型检查规则保持一致
|
||
- 禁止使用 `any` 类型，使用 `unknown` + 类型守卫
|
||
|
||
### 29.3 编译错误
|
||
- 确保编译错误的处理方式保持一致
|
||
- 编译错误必须阻断 CI/CD
|
||
|
||
---
|
||
|
||
## 30. 错误处理同步
|
||
|
||
### 30.1 统一错误格式
|
||
```typescript
|
||
interface ApiError {
|
||
code: string;
|
||
message: string;
|
||
details?: unknown;
|
||
traceId: string;
|
||
}
|
||
```
|
||
|
||
### 30.2 错误码规范
|
||
- 格式：`[模块]_[类型]_[序号]`
|
||
- 确保错误码在整个系统中保持一致
|
||
|
||
### 30.3 异常处理
|
||
- 全局异常处理机制需要保持一致
|
||
- 异常日志记录需要保持一致
|
||
|
||
---
|
||
|
||
## 31. 五元组追踪同步
|
||
|
||
### 31.1 五元组定义
|
||
```typescript
|
||
{
|
||
tenantId: string;
|
||
shopId: string;
|
||
taskId: string;
|
||
traceId: string;
|
||
businessType: 'TOC' | 'TOB';
|
||
}
|
||
```
|
||
|
||
### 31.2 追踪机制
|
||
- 确保五元组追踪在整个系统中保持一致
|
||
- 所有任务与日志必须携带五元组
|
||
|
||
### 31.3 追踪ID
|
||
- 确保追踪ID的生成和使用在整个系统中保持一致
|
||
- 追踪ID服务：`server/src/core/runtime/SnowflakeIDService.ts`
|
||
|
||
---
|
||
|
||
## 32. Mock 数据同步
|
||
|
||
### 32.1 Mock 数据原则
|
||
- 禁止硬编码 Mock 数据
|
||
- 通过 DataSource 抽象层获取数据
|
||
- 环境变量控制：`REACT_APP_USE_MOCK`, `USE_MOCK`
|
||
|
||
### 32.2 Mock 文件规范
|
||
- Mock 文件必须包含 `[MOCK]` 标记
|
||
- Mock 文件必须放在 `/mock` 目录
|
||
- Mock 数据定义：`dashboard/src/mock/data/`
|
||
|
||
### 32.3 AI 识别规则
|
||
- AI 忽略 `/mock` 目录下所有文件
|
||
- AI 忽略包含 `[MOCK]` 标记的文件
|
||
- AI 优先分析 `/services` 下的 DataSource 层
|
||
|
||
---
|
||
|
||
## 33. 逻辑集中化同步
|
||
|
||
### 33.1 核心原则
|
||
- 所有业务逻辑必须集中在 Service 层
|
||
- 禁止分散在 Controller、前端或数据库操作中
|
||
|
||
### 33.2 Controller 层职责
|
||
- 接收 HTTP 请求和参数验证
|
||
- 调用 Service 层处理业务逻辑
|
||
- 返回响应给前端
|
||
- 权限校验（通过 `authorize()` 中间件）
|
||
|
||
### 33.3 Service 层职责
|
||
- 业务逻辑编排和状态流转
|
||
- 多模块协同和数据一致性保证
|
||
- 事务管理和异常处理
|
||
- 调用 Repository 层或外部 API
|
||
|
||
---
|
||
|
||
## 34. 任务包领取同步
|
||
|
||
### 34.1 任务包定义
|
||
```
|
||
任务包 = 同一闭环的连续任务 + 依赖链完整 + 文件归属明确
|
||
```
|
||
|
||
### 34.2 领取规则
|
||
- 优先领取任务包
|
||
- 最小粒度：单次领取不少于 2 个相关任务
|
||
- 依赖自包含：领取的任务包内依赖必须闭环
|
||
|
||
### 34.3 任务包类型
|
||
- **闭环包**：同一业务闭环的全部任务
|
||
- **模块包**：同一模块的连续任务
|
||
- **依赖链包**：有依赖关系的任务链
|
||
|
||
---
|
||
|
||
## 35. 协作防撞车同步
|
||
|
||
### 35.1 模块分区锁定
|
||
- 领取任务时必须声明占用的模块/闭环名称
|
||
- 涉及的主要文件路径
|
||
- 预计完成时间
|
||
|
||
### 35.2 文件占用声明
|
||
- 在 Task_Overview.md 顶部维护 🔒 当前占用区
|
||
- 谁领取谁编辑
|
||
- 后写入方必须先 Read 最新内容，增量合并
|
||
|
||
### 35.3 撞车处理优先级
|
||
- 先声明者优先
|
||
- 后到者避让
|
||
- 协商解决
|
||
|
||
---
|
||
|
||
## 36. 利润红线同步
|
||
|
||
### 36.1 利润红线定义
|
||
- B2B 利润率 < 15% → 禁止报价
|
||
- B2C 利润率 < 20% → 触发风控预警
|
||
|
||
### 36.2 计价收敛
|
||
- 所有价格计算必须走 PricingService
|
||
- 禁止 Controller 或前端硬编码价格公式
|
||
|
||
### 36.3 套利计算口径
|
||
- 禁止仅用 "售价 - 采购价" 判断套利
|
||
- 必须使用净利公式（含平台费/物流/税费/汇率/售后/广告摊销）
|
||
|
||
---
|
||
|
||
## 37. 无 API 平台约束同步
|
||
|
||
### 37.1 No-API Bridge
|
||
- 必须走 No-API Bridge + PENDING_REVIEW
|
||
- 禁止全自动直发
|
||
|
||
### 37.2 Win 节点隔离
|
||
- 一店一上下文：profileDir/proxy/fingerprintPolicy
|
||
- 同店任务：严格串行执行
|
||
|
||
---
|
||
|
||
## 38. 企业交付底线同步
|
||
|
||
### 38.1 必备功能
|
||
- ✅ 租户隔离
|
||
- ✅ 审计追责
|
||
- ✅ 配额治理
|
||
- ✅ SLA 指标可观测
|
||
|
||
### 38.2 交付标准
|
||
- 数据库表已初始化
|
||
- 核心逻辑已闭环
|
||
- 通过 GetDiagnostics 校验
|
||
|
||
---
|
||
|
||
## 39. 代码质量门禁同步
|
||
|
||
### 39.1 命名规范
|
||
- 服务类统一使用 `Service` 后缀
|
||
- 禁止使用 `Manager`/`Helper` 等后缀
|
||
|
||
### 39.2 注释规范
|
||
- 每个服务类包含完整 JSDoc
|
||
- 明确标识任务ID和功能描述
|
||
|
||
### 39.3 文件规模限制
|
||
- 单文件 ≤ 1500 行
|
||
- 单函数 ≤ 120 行
|
||
- UI 组件 ≤ 300 行
|
||
|
||
---
|
||
|
||
## 40. 数据库约束同步
|
||
|
||
### 40.1 表命名规范
|
||
- 所有表必须以 `cf_` 开头
|
||
- 金额字段必须使用 `decimal(10,2)`，禁止 float/double
|
||
- 物理属性单位：长度, 重量(kg), 体积(m³)
|
||
|
||
### 40.2 数据完整性
|
||
- cf_product 表必须保证 (platform, productId) 唯一
|
||
- images/skus/attributes 入库前序列化，出库解析
|
||
- 所有建表语句必须使用 `db.schema.hasTable` 前置校验
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
以上是整个项目中需要同步的所有内容，涵盖了类型定义、图标管理、服务层、导入配置、业务闭环、多平台数据、权限组织架构、状态机、配置管理、日志监控、国际化、插件系统、数据模型、价格体系、数据同步策略、枚举类型、配置文件、平台连接器、核心引擎、数据隔离、安全服务、监控日志、数据治理、服务编排、部署迁移、插件扩展、测试、文档、TypeScript 编译、错误处理、五元组追踪、Mock 数据、逻辑集中化、任务包领取、协作防撞车、利润红线、无 API 平台约束、企业交付底线、代码质量门禁、数据库约束等 40 个方面。
|
||
|
||
确保这些内容的同步，可以提高系统的一致性、可靠性和可维护性，减少因数据不一致或配置不同步导致的问题。 |