TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
leaudit-platform-backend/docs/权限与地区隔离/模块级开发任务单.md
T

26 KiB
Raw Permalink Blame History

模块级开发任务单

适用范围：leaudit-platform 权限、地区、租户、多租户入口模块改造执行阶段
更新日期：2026-05-21
文档定位：把当前改造拆成可逐项推进的模块级开发任务单，便于研发、联调、验收逐条跟进。

1. 使用方式

本文档只做执行，不重复讲大方案。

每个模块统一拆成五栏：

  1. 数据库变更
  2. 后端改造
  3. 前端改造
  4. 验收点
  5. 风险

状态建议：

  • 未开始
  • 进行中
  • 待联调
  • 已完成

2. 推荐执行顺序

建议按下面顺序推进：

  1. T8 首页入口 + 入口模块后台收口
  2. T9 租户主数据维护能力
  3. T2 文档模块
  4. T3 内部公文模块
  5. T6 合同模板模块
  6. T7 系统使用统计模块
  7. T4 RAG 知识库模块
  8. T5 评查点模块
  9. T11 规则域多租户方案 A 落地
  10. T1 RBAC 管理域全量 scope 收口
  11. T10 前端去角色化收口

3. 模块任务单

3.1 T1 RBAC 管理域

当前状态：已完成首轮联调，待全量收口

涉及文件：

栏位 任务
数据库变更 1. 明确 sso_users.tenant_code 作为用户主归属租户字段。 2. 如现有用户管理结果必须展示租户名，确保 tenant_code -> tenant_name 可稳定关联。 3. 如后续组织树要租户化，评估是否新增“租户组织映射”或直接用租户主数据树。
后端改造 1. 用户列表、用户树、按地区筛选逻辑从 u.area 迁到 tenant_code。 2. 保留 area 仅做兼容展示，不再作为管理边界主条件。 3. 补用户租户设置/修改接口。 4. 管理员查询范围统一为“当前用户可管理租户集合”。
前端改造 1. 用户管理页新增标准租户选择器。 2. 地区筛选改为租户筛选。 3. 用户详情、编辑弹窗展示 tenant_code + tenant_name。 4. 组织树若仍展示地区名，需明确它是租户展示名。
验收点 1. 000 用户可被稳定设置租户。 2. 设置后重新登录 /auth/me 返回正确 tenant_code。 3. 不同租户管理员看不到其他租户用户。 4. 省级/超级管理员可按租户查看所有用户。 5. 已完成 PUT /api/v3/rbac/users/{UserId}/tenant 与前端弹窗的真实联调。
风险 1. 这是全局入口模块，改错会影响登录后所有租户边界。 2. 历史 area 和 tenant_name 不一致时，容易出现列表对了、详情错了。

3.2 T2 文档模块

当前状态：首轮 tenant-first 收口已完成，仍处于过渡态

涉及文件：

栏位 任务
数据库变更 1. 为文档主表补 tenant_code。 2. 为文档附件/版本链相关查询建立 tenant_code 联动索引。 3. 历史 region -> tenant_code 回填。 4. 保留 region 作为兼容展示字段。
后端改造 1. 上传、列表、详情、状态、确认、附件、删除统一按 tenant_code 过滤。 2. _resolve_document_region 一类方法逐步退化为兼容层。 3. 版本链、重复上传判重、路径归属判断不再只依赖 region。 4. 接入统一 DocumentPolicy。
前端改造 1. 上传页、列表筛选、详情页统一传 tenant_code。 2. 地区筛选改成租户筛选。 3. 展示仍可显示中文名，但请求层不能只传中文地区。
验收点 1. 同名文档在不同租户下互不冲突。 2. 用户只能看到自己租户和授权范围内文档。 3. 不可见文档的详情、状态、附件接口也必须拒绝。 4. 历史文档不丢失、旧数据可查。
风险 1. 文档是主数据域，改动会联动统计、评查、公文、交叉评查。 2. 若只改列表不改详情/附件，会形成新的越权口子。

3.3 T3 内部公文模块

当前状态：T5-1 读链路收口已完成，T5-2 待开始

涉及文件：

