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
   • 修复 PUT /api/v3/tenants/{tenantCode} 时 sys_tenant_feature_flags 因软删重插撞唯一约束导致的 500

---

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

已再次执行：

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

结果：

1. 16 passed in 20.36s

这次复核说明：

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