# HOMEVISTA A端项目主题管理 PRD

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

## 修订记录

| 版本 | 日期 | 变更类型 | 变更摘要 | 备注 |
|---|---|---|---|---|
| v0.1 | 2026-07-28 | 初始创建 / 文档结构重构 | 从原01、03、04、05文档迁移项目主题新增、编辑、预览、应用、恢复默认及系统状态色锁定规则，建立项目主题管理唯一事实源。 | 原文及历史修订记录见 `archive/`。 |
| v0.2 | 2026-07-28 | **重大主题生成流程与配置范围变更** | 在暂无正式设计稿的前提下建立三步主题生成流程；MVP开放基础背景、文字、链接、主按钮、项目菜单、边框颜色、受控边框宽度和受控圆角配置。主题仍不得改变页面布局，系统状态色继续锁定为VISTA默认值。 | 产品提出 / Codex整理。 |
| v0.3 | 2026-07-28 | **重大主题继承与恢复规则补充** | MVP可读性检查只警告、不阻断应用；恢复默认仅切换使用模式并保留最近一次个性化配置；默认主题项目自动跟随VISTA默认主题升级，个性化主题项目保持已保存主题值。 | 跨文档评审后产品确认。 |
| v0.4 | 2026-07-30 | **重大项目导航入口变更** | 项目主题改为选中项目后才在“项目管理”下展开的子页面；未选择项目时隐藏入口，选择项目后与项目页面共享当前项目上下文。 | 产品确认。 |
| v0.5 | 2026-08-03 | 重大跨端主题继承规则补充 | 明确 B端预览和 C端页面均继承当前项目主题，B端销售人员不得修改主题。 | 产品确认清单。 |
| v0.6 | 2026-08-04 | **重大并行应用规则补充** | 补充主题被他人更新时的提示与处理，防止覆盖较新的项目主题。 | 对照 A端前端技术架构设计文档后的产品确认。 |
| v0.7 | 2026-08-05 | **重大品牌标识配置范围变更** | 新增“品牌标识”步骤：可上传项目级页面加载等待标识（安全 SVG 或 GIF），并可隐藏 C 端平台署名标识；配置仍统一作用于项目全部页面，不提供逐页或逐 Widget 覆盖。 | 产品确认；加载标识的尺寸、体积和动效规格待设计系统补充。 |
| v0.8 | 2026-08-05 | **重大品牌素材拆分与导航适配变更** | 品牌标识拆为加载中 GIF、加载中动画 JSON、品牌 SVG 三类独立素材；GIF 与 JSON 是适用于不同加载场景的平级方案，不定义兜底或相互替代关系。品牌标识提供“更换 SVG”或“隐藏”两种选择；四步导航按内容和可用宽度自适应，不再等分整行。 | 产品确认；JSON 动画格式与播放器规格待设计系统补充。 |
| v0.9 | 2026-08-05 | **主题预览边界收口** | 明确主题预览是静态视觉样本，不模拟项目真实页面集合、页面名称、项目菜单或页面切换；项目可能拥有任意数量页面，页面导航效果在实际页面验收中验证。 | 产品确认。 |
| v0.10 | 2026-08-06 | **重大项目入口调整** | 删除选中项目后左侧“项目主题”子导航；项目清单每行新增“主题管理”入口，与“页面管理”并列进入对应项目。 | 产品确认。 |
| v0.11 | 2026-09-02 | 页面状态术语同步 | 将主题影响范围中的页面状态统一为已启用、已停用；删除页面重新发布表述。主题编辑过程中的未保存配置仍只属于主题编辑，不属于页面草稿。 | 同步 ABC端页面实例统一规则。 |
| v0.12 | 2026-09-03 | 文档表达与状态清理 | 主题生效规则改为直接描述项目页面读取当前有效主题的现行逻辑；将未应用输入统一定义为当前编辑会话内容，避免误解为独立的主题草稿能力。 | 初步需求评审整改。 |
| v0.12 | 2026-09-03 | 多 Widget 独占窗口引用同步 | 主题范围作用于页面全部 Widget 及通用区域；清理旧 Widget 尺寸规格引用。主题不改变 Widget 顺序或顾客端切换方式。 | 产品纠正；同一连续编辑时段沿用 v0.12。 |
| v0.13 | 2026-09-04 | **重大：Widget 展示规格边界恢复** | 恢复页面逐 Widget 微、小、中、大展示规格后，明确主题只作用于各规格允许继承的视觉令牌，不改变已保存规格、Widget 顺序、独占窗口或切换方式。 | 与 A端 Widget 及页面规则同步。 |

