# 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、日志和权限不能省。