- 重构前端导入和组件结构,优化代码组织 - 添加Java后端基础框架和API实现 - 修复类型定义和接口兼容性问题 - 新增测试页面和工具函数 - 优化国际化支持和错误处理 - 更新依赖配置和构建脚本 新增Java后端模块: - 实现基础认证、订单、支付等服务 - 添加Swagger API文档支持 - 配置数据库连接和缓存 - 实现国际化消息处理 - 添加安全过滤器和限流控制
24 KiB
24 KiB
项目同步清单
本文档记录了整个项目中需要同步的所有内容,确保前后端一致性
1. 类型定义同步
1.1 前后端类型共享
- 前端类型导入:
dashboard/src/types/index.ts从后端导入共享类型 - 后端类型定义:
server/src/shared/types/目录下的类型定义 - 类型边界:遵循 Schema 驱动开发,确保 API 返回数据经过 Schema 验证
1.2 类型定义文件
-
前端本地类型:
certificate.tsdataSourceMap.tsdatasource.tsorder.tsplatform.tsprocurement.tsproduct.tsproductManagement.tsproductSelection.tsuser.tswarehouse.ts
-
后端共享类型:
domain/User.tsdomain/Product.tsdomain/Order.tsdomain/Inventory.tsdomain/ShopInfo.tsdomain/Certificate.tsdomain/ProductSelection.tsbatch-operation.tsenums/index.tsdto/index.tsshared/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 日志格式
{
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.tsStoreStatus.tsBusinessEnums.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 统一错误格式
interface ApiError {
code: string;
message: string;
details?: unknown;
traceId: string;
}
30.2 错误码规范
- 格式:
[模块]_[类型]_[序号] - 确保错误码在整个系统中保持一致
30.3 异常处理
- 全局异常处理机制需要保持一致
- 异常日志记录需要保持一致
31. 五元组追踪同步
31.1 五元组定义
{
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 个方面。
确保这些内容的同步,可以提高系统的一致性、可靠性和可维护性,减少因数据不一致或配置不同步导致的问题。