Refactor code structure for improved readability and maintainability
This commit is contained in:
duanshuwen
22
AGENTS.md
22
AGENTS.md
@@ -4,7 +4,7 @@
|
||||
|
||||
WonderQ-Admin-UI 是独立的 WonderQ 后台管理前端，用于维护小程序/H5 前台的首页结构、目的地、线路商品、活动入口和客户需求线索。
|
||||
|
||||
当前项目是一个轻量单页后台应用，技术栈为 Vite + React + TypeScript + 普通 CSS。前端通过 `/api/admin/...` 调用后端管理接口，本地开发时由 Vite 代理到后端服务。
|
||||
当前项目是一个轻量单页后台应用，技术栈为 Vite + React + TypeScript + Tailwind CSS 4 + shadcn/ui 风格组件 + 普通 CSS。前端通过 `/api/admin/...` 调用后端管理接口，本地开发时由 Vite 代理到后端服务。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -12,6 +12,7 @@ WonderQ-Admin-UI 是独立的 WonderQ 后台管理前端，用于维护小程序
|
||||
WonderQ-Admin-UI/
|
||||
├─ AGENTS.md # Agent 项目规则
|
||||
├─ README.md # 项目启动说明
|
||||
├─ components.json # shadcn/ui 组件配置
|
||||
├─ docs/
|
||||
│ ├─ README.md # 文档索引
|
||||
│ └─ admin-backend-plan.md # 后台管理规划文档
|
||||
@@ -22,8 +23,12 @@ WonderQ-Admin-UI/
|
||||
├─ src/
|
||||
│ ├─ App.tsx # 后台主界面、页面状态、表单和业务 UI
|
||||
│ ├─ api.ts # Admin API 类型、Token 管理和请求封装
|
||||
│ ├─ components/
|
||||
│ │ └─ ui/ # 本地 shadcn/ui 风格基础组件
|
||||
│ ├─ lib/
|
||||
│ │ └─ utils.ts # className 合并工具
|
||||
│ ├─ main.tsx # React 挂载入口
|
||||
│ ├─ styles.css # 全局样式与响应式布局
|
||||
│ ├─ styles.css # Tailwind 入口、设计变量、全局样式与响应式布局
|
||||
│ └─ vite-env.d.ts # Vite 类型声明
|
||||
├─ index.html # Vite HTML 入口
|
||||
├─ package.json # 脚本与依赖
|
||||
@@ -34,9 +39,11 @@ WonderQ-Admin-UI/
|
||||
|
||||
## 模块分工
|
||||
|
||||
- `src/App.tsx`：集中实现登录页、侧边导航、结构维护、首页/目的地维护、商品维护、线索跟进、Toast 提示等后台 UI。
|
||||
- `src/App.tsx`：集中实现登录页、侧边导航、结构维护、首页/目的地维护、商品维护、线索跟进、Toast 提示等后台 UI，并优先复用 `src/components/ui/` 基础组件。
|
||||
- `src/api.ts`：定义 `Product`、`Destination`、`Lead`、`SiteConfig` 等接口类型，封装登录、商品、目的地、站点配置、线索、发布和重置接口。
|
||||
- `src/styles.css`：全局布局、后台工作台、表格/表单、商品编辑器、移动端适配等样式。
|
||||
- `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 和数据模型时先参考这里，再看后端仓库文档。
|
||||
|
||||
@@ -48,6 +55,8 @@ WonderQ-Admin-UI/
|
||||
yarn install
|
||||
```
|
||||
|
||||
本仓库使用 Yarn 1 锁文件。Windows 本地构建依赖 Vite/Rolldown、Tailwind Oxide 和 lightningcss 的 native binding，`package.json` 中固定了对应 Windows 包；未完整验证前不要随意移除这些依赖。
|
||||
|
||||
本地开发：
|
||||
|
||||
```bash
|
||||
@@ -64,6 +73,7 @@ http://localhost:5601
|
||||
|
||||
- 后端 Admin API 默认运行在 `http://localhost:4000`。
|
||||
- `vite.config.ts` 将 `/api` 代理到本地后端。
|
||||
- `vite.config.ts` 同时接入 `@tailwindcss/vite` 和 `@/*` 路径别名。
|
||||
- 如需改 API 地址，优先使用环境变量 `VITE_API_BASE_URL`，不要硬编码生产地址。
|
||||
|
||||
类型检查与生产构建：
|
||||
@@ -103,7 +113,8 @@ yarn build
|
||||
- React 采用函数组件和 Hooks，不引入 class component。
|
||||
- 遵循现有单文件轻量结构；未获授权前不要主动拆分大型组件或引入状态管理库。
|
||||
- UI 图标优先复用 `lucide-react`。
|
||||
- 样式优先沿用 `src/styles.css` 的类名、色彩、间距和 6-8px 圆角习惯。
|
||||
- 通用按钮、输入框、卡片、提示、徽标、开关等基础控件优先复用 `src/components/ui/`，保持 shadcn/ui 风格一致。
|
||||
- 样式优先沿用 `src/styles.css` 的设计变量、类名、色彩、间距和 6-10px 圆角习惯；避免绕过组件体系写一套重复按钮/表单样式。
|
||||
- API 访问统一走 `src/api.ts` 的 `request` 封装，不在组件里重复拼接鉴权逻辑。
|
||||
- 中文文案文件按 UTF-8 处理；修改前确认编辑器编码，避免造成乱码。
|
||||
|
||||
@@ -113,6 +124,7 @@ yarn build
|
||||
- 函数、变量使用 camelCase，例如 `getProducts`、`selectedId`。
|
||||
- 联合类型字面量使用小写英文，例如 `"draft"`、`"published"`、`"leads"`。
|
||||
- CSS class 沿用 kebab-case，例如 `.admin-shell`、`.product-table`。
|
||||
- 组件文件命名沿用 shadcn/ui 习惯，基础组件放在 `src/components/ui/`，工具函数放在 `src/lib/`。
|
||||
- API 类型与后端字段保持同名，避免在前端私自改字段语义。
|
||||
|
||||
## 开发准则
|
||||
|
||||
Reference in New Issue
Block a user