# 项目内容数据与素材字典

版本：v0.9
状态：第一阶段 MVP 数据范围与项目 Logo/封面降级口径已确认，待技术映射与开发
适用表面：VISTA C

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-29 | v0.1 | 初始创建 / 重大数据口径确认 | 建立 MVP 项目身份、项目介绍、项目位置、地图注意事项、POI、户型、公共联系方式和图片素材字典；锁定稳定数据键、必填性、校验、缺失处理、素材质量门槛及 Widget/组件消费关系。 |
| 2026-07-29 | v0.2 | 重大：项目身份消费边界调整 | 删除“项目标识”展示字段口径；项目 Logo 改由独立页面通用组件消费，开发主体统一改称开发商名称，M-01 只读取项目名称和可选开发商名称。 |
| 2026-07-29 | v0.3 | 重大：封面与介绍展示数据规则调整 | 明确封面必须保持整图、运行时失败使用系统默认底图；项目介绍限定纯文本，长文本自动滚屏属于显示行为，不新增另一份滚屏文案。 |
| 2026-08-03 | v0.4 | 引用迁移 | 三份 P0 Widget 数据消费者引用迁移到无 M-XX 的正式 Widget PRD；数据字段口径不变。 |
| 2026-08-03 | v0.5 | 引用迁移 | 通用组件引用迁移到合并后的当前组件需求目录；数据字段口径不变。 |
| 2026-08-04 | v0.6 | 重大：素材更新提示规则补充 | 页面读取已引用素材的最新内容；素材变化时向顾客显示非阻断的页面内容更新提示，确认后在该顾客当前页面的本次素材版本组合内不重复提示。 |
| 2026-08-09 | v0.7 | 重大：全 C端内容来源收敛 | 明确页面、Widget、组件和原型的允许来源、禁止来源与缺失处理；通用槽位、旧页面、Demo 和 AI 均不得成为新增顾客内容的依据。 |
| 2026-08-11 | v0.8 | 重大：项目概览字段同步 | 项目概览新增公开地址与开发商名称，取消项目名称作为该 Widget 的顾客可见字段。 |
| 2026-08-11 | v0.9 | 项目概览消费口径校正 | 清除项目概览仍以项目名称作为发布前置或运行时展示内容的遗留表述。 |

## 1. 文档目的与适用对象

本文档统一定义第一阶段 MVP 中，C 端页面、Widget 和通用组件可读取的项目内容数据与素材。

它面向产品、设计、数据接口开发、前端开发、测试及 Codex，解决以下问题：

1. 同一个项目内容对象在不同页面中使用什么统一名称和稳定数据键。
2. 哪些内容是发布必需项，哪些是可选项。
3. 数据或素材缺失、失效、格式错误时，是阻止发布、隐藏字段，还是进入局部错误。
4. Widget 实例配置与项目内容数据如何分开。
5. 图片素材达到什么最低质量后，才可进入 MVP 页面。

关联文档：

- [`00-C端交付总览与阶段路线图.md`](00-C端交付总览与阶段路线图.md)
- [`02-Widget体系/Widget需求/01-项目概览Widget-PRD.md`](02-Widget体系/Widget需求/01-项目概览Widget-PRD.md)
- [`02-Widget体系/Widget需求/03-周边地图Widget-PRD.md`](02-Widget体系/Widget需求/03-周边地图Widget-PRD.md)
- [`02-Widget体系/Widget需求/02-户型卡片列表Widget-PRD.md`](02-Widget体系/Widget需求/02-户型卡片列表Widget-PRD.md)
- [`03-通用组件体系/03-项目联系组件PRD.md`](03-通用组件体系/03-项目联系组件PRD.md)
- [`03-通用组件体系/04-媒体查看器组件PRD.md`](03-通用组件体系/04-媒体查看器组件PRD.md)
- [`03-通用组件体系/01-项目识别组件PRD.md`](03-通用组件体系/01-项目识别组件PRD.md)

## 2. 定义与边界

### 2.1 本文档中的“内容数据”和“素材”

- **内容数据**：项目名称、项目介绍、开发商名称、坐标、POI、户型、联系方式等可被 C 端读取和展示的项目事实。
- **素材**：项目 Logo、项目封面、POI 图片、户型图等用于展示的图片资源。
- **稳定数据键**：Widget 和组件依赖的业务语义名称，不等同于数据库字段名、接口 URL 或某一版后端响应字段。
- **数据适配层**：把现有项目接口、内容系统或素材服务映射为本文档稳定数据键的技术层。
- **Widget 实例配置**：决定某个 Widget 实例选用哪些项目内容、采用什么展示模式的配置，不是项目内容本身。

### 2.2 MVP 纳入范围

- 项目身份：项目名称、项目 Logo、开发商名称。
- 项目概览：项目介绍、单张封面图、公开项目地址、开发商名称。
- 项目地图：项目位置、地图注意事项、POI 分类、POI。
- 项目户型：户型名称/类型、LDK、面积、户型图、可选说明/标签及可选楼栋关系。
- 项目公共联系方式：官网、邮箱、电话。
- 上述对象共同使用的图片素材资料项。
- Google 地图服务是否可用这一运行依赖。

