my-django/CLAUDE.md

CLAUDE.md

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

Development Commands

Running the Application

# Start development server (for local development)
python manage.py runserver

# Start with uvicorn (production-like)
uvicorn mysite.asgi:application --host=0.0.0.0 --port=8000 --reload

Database Operations

# Run migrations
python manage.py makemigrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

Docker Development

# Build Docker image
docker build -t my-django:latest .

# Run with Docker Compose (see deploy/compose-test.yaml)
docker-compose -f deploy/compose-test.yaml up -d

Testing

# Run tests
python manage.py test

# Run tests for specific app
python manage.py test apps.role

Architecture Overview

Project Structure

This is a Django 5.1 REST API project with the following key components:

• mysite/: Main Django project configuration
• apps/: Modular Django applications
  • area/: Geographic area management
  • dictionary/: Data dictionary/configuration
  • menu/: Navigation menu system
  • menu_button/: Menu button permissions
  • role/: Role-based access control
  • system_user/: User management
• utils/: Shared utilities and middleware

Key Configuration Details

Database Setup

• Primary Database: MySQL (host: 47.108.232.131:3306, database: ky)
• Secondary Database: MongoDB (host: 47.108.232.131:27017, database: wk)
• Caching: Redis with multiple databases (0: default, 1: queue, 2: base, 3: cache)

REST Framework Configuration

• Uses Django REST Framework 3.15.2
• JSON response format with custom response wrapper
• Exception handling via utils.exception.CustomExceptionMiddleware
• Filtering support via django-filter
• API documentation with CoreAPI

Internationalization

• Primary language: Chinese (zh-hans)
• Timezone: Asia/Shanghai
• Localization support enabled

API Structure

All APIs follow the pattern:

• /area/ - Area management endpoints
• /role/ - Role management endpoints
• /menu/ - Menu management endpoints
• /menu_button/ - Menu button endpoints
• /dictionary/ - Dictionary endpoints
• /system_user/ - User management endpoints

Custom Utilities

• utils.json_response.Response: Standardized API response wrapper
• utils.exception.CustomExceptionMiddleware: Global exception handling
• utils.paginator: Custom pagination logic
• utils.redis: Redis connection utilities

Deployment

• Containerized with Docker (Python 3.11-slim base)
• Uses uvicorn ASGI server
• CI/CD via GitHub Actions with self-hosted runners
• Deployment to test environment via Docker Compose

Development Notes

Dependencies

• Core: Django 5.1.5, Django REST Framework 3.15.2
• Database: PyMySQL, mongoengine
• Caching: django-redis
• Server: uvicorn

Security Considerations

• CSRF middleware is disabled (line 55 in settings.py)
• Custom exception middleware catches all unhandled exceptions
• Debug mode enabled (should be disabled in production)

Logging

• Comprehensive logging setup with rotation
• Separate log files for general logs and error logs
• File-based logging with console output for development