## 1. 文档目的

本文定义 A端从项目清单进入“主题管理”的产品边界、主题新增与编辑、配置范围、应用规则和验收标准。项目页面只读取项目当前有效主题，不在单页中保存或选择主题。

## 2. 产品背景与目标

不同房地产项目需要使用自身品牌配色，但 Widget和页面模板需要跨项目通用。如果在每个页面或 Widget中分别设置颜色，会造成重复配置、风格不一致和已启用页面难以统一更新。

本期目标：

1. 没有个性化主题的项目自动使用 VISTA默认主题。
2. 每个项目最多维护一个个性化主题。
3. 统一控制页面背景、项目菜单、Widget和通用组件的基础视觉规则，以及项目级品牌标识。
4. 主题可以改变受控颜色、边框宽度、圆角、加载中 GIF、加载中动画、品牌标识和品牌显示状态，但不改变页面布局、内容和交互。
5. 主题更新后，该项目全部页面在下一次读取或刷新时使用当前有效主题。
6. B端预览和 C端顾客页面均读取当前项目主题；B端销售人员不提供主题修改入口。

## 3. MVP范围与边界

### 3.1 本期包含

- 默认主题状态；
- 创建个性化主题；
- 编辑当前个性化主题；
- 项目级语义颜色配置；
- 受控边框宽度和圆角配置；
- “基础配色—组件外观—品牌标识—预览与应用”四步生成流程；
- 配置过程中的实时预览；
- 主题预览；
- 保存并应用；
- 恢复 VISTA默认主题；
- 恢复默认后保留最近一次个性化主题配置，供再次编辑或启用；
- 主题变更对当前项目全部页面统一生效；
- 配置异常时继续使用上一个有效主题或默认主题。

### 3.2 本期明确不做

- 一个项目创建多套主题或在多套主题间切换；
- 为单个页面或单个 Widget 设置主题；
- 修改页面模板、Widget顺序、区块宽度、间距或响应式布局；
- 修改字体、字号、字重、阴影、动画和内容资产；
- 为单个页面或单个 Widget 单独上传、替换或隐藏品牌标识；
- 将品牌 SVG 作为加载素材使用，或由系统从项目 Logo、图片自动生成任一品牌素材；
- 修改或隐藏错误、警告、成功、禁用等系统状态中的 VISTA 标识；
- 自由输入任意边框宽度或圆角数值；
- 分别配置某一个 Widget或组件的专属外观；
- 修改错误、警告、成功、禁用、危险操作和权限不足等系统状态色；
- 主题版本历史、定时生效、灰度发布和一键回滚；
- 自动从项目 Logo或图片提取主题颜色。

### 3.3 管理边界

A端只配置项目级通用视觉规则和品牌标识，不逐个管理每个 Widget的专属样式或署名。页面模板、Widget和通用组件应统一使用项目主题。新增 Widget不应要求A端增加一组 Widget专属主题字段。

边框宽度和圆角虽然会改变组件外观，但不能改变页面栅格、区块位置、组件尺寸规则或响应式布局。为了避免不同 Widget产生不可预测结果，MVP只允许从受控档位中选择，不开放任意数值。

系统状态色不属于项目品牌主题，始终使用 VISTA默认规范。状态组件还应使用图标和明确文字，不能只依赖颜色表达含义。

## 4. 用户角色与场景

### 4.1 目标用户

- A端项目配置人员：创建或调整个性化主题。
- 服务商 / 供应商：根据项目品牌要求确认配色。
- 测试人员：验证主题在模板、Widget、组件和页面状态中的一致性。

### 4.2 核心场景

- 新项目不配置主题，自动使用 VISTA默认主题。
- 配置人员按四步流程为项目创建个性化主题并实时预览。
- 修改当前主题并统一更新全部项目页面。
- 已启用页面在下一次读取或刷新时使用新主题。
- 恢复默认主题，所有页面统一回到 VISTA默认配色。

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