### 2.3 MVP 不纳入范围

- 页面布局、内容顺序、卡片样式、弹窗尺寸、动效或响应式视觉参数。
- A 端字段录入页面、上传控件、表单流程和权限界面。
- 数据库表、接口路径、API URL、鉴权令牌、Google API Key、CDN 实际地址。
- Widget 注册、启停、排序、页面集合、导航项、分享、国际化切换或埋点数据。
- 项目价格、房号、销售状态、样板间、WALK、VR、预约、个人销售联系人。
- 用户行为、浏览记录、地图操作记录和联系方式点击记录。
- 通过 Google 搜索、第三方网页或 AI 自动生成项目内容。

## 3. 总体数据规则

### 3.1 数据事实源与消费路径

```mermaid
flowchart LR
    A["项目接口 / 已发布内容 / 素材服务"] --> B["数据适配层"]
    B --> C["稳定项目数据键"]
    D["Widget 实例配置"] --> E["M-01 / M-20 / M-10"]
    C --> E
    C --> F["项目 Logo / 项目联系 / 图片查看器"]
    E --> G["三个独立 C 端页面"]
    F --> G
```

规则：

1. 项目接口、已发布内容和项目素材服务是事实来源；C 端不在运行时自行补写项目事实。
2. Widget 只记录数据键和项目内容对象的稳定标识，不保存 API URL、密钥或外部原始地址。
3. 数据适配层负责把不同来源字段映射为本文档语义，并完成坐标、空值、格式和发布状态校验。
4. 同一项目内容对象由多个页面复用，不为每个页面复制一份项目名称、POI、户型或联系方式。
5. 示例值、演示项目内容、其他项目内容和未发布内容不得作为缺失数据的回退值。

### 3.2 所有项目对象的共同约束

| 共同资料项 | 必需性 | 规则 |
| --- | --- | --- |
| `id` | 必需 | 对象在所属项目内稳定且唯一；发布后不得因名称修改而改变。 |
| `project_id` | 必需 | 必须与当前页面实例所属项目一致；禁止跨项目引用。 |
| `publication_status` | 必需 | C 端只消费已发布且允许公开调用的对象；草稿、停用、过期或待核实对象不可进入可用集合。 |
| `locale` | 文字对象必需 | 必须与页面实例发布语言完全一致；MVP 不跨语言回退。 |
| `sort_order` | 集合对象可选 | 仅表达项目内容默认顺序；Widget 有明确实例顺序时以实例顺序为准。 |

共同校验：

- 字符串去除首尾空白后为空，按缺失处理。
- 数字必须为有限数值，不接受 `NaN`、无穷值或以文案代替数值。
- 对象引用必须指向同一项目内真实存在且已发布的对象。
- 相同 `id` 出现冲突时，该对象不可进入 C 端，不以最后一条数据静默覆盖。
- C 端不得通过解析项目名称、户型名称或图片文件名推导结构化字段。

后续各对象表重点列出该对象自己的业务字段，不再重复 `project_id` 等共同资料项；除非表内另有说明，均继承本节约束。

### 3.3 单语言发布规则

- 页面实例必须带有唯一确定的发布语言。
- 项目名称、项目介绍、开发商名称、地图注意事项、分类名称、POI 名称/说明、户型名称/说明和组件文案使用同一语言上下文。
- 上游可以保存同一对象的多个语言版本，但数据适配层只向当前页面返回目标语言视图，并保留同一个稳定对象 `id`。
- 当前语言的必需文字缺失时执行对应发布校验或运行时异常，不自动读取另一语言。
- 无需翻译的事实字段，如坐标、数值面积、图片资源引用和电话号码，可以在不同语言内容中复用。

### 3.4 必填层级

本文档只区分两种会影响 C 端的必填性：

- **对象必需**：缺失时，依赖该对象的 Widget 或页面不允许发布。
- **字段必需**：对象存在但该字段无效时，该对象不可进入可用集合；若因此导致可用集合为空，则阻止发布。
- **可选**：无有效值时隐藏对应内容，不创建占位数据，不影响其他有效内容。

草稿保存、编辑表单何时提示以及 A 端如何展示校验错误，由 A 端需求定义；但 A 端不得绕过本文档的发布前置。

### 3.5 素材更新与下线

- C端每次打开或刷新页面时，读取页面已引用素材的最新可用内容；不保留旧素材供顾客选择或回看。
- 已引用素材内容更新后，页面以非阻断方式提示“页面内容有更新”。提示不展示内部版本号、更新明细、其他顾客信息或素材管理状态。
- 顾客确认提示后，在该顾客、该项目、该页面及当前素材版本组合下不再重复提示；素材再次更新时可以再次提示。确认状态绝对禁止跨项目复用。
- 素材下线、删除或变为不可用时，不让整页变为 403 或 404。相关 Widget 按其自身 PRD 隐藏、移除、显示局部错误或阻止后续发布；不得使用其他项目、未发布或无关素材补位。

