Files

duanshuwen 548f91c37f refactor: 清理废弃业务模块并更新全栈配置

- 移除后端产品、目的地、活动专题等废弃模块的数据库表与业务代码，删除冗余API接口
- 删除小程序端详情页、线路组件等冗余代码，移除搜索工具与测试用例，调整导航逻辑
- 清理管理端废弃的类型定义、编辑器与测试代码
- 更新项目文档，修正模块维护说明与接口文档内容

2026-08-17 22:43:49 +08:00

3.3 KiB

Raw Blame History

页面模块配置 Admin API 契约

本文档约束 WonderQ-Admin-UI 对站点结构模块的 CRUD、排序和字段白名单。

适用模块

模块	用途
`heroSlides`	首页顶部轮播
`destinationHero`	目的地页主视觉
`demandHero`	需求页主视觉
`demandFeatureCards`	需求页能力卡片
`demandForm`	需求提交表单
`vehicleOptions`	万趣用车卡片

通用规则

路径：/api/admin/site-config/{module}。
所有模块项都使用字符串 id；排序项使用整数 sortOrder。
创建、更新、删除和排序均需要后台 JWT。
后端只接受模块字段白名单，未知字段会被忽略。
demandForm 是单例模块，重复创建返回 409。
demandForm 不支持排序；其他模块支持排序。
所有变更写入审计日志，并在成功提交后返回最新模块项。

类型

type SiteModule =
  | "heroSlides"
  | "destinationHero"
  | "demandHero"
  | "demandFeatureCards"
  | "demandForm"
  | "vehicleOptions"

type SiteItemPatch = {
  title?: string;
  kicker?: string | null;
  image?: string | null;
  description?: string | null;
  steps?: string[];
  destinationLabel?: string;
  destinationPlaceholder?: string | null;
  phoneLabel?: string;
  phonePlaceholder?: string | null;
  noteLabel?: string;
  notePlaceholder?: string | null;
  submitLabel?: string;
  chips?: string[];
  targetType?: string | null;
  targetValue?: string | null;
  isActive?: boolean;
  sortOrder?: number;
};

获取完整配置

`GET /api/admin/site-config`

返回所有模块数组，包括停用项：

{
  heroSlides: unknown[];
  destinationHero: unknown[];
  demandHero: unknown[];
  demandFeatureCards: unknown[];
  demandForm: unknown[];
  vehicleOptions: unknown[];
}

空模块必须返回 []，不能返回 null 或省略字段。

CRUD

新增

POST /api/admin/site-config/{module}
Authorization: Bearer <admin-jwt>
Content-Type: application/json

请求体使用 SiteItemPatch。成功返回 201 和新建模块项。各模块的主字段如下：

模块	主字段
`heroSlides`	`title`
`destinationHero`	`title`
`demandHero`	`title`
`demandFeatureCards`	`title`
`demandForm`	`submitLabel`
`vehicleOptions`	`title`

缺少主字段返回 422 MODULE_CONFIG_VALIDATION_ERROR。模块不存在返回 400 MODULE_CONFIG_FORBIDDEN。

更新

PATCH /api/admin/site-config/{module}/{id}

只更新该模块允许的字段；不存在的 ID 返回 404 MODULE_CONFIG_NOT_FOUND。

删除

DELETE /api/admin/site-config/{module}/{id}

成功返回 { "id": "..." }。删除后，排序模块会重新从 0 开始编号。

排序

PATCH /api/admin/site-config/{module}/reorder
Content-Type: application/json

{ "itemIds": ["id-2", "id-1"] }

itemIds 必须刚好包含当前模块的全部 ID，且不能重复。否则返回 400 MODULE_CONFIG_REORDER_INVALID。不支持排序的模块返回 400 MODULE_CONFIG_REORDER_UNSUPPORTED。

模块字段补充

demandForm 的 chips 会过滤空白值；表单只保留一条配置。

删除范围边界

模块配置只维护站点内容，不负责客户、线索或订单数据。接口变更必须同步 src/api.ts、src/types/admin.ts 和本文档。

3.3 KiB Raw Blame History Unescape Escape