WonderQ-Admin-UI/AGENTS.md

WonderQ-Admin-UI Agent 工作说明

项目定位

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

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

目录结构

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 和数据模型时先参考这里，再看后端仓库文档。

启动与构建

依赖安装：

yarn install

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

本地开发：

yarn dev

默认访问地址：

http://localhost:5602

本地联调要求：

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

类型检查与生产构建：

yarn build

构建产物预览：

yarn preview

默认预览端口为 5603。

测试流程

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

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、权限和生产后端配置在后端仓库维护。