### 3.6 顾客可见内容来源与收敛规则

本节适用于全部 C端页面、Widget、通用组件、系统状态页和原型。

| 内容类型 | 允许来源 | 缺失时处理 |
| --- | --- | --- |
| 项目事实、对象字段和媒体 | 当前项目、当前语言、已发布且被对应 PRD 明确引用的内容对象或素材 | 按 PRD 隐藏、局部降级或阻止发布，不生成替代内容。 |
| 页面级内容 | 页面 PRD 明确定义的标题、结构说明或页面动作 | 未定义则不展示，页面不得替 Widget 追加内容。 |
| Widget 内容 | 单项 Widget PRD 明确定义的内容名称、来源、必需性和显示条件 | 未定义或无有效值时不展示。 |
| 通用组件内容 | 调用方 PRD 明确定义并传入的内容，或组件 / 共享规则固定的状态与操作文案 | 未定义的可选槽位隐藏。 |
| 系统状态与操作文案 | 系统状态规则、组件 PRD 或调用方 PRD 中已固定的顾客文案 | 不根据错误细节、技术原因或 AI 推测生成。 |

以下内容不是合法来源：AI 生成或改写、Demo 页面布局和文案、旧版页面残留、其他项目内容、其他语言内容、设计稿装饰文字、原型评审说明、实现注释，以及通用组件仅声明“可选”但调用方未定义的槽位。它们不得进入顾客可见界面，也不得因已经出现在原型中而反向成为需求。

原型可以用代表值演示已定义字段和状态，但必须保持一一映射；代表值不构成项目真实资料或新增字段。所有内部标识、优先级、`Widget`、`iframe`、`Prototype`、线框说明和评审记录必须留在原型工作台或文档中，不得进入顾客页面区域。

## 4. 稳定数据键总览

| 稳定数据键 | 数据对象 | MVP 主要消费者 | 基数 |
| --- | --- | --- | --- |
| `project.identity` | 项目身份 | M-01、项目 Logo 组件、三个页面的项目上下文 | 每项目 1 个 |
| `project.images` | 项目公共图片素材集合 | M-01、M-20、M-10、图片查看器 | 每项目 0 至多个 |
| `project.introductions` | 项目介绍集合 | M-01 | 每项目 1 至多个，可由实例选择 1 个 |
| `project.location` | 项目位置 | M-01、M-20 | 每项目 1 个 |
| `project.map_notice` | 地图注意事项 | M-20 | 每项目当前语言 0 或 1 个 |
| `project.poi_categories` | POI 分类集合 | M-20 | 每项目 1 至多个 |
| `project.pois` | POI 集合 | M-20 | 每项目 1 至多个 |
| `project.floorplans` | 户型集合 | M-10、图片查看器 | 每项目 1 至多个 |
| `project.contact` | 项目公共联系方式 | 项目联系组件 | 每项目 1 个 |

稳定数据键表示业务语义，不要求后端直接使用相同 JSON 路径。后端字段与这些键不一致时，由数据适配层映射，不能要求 Widget 分别适配多套历史接口。

## 5. `project.identity`：项目身份

### 5.1 对象定义

项目身份是当前项目唯一的公开识别信息。MVP 不允许 M-01 单独维护另一套项目身份。

| 字段 | 类型 | 必需性 | 来源 | 校验与使用规则 | 缺失处理 |
| --- | --- | --- | --- | --- | --- |
| `name` | 文字 | 必需 | 项目基础信息接口 | 当前发布语言下非空；展示接口已发布名称。 | 不阻止 M-01 发布；由需要项目名称的其他调用方按各自规则处理。 |
| `locale` | 语言标识 | 必需 | 页面实例与项目基础信息 | 标识当前返回的项目名称和开发商名称语言，必须等于页面实例发布语言。 | 当前语言项目身份不可用。 |
| `logo_asset_id` | 图片素材引用 | 可选 | 项目基础信息接口 / 项目素材 | 指向同项目已发布的项目 Logo 图片；只由项目 Logo 通用组件显示。 | 隐藏项目 Logo 组件，不保留占位。 |
| `developer_name` | 文字 | 可选 | 项目基础信息接口 | 当前发布语言下有有效值时以“开发商名称”业务含义展示。 | 隐藏开发商名称及其标签、分隔符和空白。 |

### 5.2 项目 Logo 素材规则

- SVG 优先；也可使用带透明背景的 PNG 或 WebP。
- SVG 必须经过安全处理，不包含脚本、外部资源或可执行内容。
- 位图项目 Logo 长边不低于 512px，短边不低于 128px。
- 保留原始宽高比，不要求强制裁成正方形。
- 项目 Logo 的替代文字使用项目名称，不另写营销口号。
- 项目 Logo 不属于 M-01，不覆盖在项目封面内部；缺失或加载失败时隐藏，不使用 HOMEVISTA Logo 或文字项目名补位。
- 最终显示尺寸、明暗版本选择和背景适配属于 VISTA C 设计，字典不规定像素级布局。

