# M-10 户型卡片列表 Widget PRD

版本：v0.6
状态：第一阶段 MVP 响应式交互原型已制作，待开发

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-28 | v0.1 | 初始创建 | 定义格局/面积筛选、列表/卡片滑动/单卡片模式、户型卡片内容、大图查看、移动端行为和 MVP 排除项。 |
| 2026-07-28 | v0.2 | 重大：单语言发布规则 | M-10 在 MVP 中只读取页面实例确定的发布语言；筛选、户型名称/说明和组件文案不得自动翻译或跨语言回退。 |
| 2026-07-29 | v0.3 | 重大：筛选条件定稿 | MVP 筛选条件确认为户型名称/类型、面积和 LDK；不包含内览、价格、楼层或销售状态。 |
| 2026-07-29 | v0.4 | 重大：展示模式定稿 | 列表、卡片滑动、单卡片由 M-10 Widget 实例明确决定，不由页面或户型数量自动切换；缺失或非法模式降级为列表。 |
| 2026-07-29 | v0.5 | 重大：面积区间定稿 | 面积筛选基于 Widget 全量可用户型自动生成 10㎡区间并隐藏空区间，不提供项目手工区间配置。 |
| 2026-07-29 | v0.6 | 重大：大图手势定稿 | 手机支持双指缩放、放大后平移、恢复适配与关闭；PAD/PC 支持缩放控件或滚轮、拖动与关闭；双击缩放不进入 MVP。 |
| 2026-07-29 | v0.6 | 非重大：原型交付同步 | 已完成三种实例模式、三类筛选、空状态及户型图查看器的响应式交互原型。 |

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

M-10 帮助顾客从项目可公开户型中进行基础筛选和浏览，并查看户型图细节。列表、卡片滑动和单卡片是同一 Widget 的展示模式，不拆成多个 Widget 或页面。

MVP 使用页面：[`../01-页面体系/03-户型列表页PRD.md`](../01-页面体系/03-户型列表页PRD.md)。

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

主要数据来源为项目户型集合，稳定数据键建议统一为 `project.floorplans`，最终命名以 `04-项目内容数据与素材字典.md` 为准。

| 内容 | 必需性 | 使用规则 |
| --- | --- | --- |
| 户型稳定标识 | 必需 | 用于卡片、筛选和图片查看状态关联；C 端不展示内部 ID。 |
| 户型名称/类型名 | 必需 | 使用项目已发布名称。 |
| 户型图 | 必需 | 使用可公开图纸；无有效图纸的户型不进入 MVP 集合。 |
| LDK/格局 | 必需 | 用于卡片展示和 LDK 筛选，例如 2LDK、3LDK。 |
| 面积 | 必需 | 展示明确数值与单位，用于面积筛选。 |
| 户型说明/标签 | 可选 | 有已发布内容时展示，无内容时隐藏。 |
| 楼栋/分组 | 可选 | 仅在项目数据有明确关系且 A 端启用分组时使用。 |

MVP 不读取住户房号、销售状态、价格、费用、样板间、WALK/VR 或比较数据。M-10 只使用页面实例传入的一种发布语言；户型名称、说明/标签和筛选显示文案必须来自同一语言上下文，当前语言必需内容缺失时不自动使用其他语言补位。

## 3. A端配置

本节描述 M-10 Widget 实例自身的内容与模式参数。展示模式不属于页面规则，也不由 C 端页面根据数量推断；具体管理界面归属以 A 端 PRD 为准。

| 配置项 | 规则 |
| --- | --- |
| 户型选择 | 从项目可公开户型中选择进入 Widget 的对象。 |
| 户型顺序 | 支持项目推荐顺序；未配置时使用项目默认顺序。 |
| 展示模式 | M-10 Widget 实例必需参数：列表、卡片滑动、单卡片；不由页面或户型数量自动决定，缺失或非法时降级为列表。 |
| 筛选启用 | MVP 支持户型名称/类型、面积、LDK；单个维度不足两个有效选项时隐藏该维度。 |
| 面积范围 | 基于本 Widget 全量可用户型自动生成 10㎡区间并隐藏空区间，不提供手工区间配置。 |
| 可选说明/标签 | 可选择显示，但不得覆盖名称、LDK/格局和面积。 |
| 样板间/比较入口 | MVP 不提供配置项。 |
| 语言 | 不作为 Widget 内切换项；由页面实例统一传入发布语言。 |