### 5.1 对象关系

```text
项目
├── 未定义个性化主题 → 使用 VISTA默认主题
└── 已定义个性化主题 → 使用当前项目主题
    └── 统一作用于该项目所有页面、模板代码、Widget和通用组件
```

项目页面只保存项目归属，不保存独立主题副本。顾客访问时根据所属项目读取当前有效主题。

### 5.2 单主题规则

- 每个项目同时只能有一个当前有效的个性化主题。
- 未创建个性化主题时显示“使用 VISTA默认主题”。
- 创建并应用后显示“使用个性化主题”。
- 恢复默认后停止应用个性化主题，所有页面使用 VISTA默认主题，但保留最近一次个性化主题配置。
- 使用 VISTA默认主题的项目自动跟随系统默认主题升级。
- 使用个性化主题的项目继续使用已保存的完整主题值，不自动混入新版默认配色；系统状态色仍跟随 VISTA统一规范。

### 5.3 全项目生效

- 项目主题是项目级共享配置，不属于单个页面保存内容。
- 保存并应用后，新主题成为当前项目唯一有效主题；所有已启用和已停用页面在下一次读取或刷新时使用该主题，既有分享链接继续指向原页面。
- 主题只控制项目级视觉规则；页面内容、模板来源、Widget 结构、顺序与展示规格、访问方式和页面状态继续使用各自现有配置。
- 不同项目之间必须隔离。

### 5.4 主题生成流程

创建和编辑个性化主题使用同一套四步全屏流程：

1. **基础配色**：配置页面背景、内容背景、标题、正文、辅助文字和链接颜色。
2. **组件外观**：配置主要按钮、项目菜单、边框颜色、边框宽度和圆角。
3. **品牌标识**：分别上传加载中 GIF、加载中动画 JSON、品牌 SVG，并设置是否显示 C 端常规品牌标识。
4. **预览与应用**：统一检查普通页面、Widget、菜单、按钮、链接、边框、品牌标识及锁定的系统状态色，再确认应用。

- 每一步都显示同一份实时预览，修改只作用于当前编辑会话。
- 上一步和下一步切换编辑步骤，并在当前会话内保留已输入内容。
- 只有在第四步点击“保存并应用”并完成全项目影响确认后，主题才正式生效。
- 创建和编辑复用同一流程；区别只在初始值来自VISTA默认主题还是当前个性化主题。

### 5.5 布局和内容不可变

主题不得改变：

- 页面 Widget 数量、顺序和独占窗口规则；
- 每个 Widget 已保存的微、小、中、大展示规格；
- 页面导航、演示模式按钮和 Widget 切换交互；
- PC端和移动端布局；
- 组件尺寸、间距、阴影和动画；
- 菜单结构、入口和交互方式；
- 文字、图片、视频及其他业务数据。

### 5.6 MVP主题字段

| 配置组 | 页面字段 | MVP规则 |
|---|---|---|
| 基础背景 | 页面背景色 | 页面最底层背景，必填颜色值。 |
| 基础背景 | 内容背景色 | Widget、卡片、弹窗等主要内容表面，必填颜色值。 |
| 文字 | 标题色 | 页面标题、Widget标题和重要标题。 |
| 文字 | 正文色 | 正文和主要说明文字。 |
| 文字 | 辅助文字色 | 次要说明、时间、补充信息。 |
| 交互 | 链接色 | 普通业务链接及轻量文字操作。 |
| 交互 | 主要按钮色 | 主要业务按钮背景，不用于错误或危险操作。 |
| 交互 | 主要按钮文字色 | 主要按钮上的文字和图标。 |
| 边界 | 边框色 | Widget、卡片、输入框和普通分隔边界。 |
| 边界 | 边框宽度 | 只允许无边框、细边框、强调边框三档，分别对应0、1、2px。 |
| 形状 | 圆角 | 只允许直角、小圆角、标准圆角、大圆角四档，分别对应0、4、8、16px。 |
| 项目菜单 | 菜单背景色 | 项目菜单容器背景。 |
| 项目菜单 | 菜单文字色 | 普通菜单文字。 |
| 项目菜单 | 当前项背景色 | 当前菜单项或选中项背景。 |
| 项目菜单 | 当前项文字色 | 当前菜单项或选中项文字。 |
| 品牌标识 | 加载中 GIF | 可选。仅允许上传 GIF 图片，供采用 GIF 加载方案的页面或能力使用。与加载中动画 JSON 互不替代、不定义优先级或兜底关系。文件体积、显示尺寸、时长和循环参数均为`待设计系统补充`。 |
| 品牌标识 | 加载中动画 | 可选。仅允许上传可解析的 JSON 文件，供采用 JSON 动画加载方案的页面或能力使用。与加载中 GIF 互不替代、不定义优先级或兜底关系；JSON 的动画格式、播放器及兼容性校验规则为`待设计系统补充`。 |
| 品牌标识 | 品牌标识 | 两个选择：**更换**或**隐藏**。选择更换时，仅允许上传通过安全校验的 SVG 图片，以替换默认 `Powered by HOMEVISTA` 品牌标识；SVG 不得含脚本、外部资源或可执行内容。选择隐藏时，C 端不显示默认或替换后的常规品牌标识。 |

