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