Katana 电商平台 - 总体架构文档

项目概述

Katana 是一个支持多平台商户（Shopify、AliExpress、Katana）的社交电商平台，支持网红/联盟营销功能。

技术栈概览

系统架构

┌─────────────────────────────────────────────────────────────────┐
│                         客户端层                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│  │  Web App    │  │  Admin App  │  │  Consumer Web       │   │
│  │  (Next.js)  │  │  (Next.js)  │  │  (Next.js)          │   │
│  │   Port:3000 │  │  Port:3002  │  │                      │   │
│  └─────────────┘  └─────────────┘  └─────────────────────┘   │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/HTTPS
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                       API 网关 / 后端服务                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Katana Server (NestJS)                     │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐      │   │
│  │  │ Auth     │  │ Payment  │  │  Business Logic  │      │   │
│  │  │ (JWT)    │  │(Stripe   │  │  - Products      │      │   │
│  │  │          │  │ PayPal)  │  │  - Orders        │      │   │
│  │  └──────────┘  └──────────┘  │  - Sales         │      │   │
│  │                                │  - Posts         │      │   │
│  │  ┌──────────┐  ┌──────────┐   │  - Commissions  │      │   │
│  │  │ Queue    │  │ External │   └──────────────────┘      │   │
│  │  │ (Bull)   │  │ Integr.  │                            │   │
│  │  └──────────┘  └──────────┘                            │   │
│  └─────────────────────────────────────────────────────────┘   │
└───────────┬───────────────┬───────────────────┬─────────────────┘
            │               │                   │
            ▼               ▼                   ▼
┌───────────────┐  ┌───────────────┐  ┌──────────────────┐
│  PostgreSQL   │  │    Redis      │  │   第三方服务      │
│  (Prisma ORM) │  │  (缓存/队列)   │  │  - Shopify       │
│               │  │               │  │  - AliExpress    │
└───────────────┘  └───────────────┘  │  - Stripe        │
                                      │  - PayPal        │
                                      │  - OpenAI        │
                                      │  - AWS SES       │
                                      └──────────────────┘

项目结构

Pears/
├── katana-server/              # 后端服务 (NestJS)
│   ├── src/
│   │   ├── auth/               # 认证模块
│   │   ├── payment/            # 支付处理
│   │   ├── sales/              # 销售管理
│   │   ├── products/           # 产品管理
│   │   ├── posts/              # 帖子管理
│   │   ├── commission/         # 佣金系统
│   │   ├── shopify/            # Shopify 集成
│   │   ├── ai/                 # AI 集成
│   │   └── ...
│   ├── vitest/                 # 测试
│   └── package.json
│
├── katana-web/                 # 前端应用 (Monorepo)
│   ├── apps/
│   │   ├── web/                # 主 Web 应用
│   │   ├── admin/              # 管理后台
│   │   ├── consumer-web/       # 消费者应用
│   │   └── katana-common/      # 公共模块
│   ├── packages/
│   │   ├── ui/                 # UI 组件库
│   │   ├── hooks/              # 自定义 Hooks
│   │   ├── icons/              # 图标库
│   │   ├── mui/                # Material-UI
│   │   ├── utils/              # 工具函数
│   │   └── ...
│   └── package.json
│
└── ai-docs/                    # 项目文档
    ├── katana-server/
    │   └── README.md
    ├── katana-web/
    │   └── README.md
    └── README.md               # 本文件

核心业务领域

1. 用户管理

• 多角色用户系统：Consumer、Promoter、Merchant、Admin
• JWT 认证与授权
• 用户活动追踪
• 商店管理员（多管理员账户系统）

2. 产品管理

• 多平台商品目录（Shopify、AliExpress、Katana）
• 产品变体和库存管理
• 产品评价系统
• 票务产品（多日通行证）

3. 订单与销售

• 订单处理和履约
• 退款管理
• 票务验证
• 多日通行证处理

4. 支付系统

• Stripe 支付集成
• PayPal 支付集成
• 交易费用计算
• 税务处理

5. 佣金与分润

• 推广者佣金追踪
• 收益分享
• 结算管理
• 分润处理

6. 营销活动

• 营销活动管理
• 推广管理
• 优惠券系统
• 事件和票务管理

7. 社交电商

• 帖子内容管理
• 转售链关系
• 社交分享
• 网红/推广者关联

技术亮点

后端架构

NestJS 模块化设计

• 每个业务域独立模块
• Controller → Service → Repository 模式
• 依赖注入
• 全局异常过滤和响应拦截

认证与授权

• JWT 全局守卫
• 基于角色的访问控制
• 请求上下文中间件

队列系统

• Bull + Redis 异步任务处理
• 事件驱动架构
• 队列监控（Bull Board）

测试

• Vitest（新，40-60x 更快）
• Jest（旧，逐步迁移）
• Docker 容器化测试环境

前端架构

Monorepo 管理

• Turborepo 构建系统
• pnpm workspace
• 共享包和组件

状态管理

• Jotai 原子化状态
• React Context
• ahooks 工具库

UI 组件

• Material-UI 自定义
• Shopify Polaris
• Emotion CSS-in-JS
• 自定义组件库

表单处理

• React Hook Form
• Yup 验证

开发环境

环境要求

环境配置

后端 (katana-server):

• .env.local - 本地开发
• .env.dev - 开发环境
• .env.staging - 预发布环境
• .env.release - 发布环境
• .env.production - 生产环境

前端 (katana-web):

• apps/web/.env.local - Web 本地开发
• apps/admin/.env.local - Admin 本地开发
• 对应 dev/staging/release/main 环境配置

开发命令速查

后端 (katana-server)

cd katana-server

# 开发
npm run start:dev          # 开发模式
npm run start:release      # 发布模式
npm run start:production   # 生产模式

# 数据库（需要用户确认）
npm run prisma:generate    # 生成 Prisma 客户端（安全）
npm run db:migrate         # 创建迁移

# 测试
npm run vitest             # 运行测试（新）
npm run test               # 运行测试（旧）

# 代码质量
npm run lint               # ESLint 检查
npm run format             # Prettier 格式化

# 构建
npm run build              # 构建应用

前端 (katana-web)

cd katana-web

# 开发
pnpm run dev               # 启动所有应用
pnpm run dev:web           # 仅启动 web 应用
pnpm run dev:admin         # 仅启动 admin 应用

# 构建
pnpm run build             # 构建所有应用
pnpm run build:dev         # 构建开发环境
pnpm run build:prod        # 构建生产环境

# 代码质量
pnpm run lint              # ESLint 检查
pnpm run format            # Prettier 格式化
pnpm run knip              # 检测未使用代码

# 测试
pnpm run test:web          # 运行 web 应用测试

部署

后端部署

• 平台: AWS ElasticBeanstalk
• 容器化: Docker 支持
• 监控: Prometheus + Datadog

前端部署

• 平台: Vercel
• 容器化: Docker 支持
• 监控: Vercel Speed Insights + PostHog

Git 工作流

分支策略

• 主分支: release - 后端 PR 合并目标
• 预发布: staging - 发布前测试

提交规范

• 使用 git commit -m "message" 格式
• PR 合并使用 gh pr merge <number> --merge
• 提交前通过 lint-staged 检查

参考文档

项目文档

• Katana Server 文档
• Katana Web 文档

后端模块文档

• Sales 模块
• Products 模块
• Posts 模块
• Product Event 模块
• Shop Admin 模块

前端文档

• 架构标准
• 开发标准
• 版本控制

许可证

UNLICENSED (私有项目)