文档修改

Project/fonrey/UI_DESIGN/系统配置/首页设置_UI.md

@@ -0,0 +1,186 @@
+# 首页设置 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`