Files

T

wren 68d0b4c878 feat: update audit platform workspace

2026-05-25 09:50:01 +08:00

23 KiB

Raw Blame History

业务入口与业务类型交互优化实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 把当前“入口模块管理 + 文档类型管理 + 规则分组 + 上传”的用户理解成本降下来，让用户按“业务入口、业务大类、业务类型、规则”完成配置，而不是理解 entry_module_id/type_id/group_id。

Architecture: 不改后端核心数据模型，不自动创建业务大类或业务类型。前端做语义重构和交互包装：入口模块页只选择已有业务范围；业务类型管理页负责维护大类/类型；上传页保留两级选择但改成业务语言；规则分组页继续承接规则绑定。

Tech Stack: Next.js App Router、React、现有 Card/Button/FormSelect/Table/Toast 组件、现有 CSS 变量、FastAPI 现有入口模块/文档类型/规则分组接口、Playwright UI 验收。

一、设计结论

1.1 用户语义

统一使用下面这套用户可理解的语言：

业务入口 = 首页工作台，对应 leaudit_entry_modules
业务大类 = 上传第一步选择，对应一级分组/当前文档类型大类
业务类型 = 上传第二步选择，对应二级分组/运行子类型
规则配置 = 给业务类型绑定规则集

前端不再重点暴露这些技术词：

入口模块绑定文档类型
一级分组
二级分组
document_type_id
group_id
entry_module_id

技术词可以保留在调试信息、接口字段、开发文档里，但不能作为普通后台用户的主要操作语言。

1.2 业务边界

入口模块新建/编辑页只允许选择已有业务范围：

不能在入口模块页自动创建业务大类
不能在入口模块页自动创建业务类型
不能在入口模块页自动创建规则绑定

如果用户找不到业务类型，页面只做引导：

未找到需要的业务类型？请先到“业务类型管理”维护。

1.3 最终操作链路

1. 业务类型管理：维护业务大类和业务类型
2. 业务入口管理：创建入口，选择菜单、租户、业务范围
3. 规则配置：给业务类型绑定规则集
4. 上传页：选择业务大类、业务类型，上传文件
5. 文档列表/评查：按入口、租户、大类、类型过滤和命中规则

二、UI 风格约束

所有新增 UI 必须和当前系统保持一致：

继续使用现有 Card、Button、FormSelect、Table、Toast
继续使用现有 ant-btn / ant-btn-primary 按钮风格
继续使用绿色主色 #00684a
继续使用 var(--color-primary-text)、var(--color-primary-text-muted)、var(--color-primary-border-soft)、var(--color-primary-surface)
继续使用当前后台页面 24px 外边距、Card 容器、表格、圆角、阴影风格
继续沿用当前入口模块、文档类型、规则分组页面的表单布局

禁止：

不要引入新的 UI 框架
不要重做视觉体系
不要大面积渐变、特殊字体、花哨动效
不要把入口模块管理页做成和系统其他管理页不一致的风格
不要改变现有按钮颜色体系

三、页面信息架构调整

3.1 菜单命名

建议调整左侧菜单文案：

文档类型 -> 业务类型
入口模块 -> 业务入口
规则分组 -> 规则配置

如果担心一次改名影响用户习惯，可以第一阶段使用过渡文案：

业务类型（原文档类型）
业务入口（原入口模块）
规则配置

3.2 页面职责

业务入口管理：配置工作台、菜单、租户、业务范围
业务类型管理：维护业务大类和业务类型，不绑定规则集
规则配置：给业务类型绑定规则集
上传文档：选择业务大类和业务类型后上传

四、入口模块管理 UI 方案

4.1 列表页优化

文件：

legal-platform-frontend/app/(audit)/entry-modules/EntryModulesClient.tsx
legal-platform-frontend/styles/pages/entry-modules.css

列表页保留现有表格风格，但字段改成业务可读：

入口名称
工作台类型
适用租户
业务范围
功能菜单
状态
操作

业务范围列显示摘要：

合同 3 个类型 / 公文 2 个类型

如果接口暂时没有业务范围摘要，第一阶段先显示：

已配置业务范围
未配置业务范围

操作按钮：

编辑入口
配置业务范围
预览入口
删除/停用

权限仍走现有 RBAC：

entry_module:list:read
entry_module:create:write
entry_module:update:write
entry_module:delete:delete
entry_module:image:write

4.2 新建/编辑页改成 4 步向导

