跳到主要内容

AOVIS 后台未来研发计划指导文档（Medusa 设计思路参考版）

文档版本：v1.0
更新日期：2026-04-04
适用对象：AOVIS / NEXA 团队研发负责人、产品负责人、后续 AI 工具研发执行者

1. 文档定位​

这份文档不是要把 Medusa 接入 AOVIS，也不是要把当前后台迁移到新的 commerce platform。

它的用途是：

  • 作为 AOVIS 现有后台未来 3 个迭代 的指导性文档
  • 为后续 AI 工具研发提供统一参考边界
  • 明确哪些设计思路可以借鉴 Medusa，哪些不能直接照搬
  • 保证未来研发继续建立在 aovis.app 当前真实已落地的后台能力之上，而不是脱离现状重新设计

2. 核心原则​

后续任何基于本文件的研发，都应遵守以下原则：

  • 不引入 Medusa 作为当前生产主 backend
  • 不重写现有 checkout / Stripe / webhook / order finalization 主链路
  • 不扩展到 ERP / WMS / 多仓 / 实时承运商询价 / 完整税务平台
  • 不破坏当前已上线的 admin tax / shipping / shipment / audit 基础能力
  • 所有迭代都以“小范围、可上线、可验证”为原则

3. 为什么参考 Medusa​

Medusa 对 AOVIS 当前阶段最有价值的，不是它整套 commerce platform，而是它对后台模块边界的划分方式。

当前最值得借鉴的方向：

  • fulfillment / shipment
  • shipping options / shipping configuration
  • region / market boundary
  • admin order operations 的分层方式
  • inventory / returns 的边界意识

当前不适合借鉴为实际开发主题的方向：

  • tax engine 重建
  • promotion / pricing engine
  • 多仓库存系统
  • 完整 returns / exchanges 平台
  • 平台级 commerce backend 替换

4. 未来 3 个迭代的研发计划​

Iteration 1：把订单运营后台做扎实​

目标​

把当前已经存在的 orders / audit / shipment / payment note 补成真正顺手的运营后台。

建议研发清单​

  1. 订单详情页按领域重新整理操作区
  • 分成：
    • Financial / tax
    • Shipping / address
    • Fulfillment / shipment
    • Payment notes
    • Audit timeline
  1. 强化 audit timeline
  • 显示更明确的变更摘要
  • 对 billingAddress、shippingAddress、shipment 事件做更可读的 diff
  • 不只停留在原始 JSON 展示
  1. 补 shipment 操作的最小完整闭环
  • 新增/更新 tracking
  • 标记 shipped
  • 标记 delivered
  • 更清楚地显示最新 shipment 状态和历史事件
  1. 强化 payments detail 的轻量运营能力
  • 更清楚地区分：
    • reconciliation note
    • support note
  1. 强化 orders list 的筛选/结果反馈
  • 保持已有筛选能力
  • 继续优化筛选后的结果反馈与空状态说明

本迭代不要做​

  • 直接改税额/运费的已支付财务值
  • returns / refunds workflow
  • inventory
  • checkout 重写

Iteration 2：把 shipping 配置做成清晰的结构层​

目标​

借鉴 Medusa 的 shipping options / regions / fulfillment context 思路，把当前轻量运费配置继续结构化，但不引入复杂 rule engine。

建议研发清单​

  1. 强化 ShippingRateConfig 的后台管理体验
  • 明确：
    • code
    • label
    • amount
    • countries
    • active
    • display order
  1. 正式启用 ShippingZoneConfig
  • 至少支持：
    • country
    • state / province matcher
    • standard estimate
    • expedited estimate
  1. checkout 继续读取后台 shipping config
  • 保持 fallback
  • 但让：
    • shipping rate
    • shipping zone
    • delivery estimate 的来源更清楚可追踪
  1. order detail 展示更明确的 shipping 来源
  • 显示订单命中的：
    • rate
    • zone
    • estimate 来源
  1. shipping settings 页增加配置验证
  • 提示明显错误或不完整配置

本迭代不要做​

  • 实时 carrier quote
  • fulfillment provider 接入
  • 多仓发货逻辑
  • label purchasing

Iteration 3：把后台运营边界从“订单页堆表单”提升到“模块化运营”​

目标​

借鉴 Medusa 的模块边界，把 AOVIS 后台从“功能都塞在订单详情页”提升到更清晰的运营结构，但仍然不引入大系统。

建议研发清单​

  1. 形成独立的 fulfillment 视图
  • 可以先不是完整新模块
  • 但至少新增：
    • shipments 列表页
    • 或 orders 中的 fulfillment-focused 视图
  1. 形成更清晰的 tax / shipping operations 边界
  • tax note
  • shipping note
  • payment note
  • address correction
  • fulfillment note
  1. 订单事件模型进一步规范
  • 统一 FulfillmentEvent / OrderAuditLog 的 event naming
  • 提高统计和导出的稳定性
  1. 为 future region 模型预留接口
  • 当前不做完整 region system
  • 但逐步统一这些概念：
    • allowed countries
    • tax applies to product type
    • shipping availability by market
  1. 为未来 returns / post-purchase ops 做边界预埋
  • 当前不做 returns 系统
  • 但让 order operations 的分类先理顺

本迭代不要做​

  • 完整 OMS
  • returns / exchanges engine
  • inventory reservations
  • warehouse / location system
  • promotion / pricing engine

5. 优先级建议​

P0​

  • Iteration 1 全部

原因：

  • 对当前后台使用体验提升最大
  • 风险最低
  • 不影响支付主链路

P1​

  • Iteration 2 的 ShippingZoneConfig + shipping source visibility

原因：

  • 能让 shipping 从“半后台化”走向“结构化后台配置”

P2​

  • Iteration 3 的 fulfillment-focused 视图和事件规范化

原因：

  • 这是后台从“能用”走向“可扩展”的关键一步

6. 给后续 AI 工具研发的使用说明​

后续使用 Claude、ChatGPT、Codex 或其他 AI 工具做后台研发时，建议把本文件作为：

  • 背景文档
  • 范围约束文档
  • 迭代优先级参考文档

并同时配合以下文档一起使用：

  • docs/current-store-development-status.md
  • PROGRESS.md
  • 当前仓库中的实际 admin 页面、API、schema

AI 工具在基于本文件给出方案时，必须遵守：

  • 以当前已落地后台现状为前提
  • 不把 scope 扩成平台重构
  • 不把 Medusa 当作当前生产后端替换方案

7. 一句话总结​

这份文档的核心不是“把 Medusa 搬进 AOVIS”，而是：

借鉴 Medusa 的模块拆分思路，指导 AOVIS 后台在未来 3 个迭代里，以最小可上线改动逐步走向更清晰、更可运营的后台结构。