# HOMEVISTA A端 Widget、模板与实例字段字典

> 文档版本：v0.22
>
> 关联 PRD：`01-A端Widget与页面模板管理PRD.md`

## 修订记录

| 版本 | 日期 | 变更类型 | 变更摘要 | 修改人 / 来源 |
|---|---|---|---|---|
| v0.1-v0.8 | 2026-07-16 至 2026-07-20 | 历史修订汇总 | 建立 Widget、模板、实例字段，收口发布快照、长期有效及实例不可切换模板规则。 | 产品讨论 / Codex |
| v0.9 | 2026-07-20 | **重大字段模型变更** | 新增 Widget 三类内容属性和表现形式；页面模板改为 A端编排的有序 Widget 区块；实例内容按区块保存，区块表现形式只读。 | 销售沟通 / 产品确认 / Codex |
| v0.10 | 2026-07-20 | 页面用语映射 | 增加业务页面用语与技术字段映射；明确技术字段只在字段字典、接口和开发实现中使用，原型页面显示人话名称。 | 产品评审 / Codex |
| v0.11 | 2026-07-20 | **重大字段模型变更：Widget 注册先行** | Widget 标识改为注册时由系统生成；注册属性收敛为名称、内容配置方式、内容说明和展示方式；增加待开发、待验证状态，并删除 A端的资产类型和输入契约字段。 | 产品评审 / Codex |
| v0.12 | 2026-07-20 | **重大字段模型变更：展示尺寸** | 展示方式增加说明和支持尺寸；新增小、中、大全局枚举，模板区块同时保存展示方式和尺寸规格。 | 产品确认 / Codex |
| v0.13 | 2026-07-20 | **重大字段模型变更：状态简化** | 删除 `pending-development`；Widget 注册后直接进入 `pending-verification`，MVP 由人工确认上线转为 `enabled`，不保存虚假的自动验证结果。 | 产品确认 / Codex |
| v0.14 | 2026-07-20 | **重大字段模型变更：删除展示方式对象** | 删除 `presentation_modes` 和模板区块的 `presentation_mode`；Widget 仅保存 `supported_display_sizes`，模板区块只保存一个 `display_size`。 | 产品确认 / Codex |
| v0.15 | 2026-07-20 | Widget 引用参数澄清 | 明确 `widget_occurrence` 是 Widget 在模板中的一次独立引用，`display_size` 是该引用的配置参数；同一 `widget_id` 的多个引用可保存相同或不同规格。 | 产品确认 / Codex |
| v0.16 | 2026-07-20 | Widget 区块排序规则 | 明确拖拽完成后重新计算并保存 `sort_order`，用于项目页面生成及顾客端渲染顺序。 | 产品确认 / Codex |
| v0.17 | 2026-07-20 | **重大字段模型变更：模板注册与发布** | 页面模板增加开发前生成的稳定 `template_id`、部署发布标识和待验证状态；项目页面固化模板发布引用及区块结构。 | 产品确认 / Codex |
| v0.18 | 2026-07-20 | 模板字段精简 | MVP 删除 `template_category`，不在前端或数据模型中保留未使用的模板分类字段。 | 产品确认 / Codex |
| v0.19 | 2026-07-21 | **重大字段模型变更：项目级主题** | `theme_id` 和主题值从页面实例及发布内容中移除；页面通过 `project_id` 读取项目当前有效主题，主题更新不产生页面未发布修改。 | 产品确认 / Codex |
| v0.20 | 2026-07-28 | **重大字段模型变更：Widget 数据来源** | Widget 注册增加单选 `data_source`，固定九项业务标识；模板区块固化该标识，项目页面需要选择内容时按标识确定数据范围。技术接口映射不在本字段字典定义。 | 产品确认 / Codex |
| v0.21 | 2026-07-28 | Widget 注册字段分组优化 | 页面字段分为唯一标识、Widget 定义、展示规则；明确 `widget_id` 不可修改，`display_name` 允许修改且不影响标识和既有引用。 | 产品确认 / Codex |
| v0.22 | 2026-07-28 | **重大字段模型变更：C端分类统一** | 新增 `widget_category` 七项业务分类；`data_source` 改为十项 C端资产对象标识，将公共区、外景、资料集等旧值替换为公共空间、建筑与楼栋、眺望与景观、资料文件。 | 产品确认 / Codex |

## 0. 说明

本文是产品字段说明，不等同于数据库或接口设计。字段来源分为“A端注册”“开发部署后读取”“A端模板配置”“项目配置”“系统生成”。

