Katana Server 项目文档

项目概述

Katana Server 是一个基于 NestJS 的电商平台后端服务，支持多平台商户（Shopify、AliExpress、Katana）、社交电商和网红/联盟营销。

版本: 0.0.8 主要语言: TypeScript 框架: NestJS 10.x

技术栈

核心框架

  • NestJS 10.x - Node.js 企业级后端框架
  • TypeScript 5.x - 主要开发语言
  • Prisma 5.x - 数据库 ORM
  • PostgreSQL - 主数据库
  • MongoDB - 文档数据库（部分模块）
  • Redis - 缓存和消息队列

认证与安全

  • JWT - JSON Web Token 认证 (@nestjs/jwt)
  • Passport - 认证中间件 (@nestjs/passport)
  • Auth0 - 第三方认证集成
  • JWKS RSA - RSA 密钥验证

支付集成

  • Stripe 16.x - 支付处理
  • PayPal - PayPal 支付集成

电商平台集成

  • Shopify API 7.x - Shopify 店铺集成
  • AliExpress - 全球速卖通集成

AI 集成

  • OpenAI SDK (@ai-sdk/openai)
  • Anthropic SDK (@ai-sdk/anthropic)
  • Google AI SDK (@ai-sdk/google)
  • Vercel AI SDK 4.x - AI 统一接口

消息队列与任务

  • Bull 4.x - Redis 队列 (@nestjs/bull)
  • Kafka (kafkajs) - 事件流处理

邮件与通信

  • AWS SES (@aws-sdk/client-sesv2) - 邮件服务
  • Nodemailer - SMTP 邮件
  • Twilio - 短信服务
  • MJML - 邮件模板

搜索与分析

  • Algolia 4.x - 搜索引擎
  • Prometheus (@willsoto/nestjs-prometheus) - 监控指标
  • Datadog (dd-trace) - APM 追踪

图片与媒体

  • Sharp 0.34.x - 图片处理
  • Cloudinary - 图片存储和 CDN

数据处理

  • ExcelJS - Excel 导入导出
  • XLSX - 表格处理
  • Archiver - 压缩打包
  • Cheerio - HTML 解析

工具库

  • Lodash - 工具函数
  • Day.js - 日期处理
  • Currency.js - 货币计算
  • Decimal.js - 高精度数值计算
  • Zod - Schema 验证

测试框架

  • Vitest 4.x - 新测试框架（推荐）
  • Jest - 旧测试框架（逐步迁移）
  • @vitest/coverage-v8 - 代码覆盖率

目录结构