栏位 任务
数据库变更 1. 公文文档链路补 tenant_code。 2. 历史 region 数据回填到 tenant_code。 3. 为版本链查询增加租户索引。
后端改造 1. 上传、列表、详情、运行、结果查询统一按 tenant_code。 2. _resolve_upload_region 和版本查重逻辑切换为租户编码优先。 3. OSS 路径生成保留展示地区，但归属判断改成 tenant_code。
前端改造 1. 上传页和列表筛选统一使用租户选择器。 2. 老 region 参数只做兼容透传，页面主模型改为 tenant_code。
验收点 1. 不同租户同名公文互不串版本。 2. 非本租户用户无法查看或触发运行。 3. 历史公文可正常展示原地区中文名。
风险 1. 版本链归属如果处理不干净，最容易串数据。 2. OSS/报告路径如果强依赖旧地区名，迁移时要防回归。

3.4 T4 RAG 知识库模块

当前状态：进行中

涉及文件：

栏位 任务
数据库变更 1. 如 rag_dataset 仍只存 area，补 tenant_code。 2. 历史 area 回填标准租户编码。 3. 若默认应用与数据集绑定依赖地区，需同步补租户归属字段。
后端改造 1. 删除 service 中 provincial_admin/admin/super_admin 角色白名单。 2. 改为 permission + tenant scope 判定。 3. 数据集列表、创建、更新、删除、文档上传、检索测试统一按 tenant_code。 4. 公共知识库策略单独抽成标准规则。
前端改造 1. area-dataset 命名逐步迁到 tenant-dataset。 2. 页面按钮显示改为按能力/权限，不按角色名。 3. 数据集管理页统一使用租户选择器。
验收点 1. 自定义角色只要有权限即可管理知识库。 2. 仅有 admin 角色名但无权限时必须拒绝。 3. 公共知识库、本租户知识库、省级知识库展示边界正确。
风险 1. 这是角色硬编码最集中的模块。 2. 前后端若只改一侧，会出现按钮能点但接口 403，或接口能过但前端不显示。

3.5 T5 评查点模块

当前状态：进行中

涉及文件：

栏位 任务
数据库变更 1. 为评查点表补 tenant_code。 2. 视旧库现状同步补 tenant_name 展示字段。 3. 历史 ep.area 回填标准租户编码。 4. 公共/省级类记录补固定租户编码，不再只存中文常量。 5. 已新增数据库草案：schema_evaluation_points_tenant_cleanup.sql。
后端改造 1. 首轮已完成：列表、详情、创建、更新已切为 tenant_code 优先，旧 area 仅在老表无字段时回退。 2. T5-1 已完成：列表读链路已拆分“当前用户租户上下文”和“显式筛选租户条件”，避免查询参数反向污染当前用户 scope。 3. T5-1 已完成：无效的 visible_areas SQL 绑定残留已清理。 4. T5-2 已完成第一轮：创建/更新写链路不再允许原始 area 文本直接作为归属主语义，统一从解析后的 writable_scope 推导 area/tenant_code/tenant_name。 5. T5-2 已完成第一轮：PUBLIC/PROVINCIAL 与 公共/省级/default 共享域写入已统一归一化到标准租户编码。 6. T5-3 已完成第一轮：列表/详情筛选默认优先按标准 tenant_code 命中共享域，旧 公共/default/空值/省局/省级 只作为无 tenant_code 老数据的受控 fallback。 7. T5-4 已完成第一轮：评查点模块主链路的 is_global/can_manage 不再直接依赖 super_admin/provincial_admin/admin 角色名，改为 roles.data_scope + evaluation_point:* 权限推断。 8. T5-5 已完成第一轮：查不到数据库用户上下文时，已移除 payload.user_role 角色名兜底；fallback 仅保留租户解析和权限服务判定，默认不再推断全局范围。 9. 全局用户写非公共评查点时，已要求必须显式提供标准 tenant_code；未指定租户/共享域时直接拒绝，避免静默落错域。 10. 模块内统一 policy 与最终 area 物理兼容层仍未收口。
前端改造 1. 筛选条件改为租户。 2. 创建/编辑表单改为租户选择，不再直接填地区文本。 3. 详情页展示租户中文名。
验收点 1. 已完成首轮验证目标：本租户用户只会看到并维护本租户评查点，公共/省级保持兼容共享。 2. 全局用户若创建非公共评查点，缺失 tenant_code 或完全未指定归属范围时会被明确拒绝。 3. 更新接口即便收到原始 area 文本，也不会再把它直接当成最终归属写入。 4. 列表和详情读取共享域时，已优先按 PUBLIC/PROVINCIAL 命中；老数据仅在缺标准字段时才回退旧名称集合。 5. 自定义新租户若数据库已补字段，可正常创建和筛选评查点。
风险 1. 当前模块物理表仍是 area 主模型，最容易误判“接口 tenant 化 = 数据已 tenant 化”。 2. 共享域中文常量仍未完全收口。 3. 若数据库未执行补字段脚本，仍只能停留在兼容态。 4. 收尾顺序、验收项与下线边界已另行整理到 评查点模块收尾清单.md。

