docs: 新增系统配置模块PRD及数据模型文档，更新TASK.md
- 新增 PRD/系统配置/系统配置模块PRD.md（v0.1 Draft） - MVP 范围：US-SETTING-001-A（Lookup Items）、B（房源字段必填规则）、C（客源录入规则） - 新增 PRD/系统配置/系统配置数据模型设计说明_for_Atlas.md - 新增 PRD/系统配置/系统配置参数数据.md（竞品参数数据） - 删除旧版 PRD/系统配置/系统配置.md（已被新PRD替代） - 新增 DATA_MODEL/DATA_MODEL_SETTING.md（系统配置数据模型） - 新增 DATA_MODEL/ENUMS.md（枚举定义与约定） - 新增 AGENTS.md（AI Agent 开发规范） - 更新 PRD/TASK.md：US-SETTING-001 拆分为 A/B/C 三个子任务，修正参考文档路径与验收标准 - 新增 VIBE_CODING_开工前缺失清单.md - 新增 TECH_STACK/房源管理技术方案.md - 更新 DATA_MODEL/DATA_MODEL.md、DATA_MODEL_CLIENT.md、DATA_MODEL_LOGIN.md - 更新 PRD/PRD_MVP.md、PRD/权限管理/权限管理模块PRD.md - 更新 TECH_STACK/TECH_STACK.md、权限管理系统技术方案.md - 更新 UI_DESIGN/preview.html、UI_SYSTEM/UI_SYSTEM.md - 新增 prompt/PRD - 为系统设置生成PRD设计文档.md、更新 prompt 模板
This commit is contained in:
Shen Wei
273
Project/fonrey/PRD/系统配置/系统配置模块PRD.md
Normal file
273
Project/fonrey/PRD/系统配置/系统配置模块PRD.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# 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`
|
||||
|
||||
---
|
||||
|
||||
## 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. 目标用户
|
||||
|
||||
**主要角色**：系统管理员（租户侧，每租户 1～3 人）
|
||||
|
||||
> 典型画像：门店运营负责人或行政主管，熟悉业务流程，无技术背景，通过系统后台进行日常运营配置。使用频率：初始开通时高频（完成初始化配置），此后低频（按需调整）。
|
||||
|
||||
**间接受益角色**：
|
||||
- 一线经纪人 — 看到的下拉选项和必填规则由管理员配置决定
|
||||
- 店长/经理 — 配置直接影响客源来源分析报表的数据质量
|
||||
|
||||
---
|
||||
|
||||
## 5. User Stories 与验收标准
|
||||
|
||||
---
|
||||
|
||||
### US-SETTING-001-A：管理员配置可选枚举值（Lookup Items）
|
||||
|
||||
> **As** 系统管理员，
|
||||
> **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** 系统管理员，
|
||||
> **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** 系统管理员，
|
||||
> **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` 表，由平台管理员通过 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`
|
||||
Reference in New Issue
Block a user