## 6. `project.images` 与 `project.introductions`：项目概览内容

### 6.1 `project.images` 公共图片素材

图片素材是可被项目内容对象引用的公共素材集合。同一图片只维护一个素材对象，由 M-01、POI 或户型引用，不为页面复制文件。

| 字段 | 类型 | 必需性 | 校验与使用规则 |
| --- | --- | --- | --- |
| `id` | 标识 | 必需 | 同项目内稳定唯一。 |
| `usage_type` | 枚举 | 必需 | MVP 允许 `project_logo`、`project_cover`、`poi_image`、`floorplan_image`。 |
| `mime_type` | 枚举 | 必需 | 位图允许 JPEG、PNG、WebP；项目 Logo 额外允许安全 SVG。 |
| `width_px` | 正整数 | 位图必需 | 必须与实际文件一致。 |
| `height_px` | 正整数 | 位图必需 | 必须与实际文件一致。 |
| `file_size_bytes` | 正整数 | 必需 | 用于上传与传输策略校验；MVP 不在 C 端展示。 |
| `alt_text` | 文字 | 按用途 | 项目封面必需；户型图可由户型名称生成；POI 图片可由 POI 名称生成。 |
| `publication_status` | 状态 | 必需 | 只有已发布且允许公开调用的素材可被 C 端引用。 |

图片实际访问 URL、CDN 域名、响应式衍生图地址和签名参数不是稳定内容键，由素材服务和数据适配层在运行时提供。

### 6.2 `project.introductions` 项目介绍

| 字段 | 类型 | 必需性 | 校验与使用规则 |
| --- | --- | --- | --- |
| `id` | 标识 | 必需 | 供 M-01 Widget 实例稳定引用。 |
| `locale` | 语言标识 | 必需 | 必须等于页面实例发布语言。 |
| `body` | 纯文本 / 段落文本 | 必需 | 去除空白后非空；保留自然段和换行，不接受任意 HTML、脚本或嵌入对象。 |
| `publication_status` | 状态 | 必需 | 只有已发布版本可被 M-01 选择。 |

MVP 不由 C 端生成摘要、改写介绍或跨语言补齐。文案的字体、字号、段落间距与视觉层级属于 VISTA C 设计。

### 6.3 M-01 引用规则

M-01 Widget 实例只保存：

- 一个 `project.images` 中 `usage_type = project_cover` 的 `id`。
- 一个当前语言 `project.introductions` 对象的 `id`。

M-01 自动读取可选的 `project.identity.developer_name` 与 `project.location.address`，不在实例中复制地址或开发商名称。`project.identity.name` 和 `logo_asset_id` 由项目 Logo 或页面上下文等其他调用方单独消费，不传给 M-01。

### 6.4 项目封面素材质量门槛

- 必须是 JPEG、PNG 或 WebP 位图。
- 原图宽度不低于 1600px，且长边不低于 1920px。
- 保留原始宽高比；MVP 不要求固定横竖比例，也不以裁切后的局部图替代原图。
- C 端必须完整显示原图，不得以 `cover`/中心裁切填满容器；允许按图片比例调整容器或出现设计稿规定的留白。
- 画面不得依赖贴近边缘的小字号文字传达必要信息，以免响应式展示时不可读。
- 封面替代文字必需，描述图片内容或使用项目名称，不使用“图片”“封面”等无意义文本。
- 精确压缩率、文件体积上限、响应式衍生图尺寸和 CDN 格式协商为 **待技术设计**；不得因此降低上述原图质量门槛。

封面运行时加载失败时使用系统统一的中性默认底图。默认底图属于系统 UI 资源，不是项目内容数据，不得从其他项目图片、未发布素材或 AI 生成内容中随机补位；正式默认底图视觉待设计提供。

## 7. `project.location`、`project.map_notice` 与地图服务依赖

### 7.1 `project.location`

| 字段 | 类型 | 必需性 | 来源 | 校验与使用规则 |
| --- | --- | --- | --- | --- |
| `latitude` | 十进制度数 | 必需 | 项目位置数据 | WGS84；有限数值，范围 `[-90, 90]`。 |
| `longitude` | 十进制度数 | 必需 | 项目位置数据 | WGS84；有限数值，范围 `[-180, 180]`。 |
| `address` | 文字 | 可选 | 项目基础信息接口 | 仅作为项目位置说明数据；M-20 MVP 不依赖地址反查坐标。 |

规则：

- M-20 只使用已发布坐标作为项目锚点，不使用地址在 C 端实时地理编码。
- 非 WGS84 来源必须在数据适配层完成一次明确转换；C 端不得猜测坐标系。
- 项目坐标缺失或无效时阻止 M-20 发布，不允许用城市中心、设备定位或第一个 POI 代替项目位置。