3.6 T6 合同模板模块

当前状态：高风险收口进行中

涉及文件：

栏位 任务
数据库变更 1. 为合同模板主表补 tenant_code。 2. 补 tenant_name 展示字段。 3. 历史 region 回填标准租户编码。 4. 如分类有租户隔离要求，评估分类表是否补租户字段。
后端改造 1. 删除结果中伪造的空 tenant_code。 2. 列表、搜索、详情、上传统一按 tenant_code 过滤。 3. 上传写入真实 tenant_code/tenant_name。 4. region 降级为兼容展示字段。 5. 去重规则从 region + template_code 迁到 tenant_code + template_code，旧数据保留 region fallback。
前端改造 1. 搜索筛选和上传表单改为租户选择器。 2. 页面展示 tenant_name，请求传 tenant_code。
验收点 1. 不同租户模板互相不可见。 2. 搜索结果、分类统计、详情页边界一致。 3. 历史模板仍可按旧中文地区展示。 4. 当前已完成第一批后端收口：服务端写入 tenant_code/tenant_name，列表/详情真实返回 tenant_code。
风险 1. 当前模块最容易出现“接口看似支持租户，实际完全没有真实租户字段”。 2. 如果分类和模板边界不同步，会出现分类统计异常。 3. 在数据库正式执行高风险迁移脚本前，线上旧表仍可能缺 tenant_name 列，需要先执行迁移或依赖运行时补列。

3.7 T7 系统使用统计模块

当前状态：进行中

涉及文件：

栏位 任务
数据库变更 1. 为 usage_login_events 补 tenant_code_snapshot / tenant_name_snapshot。 2. 如其他统计事件表缺租户快照，同步补齐。 3. 为统计聚合补租户索引。
后端改造 1. 登录审计、上传审计、运行审计统一记录标准租户快照。 2. 统计聚合优先按 tenant_code，展示层再转 tenant_name。 3. 旧 area_snapshot 保留兼容，不再作为主统计维度。
前端改造 1. 统计页筛选维度改成租户。 2. 图表与导出字段展示租户中文名。
验收点 1. 登录统计、上传统计、运行统计按租户聚合结果正确。 2. 同一用户改租户后，历史事件仍保留原快照。 3. 导出与页面统计口径一致。
风险 1. 快照字段如果不补，后续历史统计无法稳定回溯。 2. 统计是衍生域，容易被主业务迁移遗漏。

3.8 T8 首页入口 + 入口模块后台收口

当前状态：已完成

涉及文件：

栏位 任务
数据库变更 1. 继续以 leaudit_entry_module_tenants 为主，不再扩散 areas。 2. 核对历史入口模块迁移结果是否完整。
后端改造 1. 读写链路统一以 tenants 关系表为主。 2. areas/default/省局 fallback 已收敛为只读兼容。 3. “无 tenant 配置” 已有明确业务语义。 4. 创建/更新时若最终租户配置为空，后端直接拒绝。 5. 首页租户过滤已去掉会放宽范围的 areas IS NULL 类 fallback。
前端改造 1. 入口模块新建/编辑页面只认租户对象。 2. 列表页支持按租户过滤。 3. 首页消费的返回结构统一优先 tenants。 4. 首页兼容层统一识别 route_path / routePath / target_path / targetPath / path。 5. 创建/更新请求只以下发 tenants 为主，不再以 areas 作为主提交流程字段。 6. 管理端编辑页已不再消费 areas。 7. 管理端 API 类型已不再把 areas 作为主返回模型。 8. 交叉评查入口前端判断已改成“有 tenants 就绝不回退 areas”。 9. 首页前端标准化时优先由 tenants 反推兼容 areas。
验收点 1. 新建入口模块可配置任意新租户。 2. 首页可按租户正确展示模块。 3. 旧模块迁移后展示不回归。 4. 已验证 000 用户首页会话接口返回 entryModules=5。 5. 已验证 /api/v3/entry-modules?tenant_code=MZ 返回正常。 6. 已验证空 tenants 创建会返回明确 400。 7. 已验证入口模块详情接口返回正常，管理端可仅凭 tenants 回显。 8. 已验证管理端列表/详情接口不再返回 areas。 9. 已验证 /api/home/entry-modules 仍正常返回 5 个入口。 10. 已验证首页交叉评查可见性未回退。
风险 1. 旧 JSON 与新关系表双写期间容易不一致。 2. 首页和后台若消费不同字段，会出现“配了但不显示”。

