nexus/Project/fonrey/TECH_STACK/系统设置技术方案.md

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

---

一、文档定位与边界

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

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

不在本文件展开 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 设计原则

1. 固定枚举与可配置枚举分层管理。
2. 设置写入后下一次请求立即可见（主动失效）。
3. 所有配置接口默认管理员权限保护。
4. 批量规则写入以原子事务提交。
5. 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 查询

---

十一、安全与合规

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

---

十二、错误码建议

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

---

十四、落地顺序建议

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

---

十五、文档同步规则

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