# WonderQ-Admin-UI Agent 工作说明

## 项目定位

WonderQ-Admin-UI 是独立的 WonderQ 后台管理前端，用于维护小程序/H5 前台的首页结构、目的地、线路商品、活动入口和客户需求线索。

当前项目是一个轻量单页后台应用，技术栈为 Vite + React + TypeScript + Tailwind CSS 4 + shadcn/ui 风格组件 + 普通 CSS。前端通过 `/api/admin/...` 调用后端管理接口，本地开发时由 Vite 代理到后端服务。

## 目录结构

```text
WonderQ-Admin-UI/
├─ AGENTS.md                 # Agent 项目规则
├─ README.md                 # 项目启动说明
├─ components.json           # shadcn/ui 组件配置
├─ docs/
│  ├─ README.md              # 文档索引
│  └─ admin-backend-plan.md  # 后台管理规划文档
├─ public/
│  └─ assets/
│     ├─ guizhou/            # 贵州目的地展示图
│     └─ source/             # 原始/通用静态素材与 manifest
├─ src/
│  ├─ App.tsx                # 后台主界面、页面状态、表单和业务 UI
│  ├─ api.ts                 # Admin API 类型、Token 管理和请求封装
│  ├─ components/
│  │  └─ ui/                 # 本地 shadcn/ui 风格基础组件
│  ├─ lib/
│  │  └─ utils.ts            # className 合并工具
│  ├─ main.tsx               # React 挂载入口
│  ├─ styles.css             # Tailwind 入口、设计变量、全局样式与响应式布局
│  └─ vite-env.d.ts          # Vite 类型声明
├─ index.html                # Vite HTML 入口
├─ package.json              # 脚本与依赖
├─ tsconfig.json             # TypeScript 严格模式配置
├─ vite.config.ts            # Vite/React/本地 API 代理配置
└─ yarn.lock                 # Yarn 依赖锁文件
```

## 模块分工

- `src/App.tsx`：集中实现登录页、侧边导航、结构维护、首页/目的地维护、商品维护、线索跟进、Toast 提示等后台 UI，并优先复用 `src/components/ui/` 基础组件。
- `src/api.ts`：定义 `Product`、`Destination`、`Lead`、`SiteConfig` 等接口类型，封装登录、商品、目的地、站点配置、线索、发布和重置接口。
- `src/components/ui/`：本地 shadcn/ui 风格组件目录，当前包含 Button、Card、Input、Textarea、Badge、Alert、Switch、NativeSelect、Separator 等基础组件。
- `src/lib/utils.ts`：封装 `clsx` + `tailwind-merge` 的 `cn` 工具。
- `src/styles.css`：Tailwind CSS 4 入口、设计变量、全局布局、后台工作台、表格/表单、商品编辑器、移动端适配等样式。
- `public/assets/`：前台/后台预览用静态图片资源，代码中保留 `/assets/...` 路径引用。
- `docs/`：后台规划与后续协作边界，涉及后端 API 和数据模型时先参考这里，再看后端仓库文档。

## 启动与构建

依赖安装：

```bash
yarn install
```

本仓库使用 Yarn 1 锁文件。Windows 本地构建依赖 Vite/Rolldown、Tailwind Oxide 和 lightningcss 的 native binding，`package.json` 中固定了对应 Windows 包；未完整验证前不要随意移除这些依赖。

本地开发：

```bash
yarn dev
```

默认访问地址：

```text
http://localhost:5602
```

本地联调要求：

- 后端 Admin API 默认运行在 `http://localhost:4000`。
- `vite.config.ts` 将 `/api` 代理到本地后端。
- `vite.config.ts` 同时接入 `@tailwindcss/vite` 和 `@/*` 路径别名。
- 如需改 API 地址，优先使用环境变量 `VITE_API_BASE_URL`，不要硬编码生产地址。

类型检查与生产构建：

```bash
yarn build
```

构建产物预览：

```bash
yarn preview
```

默认预览端口为 `5603`。

## 测试流程

当前 `package.json` 未配置独立测试脚本。提交前至少执行：

```bash
yarn build
```

该命令会先运行 `tsc --noEmit`，再执行 Vite 生产构建。涉及 UI 布局、交互或接口行为时，还需本地启动页面并手动验证关键流程。

## 部署规范

- 生产发布使用 `yarn build` 生成 `dist/`。
- `dist/` 可交给 Nginx、CDN 或静态托管服务部署。
- 生产环境 API 地址必须通过部署环境变量配置，不要提交 `.env`、`.env.local` 或任何包含密钥的配置。
- 后台接口、数据库、权限、发布/回滚能力属于后端仓库边界，本仓库只维护管理前端。

## 代码风格

- 使用 TypeScript 严格模式，新增代码必须有明确类型，避免 `any`。
- React 采用函数组件和 Hooks，不引入 class component。
- 遵循现有单文件轻量结构；未获授权前不要主动拆分大型组件或引入状态管理库。
- UI 图标优先复用 `lucide-react`。
- 通用按钮、输入框、卡片、提示、徽标、开关等基础控件优先复用 `src/components/ui/`，保持 shadcn/ui 风格一致。
- 样式优先沿用 `src/styles.css` 的设计变量、类名、色彩、间距和 6-10px 圆角习惯；避免绕过组件体系写一套重复按钮/表单样式。
- API 访问统一走 `src/api.ts` 的 `request` 封装，不在组件里重复拼接鉴权逻辑。
- 中文文案文件按 UTF-8 处理；修改前确认编辑器编码，避免造成乱码。

## 命名规范

- 组件、类型使用 PascalCase，例如 `ProductManager`、`SiteConfig`。
- 函数、变量使用 camelCase，例如 `getProducts`、`selectedId`。
- 联合类型字面量使用小写英文，例如 `"draft"`、`"published"`、`"leads"`。
- CSS class 沿用 kebab-case，例如 `.admin-shell`、`.product-table`。
- 组件文件命名沿用 shadcn/ui 习惯，基础组件放在 `src/components/ui/`，工具函数放在 `src/lib/`。
- API 类型与后端字段保持同名，避免在前端私自改字段语义。

## 开发准则

- 默认先读相关文件和现有模式，再修改。
- 只处理用户明确要求的范围，不额外加功能。
- 修改前确认是否涉及接口契约、登录鉴权、发布操作或静态资源路径。
- 不展示、不输出、不提交 Token、密码、密钥、真实客户手机号等敏感信息。
- 不新增依赖，除非用户明确授权并说明理由。
- 不提交 `node_modules/`、`dist/`、`.env`、`.env.local`、日志或覆盖率文件。
- 涉及删除、批量移动、重命名资源文件时必须先征得用户明确授权。

## 锁定文件与高风险区域

未经用户明确授权，不得改动：

- `.env`、`.env.local`、任何生产环境变量或密钥配置。
- `vite.config.ts` 中的代理、端口和构建配置。
- `tsconfig.json` 的严格类型配置。
- `package.json`、`yarn.lock` 的依赖与脚本。
- `src/api.ts` 的接口路径、Token 存储键、鉴权头和类型契约。
- `public/assets/` 下已被页面引用的图片资源和 `manifest.json`。
- `docs/admin-backend-plan.md` 中的后端规划，除非任务明确要求更新文档。

本仓库没有数据库配置文件；数据库、Prisma、权限和生产后端配置在后端仓库维护。