# CLAUDE.md

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

## Development Commands

### Running the Application
```bash
# 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
```bash
# Run migrations
python manage.py makemigrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser
```

### Docker Development
```bash
# 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
```bash
# 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