422 lines
20 KiB
Markdown
422 lines
20 KiB
Markdown
# Codebase Structure
|
|
|
|
**Analysis Date:** 2026-05-07
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
qy_lty/
|
|
├── manage.py # Django management script
|
|
├── run.sh # Start development server (daphne)
|
|
├── requirements.txt # Python dependencies
|
|
├── Dockerfile # Container image build
|
|
├── docker-compose.yml # Docker compose for dev environment
|
|
├── .env # Environment variables (not committed)
|
|
│
|
|
├── qy_lty/ # Project configuration package
|
|
│ ├── __init__.py
|
|
│ ├── settings.py # Django settings (INSTALLED_APPS, middleware, auth, etc.)
|
|
│ ├── asgi.py # ASGI app entry (Channels + HTTP routing)
|
|
│ ├── wsgi.py # WSGI app entry (for traditional servers)
|
|
│ └── urls.py # Root URL router (includes all app URLs)
|
|
│
|
|
├── userapp/ # User authentication & profile management
|
|
│ ├── models.py # ParadiseUser (custom user model), AffinityRule, AffinityLevel
|
|
│ ├── views.py # MacAddressLoginView, PhoneLoginView, UserViewSet, ProfileView
|
|
│ ├── serializers.py # ParadiseUserSerializer, ProfileUpdateSerializer
|
|
│ ├── urls.py # User API routes: /api/user/
|
|
│ ├── auth_urls.py # Auth-specific routes (deprecated/legacy)
|
|
│ ├── admin_urls.py # Admin API routes: /api/v1/admin/
|
|
│ ├── authentication.py # RedisTokenAuthentication class
|
|
│ ├── utils.py # generate_token(), get_user_id_from_token(), send_sms()
|
|
│ ├── admin.py # Django admin customization
|
|
│ ├── apps.py # App configuration
|
|
│ ├── migrations/ # Database migrations
|
|
│ ├── management/ # Custom management commands
|
|
│ └── tests.py # Unit tests
|
|
│
|
|
├── aiapp/ # AI chat & voice integration
|
|
│ ├── models.py # ChatMessage, Bot, ConversationSubtitle
|
|
│ ├── views.py # BotViewSet, ChatView (Kimi API integration, multi-turn chat)
|
|
│ ├── serializers.py # ChatMessageSerializer
|
|
│ ├── urls.py # AI API routes: /api/ai/
|
|
│ ├── kimi.py # Kimi API client (OpenAI compatible)
|
|
│ ├── audio/ # Audio service abstraction
|
|
│ │ ├── AudioService.py # Multi-provider audio (Aliyun/Volcengine/Tencent)
|
|
│ │ ├── aliyun_audio.py # Aliyun NLS implementation
|
|
│ │ └── [other provider implementations]
|
|
│ ├── admin.py # Admin interface for Chat models
|
|
│ ├── apps.py # App configuration
|
|
│ ├── migrations/ # Database migrations
|
|
│ └── tests.py
|
|
│
|
|
├── device_interaction/ # WebSocket real-time device communication
|
|
│ ├── models.py # Device, DeviceType, DeviceBatch, UserDevice
|
|
│ ├── views.py # DeviceTypeViewSet, DeviceViewSet, UserDeviceViewSet, RTC endpoints
|
|
│ ├── serializers.py # DeviceSerializer, UserDeviceSerializer, DeviceBindSerializer
|
|
│ ├── urls.py # Device HTTP API routes: /api/device/
|
|
│ ├── routing.py # WebSocket URL routing (ws://domain/ws/device/)
|
|
│ ├── consumers.py # DeviceConsumer (AsyncWebsocketConsumer, message handlers)
|
|
│ ├── auth.py # TokenAuthMiddleware (WebSocket auth)
|
|
│ ├── amap_api.py # Amap (高德地图) location/nearby search
|
|
│ ├── weather.py # QWeather API for weather data
|
|
│ ├── volcengine_api.py # Volcengine RTC token generation
|
|
│ ├── swagger.py # Swagger schema definitions
|
|
│ ├── admin.py # Admin interface for Device models
|
|
│ ├── apps.py # App configuration
|
|
│ ├── middleware.py # Custom middleware (if any)
|
|
│ ├── services.py # Business logic services
|
|
│ ├── scheduler.py # Async task scheduling (e.g., device heartbeat monitoring)
|
|
│ ├── management/ # Custom management commands
|
|
│ ├── migrations/ # Database migrations
|
|
│ └── tests.py
|
|
│
|
|
├── card/ # Card management system
|
|
│ ├── models.py # CardCategory, CardBatch, Card, CardUsageLog
|
|
│ ├── views.py # CardViewSet, batch generation, QR code endpoints
|
|
│ ├── serializers.py # CardSerializer
|
|
│ ├── urls.py # Card API routes: /api/card/
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ ├── migrations/
|
|
│ └── tests.py
|
|
│
|
|
├── achievement_app/ # User achievements & progress tracking
|
|
│ ├── models.py # Achievement, AchievementProgress, AchievementBadge
|
|
│ ├── views.py # AchievementViewSet, ProgressView
|
|
│ ├── serializers.py # AchievementSerializer
|
|
│ ├── urls.py # Achievement API routes: /api/achievement/
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ ├── migrations/
|
|
│ └── tests.py
|
|
│
|
|
├── subscription_app/ # Subscription & billing management
|
|
│ ├── models.py # Subscription, SubscriptionPlan, Payment
|
|
│ ├── views.py # SubscriptionViewSet
|
|
│ ├── serializers.py # SubscriptionSerializer
|
|
│ ├── urls.py # Subscription API routes (if exposed)
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ ├── migrations/
|
|
│ ├── templates/ # Email templates for subscription notifications
|
|
│ └── tests.py
|
|
│
|
|
├── ali_vi_app/ # Aliyun Visual Intelligence integration
|
|
│ ├── models.py # VIRequest, VIResult
|
|
│ ├── views.py # Aliyun VI API wrappers
|
|
│ ├── urls.py # VI API routes (currently disabled in root urls.py line 52)
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ ├── migrations/
|
|
│ └── tests.py
|
|
│
|
|
├── food_app/ # Food management system (new)
|
|
│ ├── models.py # Food, FoodInventory
|
|
│ ├── views.py # FoodViewSet
|
|
│ ├── serializers.py
|
|
│ ├── urls.py # Food API routes: /api/food/
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ ├── migrations/
|
|
│ └── tests.py
|
|
│
|
|
├── workflow_app/ # Multi-tenant workflow management (dev)
|
|
│ ├── models.py # Workflow, WorkflowStep, WorkflowTask
|
|
│ ├── views.py
|
|
│ ├── serializers.py
|
|
│ ├── urls.py
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ ├── migrations/
|
|
│ └── tests.py
|
|
│
|
|
├── common/ # Shared utilities & middleware
|
|
│ ├── middleware.py # StandardResponseMiddleware (standardizes all responses)
|
|
│ ├── pagination.py # CustomPageNumberPagination (DRF pagination)
|
|
│ ├── responses.py # Helper functions: success_response(), error_response()
|
|
│ ├── swagger_utils.py # Swagger/OpenAPI utilities
|
|
│ ├── aliyun_logging.py # Aliyun log service setup
|
|
│ ├── VolcEngineAccessToken.py # Volcengine RTC token generation
|
|
│ ├── admin.py
|
|
│ ├── apps.py
|
|
│ └── [other shared modules]
|
|
│
|
|
├── templates/ # HTML templates for Django admin & error pages
|
|
│ └── [admin templates, error pages]
|
|
│
|
|
├── locale/ # i18n translation catalogs
|
|
│ ├── en/ # English translations
|
|
│ │ └── LC_MESSAGES/
|
|
│ │ ├── django.po # Compiled message file
|
|
│ │ └── django.mo # Binary compiled messages
|
|
│ └── zh_HAns/ # Simplified Chinese translations
|
|
│ └── LC_MESSAGES/
|
|
│
|
|
├── static/ # Static files (JS, CSS, images) — dev only
|
|
│ └── [served by STATIC_URL]
|
|
│
|
|
├── media/ # User-uploaded files — dev only
|
|
│ └── [served by MEDIA_URL]
|
|
│
|
|
├── docs/ # Documentation
|
|
│ ├── README.md # Project overview
|
|
│ ├── 修改记录.md # Change log (Chinese, auto-maintained)
|
|
│ ├── 设备动态绑定方案.md # Device dynamic binding design
|
|
│ ├── 设备聊天记录_字幕落库方案.md # Chat transcript & subtitle storage design
|
|
│ ├── device_api.md # WebSocket device API reference
|
|
│ ├── device_commands.md # Device command reference
|
|
│ ├── device_errors.md # Device error codes
|
|
│ ├── device_module.md # Device module overview
|
|
│ ├── user_authentication_api.md # User auth API reference
|
|
│ ├── api/ # API endpoint documentation
|
|
│ ├── development/ # Development guides
|
|
│ ├── features/ # Feature documentation
|
|
│ └── integrations/ # Integration guides
|
|
│
|
|
└── .planning/ # GSD codebase mapping (auto-generated)
|
|
└── codebase/
|
|
├── ARCHITECTURE.md # Architecture patterns & data flows
|
|
└── STRUCTURE.md # This file
|
|
```
|
|
|
|
## Directory Purposes
|
|
|
|
**qy_lty/ (Project Config):**
|
|
- Purpose: Django project configuration and root URL routing
|
|
- Contains: Settings, ASGI/WSGI entry points, URL dispatcher
|
|
- Key files:
|
|
- `settings.py` (line 1-400+): All Django configuration, app list, middleware, DB, cache, auth
|
|
- `urls.py` (line 49-60): Centralizes all API routes via `include()`
|
|
- `asgi.py` (line 19-26): ProtocolTypeRouter for HTTP + WebSocket
|
|
|
|
**userapp/:**
|
|
- Purpose: User authentication, profile management, affinity system
|
|
- Contains: ParadiseUser model, MAC/phone login, token generation, user info endpoints
|
|
- Key files:
|
|
- `models.py` (line 8-145): ParadiseUser, AffinityRule, AffinityLevel (favorability system)
|
|
- `authentication.py` (line 10-34): RedisTokenAuthentication class
|
|
- `utils.py` (line 33-37): `generate_token()` stores in Redis with 30-day TTL
|
|
|
|
**device_interaction/:**
|
|
- Purpose: Real-time device communication via WebSocket, device management
|
|
- Contains: WebSocket consumer, device CRUD, user-device binding, RTC token endpoints
|
|
- Key files:
|
|
- `consumers.py` (line 10-320+): DeviceConsumer handles connect/receive/disconnect, group messaging
|
|
- `routing.py` (line 4-7): WebSocket URL patterns
|
|
- `auth.py` (line 4-50): TokenAuthMiddleware authenticates WebSocket connections
|
|
- `models.py` (line 43-145): Device, UserDevice with "last-bind-wins" ordering
|
|
|
|
**aiapp/:**
|
|
- Purpose: AI chat (Kimi), multi-provider audio services
|
|
- Contains: Chat message models, Kimi API client, audio synthesis/recognition
|
|
- Key files:
|
|
- `views.py` (line 1-60+): BotViewSet, ChatView for multi-turn conversations
|
|
- `audio/` (submodule): AudioService factory + provider implementations
|
|
|
|
**card/:**
|
|
- Purpose: Card management (categories, batches, QR codes, usage tracking)
|
|
- Contains: Card CRUD, batch generation, QR code generation/scanning
|
|
- Key files: models.py, views.py (batch endpoints), serializers.py
|
|
|
|
**achievement_app/:**
|
|
- Purpose: User achievements, progress tracking, badges
|
|
- Contains: Achievement definitions, user progress models
|
|
- Key files: models.py, views.py (progress endpoints)
|
|
|
|
**subscription_app/:**
|
|
- Purpose: Billing and subscription management
|
|
- Contains: Subscription plans, payment records
|
|
- Key files: models.py
|
|
|
|
**ali_vi_app/, food_app/, workflow_app/:**
|
|
- Purpose: Specialized modules (Aliyun Visual Intelligence, Food management, Workflow automation)
|
|
- Contains: Domain-specific models, views, serializers
|
|
- Note: ali_vi_app routes disabled in qy_lty/urls.py line 52
|
|
|
|
**common/:**
|
|
- Purpose: Shared utilities across all apps
|
|
- Contains: Middleware, pagination, response helpers, external API clients
|
|
- Key files:
|
|
- `middleware.py` (line 6-145): StandardResponseMiddleware wraps all responses
|
|
- `pagination.py` (line 1-9): CustomPageNumberPagination for DRF list views
|
|
- `responses.py`: Helper functions for standardized responses
|
|
|
|
**locale/:**
|
|
- Purpose: i18n translation catalogs (Chinese/English)
|
|
- Contains: Django message files (.po/.mo)
|
|
- Generated by: `django-admin makemessages -l en`, `compilemessages`
|
|
|
|
**docs/:**
|
|
- Purpose: Human-readable documentation
|
|
- Contains: Design docs, API references, development guides
|
|
- Key files:
|
|
- `修改记录.md`: Auto-maintained change log (new entries at top)
|
|
- `设备动态绑定方案.md`: Device binding strategy & semantics
|
|
- `device_api.md`: WebSocket message types & format
|
|
|
|
## Key File Locations
|
|
|
|
**Entry Points:**
|
|
- `qy_lty/urls.py`: HTTP root router (line 63-73)
|
|
- `qy_lty/asgi.py`: ASGI app with Channels (line 19-26)
|
|
- `device_interaction/routing.py`: WebSocket URL patterns (line 4-7)
|
|
- `device_interaction/consumers.py`: WebSocket message handler (line 10+)
|
|
|
|
**Configuration:**
|
|
- `qy_lty/settings.py`: All Django configuration (INSTALLED_APPS, middleware, auth, databases)
|
|
- `.env`: Environment variables (NEVER committed; copy from `.env.bak` if it exists)
|
|
- `requirements.txt`: Python package dependencies
|
|
|
|
**Authentication & Authorization:**
|
|
- `userapp/authentication.py`: RedisTokenAuthentication (HTTP)
|
|
- `device_interaction/auth.py`: TokenAuthMiddleware (WebSocket)
|
|
- `userapp/utils.py`: Token generation/lookup with Redis
|
|
- `userapp/models.py`: ParadiseUser (custom user model)
|
|
|
|
**Core Models:**
|
|
- `userapp/models.py`: ParadiseUser, AffinityRule, AffinityLevel
|
|
- `device_interaction/models.py`: Device, DeviceType, DeviceBatch, UserDevice
|
|
- `aiapp/models.py`: ChatMessage, Bot, ConversationSubtitle
|
|
- `card/models.py`: CardCategory, CardBatch, Card, CardUsageLog
|
|
- `achievement_app/models.py`: Achievement, AchievementProgress
|
|
- `subscription_app/models.py`: Subscription, SubscriptionPlan
|
|
|
|
**Middleware & Cross-Cutting:**
|
|
- `common/middleware.py`: StandardResponseMiddleware (response wrapper)
|
|
- `common/pagination.py`: CustomPageNumberPagination (DRF pagination)
|
|
- `common/responses.py`: `success_response()`, `error_response()` helpers
|
|
- `qy_lty/settings.py` line 82-95: All middleware configured
|
|
|
|
**API Documentation:**
|
|
- Swagger UI: Generated from code, served at `/swagger/`
|
|
- ReDoc: Alternative documentation UI at `/redoc/`
|
|
- drf-yasg integration: Configured in qy_lty/urls.py line 22-46
|
|
|
|
**Logging:**
|
|
- Configuration: `qy_lty/settings.py` (logging config, or via `common/aliyun_logging.py`)
|
|
- Entry point: `setup_logging()` in common/aliyun_logging.py (called from settings.py line 16)
|
|
|
|
**i18n Catalogs:**
|
|
- English: `locale/en/LC_MESSAGES/django.{po,mo}`
|
|
- Chinese: `locale/zh_HAns/LC_MESSAGES/django.{po,mo}`
|
|
- Generation: `django-admin makemessages -l {lang}`
|
|
- Compilation: `django-admin compilemessages`
|
|
|
|
## Naming Conventions
|
|
|
|
**Files:**
|
|
- Django app folders: lowercase_underscore (e.g., `device_interaction`, `user_app`)
|
|
- Python modules: lowercase_underscore (e.g., `models.py`, `serializers.py`, `auth.py`)
|
|
- Migrations: auto-generated format `000X_auto_YYYYMMDD_HHMM.py`
|
|
- Documentation: Chinese filename or English snake_case
|
|
|
|
**Directories:**
|
|
- Apps: snake_case (userapp, device_interaction, achievement_app)
|
|
- Packages: lowercase without underscores (audio/, management/, migrations/)
|
|
|
|
**URL Prefixes:**
|
|
- `/api/user/` → userapp endpoints
|
|
- `/api/device/` → device_interaction endpoints
|
|
- `/api/ai/` → aiapp endpoints
|
|
- `/api/card/` → card endpoints
|
|
- `/api/achievement/` → achievement_app endpoints
|
|
- `/api/food/` → food_app endpoints
|
|
- `/api/v1/admin/` → admin endpoints (via userapp.admin_urls)
|
|
- `/ws/device/` → WebSocket endpoint
|
|
|
|
**Database Models:**
|
|
- User model: `ParadiseUser` (extends AbstractUser)
|
|
- Device-related: `Device`, `DeviceBatch`, `DeviceType`, `UserDevice`
|
|
- Message models: `ChatMessage`, `ConversationSubtitle`
|
|
- Achievement models: `Achievement`, `AchievementProgress`, `AchievementBadge`
|
|
|
|
## Where to Add New Code
|
|
|
|
**New Feature (e.g., "Affinity Decay Task"):**
|
|
- Models: `device_interaction/models.py` (if device-related) or `userapp/models.py` (if user-related)
|
|
- Views/API: `device_interaction/views.py` or `userapp/views.py` → new ViewSet or APIView
|
|
- Serializers: `device_interaction/serializers.py` or `userapp/serializers.py` → new ModelSerializer
|
|
- URLs: Edit `device_interaction/urls.py` or `userapp/urls.py` → add path/route
|
|
- Async tasks: `device_interaction/scheduler.py` or new `tasks.py` file
|
|
- Tests: `device_interaction/tests.py` or `userapp/tests.py`
|
|
|
|
**New Component/Module (e.g., "Chat Analytics"):**
|
|
- Create new Django app: `python manage.py startapp analytics`
|
|
- Standard files: `models.py`, `views.py`, `serializers.py`, `urls.py`, `admin.py`, `apps.py`, `tests.py`
|
|
- Register in `qy_lty/settings.py` INSTALLED_APPS (line 43+)
|
|
- Include URLs in `qy_lty/urls.py` (line 49-60)
|
|
|
|
**Shared Utilities:**
|
|
- Common middleware/helpers: Add to `common/` directory
|
|
- Examples: `common/responses.py`, `common/swagger_utils.py`
|
|
- New integration (e.g., API client): Create in `common/` or within relevant app (e.g., `device_interaction/amap_api.py`)
|
|
|
|
**WebSocket Message Handler:**
|
|
- Edit `device_interaction/consumers.py:DeviceConsumer.receive()` (line 171+)
|
|
- Add new `elif message_type == 'new_type':` branch
|
|
- Call appropriate handler or `group_send()` to broadcast
|
|
|
|
**Serializer Customization:**
|
|
- Override `to_representation()` for custom output
|
|
- Override `to_internal_value()` for custom input processing
|
|
- Add `validate_<field>()` for field-specific validation
|
|
- Add `validate()` for cross-field validation
|
|
|
|
## Special Directories
|
|
|
|
**migrations/:**
|
|
- Purpose: Track database schema changes
|
|
- Generated: `python manage.py makemigrations`
|
|
- Applied: `python manage.py migrate`
|
|
- Committed: Yes (part of version control)
|
|
|
|
**.planning/codebase/:**
|
|
- Purpose: GSD (Generate Specification Documents) auto-generated codebase maps
|
|
- Generated: By `/gsd-map-codebase` orchestrator
|
|
- Committed: Yes (reference docs for other GSD commands)
|
|
- Contents: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md, INTEGRATIONS.md, STACK.md
|
|
|
|
**docs/:**
|
|
- Purpose: Human documentation
|
|
- Committed: Yes
|
|
- Auto-maintained: `修改记录.md` (change log, appended by developers after each commit)
|
|
|
|
**locale/:**
|
|
- Purpose: i18n translation catalogs
|
|
- Generated: `django-admin makemessages` (creates .po files)
|
|
- Compiled: `django-admin compilemessages` (creates .mo files)
|
|
- Committed: Yes (both .po and .mo)
|
|
|
|
**static/ & media/:**
|
|
- Purpose: Served files (CSS, JS, images; user uploads)
|
|
- Generated: No (user-managed)
|
|
- Committed: No (in .gitignore)
|
|
- Dev only: Yes (production uses CloudStorage/OSS)
|
|
|
|
## Management Commands
|
|
|
|
**Standard Django:**
|
|
```bash
|
|
python manage.py migrate # Apply database migrations
|
|
python manage.py makemigrations # Create new migration files
|
|
python manage.py createsuperuser # Create admin user
|
|
python manage.py shell # Interactive Python shell
|
|
python manage.py dbshell # Interactive database shell
|
|
```
|
|
|
|
**i18n:**
|
|
```bash
|
|
django-admin makemessages -l en # Extract translatable strings (English)
|
|
django-admin makemessages -l zh_HAns # Extract translatable strings (Simplified Chinese)
|
|
django-admin compilemessages # Compile .po to .mo files
|
|
```
|
|
|
|
**Custom Commands (if any):**
|
|
- Location: `<app>/management/commands/<command_name>.py`
|
|
- Run: `python manage.py <command_name>`
|
|
|
|
---
|
|
|
|
*Structure analysis: 2026-05-07*
|