### 0.1 页面用语与技术字段映射

| A端页面显示 | 技术字段 / 技术用语 | 使用规则 |
|---|---|---|
| Widget 标识 | `widget_id` | 页面显示，并说明由系统生成、注册后固定，开发必须使用。 |
| Widget 分类 | `widget_category` | 页面显示 C端七类功能模块分类，用于业务归类，不映射接口。 |
| 模板标识 | `template_id` | 页面显示，并说明由系统生成、注册后固定，开发必须使用。 |
| 内容配置方式 | `content_config_mode` | 页面显示“自动带入、选择项目内容、自定义内容”，不显示旧的内容类型或输入契约。 |
| 数据来源 | `data_source` | 页面显示受控中文选项；技术字段只保存稳定业务标识，不保存接口地址。 |
| 内容说明 | `content_description` | 一段人话说明内容从哪里来、可以使用什么内容；不是接口或数据结构定义。 |
| 支持的展示规格 | `supported_display_sizes` | Widget 注册页显示小、中、大三个复选项。 |
| 展示规格 | `display_size` | 模板和项目页面显示“小 · 半宽、中 · 通栏、大 · 全屏”，不显示代码值。 |
| Widget 区块 | `widget_occurrence` | 页面不显示 occurrence；表示 Widget 在模板中的一次独立使用记录。每次添加或重复添加都会生成新的 Widget 区块。 |
| 项目页面 | 页面实例 / `instance` | 页面统一称“项目页面”；字段字典和接口可以继续使用 instance。 |
| 允许未登录顾客查看 | `anonymous_access` | 页面不显示“匿名访问”。 |
| 当前线上内容 | `published_snapshot` | 页面不显示“发布快照”或快照编号。 |
| 有尚未发布的修改 | `has_unpublished_changes` | 页面不显示“工作稿与快照不一致”。 |
| 模板发布记录 | `template_definition_release_ref` | MVP 页面不展示发布引用，只由系统固化，用于保护已有项目页面。 |

## 一、固定枚举

| 字段 | 可选值 | 说明 |
|---|---|---|
| `content_config_mode` | `auto` / `project-selection` / `custom` | 分别表示自动带入、选择项目内容、自定义内容。 |
| `display_size` | `small` / `medium` / `large` | 分别表示小半宽、中通栏、大全屏；响应式行为由全局规则统一定义。 |
| `widget_category` | `project-base` / `architecture-space` / `spatial-experience` / `resident-product` / `surrounding-environment` / `resource-content` / `system-capability` | 分别表示项目基础、建筑与空间、空间体验、住户产品、周边环境、资料内容、系统能力。 |
| `data_source` | `project-basic-info` / `floor-info` / `floorplan` / `resident` / `model-room` / `public-space` / `building-and-tower` / `view-landscape` / `resource-file` / `other` | 分别表示项目基本信息、楼层信息、户型、住户、样板间、公共空间、建筑与楼栋、眺望与景观、资料文件、其它（无需选择数据）。 |
| `registration_status` | `pending-verification` / `enabled` / `disabled` | Widget 和模板注册后直接待验证；MVP 人工确认代码部署完成后启用。仅启用对象可被下一层新建流程使用。 |
| `instance_status` | `draft` / `online` / `offline` | 草稿、已上线、已下线。 |

## 二、Widget 注册记录

页面分组如下：

- **唯一标识**：仅展示 `widget_id`，由系统生成，注册后不可修改。
- **Widget 定义**：包含 `display_name`、`widget_category`、`content_config_mode`、`data_source`、`content_description`。
- **展示规则**：包含 `supported_display_sizes`。

