leaudit-platform-backend/docs/权限与地区隔离/冻结版进度盘点与最小冒烟验收-2026-05-21.md

# 冻结版进度盘点与最小冒烟验收（2026-05-21）

> 目的：先冻结当前大改状态，不再继续无边界扩散修改；先回答“现在到底做到哪里、哪些真的通了、哪些还没验证”。

---

## 1. 本次冻结结论

当前仓库已经进入“**大范围改动已发生，但只完成部分真实验收**”的阶段。

### 2026-05-21 第二次补充结论（Pytest 黑盒验收）

在首次人工独立重放之后，已经补上 `pytest` 黑盒验收基座，并对正在运行的本地后端执行了可重复的发布验收。

本次新增确认：

1. `tests/release/` 已落地，可直接对运行中的后端执行黑盒验收
2. `G1-G3` 已通过 `pytest` 重复执行验证，不再只依赖手工 `curl`
3. 已补基础“不同租户 + 不同角色”矩阵验证
4. 验收过程中暴露并修复了一个真实后端缺陷：`租户 alias 更新幂等性`
5. `G4` 文档、`G5` RAG、`G6` 规则/交叉评查 首轮租户边界矩阵已补进黑盒验收

可以明确确认的结论：

1. 租户底座、入口模块租户化、RBAC 用户租户设置、RAG 读链路、评查组只读链路，**都已经有真实运行证据**
2. `000` 账号当前可正常登录，且登录后用户上下文已带 `tenant_code=MZ`
3. 首页入口、租户选项、入口模块后台、RAG 读接口、评查组 `/all`、规则集列表，**本次已独立重放成功**
4. 当前发布级黑盒验收总数已达到 **16 passed**
5. 现在不适合继续盲目扩散修改，应该先按“已验证通过 / 当前真实行为 / 未验证”控盘

---

## 2. 冻结时点现状

### 2.1 服务状态

`bash ./leaudit.sh status` 结果：

1. 后端运行中，端口 `8096`
2. 前端运行中，访问端口 `5173`
3. Worker 运行中
4. Beat 运行中

### 2.2 文档状态

`docs/权限与地区隔离/` 已经形成较完整文档体系，已不是“缺方案”，而是“**缺收口、缺验收、缺最终清理**”。

### 2.3 代码库状态

冻结时点 `git status --short` 统计：

1. 总变更数：`109`
2. 已跟踪修改：`59`
3. 未跟踪文件：`50`

这意味着：

1. 这轮改造面已经足够大
2. 继续一口气推进所有剩余项，风险会继续上升
3. 后续应以“单模块、单链路、可回看”方式继续

---

## 3. 本次最小冒烟验收

## 3.1 验收方式

本次不只看历史日志，还做了**独立重放**：

1. 直接 `POST http://127.0.0.1:8096/api/auth/login`
2. 使用登录返回的 `Bearer token`
3. 逐个调用关键只读接口

本次使用的真实测试口径：

1. 用户名：`000`
2. 密码：`admin06111`

独立登录返回的关键事实：

1. `user_id=5`
2. `username=admin`
3. `area=梅州`
4. `tenant_code=MZ`
5. `tenant_name=梅州`
6. `tenant_type=LOCAL`
7. `user_role=provincial_admin`

---

## 4. 已验证通过

以下接口为**本次独立重放通过**，非仅历史日志推断：

| 链路 | 接口 | 结果 | 关键观察 |
| --- | --- | --- | --- |
| 登录 | `POST /api/auth/login` | 通过 | `000 / admin06111` 可登录，返回 JWT |
| 当前用户 | `GET /api/auth/me` | 通过 | 返回 `tenant_code=MZ` |
| 首页入口 | `GET /api/home/entry-modules` | 通过 | 返回入口列表，仍带兼容 `areas` 与新 `tenants` |
| 租户选项 | `GET /api/v3/tenants/options?feature_key=home.entry_module` | 通过 | 返回 `MZ/YF/JY/CZ/PROVINCIAL/...` |
| 入口模块后台 | `GET /api/v3/entry-modules?page=1&page_size=10` | 通过 | 列表正常返回，主输出已是 `tenants` |
| RAG 应用列表 | `GET /api/v3/rag/apps` | 通过 | 返回默认应用 |
| RAG 默认应用 | `GET /api/v3/rag/apps/default` | 通过 | 返回默认应用 |
| RAG 会话列表 | `GET /api/v3/rag/chat/conversations?page=1&pageSize=20&appId=1` | 通过 | 返回真实会话数据 |
| 评查组树 | `GET /api/v3/evaluation-point-groups/all` | 通过 | 返回真实分组树 |
| 规则集列表 | `GET /api/rule-sets` | 通过 | 返回规则集数据 |

