Katana Web 项目文档

项目概述

Katana Web 是一个基于 Next.js 14 的电商平台前端项目，采用 Turborepo 管理的 Monorepo 架构。项目包含消费者 Web 应用、管理后台和共享组件库。

技术栈: Next.js 14 + React 18 + TypeScript 构建系统: Turborepo 2.x 包管理器: pnpm 9.x

技术栈

核心框架

  • Next.js 14.2.35 - React 全栈框架
  • React 18.2.0 - UI 库
  • TypeScript 5.2.2 - 类型系统

UI/UX 组件

  • Material-UI (mui workspace) - 自定义 MUI 组件
  • Shopify Polaris 12.27.0 - Shopify 组件库
  • Emotion - CSS-in-JS 样式方案
  • @dnd-kit - 拖拽功能
  • Lexical 0.18.0 - 富文本编辑器

状态管理

  • Jotai 2.x - 原子化状态管理
  • React Context - 上下文状态
  • ahooks 3.8.1 - React Hooks 工具库

表单处理

  • React Hook Form 7.48.2 - 表单管理
  • Yup 1.6.1 - Schema 验证

支付集成

  • PayPal SDK (@paypal/react-paypal-js 8.8.1)
  • Stripe - 支付处理

二维码

  • qrcode 1.5.4 - 二维码生成
  • qr-scanner 1.4.2 - 二维码扫描
  • zxing-wasm 2.2.1 - 二维码解码

工具库

  • Ramda 0.29.1 - 函数式编程工具
  • date-fns 2.30.0 - 日期处理
  • currency.js 2.0.4 - 货币计算
  • dompurify 3.2.5 - HTML 清理

分析与监控

  • PostHog 1.215.4 - 产品分析
  • Vercel Speed Insights - 性能监控

开发工具

  • ESLint 8.57.1 - 代码检查
  • Prettier 3.3.2 - 代码格式化
  • Knip 5.60.0 - 未使用代码检测
  • Husky 9.0.3 - Git hooks
  • lint-staged 14.0.1 - 提交前检查

测试

  • Vitest 4.0.15 - 单元测试
  • @testing-library/react 16.3.0 - React 测试工具

Monorepo 架构

工作空间结构

katana-web/
├── apps/                      # 应用程序
│   ├── web/                   # 主 Web 应用（消费者）
│   ├── admin/                 # 管理后台
│   ├── consumer-web/          # 消费者 Web 应用
│   ├── katana-common/         # 公共模块
│   └── katana-transfer/       # 转账功能
│
├── packages/                  # 共享包
│   ├── ui/                    # UI 组件库
│   ├── hooks/                 # 自定义 Hooks
│   ├── icons/                 # 图标库
│   ├── mui/                   # Material-UI 组件
│   ├── utils/                 # 工具函数
│   ├── color-picker/          # 颜色选择器
│   ├── picker/                # 选择器组件
│   ├── eslint-config-custom/  # ESLint 配置
│   ├── tsconfig/              # TypeScript 配置
│   └── generator-template/    # 代码生成器模板
│
├── docs/                      # 文档
├── scripts/                   # 脚本文件
├── turbo.json                 # Turborepo 配置
├── Dockerfile
└── docker-compose.yml

应用说明

1. Web 应用 (apps/web)

端口: 3000 用途: 消费者电商平台

主要功能:

  • 产品浏览和搜索
  • 购物车和结账
  • 用户账户管理
  • 订单追踪
  • 社交电商功能

关键页面:

  • 登录/注册 (login)/
  • 产品目录 catalog/[storeId]/
  • 帖子详情 [vanityUrl]/post/[postAlias]/
  • 购物车 cart/
  • 结账 checkout/
  • 账户 account/

2. Admin 应用 (apps/admin)

端口: 3002 用途: 管理后台

主要功能:

  • 商户管理
  • 产品管理
  • 订单管理
  • 数据分析

额外依赖:

  • @antv/g2 5.2.10 - 图表库
  • Papaparse 5.5.3 - CSV 解析
  • Smartlook 10.0.0 - 用户行为分析

3. Consumer Web (apps/consumer-web)

用途: 消费者端专用应用

4. Katana Common (apps/katana-common)

用途: 应用间共享的公共代码

5. Katana Transfer (apps/katana-transfer)

用途: 转账功能模块

共享包说明

UI 包 (packages/ui)

Tag: shared 用途: 共享 UI 组件库

主要组件:

  • 按钮组件
  • 表单组件
  • 日期时间组件
  • 拖拽组件 (dnd-kit)
  • 数字输入 (react-number-format)
  • OTP 输入 (react18-input-otp)

技术依赖:

  • Emotion (CSS-in-JS)
  • React Hook Form
  • Lexical (富文本编辑器)
  • react-dnd (拖拽)

Hooks 包 (packages/hooks)

Tag: shared 用途: 自定义 React Hooks

主要 Hooks:

  • 国际化 (use-intl)
  • 状态管理 (jotai)
  • 动画 (@react-spring/web)
  • 手势 (@use-gesture/react)

MUI 包 (packages/mui)

