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

Codebase Structure

Analysis Date: 2026-05-07

Directory Layout

qy-lty-admin/
├── app/                          # Next.js App Router pages & layouts
│   ├── layout.tsx                # Root layout with metadata
│   ├── page.tsx                  # Dashboard homepage
│   ├── login/page.tsx            # Login page
│   ├── register/page.tsx         # Registration page
│   ├── forgot-password/page.tsx  # Password reset page
│   ├── ai-model/page.tsx         # AI Model management
│   ├── outfits/                  # Outfit content module
│   │   ├── page.tsx              # List view
│   │   ├── [id]/page.tsx         # Detail view
│   │   ├── edit/[id]/page.tsx    # Edit form
│   │   └── loading.tsx           # Loading skeleton
│   ├── props/                    # Props module (same structure as outfits)
│   ├── home-decor/               # Home decor module
│   ├── food/                     # Food module
│   ├── songs/                    # Songs module
│   ├── dances/                   # Dances module
│   ├── achievements/             # Achievements module
│   ├── affinity/                 # Affinity/favorability module
│   ├── users/                    # User management module
│   ├── permissions/              # Permissions management module
│   ├── settings/                 # System settings module
│   └── globals.css               # Global Tailwind + custom styles
├── components/                   # Reusable React components
│   ├── ui/                       # Shadcn-style primitive components (copy-paste)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   ├── input.tsx
│   │   ├── label.tsx
│   │   ├── table.tsx
│   │   ├── tabs.tsx
│   │   ├── select.tsx
│   │   ├── form.tsx
│   │   ├── alert-dialog.tsx
│   │   └── ... (30+ primitive components)
│   ├── outfits/                  # Outfit feature components
│   │   ├── OutfitsList.tsx
│   │   ├── OutfitsTable.tsx
│   │   ├── AddOutfitDialog.tsx
│   │   └── OutfitDetailCard.tsx
│   ├── songs/                    # Songs feature components
│   ├── dances/                   # Dances feature components
│   ├── food/                     # Food feature components
│   ├── home-decor/               # Home decor feature components
│   ├── props/                    # Props feature components
│   ├── affinity/                 # Affinity feature components
│   ├── achievements/             # Achievements feature components
│   ├── permissions/              # Permissions feature components
│   ├── users/                    # Users feature components
│   ├── sidebar.tsx               # Main navigation sidebar (client)
│   ├── dashboard-shell.tsx       # Layout wrapper with permission checks (client)
│   ├── dashboard-header.tsx      # Page header component
│   ├── overview.tsx              # Dashboard overview chart
│   ├── recent-activity.tsx       # Recent activity feed
│   ├── stat-card.tsx             # KPI stat card
│   ├── delete-confirmation-dialog.tsx
│   ├── publish-confirmation-dialog.tsx
│   ├── theme-provider.tsx
│   └── add-outfit-dialog.tsx     # Shared modal for outfit creation
├── lib/                          # Utilities, types, API clients
│   ├── api/
│   │   ├── client.ts             # Axios instance + interceptors + interfaces
│   │   ├── auth.ts               # Login, logout, token management
│   │   ├── outfits.ts            # Outfit CRUD operations
│   │   ├── props.ts              # Props CRUD operations
│   │   ├── songs.ts              # Songs CRUD operations
│   │   ├── dances.ts             # Dances CRUD operations
│   │   ├── food.ts               # Food CRUD operations
│   │   ├── home-decor.ts         # Home decor CRUD operations
│   │   ├── achievements.ts       # Achievements CRUD operations
│   │   ├── affinity.ts           # Affinity system API
│   │   ├── ai-models.ts          # AI model management
│   │   ├── users.ts              # User management
│   │   ├── roles.ts              # Role/permission management
│   │   ├── error-handler.ts      # Centralized error handling
│   │   ├── adapters.ts           # Response schema mappers
│   │   ├── types.ts              # Shared API type definitions
│   │   ├── token-debug.ts        # Token debugging utilities
│   │   ├── card.ts               # Card-related API
│   │   └── index.ts              # Export barrel
│   ├── permissions.ts            # RBAC matrix + permission utilities
│   └── utils.ts                  # Utility functions (Tailwind cn)
├── hooks/                        # Custom React hooks
│   ├── use-mobile.tsx            # Mobile breakpoint detection hook
│   └── use-toast.ts              # Toast notification hook
├── middleware.ts                 # Next.js route protection middleware
├── public/                       # Static assets
├── styles/                       # Additional stylesheets (if any)
├── package.json                  # Dependencies & scripts
├── tsconfig.json                 # TypeScript configuration
├── tailwind.config.ts            # Tailwind CSS configuration
├── postcss.config.mjs            # PostCSS configuration
├── next.config.mjs               # Next.js configuration
├── Dockerfile                    # Docker build (yarn + Taobao mirror)
├── docker-compose.yml            # Local dev Docker Compose
├── README.md                     # Project overview & permissions matrix
├── CLAUDE.md                     # Codebase instructions for Claude
└── docs/
    └── 修改记录.md              # Change log (Chinese)

