# HOMEVISTA A端 Widget 管理 PRD

> 文档版本：v0.26
>
> 所属终端：A端（装配交付与服务支持端）
>
> 适用对象：产品、服务商、供应商、设计、开发、测试、Codex

## 修订记录

| 版本 | 日期 | 变更类型 | 变更摘要 | 备注 |
|---|---|---|---|---|
| v0.1 | 2026-07-28 | 初始创建 / 文档结构重构 | 从原01、03、04文档迁移 Widget 管理、注册、编辑、状态、字段和验收规则，建立 Widget 管理唯一事实源。 | 原文及历史修订记录见 `archive/`。 |
| v0.2 | 2026-07-28 | **重大编辑规则变更** | Widget注册后除标识外的登记信息全部允许修改；修改直接保存且不改变当前状态，不再强制下线或重新进入待验证。已有模板和项目页面不被改写。 | 产品确认。 |
| v0.3 | 2026-07-28 | **重大交互结构变更** | Widget注册与编辑统一复用同一套全屏表单、字段分区和校验规则；编辑不再使用弹窗，弹窗只承担上线、停用等短确认操作。 | 产品评审纠正。 |
| v0.4 | 2026-07-28 | **重大 MVP 数据范围收敛** | MVP删除“资料文件”数据来源，不预置单文件夹引用 Widget，不实施资料集相关页面内容选择；资料类能力待后续需求明确后重新登记。 | 产品确认。 |
| v0.5 | 2026-07-28 | **重大内容选择规则补充** | “选择项目内容”增加必选的单选/多选登记规则，供项目页面统一数据选择弹窗决定交互；“其它”明确为无需A端选择项目数据，只能与自动带入或自定义内容配合。 | 跨文档评审后产品确认。 |
| v0.6 | 2026-07-30 | **重大 Widget 注册边界与元数据规则变更** | Widget标识改为人工填写并校验全局唯一，首次上线前允许修改、首次上线后永久锁定；名称、分类、简介收敛为A端可编辑的管理字段；内容配置方式、数据来源、选择数量统一定义为代码提供、A端读取的只读“Widget元数据”；MVP删除展示规则及小、中、大规格。 | 产品确认；产品评审补齐元数据读取闭环；列表精简为不展示元数据列。 |
| v0.7 | 2026-07-30 | **重大 Widget 下游使用范围变更** | 已启用 Widget除可加入页面模板外，也可直接加入已创建项目页面并形成独立页面模块；加入时复制当前Widget标识、名称和元数据，之后Widget停用或修改不回写既有页面模块。 | 产品确认。 |
| v0.8 | 2026-08-03 | **重大 Widget 能力定义边界补充** | 开发按 Widget 提供能力定义，A端只读使用；不采用跨所有 Widget 的固定字段表。明确内容／素材类 Widget 的多内容范围和不兼容变更新标识要求。 | 产品确认清单。 |
| v0.9 | 2026-08-04 | **重大协同与元数据快照规则补充** | 明确 Widget 元数据由系统在引用时固化为只读快照；补充无权限与多人并行编辑时的页面表现，防止误改或静默覆盖。 | 对照 A端前端技术架构设计文档后的产品确认。 |
| v0.10 | 2026-08-04 | **重大项目内容来源字典与实例配置规则补充** | 明确项目内容来源字典由 A端维护；Widget 仅声明可使用的来源分类及选择规则，项目页面按该规则列出当前项目的候选数据并供操作人员勾选。 | 产品确认。 |
| v0.11 | 2026-08-04 | **重大 Widget 内容范围归属修订** | 取消 A端维护全局项目内容来源字典；Widget 可配置的内容对象与组合规则改由开发随每个 Widget 能力定义提供，A端只读使用。 | 2026-08-04 跨端评审确认。 |
| v0.12 | 2026-08-04 | **重大项目内容分类与配置方式重构** | 恢复 22 项项目内容分类，明确其用于组织可选择内容而非定义来源类型；内容配置方式仅保留自动带入和选择项目内容，取消自定义内容。 | 产品确认。 |
| v0.13 | 2026-08-04 | **重大导入、国际化与启用规则变更** | Widget 改由工程师以唯一标识直接导入，A端取消新建入口且标识永久只读；名称、简介改用通用国际化组件提交五种语言，分类沿用既有字典翻译；导入后默认停用，启用及重新启用须通过管理信息、分类字典、元数据和国际化完整性校验。 | 本次方案确认；DeepSeek PM 二审后收口。 |
| v0.14 | 2026-08-06 | **重大：全量清单、展示模式与分类同步** | 以《全部Widget清单》作为 A端导入清单；补充工程师导入的只读“支持展示模式”，页面仅可从中单选。WALK、VR 作为独立 Widget 归入建筑与空间。 | A端技术评审后产品确认。 |
| v0.15 | 2026-08-06 | 国际化完成状态统一 | 名称、简介等国际化字段统一只显示橙色“未完成”和绿色“已完成”两种状态；完成仅以五语文本是否齐全判断，不增加 AI 草稿或人工确认状态。 | 产品确认。 |
| v0.16 | 2026-08-06 | 国际化入口与状态合并 | 编辑字段不再在国际化按钮外单独展示状态；保留统一按钮样式，在“国际化”按钮上以橙色或绿色图标显示完成状态。 | 产品确认。 |
| v0.17 | 2026-08-06 | 列表国际化标记精简 | 删除 Widget 列表中名称、简介的国际化完成标记；完成状态仅在对应编辑字段的国际化按钮内显示。 | 产品确认。 |
| v0.18 | 2026-08-06 | 编辑字段国际化可见性调整 | Widget 名称、简介直接显示当前 A端界面语言的文本；国际化按钮缩小并与输入框同列，供查看和编辑其他语言。 | 产品确认。 |
| v0.19 | 2026-08-06 | **重大 Widget 内容选择规则收口** | 删除 Widget 元数据中的选择数量、单选/多选规则及其页面展示；Widget 仅声明可选择的数据来源分类，项目页面不再按 Widget 限制选择数量。 | 产品确认。 |
| v0.20 | 2026-08-06 | **重大页面模板布局规则调整** | 页面模板新增 Widget 模块后，必须从该 Widget 工程师导入的支持展示模式中单选一个模板布局方案；该方案随模板区块复制到非通用模板项目页面并锁定。 | 产品确认。 |
| v0.21 | 2026-08-11 | **重大：WALK / VR 退出 Widget 范围** | WALK、VR 作为项目内容对象的关联体验，由沉浸内容承载组件调用；A端不再将其导入、启用或配置为独立 Widget。 | 产品确认。 |
| v0.22 | 2026-08-11 | **重大：全量 Widget 属性同步** | 当前导入范围固定为 22 个 Widget；同步项目概览、共有部、样板间、住户表与购置费用试算的数据来源和内容边界。 | 产品确认。 |
| v0.23 | 2026-09-02 | **重大页面素材引用与同步规则补充** | 明确页面模块只保存素材标识和选择关系，不复制素材正文；素材源变化后页面读取最新有效内容。Widget 引用能力记录不属于页面内容快照。 | 产品确认；统一方案见 `../修改说明/2026-09-02-ABC端页面实例统一规则修改说明.md`。 |
| v0.24 | 2026-09-03 | 文档表达清理 | 正文直接描述 Widget 引用能力记录、既有引用和素材来源的当前规则，清理以“不回写”“不是快照”等否定旧逻辑为主的重复表述。 | 初步需求评审整改。 |
| v0.25 | 2026-09-03 | 自由模板名称对齐 | 当前正文中的“通用模板项目页面”统一改为“自由模板页面”，与 B端 V0.251 及自由模板专项 PRD 一致。 | 对齐 B端最新正式 PRD。 |
| v0.25 | 2026-09-03 | **重大：取消 Widget 尺寸配置** | 删除微、小、中、大支持展示模式及所有尺寸配置；保留同页多 Widget、重复引用和有序编排。每个 Widget 在顾客端独占内容窗口。 | 产品纠正；同一连续编辑时段沿用 v0.25。 |
| v0.26 | 2026-09-04 | **重大：恢复 Widget 展示规格** | 恢复工程师导入的微、小、中、大支持展示规格，并允许模板或自由模板页面为每个 Widget 实例单选。展示规格不决定页面同时展示数量；C端仍按独占窗口逐个展示 Widget。 | 撤回 2026-09-03 17:16 的尺寸取消要求；保留后续确认的 C端切换规则。 |