文件：

legal-platform-frontend/app/(audit)/entry-modules/new/EntryModuleNewClient.tsx
legal-platform-frontend/styles/pages/entry-modules.css

页面顶部增加步骤条：

1 基础信息 -> 2 功能菜单 -> 3 适用租户 -> 4 业务范围

步骤条只控制页面分区滚动/显示，不做复杂路由拆分。保存仍然是一个表单整体提交。

Step 1 基础信息

字段：

入口名称
入口描述
Logo
跳转入口

跳转入口不要直接展示裸路径作为主选项，改成业务文案：

通用文档评查（/documents）
内部公文评查（/govdoc/audits）
交叉评查（/cross-checking）

保存时仍提交原 route_path。

Step 2 功能菜单

把菜单模板做成当前系统风格的轻量卡片：

通用文档评查
合同工作台
公文工作台
交叉评查
自定义工作台

选中模板后自动带出默认功能。

功能勾选默认折叠为“高级功能设置”，避免用户一进来看到一大堆 checkbox。

高级区域展开后显示现有功能勾选：

首页
文件上传
文档列表
规则管理
规则分组
模板搜索
模板列表
公文列表
公文上传
交叉评查
创建任务
评查任务列表
使用统计

Step 3 适用租户

保持 checkbox，但分组显示：

公共
  PUBLIC

地区租户
  云浮
  揭阳
  梅州

提示文案：

未勾选的租户首页不会看到该业务入口。

Step 4 业务范围

标题：

这个入口可以处理哪些业务？

交互：

[ ] 合同
    [ ] 建设工程合同
    [ ] 买卖合同
    [ ] 租赁合同

[ ] 公文
    [ ] 请示
    [ ] 通知
    [ ] 会议纪要

规则：

勾选业务大类 = 勾选其下全部业务类型
取消某个业务类型 = 当前入口不包含这个类型
只允许选择已有业务大类和业务类型
不自动创建业务大类和业务类型

右侧摘要：

已选择 2 个业务大类，5 个业务类型
上传页将只显示这些业务范围
文档列表将只显示这些业务范围
规则配置将只显示这些业务范围

空状态：

暂无可选业务类型
请先到“业务类型管理”维护业务大类和业务类型
[去业务类型管理]

4.3 业务范围接口策略

第一阶段优先复用现有接口：

GET /api/v3/document-type-roots?entry_module_id=...
GET /api/evaluation-point-groups?entry_module_id=...
GET /api/evaluation-point-groups/by-document-types

如果现有接口难以一次返回完整树，再新增轻量聚合接口：

GET /api/entry-modules/{id}/business-scope-options
PUT /api/entry-modules/{id}/business-scope

返回结构建议：

{
  "roots": [
    {
      "id": 1,
      "name": "合同",
      "code": "root.contract",
      "selected": true,
      "children": [
        {
          "groupId": 101,
          "documentTypeId": 11,
          "name": "建设工程合同",
          "code": "contract.construction",
          "selected": true
        }
      ]
    }
  ]
}

保存结构建议：

{
  "selectedGroupIds": [101, 102, 201]
}

注意：

这里保存的是入口可用业务范围，不创建新业务类型。

五、业务类型管理 UI 方案

5.1 页面改名和说明

文件：

legal-platform-frontend/app/(audit)/document-types/DocumentTypesIndexClient.tsx
legal-platform-frontend/app/(audit)/document-types/new/DocumentTypesNewClient.tsx
legal-platform-frontend/styles/pages/document-types_index.css
legal-platform-frontend/styles/pages/document-types_new.css

页面标题：

业务类型管理

顶部说明：

这里维护系统可用的业务大类和业务类型。
业务大类用于上传时第一步选择。
业务类型用于上传时第二步选择，并用于绑定规则集。

5.2 列表页展示

当前表格保留，但列名改成：

编码
业务大类
所属业务入口
业务类型数量
已绑定规则集
状态
操作

“一级文档类型”“一级分组”“二级分组”这些词从主表格文案里去掉。

5.3 新建/编辑页文案

当前页先只维护业务大类，不让用户误会它会自动创建运行类型。

标题：

新建业务大类
编辑业务大类

说明：

业务大类是上传时第一步选择，例如合同、公文、案卷。具体业务类型请在规则配置中维护。

如果后续要把业务类型维护也放到这里，需要单独设计二级列表，不和本轮混在一起。

