lty/qy-lty-admin/.planning/codebase/INTEGRATIONS.md

External Integrations

Analysis Date: 2026-05-07

APIs & External Services

qy_lty Backend (Django REST API):

• Primary backend for all business logic
• URL: Base configured via NEXT_PUBLIC_API_BASE_URL (default: http://localhost:8000/api)
• SDK/Client: Axios (custom instance with interceptors)
• Auth: Bearer token via Authorization: Bearer {token} header
• Primary modules consumed:
  • /api/v1/admin/login/ - User authentication
  • /api/v1/admin/logout/ - User logout
  • /ai/bots/ - AI model CRUD
  • /card/category/clothing/ - Outfit/clothing items
  • /card/category/props/ - Props/accessories
  • /card/category/home-decor/ - Home decoration items
  • /card/category/food/ - Food items
  • /music/songs/ - Song management
  • /dances/ - Dance content
  • /achievements/ - Achievement system
  • /affinity/ - Affinity/favorability system
  • /common/upload/ - File upload endpoint
  • /common/upload/info/ - File metadata retrieval

Request/Response Pattern:

// Axios configuration: lib/api/client.ts
const apiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: { 'Content-Type': 'application/json' }
})

// Request interceptor: auto-injects token
apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token')
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

// Response interceptor: handles 401 (redirect to /login)
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('auth_token')
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

Data Storage

Databases:

• No direct database connection from frontend
• Backend (qy_lty) manages all persistent data (PostgreSQL/MySQL presumed)
• Frontend uses in-memory mock data for fallback/demo scenarios only

File Storage:

• Backend-managed via /common/upload/ endpoint
• Upload types supported:
  • Images (JPEG, PNG, GIF, WebP) - max 10MB
  • Avatars (JPEG, PNG) - max 2MB
  • Audio (MP3, WAV, OGG, AAC, FLAC, WMA, M4A) - max 20MB
  • Animations (MP4, AVI, MOV, WMV, FLV, GIF, Lottie JSON) - max 50MB
  • General files - multipart/form-data
• Upload library: File API (FormData) via Axios
• Progress tracking: onUploadProgress callback support

Caching:

• Browser localStorage for:
  • auth_token - Authentication token (auto-removed on 401)
  • is_superuser - Superuser flag
  • user_role - User role string (used for permission checks)
  • isLoggedIn - Session state flag
• No server-side caching configured (Redis presumed in backend qy_lty)

Authentication & Identity

Auth Provider:

• Custom implementation via qy_lty backend
• Backend OAuth/token system: admin token key format admin_token:{token} (in Redis)

Login Flow:

1. POST /api/v1/admin/login/ with email + password
2. Backend returns: { success, code, data: { token, is_superuser?, role? }, message }
3. Frontend stores token in localStorage + cookies (7-day expiry)
4. All subsequent requests include Authorization: Bearer {token}
5. On 401 response: clear tokens, redirect to /login

Token Storage:

• Primary: localStorage.auth_token (checked on every request)
• Secondary: js-cookie cookie auth_token (7-day expiry) for middleware access
• Logout clears both storages

Role-Based Access:

• Roles stored in localStorage: user_role
• Permission matrix defined in lib/permissions.ts
• Supported roles: 超级管理员, 内容管理员, AI模型管理员, 卡牌管理员, 查看者, 管理员
• Module-level access control via hasPermission() and hasPathPermission() functions

Protected Routes:

• Middleware: middleware.ts checks for token on protected paths
• Protected paths: /, /dashboard, /users, /roles, /ai-models, /outfits, /props, /songs, /settings
• Public paths: /login, /register, /forgot-password (no token required)

Monitoring & Observability

Error Tracking:

• Not detected - errors logged to console only
• Error messages mapped in lib/api/error-handler.ts
• Toast notifications via Sonner for user-facing errors

Logs:

• Console logging (development-focused)
• Request/response logging in Axios interceptors (logs token status, URLs, headers, status codes)
• Client-side logging only (no centralized log aggregation)

CI/CD & Deployment

Hosting:

• Docker containerization: Dockerfile (multi-stage build)
• Runtime: Node.js 22.10.0 Alpine Linux
• Port: 3000
• Command: yarn start (runs Next.js production server)

CI Pipeline:

• Not detected in codebase (likely external to this repo)

Build Output:

• Format: Next.js standalone (self-contained, no node_modules in runtime image)
• Files included: .next/standalone/, public/
• Size optimization: devDependencies not included in runner stage

Environment Configuration

Required env vars:

• NEXT_PUBLIC_API_BASE_URL - Backend API base URL (must be public, prefixed with NEXT_PUBLIC_)
  • Example: http://localhost:8000/api (development), https://api.production.com/api (production)

Optional env vars:

• NODE_ENV - Set to production in Docker runner stage
• .env.local - Overrides all other env files (gitignored)
• .env.development - Dev-specific overrides
• .env.production - Production-specific overrides

Secrets location:

• Authentication tokens: browser localStorage + cookies
• No API keys or credentials hardcoded in source
• Environment variable NEXT_PUBLIC_API_BASE_URL is the sole configuration bridge to backend

Webhooks & Callbacks

Incoming:

• None detected
• Backend (qy_lty) may have webhooks, but frontend is purely client-side consumer

Outgoing:

• None detected
• All communication is request-response (REST API calls to qy_lty)

Cross-Repo Dependencies

qy_lty Backend (Sibling Repo):

• Location: C:\Users\admin\Desktop\Lila-Server\qy_lty\ (Django)
• Contract: /api/v1/admin/ endpoint suite
• Shared concerns: Token format (admin_token:{token}), role names, permission structure
• Change coordination required: Both docs/修改记录.md files must be updated when API contracts change

Notes:

• Frontend is tightly coupled to backend API schema (no API versioning detected)
• Backend controls: authentication, authorization, data persistence, file storage
• Frontend is purely a UI/UX layer consuming backend HTTP APIs

---

Integration audit: 2026-05-07