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/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,7 @@
+# WonderQ-Admin-UI 文档
+
+本目录存放后台管理前端相关文档。
+
+- `admin-backend-plan.md`：从原 MiniAPP 迁出的后台管理规划，保留管理模块、页面能力和与后端 API 的协作边界。
+
+后端 API 文档位于 `D:\www\znkj\WonderQ-Admin\docs`。
--- a/docs/admin-backend-plan.md
+++ b/docs/admin-backend-plan.md
@@ -0,0 +1,404 @@
+# H5 后台管理系统规划
+
+## 目标
+
+为当前鸿鹄逸游 H5 项目建设一套可真实上线维护的后台系统，让运营人员可以管理首页内容、目的地、线路产品、活动专题、客户需求、订单线索、消息和客服配置，而不是继续依赖改代码发布。
+
+当前 H5 主要是一个静态 Vite + React 应用：
+
+- 首页配置来自 `src/content.ts`：轮播、目的地、主题卡、线路分区、底部 CTA。
+- 线路产品来自 `src/generated-products.json`：48 条产品卡片。
+- 目的地搜索、活动页、需求表单、消息、订单、客服经理等流程目前集中写在 `src/App.tsx`。
+- 图片资源在 `public/assets/source`，约 115 个文件。
+
+后台建设的核心不是简单加一个管理页面，而是把这些静态内容拆成稳定的数据模型，并提供发布、审核、回滚、权限、日志和运维能力。
+
+## 推荐架构
+
+### 代码组织
+
+建议从单一前端项目演进为 TypeScript monorepo：
+
+```text
+apps/
+  h5/          # 当前 Vite React H5，可从现有 src/ 迁移
+  admin/       # 后台管理端，React + Ant Design Pro 或 shadcn/ui
+  api/         # 后端 API，NestJS 或 Fastify
+packages/
+  shared/      # 共享类型、校验 schema、接口 DTO
+  config/      # eslint/tsconfig 等公共配置
+```
+
+保守可落地方案：
+
+- 前台 H5：继续 Vite + React，先只改数据来源。
+- 后台 Admin：React + Ant Design Pro。原因是后台表格、筛选、表单、权限、布局成熟，开发快。
+- API：NestJS + Prisma。原因是 TypeScript 体系一致，权限、模块化、OpenAPI、测试更规整。
+- 数据库：PostgreSQL。
+- 缓存/队列：Redis，先用于发布缓存、短信/通知任务、操作频控。
+- 文件存储：阿里 OSS、腾讯 COS 或 S3 兼容对象存储。
+- 部署：Docker + Nginx + CDN，后续可上云托管或 Kubernetes。
+
+### 服务边界
+
+```mermaid
+flowchart LR
+  H5["H5 前台"] --> API["Public API"]
+  Admin["后台管理端"] --> AdminAPI["Admin API"]
+  API --> DB[("PostgreSQL")]
+  AdminAPI --> DB
+  AdminAPI --> OSS["对象存储"]
+  AdminAPI --> Redis[("Redis")]
+  CDN["CDN"] --> H5
+  CDN --> OSS
+```
+
+## 后台功能模块
+
+### 1. 工作台
+
+- 今日新增需求、待跟进需求、待确认订单、上架线路数。
+- 最近发布记录、失败任务、异常日志。
+- 快捷入口：新建线路、新建活动、发布首页、导出需求。
+
+### 2. 首页装修
+
+对应当前 `src/content.ts`。
+
+- 轮播管理：图片、标题、副标题、跳转类型、排序、上下架。
+- 锚点分类：探索世界、主题甄选、精选线路、一生一次、鸿鹄稀缺。
+- 目的地宫格：名称、图片、跳转关键词、排序、是否推荐。
+- 主题卡片：主题名、封面、关联线路或活动专题。
+- 线路分区：分区标题图、分区名称、展示线路、排序规则。
+- 底部 CTA：权益卡、公众号、目的地搜索、需求表单等入口。
+- 页脚与品牌图：图片、服务承诺、备案信息。
+- 预览与发布：草稿预览、定时发布、回滚上一版。
+
+### 3. 线路产品管理
+
+对应当前 `src/generated-products.json` 和产品详情页。
+
+- 基础信息：标题、副标题、目的地、产品类型、价格、起价单位、标签。
+- 封面与图集：列表图、详情头图、行程图片。
+- 详情内容：特色、玩法、美食、行程日程、费用包含/不含、预订须知。
+- 售卖配置：上架状态、推荐权重、活动归属、库存/席位说明。
+- 搜索配置：关键词、别名、目的地关联、主题标签。
+- SEO/分享：分享标题、描述、海报图。
+- 批量能力：导入、导出、批量上下架、批量改标签。
+
+### 4. 目的地管理
+
+对应当前首页目的地、目的地搜索页和搜索别名逻辑。
+
+- 国家/城市/地区层级。
+- 热门目的地、出境/国内分类。
+- 搜索别名：例如 `马代 -> 马尔代夫`、`内蒙 -> 内蒙古`。
+- 目的地封面图、推荐线路、活动专题绑定。
+- 排序和上下架。
+
+### 5. 活动专题管理
+
+对应当前端午甄选、早鸟尊享、鸿鹄逸游等活动页。
+
+- 专题标题、封面、介绍文案、活动时间。
+- 关联线路列表。
+- CTA：提交需求、联系客服、跳转线路。
+- 发布状态：草稿、待审核、已发布、已下线。
+- 合规文案：例如活动免责声明。
+
+### 6. 客户需求管理
+
+对应当前 `DemandPage`，上线后这是最重要的转化入口。
+
+- 表单字段：目的地、手机号、出行时间、预算、人数、备注、来源页面、来源线路。
+- 线索状态：新建、已分配、已联系、方案中、已成交、无效。
+- 客户经理分配：手动分配、自动轮询分配。
+- 跟进记录：电话、微信、备注、下次提醒。
+- 防刷：手机号频控、验证码、IP 风控、黑名单。
+- 导出：Excel/CSV，按时间、状态、顾问筛选。
+
+### 7. 客户与订单管理
+
+对应当前消息、订单中心的真实业务化。
+
+- 客户档案：手机号、姓名、微信、偏好、历史需求。
+- 订单/方案：关联客户、线路、顾问、出行时间、人数、报价、状态。
+- 状态流转：需求单 -> 方案 -> 合同/支付 -> 出行中 -> 已完成/售后。
+- 附件：合同、方案 PDF、发票、签证材料。
+- 订单备注和操作日志。
+
+### 8. 消息与客服配置
+
+- 后台通知：需求分配、订单状态变化、发布失败。
+- 前台消息：活动通知、顾问消息、订单提醒。
+- 客服入口：在线联系、电话、服务时间、企业微信/IM 配置。
+- 短信：验证码、需求提交确认、顾问跟进提醒。
+
+### 9. 媒体库
+
+- 图片上传、裁剪、压缩、WebP 转换。
+- 图片分组：轮播、目的地、线路、活动、品牌。
+- 文件引用关系：防止删除正在使用的图片。
+- CDN URL、缩略图、多尺寸版本。
+
+### 10. 权限与审计
+
+- 角色：超级管理员、运营、产品、客服主管、客户经理、只读审计。
+- 权限粒度：菜单权限、按钮权限、数据范围权限。
+- 审核流：重要内容先提交审核再发布。
+- 操作日志：谁在什么时候改了什么，从什么值改到什么值。
+- 登录安全：强密码、二次验证可选、登录 IP 记录。
+
+## 核心数据模型
+
+第一期建议覆盖这些表：
+
+| 表 | 用途 |
+| --- | --- |
+| `admin_users` | 后台用户 |
+| `roles` / `permissions` | RBAC 权限 |
+| `media_assets` | 图片和文件资源 |
+| `site_versions` | 首页/站点配置发布版本 |
+| `home_sections` | 首页模块配置 |
+| `hero_slides` | 首页轮播 |
+| `destinations` | 目的地 |
+| `destination_aliases` | 搜索别名 |
+| `themes` | 主题甄选 |
+| `products` | 线路产品 |
+| `product_images` | 产品图片 |
+| `product_itineraries` | 行程日程 |
+| `product_fee_items` | 费用说明 |
+| `campaigns` | 活动专题 |
+| `campaign_products` | 专题与线路关联 |
+| `leads` | 客户需求/线索 |
+| `lead_followups` | 跟进记录 |
+| `customers` | 客户档案 |
+| `orders` | 订单/方案 |
+| `messages` | 前台消息 |
+| `audit_logs` | 操作审计 |
+
+### 示例：产品表
+
+```sql
+products (
+  id uuid primary key,
+  title text not null,
+  subtitle text,
+  destination_id uuid,
+  price_amount integer,
+  price_unit varchar(20),
+  tags text[],
+  cover_asset_id uuid,
+  summary text,
+  status varchar(20), -- draft, published, archived
+  sort_weight integer default 0,
+  published_at timestamptz,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+### 示例：线索表
+
+```sql
+leads (
+  id uuid primary key,
+  destination text,
+  phone varchar(30) not null,
+  travel_date date,
+  people_count integer,
+  budget_min integer,
+  budget_max integer,
+  source_page text,
+  source_product_id uuid,
+  status varchar(30) not null,
+  assigned_user_id uuid,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## API 设计
+
+### Public API 给 H5 使用
+
+- `GET /api/public/site-config`：首页配置、模块排序、底部导航。
+- `GET /api/public/products`：线路列表，支持目的地、主题、活动、关键词筛选。
+- `GET /api/public/products/:id`：线路详情。
+- `GET /api/public/destinations`：目的地和热门分类。
+- `GET /api/public/campaigns/:slug`：活动专题详情。
+- `POST /api/public/leads`：提交出行需求。
+- `POST /api/public/sms/send-code`：发送验证码。
+
+### Admin API 给后台使用
+
+- `POST /api/admin/auth/login`
+- `GET /api/admin/dashboard`
+- `CRUD /api/admin/products`
+- `CRUD /api/admin/destinations`
+- `CRUD /api/admin/campaigns`
+- `CRUD /api/admin/home-config`
+- `CRUD /api/admin/media-assets`
+- `GET /api/admin/leads`
+- `PATCH /api/admin/leads/:id/status`
+- `POST /api/admin/leads/:id/followups`
+- `CRUD /api/admin/orders`
+- `GET /api/admin/audit-logs`
+- `POST /api/admin/publish`
+- `POST /api/admin/rollback`
+
+## 前台改造路径
+
+### 第一步：数据层抽离
+
+先不大改 UI，把硬编码内容替换成数据适配层。
+
+- 新建 `src/api/client.ts` 和 `src/api/types.ts`。
+- 新建 `src/adapters/siteConfig.ts`，把接口数据转成当前组件需要的结构。
+- 保留本地 JSON fallback，便于本地开发和接口故障降级。
+- 把 `heroSlides`、`destinations`、`themeCards`、`sectionHeaders`、`bottomCtas` 从静态 import 改成接口加载。
+
+### 第二步：产品和目的地接口化
+
+- `generated-products.json` 改为接口 seed 数据。
+- 搜索逻辑从前端 `keywordAliases` 迁移到后端。
+- 产品详情页从 `getDetailMeta` 这类本地推断改为真实详情字段。
+
+### 第三步：需求表单真实提交
+
+- `DemandPage` 接入 `POST /api/public/leads`。
+- 增加手机号校验、验证码、提交成功页。
+- 后台线索列表能看到来源页面和来源产品。
+
+### 第四步：消息与订单真实化
+
+- 登录态、客户身份、订单列表需要独立规划。
+- 如果短期不做会员体系，可先保留“提交需求后的查询链接/手机号验证码查询”。
+
+## 发布与运维
+
+### 发布策略
+
+- 内容发布与代码发布分离。
+- 运营修改内容后生成草稿版本。
+- 审核通过后写入 `site_versions`，Public API 默认返回当前发布版本。
+- CDN 缓存使用短 TTL 或发布后主动刷新。
+- 每次发布可回滚到上一版本。
+
+### 环境
+
+| 环境 | 用途 |
+| --- | --- |
+| local | 本地开发 |
+| dev | 联调环境 |
+| staging | 预发布，连接准生产数据或脱敏数据 |
+| production | 正式环境 |
+
+### 监控与备份
+
+- API 错误率、响应时间、数据库连接数。
+- 需求提交成功率、短信发送成功率。
+- 每日数据库自动备份，至少保留 14 到 30 天。
+- 对象存储开启版本控制或回收站。
+- 关键操作日志不可被普通管理员删除。
+
+### 安全
+
+- 后台必须 HTTPS。
+- 管理端登录限流。
+- 所有 Admin API 校验权限。
+- Public API 做参数校验和频控。
+- 手机号等隐私信息后台脱敏展示，导出需要高权限。
+- 防止任意文件上传：限制 MIME、大小、后缀，图片重新编码。
+
+## 分阶段交付计划
+
+### Phase 1：后台 MVP，约 2 到 3 周
+
+目标：运营可以维护首页和线路，H5 可以读取接口。
+
+- 搭建 monorepo、API、Admin、数据库。
+- 建立媒体库、产品、目的地、首页配置数据表。
+- 写 seed 脚本，把当前 `content.ts` 和 `generated-products.json` 导入数据库。
+- 后台完成登录、产品列表/编辑、首页配置、图片上传。
+- H5 接入 `site-config` 和 `products`，保留本地 fallback。
+
+### Phase 2：线索闭环，约 2 周
+
+目标：出行需求可以真实提交、分配、跟进。
+
+- 需求表单接口。
+- 后台线索列表、状态流转、跟进记录。
+- 客户经理分配。
+- 短信验证码和提交通知。
+- 导出和基础统计。
+
+### Phase 3：活动和发布体系，约 2 到 3 周
+
+目标：专题页和首页可以安全发布。
+
+- 活动专题管理。
+- 草稿/审核/发布/回滚。
+- 发布日志和操作审计。
+- CDN 刷新。
+- 预发布环境验收。
+
+### Phase 4：订单、客户和消息，约 3 到 5 周
+
+目标：从线索进一步进入服务履约。
+
+- 客户档案。
+- 订单/方案管理。
+- 前台消息和订单查询。
+- 附件上传。
+- 顾问工作台。
+
+### Phase 5：生产加固，持续迭代
+
+目标：稳定上线维护。
+
+- 监控告警、备份恢复演练。
+- 权限细化、数据脱敏。
+- 性能优化和缓存。
+- 自动化测试、CI/CD。
+- 数据分析看板。
+
+## MVP 优先级
+
+必须先做：
+
+1. 后台登录与权限。
+2. 媒体库。
+3. 线路产品管理。
+4. 首页配置管理。
+5. H5 读取接口并保留 fallback。
+6. 需求表单真实提交。
+7. 线索后台跟进。
+8. 发布、回滚、操作日志。
+
+可以后做：
+
+1. 完整会员登录。
+2. 真实支付。
+3. 复杂订单履约。
+4. 企业微信深度集成。
+5. 多语言/多品牌站点。
+
+## 近期可执行清单
+
+1. 建立 `apps/h5`、`apps/admin`、`apps/api` 结构。
+2. 设计 Prisma schema，并先覆盖产品、首页、媒体、目的地、线索。
+3. 编写 seed 脚本，把现有静态内容导入数据库。
+4. 做 Public API，先返回与当前 H5 兼容的数据。
+5. 改造 H5 数据加载层，保证 UI 不变。
+6. 做 Admin 的产品管理和首页装修。
+7. 接通需求表单和后台线索列表。
+8. 补充发布版本、回滚、审计日志。
+
+## 风险与建议
+
+- 不建议一开始就做完整电商订单和支付，旅游定制业务更适合先做线索和顾问跟进闭环。
+- 不建议让后台直接编辑任意 JSON，短期快但长期容易把数据结构搞乱。
+- 不建议 H5 只依赖实时接口，首页配置应支持发布版本和缓存，避免后台故障影响前台展示。
+- 不建议图片继续只放在代码仓库里，真实上线后要进入对象存储和 CDN。
+- 如果预算有限，第一期可以先用单台云服务器 + PostgreSQL + 对象存储；但备份、HTTPS、日志和权限不能省。