chore: sync local project changes

2026-04-27 16:26:07 +08:00
parent dfcf7de003
commit 5854781fa8
144 changed files with 12849 additions and 12330 deletions
--- a/Project/fonrey/TECH_STACK/系统设置技术方案.md
+++ b/Project/fonrey/TECH_STACK/系统设置技术方案.md
@@ -0,0 +1,265 @@
+> **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）  
+**关联枚举字典**: `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/`
+
+```json
+{
+  "module": "client",
+  "key": "source",
+  "value": "douyin",
+  "label_zh": "抖音",
+  "sort_order": 99
+}
+```
+
+校验：
+- 同组 `value` 不可重复
+- `value` 限定 lowercase + `_`
+
+## 6.2 批量保存房源字段规则
+
+`POST /api/setting/property-field-rules/batch-upsert/`
+
+```json
+{
+  "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