Files

wurenzhi cd55097dbf docs: 重构并删除docs11目录，更新项目文档结构

删除旧的docs11目录及其所有内容，包括：
- 业务蓝图文档(business-blueprint.md)
- 数据API规范(data-api-specs.md)
- 系统架构文档(system-architecture.md)
- 模块蓝图文档(module-blueprints.md)
- 治理标准文档(governance-standards.md)
- 质量标准文档(quality-optimization.md)
- 任务总览文档(Crawlful_Hub_Task_Overview_Full_v1.md)
- README.md等文件

同时更新了docs目录下的现有文档：
- 更新SERVICE_MAP.md强化服务层职责和调用规范
- 更新Service_Design.md明确服务层设计规范和边界
- 更新项目规则文档加入逻辑集中化原则
- 统一调整了文档表格格式和结构

2026-03-18 21:51:52 +08:00

19 KiB

Raw Blame History

📊 开发进度互通文档

🎯 文档目的

本文档用于与AI开发助手（GPT）互通开发进度，确保双方对项目状态有清晰的了解，避免信息断层和重复工作。

🔍 开发概览

项目定位

商业模式：非 SaaS 订阅制 + 功能收费体系
核心策略：商户入驻免费 → 基础功能可用 → 增值功能收费 → 平台监控与结算闭环
技术栈：Node.js + TypeScript + React + Umi

当前阶段

阶段：服务编排层实现与完善 + 前端优化
核心目标：构建可收费的多商户业务闭环，确保前端交互流畅、功能完善
架构升级：从"接口驱动" → "服务驱动"，前端从"基础实现" → "优化完善"

关键里程碑

里程碑	状态	预计完成时间	实际完成时间
多商户业务闭环文档完善	✅ 已完成	2026-03-18	2026-03-18
服务编排地图（SERVICE_MAP）	✅ 已完成	2026-03-18	2026-03-18
领域模型（DOMAIN_MODEL）	✅ 已完成	2026-03-18	2026-03-18
状态机定义（STATE_MACHINE）	✅ 已完成	2026-03-18	2026-03-18
功能开通服务实现	✅ 已完成	2026-03-18	2026-03-18
服务层代码实现与修复	✅ 已完成	2026-03-18	2026-03-18
前端服务启动	✅ 已完成	2026-03-18	2026-03-18
后端服务启动	✅ 已完成	2026-03-18	2026-03-18
前端优化	✅ 已完成	2026-03-18	2026-03-18
前端页面骨架创建	✅ 已完成	2026-03-18	2026-03-18
前端文档补充	✅ 已完成	2026-03-18	2026-03-18
系统集成测试	🔄 进行中	2026-03-19	-

📋 任务状态跟踪

已完成任务

