Skip to content

每个单元生成Spec的文档 ​

生成Spec文档的提示词模板 ​

bash
好的,这个拆分方案我接受。
现在请为 homepage-hero 生成完整的Spec文档。
文档结构要求:
1. 模块边界(包含什么/不包含什么)
2. 核心场景(WHEN/THEN/AND格式,覆盖正常+异常路径)
3. 数据结构(组件Props定义、类型与约束)
4. 验收标准(ACCEPTANCE Checklist)
技术约束:
- React + Next.js App Router
- Tailwind CSS + shadcn/ui
- 响应式 (mobile-first)
- next/image图片优化
输出保存为 specs/homepage-hero.md

提示词结果如下 ​

文档信息 ​

项目内容
单元编号H-01
Spec 版本V1.0
日期2026-11-16
上游文档《WanderChina首页开发单元拆分》V1.1、《WanderChina_MVP_P0模块规格说明》V1.2
技术栈React + Next.js App Router · Tailwind CSS + shadcn/ui · 响应式 mobile-first · next/image 图片优化
所属页面首页 / 第一个区块
评审状态待评审

0. 技术约束(实现基线,必须遵守) ​

约束落地要求
Next.js App Router本区块为服务端组件(Server Component)为主,仅搜索框交互部分用客户端组件(use client)
Tailwind CSS全部样式用 Tailwind 原子类;断点采用 mobile-first(base → sm → md → lg)
shadcn/ui搜索框输入用 shadcn/ui Input;提示用 Toast(sonner)或 Tooltip,不手写原生 alert
响应式 mobile-first先写移动端样式,再用断点向上增强;不得出现横向滚动条
next/image背景图必须用 next/image(fill + sizes + priority),禁止用 <img> 或 CSS background-image 加载主视觉

1. 模块边界 ​

1.1 包含什么(In Scope) ​

#能力说明
1主视觉背景图品牌背景图,用 next/image 渲染并做响应式裁切与懒加载优化
2品牌标语英文主 + 中文对照,取自配置 slogan_en / slogan_zh
3副标题英文主 + 中文对照,取自配置 subtitle_en / subtitle_zh
4搜索框 UI 骨架只读输入框 + 占位提示;点击/聚焦弹出「即将开放」提示
5响应式布局移动端到桌面端的字号、间距、高度自适应
6文案配置化全部文案由配置注入,不硬编码在组件里

本期种子文案(英文主 + 中文对照,原创,已过合规检查):

字段英文(主)中文(对照)
标语China, without the guesswork.玩转中国,不必先当「中国通」。
副标题Curated guides, honest traveler posts, and an AI that speaks your language — from touchdown to departure.精选攻略、真实游记、随时可问的 AI 助手 —— 从落地到离开,一路有解。

1.2 不包含什么(Out of Scope) ​

#明确不做原因
1❌ 真实搜索逻辑(查询、结果页、联想词)全站搜索列为 P1,本期仅占位
2❌ 搜索接口调用点击不发起任何网络请求
3❌ AI 助手入口属 H-05(顶部图标 + 悬浮按钮),不在本区块
4❌ 城市入口 / 热门内容属 H-03 / H-04
5❌ 用户个性化内容无登录态差异化
6❌ 图片上传 / 运营后台 UI配置由 H-09 种子数据直接维护
7❌ 视频 / 动效背景本期静态图

边界提示:搜索框「占位」指 UI 可见但不可真正搜索;点击应给明确反馈(Toast),不得是死输入框或无响应。


2. 核心场景(WHEN / THEN / AND,覆盖正常 + 异常路径) ​

2.1 正常路径 ​

编号场景
S-01首屏正常渲染 — WHEN 用户打开首页 / THEN 系统展示背景图 + 英文标语 + 英文副标题 + 中文对照 + 搜索框 AND 内容取自当前启用的 home_hero_config 配置行
S-02搜索框占位反馈 — WHEN 用户点击或聚焦搜索框 THEN 系统弹出提示「Search is coming soon / 搜索功能即将开放」 AND 不发起任何网络请求、不跳转页面
S-03配置驱动文案 — WHEN 运营修改 slogan_en 并更新配置 THEN 前端在 5 分钟内展示新文案 AND 无需重新发版
S-04首屏性能 — WHEN 用户在 4G 网络下首次访问 THEN Hero 区块在 2 秒内可见(P75,LCP 目标) AND 背景图由 next/image 优化输出 WebP/AVIF 并按 sizes 加载合适尺寸

2.2 异常与边界路径 ​