Directory Purposes

app/:

• Purpose: Next.js App Router pages and layouts; each module has a folder with page.tsx + optional nested routes
• Contains: Page components ("use client"), form pages, dynamic routes with [id]
• Key files: page.tsx (list), [id]/page.tsx (detail), edit/[id]/page.tsx (edit form), loading.tsx (skeleton)

components/:

• Purpose: Reusable React components organized by feature
• Contains: UI primitives (components/ui/), feature-specific components (components/[feature]/), layout components (sidebar, shell)
• Key pattern: Feature folders mirror app module structure; components within are sub-components (no subfolders unless complex)

components/ui/:

• Purpose: Shadcn-style copy-paste UI primitives
• Contains: 30+ Base UI components (Button, Card, Dialog, Form, Table, Tabs, Select, etc.)
• Note: These are copied into the repo, not npm packages; safe to modify directly

lib/api/:

• Purpose: HTTP client and API communication layer
• Contains: Axios singleton instance, interceptors, module-specific API functions, response adapters, type definitions
• Pattern: One file per backend module (outfits.ts, songs.ts, etc.) + shared client.ts

lib/:

• Purpose: Shared utilities, types, configuration
• Contains: permissions.ts (RBAC logic), utils.ts (Tailwind helpers), api/ subfolder

hooks/:

• Purpose: Custom React hooks
• Contains: use-mobile (responsive detection), use-toast (notification system)

middleware.ts:

• Purpose: Next.js request middleware for route protection
• Functionality: Checks Cookie auth_token; redirects to /login if missing; whitelists public routes

public/:

• Purpose: Static assets (images, icons, etc.)

styles/:

• Purpose: Additional CSS if needed (most styling via Tailwind in components)

Key File Locations

Entry Points:

• app/layout.tsx: Root layout (metadata only)
• app/page.tsx: Dashboard homepage (stats, charts, links)
• app/login/page.tsx: Authentication entry point
• middleware.ts: Route protection middleware

Configuration:

• next.config.mjs: Next.js config (standalone output)
• tsconfig.json: TypeScript strict mode
• tailwind.config.ts: Tailwind CSS theme + animations
• postcss.config.mjs: PostCSS with Tailwind + autoprefixer
• .env.local: Environment variables (API_BASE_URL)

Core Logic:

• lib/permissions.ts: Role-based access control matrix & utilities
• lib/api/client.ts: Axios instance with auth/error interceptors
• components/dashboard-shell.tsx: Permission-checking layout wrapper
• components/sidebar.tsx: Role-filtered navigation menu

Authentication:

• lib/api/auth.ts: Login, logout, token persistence
• middleware.ts: Route-level token validation

Testing:

• No test files detected; testing not yet set up

Naming Conventions

Files:

• Page components: page.tsx (App Router standard)
• Feature pages: /app/[module]/page.tsx (e.g., app/outfits/page.tsx)
• Dynamic routes: /app/[module]/[id]/page.tsx (e.g., app/outfits/[id]/page.tsx)
• Layout files: layout.tsx
• Loading states: loading.tsx
• API modules: /lib/api/[feature].ts (e.g., lib/api/outfits.ts)
• Component files: PascalCase (e.g., OutfitsList.tsx, AddOutfitDialog.tsx)
• Hook files: use-[name].ts (e.g., use-mobile.tsx)