### 7.2 `project.map_notice`

| 字段 | 类型 | 必需性 | 校验与使用规则 | 缺失处理 |
| --- | --- | --- | --- | --- |
| `id` | 标识 | 对象存在时必需 | 同项目内稳定唯一。 | 整个对象视为未定义。 |
| `locale` | 语言标识 | 对象存在时必需 | 必须等于页面实例发布语言。 | 当前语言视为未定义。 |
| `body` | 纯文本 / 段落文本 | 对象存在时必需 | 去除空白后非空；不接受脚本或任意 HTML。 | 不弹出注意事项。 |
| `publication_status` | 状态 | 对象存在时必需 | 只有已发布内容可展示。 | 不弹出注意事项。 |

注意事项是可选项目内容。有效对象存在时，M-20 按当前页面浏览会话首次进入规则弹出；不存在或无效时直接进入地图。

### 7.3 Google 地图服务依赖

Google 地图服务配置不是项目内容素材，不进入 Widget 实例，也不得在本文档记录密钥。

发布预检只判断当前部署环境是否具备有效的 Google 地图服务配置；运行时再判断服务是否成功加载。API Key、地图 ID、域名白名单、配额、加载器和监控方式由技术方案定义。

## 8. `project.poi_categories` 与 `project.pois`

### 8.1 POI 分类

| 字段 | 类型 | 必需性 | 校验与使用规则 |
| --- | --- | --- | --- |
| `id` | 标识 | 必需 | 同项目内稳定唯一。 |
| `name` | 文字 | 必需 | 当前语言非空；用于分类显示。 |
| `locale` | 语言标识 | 必需 | 必须等于页面实例发布语言。 |
| `sort_order` | 整数 | 可选 | 没有 Widget 实例顺序时作为默认顺序。 |
| `publication_status` | 状态 | 必需 | 只有已发布分类可进入候选集合。 |

只有至少关联一个有效 POI 的分类才进入 M-20 可用分类集合。

### 8.2 POI

| 字段 | 类型 | 必需性 | 来源 | 校验与使用规则 | 缺失处理 |
| --- | --- | --- | --- | --- | --- |
| `id` | 标识 | 必需 | 项目周边 POI 数据 | 同项目内稳定唯一。 | 该 POI 不可用。 |
| `name` | 文字 | 必需 | 项目周边 POI 数据 | 当前语言非空。 | 移除该 POI。 |
| `locale` | 语言标识 | 必需 | 项目周边 POI 数据 | 等于页面实例发布语言。 | 移除该 POI。 |
| `latitude` | 十进制度数 | 必需 | 项目周边 POI 数据 | WGS84，范围 `[-90, 90]`。 | 移除该 POI。 |
| `longitude` | 十进制度数 | 必需 | 项目周边 POI 数据 | WGS84，范围 `[-180, 180]`。 | 移除该 POI。 |
| `category_ids` | 标识数组 | 必需 | 项目周边 POI 数据 | 至少引用一个同项目已发布分类。 | 无有效分类时移除该 POI。 |
| `image_asset_id` | 图片素材引用 | 可选 | POI 关联图片 | 指向 `usage_type = poi_image` 的已发布素材。 | 信息卡隐藏图片区，不显示占位图。 |
| `summary` | 文字 | 可选 | POI 公开说明 | 只展示项目已发布内容。 | 隐藏摘要区域。 |
| `address` | 文字 | 可选 | POI 公开说明 | 仅展示，不用于自动推算路线、距离或时间。 | 隐藏地址区域。 |
| `sort_order` | 整数 | 可选 | 项目周边 POI 数据 | 没有 Widget 实例顺序时作为默认顺序。 | 使用稳定默认顺序。 |
| `publication_status` | 状态 | 必需 | 项目周边 POI 数据 | 只有已发布 POI 可进入候选集合。 | 移除该 POI。 |

### 8.3 M-20 引用规则

- M-20 Widget 实例从 `project.pois` 中选择可公开 POI，并可保存点位顺序。
- 分类来自所选 POI 关联的 `project.poi_categories`，无有效点位的分类不显示。
- 默认分类属于 Widget 实例配置；未配置或失效时使用第一个包含有效 POI 的分类。
- 初始地图范围由 M-20 根据 `project.location` 和默认分类有效 POI 自动计算，不存储人工中心点或缩放级别。
- POI 图片不存在时不使用项目封面、分类图标、Google 搜索图片或其他项目图片补位。

### 8.4 POI 图片素材质量门槛

- POI 图片可选；没有图片不降低 POI 的数据有效性。
- 有图片时允许 JPEG、PNG 或 WebP。
- 原图长边不低于 1200px，短边不低于 720px。
- 保留原始宽高比；具体裁切比例和信息卡显示尺寸属于 VISTA C 设计。
- POI 名称可作为替代文字来源，不要求项目另外维护营销型图片说明。
- 精确文件体积上限和响应式衍生图尺寸为 **待技术设计**。