3.9 T9 租户主数据维护能力

当前状态：进行中

涉及文件：

栏位 任务
数据库变更 1. 复核 sys_tenants、sys_tenant_aliases、sys_tenant_feature_flags 约束是否满足新增租户场景。 2. 如需入口模块/文档/RAG能力独立控制，补全 feature flag 种子。
后端改造 1. 已新增 POST /api/v3/tenants、PUT /api/v3/tenants/{tenantCode}、PATCH /api/v3/tenants/{tenantCode}/status。 2. 已支持同步维护 sys_tenants / sys_tenant_aliases / sys_tenant_feature_flags。 3. 已补租户专属权限 rbac:tenants:* 与 /tenants 菜单蓝图。 4. 已增加“禁用前引用检查”，当前至少拦截子租户、入口模块、启用用户引用场景。
前端改造 1. 已新增 /tenants 独立租户管理页。 2. 已支持维护租户名称、编码、类型、父级、别名、能力开关、feature keys、启停状态。 3. 仍未做更复杂的租户树和删除能力。
验收点 1. 无需手改 SQL 即可新增一个新租户。 2. 新租户创建后可被入口模块、用户管理、业务表单引用。 3. 禁用租户后下拉可按配置隐藏。 4. 系统设置菜单出现“租户管理”，并可真实保存。
风险 1. 只有读接口没有写接口，会导致每次新增租户都要人工入库。 2. 不做引用检查，容易禁用已被业务广泛使用的租户。

3.10 T10 前端去角色化收口

当前状态：未完成