## 1. 文档目的

本文定义 A端 Widget 管理的产品边界、工程师导入、管理信息国际化、Widget元数据展示、编辑能力、状态规则和验收标准。页面模板如何引用 Widget 见 `02-A端页面模板管理PRD.md`；项目页面如何根据 Widget元数据配置内容见 `03-A端项目页面管理PRD.md`。

## 2. 产品背景与目标

Widget 是由开发人员实现的可复用页面能力。A端不制作 Widget，不管理 Widget代码，也不定义 Widget运行所需的内容属性；A端只建立管理记录、控制可用状态，并展示代码已经提供的 Widget元数据。

本期目标：

1. 由工程师在开发时定义具备业务语义的唯一标识，并直接导入 A端台账；操作人员不创建或修改标识。
2. 用名称、分类和简介帮助业务人员识别、搜索和管理 Widget。
3. 只读展示代码定义的 Widget元数据，供页面模板和项目页面正确使用 Widget。
4. 通过已启用、已停用状态控制 Widget是否可用于新的页面模板或页面。
5. 为页面模板和项目页面提供唯一、受控的 Widget可用清单。

## 3. MVP范围与边界

### 3.1 本期包含

- Widget列表、搜索、状态筛选和分类筛选；
- 工程师直接导入 Widget 标识和 Widget 元数据；导入时检查全局唯一性；
- 编辑 Widget名称、分类和简介及其国际化内容；Widget 标识永久只读；
- 只读展示工程师导入的内容配置方式、数据来源和支持展示规格；
- 启用、停用和重新启用；
- 查看被页面模板和项目页面引用的数量。