### 4.1 已通过的 Pytest 验收

本次新增可重复执行测试：

1. `tests/release/test_g1_rbac_context.py`
2. `tests/release/test_g2_g3_tenant_entry_chain.py`
3. `tests/release/test_role_tenant_matrix.py`
4. `tests/release/test_g4_documents.py`
5. `tests/release/test_g5_rag.py`
6. `tests/release/test_g5_rule_cross_review_matrix.py`

执行结果：

1. `G1-G3`：通过
2. 角色/租户矩阵基础用例：通过
3. `G4` 文档跨租户读写边界：通过
4. `G5` RAG 可见性与管理边界：按当前真实权限模型通过
5. `G6` 规则/评查组只读矩阵与交叉评查建单边界：通过
6. 当前已固化的发布级黑盒验收总数：`16 passed`

当前已被 `pytest` 固化的核心断言：

1. 管理员登录、`/api/auth/me`、路由树、用户列表、组织树、租户选项可正常读取
2. 测试租户可重复创建/更新/启用，用户租户切换后重新登录可读到正确 `tenant_code`
3. 入口模块租户分配会真实影响不同租户首页入口可见性
4. 全局管理员可跨租户查询
5. 租户管理员只能查询/修改本租户范围
6. 普通用户不能访问系统设置管理接口，但仍能看到本租户业务入口
7. 文档上传、列表、详情、更新、附件追加、删除已验证租户边界
8. RAG 私有应用和公共应用已验证跨租户可见性差异
9. 交叉评查建单已验证“文档/成员不得混租户”

### 4.2 本轮补齐的真实权限语义

这轮 `pytest` 还确认了几个重要现实，不应在评审时误判：

1. `RAG` 当前不是“租户管理员即可管理知识库”的模型
2. 当前环境里，`/api/v3/rag/datasets/admin*` 仍属于全局管理员管理域
3. 租户管理员可以读取本租户数据集详情，但不能创建或修改数据集
4. 规则集元数据当前是全局可读资产，不等于规则绑定和评查组树也是全局可写
5. 交叉评查当前被实现为“单任务单租户”模型，而不是允许跨租户混编的协作模型

---

## 5. 仅有历史运行证据，但本次未独立重放

以下链路在 `/.codex-run/backend.log` 中看到过成功记录，但本次没有再单独做完整回放：

1. `GET /api/rbac/user/routes`
2. `GET /api/v3/rag/chat/conversations/{conversationId}/messages`
3. `GET /api/documents/list?page=1&pageSize=10&entry_module_id=1`
4. `GET /api/document-types?page=1&pageSize=200&entry_module_id=1`
5. 前端 `/api/auth/session-data` 联动首页入口展示

这些链路当前可判定为：

1. **有成功证据**
2. 但本次冻结验收里不算“独立重放通过”

---

## 6. 尚未验证

以下范围本次**明确不算通过**：

### 6.1 租户管理写链路

1. `POST /api/v3/tenants`
2. `PUT /api/v3/tenants/{tenantCode}`
3. `PATCH /api/v3/tenants/{tenantCode}/status`
4. 前端租户管理页完整交互

### 6.2 RBAC 写链路

1. `PUT /api/v3/rbac/users/{UserId}/tenant`
2. 用户角色分配/撤销
3. 组织树跨租户边界行为

### 6.3 入口模块写链路

1. 新建入口模块
2. 编辑入口模块
3. 上传入口模块图标
4. 新租户分配到入口模块后的前后端联动

### 6.4 文档/公文/合同模板写链路

以下仅文档主链路已纳入通过，其余仍未验证：

1. 文档上传
2. 文档列表
3. 文档详情
4. 文档更新
5. 附件追加新版本
6. 文档删除
7. 合同模板上传
8. 内部公文上传与运行

### 6.5 RAG 写链路

以下仍未验证，当前 `G5` 只覆盖到可见性、详情读取与管理边界：

1. 会话重命名
2. 会话删除
3. 消息反馈
4. StopMessage
5. 数据集文档上传、重处理、删除
6. 真实聊天消息写入链路

### 6.6 新平台主链路深水区

1. 入口模块 -> 一级业务大类 -> 二级业务子类型 -> 规则集 -> 规则版本 -> 文档评查结果 的完整端到端
2. 交叉评查补传、提案、投票、归档深链路
3. 统计聚合按 `tenant_code` 的最终正确性

---

## 7. 本次暴露出的残余风险

## 7.1 高风险

1. **仍有大量链路未做写入验证**
   现在能证明“读链路部分恢复”，不能证明“写入不落错租户”

2. **当前仓库处于超大脏工作区状态**
   总计 `109` 条变更，后续定位回归会很痛苦

