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
@@ -1,128 +0,0 @@
|
||||
## 首页设置
|
||||
|
||||
|
||||
## 房源设置
|
||||
### 新增/编辑/查看
|
||||
|
||||
|
||||
### 字段/标签设置
|
||||
|
||||
|
||||
### 相关方设置
|
||||
|
||||
|
||||
### 相关方保护规则设置
|
||||
|
||||
|
||||
### 跟进/面访/回访
|
||||
|
||||
|
||||
### 实勘视频/VR/实地核验
|
||||
|
||||
|
||||
### 预约拍摄设置
|
||||
|
||||
|
||||
### 钥匙/委托/政府核验
|
||||
|
||||
|
||||
### 作业盘设置
|
||||
|
||||
|
||||
### 维护人员设置
|
||||
|
||||
|
||||
### 列表/房源/分级
|
||||
|
||||
|
||||
### 营销设置
|
||||
|
||||
|
||||
### 楼盘设置
|
||||
|
||||
|
||||
### 资料房/业主委托/预录入
|
||||
|
||||
|
||||
### 隐私保护及防骚扰
|
||||
|
||||
|
||||
### 房源检查及纠错
|
||||
|
||||
|
||||
## 新房设置
|
||||
### 新房基本设置
|
||||
|
||||
### 新房参数设置
|
||||
|
||||
|
||||
## 客源设置
|
||||
### 客源基本配置
|
||||
|
||||
|
||||
### 客源参数配置
|
||||
|
||||
|
||||
### 客源相关方配置
|
||||
|
||||
### 客源行政跨部权限
|
||||
|
||||
## 交易设置
|
||||
|
||||
### 交易流程
|
||||
|
||||
### 二手售后流程
|
||||
|
||||
### 新房售后流程
|
||||
|
||||
### 参数&备件条件
|
||||
|
||||
## 财务设置
|
||||
|
||||
### 业绩管理
|
||||
|
||||
### 资金管理
|
||||
|
||||
### 结算设置
|
||||
|
||||
### 提成设置
|
||||
|
||||
|
||||
## 人事OA设置
|
||||
|
||||
### 组织人事基本设置
|
||||
|
||||
### 员工自动升降级设置
|
||||
|
||||
### 审批流程设置
|
||||
|
||||
## 任务设置
|
||||
|
||||
### 参数设置
|
||||
|
||||
### 入职周年祝福设置
|
||||
|
||||
|
||||
## 合同设置
|
||||
|
||||
### 合同基本设置
|
||||
|
||||
## 通用及移动端设置
|
||||
|
||||
### 指标设置
|
||||
### 安全设置
|
||||
|
||||
### 其他设置
|
||||
|
||||
### 电话智能监控设置
|
||||
|
||||
### 黑名单设置
|
||||
|
||||
## 安装与登录设置
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
1100
Project/fonrey/PRD/系统配置/系统配置参数数据.md
Normal file
1100
Project/fonrey/PRD/系统配置/系统配置参数数据.md
Normal file
File diff suppressed because it is too large
Load Diff
275
Project/fonrey/PRD/系统配置/系统配置数据模型设计说明_for_Atlas.md
Normal file
275
Project/fonrey/PRD/系统配置/系统配置数据模型设计说明_for_Atlas.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 系统配置模块 — 数据模型设计说明
|
||||
|
||||
**致**：Atlas（架构师）
|
||||
**来自**：Nova（PM）
|
||||
**日期**：2026-04-27
|
||||
**关联 PRD**：`PRD/系统配置/系统配置模块PRD.md`
|
||||
**关联文档**：`DATA_MODEL/ENUMS.md`、`DATA_MODEL/DATA_MODEL.md`
|
||||
|
||||
---
|
||||
|
||||
## 一、背景与问题
|
||||
|
||||
在设计系统配置模块的数据模型时，我发现当前 `DATA_MODEL/ENUMS.md` 已经明确了「固定枚举」与「可配置枚举」的分层设计，但两者的边界在文档中未完全显式化。本说明文档的目的是：
|
||||
|
||||
1. 厘清三类配置数据各自应存在哪张表
|
||||
2. 指出需要新增的两张表及其建议 DDL
|
||||
3. 说明与 ENUMS.md 现有设计的关系，以及需要 Atlas 补充/修改的内容
|
||||
|
||||
请 Atlas 在完成 `DATA_MODEL/DATA_MODEL.md` 和 `DATA_MODEL/ENUMS.md` 的修订后，同步通知 Nova 确认。
|
||||
|
||||
---
|
||||
|
||||
## 二、三类配置数据的划分
|
||||
|
||||
系统配置涉及三类性质不同的数据，**分属不同的表和 Schema**，请严格区分：
|
||||
|
||||
### 类型 A：固定系统枚举（存 Public Schema / `enum_labels`）
|
||||
|
||||
**特征**：
|
||||
- 值域固定，所有租户共享同一套
|
||||
- 与数据库 `CHECK CONSTRAINT` 绑定（如 `decoration IN ('rough','plain','simple','medium','fine','luxury')`）
|
||||
- 只能由平台研发通过 migration 修改
|
||||
- 租户管理员**无权**增删
|
||||
|
||||
**代表字段**：`property.decoration`（装修）、`property.orientation`（朝向）、`property.status`（交易状态）、`client.status`（客源状态）、`client.grade`（客源等级）、`common.gender`、`common.id_type`
|
||||
|
||||
**现状**：ENUMS.md 已完整定义，`enum_labels` 表 DDL 已存在。**无需改动。**
|
||||
|
||||
---
|
||||
|
||||
### 类型 B：租户可配置枚举（存 Tenant Schema / `lookup_items`，**需新增**）
|
||||
|
||||
**特征**：
|
||||
- 各租户选项不同（如来源渠道：A 公司有「抖音」，B 公司没有）
|
||||
- 租户管理员可通过界面增删排序
|
||||
- 系统预制初始值（`is_system = True`），预制值不可删除但可停用
|
||||
- **无** `CHECK CONSTRAINT`（值域动态）
|
||||
- 与 `enum_labels` 完全独立，不存在于 Public Schema
|
||||
|
||||
**代表字段**：客源来源（`client.source`）、跟进目的（`client_follow_logs.follow_purpose`）、房源来源（`property.source`）
|
||||
|
||||
**ENUMS.md 现状**：
|
||||
- `§2.14 跟进目的` 已明确标注「此枚举为可配置项，存储方式：`lookup_items` 表」，但 `lookup_items` 的 DDL 尚未在任何 DATA_MODEL 文档中定义
|
||||
- `client.source`（来源）在 ENUMS.md 中未定义（因为它是可配置的），但竞品系统有 50+ 预制来源选项
|
||||
|
||||
**需要 Atlas 做的事**：
|
||||
1. 在 `DATA_MODEL/DATA_MODEL.md` 中新增 `lookup_groups` 和 `lookup_items` 表的 DDL
|
||||
2. 在 ENUMS.md 中补充一节「可配置枚举说明」，列出哪些 domain 属于 `lookup_items` 而非 `enum_labels`
|
||||
3. 确认 `apps/setting/` 下新增 `lookup.py` models 文件
|
||||
|
||||
**建议 DDL（供参考，Atlas 可调整）**：
|
||||
|
||||
```sql
|
||||
-- ============================================================
|
||||
-- 可配置枚举分组（租户 Schema）
|
||||
-- ============================================================
|
||||
CREATE TABLE lookup_groups (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
module VARCHAR(50) NOT NULL, -- 'client' | 'property'
|
||||
key VARCHAR(100) NOT NULL, -- 'source' | 'follow_purpose'
|
||||
label_zh VARCHAR(50) NOT NULL, -- 界面显示名称，如「客源来源」
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (module, key)
|
||||
);
|
||||
|
||||
-- ============================================================
|
||||
-- 可配置枚举选项（租户 Schema）
|
||||
-- ============================================================
|
||||
CREATE TABLE lookup_items (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
group_id UUID NOT NULL REFERENCES lookup_groups(id) ON DELETE CASCADE,
|
||||
value VARCHAR(100) NOT NULL, -- 存储值（英文 key，建议 snake_case）
|
||||
label_zh VARCHAR(50) NOT NULL, -- 显示文本
|
||||
is_system BOOLEAN NOT NULL DEFAULT FALSE, -- True=系统预制，不可删除
|
||||
is_active BOOLEAN NOT NULL DEFAULT TRUE,
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||||
created_by UUID REFERENCES staff(id),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (group_id, value)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_lookup_items_group_active ON lookup_items(group_id, is_active, sort_order);
|
||||
```
|
||||
|
||||
**预制种子数据参考**（需写入 migration fixtures，`is_system = TRUE`）：
|
||||
|
||||
| module | key | 预制选项（部分） |
|
||||
|--------|-----|----------------|
|
||||
| `client` | `source` | 门店接待、老客户转介绍、驻守派单、上门、网络-58同城、网络-安居客、微信、朋友介绍 |
|
||||
| `client` | `follow_purpose` | 回拨、推房、带看、维护、其他 |
|
||||
| `property` | `source` | 主动开发、业主上门、老客户转介绍、网络来电 |
|
||||
|
||||
---
|
||||
|
||||
### 类型 C：行为规则与开关（存 Tenant Schema，**需新增两张表**）
|
||||
|
||||
#### C-1：键值配置表 `tenant_settings`
|
||||
|
||||
**特征**：
|
||||
- 存储开关（bool）、阈值（int）、枚举选择（string）等标量类型配置
|
||||
- 每个 key 全局唯一，有默认值
|
||||
- 租户管理员通过界面修改
|
||||
|
||||
**建议 DDL**：
|
||||
|
||||
```sql
|
||||
-- ============================================================
|
||||
-- 租户标量配置表（键值对）
|
||||
-- ============================================================
|
||||
CREATE TABLE tenant_settings (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
category VARCHAR(50) NOT NULL, -- 配置分类：'client' | 'property' | 'showroom'
|
||||
key VARCHAR(100) NOT NULL, -- 配置 key，如 'duplicate_check_scope'
|
||||
value JSONB NOT NULL, -- 存储任意类型（bool/int/str/list）
|
||||
value_type VARCHAR(20) NOT NULL, -- 'bool' | 'int' | 'string' | 'enum'（用于前端渲染）
|
||||
updated_by UUID REFERENCES staff(id),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (category, key)
|
||||
);
|
||||
```
|
||||
|
||||
**MVP 阶段需要预置的 key**：
|
||||
|
||||
| category | key | value_type | 默认值 | 说明 |
|
||||
|----------|-----|-----------|--------|------|
|
||||
| `client` | `duplicate_check_scope` | `enum` | `"self"` | 新增私客查重范围：`self`/`dept`/`company` |
|
||||
|
||||
#### C-2：字段必填规则表 `field_requirement_rules`
|
||||
|
||||
**特征**：
|
||||
- 按「模块 × 实体用途 × 交易状态 × 字段」四元组确定一条规则
|
||||
- 规则值为三态：`required` / `optional` / `hidden`
|
||||
- MVP 仅需支持 `property` 模块
|
||||
|
||||
**建议 DDL**：
|
||||
|
||||
```sql
|
||||
-- ============================================================
|
||||
-- 字段必填/隐藏规则表（租户 Schema）
|
||||
-- ============================================================
|
||||
CREATE TABLE field_requirement_rules (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
module VARCHAR(20) NOT NULL, -- 'property' | 'client'
|
||||
entity_type VARCHAR(50) NOT NULL, -- property_type 值，如 'residential' | 'shop'
|
||||
trade_status VARCHAR(50) NOT NULL, -- 'sale' | 'rent' | 'sale_rent'（or '*' 表示所有）
|
||||
field_key VARCHAR(50) NOT NULL, -- 字段 key，如 'orientation' | 'decoration'
|
||||
requirement VARCHAR(10) NOT NULL -- 'required' | 'optional' | 'hidden'
|
||||
CHECK (requirement IN ('required', 'optional', 'hidden')),
|
||||
updated_by UUID REFERENCES staff(id),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (module, entity_type, trade_status, field_key)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_field_req_lookup ON field_requirement_rules(module, entity_type, trade_status);
|
||||
```
|
||||
|
||||
**MVP 初始规则**（建议由研发预置，管理员可覆盖）：
|
||||
|
||||
| module | entity_type | trade_status | field_key | requirement |
|
||||
|--------|-------------|--------------|-----------|-------------|
|
||||
| `property` | `residential` | `sale` | `orientation` | `optional` |
|
||||
| `property` | `residential` | `sale` | `decoration` | `optional` |
|
||||
| `property` | `residential` | `sale` | `floor` | `optional` |
|
||||
| `property` | `residential` | `rent` | `decoration` | `optional` |
|
||||
| `property` | `residential` | `rent` | `floor` | `optional` |
|
||||
|
||||
---
|
||||
|
||||
## 三、与 ENUMS.md 的冲突与修改建议
|
||||
|
||||
### 冲突点 1：`lookup_items` DDL 缺失
|
||||
|
||||
**现状**：ENUMS.md §2.14 和 §六.4 已提到「可配置枚举通过 `lookup_items` 表管理」，但 `lookup_items` 的 DDL 既不在 ENUMS.md 中，也不在 DATA_MODEL.md 中。
|
||||
|
||||
**建议修改**：在 `DATA_MODEL/ENUMS.md` 末尾（或新增 §七）补充 `lookup_groups` + `lookup_items` 的 DDL 和说明，明确与 `enum_labels` 的区别：
|
||||
|
||||
```markdown
|
||||
## 七、可配置枚举（lookup_items）
|
||||
|
||||
与 `enum_labels`（Public Schema，固定）不同，`lookup_items` 存储在 **Tenant Schema**，
|
||||
由租户管理员自主维护。适用于各租户选项不同的枚举字段。
|
||||
|
||||
[此处补充 DDL 和说明]
|
||||
|
||||
**属于 lookup_items 的 domain**：
|
||||
- `client.source`（客源来源）
|
||||
- `client.follow_purpose`（跟进目的）— 已在 §2.14 说明
|
||||
- `property.source`（房源来源）
|
||||
```
|
||||
|
||||
### 冲突点 2：`client.source`（来源）未在 ENUMS.md 定义
|
||||
|
||||
**现状**：来源是可配置枚举，不应在 ENUMS.md 中定义固定值。但目前 ENUMS.md 中没有任何地方说明「哪些 domain 是可配置的、对应哪张表」，导致读者不清楚来源应该去哪里查。
|
||||
|
||||
**建议修改**：在 ENUMS.md §六 维护约定中新增一条：
|
||||
|
||||
```markdown
|
||||
5. **可配置枚举对照表**：以下 domain 属于 `lookup_items`，不在本文件定义，
|
||||
不建立 CHECK 约束，请查阅 `PRD/系统配置/系统配置模块PRD.md`：
|
||||
- `client.source`
|
||||
- `client.follow_purpose`（已标注）
|
||||
- `property.source`
|
||||
```
|
||||
|
||||
### 冲突点 3：`tenant_settings` 和 `field_requirement_rules` 完全缺失
|
||||
|
||||
**现状**：现有 DATA_MODEL 文档未涵盖这两张表。
|
||||
|
||||
**建议修改**：在 `DATA_MODEL/DATA_MODEL.md` 中新增「系统配置模块数据模型」章节，包含这两张表的 DDL。（本文件的建议 DDL 见第二章 C 节）
|
||||
|
||||
---
|
||||
|
||||
## 四、服务层约定（供研发参考）
|
||||
|
||||
所有业务模块通过统一服务层读取配置，**禁止直接查询配置表**：
|
||||
|
||||
```python
|
||||
# apps/setting/services/tenant_settings_service.py
|
||||
|
||||
class TenantSettingsService:
|
||||
|
||||
def get(self, key: str, default=None):
|
||||
"""
|
||||
读取标量配置（tenant_settings 表）
|
||||
缓存 key：{tenant_schema}:setting:kv:{key}，TTL 5min
|
||||
"""
|
||||
|
||||
def get_lookup_items(self, module: str, key: str) -> list[dict]:
|
||||
"""
|
||||
获取可配置枚举选项（lookup_items 表）
|
||||
仅返回 is_active=True 的项，按 sort_order 排序
|
||||
缓存 key：{tenant_schema}:setting:lookup:{module}.{key}，TTL 5min
|
||||
写入时主动 invalidate
|
||||
"""
|
||||
|
||||
def get_field_requirements(
|
||||
self, module: str, entity_type: str, trade_status: str
|
||||
) -> dict[str, str]:
|
||||
"""
|
||||
获取字段必填规则，返回 {field_key: 'required'|'optional'|'hidden'}
|
||||
缓存 key：{tenant_schema}:setting:field_req:{module}.{entity_type}.{trade_status}，TTL 5min
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、需要 Atlas 完成的具体动作
|
||||
|
||||
| 编号 | 动作 | 修改文件 | 优先级 |
|
||||
|------|------|---------|--------|
|
||||
| A-1 | 新增 `lookup_groups` + `lookup_items` DDL | `DATA_MODEL/DATA_MODEL.md` 或单独 `DATA_MODEL_SETTING.md` | P0（开发依赖） |
|
||||
| A-2 | 新增 `tenant_settings` DDL | 同上 | P0 |
|
||||
| A-3 | 新增 `field_requirement_rules` DDL | 同上 | P0 |
|
||||
| A-4 | ENUMS.md §七 补充可配置枚举说明和对照表 | `DATA_MODEL/ENUMS.md` | P0 |
|
||||
| A-5 | ENUMS.md §六 维护约定新增第 5 条（可配置枚举对照） | `DATA_MODEL/ENUMS.md` | P0 |
|
||||
| A-6 | 确认 `entity_type` 字段的值域与 `property.property_type` 的 CHECK 约束完全一致 | `DATA_MODEL_PROPERTY.md` 对齐 | P0 |
|
||||
| A-7 | 确认 `trade_status` 字段的值域（`sale`/`rent`/`sale_rent`/`*`）是否与 `property.status` 兼容 | `DATA_MODEL_PROPERTY.md` 对齐 | P1 |
|
||||
|
||||
完成以上动作后，请更新 `DATA_MODEL/DATA_MODEL.md` 的版本号，并通知 Nova 做最终 PRD 对齐确认。
|
||||
|
||||
---
|
||||
|
||||
*本文档由 Nova 起草，数据模型最终决策权归 Atlas。如有架构层面的调整，请反馈给 Nova 同步更新 PRD 中的技术考量章节。*
|
||||
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