Directories:

• App modules: kebab-case (e.g., /app/ai-model, /app/home-decor, /app/forgot-password)
• Component folders: kebab-case for feature groups, ui for primitives
• API folder: All in lib/api/ (no nested folders)

Functions:

• API functions: camelCase, verb-first (e.g., getOutfits(), createOutfit(), updateOutfit())
• Utility functions: camelCase (e.g., hasPermission(), getUserRole())
• Components: PascalCase (e.g., DashboardShell, Sidebar, OutfitsList)
• Hooks: camelCase with use prefix (e.g., useMobile, useToast)

Variables/Constants:

• Type definitions: PascalCase (e.g., Outfit, RoleName, ApiResponse)
• Constants: UPPER_SNAKE_CASE (e.g., API_BASE_URL, PERMISSION_MATRIX)
• Local variables: camelCase (e.g., outfits, isLoading, userRole)

Routes:

• Module routes: kebab-case URLs (e.g., /ai-model, /home-decor, /forgot-password)
• Dynamic routes: [paramName] (e.g., /outfits/[id], /dances/[id]/edit)

Where to Add New Code

New Feature Module (e.g., New Content Type):

1. Page component: Create app/[module-name]/page.tsx

   • Wrap with DashboardShell
   • Import feature components from components/[module-name]/
   • Call API functions from lib/api/[module-name].ts

2. API client: Create lib/api/[module-name].ts

   • Export get[Feature]s(), get[Feature](), create[Feature](), update[Feature](), delete[Feature]()
   • Use apiClient.get/post/put/delete() from lib/api/client.ts
   • Include adapter function to map backend response to frontend type
   • Export types or import from lib/api/types.ts

3. Components: Create components/[module-name]/ folder

   • List component (e.g., [Feature]List.tsx)
   • Detail/edit component
   • Dialog/modal for creation
   • Table component if displaying tabular data

4. Permission matrix: Add to lib/permissions.ts

   • Add module key to PermissionModule type
   • Add module to relevant roles in PERMISSION_MATRIX
   • Add path mapping in getModuleFromPath()

5. Sidebar: Update components/sidebar.tsx

   • Add menu item to appropriate section (AI Admin, Content Admin, or System Admin)
   • Use lucide-react icon

6. Middleware: Update middleware.ts

   • Add route to protectedPaths array if requiring auth

New Component:

• Location: components/[feature-name]/[ComponentName].tsx
• Import from UI primitives: components/ui/button.tsx, etc.
• Use React Hook Form for forms
• Use icons from lucide-react
• Mark as "use client" if using hooks/state

New Utility Function:

• Location: lib/utils.ts (for generic utilities) or lib/api/[module].ts (for API helpers)
• Type everything with TypeScript
• Export from lib/api/index.ts if API-related

New Hook:

• Location: hooks/use-[name].ts
• Follow React hook naming convention (use- prefix)

Special Directories

components/ui/:

• Purpose: Shadcn-style primitives (Button, Card, Dialog, Form, Input, etc.)
• Generated: No (manually copied from shadcn/ui)
• Committed: Yes (safe to modify without breaking npm upgrades)
• Note: Each file is a single component; complex components like Dialog may have sub-exports

public/:

• Purpose: Static assets served at root level
• Generated: No
• Committed: Yes

node_modules/:

• Purpose: Installed dependencies
• Generated: Yes (by npm/pnpm/yarn)
• Committed: No (.gitignore)

.next/:

• Purpose: Next.js build output
• Generated: Yes (by npm run build)
• Committed: No (.gitignore)

lib/api/:

• Purpose: All API communication in one folder for easy discovery
• Generated: No (hand-written)
• Committed: Yes
• Note: No subfolders; keep flat for single-module-per-file pattern

---

Structure analysis: 2026-05-07