六、上传页 UI 方案

文件：

legal-platform-frontend/app/(audit)/files/upload/FilesUploadClient.tsx
legal-platform-frontend/styles/pages/files_upload.css

上传页保留两级选择，但统一文案：

业务大类
业务类型

选择逻辑：

先按当前入口模块过滤业务大类
选择业务大类后，只显示当前入口允许的业务类型

默认规则：

当前入口只有一个业务大类 -> 默认选中并展示提示
当前业务大类只有一个业务类型 -> 默认选中并展示提示

提示：

当前业务入口：合同评查
上传文件将归属到所选业务大类和业务类型。

提交字段不变：

entryModuleId
typeId
groupId
tenantCode

七、规则配置页 UI 方案

文件：

legal-platform-frontend/app/(audit)/rule-groups/RuleGroupsClient.tsx
legal-platform-frontend/styles/pages/rule-groups_index.css

文案调整：

规则分组 -> 规则配置
一级分组 -> 业务大类
二级分组 -> 业务类型
绑定规则集 -> 配置评查规则

操作规则不变：

业务大类不能绑定规则集
业务类型才可以绑定规则集

按钮文案：

新增一级分组 -> 新增业务大类
新增二级分组 -> 新增业务类型
绑定规则集 -> 配置规则

八、实施任务清单

8.1 准备和基线

执行 ./leaudit.sh status，确认后端、前端、Worker、Beat 运行。
使用 Playwright 登录 000/admin06111 截取当前入口模块、文档类型、上传、规则分组页面现状。
记录当前主要入口 URL：/entry-modules、/entry-modules/new、/document-types、/files/upload、/rule-groups。

8.2 入口模块列表页优化

修改 EntryModulesClient.tsx 页面标题和文案：入口模块管理 改为 业务入口管理。
修改列表列名，隐藏或弱化技术字段。
增加功能菜单摘要展示，沿用现有 tag/badge 风格。
增加业务范围摘要占位，接口未完成前显示 待配置 或 已配置。
跑 Playwright 验证列表页没有布局溢出，按钮权限仍正确。

8.3 入口模块新建/编辑页 4 步向导

在 EntryModuleNewClient.tsx 增加步骤条状态。
把现有基础字段移动到 基础信息 分区。
把 route_path 下拉改成业务文案 + 路径说明。
把菜单模板改成模板卡片，选中后仍更新 menu_profile/features。
把功能勾选移动到 高级功能设置 折叠区。
把租户勾选拆成 公共 和 地区租户 两组。
增加 业务范围 分区，先展示只读/占位状态和跳转 业务类型管理 按钮。
保持提交 payload 字段不变：name/description/route_path/menu_profile/features/tenants。
跑 TypeScript 检查。
跑 Playwright 验证新建、编辑、权限只读、Logo 上传入口不破坏。

8.4 业务范围选择器接入

新增前端组件 BusinessScopeSelector，放在入口模块页面附近，复用现有 checkbox、Card、empty state 风格。
优先用现有文档类型/规则分组接口组装业务大类和业务类型树。
如果现有接口不足，补后端聚合接口 business-scope-options。
选择器支持勾选大类自动勾选子类型。
选择器支持右侧摘要：大类数、业务类型数。
保存时只保存已有业务类型范围，不创建新大类/类型。
跑 Playwright 验证入口编辑页业务范围选择、保存、回显。

8.5 业务类型管理文案优化

修改 DocumentTypesIndexClient.tsx 标题为 业务大类管理。
修改表格列名：业务大类、所属业务入口、业务类型数量、已绑定规则集。
修改空状态文案。
修改 DocumentTypesNewClient.tsx 标题为 新建业务大类/编辑业务大类。
修改说明文案，强调这里维护上传第一步的业务大类。
修改 document-types/page.tsx 和 document-types/new/page.tsx metadata，避免浏览器标题继续显示文档类型。
修改面包屑 文档类型管理/新建文档类型 为 业务大类管理/新建业务大类。
修改侧栏 fallback 菜单 文档类型 为 业务大类管理。
修改上传失败诊断文案中的 文档类型管理/当前文档类型 为 业务大类管理/当前业务大类。
保持现有创建/编辑接口字段不变。
跑 Playwright 验证新建和编辑页字段仍能保存。

8.6 上传页交互文案优化

