# HOMEVISTA A端项目主题管理 PRD

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

## 修订记录

| 版本 | 日期 | 变更类型 | 变更摘要 | 备注 |
|---|---|---|---|---|
| v0.1 | 2026-07-21 | 初始创建 / **重大业务规则确认** | 建立项目级主题管理需求；确认默认主题、单项目单个性化主题、只改配色不改布局，以及主题更新影响全部页面（含已上线页面）。 | 产品确认 / Codex |
| v0.2 | 2026-07-21 | **重大主题范围确认：系统状态色锁定** | 明确错误、警告、成功、禁用及危险操作色不可由项目主题定义或覆盖，只能使用 VISTA 默认状态色。 | 产品确认 / Codex |

## 一、文档目的

本文定义 A端“项目管理 → 项目主题”的产品边界、配置范围、应用规则和验收标准，用于后续页面设计、原型制作、开发和测试。

本文只管理项目级视觉配色，不改变 Widget、页面模板和项目页面的内容职责。

## 二、产品背景与目标

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

本功能目标是：

1. 没有个性化主题的项目自动使用 VISTA 默认主题，无需额外配置。
2. 每个项目最多维护一个个性化主题，统一控制该项目所有 C端页面的配色。
3. 主题从页面背景到项目菜单、Widget 和通用组件统一生效，但不允许改变页面布局。
4. 主题更新后统一影响该项目全部页面，包括草稿、已上线和已下线页面；页面无须逐个重新发布。

## 三、版本范围与明确不做

### 3.1 本期包含

- 项目级默认主题与个性化主题状态；
- 一个项目最多一个个性化主题；
- 项目主题配色编辑；
- 主题预览；
- 保存并应用个性化主题；
- 恢复 VISTA 默认主题；
- 主题变更对当前项目全部页面统一生效；
- 主题配置异常时回退 VISTA 默认主题。

### 3.2 本期明确不做

- 一个项目创建多套主题或在多套主题之间切换；
- 为单个页面单独选择主题；
- 为同一 Widget 的不同区块分别设置配色；
- 修改页面模板、Widget 顺序、区块宽度、间距、尺寸或响应式布局；
- 修改字体、字号、圆角、阴影、动画和图片内容；
- 修改成功、警告、错误、禁用、危险操作、权限不足等系统状态色；这些颜色不可配置，只能使用 VISTA 默认状态色；
- 修改品牌 Logo、项目图片、视频、户型图等内容资产自身颜色；
- 主题版本历史、定时生效、灰度发布和回滚记录；
- 自动从项目 Logo 或图片提取主题颜色。

### 3.3 边界说明

“支持所有 Widget 及组件配色”不表示 A端逐个管理每个 Widget。A端只配置项目级语义颜色；页面模板、Widget 和通用组件必须按照统一主题规则消费这些颜色。新增 Widget 不应要求 A端新增一组 Widget 专属主题字段。

系统状态色不属于项目品牌主题。错误、警告、成功、禁用、危险操作及权限不足等状态色均不可在 A端定义或被项目主题覆盖，只能使用 VISTA 默认状态色。即使项目品牌色与某个状态色接近，也不得修改系统状态色；状态组件应同时使用图标和明确文字，不能只依赖颜色传达含义。

## 四、用户角色与核心场景

### 4.1 目标用户

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

### 4.2 核心场景

- 新项目尚未配置主题，所有页面自动使用 VISTA 默认主题。
- 配置人员为项目建立个性化主题并预览整体效果。
- 配置人员确认应用后，该项目所有页面统一使用新主题。
- 已上线页面在主题更新后直接显示新主题，不需要重新编辑或发布页面。
- 配置人员恢复默认主题，项目所有页面重新使用 VISTA 默认主题。

## 五、核心对象与业务规则

### 5.1 对象关系

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

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

### 5.2 单主题规则

