# M-01 项目概览 Widget PRD

版本：v0.9
状态：第一阶段 MVP 内容与异常规则已确认；响应式原型为设计参考，待视觉定稿与开发

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-28 | v0.1 | 初始创建 | 定义 M-01 的图文内容、配置、移动端行为、状态与验收；以用户确认的封面图和项目介绍为 MVP 核心。 |
| 2026-07-28 | v0.2 | 重大：导航与组合退出 MVP | 同步页面交付边界：MVP 仅在独立项目概览页使用 M-01；未来是否加入页面组合不成为 Widget 配置，也不改变 Widget 内容。 |
| 2026-07-28 | v0.3 | 重大：单语言发布规则 | M-01 在 MVP 中只读取页面实例确定的发布语言；项目名称、介绍、主体和替代文字不得自动翻译或跨语言回退。 |
| 2026-07-29 | v0.4 | 重大：封面数量定稿 | 确认 MVP 只使用一张项目主封面图，不支持多图、轮播或画廊。 |
| 2026-07-29 | v0.5 | 重大：封面交互定稿 | 确认项目封面不可点击，不打开大图，也不显示可点击反馈。 |
| 2026-07-29 | v0.6 | 重大：项目身份字段定稿 | 项目名称、项目标识和开发主体按照已发布接口数据展示；项目名称必需，项目标识和开发主体有值显示、无值独立隐藏。 |
| 2026-07-29 | v0.6 | 非重大：原型交付同步 | 已在项目概览页完成单封面图文布局的移动端、PAD 和 PC 响应式原型。 |
| 2026-07-29 | v0.7 | 重大：项目信息范围调整 | 删除项目标识和非业务装饰文案；开发主体统一改称“开发商名称”，有值显示、无值隐藏。项目 Logo 移出 M-01，改由页面通用组件承载。 |
| 2026-07-29 | v0.8 | 重大：长文本展示规则调整 | 项目介绍限定为纯文本；长文本允许采用自动滚屏，但必须可被用户操作打断、支持手动阅读，并在减少动态效果偏好下停用自动运动。 |
| 2026-07-29 | v0.9 | 重大：封面展示与失败规则调整 | 封面改为始终保持原图完整可见，不允许裁切；运行时加载失败时显示系统默认底图，且不随机替换为其他项目素材。 |

## 1. Widget目标与使用页面

M-01 用设计感明确的图文组合，让顾客快速识别项目并阅读项目介绍。它必须能独立完成项目认知任务，不依赖地图、户型、预约或其他 Widget。

MVP 使用页面：[`../01-页面体系/01-项目概览页PRD.md`](../01-页面体系/01-项目概览页PRD.md)。

## 2. 内容清单与来源规则

| 内容 | 必需性 | 业务来源 | 使用规则 |
| --- | --- | --- | --- |
| 项目名称 | 必需 | 项目基础信息接口 | 自动读取已发布项目名称；Widget 内不另写一个不同项目名。 |
| 项目封面图 | 必需 | 项目可公开图片素材 | A 端从项目素材中选择一张作为封面；MVP 只读取这一张，不自动使用其他项目或未公开素材。 |
| 项目介绍文字 | 必需 | 项目公开介绍内容 | 使用已发布纯文本介绍；保留自然段与换行，不接受富文本、HTML、图片或嵌入对象。若存在多个已发布版本，A 端选择本实例使用版本。 |
| 开发商名称 | 可选 | 项目基础信息接口 | 接口返回有效公开值时展示；无值时隐藏，不保留标签、分隔符或占位。 |
| 图片替代文字 | 必需 | 素材说明或项目名称生成规则 | 用于图片加载失败与无障碍识别；不得写成营销口号。 |

MVP 不支持 Widget 内自由录入一套脱离项目数据的项目名称、封面和介绍。M-01 只使用页面实例传入的一种发布语言，所有文字字段必须来自同一语言上下文；当前语言必需内容缺失时按发布校验处理，不自动使用其他语言。具体稳定数据键在 `04-项目内容数据与素材字典.md` 统一命名。

项目 Logo 不是 M-01 内容字段，也不得覆盖在封面内部；其显示由页面级“项目 Logo 组件”负责。`VISTA RESIDENCE` 等无业务来源的装饰文字不进入数据或展示范围。

## 3. A端配置

| 配置项 | 规则 |
| --- | --- |
| 封面图选择 | 必选且只能选择项目可公开图片；MVP 只使用一张主封面。 |
| 项目介绍选择 | 必选；从已发布项目介绍版本中选择。 |
| 开发商名称 | 不提供独立显隐配置；按已发布接口数据自动展示或隐藏。 |
| 内容顺序 | MVP 固定为封面图、项目名称/可选开发商名称、项目介绍三个内容区；具体并列或上下布局由设计稿决定，不开放内容拖拽排序。 |
| 页面交付方式 | 不作为 Widget 配置；MVP 仅独立交付，未来加入导航或页面组合时仍复用同一 Widget。 |
| 语言 | 不作为 Widget 内切换项；由页面实例统一传入发布语言。 |

## 4. 核心功能

### F-01 图文展示