修改上传页选择项文案：文档类型 改为 业务大类。
修改子类型选择项文案：子类型/二级分组 改为 业务类型。
当前入口只有一个业务大类时自动选中并展示提示。
当前业务大类只有一个业务类型时自动选中并展示提示。
保持提交字段 entryModuleId/typeId/groupId/tenantCode 不变。
跑 Playwright 真实上传表单测试，确认字段落库正确。

8.7 规则配置页文案优化

修改页面标题：规则分组 改为 规则配置。
修改树节点文案：一级分组显示为业务大类，二级分组显示为业务类型。
修改按钮文案：新增业务大类、新增业务类型、配置规则。
一级节点不显示配置规则入口。
二级节点显示配置规则入口。
跑 Playwright 验证规则配置页业务文案、业务大类/业务类型行展示和二级配置入口可见。

8.8 权限和多租户回归

验证没有 entry_module:list:read 不显示业务入口管理菜单。
验证没有 entry_module:create:write 不显示新建业务入口按钮。
验证没有 entry_module:update:write 编辑页不可保存业务入口。
验证没有 entry_module:image:write 不可上传入口 Logo。
验证云浮、揭阳、梅州租户只看到自己或 PUBLIC 入口。

8.9 最终验收

legal-platform-frontend 下运行 npx tsc --noEmit --pretty false。
运行目标 eslint，要求 0 error。
使用 Playwright 跑入口模块编辑页：业务范围步骤、业务范围摘要、业务大类列表/空状态回显。
使用 Playwright 跑上传页：业务大类、业务类型选择和真实提交。
使用 Playwright 跑规则配置页：业务大类/业务类型树、一级不显示配置入口、二级显示配置入口。
更新 docs/superpowers/plans/2026-05-23-entry-module-menu-profile-multitenant-refactor.md 执行记录。

8.10 执行记录 2026-05-23