## 4. 核心功能

### F-01 户型集合与结果摘要

- 只使用已选择且可公开的户型。
- 可显示当前结果数量；数量必须与筛选结果一致。
- 个别户型失效时从集合移除，不显示空白卡片。

### F-02 户型、面积与 LDK 筛选

- 户型选项来自本 Widget 全量可用户型的户型名称/类型名。
- LDK 选项来自本 Widget 全量可用户型的 LDK/格局数据，例如 2LDK、3LDK。
- 面积区间按 10㎡步长、以 10 的整数倍为边界自动生成，采用左闭右开规则 `[n, n+10)`；例如 60㎡进入 `[60,70)`，70㎡进入 `[70,80)`。
- 面积区间基于筛选前的全量可用户型生成，筛选过程中不重建，避免选项跳动。
- 没有户型落入的面积区间不显示；仅形成一个有效区间时隐藏面积筛选维度。
- 每个筛选维度在 MVP 中单选并提供“全部”；跨维度按“户型 AND 面积 AND LDK”组合。
- 确认后更新结果并回到结果起始位置。
- 提供一键重置。
- 筛选无结果时展示当前条件和重置动作。

### F-03 三种展示模式

**列表模式**

- 手机端使用单列纵向卡片。
- PAD/PC 可按可读宽度增加列数。

**卡片滑动模式**

- 手机端一次突出一张卡片，并露出下一张的部分边缘或提供明确进度。
- 支持触控横向滑动。
- 到达首尾时不得继续出现空白卡片。

**单卡片模式**

- 展示一个户型时不显示无意义的分页、滑动或结果切换。
- 仍可打开大图。

展示模式由 M-10 Widget 实例明确配置，不由页面或当前结果数量自动改变：

- 列表、卡片滑动模式允许一个或多个已选择户型；只有一个结果时隐藏无意义的分页或滑动提示，但不改写 Widget 模式。
- 单卡片模式要求 Widget 实例只选择一个户型，不显示筛选、分页或滑动控件。
- 展示模式缺失、为空或非法时，安全降级为列表模式。
- 展示模式变化不改变卡片字段、筛选口径和大图动作。

### F-04 户型卡片

卡片内容顺序：

1. 户型图。
2. 户型名称。
3. 格局。
4. 面积及单位。
5. 可选说明/标签。
6. 查看大图动作。

不得显示比较、内览/样板间、WALK/VR、价格、销售状态、收藏或预约按钮。

### F-05 户型图大图查看

- 点击户型图或查看大图动作打开图片查看器。
- 手机端全屏展示，关闭动作始终可达。
- 手机支持双指缩放、放大后的单指平移和恢复适配；双击不触发缩放。
- PAD/PC 支持明确缩放控件或鼠标滚轮缩放，放大后可拖动查看；支持关闭按钮，键盘环境支持 `Esc` 关闭。
- 关闭后恢复筛选、展示模式、当前卡片和滚动位置。
- 大图失败时在查看器内显示错误并允许关闭，不破坏列表。
- 大图不是独立 Widget 或单户型详情页。
- 详细规则以 [`../03-通用组件体系/02-图片查看器组件PRD.md`](../03-通用组件体系/02-图片查看器组件PRD.md) 为准。

## 5. 核心用户用例

### UC-01 筛选并浏览户型

1. Widget 展示全部可用户型。
2. 用户选择户型名称/类型、面积和/或 LDK。
3. Widget 更新结果与数量。
4. 用户浏览匹配卡片。
5. 用户可重置回全部结果。

### UC-02 滑动浏览户型

1. Widget 使用卡片滑动模式。
2. 用户左右滑动。
3. 当前卡片和下一步方向始终明确。
4. 滑动到末尾不出现空卡。

### UC-03 查看大图并返回

1. 用户点击户型图。
2. 查看器展示对应大图。
3. 用户缩放/平移并关闭。
4. Widget 恢复原卡片和筛选状态。

### UC-04 无结果与空数据

