# CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指导。

## 项目概述

**洛天依应用管理后台 (qy-lty-admin)** —— 基于 **Next.js 15 (App Router) + React 19 + TypeScript** 构建的 Web 管理后台，搭配 Tailwind CSS + Radix UI / shadcn 风格组件库。

后端 API 由独立项目 [qy_lty](../qy_lty/) 提供（Django，路径 `C:\Users\admin\Desktop\Lila-Server\qy_lty`），通过 `NEXT_PUBLIC_API_BASE_URL` 配置接入，主要使用 `/api/v1/admin/` 模块。

## 开发命令

```bash
# 安装依赖（Dockerfile 用 yarn + 淘宝镜像源；本地 npm/pnpm 也可）
npm install

# 开发模式
npm run dev          # 默认 http://localhost:3000

# 生产构建（standalone 输出）
npm run build && npm run start

# 类型检查
npm run lint
```

环境变量（`.env.local`）：
- `NEXT_PUBLIC_API_BASE_URL` —— 后端 qy_lty 服务地址

## 架构要点

### 技术栈
| 类别 | 选型 |
|------|------|
| 框架 | Next.js 15.2.4（App Router、standalone 输出）|
| 语言 | TypeScript 5、React 19 |
| 样式 | Tailwind CSS 3.4 + `tailwindcss-animate` |
| 组件 | Radix UI + shadcn 风格封装（[components/ui/](components/ui/)）|
| HTTP 客户端 | Axios（含请求/响应拦截器）|
| 表单 | React Hook Form + Zod |
| 图表 | Recharts |
| 通知 | Sonner + Radix Toast |

### 路由与页面（App Router）
- `app/page.tsx` —— 仪表盘首页
- `app/login/`、`app/register/`、`app/forgot-password/` —— 账户流
- 业务模块（按权限分组）：
  - **AI 管理**：`/ai-model`
  - **内容管理**：`/outfits`、`/props`、`/home-decor`、`/food`、`/songs`、`/dances`、`/achievements`、`/affinity`
  - **系统管理**：`/users`、`/permissions`、`/settings`

### 鉴权与权限
- 角色信息存于 `localStorage.user_role`
- 模块权限矩阵定义在 [lib/permissions.ts](lib/permissions.ts)
- 侧边栏 [components/sidebar.tsx](components/sidebar.tsx) 客户端按角色过滤可见菜单
- 路由保护中间件：[middleware.ts](middleware.ts)

### API 集成
- Axios 实例 + 拦截器统一注入 token
- 所有请求走 `NEXT_PUBLIC_API_BASE_URL + /api/v1/admin/...`
- 后端鉴权 token 复用 qy_lty 的 Redis token 体系（admin token key 为 `admin_token:{token}`）

## 跨仓库联动

本仓库**依赖** [qy_lty](../qy_lty/) 后端的 `/api/v1/admin/` 接口。修改任何接口契约（请求/响应结构、字段、URL）的改动**必须同时**：
1. 在 [qy_lty/docs/修改记录.md](../qy_lty/docs/修改记录.md) 记录服务端改动
2. 在 [docs/修改记录.md](docs/修改记录.md) 记录前端配套改动
3. 两端条目相互引用对方的同期条目

## 项目修改记录规则（重要 — 自动执行）

每次对本仓库代码做出改动后，**必须**在同一会话内把变更追加到 [docs/修改记录.md](docs/修改记录.md) **顶部**（最新在最前），不要等用户提醒。条目格式遵循该文件头部"修改格式说明"约定：

```
### [日期] 修改简述

- **文件路径**: 相对于项目根目录的文件路径
- **修改类型**: 新增 / 修改 / 删除 / 重构 / 修复Bug
- **修改内容**: 具体修改了什么
- **修改原因**: 为什么要做这个修改
```

### `qy-lty-admin` 与 `qy_lty` 是独立项目，各自维护

- `qy-lty-admin/docs/修改记录.md` —— **仅**记录管理后台前端（本仓库）改动
- `qy_lty/docs/修改记录.md` —— **仅**记录服务端改动

跨项目联动改动：**两端各写一条**，相互引用对方的修改记录条目，不要混在同一条记录里。

### 适用范围

- 业务代码、配置、`package.json`、Dockerfile、CI、文档结构性改动 → **必须**记录
- 单纯的 typo 修复、注释微调 → 可省略
- 临时调试脚本、`.gitignore` 中文件、本地实验文件 → 不记录

## 注意事项

- **语言**：用户偏好**中文**沟通；注释、commit message 用中文
- **包管理器**：项目同时存在 `package-lock.json` 和 `pnpm-lock.yaml`；Dockerfile 用 yarn + 淘宝镜像源。本地开发任选其一即可，但**不要混用**导致 lock 文件冲突
- **shadcn 组件**：[components/ui/](components/ui/) 下的组件是 shadcn 复制粘贴风格（不是 npm 包），可以直接修改源码而不破坏第三方升级

## 相关文档

- [README.md](README.md) —— 完整功能概览、权限矩阵、部署指南
- [docs/修改记录.md](docs/修改记录.md) —— 本仓库变更历史（强制维护）
- [../qy_lty/CLAUDE.md](../qy_lty/CLAUDE.md) —— 后端项目上下文与跨仓库联动规则