- 每个项目同时只能有一个当前有效的个性化主题。
- 未创建个性化主题时，主题状态显示“使用 VISTA 默认主题”。
- 创建并应用后，主题状态显示“使用个性化主题”。
- 恢复默认后，不再应用个性化主题，所有页面立即使用 VISTA 默认主题。

### 5.3 全项目生效规则

- 项目主题是项目级共享配置，不属于单个页面的发布内容。
- 保存并应用主题后，新主题影响当前项目所有页面，包括已上线页面。
- 页面不需要重新预览或重新发布，既有分享链接不变。
- 主题更新不得改变页面内容、模板引用、Widget 区块、访问权限和页面状态。
- 不同项目之间的主题必须隔离；修改项目 A 的主题不得影响项目 B。

### 5.4 布局不可变规则

主题只能改变颜色。以下内容均不得随主题改变：

- 页面结构和区块顺序；
- PC端与移动端布局；
- Widget 小、中、大展示规格；
- 组件尺寸、间距、圆角、阴影和动画；
- 菜单结构、入口数量和交互方式；
- 文字内容、图片、视频和其他业务数据。

## 六、用户用例

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

**目标**：新项目不做主题配置也能正常生成和展示页面。

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

**主流程**：

1. 配置人员进入“项目管理 → 项目主题”。
2. 页面显示当前项目使用 VISTA 默认主题。
3. 项目页面按 VISTA 默认主题展示。

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

**异常 / 边界**：默认主题资源加载失败时按系统异常处理，不允许显示无样式页面。

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

**目标**：使用项目品牌配色统一调整全部页面。

**前置条件**：已选择项目；用户具有项目配置权限。

**主流程**：

1. 配置人员进入当前项目的“项目主题”。
2. 选择“创建个性化主题”。
3. 配置项目级语义颜色。
4. 查看主题预览。
5. 点击“保存并应用”。
6. 系统提示该操作将影响当前项目全部页面，包括已上线页面。
7. 配置人员确认后，系统应用新主题。

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

**异常 / 边界**：颜色值不合法、必填颜色缺失或可读性校验不通过时，禁止应用。

### UC-003：修改当前个性化主题

**目标**：统一更新项目全部页面的配色。

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

**主流程**：

1. 配置人员修改一个或多个主题颜色。
2. 页面预览展示修改后的效果。
3. 配置人员点击“保存并应用”，并确认全项目影响提示。
4. 系统更新当前项目主题。

**结果**：草稿、已上线和已下线页面均读取新主题；既有分享链接不变。

**异常 / 边界**：保存失败时继续使用修改前的有效主题，不得出现部分页面使用新主题、部分页面使用旧主题。

### UC-004：恢复 VISTA 默认主题

**目标**：停止使用项目个性化主题并恢复平台默认配色。

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

**主流程**：

1. 配置人员点击“恢复 VISTA 默认主题”。
2. 系统提示该操作将影响当前项目全部页面。
3. 配置人员确认。
4. 系统将当前有效主题切换为 VISTA 默认主题。

**结果**：当前项目全部页面统一使用 VISTA 默认主题。

## 七、功能需求矩阵

| 功能ID | 功能名称 | 关联用例 | 优先级 | 状态 |
|---|---|---|---|---|
| TH-001 | 默认主题状态 | UC-001 | P0 | 待设计 |
| TH-002 | 个性化主题配置 | UC-002、UC-003 | P0 | 待设计 |
| TH-003 | 主题预览 | UC-002、UC-003 | P0 | 待设计 |
| TH-004 | 保存并应用 | UC-002、UC-003 | P0 | 待设计 |
| TH-005 | 恢复默认主题 | UC-004 | P0 | 待设计 |
| TH-006 | 全项目页面即时生效 | UC-002、UC-003、UC-004 | P0 | 待开发 |
| TH-007 | 异常回退默认主题 | UC-001、UC-003 | P0 | 待开发 |

