WonderQ-Project/docs/team-building-api.md

团队共创详情接口契约

适用端：WonderQ-Admin、WonderQ-Admin-UI、WonderQ-MiniAPP。
目标：复用 HomeTeamBuilding 表，维护首页团队共创卡片和沉浸式详情页内容。

领域边界

• 团队共创卡片和详情共用一条 HomeTeamBuilding 记录。
• 详情封面复用 image，不新增独立详情表或第二张 hero 图片。
• detailSubtitle 是详情首屏副标题。
• detailParagraphs 是按阅读顺序保存的正文段落数组。
• Admin UI 使用正文 textarea 的“空行分隔段落”约定；后端保存前会清洗首尾空白和空段落。
• 首页卡片仍保留 demandKeyword，但点击行为改为详情页；该字段仅作为其他需求入口的普通文案，不建立商品或订单外键。

数据类型

type HomeTeamBuilding = {
  id: string;
  tag: string;
  title: string;
  description: string;
  image: string;
  demandKeyword: string;
  detailSubtitle: string;
  detailParagraphs: string[];
  isActive: boolean;
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
};

type HomeTeamBuildingCreate = {
  tag: string;
  title: string;
  description: string;
  image: string;
  demandKeyword: string;
  detailSubtitle?: string;
  detailParagraphs?: string[];
  isActive?: boolean;
  sortOrder?: number;
};

type HomeTeamBuildingPatch = Partial<HomeTeamBuildingCreate>;

兼容规则：旧客户端不提交详情字段时，后端使用模型默认值；迁移 0020_home_team_building_details 会把已有记录的副标题回填为 description，正文回填为 [description]。Public 序列化时仍会对空值做相同 fallback。

Admin API

前缀为 /api/admin，需要 Authorization: Bearer <admin-jwt>。既有列表、创建、编辑、删除和排序路径保持不变：

方法	路径	用途
GET	/api/admin/home/team-buildings	获取全部团队共创记录
POST	/api/admin/home/team-buildings	新增团队共创记录
PATCH	/api/admin/home/team-buildings/{teamBuildingId}	编辑团队共创记录和详情字段
DELETE	/api/admin/home/team-buildings/{teamBuildingId}	删除团队共创记录
PATCH	/api/admin/home/team-buildings/reorder	调整团队共创顺序

创建或编辑请求示例：

{
  "tag": "户外挑战",
  "title": "山野挑战，共创极境",
  "description": "洞穴、瀑降与协作，适合 10-30 人。",
  "image": "https://example.test/assets/team-building.jpg",
  "demandKeyword": "户外团建",
  "detailSubtitle": "越过山丘，向来处去",
  "detailParagraphs": [
    "真正的贵州，从未被写进流水线的攻略里。",
    "把会议室换成山野，让团队重新认识彼此。"
  ],
  "isActive": true
}

约束：

• 文本字段去除首尾空白后不得为空；详情副标题最大 160 字，正文最多 30 段。
• detailParagraphs 保存时过滤空段落；编辑接口显式传空正文会返回 422。
• 图片只接受 HTTP(S) URL；排序值为非负整数。
• 列表接口返回启用和停用记录，按 sortOrder 升序；删除和排序继续写审计日志。
• 迁移只新增两列，不改变旧字段和现有接口路径；本次实现不自动执行迁移。

Public API

首页摘要

GET /api/public/home

首页响应中的 teamBuildings 只返回卡片摘要：

type PublicHomeTeamBuildingSummary = {
  id: string;
  tag: string;
  title: string;
  description: string;
  image: string;
  demandKeyword: string;
};

详情

GET /api/public/home/team-buildings/{teamBuildingId}

无需鉴权。成功响应：

type PublicHomeTeamBuildingDetail = PublicHomeTeamBuildingSummary & {
  detailSubtitle: string;
  detailParagraphs: string[];
};

错误响应：

状态码	场景
404	ID 不存在或团队共创已停用
5xx	服务端异常；MiniAPP 进入本地 fallback

响应中的 detailSubtitle 为空时返回 description；detailParagraphs 为空时返回 [description]。Public API 不返回管理端状态、排序和审计字段。

MiniAPP 联调约定

1. 首页通过 /api/public/home 加载团队共创卡片。
2. openTeamBuilding(item) 调用 goTeamBuildingDetail(item.id)，跳转 /pages/team-buildings/detail?id={teamBuildingId}。
3. 详情页调用 fetchPublicTeamBuildingDetail(teamBuildingId)，成功后通过 normalizeHomeTeamBuildingDetail 归一化。
4. 请求失败时按 ID 查找 homeTeamBuildingFallback；命中则展示模拟网络图片、标题、副标题和正文，并提示“接口暂不可用，当前展示模拟数据”。
5. 无 ID、ID 不存在且无 fallback 时展示未找到状态，并提供返回首页操作。
6. 页面必须覆盖 loading、接口失败、空正文和未找到状态；详情布局使用 TailwindCSS，不新增页面级自定义样式。

三端联调顺序

1. 在 WonderQ-Admin 执行 python -m alembic upgrade head，仅在确认目标数据库后执行。
2. 启动后端并验证 GET /health。
3. 在 Admin UI 创建或编辑团队共创，填写详情副标题和正文；正文 textarea 使用空行分段。
4. 验证 Admin API 返回详情字段，Public 首页只返回摘要。
5. 在 MiniAPP 首页点击团队共创卡片，确认 URL 携带正确 ID。
6. 验证详情接口成功展示最新内容；停止后端后确认按 ID fallback 并显示提示。

变更文件

• 后端：WonderQ-Admin/app/models.py、app/schemas.py、app/serializers.py、app/routers/public.py、alembic/versions/0020_home_team_building_details.py。
• 管理端：WonderQ-Admin-UI/src/api.ts、src/pages/structure/HomeContentPage.tsx、src/components/admin/HomeContentEditor.tsx、src/components/admin/HomeContentCardRail.tsx。
• 前台：WonderQ-MiniAPP/src/pages/home/components/homeTeamBuildingData.ts、src/lib/types.ts、src/lib/api.ts、src/lib/navigation.ts、src/pages/home/index.vue、src/pages/team-buildings/detail.vue、src/pages.json。