292 lines
13 KiB
Markdown
292 lines
13 KiB
Markdown
# 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*
|