MVP不提供主题名称。每个项目只有一个个性化主题，页面直接显示“VISTA默认主题”或“个性化主题”。

### 5.7 配置作用范围

| 配置组 | 最小覆盖对象 |
|---|---|
| 基础背景 | 页面背景、内容区域、浮层和卡片表面。 |
| 品牌与操作 | 主品牌色、辅助强调色、链接、主要按钮和普通选中态。 |
| 文字与边界 | 主文字、辅助文字、弱提示、边框和分隔线。 |
| 项目菜单 | 菜单背景、菜单文字、当前项背景和文字。 |
| Widget与通用组件 | 容器、标题、正文、边界、按钮、链接和业务配色。 |
| 品牌标识 | C 端页面加载等待状态与品牌标识展示；B 端只读预览同步反映，不提供独立覆盖。 |

以下颜色始终锁定为 VISTA默认值：错误、警告、成功、禁用、删除或停用等危险操作、权限不足等系统状态。

同一语义字段必须被所有已接入主题能力的模板、Widget和通用组件一致消费。A端不提供逐组件覆盖入口。

### 5.8 状态规则

页面只表达两种有效主题状态：

| 状态 | 页面说明 | 主要操作 |
|---|---|---|
| 使用 VISTA默认主题 | 当前项目没有启用个性化主题。 | 创建个性化主题。 |
| 使用个性化主题 | 当前项目全部页面正在使用该主题。 | 编辑主题、恢复默认。 |

编辑中的主题只影响预览。保存并应用成功后才影响真实页面。三类品牌素材与品牌显示状态均随主题整体应用。GIF 与 JSON 的场景选择由页面或能力代码决定，A端不提供逐页面、逐 Widget 的选择、优先级或兜底配置。

### 5.9 权限与并行应用

- 只有具备当前项目主题管理权限的操作人员才能查看、创建、编辑、应用或恢复主题；无权限时不显示对应操作，并明确提示暂无权限。
- 多人同时编辑同一项目主题时，后提交的一方不得覆盖已经应用的较新主题。系统应提示刷新后重新确认；未保存输入由页面保留至操作人员主动处理。
- 权限的具体角色、权限名称和后台校验方式由权限设计定义，不在本文固定。

## 6. 用户用例

### UC-TH01：使用默认主题

**前置条件**：项目存在，尚未创建个性化主题。

**主流程**：进入当前项目的主题管理，页面显示使用 VISTA默认主题。

**结果**：无需创建主题记录，项目全部页面具有完整默认样式。

### UC-TH02：创建并应用个性化主题

**前置条件**：已选择项目。

**主流程**：

1. 点击“创建个性化主题”。
2. 完成基础配色。
3. 完成组件外观。
4. 配置品牌标识。
5. 在实时预览中检查页面、菜单、Widget、通用组件和加载等待状态。
6. 点击“保存并应用”。
7. 确认将影响全部项目页面。

**结果**：当前项目全部页面统一读取新主题，内容和布局不变。

**异常 / 边界**：颜色不合法或必填值缺失时禁止应用。MVP可读性检查只显示警告并要求人工预览，不阻断应用。

### UC-TH03：编辑当前主题

