# PRD：系统配置模块（MVP）

**状态**：Draft  
**作者**：Nova（PM）  
**最后更新**：2026-04-27  
**版本**：v0.1  
**关联 Task**：US-SETTING-001  
**相关文档**：`DATA_MODEL/ENUMS.md`、`PRD/系统配置/系统配置参数数据.md`、`DATA_MODEL/DATA_MODEL.md`

## 变更历史

| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|---------|
| v0.1 | 2026-04-27 | Nova（PM） | 初稿（MVP 范围） |


---

## 1. 问题陈述

**背景**：Fonrey 各业务模块（房源录入、客源录入、跟进记录、带看）中存在大量下拉选项、业务规则开关、字段必填控制。如果这些值硬编码在代码中，将导致：
- 不同租户无法根据自身业务习惯调整选项（如来源渠道、跟进目的）
- 管理员无法灵活控制录入数据质量（如哪些字段必填）
- 业务规则变更（如查重范围）需要研发介入，无法自服务

**核心问题**：租户管理员无法通过界面自主维护业务枚举选项和录入规则，导致高频配置变更依赖研发，降低了系统的可用性与租户自服务能力。

**MVP 范围决策**：竞品系统配置涵盖 10+ 大类、100+ 设置项，MVP 阶段仅实现影响核心业务链路的 3 类配置，其余推迟至 P1/P2。

---

## 2. 目标与成功指标

| 目标            | 度量指标           | 当前基线          | 目标值                  | 测量窗口     |
| ------------- | -------------- | ------------- | -------------------- | -------- |
| 管理员可自主维护枚举选项  | 系统配置依赖研发变更的工单数 | 100%（所有变更需研发） | 0（枚举类变更全部自服务）        | 上线后 30 天 |
| 房源/客源录入数据质量提升 | 必填字段为空的录入比例    | 未知（当前无必填控制）   | < 5%                 | 上线后 60 天 |
| 配置变更生效时效      | 配置保存到前端生效的时间   | N/A           | ≤ 5 分钟（Redis 缓存 TTL） | —        |

---

## 3. 非目标（MVP 明确不做）

以下内容在竞品中存在，但 MVP 阶段不实现：

- ❌ 房源标签配置（颜色/排序/启用）— 标签功能整体推迟至 P1
- ❌ 私盘数量上限配置 — 推迟至 P1（当前无私盘流转业务逻辑）
- ❌ 带看规则配置（补录时间、附件必填等）— 带看功能推迟至 P1
- ❌ 跟进置顶条数限制 — 推迟至 P1
- ❌ 公司信息（Logo、名称、联系方式）— 归入系统管理模块（平台运营层），非租户配置
- ❌ 区域/商圈配置 — 归入楼盘管理模块（US-COMPLEX-003）
- ❌ 委托/交易/财务/合同相关配置 — 超出 MVP 范围
- ❌ 通知消息配置 — P2
- ❌ 发布平台配置 — P2

---

## 4. 目标用户

**主要角色**：Tenant Admin（租户管理员）（租户侧，每租户 1～3 人）

> 典型画像：门店运营负责人或行政主管，熟悉业务流程，无技术背景，通过系统后台进行日常运营配置。使用频率：初始开通时高频（完成初始化配置），此后低频（按需调整）。

**间接受益角色**：
- Agent（经纪人） — 看到的下拉选项和必填规则由管理员配置决定
- 店长/经理 — 配置直接影响客源来源分析报表的数据质量

---

## 5. User Stories 与验收标准

---

### US-SETTING-001-A：管理员配置可选枚举值（Lookup Items）

> **As** Tenant Admin（租户管理员），  
> **I want** 在「系统设置 → 参数配置」页面维护各业务模块的下拉选项（如客源来源、跟进目的），  
> **So that** 经纪人录入时看到的选项符合公司实际业务，不再依赖研发修改代码。

#### 验收标准

**AC-1：参数分组展示**
- Given 管理员进入「系统设置 → 参数配置」
- When 页面加载完成
- Then 页面按模块分组展示所有可配置参数项，至少包含：
  - 「客源」分组：客源来源、跟进目的
  - 「房源」分组：房源来源
- 每个分组展示当前已有选项列表（名称 + 排序 + 状态）

**AC-2：新增自定义选项**
- Given 管理员点击某参数项的「编辑」按钮
- When 弹出编辑抽屉，填写「选项名称」并提交
- Then 新选项追加至列表末尾，排序值自动计算
- And 经纪人在录入界面的对应下拉中立即可见该新选项（刷新后生效）

