462498660e
- Updated styles in src/styles.css for better responsiveness and layout adjustments. - Added new CSS classes for edit drawer and item rail components. - Introduced animations for drawer transitions. - Created new types in src/types/admin.ts for better type safety in admin features. - Modified vite.config.ts to change server port and enable strict port settings for development.
153 lines
6.9 KiB
Markdown
153 lines
6.9 KiB
Markdown
# 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、权限和生产后端配置在后端仓库维护。
|