### 3.2 本期明确不做

- 不在 A端编写、上传、修改或运行 Widget程序文件；
- 不在 A端新建、注册、修改或迁移 Widget标识；
- 不在 A端编辑 Widget元数据；
- 不在 A端读取、刷新或用人工填写覆盖已导入的 Widget元数据；
- 不在 A端定义 Widget内部输入控件、内容数据结构、接口地址、请求参数或返回结构；
- 不登记开发负责人或服务商字段；
- 不登记“列表式、卡片滑动式”等内部表现形式；
- 不实施自动验证，也不输出虚假的逐项验证通过结果；
- 不删除已经被模板或项目页面引用的 Widget；
- 首批不预置用途和内容边界不清的通用“自定义图文”Widget；
- 不在 A端自行新增清单外的资料类 Widget 或数据来源；资料集、单个文件夹展示及资料文件夹数据来源以工程师导入的《全部Widget清单》元数据为准；
- 项目联系页脚属于 C端通用组件，不登记为 Widget。

### 3.3 管理边界

“编辑 Widget”只表示编辑 Widget管理记录，不表示编辑 Widget程序或工程师导入内容。

- 工程师导入 Widget 时同时写入唯一标识和元数据；标识全局唯一、永久只读，已停用记录也继续占用该标识。
- Widget名称和简介均须通过 A端通用国际化组件提交简体中文、繁体中文、日文、英文、韩文五种文本；分类的翻译只读取既有分类字典，不在 Widget 页重复维护。
- 编辑页直接显示当前 A端界面语言下的 Widget名称和简介文本；操作人员可在该输入框修改当前语言内容，其他语言通过紧邻的小型国际化按钮编辑。
- 每个国际化字段保留统一的“国际化”按钮样式，按钮内以图标显示完成状态：五种语言任一缺失时为橙色图标，五种语言均已填写时为绿色图标。不另设重复状态标签；状态仅反映文本是否齐全，不区分填写方式。
- 内容配置方式、数据来源和支持展示规格合称“Widget元数据”，由工程师导入；A端只读展示。
- 导入可保留元数据或国际化未完成的记录，但状态必须为已停用；缺失项补齐前不得启用。
- A端只校验导入标识唯一性、元数据完整性及可运营信息的完整性，不自动判断元数据与 Widget实际行为是否一致。

如需改变标识，工程师必须导入新的 Widget。Widget元数据发生不兼容变化时，也必须使用新的 Widget标识，不能改变既有 Widget标识的功能含义。已有模板和项目页面继续使用创建时保存的 Widget引用能力记录。该记录只固定模块可以怎样配置，不保存页面内容或素材内容。

## 4. 用户角色与场景

### 4.1 目标用户

- A端产品或交付配置人员：查找、补齐运营信息和管理 Widget。
- Widget开发人员：定义唯一标识、完成 Widget 开发，并导入标识和元数据。
- 测试人员：确认已导入的元数据与实际能力相符，并验证启用校验。

### 4.2 核心场景

- 开发人员完成 Widget 后，按唯一标识将 Widget 及元数据导入 A端，系统创建为已停用。
- 操作人员补齐名称、简介的五语文本并选择分类；分类翻译由分类字典提供。
- 操作人员查看已导入的只读元数据，校验通过后启用 Widget。
- 模板或项目页面配置人员按分类、名称或标识查找已启用 Widget。
- 操作人员通过停用状态控制 Widget 的新引用资格，既有引用继续有效。

## 5. 核心对象与业务规则

### 5.1 Widget管理信息

| 页面属性 | 规则 |
|---|---|
| Widget标识 | 工程师导入；全局唯一；永久只读；开发必须使用。 |
| Widget名称 | 供业务人员识别和搜索；使用单行文本国际化通用组件提交五语文本；允许修改；不参与运行逻辑。 |
| Widget分类 | 必选、单选；用于业务归类和筛选；翻译由既有分类字典提供；允许修改；不决定数据接口。 |
| Widget简介 | 用自然语言说明用途和适用场景；使用多行文本国际化通用组件提交五语文本；允许修改；不作为项目页面内容规则。 |
| Widget元数据 | 内容配置方式、数据来源和支持展示规格；由工程师导入，A端只读。 |
| 状态 | 已停用、已启用。工程师导入后默认已停用。 |
| 被模板使用 | 只读统计，用于判断停用影响。 |