| 字段 | 含义 | 来源 | 必填 | 可修改 | MVP 规则 |
|---|---|---|---|---|---|
| `widget_id` | Widget 稳定 ID | 系统生成 | 是 | 否 | 注册时生成，全局唯一且长期不变；开发必须使用。 |
| `display_name` | Widget 名称 | A端注册 | 是 | 是 | 给产品、交付和开发识别；启用后的改名不改变标识。 |
| `widget_category` | Widget 分类 | A端注册 | 是 | 是 | 单选 C端功能模块分类，用于归类和筛选；不决定数据接口。启用后的调整不改变 Widget 标识。 |
| `content_config_mode` | 内容配置方式 | A端注册 | 是 | 是 | `auto`、`project-selection`、`custom` 三选一；启用后的变更需重新验证。 |
| `data_source` | 数据来源 | A端注册 | 是 | 是 | 单选受控枚举；`project-selection` 不得选择 `other`。启用后的变更需重新验证。 |
| `content_description` | 内容说明 | A端注册 | 是 | 是 | 合并说明内容来源和可用内容，仅供人阅读；启用后的变更需重新验证。 |
| `supported_display_sizes` | 支持的展示规格 | A端注册 | 是 | 是 | `small`、`medium`、`large` 至少选择一个，最多全选；启用后的变更需重新确认上线。 |
| `definition_release_id` | 已部署发布标识 | 开发部署后读取 | 待验证后是 | 否 | 每次部署形成新的发布标识，不改变 `widget_id`。 |
| `definition_release_ref` | 已部署 Widget 引用 | 系统生成 | 待验证后是 | 否 | 由 `widget_id + definition_release_id` 组成。 |
| `registration_status` | 注册状态 | 系统 / A端操作 | 是 | 是 | 注册后待验证；人工确认上线后启用；停用后不能加入新模板。 |

说明：A端注册的是 Widget 的管理身份和业务属性，不制作 Widget 内容，也不定义接口结构。`widget_category` 用于业务归类，`data_source` 用于标识项目内容选择范围，两者都不是接口名称；接口地址、请求参数、返回结构和调用方案由工程师根据需求文档另行设计。MVP 不执行自动验证，也不保存虚假的“验证通过”结果。后续增加自动验证时，可检查实际 Widget 是否使用已分配标识，以及内容配置方式、数据来源和支持规格是否与注册记录一致；具体输入控件、数据结构和各规格下的容器内表现由 Widget 代码实现。

## 三、页面模板记录

| 字段 | 含义 | 来源 | 必填 | 可修改 | MVP 规则 |
|---|---|---|---|---|---|
| `template_id` | 模板稳定 ID | 系统生成 | 是 | 否 | 注册时生成，全局唯一且长期不变；开发必须使用。 |
| `display_name` | 模板名称 | A端模板配置 | 是 | 是 | 不能为空。 |
| `customer_task` | 核心顾客任务 | A端模板配置 | 是 | 是 | 用人话说明页面帮助顾客完成什么。 |
| `widget_occurrences` | 有序 Widget 区块 | A端模板配置 | 是 | 是 | 至少一个；允许同一 `widget_id` 多次出现。 |
| `template_definition_release_id` | 已部署模板发布标识 | 开发部署后读取 | 待验证后是 | 否 | 每次代码部署形成新的发布标识，不改变 `template_id`。 |
| `template_definition_release_ref` | 已部署模板引用 | 系统生成 | 待验证后是 | 否 | 由 `template_id + template_definition_release_id` 组成。 |
| `registration_status` | 模板状态 | 系统 / A端操作 | 是 | 是 | 注册后待验证；人工确认上线后启用；停用后不能创建新项目页面。 |

说明：A端登记的 `widget_occurrences` 只描述模板中需要按项目动态配置的内容区域。模板代码可以包含页头、导航等通用组件和固定非区块内容；这些内容不进入 A端字段，也不得依赖项目或实例配置。

### 3.1 Widget 区块 `widget_occurrence`

| 字段 | 含义 | 来源 | 必填 | 可修改 | MVP 规则 |
|---|---|---|---|---|---|
| `occurrence_id` | 区块唯一 ID | 系统生成 | 是 | 否 | 同一模板配置内唯一；不可只用 `widget_id` 代替。 |
| `occurrence_name` | 区块名称 | A端模板配置 | 是 | 是 | 例如“A户型推荐”“小户型推荐”。 |
| `widget_id` | 引用 Widget | A端模板配置 | 是 | 是 | 只能选择已启用 Widget。 |
| `content_config_mode_snapshot` | 内容配置方式记录 | 系统读取 | 是 | 否 | 用于项目页面决定是否需要人工配置。 |
| `data_source_snapshot` | 数据来源记录 | 系统读取 | 是 | 否 | 用于需要人工选择内容时确定当前项目的数据范围。 |
| `content_description_snapshot` | 内容说明记录 | 系统读取 | 是 | 否 | 保留模板创建时的业务说明。 |
| `sort_order` | 页面顺序 | A端模板配置 | 是 | 是 | 拖拽完成后按当前列表顺序重新计算；同一模板内不重复，项目页面和顾客端按升序渲染。 |
| `display_size` | 本 Widget 区块展示规格参数 | A端模板配置 | 是 | 是 | 必须属于 Widget 的 `supported_display_sizes`；按 `occurrence_id` 独立保存，同一 Widget 的多个区块可相同或不同；项目页面中不可改。 |