**AC-3：停用选项（不可删除系统预制项）**
- Given 管理员在编辑态对某选项执行「停用」操作
- When 确认提交
- Then 该选项的 `is_active` 置为 False
- And 前端录入下拉中不再展示该选项
- And 历史已选该值的记录保留原值不变，仅展示时标注「已停用」
- And 系统预制选项（`is_system = True`）的「删除」按钮禁用，仅可停用

**AC-4：调整选项排序**
- Given 管理员在编辑态拖拽选项或修改排序值
- When 保存后
- Then 经纪人录入下拉中按新排序展示

**AC-5：缓存一致性**
- Given 管理员保存配置变更
- When 变更写入数据库成功
- Then 对应 Redis 缓存 key 主动失效（`{tenant_schema}:setting:lookup:{module}.{key}`）
- And 所有经纪人在下次请求时获取到最新选项（最长 5 分钟延迟）

**AC-6：MVP 必须覆盖的参数项**

| 模块 | 参数 key | 中文名 | 系统预制值（部分示例） |
|------|---------|--------|------------------|
| `client` | `source` | 客源来源 | 门店接待、老客户转介绍、网络（58/安居客）、驻守、上门、朋友介绍 |
| `client` | `follow_purpose` | 跟进目的 | 回拨、推房、带看、维护、其他 |
| `property` | `source` | 房源来源 | 主动开发、业主上门、老客户转介绍、网络来电 |

---

### US-SETTING-001-B：管理员配置房源字段必填规则

> **As** Tenant Admin（租户管理员），  
> **I want** 按「房源用途 × 交易状态」的组合，控制哪些字段在录入时为必填/选填/隐藏，  
> **So that** 系统能在录入时强制采集公司要求的关键信息，提升房源数据完整度。

#### 验收标准

**AC-1：规则配置页面**
- Given 管理员进入「系统设置 → 房源字段规则」
- When 页面加载
- Then 以「用途 × 交易状态」为维度展示配置矩阵，MVP 仅需支持：
  - 住宅 × 出售
  - 住宅 × 出租
  - 商铺 × 出售（可选）
  - 商铺 × 出租（可选）
- 每个组合展示可配置字段列表，字段来源见 AC-4

**AC-2：规则编辑**
- Given 管理员点击某组合的「编辑」按钮
- When 进入编辑态
- Then 每个字段显示当前规则（必填 / 选填 / 隐藏），以三态 Toggle 或 Radio 形式展示
- And 管理员修改后点击「保存」提交

**AC-3：规则应用于录入界面**
- Given 管理员保存了「住宅 × 出售」的规则：朝向=必填，车位数=隐藏
- When 经纪人在录入界面新增「住宅 × 出售」房源
- Then 朝向字段显示必填标记（*），提交时若为空则拦截并提示
- And 车位数字段不显示（隐藏）
- And 规则变更在配置保存后立即对新录入生效（不影响存量房源）

**AC-4：MVP 可配置字段范围**

| 字段 | 字段 key | 说明 |
|------|---------|------|
| 朝向 | `orientation` | 对应 `property.orientation` 枚举 |
| 装修情况 | `decoration` | 对应 `property.decoration` 枚举 |
| 楼层 | `floor` | 所在楼层 / 总楼层 |
| 建筑面积 | `building_area` | 数值字段 |
| 套内面积 | `inner_area` | 数值字段 |
| 房型（室/厅/卫） | `room_layout` | 数值字段组 |
| 产权年限 | `ownership_years` | 数值字段 |
| 车位数 | `parking_count` | 数值字段 |

> **注**：字段是否存在于数据模型由 `DATA_MODEL_PROPERTY.md` 决定，本配置只控制「是否必填/展示」，不新增字段。

---

### US-SETTING-001-C：管理员配置客源录入规则

> **As** Tenant Admin（租户管理员），  
> **I want** 配置新增私客时的查重范围，以及必填字段控制，  
> **So that** 减少客源重复录入风险，并确保客源数据质量满足公司管理要求。

#### 验收标准

**AC-1：查重范围配置**
- Given 管理员进入「系统设置 → 客源规则」
- When 查看「新增私客查重范围」设置项
- Then 可选值为：
  - `本人`（默认）— 同一经纪人不可重复录入同一手机号
  - `本部门` — 同部门内不可重复
  - `全公司` — 全租户范围不可重复
- And 每个选项有说明文案，明确告知管理员改动影响范围

**AC-2：查重规则应用**
- Given 管理员将查重范围设置为「本部门」
- When 经纪人录入私客手机号时
- Then 系统在失焦后实时检测同部门内是否存在相同手机号（加密比对）
- And 若存在重复，页面提示：「该号码在本部门已有记录，归属人：XXX，录入时间：XX」
- And 经纪人可选择「仍然录入」（走审批流）或「放弃」