## 9. `project.floorplans`：户型

### 9.1 户型对象

| 字段 | 类型 | 必需性 | 来源 | 校验与使用规则 | 缺失处理 |
| --- | --- | --- | --- | --- | --- |
| `id` | 标识 | 必需 | 项目户型数据 | 同项目内稳定唯一；用于卡片、筛选和查看器状态关联，C 端不展示。 | 该户型不可用。 |
| `name` | 文字 | 必需 | 项目户型数据 | 当前语言下的户型名称/类型名；不得从 LDK 或图片名推导。 | 该户型不可用。 |
| `locale` | 语言标识 | 必需 | 项目户型数据 | 等于页面实例发布语言。 | 该户型不可用。 |
| `layout_code` | 规范化文字 | 必需 | 项目户型数据 | 表达 LDK/格局，例如 `2LDK`、`3LDK+WIC`；按完整有效值形成 LDK 筛选选项。 | 该户型不可用。 |
| `area_sqm` | 正数 | 必需 | 项目户型数据 | 以平方米为统一计算口径；可含小数，用于显示和 10㎡区间筛选。 | 该户型不可用。 |
| `floorplan_image_asset_id` | 图片素材引用 | 必需 | 项目户型图 | 指向 `usage_type = floorplan_image` 的同项目已发布素材。 | 该户型不可用。 |
| `description` | 文字 | 可选 | 项目户型说明 | 当前语言有值时展示。 | 隐藏说明。 |
| `tags` | 文字数组 | 可选 | 项目户型标签 | 只作卡片可选内容；MVP 不用标签筛选。 | 隐藏标签。 |
| `building_id` | 标识 | 可选 | 项目建筑关系 | 只用于已有明确楼栋关系的分组；不得从户型名解析。 | 不显示楼栋分组。 |
| `building_name` | 文字 | `building_id` 有效时必需 | 项目建筑关系 | 当前语言下用于分组显示。 | 楼栋关系整体不可用。 |
| `sort_order` | 整数 | 可选 | 项目户型数据 | 没有 Widget 实例顺序时作为默认顺序。 | 使用稳定默认顺序。 |
| `publication_status` | 状态 | 必需 | 项目户型数据 | 只有已发布且允许公开调用的户型可进入候选集合。 | 该户型不可用。 |

说明：

- `name` 与 `layout_code` 是两个独立字段。户型筛选使用 `name`，LDK 筛选使用 `layout_code`。
- 面积显示由 `area_sqm` 加统一单位 `㎡` 生成，不另外维护可能与数值冲突的自由文本面积。
- 面积区间不是项目内容字段。M-10 基于本 Widget 全量可用户型的 `area_sqm` 自动生成 10㎡左闭右开区间。
- 价格、销售状态、房号、楼层、内览、样板间、WALK/VR 关联不进入 M-10 MVP 数据。

### 9.2 M-10 引用规则

M-10 Widget 实例只保存：

- 从 `project.floorplans` 选择的户型 `id` 集合及实例顺序。
- `display_mode`：`list`、`carousel` 或 `single_card`。
- 是否显示可选说明/标签。

`display_mode` 是 Widget 实例配置，不是户型字段。缺失或非法时由 M-10 降级为 `list`；`single_card` 模式必须且只能引用一个有效户型。

### 9.3 户型图素材质量门槛

- 必须提供 JPEG、PNG 或 WebP 图片；PDF、CAD、PPT 不作为 MVP 图片查看器的直接输入。
- 图片必须包含完整户型图，禁止为了卡片展示裁掉图纸、图例或必要标注。
- 原图长边不低于 2400px，短边不低于 1600px，以支持至少 200% 放大查看。
- 文字、尺寸和房间标注在 200% 放大后应清晰可辨；素材本身模糊时不得依赖前端锐化或 AI 补图。
- 保持原始宽高比；背景透明与否不作为发布前置。
- 替代文字可按“项目名称 + 户型名称 + 户型图”生成，不使用文件名。
- 精确文件体积上限、缩略图规格、响应式衍生图和最大缩放倍数为 **待技术设计**；不得改变完整图纸和最低分辨率要求。

## 10. `project.contact`：项目公共联系方式

### 10.1 对象定义

`project.contact` 是整个项目复用的一组公共联系方式，不是个人销售联系信息。三个 MVP 页面使用同一个对象。

| 字段 | 类型 | 必需性 | 来源 | 有效性规则 | 无效或缺失处理 |
| --- | --- | --- | --- | --- | --- |
| `phone.display` | 文字 | 电话存在时必需 | 项目公共联系数据 | 可供用户阅读的公开电话号码。 | 电话项无效。 |
| `phone.dial_value` | 文字 | 电话存在时必需 | 项目公共联系数据 | 只包含可安全用于 `tel:` 的国际/地区号码字符；不得带营销文案。 | 电话项无效。 |
| `email` | 文字 | 可选 | 项目公共联系数据 | 基本邮箱格式有效，去除首尾空白；不要求发送验证邮件。 | 隐藏邮箱项。 |
| `website` | 绝对 URL | 可选 | 项目公共联系数据 | 使用 `http` 或 `https` 协议的完整公开网址；MVP 只做格式与安全协议校验，不以实时连通性作为发布阻断。 | 隐藏官网项。 |
| `publication_status` | 状态 | 必需 | 项目公共联系数据 | 对象必须已发布并允许公开使用。 | 整个对象不可用。 |

