13 KiB
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 + 必填规则）
核心设计决策：
-
Lookup Items 与 enum_labels 分离：固定系统枚举（装修/朝向/状态/等级）存放在 Public Schema 的
enum_labels表，由Platform Admin（平台超级管理员）通过 migration 维护，租户无权修改。可配置枚举（来源/跟进目的）存放在 Tenant Schema 的lookup_items表，由租户管理员自主维护。详见数据模型说明文档。 -
字段规则不新增字段：
field_requirement_rules只控制「必填/选填/隐藏」状态，字段本身的存在性由数据模型决定。避免配置层与数据模型层职责混淆。 -
所有配置读取走服务层：业务模块（房源/客源录入）通过
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. 附录
- 竞品系统配置参数数据
- 数据模型设计说明（写给 Atlas）
- ENUMS.md：
DATA_MODEL/ENUMS.md - 总体数据模型：
DATA_MODEL/DATA_MODEL.md