涉及目录：

  • legal-platform-frontend/app/(audit)/*
  • legal-platform-frontend/components/*
  • legal-platform-frontend/hooks/*
  • legal-platform-frontend/lib/api/legacy/auth/check-route-permission.ts
栏位 任务
数据库变更 无直接数据库变更。
后端改造 1. /auth/me 或能力快照接口补齐当前用户有效权限、租户能力摘要。 2. 为前端去角色化提供稳定字段。
前端改造 1. 菜单、按钮、guard 从“认角色名”迁到“认权限/能力”。 2. RAG、入口模块、RBAC 管理页优先清理角色名分支。 3. area-* 旧命名逐步迁移为 tenant-*。
验收点 1. 自定义角色只要有权限，前端就展示正确入口。 2. 只有角色名没有权限时，前端不应误显示按钮。 3. 路由 guard 与接口鉴权结果一致。
风险 1. 去角色化只改前端不改后端，会出现展示和鉴权不一致。 2. 多页面零散硬编码，容易漏改。

3.11 T11 规则域多租户方案 A 落地

当前状态：进行中

专项文档：

涉及文件：

栏位 任务
数据库变更 1. 已新增规则域迁移脚本：schema_rule_domain_tenant_phase1.sql。 2. 已新增预检脚本：precheck_rule_domain_tenant_phase1.sql。 3. 已新增验证脚本：verify_rule_domain_tenant_phase1.sql。 4. ruleGroupSupport.ensure_rule_group_schema() 已与迁移脚本对齐，补齐 leaudit_rule_group_bindings.tenant_code / scope_type / tenant_name_snapshot 与租户维度唯一索引兼容。 5. 当前仍需在新库实际执行 phase1 SQL。
后端改造 1. auditServiceImpl 已完成运行时 tenant-first 解析：TENANT -> PROVINCIAL -> PUBLIC。 2. storage_adapter 与 LeauditAuditRun 已完成运行结果快照兼容写入。 3. ruleServiceImpl 已完成读侧 tenant scope、写侧 CreateVersion / Publish / Rollback tenant scope、版本快照 tenant_code_snapshot / scope_type_snapshot / source_version_id 写入。 4. 当租户用户基于省级规则派生版本时，现已记录 source_rule_set_id / source_version_id lineage。 5. ruleConfigServiceImpl 已补 effectiveTenantCode / effectiveScopeType / isInherited / sourceRuleSetId，规则配置列表与详情都能回传来源态。 6. evaluationPointGroupServiceImpl 已完成规则组绑定写侧租户化：新增绑定按当前租户写入 tenant_code/scope_type/tenant_name_snapshot，租户用户不能直接写公共或其他租户绑定，更新/删除也已加同租户限制。 7. CreateRuleDraft 已改为直接回绑新建版本返回的 ruleSetId，避免多租户下按全局 rule_type 误绑。
前端改造 1. 后端来源态字段已就绪，可直接接前端“本租户规则 / 继承省级 / 继承公共”展示。 2. 评查组绑定页也已具备 effectiveTenantCode / effectiveScopeType / isInherited / sourceRuleSetId 数据基础。 3. 当前仍未完成规则配置页与评查组绑定页的最终 UI 联调展示。
验收点 1. 租户 A 发布规则版本，不影响租户 B。 2. 租户私有规则缺失时可继承 PROVINCIAL，再缺失时才继承 PUBLIC。 3. 规则配置页接口与评查组绑定接口都能明确返回规则来源态。 4. 租户用户不能直接修改继承态绑定或公共绑定。 5. CreateRuleDraft 自动补绑不会再绑到错误租户的规则集。
风险 1. 这是规则域主数据模型重构，不是单纯接口补条件。 2. rule_type 历史上被当成全局唯一键使用，迁移时最容易出隐藏耦合。 3. 若先改页面、不改运行链路，会造成“看起来分租户了，实际运行还串规则”的假象。

4. 跨模块公共任务

这些任务不属于单一模块，但必须同步推进：

公共任务 内容
C1 字段标准化 全项目统一语义：tenant_code 为主归属，tenant_name 为展示值，area/region 为兼容字段。
C2 历史值清洗 清理 default/省级/省局/公共/空值 等历史值，统一映射到标准租户编码。
C3 统一执行器接入 将模块级手写范围判断逐步收敛到统一 PermissionDecision + Policy + ScopeBuilder。
C4 回归矩阵落测 详情、下载、状态、导出、删除等派生接口必须和列表边界一致。
C5 文档同步 每完成一个模块，回写到 模块级真实落地清单与下一步动作.md 更新状态。

5. 当前建议的下一步开发计划

当前不再建议按“功能页面改一点、业务模块改一点”并发推进，而是按收尾风险分 3 组执行。

5.1 必须先做

  1. P0 评查点数据库收尾
    • 目标：执行 evaluation_points 的 tenant_code / tenant_name 补列、历史回填、预检 SQL 复核
    • 原因：T5 代码已首轮收口，但旧表不补字段就永远停留在兼容态
  2. P1 文档模块收尾
    • 目标：详情、附件、状态、删除、版本链统一按 tenant_code
    • 原因：文档是主数据域，后续统计、公文、交叉评查都依赖它
  3. P2 内部公文模块收尾
    • 目标：运行链、结果链、版本链、路径链统一按 tenant_code
    • 原因：这是最容易出现“参数租户化、底层仍按 region 跑”的模块
  4. P3 统计模块收尾
    • 目标：tenant_code_snapshot / tenant_name_snapshot 与聚合、导出口径统一
    • 原因：历史审计快照如果不先固化，后面会很难回溯

5.2 可以并行推进

  1. P4 RBAC policy 化
    • 目标：can_manage / is_global、组织树、角色分配改成统一权限/范围模型
  2. P5 RAG 与前端去角色化
    • 目标：移除角色名驱动，统一改为“权限 + 租户能力 + 数据范围”
  3. P6 CrossReview 剩余链路复核
    • 目标：任务详情、关系列表、后续动作统一 policy

5.3 最后清理

  1. P7 全局兼容值清理与回归
    • 目标：area / region / default / 省级 / 公共 / 省局 只保留在兼容层、历史清洗层、展示层
    • 同步完成跨模块回归矩阵验收

5.4 当前执行原则

  1. 一次只收一个主风险模块，不再大面积并发改造
  2. 先解决“落错租户、查错范围、串租户数据”，再做统一执行器与前端去角色化
  3. 每完成一个阶段，必须同步更新：

6. 建议配套阅读

  1. 权限与租户改造当前进度总览.md
  2. 模块级真实落地清单与下一步动作.md
  3. 权限改造实施任务拆解与排期.md
  4. 角色去硬编码迁移清单.md
  5. 地区到租户编码映射清洗清单.md
Reference in New Issue View Git Blame Copy Permalink