nexus/Project/fonrey/UI_DESIGN/系统配置/系统配置_UI.md

系统配置 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