### 5.2 Widget标识

- 工程师导入时必须检查标识全局唯一；重复标识拒绝导入，不覆盖既有 Widget，且返回冲突标识。
- 唯一性范围为整个 Widget台账，不按项目分别计算；已停用 Widget的标识仍被占用。
- 标识导入后永久只读；MVP 不提供标识迁移、别名或自动更新历史引用能力。

### 5.3 Widget分类

Widget 分类是 A端的管理字典，用于业务归类、检索和筛选；不参与 C端页面展示、内容选择或运行逻辑。MVP 固定为：

| Widget分类 | 业务含义 |
|---|---|
| 项目基础 | 项目概览等可独立装配的项目基础能力。 |
| 建筑与空间 | 建筑、楼栋、楼层和公共空间等能力。 |
| 住户产品 | 户型、住户、样板间和费用等能力。 |
| 周边环境 | 日影、眺望和地图等能力。 |
| 资料内容 | 资料与活动等内容浏览能力。 |
| 转化流程 | 预约等引导顾客提交意向、获得处理反馈的能力。 |

分类只用于归类、检索和理解业务归属，不得据此推断项目数据范围、Widget功能或技术接口。WALK、VR 是可由业务内容对象关联的体验内容类型，不登记、导入或配置为独立 Widget；其承载由沉浸内容承载与控制组件完成。分类显示语言由既有分类字典决定；翻译未完成的分类不得选择为 Widget 分类。已被 Widget 使用的分类不得删除，只能停用；停用后不能用于新导入 Widget，既有 Widget 保留原分类。

### 5.4 Widget元数据

Widget能力定义由工程师随 Widget 一次导入，A端只能读取和使用，不提供编辑、重新读取或手动刷新入口。本文列出的元数据是 A端当前需要展示的最小项，不构成跨所有 Widget 的固定字段表。

| 元数据 | 业务定义 | A端用途 |
|---|---|---|
| 内容配置方式 | 自动带入或选择项目内容。 | 决定创建项目页面是直接带入内容，还是显示内容选择。 |
| 数据来源分类 | 需要选择项目内容时，Widget 可使用的数据来源分类。 | 决定项目页面列出哪一类候选数据。 |
| 支持展示规格 | Widget 可使用的微、小、中、大展示方案集合，至少包含一项。 | 模板或自由模板页面只能从该集合中为每次 Widget 引用单选一项。 |

内容配置方式定义：

| 配置方式 | 业务定义 | 创建项目页面时的表达 |
|---|---|---|
| 自动带入 | Widget根据当前项目自动取得内容。 | 显示“无需配置”。 |
| 选择项目内容 | 从当前项目已有内容中选择展示范围。 | 在数据弹窗中勾选需要展示的候选数据；不显示或限制选择数量。 |

元数据完整性规则：

- 工程师导入时必须同时带入元数据；编辑页直接展示当前导入值，不提供“读取”“刷新”或人工填写入口。
- 元数据缺失或组合无效仍允许导入并保持已停用，系统明确显示缺失项；补齐后由工程师再次导入更新，才可启用。
- 新建页面模板或页面时，系统保存当时的只读 Widget 引用能力记录；既有模板和页面继续使用各自保存的记录。该记录只定义内容配置能力，素材标题、说明、图片、视频和其他正文由素材源统一维护。
- 所有 Widget必须提供内容配置方式。
- 所有 Widget 必须至少提供一个支持展示规格；页面所选规格必须属于对应 Widget 的支持集合。
- “选择项目内容”必须声明数据来源分类；A端不得自行补充未声明的分类，也不得定义单选/多选或选择数量限制。
- “自动带入”不提供人工选择；它可使用 Widget 固定定义的项目内容，但不要求登记为可选择内容分类。
- 元数据缺失或组合无效时，A端显示具体问题并阻止启用。
- MVP只检查元数据是否完整，不判断代码实际行为是否符合元数据；启用仍由操作人员人工确认。
- 已启用 Widget发生不兼容的元数据变化时，工程师应导入新的 Widget标识。
- 功能型 Widget必须声明明确的业务内容对象；内容／素材类 Widget可以声明多个可配置内容对象及其组合方式。A端只能在该范围内配置，不能自行扩大。
- 一个页面可以引用多个 Widget，也可重复引用同一 Widget。每个 Widget 在顾客端独占内容窗口，同一时刻不与其他 Widget 并排展示。
- 微、小、中、大表示当前 Widget 在独占窗口中采用哪一种展示方案，不表示页面可同时摆放多少个 Widget，也不改变独占窗口规则。各规格在 C端的具体视觉表现由 C端重构与 Widget 设计定义。
- 顾客端通过页面导航或演示模式按钮在 Widget 之间切换；这些切换控件不属于 Widget 元数据，也不由 A端配置，但 C端渲染当前 Widget 时需要读取其展示规格。