发布规则：

- `phone`、`email`、`website` 三者至少一项有效，三个 MVP 页面才允许发布。
- 某一项无效时不影响其他有效项。
- 三项都缺失或无效时阻止发布，不使用开发商官网、个人销售电话或其他项目联系方式补位。
- 页面运行时某项失效则隐藏该项；三项均运行时失效时，项目联系组件显示局部错误并允许关闭。
- 电话动作只调起设备拨号能力，不自动拨出；邮箱不预填营销正文；官网只打开已配置网址。

## 11. Widget 与组件消费映射

| 消费者 | 必需数据 | 可选数据 | 实例配置 | 必需数据失效 |
| --- | --- | --- | --- | --- |
| M-01 项目概览 | 一个有效项目封面、一个当前语言纯文本项目介绍 | `project.location.address`、`project.identity.developer_name` | `cover_asset_id`、`introduction_id` | 阻止发布；运行时封面失败使用系统默认底图，文字接口失败进入 Widget 局部错误。 |
| M-20 周边地图 | `project.location`、可用 Google 地图服务、至少一个有效分类和 POI | `project.map_notice`、POI 图片/摘要/地址 | POI 选择与顺序、分类顺序、默认分类 | 阻止发布；运行时单个 POI 失效时移除，地图服务失败进入 Widget 局部错误。 |
| M-10 户型卡片列表 | 至少一个名称、LDK、面积、户型图完整的户型 | 说明、标签、楼栋关系 | 户型选择与顺序、`display_mode`、可选内容显示 | 无有效户型时阻止发布；运行时个别户型失效时移除。 |
| 项目 Logo 组件 | 无必需数据 | `project.identity.logo_asset_id` | 无页面级显隐或排序配置 | 缺失或运行时失败时隐藏，不使用替代品牌或文字 Logo。 |
| 项目联系组件 | `project.contact` 中至少一项有效联系方式 | 其余联系方式 | 无页面级显隐或排序配置 | 发布前全部无效则阻止发布；运行时全部无效显示组件局部错误。 |
| 图片查看器 | 当前户型的有效户型图和户型稳定标识 | 替代文字 | 无独立内容配置 | 加载失败只显示查看器局部错误，可关闭返回。 |

## 12. 发布前校验与运行时降级总表

| 对象 / 场景 | 发布前 | 运行时 |
| --- | --- | --- |
| 项目名称缺失 | 不阻止项目概览 Widget 发布。 | M-01 不显示项目名称，也不使用其他语言或项目名补位。 |
| 项目 Logo 或开发商名称缺失 | 允许发布。 | Logo 组件或开发商名称分别隐藏，不留标签、分隔符或空白。 |
| 项目封面缺失/无效 | 阻止项目概览页发布。 | 显示系统统一默认底图，介绍、地址及开发商名称继续可读。 |
| 项目介绍缺失/语言不匹配 | 阻止项目概览页发布。 | 显示 M-01 局部错误与重试，不自动生成文案。 |
| 项目位置缺失/坐标无效 | 阻止地图页发布。 | 显示 M-20 局部错误，不用设备定位或 POI 替代。 |
| 地图注意事项缺失/无效 | 允许发布。 | 不弹出空弹窗。 |
| POI 图片缺失 | 允许发布。 | 隐藏图片区，不显示替代图片。 |
| 个别 POI 必需字段无效 | 不计入可用 POI；若无可用 POI 则阻止发布。 | 移除该点位，其他点位继续使用。 |
| Google 地图服务配置缺失或发布预检无效 | 阻止依赖地图的页面发布。 | 已有有效配置但运行时加载失败时，进入 M-20 局部错误与重试，不进入 403/404。 |
| 个别户型必需字段无效 | 不计入可用户型；若无可用户型则阻止发布。 | 移除该户型，不显示空卡片。 |
| 单卡片模式不是一个有效户型 | 阻止 M-10 发布。 | 若历史或脏数据绕过发布校验，按非法展示配置安全降级为列表。 |
| 联系方式全部无效 | 阻止三个 MVP 页面发布。 | 联系组件显示局部错误，不影响页面主体。 |
| 图片查看器大图加载失败 | 不单独改变发布结果；户型图源仍须通过发布校验。 | 查看器局部错误，可关闭并恢复原页面状态。 |
| 已引用素材内容更新 | 不改变已发布页面访问资格。 | 读取最新内容，并显示“页面内容有更新”非阻断提示；顾客确认后在当前素材版本组合内不重复提示。 |
| 已引用素材下线、删除或不可用 | 后续发布按对应 Widget 的必需性校验。 | 按对应 Widget 的局部降级规则处理，不使整页变为 403 或 404。 |