Tag: shared 用途: Material-UI 组件封装

Icons 包 (packages/icons)

Tag: shared 用途: 图标库

Utils 包 (packages/utils)

Tag: utils 用途: 工具函数库

Picker 包 (packages/picker)

Tag: shared 用途: 选择器组件（颜色、日期等）

Color Picker 包 (packages/color-picker)

Tag: shared 用途: 颜色选择器组件

开发命令

根目录命令

# 开发
pnpm run dev              # 启动所有应用
pnpm run dev:dev          # 开发环境
pnpm run dev:staging      # 预发布环境
pnpm run dev:release      # 发布环境
pnpm run dev:prod         # 生产环境

# 单独启动应用
pnpm run dev:web          # 仅启动 web 应用
pnpm run dev:admin        # 仅启动 admin 应用
pnpm run dev:web:ssl      # 启动 web (SSL)

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

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

# 测试
pnpm run test:web         # 运行 web 应用测试
pnpm run test:web-common  # 运行公共模块测试

Web 应用命令 (apps/web)

npm run dev               # 开发服务器 (PORT=3000)
npm run dev:dev           # 开发环境
npm run dev:staging       # 预发布环境
npm run dev:release       # 发布环境
npm run dev:turbo         # 使用 Turbopack
npm run dev:ssl           # HTTPS 开发

npm run build             # 构建生产版本
npm run analyze           # 构建分析

npm run start             # 启动生产服务器
npm run lint              # ESLint 检查
npm run lint:fix          # ESLint 修复

npm run test              # 运行测试
npm run test-ui           # 测试 UI + 覆盖率

Admin 应用命令 (apps/admin)

npm run dev               # 开发服务器 (PORT=3002)
npm run dev:dev           # 开发环境
npm run dev:staging       # 预发布环境
npm run dev:release       # 发布环境
npm run dev:turbo         # 使用 Turbopack

npm run build             # 构建
npm run start             # 启动生产服务器
npm run lint              # ESLint 检查

环境配置

环境变量文件

Web 应用 (apps/web/):

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

Admin 应用 (apps/admin/):

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

关键环境变量

变量名 说明
NEXT_PUBLIC_APP_ENV 应用环境
NEXT_PUBLIC_PATH_ORIGIN 源地址
NEXT_PUBLIC_ASSET_PATH_ORIGIN 资源地址
NEXT_PUBLIC_SERVER_HOST_ENV 服务器地址
NEXT_PUBLIC_PAYPAL_CLIENT_ID PayPal 客户端 ID
NEXT_PUBLIC_STRIPE_PUBLIC_KEY Stripe 公钥
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME Cloudinary 云名称
NEXT_PUBLIC_POSTHOG_KEY PostHog 密钥
NEXT_PUBLIC_APPS_SHOPIFY_CLIENT_ID Shopify 客户端 ID

开发规范

架构原则

  • 遵循 SOLID 原则
  • 使用路径别名（避免深层相对导入）
  • 语义化 HTML
  • React.memo 优化列表性能

UI/样式标准

  • 使用 rem 单位 - 字体和 SVG（ADA 合规）
  • 使用主题值 - 不硬编码颜色
  • Styled Components 优先 - 避免内联 sx props
  • 模块级组件 - 不嵌套组件定义

代码风格

  • 所有文档和代码注释使用英文
  • 通过 ESLint 和 Prettier 保持一致风格
  • 提交前通过 lint-staged 检查

构建与部署

Turborepo 配置

  • 并发数: 11
  • 缓存策略: 任务依赖和输出缓存
  • 边界检查: 防止非法依赖

部署方式

  • Vercel - 主要部署平台
  • Docker - 容器化部署

构建优化

  • Next.js 自动代码分割
  • Turborepo 增量构建
  • 包分析和优化 (analyze 命令)

测试

测试框架

  • Vitest 4.0.15 - 单元测试
  • @testing-library/react - React 组件测试
  • @vitest/coverage-v8 - 代码覆盖率

测试命令

# Web 应用
npm run test              # 运行测试
npm run test-ui           # 测试 UI + 覆盖率

浏览器支持

[
  "> 0.5%",
  "defaults"
]

运行时要求

  • Node.js: 22.x
  • pnpm: >= 9.15
  • Bun: >= 1.2.19 (可选)

Git Hooks

Husky 配置

  • pre-commit: 运行 lint-staged
  • commit-msg: 验证提交信息 (verify-commit)

Lint-staged

{
  "apps/**/*.{js,jsx,ts,tsx}": "eslint --fix --",
  "packages/(hooks|ui|utils)/**/*.{js,jsx,ts,tsx}": "eslint --fix --",
  "**/*.{js,jsx,ts,tsx,md,json}": "prettier --write"
}

开发工具脚本

依赖分析

npm run analyze-deps       # 分析依赖
npm run analyze-deps:json  # 输出 JSON 格式
npm run analyze-deps:html  # 生成 HTML 报告

循环依赖检测

npm run dpdm               # 检测循环依赖

未使用代码检测

npm run knip               # 检测未使用代码

参考文档

results matching ""

    No results matching ""