**前置条件**：当前项目使用个性化主题。

**主流程**：修改颜色、组件外观或品牌标识，查看预览，保存并确认应用。

**结果**：当前项目全部页面整体切换到新主题。

**异常 / 边界**：应用失败时继续使用修改前的有效主题，不允许部分页面切换。

### UC-TH04：恢复默认主题

**前置条件**：当前项目使用个性化主题。

**主流程**：点击恢复默认、查看全项目影响提示并确认。

**结果**：当前项目全部页面统一使用 VISTA默认主题；最近一次个性化主题配置仍被保留，后续可以继续编辑并重新启用。

## 7. 功能需求矩阵

| 功能ID | 功能名称 | 关联用例 | 优先级 |
|---|---|---|---|
| TH-001 | 默认主题状态 | UC-TH01 | P0 |
| TH-002 | 四步创建个性化主题 | UC-TH02 | P0 |
| TH-003 | 四步编辑个性化主题 | UC-TH03 | P0 |
| TH-004 | 品牌标识配置 | UC-TH02、UC-TH03 | P0 |
| TH-005 | 全流程实时预览 | UC-TH02、UC-TH03 | P0 |
| TH-006 | 保存并应用 | UC-TH02、UC-TH03 | P0 |
| TH-007 | 恢复默认主题 | UC-TH04 | P0 |
| TH-008 | 全项目页面生效和异常回退 | UC-TH02、UC-TH03、UC-TH04 | P0 |

## 8. 页面与交互要求

### 8.1 页面入口和项目上下文

- “项目管理”是可点击的一级导航，点击后进入项目清单。
- 项目清单每行提供“页面管理”和“主题管理”两个操作；点击“主题管理”后，以该行为当前项目上下文打开主题管理。
- 左侧导航不提供“项目页面”或“项目主题”子导航入口。
- 页面顶部显示当前项目名称和标识。
- 再次点击一级导航“项目管理”返回项目清单，可重新选择项目。
- 切换项目后读取新项目主题，不得沿用上一项目未保存内容。

### 8.2 主题预览

- 至少展示页面背景、普通 Widget、文字、边界、按钮和链接。
- 预览必须展示直角/圆角和0、1、2px边框档位的实际效果。
- 预览必须同时展示成功、警告、错误、禁用等锁定状态，明确说明这些颜色不会被项目主题覆盖。
- 预览必须分别展示采用加载中 GIF、加载中动画 JSON 的两个“页面加载中”场景，以及品牌标识的显示或隐藏结果；B 端预览只用于确认 C 端效果，不提供单独修改入口。
- 预览是静态视觉样本，不展示项目实际页面名称、页面数量、项目菜单或页面切换入口；不得把样本中的任何元素理解为可配置页面或当前项目的真实页面结构。
- 预览只验证配色，不允许拖拽布局或修改业务内容。
- 预览不等于应用。

### 8.3 生成步骤

- 页面顶部显示“1 基础配色、2 组件外观、3 品牌标识、4 预览与应用”。
- 当前步骤必须明确高亮，已完成步骤可返回修改。
- 第一步和第二步均显示实时预览，避免最后一步才发现颜色不协调。
- 第三步提供加载中 GIF、加载中动画 JSON、品牌 SVG 的独立上传与移除，以及品牌显示开关；上传结果进入当前编辑会话。四个步骤导航按步骤文字和当前可用宽度自适应排列，宽屏不等分填满整行，窄屏可自然换行。
- 第四步汇总主题字段、品牌标识、系统锁定项和影响范围。
- 关闭或返回时存在未保存修改，提示本次输入将被丢弃，项目继续使用当前有效主题。

### 8.4 输入与校验