编号场景
S-05背景图加载失败 — WHEN 背景图 URL 失效或加载报错 THEN 系统展示 CSS 渐变兜底背景 AND 标语/副标题/搜索框仍完整可读、不出现空白页
S-06配置缺失 — WHEN home_hero_config 无启用行或字段为空 THEN 系统使用组件内置默认文案(即本期种子文案)渲染 AND 记录一条 hero_config_missing 日志,页面不崩溃
S-07超长文案 — WHEN 配置的标语/副标题超出预设字符数(标语 >80、副标题 >200) THEN 系统进行响应式字号收缩 + 最多 2/3 行截断(line-clamp) AND 不溢出容器、不产生横向滚动
S-08慢网加载态 — WHEN 背景图尚未加载完成 THEN 系统先展示纯色/渐变占位 + 文案 AND 图片加载完成后平滑过渡,不出现布局跳动(CLS 可控)
S-09多语言/特殊字符 — WHEN 文案含 emoji、中文标点、长英文单词 THEN 文本正确换行且无乱码 AND 编码为 UTF-8
S-10响应式边界 — WHEN 视口为 320px / 375px / 768px / 1440px THEN 标语为 1 行(移动端可 2 行)、副标题不遮挡搜索框 AND 各断点均无横向滚动、无文字截断错位
S-11键盘与读屏可达 — WHEN 用户用 Tab 键聚焦搜索框 THEN 焦点样式清晰可见 AND 读屏可朗读占位文案与「即将开放」提示(无障碍 accessible)
S-12重复点击 — WHEN 用户连续多次点击搜索框 THEN 提示不重复堆叠(Toast 去重/节流) AND 无性能异常

3. 数据结构(组件 Props 定义、类型与约束) ​

3.1 配置数据来源 ​

字段类型来源约束
idnumberhome_hero_config主键
bannerUrlstringbanner_url合法 URL;允许为空(空则用兜底渐变)
sloganEnstringslogan_en必填,≤80 字符
sloganZhstringslogan_zh必填,≤80 字符
subtitleEnstringsubtitle_en必填,≤200 字符
subtitleZhstringsubtitle_zh必填,≤200 字符
status'ON' | 'OFF'status仅 ON 生效

3.2 TypeScript Props 定义 ​

ts
// types/hero.ts
export interface HeroConfig {
  id: number;
  bannerUrl: string | null; // 允许为空 → 兜底渐变
  sloganEn: string;
  sloganZh: string;
  subtitleEn: string;
  subtitleZh: string;
  status: "ON" | "OFF";
}

// 组件对外 Props(服务端组件)
export interface HeroProps {
  /** 配置数据;缺省时组件使用内置 DEFAULT_HERO_CONFIG */
  config?: HeroConfig | null;
  /** 是否首屏优先加载背景图,默认 true */
  priority?: boolean;
  /** 可选的额外类名,供 H-07 装配时调整间距 */
  className?: string;
}

3.3 组件拆分(App Router) ​

组件类型职责
Hero (components/hero/Hero.tsx)Server Component读取配置、渲染背景图(next/image)+ 标语 + 副标题 + 组合子组件
SearchPlaceholder (components/hero/SearchPlaceholder.tsx)Client Component("use client")只读搜索框,处理点击/聚焦 → Toast 提示;用 shadcn/ui Input + sonner toast
HeroFallbackServer Component背景图失败/为空时的渐变兜底层

服务端/客户端边界:仅 SearchPlaceholder 需要交互(useState / 事件处理 / toast),标记 "use client";其余保持服务端组件,减少客户端 JS。

3.4 常量与约束 ​

ts
export const DEFAULT_HERO_CONFIG: Omit<HeroConfig, "id" | "status"> = {
  bannerUrl: null,
  sloganEn: "China, without the guesswork.",
  sloganZh: "玩转中国,不必先当「中国通」。",
  subtitleEn:
    "Curated guides, honest traveler posts, and an AI that speaks your language — from touchdown to departure.",
  subtitleZh:
    "精选攻略、真实游记、随时可问的 AI 助手 —— 从落地到离开,一路有解。",
};

export const HERO_LIMITS = {
  sloganMax: 80,
  subtitleMax: 200,
  toastMessage: "Search is coming soon / 搜索功能即将开放",
} as const;

3.5 next/image 关键配置 ​

属性值说明
filltrue背景图铺满容器,容器需 relative
sizes(max-width: 640px) 100vw, (max-width: 1024px) 100vw, 50vwmobile-first,按视口加载合适尺寸
priority={priority}(默认 true)首屏 LCP 优化
altWanderChina brand background无障碍
onError触发 HeroFallback加载失败兜底(客户端处理,见 2.2 S-05)