新增业务入口 UI helper：legal-platform-frontend/lib/business-entry/business-entry-ui.ts，统一维护工作台入口文案、菜单模板文案、功能菜单摘要。
新增单测：legal-platform-frontend/tests/govdoc-audit/business-entry-ui.test.mts，覆盖路由业务文案、模板文案、功能摘要。
使用 TDD 跑红灯：helper 缺失时测试失败，随后实现 helper 并通过。
优化业务入口列表页：标题、说明、列名、工作台入口、工作台类型、业务范围占位、功能菜单摘要改为业务语义。
列表页 Logo 预览从 <img> 改为 next/image，目标 eslint 无 warning。
优化业务入口新建/编辑页：增加 基础信息/功能菜单/适用租户/业务范围 四步结构。
工作台入口下拉改为 通用文档评查/内部公文评查/交叉评查，保存仍使用原始 route_path。
菜单模板改为卡片选择，功能勾选移动到 高级功能设置 折叠区域。
租户选择拆成 公共 和 地区租户 两组。
业务范围先做占位和跳转 业务类型管理，不自动创建、不保存业务范围，避免破坏现有接口。
验证：node --test --experimental-strip-types tests/govdoc-audit/business-entry-ui.test.mts 结果 5 pass / 0 fail。
验证：目标 eslint 结果 0 error / 0 warning。
验证：npx tsc --noEmit --pretty false 通过。
新增业务分类 UI helper：legal-platform-frontend/lib/business-entry/business-taxonomy-ui.ts，统一维护 业务大类/业务类型 标签和上传必填提示。
新增单测：legal-platform-frontend/tests/govdoc-audit/business-taxonomy-ui.test.mts，覆盖业务大类/业务类型文案。
优化业务类型管理列表页：标题、说明、列名、空状态统一为业务语义。
优化业务大类新建/编辑页：把 一级文档类型/入口模块/二级分组/评查点分组 主文案替换为 业务大类/业务入口/业务类型/规则配置。
优化上传页：选择卡片改为 选择业务范围，两级选择改为 业务大类/业务类型，错误提示和说明同步改为业务语义。
验证：node --test --experimental-strip-types tests/govdoc-audit/business-taxonomy-ui.test.mts tests/govdoc-audit/business-entry-ui.test.mts 结果 7 pass / 0 fail。
验证：业务类型管理和上传页目标 eslint 结果 0 error / 0 warning。
验证：npx tsc --noEmit --pretty false 通过。
优化规则配置页：页面标题、指标卡、说明条、筛选项、业务大类/业务类型树、配置弹窗、删除确认和 toast 统一改成业务语义。
规则配置页保持接口和 payload 不变，仅替换用户可见文案；业务大类仍不显示配置规则入口，业务类型显示 配置规则。
修复规则配置页目标 eslint 的 hook dependency warning：把规则预览加载改为稳定 useCallback + ref 读取状态。
验证：npx eslint app/\(audit\)/rule-groups/RuleGroupsClient.tsx --max-warnings=0 结果 0 error / 0 warning。
验证：npx tsc --noEmit --pretty false 通过。
新增业务范围 helper：legal-platform-frontend/lib/business-entry/business-scope-ui.ts，覆盖选择摘要和保存差异计算。
新增业务范围 API 封装：复用 GET /api/v3/document-type-roots、GET /api/rule-groups/tree、PUT /api/v3/document-type-roots/{id}。
入口模块新建/编辑页接入业务范围选择器：用户勾选业务大类，下属业务类型只读展示；保存只更新业务大类归属，不自动创建业务大类或业务类型。
验证：node --test --experimental-strip-types tests/business-entry/business-scope-ui.test.mts tests/govdoc-audit/business-taxonomy-ui.test.mts tests/govdoc-audit/business-entry-ui.test.mts 结果 9 pass / 0 fail。
验证：npx eslint app/\(audit\)/entry-modules/new/EntryModuleNewClient.tsx lib/business-entry/business-scope-ui.ts --max-warnings=0 结果 0 error / 0 warning。
验证：npx eslint lib/api/legacy/entry-modules/business-scope.ts --no-warn-ignored --max-warnings=0 结果 0 error / 0 warning。
验证：npx tsc --noEmit --pretty false 通过。
修正遗漏的文档类型管理外露文案：页面 metadata、面包屑、侧栏 fallback、上传失败诊断统一改成 业务大类管理/新建业务大类/业务大类。
新增面包屑回归测试：business category management breadcrumb uses business wording。
验证：node --test --experimental-strip-types tests/govdoc-audit/home-routing.test.mts tests/govdoc-audit/business-taxonomy-ui.test.mts 结果 12 pass / 0 fail。
验证：目标 eslint 结果 0 error / 0 warning。
验证：npx tsc --noEmit --pretty false 通过。
定位并修复 /rule-groups 服务端路由守卫误拦截：后端 RBAC 权限树当前返回 /rules 且聚合了 evaluation_group:* 权限，但未返回 /rule-groups 路由；布局只按 route path 放行导致跳转 /home?error=insufficient_permissions。
新增 isRouteAllowedByBusinessPermission：仅当访问 /rule-groups 且用户拥有 evaluation_group:* 权限时放行，避免扩大其他路由访问范围。
新增路由守卫单测：route guard allows rule configuration when user has evaluation group permissions，先红灯后实现，最终通过。
Playwright 真实账号 000/admin06111 验收：node /tmp/leaudit-business-entry-ux-smoke.js 通过，结果 scopeItems=38 / rootRows=37 / childRows=58 / errorCount=0。
验证：node --test --experimental-strip-types tests/business-entry/business-scope-ui.test.mts tests/govdoc-audit/business-taxonomy-ui.test.mts tests/govdoc-audit/business-entry-ui.test.mts tests/govdoc-audit/route-access.test.mts 结果 16 pass / 0 fail。
验证：npx eslint app/\(audit\)/layout.tsx lib/auth/route-access.ts tests/govdoc-audit/route-access.test.mts app/\(audit\)/entry-modules/new/EntryModuleNewClient.tsx app/\(audit\)/rule-groups/RuleGroupsClient.tsx lib/business-entry/business-scope-ui.ts --max-warnings=0 结果 0 error / 0 warning。
验证：npx tsc --noEmit --pretty false 通过。
环境说明：本轮 ./leaudit.sh start/restart 在当前工具会话里出现启动后进程立即消失的现象；为完成 Playwright 验收，临时用同等命令在 PTY 会话中启动后端 .venv/bin/python run.py 和前端 npm run dev:dev。

九、风险控制

第一阶段优先改文案和页面组织，不改数据库。
入口模块页不自动创建业务大类/业务类型，避免隐式脏数据。
上传页保留两级选择，避免用户传错类型。
所有菜单生成仍经过 RBAC 权限过滤。
所有入口范围仍经过租户过滤。
Playwright 真实验收前先完成 UI 交互优化，避免测试脚本固化错误交互。

23 KiB Raw Blame History Unescape Escape