lty/qy_lty/.planning/codebase/STRUCTURE.md

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:

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:

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