- 封面图承担第一视觉，项目名称和介绍承担可读信息。
- 不在封面图上叠放项目介绍长文本。
- 项目介绍仅按纯文本渲染，保留自然段与换行，不解释 HTML、Markdown 或其他富文本标记。
- 介绍必须可完整阅读，不截断为无法继续阅读的摘要。
- 当设计稿为介绍区设置有限可视高度且文字发生溢出时，可以自动滚屏；未发生溢出时不得启动。
- 自动滚屏在用户触摸、滚轮、拖动、键盘滚动或聚焦阅读后立即暂停，让用户接管；滚动到末尾后停止，不循环回到开头。
- 系统启用“减少动态效果”时不自动滚屏，仅保留用户手动滚动。滚动速度、启动延迟和渐隐提示由设计稿确定，当前原型数值不作为开发口径。

### F-02 单图封面

- MVP 只展示一张项目主封面图。
- 封面始终保持原始宽高比并完整显示，不得使用中心裁切、填满裁切或局部截取；允许因图片比例与容器不同出现留白或调整图文布局。
- 封面不是操作入口，点击、轻触或键盘聚焦均不打开大图或其他内容。
- 封面不显示按压态、涟漪、放大图标、链接光标等可点击反馈。
- 不扩展为画廊、多图轮播或视频。

### F-03 内容降级

- 开发商名称按接口结果显隐；缺失时不占位，不残留标签或分隔符。
- 封面运行时失败：显示系统统一的项目封面默认底图，保留名称和介绍；默认底图不得使用其他项目图片，也不得伪造项目视觉。
- 纯文本介绍中的换行正常保留；不识别或渲染富文本标记。
- 项目名称、封面或介绍在发布前缺失：Widget 不可启用。

## 5. 核心用户用例

### UC-01 阅读项目介绍

1. 用户进入项目概览页。
2. 先看到封面图和项目名称。
3. 向下滚动阅读完整介绍。
4. 用户在不依赖其他 Widget 的情况下理解项目。

### UC-02 封面图片失败

1. 图片请求失败。
2. Widget 显示系统默认底图，并通过可访问名称说明封面暂不可用。
3. 项目名称及介绍继续可读。
4. 页面不跳转 404，也不使用其他图片随机补位。

## 6. 移动端与响应式

| 视口 | 内容与交互规则 |
| --- | --- |
| 320px / 375px | 单列；封面在前、文字在后；正文使用页面纵向滚动；无横向滚动。 |
| 768px | 具体采用单列或并列由设计稿决定；封面必须完整显示，介绍必须可完整阅读。 |
| 1024px / 1440px | 可增加内容最大宽度与并列空间；不得为了填满容器裁切封面，也不得新增桌面专属业务功能。 |

## 7. 状态

| 状态 | 触发 | 处理 |
| --- | --- | --- |
| 可启用 | 名称、封面、介绍完整 | 正常展示。 |
| 不可启用 | 任一必需内容在发布前缺失 | 阻止启用/发布。 |
| 降级 | 开发商名称缺失 | 隐藏开发商名称及标签，不留空白占位。 |
| 图片局部失败 | 封面运行时失败 | 显示系统默认底图并保留文字内容。 |
| 文字加载失败 | 必需介绍运行时不可用 | Widget 局部错误与重试，不生成替代文案。 |

## 8. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-M01-01 | 名称、封面、介绍完整 | 320px、375px 打开 | 依次看到图片、名称和介绍，全部可读。 |
| AC-M01-02 | 介绍较长且超出设计稿规定的可视区域 | 自动滚屏启动或用户手动阅读 | 全文可达；用户任一滚动/触控/键盘阅读操作会暂停自动滚屏，滚动到末尾后不循环。 |
| AC-M01-03 | 封面失败 | 名称和介绍可用 | 显示系统统一默认底图，文字继续可读，不使用其他项目图片补位。 |
| AC-M01-04 | 必需内容缺失 | A 端发布 | Widget 不可启用，不用示例内容补位。 |
| AC-M01-05 | 任一验收视口打开 | 封面正常加载 | 原图完整可见且保持宽高比，不因容器比例发生裁切；布局可按设计稿响应式调整。 |
| AC-M01-06 | 项目素材中有多张图片 | M-01 正常展示 | 只显示已选择的一张主封面，不出现轮播、分页或画廊入口。 |
| AC-M01-07 | 用户点击或轻触封面 | 封面加载正常 | 不打开大图、不跳转，也不出现可点击反馈。 |
| AC-M01-08 | 接口返回或缺失开发商名称 | Widget 渲染 | 有值时以“开发商”业务含义展示；无值时隐藏且不保留空白占位。 |
| AC-M01-09 | 项目 Logo 有效 | M-01 渲染 | M-01 内部不重复显示或覆盖 Logo；由页面级项目 Logo 组件单独承载。 |
| AC-M01-10 | 系统启用减少动态效果 | 长介绍发生溢出 | 不自动滚屏，用户仍可手动阅读全部纯文本。 |

## 9. 明确不做与待确认

**明确不做：** 项目标识字段、项目 Logo、无业务来源装饰文字、多图画廊、轮播、封面大图查看、封面裁切、视频背景、地图/户型入口、预约 CTA、AI 自动文案、富文本/HTML、埋点。

**待确认：**

- 当前无阻塞开发的待确认项。
- 自动滚屏的具体可视高度、速度、启动延迟和视觉提示待设计稿确定；不得直接采用原型参数作为最终规格。
- 系统默认底图的正式视觉素材待设计提供，产品规则已确认。

## 10. 截图参考边界

`截图/C端实际Demo/01-首页与通用交互/01-首页-主界面.jpg` 只证明当前产品重视项目主视觉。新 Widget 不继承其全屏桌面背景、HOMEVISTA 覆盖标识、旧导航和浮动工具布局。