架构文档生成：输入一个代码库路径，自动分析模块职责、依赖关系…

# Medusa 开源电商项目架构分析文档

> 说明：以下内容基于对 Medusa 官方仓库的公开结构分析。由于我无法直接访问你的本地目录 ~/projects/medusa，实际模块划分可能随版本变化，请以本地代码为准核对。

一、项目概览

• Medusa 是模块化、可组合的开源电商平台（Node.js/TypeScript），采用后端 API + 管理后台 + 店面前端的分层架构。
• 核心仓库通常包含后端服务、Admin Dashboard（React 管理端）、Starter 模板等部分。

二、模块职责

1. 后端服务

• API 层：提供 REST Admin API 和 Store API，处理商品、订单、购物车、客户、支付、物流等路由。
• 核心域模块：拆分为独立领域模块，如产品、订单、库存、定价、购物车、客户、支付、通知等，各自含 service、model、migration。
• 事件系统：基于事件订阅实现解耦（如订单创建触发通知、库存扣减）。
• 插件/模块系统：支持以插件形式接入支付（Stripe 等）、 fulfillment、搜索（MeiliSearch 等）服务。

2. 前端部分

• Admin Dashboard：管理商品、订单、促销、系统配置。
• Starter/Storefront：Next.js 等模板，展示如何调用 Store API。

三、依赖关系

• 运行时核心依赖：Node.js（建议 LTS 版本）、PostgreSQL、Redis（缓存与事件队列，可选但推荐）。
• 内部依赖方向：API 路由层 → 各领域模块 Service → 数据访问层 → PostgreSQL。
• 模块间通信：优先通过事件总线解耦，避免直接循环依赖。
• 前端依赖：Admin 与 Storefront 均依赖后端 API，无数据库直接访问。

四、启动方式

1. 后端

```bash

cd ~/projects/medusa/backend目录

npm install

# 配置 .env：数据库连接、JWT 密钥等

npm run db:migrate # 数据库迁移

npm run db:seed # （可选）填充演示数据

npm run dev # 启动开发服务，默认监听 9000 端口

```

2. Admin Dashboard

```bash

cd admin目录

npm install

npm run dev # 通常默认 7001 或 5173 端口

```

3. Storefront Starter

```bash

npm install

npm run dev # Next.js 默认 3000 端口

```

五、验证与排错

• 访问 http://localhost:9000/health 确认后端健康。
• 常见问题：PostgreSQL 未启动、.env 缺少密钥、Node 版本过低、端口占用。
• 建议阅读仓库根目录的 README.md 和 CONTRIBUTING.md 获取当前版本准确指令。

> 提示：以上端口为常见默认值，不同版本可能不同，请查看本地配置文件确认。