## 八、功能详细说明

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

- 入口位于左侧“项目管理 → 项目主题”。
- 必须先选择项目，页面顶部显示当前项目名称和项目标识。
- 切换项目后，必须读取新项目的主题状态和配置，不得沿用上一项目的未保存内容。

### 8.2 主题状态

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

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

### 8.3 配色范围

本期通过项目级语义颜色覆盖业务页面配色，最小范围包括：

| 配置组 | 最小覆盖对象 |
|---|---|
| 基础背景 | 页面背景、内容区域背景、浮层 / 卡片表面色 |
| 品牌与操作 | 主品牌色、辅助强调色、链接、主要按钮和普通交互选中态 |
| 文字与边界 | 主文字、辅助文字、弱提示文字、边框和分隔线 |
| 项目菜单 | 菜单背景、菜单文字、当前项背景、当前项文字 |
| Widget 与通用组件 | Widget 容器、标题、正文、边界、按钮、链接及通用组件的业务配色 |

Widget 与组件不得各自增加一套 A端专属颜色表。开发应将自身颜色映射到以上项目级语义颜色；系统状态色和内容资产颜色除外。

以下配色始终锁定为 VISTA 默认值，不进入任何项目主题配置项：

- 错误；
- 警告；
- 成功；
- 禁用；
- 删除、下线等危险操作；
- 权限不足等系统反馈状态。

### 8.4 主题预览

- 预览至少同时展示页面背景、项目菜单、一个普通 Widget、文字、边界、按钮和链接。
- 预览用于验证配色，不允许在预览中拖拽布局或修改内容。
- 预览不等于已经应用；只有完成“保存并应用”后才影响真实页面。

### 8.5 保存并应用

- 颜色配置完整且通过校验后才能点击“保存并应用”。
- 确认提示必须明确：“应用后将立即影响当前项目全部页面，包括已上线页面；页面无需重新发布。”
- 确认成功后必须整体切换主题，不允许按页面或按 Widget 分批生效。
- 页面显示最近应用时间；MVP 不提供历史版本和一键回滚。

### 8.6 恢复默认主题

- 只有正在使用个性化主题时显示该操作。
- 恢复前必须提示全项目影响。
- 恢复后项目页面统一读取 VISTA 默认主题。

## 九、交互与状态规则

1. 当前项目未定义主题时，默认主题自动有效，不显示空白或未配置错误。
2. 编辑中的颜色在“保存并应用”前只影响预览，不影响真实页面。
3. 应用成功后，所有页面下一次渲染时读取新主题；已经打开的页面刷新后必须读取新主题。
4. 主题应用失败时，继续使用上一个有效主题；没有上一个个性化主题时使用 VISTA 默认主题。
5. 主题更新不改变项目页面的“有尚未发布的修改”状态，因为主题不属于页面发布内容。
6. 已下线页面虽然当前不可访问，但重新上线时必须使用项目当前有效主题。
7. 项目主题被恢复默认后，不要求删除历史主题数据；MVP 页面不提供历史恢复入口。

## 十、数据与配置说明

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

| 字段 | 含义 | MVP 规则 |
|---|---|---|
| `project_id` | 所属项目 | 一个主题只能属于一个项目。 |
| `theme_mode` | 当前主题模式 | `default` 或 `custom`。 |
| `theme_values` | 项目级语义颜色 | 只保存配色，不包含布局参数。 |
| `updated_at` | 最近应用时间 | 应用成功后更新。 |
| `updated_by` | 最近操作人 | 用于基础操作追溯。 |

项目页面的发布内容不再保存 `theme_id` 或主题颜色副本。页面渲染时依据 `project_id` 读取项目当前有效主题；因此主题变更无需重新发布页面。

## 十一、验收标准