✅ 完善Business_ClosedLoops.md中的多商户相关闭环
✅ 新建开发进度互通文档
✅ 更新SERVICE_MAP.md文档，定义服务调用链
✅ 更新DOMAIN_MODEL.md文档，定义核心实体及其关系
✅ 更新PERMISSION_RULES.md文档，定义权限规则
✅ 更新BILLING_RULES.md文档，定义收费规则
✅ 更新STATE_MACHINE.md文档，定义状态机
✅ 更新TEST_SPEC.md文档，定义测试规范
✅ 更新AI_RULES.md文档，定义AI执行规则
✅ 实现服务层代码（MerchantService、StoreService、InventorySyncService、AnalyticsService）
✅ 修复AIService.ts中的optimizeProductForPlatform方法
✅ 修复ProductService.ts中的createProduct方法和其他方法错误
✅ 修复InventoryAgingService.ts中的AGING_THRESHOLD_DAYS引用问题
✅ 修复InventoryService.ts中的predictSKUDemand方法
✅ 修复ChatBotController.ts的实现，从tsoa风格改为Express风格
✅ 修复CommandCenterController.ts中的类型问题
✅ 修复AdAutoService.ts中stock可能为undefined的问题
✅ 启动前端服务（运行在 http://localhost:8001）
✅ 启动扩展开发服务（运行在 http://localhost:5173）
✅ 启动后端服务器（运行在 http://localhost:3001）
✅ 前端优化：组件化设计和状态管理
✅ 前端优化：性能优化（虚拟列表、懒加载等）
✅ 前端优化：响应式布局，支持多终端访问
✅ 前端优化：与后端集成，实现数据实时同步
✅ 前端优化：性能测试和优化
✅ 前端优化：安全测试，确保系统安全性
✅ 前端优化：建立前端组件库，提高开发效率
✅ 创建商品管理页面（Product）
✅ 创建订单管理页面（Orders）
✅ 创建商户管理页面（Merchant）
✅ 创建物流管理页面（Logistics）
✅ 创建售后服务页面（AfterSales）
✅ 创建合规管理页面（Compliance）
✅ 创建黑名单管理页面（Blacklist）
✅ 创建B2B贸易页面（B2B）
✅ 创建广告管理页面（Ad）
✅ 创建前端业务说明书目录结构
✅ 创建Product页面前端业务说明书
✅ 创建Orders页面前端业务说明书
✅ 创建Ad页面前端业务说明书
✅ 创建Finance相关页面（Finance/index.tsx, Finance/Transactions.tsx, Finance/Reconciliation.tsx）
✅ 创建Inventory相关页面（Inventory/index.tsx, Inventory/Warehouses.tsx, Inventory/InventoryForecast.tsx）
✅ 创建Marketing相关页面（Marketing/index.tsx, Marketing/Ads.tsx, Marketing/Competitors.tsx）
✅ 创建Suppliers相关页面（Suppliers/index.tsx, Suppliers/SupplierDetail.tsx）
✅ 创建Reports相关页面（Reports/index.tsx, Reports/ProfitReport.tsx, Reports/PerformanceReport.tsx）
✅ 创建Settings相关页面（Settings/index.tsx, Settings/ProfileSettings.tsx, Settings/TenantSettings.tsx, Settings/UserManagement.tsx）
✅ 补充Business_ClosedLoops.md附录A：前端交互设计规范（状态机、路由、按钮操作、用户流程）
✅ 补充Business_ClosedLoops.md附录B：前端页面映射（商品、订单、执行、数据、合规、设置页面）
✅ 补充Business_ClosedLoops.md附录C：前端组件规范（组件分类、状态管理、API交互、路由权限）
✅ 补充Task_Overview.md附录A：前端交互任务补充（商品、订单、执行、数据、合规、设置交互任务）
✅ 补充Task_Overview.md附录B：前端开发规范（技术栈、项目结构、组件、状态、API、路由权限）
✅ 更新项目规则文档（project-specific-rules.md），加入逻辑集中化原则
✅ 更新SERVICE_MAP.md，强化服务层职责和调用规范
✅ 更新Service_Design.md，明确服务层设计规范和边界

进行中任务

🔄 系统集成测试
🔄 前端交互任务开发

待开始任务

⏳ 性能测试和优化
⏳ 安全测试

🏗️ 架构演进

服务编排层架构

当前架构问题

现状：前后端模块完成，但缺少"服务编排层"（Service Layer）
问题本质：模块是"零件"，但没有"发动机"把它们串成闭环
影响：系统是"静态的"，不是"运行的"

架构升级路径

升级前（接口驱动）：

前端 → 直接调接口 → 改数据库

升级后（服务驱动）：

前端 → Controller → Service（核心）→ 多模块联动

服务层核心结构

/controller   （接口层）
/service      （业务编排层）🔥 核心层
/repository   （数据层）

逻辑集中化原则

所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。

逻辑分散的表现（禁止行为）

❌ Controller 中写业务逻辑：Controller 只负责请求/响应和权限校验
❌ 前端直接写业务规则：复杂计算、权限判断、状态流转禁止在 React 组件中实现
❌ 数据库操作分散：不同模块禁止直接调用数据库，必须通过 Service 层
❌ 脚本或工具处理逻辑：AI 任务或异步脚本必须通过 Service 层统一调用

逻辑分散的后果

维护成本高：AI 或开发者需要理解多个模块才能做一件改动
修改容易出错：改动一处可能引起其他模块逻辑不一致
难以快速迭代：新功能闭环难以接入，因为逻辑散落在各处
收费闭环风险：分散逻辑导致支付、权限、账单、状态不一致，直接影响收益
AI 维护困难：AI 无法一次性理解完整闭环，状态不一致，修改风险高

服务层职责

一个服务 = 一个闭环

示例服务：

FeatureService（功能开通服务）：点击开通 → 支付 → 开通 → 权限 → 账单
OrderService（订单服务）：拆单（多商户）→ 锁库存 → 创建订单 → 记录商户归属
SettlementService（结算服务）：汇总订单 → 扣除平台费用 → 扣除功能费用 → 生成账单

🎨 前端优化策略

架构优势与匹配

React：组件化强，状态管理灵活，社区资源丰富，适合中大型应用
Umi：
- 基于约定式路由 + 插件化，快速搭建项目结构
- 支持 Model（状态管理），可以结合 @umijs/plugin-model 做全局和模块化状态
- 内置代码分割、动态路由，支持多商户、多模块懒加载