## 四、项目页面（技术对象：页面实例）

| 字段 | 含义 | 来源 | 必填 | 可修改 | MVP 规则 |
|---|---|---|---|---|---|
| `instance_id` | 实例唯一 ID | 系统生成 | 是 | 否 | C端链接引用该对象，不引用模板。 |
| `project_id` | 所属项目 | 项目配置 | 是 | 否 | 只能绑定一个项目。 |
| `instance_name` | A端识别名称 | 项目配置 | 是 | 是 | 不影响模板结构。 |
| `template_id` | 来源模板 | 项目配置后固化 | 是 | 否 | 实例生成后不能切换。 |
| `template_definition_release_ref` | 来源模板发布引用 | 系统固化 | 是 | 否 | 指向创建页面时已确认上线的模板代码发布。 |
| `template_structure_snapshot` | 来源模板区块结构 | 系统固化 | 是 | 否 | 固化 Widget 区块、顺序和展示规格；模板后来修改不得改变该实例结构。 |
| `anonymous_access` | 是否允许未登录顾客查看 | 项目配置 | 是 | 是 | 关闭时由销售端授权具体顾客。 |
| `widget_content_values` | 各区块内容 | 项目配置 / 系统读取 | 是 | 是 | 按 `occurrence_id` 保存，不能只按 `widget_id` 保存。 |
| `instance_status` | 实例状态 | 系统 / A端操作 | 是 | 是 | 默认长期有效，直至下线。 |
| `published_snapshot` | 当前线上内容记录 | 系统生成 | 上线后是 | 否 | 包含访问方式和各区块内容，不包含项目主题。 |
| `has_unpublished_changes` | 是否有尚未发布的修改 | 系统计算 | 是 | 否 | 草稿内容与当前线上内容不一致时为真。 |

### 4.1 区块内容 `widget_content_value`

| 字段 | 规则 |
|---|---|
| `occurrence_id` | 必须对应模板中的区块 ID；重复 Widget 分别保存。 |
| 自动带入 | 不要求人工值，Widget 按项目上下文读取。 |
| 选择项目内容 | 保存 Widget 返回的当前项目内容选择结果；示例可为户型 ID 列表或视频 ID。 |
| 自定义内容 | 保存 Widget 返回的页面专用内容；示例可为文字及图片、视频等内容项。 |

### 4.2 项目主题引用规则

- 页面实例不保存 `theme_id` 或主题颜色副本。
- 页面通过 `project_id` 读取项目当前有效主题。
- 项目未定义个性化主题时读取 VISTA 默认主题。
- 主题更新不改变 `published_snapshot` 或 `has_unpublished_changes`；详细字段见 `05-A端项目主题管理PRD.md`。

## 五、字段级校验

1. 模板不得引用未启用 Widget。
2. 区块展示规格必须属于被引用 Widget 的 `supported_display_sizes`。
3. 同一模板可包含不同或相同 `widget_id`；每个 `widget_occurrence` 必须有不同 `occurrence_id`，并独立保存 `display_size`，不得按 `widget_id` 合并或联动覆盖。
4. 待验证模板不得用于创建项目页面；人工确认上线前必须确认模板代码使用正确 `template_id`，且依赖 Widget 均已启用。
5. 项目页面按区块内容配置方式调用 Widget 提供的配置界面，但不提供展示规格修改入口。
6. 所有“选择项目内容”或“自定义内容”区块未得到有效内容时允许保存草稿，禁止上线。
7. 模板修改不得回写既有实例的模板发布引用或区块结构。
8. `data_source` 必须属于受控枚举；`project-selection` 不能使用 `other`。
9. `other` 只表示无需选择项目数据，不能作为未定义数据来源的兜底值。
10. `widget_category` 必须属于 C端七类功能模块分类；它只用于业务归类，不得据此推断数据接口或项目内容范围。

## 六、全局响应式映射

| `display_size` | PC端 | 移动端 |
|---|---|---|
| `small` | 半宽；连续小规格可一行两列。 | 全宽紧凑展示。 |
| `medium` | 通栏、独占一行，高度随内容。 | 通栏、独占一行，高度随内容。 |
| `large` | 通栏并以一个安全可视区域为目标。 | 通栏并以当前设备安全可视区域为目标。 |

实现不得把中规格固定成 `50vh`，也不得把大规格机械写死为 `100vh` 后裁切内容。设备安全区域、浏览器栏和内容溢出由前端响应式实现处理。