# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目简介

Sun-Panel 是服务器/NAS 导航面板应用，前后端分离架构：

- **前端**：Vue 3 + TypeScript + Vite + Naive UI + Pinia
- **后端**：Go + Gin + GORM，支持 SQLite（默认）或 MySQL，可选 Redis

## 常用命令

### 前端

```bash
pnpm dev          # 启动开发服务器，端口 1002
pnpm build        # 生产构建（类型检查 + Vite 打包）
pnpm lint         # ESLint 检查
pnpm lint:fix     # 自动修复
pnpm type-check   # 仅 TypeScript 类型检查
```

### 后端

```bash
cd service
go run main.go    # 启动，默认端口 3002
```

### Docker 全量构建

```bash
docker build -t sun-panel .
```

## 架构要点

### 前后端通信

开发时，Vite 将 `/api/*` 和 `/uploads/*` 代理到 `http://127.0.0.1:3002`（由 `.env` 中 `VITE_APP_API_BASE_URL` 控制）。生产部署时前后端同端口，Go 直接 serve 静态文件。

### 前端分层

```
src/api/         → API 调用函数（按模块分：panel/ system/ 等）
src/store/       → Pinia 状态（auth/user/panel/admin/notice/moduleConfig/app）
src/views/       → 页面组件（home/login/exception）
src/components/  → UI 组件（apps/ common/ deskModule/）
src/utils/request/ → axios 封装，含 token 拦截器
src/hooks/       → Composition API（useTheme/useLanguage/useBasicLayout/useIconRender）
src/locales/     → 国际化（zh-CN.json / en-US.json）
```

### 后端分层

```
service/router/      → 路由注册，入口 A_ENTER.go
service/api/api_v1/  → Handler 层，中间件在 middleware/
service/lib/         → 业务逻辑（user/cache/monitor/siteFavicon 等）
service/models/      → GORM 模型
service/global/      → 全局变量（Db/Logger/Redis 等）
service/initialize/  → 启动初始化流程，入口 A_ENTER.go
```

后端每个子目录都以 `A_ENTER.go` 作为该模块的入口聚合文件。

### 路由分组（后端）

- `/system/*` — 登录/用户/系统设置，需 LoginInterceptor
- `/panel/*` — 面板数据/图标管理，需 LoginInterceptor
- `/openness/*` — 无需认证的公开接口

### 配置文件

后端使用 INI 格式配置，示例见 `service/assets/conf.example.ini`。关键字段：
- `database_drive`：`sqlite`（默认）或 `mysql`
- `cache_drive` / `queue_drive`：`memory`（默认）或 `redis`
- `source_path`：上传文件存储路径，默认 `./uploads`

## 开发注意

- 前端路径别名 `@` 指向 `src/`
- 提交前 Husky + lint-staged 会自动对 `.ts/.tsx/.vue` 运行 `eslint --fix`
- TypeScript 开启 `strict` 和 `noUnusedLocals`，避免引入 `any`
- 国际化新增文案需同时更新 `zh-CN.json` 和 `en-US.json`