### 5.5 数据来源分类

本清单定义 A端生成实例页面时可被列出、勾选的数据来源分类。它不是 Widget 分类，也不是“自动带入／选择项目内容”这类内容配置方式；Widget 仅在需要人工选择内容时，引用本清单的一项或多项分类。

| 数据来源分类 | 产品标识 | 可供选择的项目内容 |
|---|---|---|
| 项目概览内容 | `project-overview-content` | 项目身份、项目介绍、项目主视觉等项目基础展示内容。 |
| 户型 | `floorplan` | 户型资料、户型图及关联说明。 |
| 周边点位 | `surrounding-poi` | 项目位置、周边 POI 及其分类。 |
| 建筑图纸 | `architectural-drawing` | 断面图、立面图及其说明。 |
| 楼层 | `floor` | 楼层资料、楼层平面图及关联对象。 |
| 公共空间 | `public-space` | 共有部名称、代表图与有效 WALK/VR 体验内容。 |
| 三维建筑 | `building-3d` | 可公开的三维建筑内容、楼栋和热点。 |
| WALK 空间体验 | `walk-experience` | 可启动的 WALK 内容及其适用空间。 |
| VR 空间体验 | `vr-experience` | 可启动的 VR 内容及其适用空间。 |
| 样板间 | `model-room` | 样板间名称、代表图与有效 WALK/VR 体验内容。 |
| 住户 | `resident` | 可公开的住户资料、房号、状态和关联对象。 |
| 眺望 | `view` | 眺望素材、楼层/朝向/拍摄位置和说明。 |
| 资料文件夹 | `material-folder` | 已公开资料文件夹及其中图片、视频、PDF 等资料。 |
| 建筑环视 | `building-360` | 连续建筑外观帧或 360 环视内容。 |
| 日影资料 | `sunlight-shadow` | 日影素材、日期/时刻标签和说明。 |
| 活动 | `activity` | 已发布活动、时间、状态和报名入口。 |
| 预约配置 | `appointment` | 预约说明、可预约时段、意向选项和同意说明。 |
| 平面色彩方案 | `plan-color-scheme` | 同一户型/空间的平面色彩方案和 CG 图。 |
| 三维色彩方案 | `three-d-color-scheme` | 同一空间的三维/全景色彩方案。 |
| 家具摆放方案 | `furniture-layout` | 户型平面与家具摆放方案。 |
| 购置费用与试算资料 | `purchase-cost` | 购房费用计算与贷款试算所需数据。 |
| 外部服务 | `external-service` | 已批准的外部服务、责任主体和返回目标。 |

使用规则：

- A端只在当前项目、当前发布语言下的已发布且允许公开内容中，按 Widget 声明的数据来源分类列出候选数据；分类本身不等于可供顾客展示的数据。
- Widget 元数据只声明可选择的数据来源分类，不得包含选择数量、单选或多选限制。
- 固定内容、表单和专属定制功能如不需要操作人员选择项目内容，不要求引用本分类清单。
- 数据来源分类新增、停用或调整时，必须同步核对引用它的 Widget；已被既有页面引用的分类不得删除。
- 页面选择内容时只保存素材标识、选择范围和页面内顺序，不复制素材正文。
- 素材标题、说明、图片、视频或其他源内容变化后，所有引用页面在下一次读取或刷新时使用最新有效内容，不要求重新生成、保存或启用页面。
- 素材被停用、删除或失去公开权限后，页面不得继续使用旧内容副本；对应 Widget 按自身空状态、隐藏或不可用规则降级。

### 5.6 状态规则

```text
工程师导入 → 已停用 → 启用校验通过 → 已启用
已启用 → 停用 → 已停用
已停用 → 重新启用 → 已启用
```

- 工程师导入后直接进入已停用；不存在“注册”或“待验证”状态。
- 开发和导入发生在 A端编辑流程外；A端不提供新建入口。
- 启用和重新启用时必须同时校验：名称五语完整、简介五语完整、分类已选择且其既有字典五语完整、Widget元数据完整。
- 任一项未通过时，保持已停用，逐项显示缺失原因，不出现可绕过的确认操作。
- 编辑名称、简介或分类时即校验完整性；五语未填齐、分类字典翻译不完整或名称/简介为空，阻止保存，避免已启用 Widget 因保存不完整信息而处于不一致状态。
- MVP不执行代码自动验证；操作人员确认工程师已完成部署且元数据与实际能力相符后启用。
- 只有已启用且元数据完整的 Widget可用于新的页面模板或项目页面。
- Widget加入项目页面时，系统复制当前 Widget标识、名称和元数据，形成该页面中的一个独立 Widget 引用；页面随后独立存在。
- 停用后不能用于新的页面模板或项目页面；既有模板和页面保留原 Widget 引用。
- 完整地修改名称、分类或简介不会改变 Widget状态，也不会改写已有模板和项目页面。