## 13. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-DATA-01 | 后端字段名与稳定数据键不同 | 数据适配层完成映射 | Widget 只按本文档稳定语义读取，不保存或判断 API URL。 |
| AC-DATA-02 | 页面实例发布语言确定 | 加载全部文字对象 | 只返回该语言已发布内容，缺失时不跨语言回退。 |
| AC-DATA-03 | 某对象引用其他项目或未发布素材 | 执行发布校验 | 引用无效，不进入 C 端可用集合。 |
| AC-DATA-04 | M-01 配置完整 | 执行发布校验 | 一个封面和一个当前语言纯文本介绍有效；项目地址、开发商名称和项目 Logo 不作为发布前置。 |
| AC-DATA-05 | 地图项目包含无图 POI | 打开 POI 信息卡 | POI 保持有效，图片区隐藏且不使用占位图。 |
| AC-DATA-06 | 地图项目有多个有效 POI | 首次加载 M-20 | 初始范围由项目坐标和默认分类 POI 自动计算，不读取人工中心点或缩放级别。 |
| AC-DATA-07 | 户型名称、LDK 和面积同时存在 | 生成筛选项 | 名称与 LDK 分别形成选项；面积只使用 `area_sqm` 生成 10㎡区间。 |
| AC-DATA-08 | 户型图达到最低分辨率 | 图片查看器放大到至少 200% | 完整图纸和必要标注可辨，不因卡片裁切丢失内容。 |
| AC-DATA-09 | 官网、邮箱、电话只有一项有效 | 发布任一 MVP 页面 | 允许发布，联系弹窗只展示该有效项。 |
| AC-DATA-10 | 官网、邮箱、电话全部缺失或无效 | 尝试发布任一 MVP 页面 | 阻止发布并指出需要补充项目公共联系方式。 |
| AC-DATA-11 | 数据包含空字符串、重复 ID、非法坐标或失效引用 | 执行校验 | 对应字段或对象按本文档判定无效，不静默生成默认项目事实。 |
| AC-DATA-12 | 构造正常、可选项缺失、单对象失效、集合为空四类数据 | 执行页面测试 | 分别进入正常、隐藏/降级、移除/局部错误、阻止发布或空状态，结果与消费映射一致。 |
| AC-DATA-13 | 项目封面正常加载 | 任一响应式视口显示 | 原图保持宽高比并完整可见，不使用中心裁切或填满裁切。 |
| AC-DATA-14 | 项目封面运行时失败 | M-01 降级 | 使用系统统一默认底图，不读取其他项目或未发布图片。 |
| AC-DATA-15 | 项目 Logo 有效或缺失 | 页面渲染 | 由项目 Logo 组件独立显示或隐藏，M-01 不重复消费。 |
| AC-DATA-16 | 已引用素材内容发生更新 | 顾客打开或刷新页面 | C端读取最新内容并显示非阻断“页面内容有更新”提示；确认后同一顾客在当前页面的当前素材版本组合内不重复提示。 |
| AC-DATA-17 | 已引用素材下线、删除或不可用 | 顾客打开页面 | 对应 Widget 按自身规则局部降级，页面不变为 403/404，也不使用无关素材补位。 |

## 14. 非阻塞技术与设计待定项

以下事项不改变本字典的产品数据语义，但必须在开发实现前由对应方案补齐：

- 数据适配层的实际接口字段映射、缓存、刷新和错误码。
- 图片上传文件体积上限、压缩质量、响应式衍生图、CDN URL 和缓存策略。
- 图片查看器最大缩放倍数和缩放步长。
- Google API Key、地图 ID、域名白名单、配额、加载策略与服务监控。
- VISTA C 项目 Logo 显示尺寸、封面整图容器与留白方案、默认底图视觉、长文自动滚屏参数、弹窗尺寸、控件视觉和动效。

其中 VISTA C 弹窗、图片查看和地图组件存在的精确视觉缺口统一标记为 **待设计系统补充**，不得把临时原型尺寸反写为数据规则。

## 15. 供 Codex 使用的执行说明

- 新增字段前先判断它是项目事实、素材、Widget 实例配置、页面规则还是技术实现；只有前两类进入本文档。
- 不得把 Widget 实例的展示模式、页面布局、筛选 UI 或地图视野保存为项目内容。
- 不得把 API URL、数据库表名、密钥、CDN 域名或历史接口字段当作稳定数据键。
- 生成接口类型、校验器、测试数据或原型时，应以第 4 至 12 节为事实源。
- 遇到未定义的内容字段时标记“待产品确认”，不得从截图、文件名或其他项目内容自行推导。
- 原型重建时使用 VISTA C 设计系统；不得把 A 端/B 端后台字段编辑样式带入 C 端页面。