180 lines
6.4 KiB
Markdown
180 lines
6.4 KiB
Markdown
# 系统配置 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`
|