## 7.2 中风险

1. **兼容层仍较重**
   例如首页入口接口仍同时返回 `areas` 和 `tenants`

2. **首页入口可见性仍依赖“租户命中 + 路由树命中”双条件**
   这次 `pytest` 首轮失败就暴露了这一点。当前不是 bug，但这意味着后续验收必须同时覆盖：
   - 入口模块租户分配
   - 目标路由是否在当前角色路由树中可见

3. **RAG 读接口仍可见兼容态数据**
   `GET /api/v3/rag/apps` 返回中默认应用仍显示：
   - `tenantCode=""`
   - `tenantName="未分配地区"`

   这说明 RAG 模块虽然已能读，但还没有完全完成租户主语义收口

4. **评查组/规则集链路只验证到只读**
   尚未验证创建、绑定、发布、回滚等敏感操作

5. **部分写接口的“可重复执行”幂等性仍不稳**
   本次已确认并修复一处：
   - `PUT /api/v3/tenants/{tenantCode}` 在 alias 软删重建模式下会触发唯一键冲突
   这说明其他“软删 + 唯一键”写链路还需要继续专项排查

## 7.3 低风险

1. 后端日志出现了 SQLAlchemy `NullPool` 连接清理 `SAWarning`
2. 当前未导致接口失败，但说明某些会话生命周期可能还不够干净

---

## 8. 现在可以下的控制性判断

### 可以确认已经恢复/打通的

1. `000` 登录
2. 用户租户上下文读取
3. 首页入口读取
4. 租户选项读取
5. 入口模块后台列表读取
6. 文档上传/列表/详情/更新/附件/删除边界
7. RAG 应用与会话只读、数据集详情读取边界
8. 评查组只读
9. 规则集只读
10. 交叉评查建单租户一致性拦截

### 还不能宣称完成的

1. 全项目租户化完成
2. 所有 `area/region/default` 残留已清完
3. 所有写链路都不会落错租户
4. 前后端完整体验已验收
5. 新平台主链路端到端已收口

---

## 9. 冻结后建议动作

冻结后不要再按“大计划一口气推进”，而应改成下面顺序：

1. 先把当前 `已验证通过 / 未验证 / 明确待修` 固化
2. 下一轮只选 **1 个模块 + 1 条写链路** 做闭环
3. 每做完一条写链路，就立刻补最小回归验证

建议下一优先级：

1. `入口模块写链路` 验证
2. `租户管理写链路` 验证
3. `RBAC 用户租户设置` 再次独立重放
4. `文档上传 -> 文档列表 -> 详情` 单租户闭环

---

## 10. 本次冻结版一句话结论

当前系统已经从“完全不可控的大改中”回到“**部分关键只读链路已真实恢复，但大量写链路和端到端链路仍未验收**”的状态；现在最重要的不是继续铺修改面，而是按模块逐条做小闭环验收。

---

## 11. 追加进展（当日第二轮发布验收）

在冻结后继续按 `G1-G3` 做了发布前闭环验收，新增确认如下：

1. `G1` 已通过
   - 登录、`/api/auth/me`、`/api/v3/rbac/users`、`/api/rbac/user/routes`、`/api/admin/users/organizations/tree` 已实测通过
2. `G2` 已通过
   - 已真实创建测试租户 `ZZRC1`
   - 已真实更新租户
   - 已真实启停租户
   - 已真实把 `000` 用户切到 `ZZRC1`
   - 重新登录后 `/api/auth/me` 已返回 `tenant_code=ZZRC1`
3. `G3` 已通过
   - `000` 切到新租户后首页初始无入口，符合边界预期
   - 将模块 `2` 分配给 `ZZRC1` 后，首页立即能看到入口
   - `租户主数据 -> 用户租户 -> 入口模块租户分配 -> 首页展示` 已真实打通

本轮唯一实际代码修复点：

1. [tenantServiceImpl.py](/home/wren-dev/Porject/leaudit-platform/fastapi_modules/fastapi_leaudit/services/impl/tenantServiceImpl.py)
   - 修复 `PUT /api/v3/tenants/{tenantCode}` 时 `sys_tenant_feature_flags` 因软删重插撞唯一约束导致的 `500`

---

## 12. 当日第三轮补充（G4-G6 黑盒扩展复核）

已再次执行：

```bash
.venv/bin/python -m pytest tests/release -m release -q
```

结果：

1. `16 passed in 20.36s`

这次复核说明：

1. `G4` 文档跨租户读写边界已稳定可重复
2. `G5` RAG 当前真实权限模型已稳定可重复
3. `G6` 规则/评查组只读矩阵与交叉评查建单边界已稳定可重复
4. 当前冻结版文档与实际测试结果一致