✅ 对业务匹配点：

多商户模块可拆分为独立路由 + 独立 Model
数据表格、图表等复杂交互组件可封装成 React 组件，复用性高
AI agent 任务状态板可以用独立 Model 管理状态，并订阅变化实现实时更新

前端落地策略

(1) 组件化设计

UI 组件：按钮、表格、表单、下拉、弹窗
功能组件：
- 店铺管理面板
- 产品/价格/库存表格
- 图表分析模块（折线图、柱状图、K线/套利趋势）
- AI任务状态板
业务容器组件：组合功能组件，负责数据获取和状态管理

原则：尽量小组件 + 高复用 + 单一职责

(2) 状态管理

全局状态（Model）：商户列表、店铺配置、AI任务状态
模块局部状态：表格筛选条件、分页、折叠面板状态
异步数据处理：用 Umi 内置 effects 或 Redux-Saga/Thunk 风格，保证接口调用不阻塞 UI

(3) 数据展示与性能优化

表格渲染优化：
- 虚拟列表/虚拟滚动（尤其是大数据量的产品列表）
- 分页懒加载 + 数据缓存
图表优化：
- 图表库：AntV G2/G6 或 ECharts，支持数据更新动画
- 数据量大时，分批渲染 + 数据精简
接口节流与防抖：搜索联想、筛选条件、频繁刷新数据

(4) 交互体验优化

动画与过渡：按钮点击、加载状态、模块展开折叠
操作反馈：loading、success/error 提示
响应式布局：多终端访问（管理后台、桌面端、平板）

(5) 可扩展性与多商户支持

路由模块化：每个商户或功能闭环一个路由 + Model
动态加载组件：Umi 支持按需加载，保证首页/面板加载速度
AI任务板：订阅全局状态，实现任务动态显示

前端优化重点

架构层面优化：
- 路由与模块拆分更细
- Model 分层管理
- 接口统一层
性能优化：
- 虚拟列表 & 按需渲染
- 数据缓存 & debounce
- 懒加载 & 分包
- 图表优化
开发体验 & 可维护性：
- 组件库标准化
- 类型与校验
- 统一交互规范
- 代码结构规范化
用户体验优化：
- 交互反馈及时
- 响应式 & 自适应
- 任务状态可视化
可扩展 & 高可用优化：
- 模块化扩展
- 容错与降级
- 开发 & 部署优化

🔄 二层闭环体系

一级闭环（大结构，不频繁改）

订单闭环
结算闭环
广告闭环
多商户闭环

二级闭环（新功能，轻量闭环）

高级分析收费闭环
API调用收费闭环
自动补货闭环
跨境物流加速闭环

💡 核心开发原则

业务闭环优先原则

业务闭环决定"做不做 & 怎么赚"，任务表只是"怎么实现"。

判断规则（必须先做业务闭环）

满足任意 2 个 → 必须先做业务闭环：

是否涉及钱（收费 / 成本 / ROI）
是否跨模块（前端 + 后端 + 财务）
是否影响商户行为
是否可以成为一个"卖点功能"

开发流程标准

先补业务闭环（轻量版）：锁定"钱 + 权限 + 数据"三件事
再拆任务：按照现有任务表结构
AI 开始干活：确保有完整闭环指导

关键原则

你不是在"加功能"，你是在"加一个能赚钱的闭环"。

💬 沟通记录

关键洞察

服务闭环与收费的关系：服务闭环跟收费没有必然关系，收费只是把问题放大了。只要存在"状态流转 + 多模块协同"，就必须有服务闭环。
不收费场景也需要服务闭环：订单闭环、库存闭环、多商户分单等都需要服务层保证数据一致性。
收费场景更容易暴露问题：因为多了一条链（功能 → 支付 → 权限 → 使用 → 计费 → 结算），任何一个点错了都会直接损失钱。
前端优化的重要性：前端是用户直接接触的界面，其流畅性和功能完整性直接影响用户体验和系统的商业价值。
逻辑集中化的必要性：逻辑分散导致AI难以维护，状态不一致，修改风险高。集中化逻辑到服务层 + 统一状态管理，AI才能高效维护和迭代。
服务层职责边界：Controller只负责请求/响应和权限校验，Service层负责业务逻辑编排和状态流转，Repository层负责数据库操作。明确职责边界是逻辑集中化的基础。

AI开发建议