| AC 编号 | Given | When | Then |
|---|---|---|---|
| AC-TH01 | 项目没有个性化主题 | 打开任一项目页面 | 页面完整使用 VISTA 默认主题。 |
| AC-TH02 | 项目没有个性化主题 | 进入项目主题 | 显示“使用 VISTA 默认主题”和“创建个性化主题”。 |
| AC-TH03 | 正在配置个性化主题 | 修改配色但未保存应用 | 只更新预览，不影响真实页面。 |
| AC-TH04 | 配色完整且校验通过 | 确认保存并应用 | 当前项目所有页面统一使用新主题。 |
| AC-TH05 | 当前项目存在已上线页面 | 应用新主题 | 已上线页面无需重新发布，刷新后使用新主题，链接不变。 |
| AC-TH06 | 当前项目存在草稿和已下线页面 | 应用新主题 | 草稿预览和已下线页面重新上线时使用新主题。 |
| AC-TH07 | 项目 A 与项目 B 均存在 | 修改项目 A 主题 | 项目 B 的主题和页面不受影响。 |
| AC-TH08 | 当前项目使用个性化主题 | 恢复 VISTA 默认主题 | 当前项目全部页面统一恢复默认配色。 |
| AC-TH09 | 主题应用发生失败 | 系统返回失败 | 全部页面继续使用上一个有效主题，不出现混合状态。 |
| AC-TH10 | 配置项目主题 | 查看编辑项 | 不出现布局、尺寸、区块顺序、字体或内容资产编辑项。 |
| AC-TH11 | 任意已接入主题规则的模板 | 切换默认与个性化主题 | 页面背景、菜单、Widget 和通用组件业务配色均随主题变化，系统状态色保持 VISTA 规则。 |
| AC-TH12 | 进入项目主题配置 | 查看全部可配置颜色 | 不存在错误、警告、成功、禁用、危险操作或权限不足状态色的配置入口。 |
| AC-TH13 | 项目品牌色接近某个状态色 | 页面出现对应系统状态 | 状态色仍使用 VISTA 默认值，并通过图标和明确文字表达状态含义。 |

## 十二、风险与依赖

| 风险 / 依赖 | 影响 | 应对 |
|---|---|---|
| 某些 Widget 或模板代码写死颜色 | 个性化主题无法覆盖全部页面 | 将主题变量消费列为 Widget、模板和通用组件的开发准入要求。 |
| 一次错误配置影响全部线上页面 | 影响范围大 | 应用前提供整体预览、颜色校验和明确的全项目影响确认。 |
| 文字与背景对比度不足 | 可读性下降 | 应用前执行对比度校验；具体阈值待设计规范确认。 |
| 主题读取失败 | 页面样式异常 | 原子切换并回退上一个有效主题或 VISTA 默认主题。 |
| VISTA 默认主题未来升级 | 未配置项目的页面外观变化 | 默认主题版本策略列入待确认，不能在开发时自行决定。 |

## 十三、待确认事项

1. VISTA 默认主题升级后，使用默认主题的项目是自动跟随升级，还是继续使用创建项目时的默认版本。
2. 项目级语义颜色的最终字段数量、命名和默认值，需要结合 VISTA C 设计系统完成设计评审。
3. 文字与背景的最低对比度标准，以及校验不通过时是否允许强制应用。
4. MVP 是否需要保留最近一次个性化主题，以便“恢复默认”后再次启用；页面暂不提供历史版本入口。
5. 已经打开的顾客页面是否需要实时刷新主题，还是用户刷新 / 再次打开后生效。当前 PRD 按“刷新或再次打开后生效”定义。

## 十四、供 Codex 使用的执行说明

- 后续原型只能制作本文已确认的配色、预览、保存并应用和恢复默认流程。
- 不得把项目主题扩展为页面装修器、模板编辑器或 Widget 布局编辑器。
- 不得在项目页面对象中继续保存独立主题选择或主题副本。
- 未确认的语义颜色字段、可访问性阈值和默认主题版本策略必须标记为待确认。