### 5.7 权限与并行编辑

- 只有具备相应管理权限的操作人员才能查看、编辑、启用、停用或重新启用 Widget；无权限时不显示可执行操作，并明确提示暂无权限。
- 多人同时编辑同一 Widget时，后提交的一方不得静默覆盖已保存的较新内容。系统应提示刷新后重新确认；未保存输入由页面保留至操作人员主动处理。
- 权限的具体角色、权限名称和后台校验方式由权限设计定义，不在本文固定。

## 6. 用户用例

### UC-W01：工程师导入 Widget

**前置条件**：工程师已完成 Widget 开发并定义唯一标识和元数据。

**主流程**：

1. 工程师以唯一标识导入 Widget 及元数据。
2. 系统检查标识在 Widget 台账中全局唯一。
3. 系统创建 Widget 记录并设为已停用。

**结果**：编辑页直接只读显示已导入的标识和元数据；名称、简介可待运营人员补齐国际化内容。

**异常 / 边界**：标识重复时拒绝导入且不覆盖既有记录；元数据不完整可导入但只能保持已停用。

### UC-W02：补齐管理信息及国际化

**前置条件**：Widget 已由工程师导入。

**主流程**：

1. 操作人员打开编辑页。
2. 通过单行文本国际化通用组件提交 Widget名称的五语文本；通过多行文本国际化通用组件提交 Widget简介的五语文本。
3. 选择分类；页面读取既有分类字典显示其五语状态。
4. 保存完整管理信息。

**结果**：列表和编辑页更新当前语言下的名称、分类和简介；唯一标识与元数据保持只读。

**异常 / 边界**：任一名称或简介语言缺失、分类未选择或分类字典翻译缺失时阻止保存并指出具体语言或分类。

### UC-W03：启用 Widget

**前置条件**：Widget 为已停用，且工程师已完成部署和导入。

**主流程**：

1. 操作人员点击“启用”。
2. 系统检查名称、简介、分类字典和元数据完整性。
3. 校验通过后，操作人员确认工程师部署和元数据与实际能力一致。
4. 操作人员确认。

**结果**：Widget 进入已启用，可用于新模板和项目页面。

**异常 / 边界**：任一校验项缺失时不可启用，页面逐项提示；不提供“强制启用”。

### UC-W04：编辑 Widget

**前置条件**：Widget已由工程师导入。

**主流程**：

1. 在列表中找到目标 Widget。
2. 点击“编辑 Widget”。
3. 进入全屏编辑页面。
4. 修改允许编辑的管理信息。
5. 保存修改。

**结果**：列表显示最新管理信息；当前状态保持原值；已有模板和页面继续使用各自保存的 Widget 引用能力记录。

**边界**：

- 标识在所有状态下只读；名称、分类和简介仍可修改。
- Widget元数据始终只读，不能在编辑页面修改。

### UC-W05：停用或重新启用

**前置条件**：Widget已启用或已停用。

**主流程**：操作人员查看引用数量和影响提示后执行停用或重新启用。

**结果**：停用后从新模板和新页面的可选清单移除；重新启用前重新执行 UC-W03 的完整校验；既有引用继续使用各自保存的能力记录；Widget标识保持只读。

## 7. 功能需求矩阵

| 功能ID | 功能名称 | 关联用例 | 优先级 |
|---|---|---|---|
| W-001 | Widget列表与筛选 | UC-W02、UC-W04、UC-W05 | P0 |
| W-002 | 工程师导入 Widget | UC-W01 | P0 |
| W-003 | 管理信息及国际化编辑 | UC-W02、UC-W04 | P0 |
| W-004 | 只读展示已导入的 Widget元数据 | UC-W01、UC-W03、UC-W04 | P0 |
| W-005 | 启用完整性校验与人工确认 | UC-W03、UC-W05 | P0 |
| W-006 | 停用与重新启用 | UC-W05 | P0 |
| W-007 | 引用数量与影响提示 | UC-W05 | P0 |

## 8. 页面与交互要求

### 8.1 Widget管理列表

列表展示：

- Widget名称和 Widget标识；
- Widget分类；
- Widget简介；
- 支持展示规格；
- 被模板使用数量；
- 状态和可用操作。

列表展示 Widget名称与标识、分类、简介、支持展示规格、引用数和状态。国际化完成状态仅在编辑字段的国际化按钮内显示。列表不提供“新建”“注册”“读取元数据”或“刷新元数据”入口。搜索至少匹配 Widget名称和标识，不把只读元数据作为搜索条件。筛选条件至少包含状态和 Widget分类。“清空筛选”必须同时重置搜索、状态和分类。

### 8.2 编辑页面

页面分为三个模块：

