danial/kami_apple_exchage
1
0
Fork 0
mirror of https://git.oceanpay.cc/danial/kami_apple_exchage.git synced 2025-12-18 11:15:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
kami_apple_exchage/CLAUDE_CN.md
danial 48cdcb6140 feat: Add deployment scripts and configuration for Apple Gift Card Exchange Platform 
- Create README.md for deployment instructions including environment requirements and setup steps.
- Implement deploy.sh script for automated deployment of development and production environments.
- Add combined Docker Compose configuration for frontend and backend services.
- Include Redis configuration file for optimized memory management and persistence.
- Update frontend Dockerfile to handle Next.js asset paths and static files.
- Remove obsolete deployment files and configurations from frontend directory.
2025-09-11 17:57:18 +08:00

5.8 KiB
Raw Permalink Blame History

CLAUDE_CN.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供中文指导。

开发命令

前端 (Next.js)

  • cd frontend && bun install - 安装依赖
  • cd frontend && bun run dev - 启动开发服务器（使用 Turbopack）
  • cd frontend && bun run build - 构建生产版本
  • cd frontend && bun run start - 启动生产服务器
  • cd frontend && bun run lint - 运行 ESLint 检查
  • cd frontend && bun run generate:api - 从 OpenAPI 规范生成 API 客户端
  • cd frontend && bun run generate:api:watch - 监听模式生成 API 客户端

后端 (FastAPI)

  • cd backend && uv sync - 使用 UV 安装依赖
  • cd backend && uv run python app/main.py - 运行开发服务器
  • cd backend && uv run pytest - 运行测试
  • cd backend && uv run black . - 使用 Black 格式化代码
  • cd backend && uv run isort . - 使用 isort 排序导入
  • cd backend && uv run mypy . - 使用 MyPy 进行类型检查
  • cd backend && uv run ruff check . - 使用 Ruff 进行代码检查

Docker 开发

  • cd backend && docker-compose up -d - 使用 Docker Compose 启动所有服务
  • cd backend && docker-compose down - 停止所有服务
  • cd backend && docker-compose logs -f - 查看日志

架构概述

项目结构

这是一个全栈应用程序，包含：

  • 前端: Next.js 15 with App Router, React 18, TypeScript
  • 后端: FastAPI with Python 3.13, async/await 架构
  • 基础设施: Docker, Kubernetes, Redis, PostgreSQL

前端架构

  • 框架: Next.js 15 with App Router
  • UI: 苹果风格设计系统，自定义组件
  • 状态管理: React Context + TanStack Query 管理服务端状态
  • 表单: React Hook Form + Zod 验证
  • HTTP: 增强版 Axios 客户端
  • 样式: Tailwind CSS + Less 处理复杂样式
  • 动画: Framer Motion
  • 包管理器: Bun (配置在 bunfig.toml 中)

后端架构

  • 框架: FastAPI with async/await
  • 架构: 分布式微服务，使用 Celery 任务队列
  • 浏览器自动化: Playwright 网页爬虫
  • 数据库: PostgreSQL with asyncpg
  • 缓存: Redis 分布式锁和状态管理
  • 任务队列: Celery with Redis broker
  • 监控: OpenTelemetry 集成
  • 包管理器: UV (配置在 pyproject.toml 中)

核心目录

前端 (frontend/)

  • src/app/ - Next.js App Router 页面
  • src/components/ - 可重用组件
    • dashboard/ - 主要仪表板组件
    • forms/ - 表单组件（含验证）
    • layout/ - 布局和主题组件
    • ui/ - 基础 UI 组件（苹果风格）
    • animate-ui/ - 动画 UI 组件
  • src/lib/ - 工具库
    • api/ - API 客户端和生成类型
    • contexts/ - React 上下文（主题、刷新）
    • hooks/ - 自定义 React Hooks
    • telemetry/ - OpenTelemetry 集成

后端 (backend/)

  • app/api/ - FastAPI 路由和端点
  • app/core/ - 核心功能（配置、数据库、redis 等）
  • app/models/ - SQLAlchemy 数据模型
  • app/schemas/ - Pydantic 模式
  • app/services/ - 业务逻辑服务
  • app/tasks/ - Celery 任务定义
  • app/repositories/ - 数据访问层
  • deploy/ - Docker 和部署配置
  • docs/ - 架构和项目文档

核心功能

前端功能

  • 实时仪表板，自动刷新
  • 苹果风格 UI，流畅动画
  • 文件上传和数据管理
  • 订单和任务监控
  • 链接管理系统
  • 主题切换（深色/浅色）
  • OpenTelemetry 遥测集成

后端功能

  • 使用 Playwright 分布式网页爬虫
  • 基于 Redis 的分布式锁
  • Celery 任务队列系统
  • 自动任务恢复和故障处理
  • Kubernetes 部署支持
  • 优雅关闭处理
  • 全面的健康检查
  • OpenTelemetry 结构化日志

API 集成

  • 后端在 http://localhost:8000/openapi.json 提供 OpenAPI 规范
  • 前端使用 Orval 自动生成 API 客户端代码
  • 生成文件位于 frontend/src/lib/api/generated/
  • 增强版 axios 客户端，包含拦截器和错误处理

状态管理

前端状态

  • 全局状态: React Context 管理主题和刷新设置
  • 服务端状态: TanStack Query 管理 API 数据
  • 本地状态: React Hooks 管理组件状态
  • 表单状态: React Hook Form + Zod 模式

后端状态

  • 数据库: PostgreSQL with SQLAlchemy ORM
  • 缓存: Redis 分布式状态和锁
  • 任务状态: Celery backend 任务进度跟踪
  • 会话状态: Redis 基础会话管理

部署配置

开发环境

  • 前端: Bun 开发服务器
  • 后端: UV 开发服务器
  • 服务: Docker Compose 管理 Redis, PostgreSQL

生产环境

  • 前端: Docker 容器 + Nginx
  • 后端: 多服务 Docker 部署
  • 编排: Kubernetes with Helm charts
  • 监控: Prometheus + Grafana
  • 日志: OpenTelemetry 结构化日志

开发注意事项

环境变量

前端 (.env.local):

  • NEXT_PUBLIC_API_URL - 后端 API URL
  • NEXT_PUBLIC_ENV - 环境（development/production）
  • NEXT_PUBLIC_TELEMETRY_ENDPOINT - OpenTelemetry 端点

后端 (.env):

  • REDIS_URL - Redis 连接 URL
  • DATABASE_URL - PostgreSQL 连接 URL
  • SERVICE_TYPE - 服务类型（api/worker/recovery）
  • LOG_LEVEL - 日志级别

代码质量

  • 前端: ESLint + Prettier + TypeScript
  • 后端: Black + isort + MyPy + Ruff + pytest
  • 预提交: 前后端都配置了 Git hooks
  • 测试: 后端使用 pytest，前端可配置 Jest

关键架构模式

  • 微服务: 后端采用面向服务架构
  • 分布式系统: Redis 协调和锁机制
  • 事件驱动: Celery 任务队列异步处理
  • 响应式 UI: 前端使用轮询实时更新
  • 类型安全: 双端完整 TypeScript 覆盖

特别注意事项

  • 分布式锁: 多副本部署的关键机制
  • 优雅关闭: 部署期间确保任务完成
  • 错误处理: 全面的错误恢复机制
  • 监控: OpenTelemetry 全链路可观测性
  • 扩展性: Kubernetes HPA 水平扩展支持