feat: add WonderQ admin UI

2026-06-30 12:02:44 +08:00
parent 282b90b622
commit 50e9b32806
160 changed files with 4893 additions and 137 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,140 @@
+# WonderQ-Admin-UI Agent 工作说明
+
+## 项目定位
+
+WonderQ-Admin-UI 是独立的 WonderQ 后台管理前端，用于维护小程序/H5 前台的首页结构、目的地、线路商品、活动入口和客户需求线索。
+
+当前项目是一个轻量单页后台应用，技术栈为 Vite + React + TypeScript + 普通 CSS。前端通过 `/api/admin/...` 调用后端管理接口，本地开发时由 Vite 代理到后端服务。
+
+## 目录结构
+
+```text
+WonderQ-Admin-UI/
+├─ AGENTS.md                 # Agent 项目规则
+├─ README.md                 # 项目启动说明
+├─ docs/
+│  ├─ README.md              # 文档索引
+│  └─ admin-backend-plan.md  # 后台管理规划文档
+├─ public/
+│  └─ assets/
+│     ├─ guizhou/            # 贵州目的地展示图
+│     └─ source/             # 原始/通用静态素材与 manifest
+├─ src/
+│  ├─ App.tsx                # 后台主界面、页面状态、表单和业务 UI
+│  ├─ api.ts                 # Admin API 类型、Token 管理和请求封装
+│  ├─ main.tsx               # React 挂载入口
+│  ├─ styles.css             # 全局样式与响应式布局
+│  └─ 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/api.ts`：定义 `Product`、`Destination`、`Lead`、`SiteConfig` 等接口类型，封装登录、商品、目的地、站点配置、线索、发布和重置接口。
+- `src/styles.css`：全局布局、后台工作台、表格/表单、商品编辑器、移动端适配等样式。
+- `public/assets/`：前台/后台预览用静态图片资源，代码中保留 `/assets/...` 路径引用。
+- `docs/`：后台规划与后续协作边界，涉及后端 API 和数据模型时先参考这里，再看后端仓库文档。
+
+## 启动与构建
+
+依赖安装：
+
+```bash
+yarn install
+```
+
+本地开发：
+
+```bash
+yarn dev
+```
+
+默认访问地址：
+
+```text
+http://localhost:5601
+```
+
+本地联调要求：
+
+- 后端 Admin API 默认运行在 `http://localhost:4000`。
+- `vite.config.ts` 将 `/api` 代理到本地后端。
+- 如需改 API 地址，优先使用环境变量 `VITE_API_BASE_URL`，不要硬编码生产地址。
+
+类型检查与生产构建：
+
+```bash
+yarn build
+```
+
+构建产物预览：
+
+```bash
+yarn preview
+```
+
+默认预览端口为 `5602`。
+
+## 测试流程
+
+当前 `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/styles.css` 的类名、色彩、间距和 6-8px 圆角习惯。
+- API 访问统一走 `src/api.ts` 的 `request` 封装，不在组件里重复拼接鉴权逻辑。
+- 中文文案文件按 UTF-8 处理；修改前确认编辑器编码，避免造成乱码。
+
+## 命名规范
+
+- 组件、类型使用 PascalCase，例如 `ProductManager`、`SiteConfig`。
+- 函数、变量使用 camelCase，例如 `getProducts`、`selectedId`。
+- 联合类型字面量使用小写英文，例如 `"draft"`、`"published"`、`"leads"`。
+- CSS class 沿用 kebab-case，例如 `.admin-shell`、`.product-table`。
+- 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、权限和生产后端配置在后端仓库维护。