danial/kami_apple_exchage
1
0
Fork 0
mirror of https://git.oceanpay.cc/danial/kami_apple_exchage.git synced 2025-12-18 12:43:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
dd6dbdee842fca7db520edc24637ea5e0f0937bd
kami_apple_exchage/CLAUDE.md
danial 8ad2a5366a refactor(backend): 将Celery替换为Arq进行协程任务处理 
本次提交将后端的任务队列系统从Celery迁移到了Arq，以支持基于协程的任务处理。主要改动包括：
- 更新文档和配置文件，反映架构变化。
- 修改健康检查和服务初始化逻辑，以适应Arq的使用。
- 移除与Celery相关的代码，并添加Arq任务定义和调度器。
- 更新Dockerfile和相关脚本，确保Arq worker能够正确运行。
- 调整API和业务服务中的任务处理逻辑，移除对Celery的依赖。

这些改动旨在提高系统的异步处理能力和整体性能。
2025-09-18 16:02:05 +08:00

6.4 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Frontend (Next.js)

  • cd frontend && bun install - Install dependencies
  • cd frontend && bun run dev - Start development server with Turbopack
  • cd frontend && bun run build - Build production version
  • cd frontend && bun run start - Start production server
  • cd frontend && bun run lint - Run ESLint checks
  • cd frontend && bun run generate:api - Generate API client from OpenAPI spec
  • cd frontend && bun run generate:api:watch - Generate API client with watch mode

Backend (FastAPI)

  • cd backend && uv sync - Install dependencies with UV
  • cd backend && uv run python app/main.py - Run development server
  • cd backend && uv run python scripts/start_arq_worker.py - Start ARQ worker
  • cd backend && uv run pytest - Run tests
  • cd backend && uv run black . - Format code with Black
  • cd backend && uv run isort . - Sort imports with isort
  • cd backend && uv run mypy . - Type checking with MyPy
  • cd backend && uv run ruff check . - Lint with Ruff

Docker Development

  • cd backend && docker-compose up -d - Start all services with Docker Compose
  • cd backend && docker-compose down - Stop all services
  • cd backend && docker-compose logs -f - View logs

Architecture Overview

Project Structure

This is a full-stack application with:

  • Frontend: Next.js 15 with App Router, React 18, TypeScript
  • Backend: FastAPI with Python 3.13, async/await architecture
  • Infrastructure: Docker, Kubernetes, Redis, PostgreSQL

Frontend Architecture

  • Framework: Next.js 15 with App Router
  • UI: Apple-style design system with custom components
  • State Management: React Context + TanStack Query for server state
  • Forms: React Hook Form + Zod validation
  • HTTP: Axios with enhanced client
  • Styling: Tailwind CSS + Less for complex styles
  • Animation: Framer Motion
  • Package Manager: Bun (configured in bunfig.toml)

Backend Architecture

  • Framework: FastAPI with async/await
  • Architecture: Distributed microservices with ARQ task queues
  • Browser Automation: Playwright for web scraping
  • Database: PostgreSQL with asyncpg
  • Cache: Redis for distributed locking and state management
  • Task Queue: ARQ with Redis broker
  • Monitoring: OpenTelemetry integration
  • Package Manager: UV (configured in pyproject.toml)

Key Directories

Frontend (frontend/)

  • src/app/ - Next.js App Router pages
  • src/components/ - Reusable components
    • dashboard/ - Main dashboard components
    • forms/ - Form components with validation
    • layout/ - Layout and theme components
    • ui/ - Base UI components (Apple-style)
    • animate-ui/ - Animated UI components
  • src/lib/ - Utility libraries
    • api/ - API client and generated types
    • contexts/ - React contexts (theme, refresh)
    • hooks/ - Custom React hooks
    • telemetry/ - OpenTelemetry integration

Backend (backend/)

  • app/api/ - FastAPI routes and endpoints
  • app/core/ - Core functionality (config, database, redis, etc.)
  • app/models/ - SQLAlchemy data models
  • app/schemas/ - Pydantic schemas
  • app/services/ - Business logic services
  • app/tasks/ - ARQ task definitions
  • app/repositories/ - Data access layer
  • deploy/ - Docker and deployment configurations
  • docs/ - Architecture and project documentation

Core Features

Frontend Features

  • Real-time dashboard with auto-refresh
  • Apple-style UI with smooth animations
  • File upload and data management
  • Order and task monitoring
  • Link management system
  • Theme switching (dark/light)
  • OpenTelemetry telemetry integration

Backend Features

  • Distributed web scraping with Playwright
  • Redis-based distributed locking
  • ARQ task queue system
  • Automatic task recovery and failure handling
  • Kubernetes deployment support
  • Graceful shutdown handling
  • Comprehensive health checks
  • Structured logging with OpenTelemetry

API Integration

  • Backend provides OpenAPI specification at http://localhost:8000/openapi.json
  • Frontend auto-generates API client code using Orval
  • Generated files in frontend/src/lib/api/generated/
  • Enhanced axios client with interceptors and error handling

State Management

Frontend State

  • Global State: React Context for theme and refresh settings
  • Server State: TanStack Query for API data management
  • Local State: React hooks for component state
  • Form State: React Hook Form with Zod schemas

Backend State

  • Database: PostgreSQL with SQLAlchemy ORM
  • Cache: Redis for distributed state and locking
  • Task State: ARQ backend for task progress tracking
  • Session State: Redis-based session management

Deployment Configuration

Development

  • Frontend: Bun development server
  • Backend: UV development server
  • Services: Docker Compose for Redis, PostgreSQL

Production

  • Frontend: Docker container with Nginx
  • Backend: Multi-service Docker deployment
  • Orchestration: Kubernetes with Helm charts
  • Monitoring: Prometheus + Grafana
  • Logging: Structured logs with OpenTelemetry

Development Notes

Environment Variables

Frontend (.env.local):

  • NEXT_PUBLIC_API_URL - Backend API URL
  • NEXT_PUBLIC_ENV - Environment (development/production)
  • NEXT_PUBLIC_TELEMETRY_ENDPOINT - OpenTelemetry endpoint

Backend (.env):

  • REDIS_URL - Redis connection URL
  • DATABASE_URL - PostgreSQL connection URL
  • SERVICE_TYPE - Service type (api/worker/recovery)
  • LOG_LEVEL - Logging level

Code Quality

  • Frontend: ESLint + Prettier + TypeScript
  • Backend: Black + isort + MyPy + Ruff + pytest
  • Pre-commit: Hooks for both frontend and backend
  • Testing: pytest for backend, Jest setup available for frontend

Key Architectural Patterns

  • Microservices: Backend uses service-oriented architecture
  • Distributed Systems: Redis-based coordination and locking
  • Event-Driven: ARQ task queues for async processing
  • Reactive UI: Frontend uses real-time updates with polling
  • Type Safety: Full TypeScript coverage on both ends

Special Considerations

  • Distributed Locking: Critical for multi-replica deployments
  • Graceful Shutdown: Ensures task completion during deployments
  • Error Handling: Comprehensive error recovery mechanisms
  • Monitoring: Full observability with OpenTelemetry
  • Scaling: Horizontal scaling support with Kubernetes HPA