Files

2026-04-30 20:33:51 +08:00

8.5 KiB

Raw Blame History

For AI assistants: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.

Fonrey 系统管理（系统设置）技术方案

版本: 1.2
项目: Fonrey 房产经纪管理系统
技术栈: Django 4.x + HTMX + Alpine.js + PostgreSQL 16 + Redis
关联 PRD: PRD/系统配置/系统配置模块PRD.md
关联数据模型: DATA_MODEL/DATA_MODEL_SETTING.md（本方案不重复 DDL）
关联契约规范: TECH_STACK/API_CONTRACT.md（全局 API 契约权威）
关联枚举字典: DATA_MODEL/ENUMS.md
最后更新: 2026-04-27

变更历史

日期	变更人	变更内容
2026-04-30	Atlas	补充“变更历史”章节（文档治理）

一、文档定位与边界

本文件仅定义系统设置模块的：

页面与 API 端点设计
配置读取服务与调用边界
缓存一致性与审计策略
错误码与测试映射

不在本文件展开 lookup_groups/lookup_items/tenant_settings/field_requirement_rules 的 DDL。数据结构以 DATA_MODEL_SETTING.md 为唯一权威。

二、范围定义（US-SETTING-001）

2.1 MVP 必须覆盖

A：管理员配置可选枚举值（lookup items）
B：管理员配置房源字段必填规则
C：管理员配置客源规则（查重范围 + 必填字段）

2.2 预留（非本期强制）

财务/交易/合同参数配置
通知渠道与发布平台配置
高级规则引擎（跨模块联动）

三、模块架构边界

3.1 模块职责（`apps/setting`）

为租户管理员提供配置台
为业务模块提供统一读取入口
负责写后缓存失效与审计记录

3.2 外部依赖

依赖模块	依赖内容
`apps/property`	读取房源来源与字段规则
`apps/client`	读取客源来源、跟进目的、查重规则
`apps/permission`	控制设置台与配置变更权限
`core/cache.py`	缓存键封装与失效工具

3.3 分层约束

业务模块禁止直查 setting 表
统一通过 TenantSettingsService 读取
设置写入后必须同步清理对应缓存键

四、API 设计原则

固定枚举与可配置枚举分层管理。
设置写入后下一次请求立即可见（主动失效）。
所有配置接口默认管理员权限保护。
批量规则写入以原子事务提交。
API 与 HTMX 响应都遵循统一错误码语义。

五、端点清单（核心）

5.1 页面路由（SSR）

路径	方法	权限 code	说明
`/setting/`	GET	`setting.console.view.allow`	设置首页
`/setting/lookup/`	GET	`setting.lookup.view.allow`	枚举配置页
`/setting/property-field-rules/`	GET	`setting.property_rules.view.allow`	房源规则页
`/setting/client-rules/`	GET	`setting.client_rules.view.allow`	客源规则页

5.2 HTMX 片段端点

路径	方法	用途	返回
`/setting/fragments/lookup-groups/`	GET	分组列表局刷	HTML 片段
`/setting/fragments/lookup-items/{group_id}/`	GET	选项列表局刷	HTML 片段
`/setting/fragments/property-field-rule-matrix/`	GET	规则矩阵局刷	HTML 片段
`/setting/fragments/client-rule-form/`	GET	客源规则表单局刷	HTML 片段

5.3 JSON API（MVP）

端点	方法	权限 code	说明
`/api/setting/lookup/groups/`	GET	`setting.lookup.view.allow`	获取分组
`/api/setting/lookup/items/query/`	POST	`setting.lookup.view.allow`	查询选项
`/api/setting/lookup/items/`	POST	`setting.lookup.edit.allow`	新增选项
`/api/setting/lookup/items/{id}/`	PATCH	`setting.lookup.edit.allow`	编辑选项
`/api/setting/lookup/items/{id}/deactivate/`	POST	`setting.lookup.edit.allow`	停用选项
`/api/setting/lookup/items/reorder/`	POST	`setting.lookup.edit.allow`	批量排序
`/api/setting/property-field-rules/query/`	POST	`setting.property_rules.view.allow`	查询规则矩阵
`/api/setting/property-field-rules/batch-upsert/`	POST	`setting.property_rules.edit.allow`	保存房源规则
`/api/setting/client-rules/get/`	GET	`setting.client_rules.view.allow`	获取客源规则
`/api/setting/client-rules/update/`	POST	`setting.client_rules.edit.allow`	更新客源规则
`/api/setting/snapshot/`	GET	已登录	业务录入统一快照入口

