# 首页设置 UI 设计文档

> **任务编号**：10（P1-C）  
> **覆盖范围**：`US-SETTING-010`（管理员配置首页展示内容）  
> **输出文件**：`UI_DESIGN/首页设置_UI.html`  
> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（后台壳层、卡片分组、开关控件、表单校验、保存反馈）  
> **需求依据**：
> - `PRD/TASK.md`（US-SETTING-010）
> - `PRD/系统配置/系统配置参数数据.md`（1. 首页设置）
> - `PRD/系统配置/系统配置模块PRD.md`（配置模块交互规范）
> - `DATA_MODEL/DATA_MODEL_PUBLIC.md`（任务引用）
> **竞品截图参考**：
> - `screenshots/设置/首页设置.png`

---

## 1. 目标与范围

### 1.1 页面目标

本页用于提供“系统配置 → 首页设置”能力，覆盖三个验收点：

1. **可配置首页展示统计卡片**
   - 支持勾选/取消卡片（如：今日新增房源、今日新增客源、今日新增带看等）
   - 支持卡片顺序调整（上移/下移）
2. **配置变更后首页实时生效（原型态）**
   - 编辑区变更实时映射到右侧“首页预览”
   - 点击保存后固化为当前角色配置
3. **不同角色可配置不同首页视图**
   - 提供角色切换（经纪人 / 店长 / 管理员）
   - 每个角色独立保存首页模块与卡片配置

### 1.2 任务边界

- ✅ 包含：页面壳层、配置分组、开关/单选/输入、角色维度、卡片排序、保存校验、实时预览
- ✅ 包含：竞品截图中可见的首页设置分区（员工信息、行程指标、首页业绩、排行榜、成交战报）
- ⛔ 不包含：真实后端 API、真实权限控制、真实首页页面联动

---

## 2. 信息架构

### 2.1 页面骨架

- **Top Bar**：系统一级导航
- **Sidebar**：设置菜单（首页设置高亮）
- **Main Content**：
  1. 面包屑：`系统 / 设置 / 首页设置`
  2. 页面标题：`系统配置-首页设置`
  3. 搜索框：`请输入设置项名称`
  4. 角色视图切换（经纪人/店长/管理员）

### 2.2 配置分区（按竞品还原）

1. **基本设置**
   - 编辑态切换（编辑 / 取消 / 保存）
2. **员工信息模块**
   - 是否展示员工司龄（Switch）
3. **行程模块显示指标**
   - 指标范围（买卖 / 租赁）
4. **首页业绩显示设置**
   - 业绩统计口径（单选）
5. **首页统计卡片配置（补齐任务验收）**
   - 卡片启用开关
   - 顺序上移/下移
6. **排行榜设置**
   - 是否显示业绩和单数
   - 业绩计算方式
   - 默认按店或组排名
   - 默认展示全公司前10排名数据
   - 过滤账号/过滤部门
7. **成交战报设置**
   - 成交时间范围、成交业绩范围
   - 是否显示业绩/房源/房源总价

### 2.3 首页预览区

- 实时展示当前角色的：
  - 已启用统计卡片（按配置顺序）
  - 模块开关结果（员工司龄、排行榜显示项、战报显示项）
- 用于验证“配置变更后实时生效（原型级）”

---

## 3. 核心交互与校验

### 3.1 编辑流转

- 默认只读态：显示“编辑”按钮
- 点击“编辑”进入编辑态：
  - 启用所有表单控件
  - 出现“取消 / 保存配置”按钮
- 点击“取消”恢复到编辑前状态

### 3.2 保存校验

1. 至少启用 1 个首页统计卡片
   - 失败文案：`至少保留 1 个首页统计卡片`
2. 过滤账号输入长度 ≤ 100
   - 失败文案：`过滤账号输入过长，请控制在100字符以内`
3. 过滤部门输入长度 ≤ 100
   - 失败文案：`过滤部门输入过长，请控制在100字符以内`

保存成功后：
- 写入当前角色配置
- 退出编辑态
- Toast：`首页设置已保存，当前角色视图即时生效`

### 3.3 角色维度约束

- 角色切换仅允许在“非编辑态”执行
- 编辑态切换角色时提示：`请先保存或取消当前角色编辑内容`

---

## 4. 数据映射（原型）

> 注：原始 TASK 引用 `DATA_MODEL_PUBLIC.md`，未提供首页设置专用字段明细。原型用前端配置对象模拟持久层。

### 4.1 角色配置结构（模拟）

```json
{
  "role": "manager",
  "show_seniority": true,
  "itinerary_metrics": ["sale", "rent"],
  "kpi_mode": "pending_and_approved",
  "ranking": {
    "show_performance_and_deal": true,
    "calc_mode": "turn_order",
    "default_rank_level": "store",
    "show_company_top10": false,
    "filter_accounts": "",
    "filter_departments": ""
  },
  "battle_report": {
    "days_range": "",
    "amount_range": "",
    "show_performance": false,
    "show_property_name": true,
    "show_property_total_price": false
  },
  "home_cards": [
    {"key": "new_property_today", "enabled": true, "sort": 1},
    {"key": "new_client_today", "enabled": true, "sort": 2}
  ]
}
```

### 4.2 统计卡片枚举（原型）

- 今日新增房源（`new_property_today`）
- 今日新增客源（`new_client_today`）
- 今日新增带看（`new_showing_today`）
- 今日新增跟进（`new_followup_today`）
- 今日签约单量（`signed_deals_today`）
- 今日成交业绩（`deal_amount_today`）

---

## 5. 状态矩阵

| 区域 | 默认态 | 编辑态 | 保存成功 | 保存失败 |
|---|---|---|---|---|
| 基本设置 | 只读展示 | 表单可编辑 | 退出编辑 + Toast | 保持编辑态 + 顶部错误文案 |
| 统计卡片 | 显示已启用卡片 | 可启停+排序 | 预览与配置一致 | 至少1项启用校验阻断 |
| 角色切换 | 允许切换 | 禁止切换 | 切换后加载角色配置 | 提示先保存/取消 |
| 首页预览 | 展示当前角色视图 | 实时反映草稿值 | 与已保存配置一致 | 无 |

---

## 6. 验收清单（静态页）

1. 壳层结构完整（Top Bar + Sidebar + Main）
2. 页面分区覆盖截图中的首页设置关键模块
3. 角色切换可见不同配置结果
4. 统计卡片支持启用/排序，且预览实时变化
5. 保存时触发校验与反馈文案
6. 本地 `file://` 打开控制台 0 报错

---

## 7. 交付物

- `UI_DESIGN/系统配置/首页设置_UI.md`
- `UI_DESIGN/首页设置_UI.html`