**AC-3：客源必填字段配置**
- Given 管理员在「客源规则」页面勾选必填字段
- When 保存
- Then 经纪人录入私客时，已勾选的字段显示必填标记（*），提交时校验
- And MVP 可配置必填的字段范围：

| 字段 | 字段 key | 默认值 |
|------|---------|--------|
| 等级 | `grade` | 必填 |
| 来源 | `source` | 必填 |
| 求购/求租总价区间 | `budget_range` | 选填 |
| 居室需求 | `room_requirement` | 选填 |
| 购房目的 | `buying_purpose` | 选填 |

**AC-4：配置变更即时生效**
- Given 管理员修改任一客源规则并保存
- When 经纪人下次打开录入界面
- Then 应用最新规则（无需重新登录）
- And Redis 缓存 key `{tenant_schema}:setting:client_rules` 在保存时主动失效

---

## 6. 解决方案概述

**页面结构**：

```
系统设置（侧边栏）
├── 参数配置          ← US-SETTING-001-A（Lookup Items 管理）
├── 房源字段规则      ← US-SETTING-001-B（FieldRequirementRule）
└── 客源规则          ← US-SETTING-001-C（TenantSetting + 必填规则）
```

**核心设计决策**：

1. **Lookup Items 与 enum_labels 分离**：固定系统枚举（装修/朝向/状态/等级）存放在 Public Schema 的 `enum_labels` 表，由Platform Admin（平台超级管理员）通过 migration 维护，租户无权修改。可配置枚举（来源/跟进目的）存放在 Tenant Schema 的 `lookup_items` 表，由租户管理员自主维护。详见数据模型说明文档。

2. **字段规则不新增字段**：`field_requirement_rules` 只控制「必填/选填/隐藏」状态，字段本身的存在性由数据模型决定。避免配置层与数据模型层职责混淆。

3. **所有配置读取走服务层**：业务模块（房源/客源录入）通过 `TenantSettingsService` 统一读取配置，不直接查表，便于统一缓存管理。

---

## 7. 技术考量

**依赖**：
- `apps/setting/` — 配置模块宿主 App（已在 AGENTS.md 目录结构中定义）
- `core/cache.py` — Redis 工具（租户前缀管理）
- `DATA_MODEL/ENUMS.md` — `enum_labels` 设计权威来源，`lookup_items` 需与之对齐

**已知风险**：

| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|---------|
| 缓存失效不及时导致配置延迟生效 | 中 | 低 | 保存时主动 invalidate；最长 5 min TTL 兜底 |
| 字段必填规则与前端渲染逻辑耦合 | 中 | 中 | 后端在每次 form 请求时返回规则快照，前端不缓存规则 |
| 历史数据与「已停用枚举值」展示冲突 | 低 | 低 | 已停用值在展示时追加「（已停用）」后缀，数据库值不变 |

**待解决的 Open Questions**（启动开发前必须确认）：

- [ ] `lookup_items` 表的最终 DDL 由 Atlas 确认后同步至 `DATA_MODEL/DATA_MODEL.md` — **Owner: Atlas / Deadline: 开发启动前**
- [ ] 字段必填规则是否需要支持「按角色」粒度（如经纪人必填、店长选填）— **当前决策：MVP 不做角色粒度，全员统一规则。如需变更请在 Review 中提出。**
- [ ] `FieldRequirementRule` 中「房源用途」的枚举值与 `property.property_type` 是否完全一致 — **Owner: Atlas 对齐 DATA_MODEL_PROPERTY.md**

---

## 8. 上线计划

| 阶段 | 时间 | 受众 | 成功门槛 |
|------|------|------|---------|
| 内部联调 | Sprint N | 开发团队 + 测试 | 3 个 US 核心流程无 P0 Bug |
| Alpha 验证 | Sprint N+1 | 1 家种子客户管理员 | 管理员可独立完成初始化配置，无需研发介入 |
| MVP 上线 | Sprint N+2 | 全部租户 | 配置变更工单量为 0（全自服务） |

**回滚条件**：配置保存后前端报错率 > 5%，或经纪人录入报错率相比上线前上升 > 2%，立即回滚并排查。

---

## 9. 附录

- [竞品系统配置参数数据](./系统配置参数数据.md)
- [数据模型设计说明（写给 Atlas）](./系统配置数据模型设计说明_for_Atlas.md)
- ENUMS.md：`DATA_MODEL/ENUMS.md`
- 总体数据模型：`DATA_MODEL/DATA_MODEL.md`