- 颜色字段同时提供颜色选择和十六进制文字输入，文字输入格式统一为`#RRGGBB`。
- 非法颜色值必须指出具体字段，禁止最终应用。
- 标题、正文、链接、按钮文字与相应背景的可读性必须给出提示；MVP不设置自动阻断，最低对比度阈值标记为`待设计系统补充`。
- 边框宽度和圆角只能选择受控档位，不能输入任意数值。
- 系统状态色只读展示，不允许获得焦点或进入编辑状态。
- 加载中 GIF 仅接受 GIF；加载中动画仅接受可解析 JSON；品牌标识仅接受 SVG，其他格式即时拒绝并说明原因。
- 品牌 SVG 上传前必须完成安全校验；含脚本、外部资源或可执行内容时拒绝保存。GIF 只校验为有效图片文件。JSON 至少必须可解析；详细动画格式和兼容性校验为`待设计系统补充`。
- 加载素材上传、保存或运行时失败的页面表现由对应页面或能力定义；本主题不定义 GIF、JSON 或其他素材之间的优先级、兜底或替代规则。
- 文件体积上限、展示尺寸、动画时长和循环策略为`待设计系统补充`；本期不擅自设置数值门槛。
- 品牌标识有“更换”和“隐藏”两个选择。选择隐藏不影响系统异常、法律声明或第三方服务必须展示的标识；这些标识不属于本配置项。

### 8.5 保存并应用

- 配置完整并通过校验后才能保存并应用。
- 确认提示必须说明：“应用后，当前项目全部页面将在下一次读取或刷新时使用新主题。”
- 成功后整体切换，当前项目只保留一份有效主题配置。
- 显示最近应用时间和最近操作人。

### 8.6 恢复默认

- 只在当前项目使用个性化主题时显示。
- 恢复前提示全项目影响。
- 恢复后所有项目页面统一读取 VISTA默认主题。
- 恢复默认不删除最近一次个性化主题值；再次进入时提供继续编辑并重新启用的入口。

### 8.7 异常处理

| 场景 | 页面处理 |
|---|---|
| 未选择项目 | 引导返回项目清单。 |
| 配置不完整或无效 | 指出问题并禁止应用。 |
| 文字与背景明显不可读 | 显示可读性警告并要求人工预览；MVP不阻断应用，最低阈值待设计系统补充。 |
| 应用失败 | 继续使用上一个有效主题；没有个性化主题时使用默认主题。 |
| 默认主题资源加载失败 | 按系统异常处理，不允许显示无样式页面。 |
| 上传格式不符、品牌 SVG 安全校验失败或加载动画 JSON 无法解析 | 拒绝该文件，当前编辑会话保留相应素材的上一次有效值或空状态，并说明具体原因。 |
| 加载动画 JSON 或加载 GIF 上传、保存或运行时不可用 | 由采用该素材的页面或能力按自身异常规则处理；主题不切换到另一类加载素材。 |
| 选择隐藏品牌标识后出现系统异常、法律声明或第三方服务 | 仅隐藏常规 C 端品牌标识；必需标识仍按对应规则展示。 |
| 切换项目时存在未保存修改 | 提示未保存内容，避免错误应用到其他项目。 |
| 没有主题管理权限 | 不提供主题操作，并提示暂无权限。 |
| 应用时主题已被他人更新 | 不覆盖较新主题，提示刷新后重新确认。 |

## 9. 数据与配置说明

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

| 技术字段 | 含义 | MVP规则 |
|---|---|---|
| `project_id` | 所属项目 | 一个主题只能属于一个项目。 |
| `theme_mode` | 当前主题模式 | `default`或`custom`。 |
| `theme_values` | 项目级主题值 | 保存MVP确认的颜色、边框宽度、圆角、可选加载中 GIF、加载中动画 JSON、品牌 SVG 引用和品牌显示状态；不包含布局参数和系统状态色。 |
| `updated_at` | 最近应用时间 | 应用成功后更新。 |
| `updated_by` | 最近操作人 | 用于基础操作追溯。 |

项目页面配置不保存 `theme_id`或主题颜色副本。

## 10. 验收标准

