feat: deps越权防护(query/header与token不一致403) + resolve_entity_for_request + 任务⑥开发规范沉淀

2026-08-11 11:30:08 +08:00
parent b59de7c476
commit d56ba24f31
2 changed files with 117 additions and 0 deletions
@@ -0,0 +1,96 @@
+# CMA 账套模式开发规范（2026-08-11 定稿）
+
+> 依据：研学Bot《cma-account-mode-research-20260811.md》+ 全栈Bot落地改造。
+> 适用范围：cma-management 仓库全部后端/前端开发。
+
+---
+
+## 1. 铁律：新表必须带 entity_id
+
+**任何新增业务数据表（租户表）必须包含 `entity_id` 列**，用于账套隔离。
+
+```python
+class 新模型(Base):
+    __tablename__ = "xxx"
+    id = Column(Integer, primary_key=True, index=True)
+    entity_id = Column(Integer, ForeignKey("entities.id"), nullable=False, index=True, comment="企业ID（账套）")
+    # ... 业务字段
+```
+
+### 1.1 全局表 vs 租户表归类
+
+| 类型 | 说明 | 示例 | entity_id |
+|------|------|------|:---:|
+| **全局表** | 系统级、跨账套共享 | users / entities / user_entities / role_permissions / system_configs / notification_channels / kpi_templates / okr_templates / bi_report_templates | ❌ 不带 |
+| **租户表** | 业务数据、按账套隔离 | kpi_definitions / kpi_values / alerts / data_source_config / objectives / action_plans / org_nodes / budget_plans / cost_* / bsc_layer_config / kpi_hierarchy / cash_* / mpm_results / bi_reports / kpi_causality / report_history | ✅ **必须带** |
+
+**判断口诀**：数据属于"某个企业/账套" → 租户表带 entity_id；数据属于"系统/平台" → 全局表。
+
+### 1.2 新表检查清单
+
+- [ ] 建表 SQL / ORM 模型包含 `entity_id`（`nullable=False` + index）
+- [ ] 查询接口默认按 entity_id 过滤（通过 `Depends(get_entity_id)` 或显式参数）
+- [ ] 写入接口强制使用当前 token 绑定的 entity_id（禁止客户端传入）
+- [ ] 存量表缺 entity_id 的，补列并回填默认值后设为 NOT NULL
+
+---
+
+## 2. 账套解析规则（后端）
+
+```text
+get_entity_id 解析链（backend/app/deps.py）：
+  1. 有 Bearer token（登录用户）→ 强制使用 token 绑定的 entity_id（忽略 query/header/body，防越权）
+  2. 无 token（Bot服务通道白名单）→ query → header → body，校验 entity 状态 = active
+  3. 兜底默认 1（酣客）
+```
+
+### 2.1 API 开发约定
+
+- **业务 API**：一律使用 `entity_id: int = Depends(get_entity_id)` 获取当前账套，禁止自己解析 query 参数
+- **禁止**在业务 API 里让客户端传 `entity_id` 来指定账套（token 绑定才是唯一来源）
+- 需要"某账套数据"的 Bot/服务通道：无 token 时通过 query/header 传 entity_id，后端校验 `Entity.status == "active"`
+
+### 2.2 用户授权
+
+- 用户可访问哪些账套 = `user_entities` 表（user_id ↔ entity_id 多对多）
+- 登录/切换时必须校验 `user_has_entity(db, user_id, entity_id)`，未授权返回 **403**
+- 新用户注册默认授权 entity_id=1（酣客）
+
+---
+
+## 3. 账套切换（前端）
+
+- 切换走 `POST /api/cma/auth/switch-entity` → 后端校验授权 → **重新签发 token**（绑定新 entity）→ 整页刷新
+- **禁止**直接改 `localStorage['cma_entity_id']` 切换（token 未变会导致数据错乱）
+- 拦截器**不自动附加** `X-Entity-Id` / `entity_id`（账套由 token 绑定，删除自动附加逻辑）
+- 登录页公司下拉数据源：`GET /api/cma/auth/login-entities?username=xxx`（按授权过滤）
+
+---
+
+## 4. 安全红线
+
+1. 任何请求携带的 `entity_id` 与 token 绑定不一致时，**以 token 为准**（忽略 query/header）
+2. 未授权账套访问返回 403（登录、切换、业务 API 三层都校验）
+3. Redis token 存储结构 = `JSON {user_id, entity_id}`；旧 int 格式 token 一律视为无效（强制重新登录）
+4. Bot 通道（X-BOT-KEY）不走用户 token，靠 query/header 指定账套时仍须校验 entity active
+
+---
+
+## 5. 验证要点（每次改动后）
+
+```bash
+# 1. 隔离验证：登录账套A → 全系统只显示A的数据
+curl -s -X POST http://127.0.0.1:8010/api/cma/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123","entity_id":2}'
+# → token；用该token访问 /api/cma/kpis 只返回博海数据
+
+# 2. 越权验证：未授权entity请求返回403
+curl -s -X POST http://127.0.0.1:8010/api/cma/auth/switch-entity \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"entity_id":999}'   # → 403
+
+# 3. Bot通道：无token带query entity_id 仍可用
+curl -s -H "X-BOT-KEY: cma-bot-finance-2026" \
+  "http://127.0.0.1:8010/api/cma/bot/overview"   # → 200
+```