六、关键 API 规范（请求/响应）

6.1 新增可配置枚举选项

POST /api/setting/lookup/items/

{
  "module": "client",
  "key": "source",
  "value": "douyin",
  "label_zh": "抖音",
  "sort_order": 99
}

校验：

同组 value 不可重复
value 限定 lowercase + _

6.2 批量保存房源字段规则

POST /api/setting/property-field-rules/batch-upsert/

{
  "module": "property",
  "entity_type": "residential",
  "trade_status": "sale",
  "rules": [
    {"field_key": "orientation", "requirement": "required"},
    {"field_key": "parking_count", "requirement": "hidden"}
  ]
}

七、HTMX 交互约定

7.1 Header 约定

请求头：HX-Request: true
成功触发：HX-Trigger toast(success)
失败触发：HX-Trigger toast(error)

7.2 模板分片命名

templates/setting/fragments/lookup_groups.html
templates/setting/fragments/lookup_items_table.html
templates/setting/fragments/property_rule_matrix.html
templates/setting/fragments/client_rule_form.html

八、权限与数据范围

8.1 最小权限矩阵

能力	权限 code
设置台查看	`setting.console.view.allow`
可配置枚举查看/编辑	`setting.lookup.view.allow` / `setting.lookup.edit.allow`
房源规则查看/编辑	`setting.property_rules.view.allow` / `setting.property_rules.edit.allow`
客源规则查看/编辑	`setting.client_rules.view.allow` / `setting.client_rules.edit.allow`

8.2 范围规则

设置项作用域默认为当前租户
不允许跨租户读取或写入配置

九、异步任务与缓存策略

9.1 异步任务（可选）

任务	触发时机	说明
`setting_rebuild_lookup_cache_task`	大批量导入后	后台预热常用 lookup 缓存

9.2 Redis Key 规范

Key	TTL	触发失效
`{schema}:setting:lookup:{module}.{key}`	300s	lookup 新增/编辑/停用/排序
`{schema}:setting:field_req:{module}.{entity_type}.{trade_status}`	300s	字段规则保存
`{schema}:setting:kv:{category}.{key}`	300s	tenant_settings 更新
`{schema}:setting:client_rules`	300s	client rules 更新

十、性能与可靠性约束

设置读取接口目标：p95 < 150ms（命中缓存）
批量规则写入目标：p95 < 500ms（中等规模）
缓存失效失败需上报 Sentry，不回滚已提交事务
读路径在缓存不可用时可退化到 DB 查询

十一、安全与合规

配置写接口仅管理员可用。
每次写操作记录审计：操作者、配置域、前后值、IP、时间。
系统预置项（is_system=true）不可删除，可停用。
历史业务数据不得因枚举停用被破坏。

十二、错误码建议

code	HTTP	场景
`SETTING_LOOKUP_GROUP_NOT_FOUND`	404	分组不存在
`SETTING_LOOKUP_VALUE_DUPLICATED`	409	选项 value 冲突
`SETTING_LOOKUP_SYSTEM_ITEM_DELETE_FORBIDDEN`	403	尝试删除系统预置项
`SETTING_RULE_INVALID_REQUIREMENT`	400	规则值非法
`SETTING_PERMISSION_DENIED`	403	权限不足

十三、测试映射（P0）

子场景	最低覆盖
001-A 参数配置	分组加载、增改停用、排序、生效验证
001-B 房源字段规则	查询矩阵、批量保存、录入页规则生效
001-C 客源规则	查重范围更新、必填更新、录入页生效
缓存一致性	写入后缓存失效，下一次读取为最新值

测试文件：tests/integration/setting/test_us_setting.py

十四、落地顺序建议

先实现 TenantSettingsService 与失效框架
再做 lookup items（001-A）
再做 property field rules（001-B）
最后做 client rules（001-C）与业务接线

十五、文档同步规则

新增/调整可配置枚举域：同步 DATA_MODEL/ENUMS.md
新增 setting key：同步 DATA_MODEL_SETTING.md
API 变更：同步本文件与系统配置 PRD

8.5 KiB Raw Blame History Unescape Escape