若 bannerUrl 为空,不渲染 next/image,直接输出 HeroFallback 渐变层。

3.6 Tailwind 响应式要点(mobile-first) ​

元素移动端(base)sm/md 及以上
Hero 容器高度min-h-[60svh]md:min-h-[72svh]
标语字号text-3xlmd:text-5xl lg:text-6xl
副标题字号text-smmd:text-lg
中文对照text-xs opacity-80md:text-sm
内容宽度max-w-xlmd:max-w-3xl
搜索框宽度w-fullmd:max-w-lg
布局垂直堆叠垂直堆叠(保持),字号/间距放大

4. 验收标准(ACCEPTANCE Checklist) ​

4.1 功能验收 ​

  • [ ] AC-01 首页 / 加载后 Hero 区展示背景图 + 英文标语 + 英文副标题 + 中文对照 + 搜索框,内容与启用配置一致
  • [ ] AC-02 标语/副标题为「英文主 + 中文对照」双层展示,文案与 §1.1 种子文案一致(初始状态)
  • [ ] AC-03 点击/聚焦搜索框弹出「Search is coming soon / 搜索功能即将开放」提示,且 Network 面板无请求、URL 不变
  • [ ] AC-04 修改配置后 5 分钟内前端文案更新,无需重新构建发版

4.2 异常与健壮性验收 ​

  • [ ] AC-05 将 bannerUrl 置空或改为失效 URL:显示 CSS 渐变兜底,文案与搜索框仍完整可读,无报错
  • [ ] AC-06 删除所有配置行或字段留空:组件使用内置默认文案渲染,不崩溃,控制台有 hero_config_missing 日志
  • [ ] AC-07 配置超长文案(标语 100 字 / 副标题 250 字):字号收缩并截断,容器不溢出、页面无横向滚动
  • [ ] AC-08 弱网(Network 设为 Slow 3G):图片加载期间先显示占位与文案,图片到位后过渡平滑,无明显布局跳动

4.3 技术约束验收 ​

  • [ ] AC-09 背景图使用 next/image(fill + sizes + priority),构建产物中无主视觉的 <img> 或 CSS background-image 加载
  • [ ] AC-10 组件遵循 App Router 规范:Hero 为 Server Component,仅 SearchPlaceholder 使用 "use client"
  • [ ] AC-11 样式全部使用 Tailwind 原子类;搜索框使用 shadcn/ui Input,提示使用 sonner Toast/Tooltip
  • [ ] AC-12 采用 mobile-first 断点;在 320 / 375 / 768 / 1440px 四档视口下均无横向滚动、无文字错位

4.4 无障碍与质量验收 ​

  • [ ] AC-13 Tab 键可聚焦搜索框,焦点样式可见;读屏可朗读占位文案与提示(aria 属性完整)
  • [ ] AC-14 连续点击搜索框 5 次,Toast 不堆叠、无性能异常
  • [ ] AC-15 组件单元测试覆盖:正常渲染 / 搜索提示 / 空配置兜底 / 图片失败兜底 / 超长文案 / 四档视口快照
  • [ ] AC-16 Lighthouse 无障碍 ≥90,Hero 区块对 LCP 无负贡献(图片 priority 生效)

5. 依赖与交付 ​

项目内容
上游依赖H-09 配置与种子数据(home_hero_config);H-08 可选接口 /api/home/hero
下游被依赖H-07 页面装配(作为首页第一个区块)
交付物Hero.tsx(Server)、SearchPlaceholder.tsx(Client)、HeroFallback.tsx、types/hero.ts、单元测试、Storybook 故事(可选)
待确认① 背景图素材来源与授权(建议自绘渐变或已授权图片,避免侵权);② Hero 搜索框是否长期占位(C2)

本 Spec 为产品设计参考,具体实施请结合公司合规与法务要求确认。示例文案为原创,示例数据均为虚构。

审核Spec文档 ​

  • 提示词
bash

请审查生成的spec文档,重点找出以下问题:

1、安全风险-越权、信息泄漏、未做限流的接口

2、数据问题-字段类型/长度/索引是否合理

3、逻辑漏洞-有没有"没说清楚"的灰色地带

4、异常路径-空值、超长、并发:重复点击有没有覆盖

5、验收标准-验收是否可量化、可测试

每条问题给出:在文档哪一行、有什么问题、怎么改

修改完毕后 ​

如果这个spec不在change目录下面也没有tasks.md文件 ​

  • 利用 /opsx:propose 这个技能 读取这个spec文档 生成change和tasks.md

如果这个spec文档已经在change目录下面有tasks.md文件 ​

  • 利用 /opsx:apply 这个技能 按 tasks.md 逐项写代码