katana-server/
├── src/
│   ├── ad-events/              # 广告事件处理
│   ├── ai/                     # AI 集成模块
│   ├── algolia/                # 搜索引擎集成
│   ├── auth/                   # 认证模块
│   ├── aws/                    # AWS 服务集成
│   ├── balance/                # 余额管理
│   ├── bull/                   # 队列管理
│   ├── buy-count/              # 购买计数
│   ├── campaigns/              # 营销活动
│   ├── cart/                   # 购物车
│   ├── catalog/                # 商品目录
│   ├── channel/                # 渠道管理
│   ├── cloudinary/             # 图片存储
│   ├── commission/             # 佣金管理
│   ├── config/                 # 配置管理
│   ├── contract/               # 合约管理
│   ├── credit/                 # 信用/积分系统
│   ├── cronjob/                # 定时任务
│   ├── database/               # 数据库配置
│   ├── default/                # 默认路由
│   ├── earning-share/          # 收益分享
│   ├── earnings/               # 收益管理
│   ├── email/                  # 邮件服务
│   ├── events/                 # 事件管理
│   ├── feature-setting/        # 功能设置
│   ├── feture-flag/            # 功能开关
│   ├── filter/                 # 异常过滤器
│   ├── fingerprint/            # 指纹识别
│   ├── inbox/                  # 消息收件箱
│   ├── interceptor/            # 拦截器
│   ├── jwt/                    # JWT 处理
│   ├── logging/                # 日志记录
│   ├── map/                    # 地图服务
│   ├── marketplace/            # 市场平台
│   ├── merchant/               # 商户管理
│   ├── merchant-promoter-association/  # 商户推广者关联
│   ├── merchant-tools/         # 商户工具
│   ├── merchant-user/          # 商户用户
│   ├── microservices/          # 微服务
│   ├── middleware/             # 中间件
│   ├── notification-settings/  # 通知设置
│   ├── official-collections/   # 官方集合
│   ├── operations/             # 运营管理
│   ├── payout/                 # 分润管理
│   ├── payment/                # 支付处理
│   ├── paypal/                 # PayPal 集成
│   ├── periodic-notification/  # 定期通知
│   ├── post-sync/              # 帖子同步
│   ├── posts/                  # 帖子管理
│   ├── product-event/          # 产品活动
│   ├── product-event-core/     # 产品活动核心
│   ├── product-reviews/        # 产品评价
│   ├── product-v2/             # 产品模块 v2
│   ├── products/               # 产品管理
│   ├── prometheus/             # 监控指标
│   ├── promoter-association/   # 推广者关联
│   ├── promoter-earning/       # 推广者收益
│   ├── promoter-subscription/  # 推广者订阅
│   ├── promotion/              # 推广管理
│   ├── redis/                  # Redis 客户端
│   ├── sales/                  # 销售管理
│   ├── script/                 # 脚本
│   ├── settlement/             # 结算管理
│   ├── shop-admin/             # 商店管理员
│   ├── shopify/                # Shopify 集成
│   ├── shopify-metafields/    # Shopify 元字段
│   ├── shopify-variant-wiz/    # Shopify 变体向导
│   ├── short-link/             # 短链接
│   ├── sms/                    # 短信服务
│   ├── stripe/                 # Stripe 支付
│   ├── subdomain/              # 子域名
│   ├── subscription-plan/      # 订阅计划
│   ├── tax/                    # 税务处理
│   ├── transaction-fee/        # 交易费用
│   ├── user/                   # 用户管理
│   ├── user-activity/          # 用户活动
│   ├── user-meta/              # 用户元数据
│   ├── util/                   # 工具函数
│   ├── vercel/                 # Vercel 集成
│   ├── web-scraper/            # 网页爬虫
│   ├── browserlessio/          # 无头浏览器
│   ├── store-front/            # 店铺前端
│   ├── app.module.ts           # 主模块
│   └── main.ts                 # 应用入口
├── vitest/                     # Vitest 测试（新）
├── test/                       # Jest 测试（旧）
├── .monitor/                   # 监控配置
├── package.json
├── tsconfig.json
└── CLAUDE.md                   # Claude Code 开发指南

核心业务模块

1. 用户管理 (user/)

  • 多角色用户系统：Consumer、Promoter、Merchant、Admin
  • JWT 认证与授权
  • 用户活动追踪

2. 产品管理 (products/, product-v2/)

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

3. 订单与销售 (sales/)

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

4. 支付系统 (payment/, stripe/, paypal/)

  • Stripe 和 PayPal 支付集成
  • 交易费用计算
  • 税务处理 (tax/)

5. 佣金与分润 (commission/, payout/, settlement/)

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

6. 营销活动 (campaigns/, promotion/, events/)

  • 营销活动管理
  • 推广管理
  • 事件和票务管理

7. 内容管理 (posts/)

  • 社交电商内容系统
  • 帖子同步
  • 转售链关系

8. 商户管理 (merchant/, shop-admin/)

  • 多平台商户管理
  • 商店管理员（多管理员账户）
  • 权限控制（SUPER_ADMIN、ADMIN、LIMITED_ADMIN）

9. 通知系统 (email/, periodic-notification/, notification-settings/)

  • MJML 邮件模板
  • AWS SES 邮件发送
  • 定期通知