1. Widget标识：工程师导入；全程只读。
2. 管理信息：Widget名称、分类和简介均允许修改；当前 A端界面语言的名称、简介分别直接显示为单行和多行输入框；小型国际化按钮与输入框同列，名称使用单行文本国际化通用组件，简介使用多行文本国际化通用组件，均须提交五语文本。按钮内以橙色或绿色图标显示完成状态。
3. Widget元数据：自动随工程师导入并只读展示内容配置方式、数据来源和支持展示规格；无值时显示“尚未提供”。

编辑页在“Widget元数据”中只读显示内容配置方式、数据来源和支持展示规格。A端不能编辑 Widget 支持哪些规格；模板和自由模板页面只负责从支持集合中选择，不配置导航、演示模式按钮或切换动效。

不提供注册页。弹窗仅用于名称、简介国际化编辑，以及启用、停用和重新启用等短操作；国际化弹窗须提供简中、繁中、日文、英文、韩文，保存前显示每种语言的完成状态。所有五语文本填写完成即显示“已完成”，不额外设置待确认状态。

### 8.3 空状态与错误

| 场景 | 页面处理 |
|---|---|
| 没有 Widget | 显示空状态“暂无工程师导入的 Widget”，不提供新建入口。 |
| 筛选无结果 | 提示调整条件，并提供清空筛选。 |
| 导入标识冲突 | 拒绝导入，保留既有记录，向工程师返回冲突标识。 |
| 任一名称或简介语言缺失 | 国际化组件指出具体语言，阻止保存。 |
| 分类未选择或分类字典翻译缺失 | 不允许保存或启用，并说明分类字典需先补齐。 |
| 尝试修改标识 | 标识保持只读，不提供修改入口。 |
| Widget元数据尚未提供或组合无效 | 显示“尚未提供”或具体问题；记录保持已停用，不能启用。 |
| 尝试读取或刷新元数据 | 页面不提供入口；工程师再次导入后自动更新展示。 |
| 停用被引用 Widget | 显示引用数量，并说明既有模板和页面继续使用各自保存的能力记录后再确认。 |
| 没有对应操作权限 | 不提供对应操作，并提示暂无权限。 |
| 保存时记录已被他人更新 | 不覆盖较新记录，提示刷新后重新确认。 |

## 9. 数据与配置说明

本文只定义产品字段，不等同于数据库或接口设计。

| 技术字段 | 页面名称 | 来源 | 可修改 |
|---|---|---|---|
| `widget_id` | Widget标识 | 工程师导入 | 否 |
| `display_name_i18n` | Widget名称 | A端管理 / 单行文本国际化通用组件 | 是；五语完整才可保存。 |
| `widget_category` | Widget分类 | A端管理 / 分类字典 | 是；字典五语完整才可保存或启用。 |
| `widget_description_i18n` | Widget简介 | A端管理 / 多行文本国际化通用组件 | 是；五语完整才可保存。 |
| `widget_metadata` | Widget元数据 | 工程师导入 | A端只读 |
| `content_config_mode` | 内容配置方式 | Widget元数据 | A端只读 |
| `data_source_category` | 数据来源分类 | Widget元数据 | A端只读；记录可使用的数据来源分类，不记录选择数量、单选或多选。 |
| `supported_display_modes` | 支持展示规格 | Widget元数据 | A端只读；至少一项，取值为微、小、中、大。 |
| `widget_status` | 状态 | 系统 / A端操作 | 工程师导入后为已停用；按状态流转。 |

## 10. 验收标准

