文档修改

2026-04-29 15:43:49 +08:00
parent c3f9de5f9f
commit b2aadf771a
28 changed files with 7502 additions and 109 deletions
--- a/Project/fonrey/UI_DESIGN/系统配置/系统配置_UI.md
+++ b/Project/fonrey/UI_DESIGN/系统配置/系统配置_UI.md
@@ -0,0 +1,179 @@
+# 系统配置 UI 设计文档
+
+> **任务编号**：09（P0-C）  
+> **覆盖范围**：`US-SETTING-001-A / US-SETTING-001-B / US-SETTING-001-C`  
+> **输出文件**：`UI_DESIGN/系统配置_UI.html`  
+> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（后台壳层、筛选区、表格、Modal/Drawer、表单校验）  
+> **需求依据**：
+> - `PRD/TASK.md`（系统配置章节，US-SETTING-001-A/B/C）
+> - `PRD/系统配置/系统配置模块PRD.md`
+> - `PRD/系统配置/系统配置参数数据.md`
+> - `DATA_MODEL/DATA_MODEL_SETTING.md`
+> - `DATA_MODEL/ENUMS.md`
+> **竞品截图参考**：
+> - `screenshots/设置/客源设置-客源参数配置.png`
+> - `screenshots/设置/客源设置-基本配置.jpg`
+> - `screenshots/设置/房源设置-字段标签设置.png`
+> - `screenshots/设置/房源设置-字段标签设置-修改字段必填要求.png`
+> - `screenshots/设置/房源设置-字段标签设置-自定义预设参数.png`
+
+---
+
+## 1. 目标与范围
+
+### 1.1 页面目标
+
+本页用于承载系统配置模块 MVP 的三条核心能力：
+
+1. **参数配置（US-SETTING-001-A）**
+   - 管理租户可配置枚举（`lookup_items`）：客源来源、跟进目的、房源来源
+   - 支持新增项目值、调整排序、停用/启用
+   - 系统预制项（`is_system=true`）不可删除
+2. **房源字段规则（US-SETTING-001-B）**
+   - 以「用途 × 交易状态」查看规则矩阵
+   - 支持字段三态：必填 / 选填 / 隐藏（`required/optional/hidden`）
+   - MVP 字段范围：朝向、装修、楼层、建筑面积、套内面积、房型、产权年限、车位数
+3. **客源规则（US-SETTING-001-C）**
+   - 配置新增私客查重范围：本人 / 本部门 / 全公司
+   - 配置客源必填字段（等级、来源默认必填）
+   - 保存后提示规则生效与缓存失效
+
+### 1.2 任务边界
+
+- ✅ 包含：系统设置壳层、三主 Tab、配置表格、参数编辑弹窗、字段规则编辑抽屉、规则保存反馈
+- ✅ 包含：新增项必填校验、重复值校验、系统项删除限制、客源必填字段保护校验
+- ⛔ 不包含：真实后端 API、真实 Redis 调用、真实跨页面即时联动
+
+---
+
+## 2. 信息架构
+
+### 2.1 页面骨架
+
+- **Top Bar**：一级导航（系统模块高亮）
+- **Sidebar**：设置目录（系统配置高亮）
+- **Main Content**：
+  1. 面包屑：`系统 / 设置 / 系统配置`
+  2. 主 Tab：`参数配置` / `房源字段规则` / `客源规则`
+
+### 2.2 参数配置（US-SETTING-001-A）
+
+1. 筛选区
+   - 关键字（参数项/项目值）
+   - 模块筛选（客源/房源）
+2. 参数分组卡片（3组）
+   - 客源来源（`client.source`）
+   - 跟进目的（`client.follow_purpose`）
+   - 房源来源（`property.source`）
+3. 分组表格列
+   - 项目值、排序、状态、来源（预制/自定义）、操作
+4. 编辑弹窗（分组级）
+   - 项目值输入（可多行）
+   - 上移/下移排序
+   - 新增项目
+   - 删除（系统预制项禁用）
+   - 启用/停用切换
+
+### 2.3 房源字段规则（US-SETTING-001-B）
+
+1. 规则矩阵列表（组合级）
+   - 住宅×出售、住宅×出租、商铺×出售、商铺×出租
+2. 组合列表列
+   - 用途、交易状态、必填字段数、隐藏字段数、更新时间、操作
+3. 规则编辑抽屉
+   - 字段名称
+   - 必填/选填/隐藏（Radio）
+   - 录入页展示（Switch，关闭即 hidden）
+
+### 2.4 客源规则（US-SETTING-001-C）
+
+1. 查重范围卡片
+   - 单选：本人 / 本部门 / 全公司
+   - 每个选项附说明文案
+2. 必填字段卡片
+   - 等级、来源（锁定为必填）
+   - 总价区间、居室需求、购房目的（可配置）
+3. 保存反馈卡片
+   - 说明保存后缓存 key `{tenant_schema}:setting:client_rules` 失效
+
+---
+
+## 3. 核心交互与校验
+
+### 3.1 参数配置弹窗
+
+- 新增空项目后点击保存：提示 `项目值不能为空`
+- 同一分组内重名：提示 `项目值不可重复`
+- 系统预制项删除：禁止，提示 `系统预制项不可删除，仅可停用`
+- 保存成功：
+  - 回写分组列表
+  - Toast：`参数已保存，缓存失效：{tenant_schema}:setting:lookup:{module}.{key}`
+
+### 3.2 字段规则编辑抽屉
+
+- 每个字段仅允许三态之一（required/optional/hidden）
+- 关闭“录入页展示”开关时自动设为 `hidden`
+- 开启“录入页展示”且当前为 hidden 时自动回退为 `optional`
+- 保存成功：
+  - 更新矩阵统计（必填数/隐藏数）
+  - Toast：`字段规则已保存，缓存失效：{tenant_schema}:setting:field_req:{module}.{entity_type}.{trade_status}`
+
+### 3.3 客源规则保存
+
+- `等级`、`来源`不得取消必填
+- 若取消则拦截并提示：`等级、来源为默认必填字段，不可取消`
+- 保存成功提示：
+  - `客源规则已保存，缓存失效：{tenant_schema}:setting:client_rules`
+
+---
+
+## 4. 数据模型与配置映射
+
+### 4.1 Lookup 映射（001-A）
+
+- `lookup_groups.module + key`：参数分组
+- `lookup_items`：项目值列表
+- UI 字段映射：
+  - 项目值 → `label_zh`
+  - 排序 → `sort_order`
+  - 状态 → `is_active`
+  - 来源 → `is_system`
+
+### 4.2 字段规则映射（001-B）
+
+- 表：`field_requirement_rules`
+- 维度：`module + entity_type + trade_status + field_key`
+- 规则值：`requirement`（required/optional/hidden）
+
+### 4.3 客源规则映射（001-C）
+
+- 表：`tenant_settings`
+- `category=client, key=duplicate_check_scope`
+- 客源必填字段规则以规则快照形式保存（原型中以本地对象模拟）
+
+---
+
+## 5. 状态矩阵
+
+| 区域 | 默认态 | 编辑态 | 保存成功 | 校验失败 |
+|---|---|---|---|---|
+| 参数配置 | 分组列表展示 | 弹窗内增删改排序 | 列表更新 + Toast | 错误文案红字 |
+| 字段规则 | 矩阵列表展示 | 抽屉内逐字段三态设置 | 统计更新 + Toast | 保持抽屉不关闭 |
+| 客源规则 | 查重范围 + 必填项配置 | 单选/勾选编辑 | Toast + 状态持久 | 顶部错误提示 |
+
+---
+
+## 6. 验收清单（静态页）
+
+1. 三主 Tab 切换后内容区替换且壳层不变
+2. 参数配置弹窗覆盖：空值校验、重复值校验、系统项删除限制
+3. 房源字段规则抽屉覆盖：三态切换、显示开关联动、保存回写统计
+4. 客源规则覆盖：查重范围切换、默认必填保护、保存提示
+5. 控制台 0 报错后方可进入待评审
+
+---
+
+## 7. 交付物
+
+- `UI_DESIGN/系统配置/系统配置_UI.md`
+- `UI_DESIGN/系统配置_UI.html`
--- a/Project/fonrey/UI_DESIGN/系统配置/首页设置_UI.md
+++ b/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`