- 筛选无结果：保留条件、显示重置。
- 运行时无可用户型：Widget 空状态，不生成推荐内容。
- 发布前无可用户型：Widget 不可启用。

## 6. 移动端与响应式

| 视口 | 内容与交互规则 |
| --- | --- |
| 320px / 375px | 筛选使用底部面板/全宽弹层；列表单列；滑动模式触控优先；大图全屏。 |
| 768px | 列表最多扩展为两列；筛选可用侧边/弹层但操作项相同。 |
| 1024px / 1440px | 可增加列数和内容宽度，但卡片必须保持可读；不得复制旧 Demo 七列紧凑网格。 |

## 7. 状态

| 状态 | 处理 |
| --- | --- |
| 可启用 | 至少一个户型的名称、图纸、LDK/格局、面积完整，且展示模式与选择数量匹配。 |
| 不可启用 | 发布前无完整可用户型，或单卡片模式选择数量不等于一。 |
| 正常多户型 | 按 Widget 实例配置的列表或滑动模式展示。 |
| 正常单户型 | 按 Widget 实例配置展示；无意义的分页、滑动提示和筛选维度隐藏。 |
| 筛选无结果 | 条件摘要 + 重置。 |
| 运行时空集合 | 空状态，不自动跳转。 |
| 单卡/单图失败 | 移除失效对象或显示查看器局部错误。 |

## 8. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-M10-01 | 多个可用户型 | 320px、375px 打开 | 卡片核心内容清晰，列表不依赖横向页面滚动。 |
| AC-M10-02 | 户型/面积/LDK 选项有效 | 用户确认筛选 | 三个维度按 AND 组合，结果和数量正确，可一键重置。 |
| AC-M10-03 | 卡片滑动模式 | 用户连续滑动 | 当前项明确，首尾无空卡。 |
| AC-M10-04 | 单卡片模式 | 只有一个户型 | 不显示无意义分页和滑动控件。 |
| AC-M10-05 | 用户打开并关闭大图 | 原列表仍在会话中 | 恢复原筛选、卡片和滚动位置。 |
| AC-M10-06 | 筛选无结果 | 用户查看 | 显示条件与重置，不生成虚构推荐。 |
| AC-M10-07 | 检查全部卡片动作 | 用户操作 | 不出现比较、样板间、WALK/VR、价格、收藏、预约。 |
| AC-M10-08 | PAD/PC 打开 | 视口扩展 | 可增加列数，字段、筛选、状态和动作与手机一致。 |
| AC-M10-09 | Widget 模式分别为列表、滑动、单卡片 | 用户打开页面 | 按实例模式展示；页面和户型数量不自动改写模式。 |
| AC-M10-10 | Widget 模式缺失或非法 | 用户打开页面 | 安全降级为列表模式，不白屏或崩溃。 |
| AC-M10-11 | 全量可用户型具有不同面积 | Widget 生成筛选 | 以 10㎡左闭右开区间展示，空区间隐藏，筛选过程中区间不重建。 |
| AC-M10-12 | 手机打开大图 | 用户缩放、平移、恢复适配并关闭 | 操作可用，双击无缩放动作，关闭后恢复原 Widget 状态。 |
| AC-M10-13 | PAD/PC 打开大图 | 用户使用控件或滚轮缩放并拖动 | 可查看图纸细节，并可通过关闭按钮或 Esc 返回。 |
| AC-M10-14 | Widget 配置为单卡片模式 | 发布前校验选择数量 | 仅选择一个户型时可启用；零个或多个时阻止启用并提示修正。 |

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

**明确不做：** 户型比较、样板间/内览、WALK/VR、住户信息、价格费用、收藏、推荐算法、单户型详情页、预约和埋点。

**待确认：**

- 当前无阻塞开发的待确认项。

## 10. 截图参考边界

- `04-間取図.jpg`：确认卡片包含图纸、名称、格局、面积、可选说明。
- `02-户型点击详情.jpg`：确认大图查看任务。
- `04-选择菜单.jpg`：确认 LDK 与面积筛选的交互形态；户型名称/类型筛选依据本轮产品确认进入 MVP。
- 截图中的比较、内览按钮、内览筛选、旧顶部工具和七列桌面网格均不进入 MVP。