| AC编号 | Given | When | Then |
|---|---|---|---|
| AC-W01 | 打开 Widget管理 | 查看列表 | 可见 Widget名称与标识、分类、简介、引用数和状态。 |
| AC-W02 | 列表存在多个分类 | 选择一个分类 | 只显示该分类 Widget；清空后恢复全部。 |
| AC-W03 | 工程师导入新的唯一标识 | 导入成功 | 记录默认进入已停用；A端列表无“新建 / 注册 Widget”入口。 |
| AC-W04 | 工程师导入已存在的标识 | 提交导入 | 系统拒绝导入且不覆盖既有记录，并返回冲突标识。 |
| AC-W05 | 编辑任意 Widget | 查看标识 | 标识和元数据均只读；页面不存在读取、刷新或人工填写元数据入口。 |
| AC-W06 | 编辑 Widget名称 | 打开国际化组件 | 使用单行文本组件展示并提交简中、繁中、日文、英文、韩文。 |
| AC-W07 | 编辑 Widget简介 | 打开国际化组件 | 使用多行文本组件展示并提交简中、繁中、日文、英文、韩文。 |
| AC-W08 | 名称或简介有任一语言缺失 | 保存 | 指出缺失语言并阻止保存，状态保持不变。 |
| AC-W09 | 选择分类 | 保存或启用 | 分类由既有字典显示翻译；字典任一必需语言缺失时阻止保存或启用。 |
| AC-W10 | Widget元数据不完整 | 启用或重新启用 | 系统指出元数据缺失项并保持已停用。 |
| AC-W11 | 已停用 Widget的名称、简介、分类字典与元数据均完整 | 启用并确认 | 弹窗说明不执行代码自动验证；确认后变为已启用。 |
| AC-W12 | 已启用 Widget | 编辑名称、分类或简介并完整保存 | 状态仍为已启用，既有模板和页面继续使用各自保存的 Widget 引用能力记录。 |
| AC-W13 | 已停用 Widget | 重新启用 | 重新执行名称、简介、分类字典及元数据完整性校验，全部通过才可启用。 |
| AC-W14 | 已启用 Widget被模板或页面引用 | 停用 | Widget 从新模板和新页面的可选清单移除；既有引用继续存在并使用原能力记录，标识保持锁定。 |
| AC-W15 | 查看 Widget分类 | 展开选项 | 只出现项目基础、建筑与空间、住户产品、周边环境、资料内容、转化流程六类分类。 |
| AC-W16 | 查看 Widget元数据的数据来源分类 | 检查显示值 | 显示 5.5 中可使用的数据来源分类；不显示选择数量、单选或多选。 |
| AC-W17 | 内容配置方式为选择项目内容 | 查看 Widget元数据 | 存在一项 5.5 数据来源分类；A端不允许人工补充未声明的分类或限制选择数量。 |
| AC-W18 | 内容配置方式为自动带入 | 查看 Widget元数据 | 不显示内容选择器、选择数量、单选或多选。 |
| AC-W19 | 打开 Widget 列表或编辑页 | 检查 Widget 元数据 | 可见内容配置方式、数据来源和支持展示规格；三项均为只读。 |
| AC-W20 | 在模板或自由模板页面添加 Widget | 检查展示规格 | 只能从该 Widget 支持的微、小、中、大规格集合中单选；规格不改变独占窗口和同时展示数量。 |
| AC-W21 | 新页面添加已启用 Widget | 保存页面 | 每次添加都形成独立 Widget 引用；同页可包含多个或重复 Widget。 |
| AC-W22 | 页面 Widget 选择项目素材 | 保存页面 | 保存素材标识和选择关系；素材正文由素材源统一维护。 |
| AC-W23 | 已被页面引用的素材 | 修改素材源内容 | 页面下次读取或刷新时展示最新有效内容。 |

## 11. 风险与依赖

| 风险 / 依赖 | 影响 | 应对 |
|---|---|---|
| 工程师导入重复标识 | 新记录覆盖既有可用 Widget | 导入前强制全局唯一校验；冲突即拒绝导入。 |
| A端显示的 Widget元数据与实际代码不一致 | 模板或项目页面按错误规则配置内容 | MVP人工确认；后续再评估自动验证。 |
| Widget元数据未随导入完成 | 运营人员无法在 A端补齐元数据 | 保持已停用；由工程师补齐后再次导入，A端不提供读取或人工补写。 |
| 已启用 Widget发生不兼容元数据变化 | 既有模板和页面内容无法解释 | 工程师导入新的 Widget标识，不改变旧 Widget功能含义。 |
| Widget 未提供可配置数据来源分类或组合规则 | 项目页面无法正确列出候选数据 | 阻止 Widget 启用；由工程师补齐能力定义。 |
| 名称、简介或分类字典翻译缺失 | 启用后无法完整支持五种语言 | 保存和启用均阻止，明确显示缺失语言或分类。 |
| Widget 能力定义与项目内容不匹配 | 项目页面无法正确配置内容 | 由开发修正该 Widget 能力定义；A端不得用全局映射或手工扩容绕过。 |
| 页面复制素材正文 | 素材更新后各页面内容不一致 | 页面 Widget 只保存素材引用；素材正文统一由素材源维护。 |

## 12. 待确认事项

1. 自动验证的实施时间和最小校验项；MVP不因此增加代码验证流程。

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

- 不把工程师导入理解为 A端新建 Widget。
- 不允许 A端编辑 Widget元数据。
- 不提供读取或刷新 Widget元数据的按钮；工程师再次导入后自动更新只读展示。
- 不根据数据来源分类规则自行定义接口方案。
- Widget 引用能力记录用于限定页面中每个 Widget 实例的配置范围；页面当前有效内容按页面规则保存。
- 页面保存素材引用，素材内容始终读取素材源的最新有效值。
- 不把 Widget分类、数据来源分类和内容配置方式合并成一个字段。
- Widget 不再有尺寸元数据或 A端尺寸配置字段；独占内容窗口及切换方式由顾客端页面规则统一实现。
- 不允许任何状态下的 Widget标识进入可编辑状态。
- 待确认事项不得作为已定需求实现。