10. 集成服务

  • Shopify (shopify/) - 完整集成
  • AI (ai/) - OpenAI、Anthropic、Google AI
  • 搜索 (algolia/) - Algolia 搜索
  • 图片 (cloudinary/) - 图片存储和处理

数据库架构

ORM

  • Prisma - 类型安全的数据库访问
  • Schema 文件: src/database/schema.prisma
  • 迁移目录: src/database/migrations/

关键模型

  • User - 用户
  • Order - 订单
  • MerchantOrder - 商户订单
  • Product - 产品
  • ProductVariant - 产品变体
  • Address - 地址
  • ShopAdmin - 商店管理员

数据库命名约定

  • 字段名使用 camelCase（如 createdAt、orderNumber）
  • 布尔字段使用 is、allow 或 can 前缀
  • 枚举值使用 UPPER_SNAKE_CASE
  • 主键遵循 entityNameId 模式
  • 时间字段使用过去分词 + At（如 createdAt、updatedAt）

认证与授权

JWT 认证

  • 全局 JwtAuthGuard
  • 使用 @Public() 装饰器标记无需认证的端点
  • 基于角色的访问控制：Consumer、Promoter、Merchant、Admin

请求上下文

  • 请求上下文中间件追踪用户信息
  • RequestContextFields 包含：
    • requestId - 请求 ID
    • userId - 用户 ID
    • userRole - 用户角色
    • phoneNumber - 电话号码
    • email - 邮箱
    • userType - 用户类型
    • shopAdminId - 商店管理员 ID（v2.0）

队列系统

Bull 队列

  • 使用 Bull + Redis 实现后台任务队列
  • 队列类型：
    • Product - 产品处理
    • ImportProduct - 产品导入
    • InventoryItem - 库存项
    • OrderFulfillment - 订单履约
    • Order - 订单处理
    • Payout - 分润处理

队列监控

  • Bull Board 仪表板（开发环境）

API 开发规范

验证与转换

  • 使用 NestJS 装饰器进行验证
  • ValidationPipe 全局启用：
    • whitelist: true
    • transform: true
    • enableImplicitConversion: true

响应格式

  • 统一响应格式（ResponseInterceptor）
  • 自定义异常过滤器（AllExceptionsFilter）

分页模式

  • 所有列表 API 必须使用 PaginationInfo 基类
  • 查询参数：pageSize 和 pageNumber
  • 响应分页：page、limit、total、totalPages
  • 支持基于游标的分页（可选 cursor）

开发命令

启动服务

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

数据库操作

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

测试

npm run vitest           # 运行 Vitest 测试（新）
npm run test             # 运行 Jest 测试（旧）
npm run vitest:watch     # 监听模式
npm run vitest:cov       # 覆盖率报告
npm run vitest:e2e       # E2E 测试

代码质量

npm run lint             # ESLint 检查并修复
npm run format           # Prettier 格式化

构建

npm run build            # 构建应用

环境配置

环境变量文件

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

依赖环境

  • PostgreSQL 数据库
  • Redis 服务
  • AWS 账户（SES、Secrets Manager）
  • Stripe/PayPal 账户
  • Algolia 账户

部署

部署方式

  • AWS ElasticBeanstalk
  • Docker 容器化部署

监控

  • Prometheus 指标收集
  • Datadog APM 追踪
  • Bull Board 队列监控（开发）

测试策略

测试框架迁移

项目正在从 Jest 迁移到 Vitest：

  • 新测试（2025-01 后）必须使用 Vitest
  • 旧测试保留在 Jest 中，逐步迁移
  • Vitest 速度比 Jest 快 40-60 倍

测试位置

  • Vitest: vitest/ 目录
    • 单元测试: vitest/modules/[module-name]/*.spec.ts
    • E2E 测试: vitest/e2e/*.spec.ts
  • Jest: test/ 目录（废弃，不用于新测试）

Git 分支策略

  • 主分支: release - PR 应合并到此分支
  • 预发布分支: staging - 发布前测试

参考文档

results matching ""

    No results matching ""