文档修改

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`