优先进行系统集成测试，确保各服务之间的正确交互
实现完整的错误处理和日志记录机制
优化服务层性能，特别是数据库查询和异步操作
加强安全措施，确保支付流程和数据传输的安全性
严格执行"业务闭环优先"原则，避免碎片化开发
按照前端优化策略，逐步实现组件化、状态管理和性能优化
确保前端与后端的良好集成，实现数据的实时同步和交互的流畅性
严格执行逻辑集中化原则：所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中
明确服务层职责边界：Controller 只负责请求/响应和权限校验，Service 层负责业务逻辑编排和状态流转，Repository 层负责数据库操作
统一状态管理：前端使用全局 Model 或状态管理库，后端统一使用 STATE_MACHINE 定义的状态机，所有状态更新必须通过 Service 层

📝 下一步计划

短期计划（2026-03-19 至 2026-03-21）

完成系统集成测试，验证服务层功能
优化数据库查询和缓存策略
实现完整的错误处理和日志记录
进行性能测试和优化
实现安全测试，确保系统安全性
完成前端交互任务开发，包括筛选、排序、新增、编辑、定价、上架、同步等
代码审查：检查所有Controller、Service、Repository代码，确保符合逻辑集中化原则
重构优化：将分散的业务逻辑迁移到Service层，确保职责边界清晰
测试验证：验证逻辑集中化后的代码，确保功能正确性和数据一致性

中期计划（2026-03-22 至 2026-03-28）

完善前端与后端的集成，实现数据实时同步
补充二级闭环（功能收费闭环、权限控制闭环、商户账单闭环）
部署系统到测试环境
进行系统性能测试和安全测试
完善前端组件库，实现组件复用
实现前端状态管理，优化数据流

长期计划（2026-03-29 至 2026-04-11）

部署系统到生产环境
监控系统运行状态
持续优化和迭代系统功能
实现自动化 / AI驱动功能
完善前端组件库，提高开发效率
实现完整的前端监控和分析
实现前端性能优化，包括虚拟列表、懒加载、数据缓存等
实现前端交互优化，包括动画、过渡、操作反馈等

🚨 风险与问题

当前风险

系统集成测试可能发现服务间交互问题
数据库性能可能成为系统瓶颈，特别是在高并发场景下
安全漏洞可能存在于支付流程和数据传输中

需要关注的问题

确保系统在高并发场景下的稳定性
实现完善的监控和告警机制
加强数据备份和恢复策略
确保符合相关法规和合规要求
避免逻辑分散，确保业务逻辑集中在服务层

架构风险

逻辑分散风险：如果在 Controller 中写业务逻辑，会导致逻辑分散，AI 无法维护。逻辑分散导致AI难以追踪业务流程、状态流转不统一、重复逻辑、难以保证一致性、代码依赖复杂。
收费必炸风险：没有完整的服务闭环，后期收费功能必定出现问题。分散逻辑导致支付、权限、账单、状态不一致，直接影响收益。
数据一致性风险：多商户场景下，没有服务层会导致商户归属混乱、结算错误。
AI维护困难风险：逻辑分散让 AI 无法一次性理解完整闭环，状态不一致，修改风险高。集中化逻辑到服务层 + 统一状态管理，AI 才能高效维护和迭代。

📞 联系方式

项目负责人：用户
AI开发助手：GPT
沟通渠道：本文档 + 代码注释

本文档将定期更新，确保开发进度的透明和同步。

19 KiB Raw Blame History Unescape Escape

📊 开发进度互通文档

🎯 文档目的

🔍 开发概览

项目定位

当前阶段

关键里程碑

📋 任务状态跟踪

已完成任务

进行中任务

待开始任务

🏗️ 架构演进

服务编排层架构

当前架构问题

架构升级路径

服务层核心结构

逻辑集中化原则

逻辑分散的表现（禁止行为）

逻辑分散的后果

服务层职责

🎨 前端优化策略

架构优势与匹配

前端落地策略

(1) 组件化设计

(2) 状态管理

(3) 数据展示与性能优化

(4) 交互体验优化

(5) 可扩展性与多商户支持

前端优化重点

🔄 二层闭环体系

一级闭环（大结构，不频繁改）

二级闭环（新功能，轻量闭环）

💡 核心开发原则

业务闭环优先原则

判断规则（必须先做业务闭环）

开发流程标准

关键原则

💬 沟通记录

最近沟通

关键洞察

AI开发建议

📝 下一步计划

短期计划（2026-03-19 至 2026-03-21）

中期计划（2026-03-22 至 2026-03-28）

长期计划（2026-03-29 至 2026-04-11）

🚨 风险与问题

当前风险

需要关注的问题

架构风险

📞 联系方式

19 KiB

Raw Blame History