| AC编号 | Given | When | Then |
|---|---|---|---|
| AC-TH01 | 项目没有个性化主题 | 打开项目页面 | 页面完整使用 VISTA默认主题。 |
| AC-TH02 | 项目没有个性化主题 | 进入项目主题 | 显示默认主题状态和创建入口。 |
| AC-TH03 | 正在编辑主题 | 尚未保存应用 | 只更新预览，不影响真实页面。 |
| AC-TH04 | 配置完整且校验通过 | 保存并应用 | 当前项目所有页面统一使用新主题。 |
| AC-TH05 | 项目存在已启用页面 | 应用新主题 | 页面在下一次读取或刷新时使用新主题，链接继续指向原页面。 |
| AC-TH06 | 项目存在已停用页面 | 应用新主题 | 页面保存内容不变；重新启用后直接使用当前项目主题。 |
| AC-TH07 | 存在项目A和项目B | 修改项目A主题 | 项目B不受影响。 |
| AC-TH08 | 当前使用个性化主题 | 恢复默认 | 当前项目全部页面恢复默认配色，最近一次个性化配置仍被保留。 |
| AC-TH09 | 主题应用失败 | 系统返回失败 | 所有页面继续使用上一个有效主题。 |
| AC-TH10 | 查看主题编辑项 | 检查配置范围 | 不存在布局、规格、字体、内容或系统状态色配置。 |
| AC-TH11 | 品牌色接近系统状态色 | 页面出现对应状态 | 状态色仍使用 VISTA默认值，并配合图标和文字。 |
| AC-TH12 | 当前项目使用默认主题 | 点击创建个性化主题 | 进入第一步并带入VISTA默认主题值作为起点。 |
| AC-TH13 | 正在创建或编辑主题 | 修改任意主题字段 | 同页预览立即更新，真实项目页面保持不变。 |
| AC-TH14 | 进入生成流程 | 查看步骤 | 依次显示基础配色、组件外观、预览与应用三个步骤。 |
| AC-TH15 | 配置颜色字段 | 输入非`#RRGGBB`值 | 指出具体无效字段并禁止保存应用。 |
| AC-TH16 | 配置边框宽度 | 展开选项 | 只显示无边框、细边框、强调边框三档。 |
| AC-TH17 | 配置圆角 | 展开选项 | 只显示直角、小圆角、标准圆角、大圆角四档。 |
| AC-TH18 | 打开系统状态色区域 | 尝试修改 | 错误、警告、成功、禁用等状态色只读且不可覆盖。 |
| AC-TH19 | 当前使用个性化主题 | 点击编辑 | 创建和编辑复用相同四步流程，初始值读取当前主题。 |
| AC-TH20 | 完成第四步且校验通过 | 保存并确认应用 | 当前项目全部页面统一使用新颜色、边框、圆角和品牌配置；布局保持不变。 |
| AC-TH21 | 主题存在可读性警告但颜色格式和必填项有效 | 保存并确认应用 | 系统显示警告并允许操作人员确认应用，不因未定义的对比度阈值阻断。 |
| AC-TH22 | 项目恢复默认且保留过个性化配置 | 再次进入项目主题 | 页面提供继续编辑并重新启用入口，初始值读取最近一次个性化配置。 |
| AC-TH23 | VISTA默认主题升级 | 打开使用默认主题的项目 | 项目自动使用升级后的默认主题。 |
| AC-TH24 | VISTA默认主题升级 | 打开使用个性化主题的项目 | 项目继续使用已保存个性化主题值，系统状态色仍使用最新VISTA规范。 |
| AC-TH25 | 查看项目清单 | 点击“主题管理” | 进入该项目主题管理；左侧不显示项目主题子导航。 |
| AC-TH26 | 多人编辑同一项目主题 | 后提交者保存并应用 | 不静默覆盖较新主题，提示刷新后重新确认。 |
| AC-TH27 | 进入主题生成流程 | 查看步骤 | 依次显示基础配色、组件外观、品牌标识、预览与应用四个步骤。 |
| AC-TH28 | 未配置加载中动画和加载中 GIF | 保存并应用主题 | 两项均保持为空，不自动生成、替代或关联任何加载素材。 |
| AC-TH29 | 当前处于主题编辑会话 | 上传有效 GIF | 当前编辑页显示 GIF 文件名称和预览；项目页面继续使用当前有效主题，直至完成保存并应用。 |
| AC-TH30 | 当前处于主题编辑会话 | 上传可解析 JSON 文件 | 当前编辑页显示加载动画文件名称；JSON 动画场景预览独立显示该配置。 |
| AC-TH31 | 同时配置有效 JSON 动画和 GIF | 打开采用 GIF 或 JSON 方案的不同页面/能力 | 各自仅读取其对应素材，不存在优先级、相互替代或兜底。 |
| AC-TH32 | JSON 动画或 GIF 不可用 | 打开采用该素材的页面或能力 | 按该页面或能力自身异常规则处理；主题不改用另一类加载素材。 |
| AC-TH33 | 上传 PNG、JPG 等不支持格式、无法解析的 JSON，或含脚本/外部资源的 SVG | 上传文件 | 拒绝对应文件并说明格式、解析或安全原因，其他主题字段仍可继续编辑。 |
| AC-TH34 | 当前处于主题编辑会话 | 上传通过安全校验的品牌 SVG | 当前编辑页显示品牌 SVG 预览；打开品牌显示开关时，预览使用该 SVG。 |
| AC-TH35 | 选择“更换”，并上传品牌 SVG | 预览或打开 C 端项目页面 | 显示替换后的品牌 SVG。 |
| AC-TH36 | 选择“隐藏”并完成应用 | 预览或打开该项目任意 C 端页面 | 常规页尾、加载等待页和主题预览均不显示默认或替换后的品牌标识；系统异常、法律声明及第三方服务必需标识不受影响。 |
| AC-TH38 | 已启用页面存在 | 应用任一品牌素材或品牌显示开关变更 | B 端预览与 C 端页面在下一次读取或刷新时使用当前项目新配置。 |
| AC-TH39 | 查看主题预览 | 检查样本头部与交互 | 不显示项目实际或模拟页面名称、项目菜单和页面切换入口；预览不代表项目页面数量或页面结构。 |

## 11. 风险与依赖

| 风险 / 依赖 | 影响 | 应对 |
|---|---|---|
| Widget或模板代码写死颜色 | 主题无法覆盖全部页面 | 将统一主题消费列为开发准入要求。 |
| 错误配置影响全部线上页面 | 影响范围大 | 应用前整体预览、校验和全项目影响确认。 |
| 文字与背景对比度不足 | 可读性下降 | MVP显示警告并要求人工预览；明确阈值后再评估自动阻断。 |
| 主题读取失败 | 页面样式异常 | 整体回退上一个有效主题或默认主题。 |
| 任意边框或圆角值破坏组件一致性 | 不同Widget表现不可预测 | MVP只开放受控档位，不允许自由输入。 |
| SVG 含脚本或外部资源 | 可能产生安全和稳定性风险 | 上传前安全校验并拒绝不安全文件。 |
| JSON 动画不可解析或播放器不兼容 | 页面加载表现异常 | 上传时校验可解析性；运行时异常由采用该素材的页面或能力处理；播放器规格待设计系统补充。 |
| 隐藏品牌标识与合同、法律或第三方要求冲突 | 可能产生对外合规风险 | 本配置只作用于常规 C 端品牌标识；必需标识不得由主题隐藏，具体清单待业务与法务确认。 |

## 12. 待确认事项

1. 已打开的顾客页面是否需要实时更新；当前按刷新或再次打开后生效。
2. 加载中 GIF、加载中动画 JSON 与品牌 SVG 的文件体积、显示尺寸、动画时长、循环策略及无障碍替代文本，均为`待设计系统补充`。
3. 加载中动画 JSON 的具体动画格式、播放器与兼容性校验规则，需由设计系统和研发确认；当前只要求 JSON 可解析。
4. 哪些标识属于不得隐藏的系统、法律或第三方必需标识，需由业务与法务确认；本期仅保证不隐藏这些必需标识。

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

- 不把项目主题扩展为页面装修器或模板编辑器。
- 不在项目页面中保存主题副本或独立主题选择。
- 不允许项目主题覆盖任何系统状态色。
- 不把边框宽度和圆角开放为任意数值。
- “品牌标识”只管理项目级加载中 GIF、加载中动画 JSON、品牌 SVG 与常规 C 端品牌状态，不得扩展为页面内容资产或逐页品牌装修器。
- 品牌 SVG 必须经安全校验；GIF 与 JSON 不定义优先级、相互替代或兜底，加载异常由实际采用它的页面或能力处理。
- 品牌标识只提供“更换 SVG”或“隐藏”两个选择；不得用隐藏选项隐藏系统异常、法律声明或第三方服务的必需标识。
- 可访问性阈值必须继续标记`待设计系统补充`；MVP仅警告，不得作为未定义的自动阻断条件。