leaudit-platform-backend/docs/superpowers/plans/2026-05-23-business-entry-ux-optimization.md

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

> **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 用户语义

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

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

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

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

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

### 1.2 业务边界

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

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

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

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

### 1.3 最终操作链路

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

## 二、UI 风格约束

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

```text
继续使用现有 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 容器、表格、圆角、阴影风格
继续沿用当前入口模块、文档类型、规则分组页面的表单布局
```

禁止：

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

## 三、页面信息架构调整

### 3.1 菜单命名

建议调整左侧菜单文案：

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

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

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

### 3.2 页面职责

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

## 四、入口模块管理 UI 方案

### 4.1 列表页优化

文件：

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

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

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

业务范围列显示摘要：

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

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

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

操作按钮：

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

权限仍走现有 RBAC：

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

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

文件：

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

页面顶部增加步骤条：

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

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

#### Step 1 基础信息

字段：

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

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

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

保存时仍提交原 `route_path`。

#### Step 2 功能菜单

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

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

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

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

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

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

#### Step 3 适用租户

保持 checkbox，但分组显示：

```text
公共
  PUBLIC

地区租户
  云浮
  揭阳
  梅州
```

提示文案：

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

#### Step 4 业务范围

标题：

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

交互：

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

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

规则：

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

右侧摘要：

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

空状态：

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

### 4.3 业务范围接口策略

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

```text
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
```

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

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

返回结构建议：

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

保存结构建议：

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

注意：

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

## 五、业务类型管理 UI 方案

### 5.1 页面改名和说明

文件：

```text
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
```

页面标题：

```text
业务类型管理
```

顶部说明：

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

### 5.2 列表页展示

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

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

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

### 5.3 新建/编辑页文案

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

标题：

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

说明：

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

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

## 六、上传页 UI 方案

文件：

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

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

```text
业务大类
业务类型
```

选择逻辑：

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

默认规则：

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

提示：

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

提交字段不变：

```text
entryModuleId
typeId
groupId
tenantCode
```

## 七、规则配置页 UI 方案

文件：

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

文案调整：

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

操作规则不变：

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

按钮文案：

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

## 八、实施任务清单

### 8.1 准备和基线

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

### 8.2 入口模块列表页优化

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

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

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

### 8.4 业务范围选择器接入

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

### 8.5 业务类型管理文案优化

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

### 8.6 上传页交互文案优化

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

### 8.7 规则配置页文案优化

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

### 8.8 权限和多租户回归

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

### 8.9 最终验收

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

### 8.10 执行记录 2026-05-23

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

## 九、风险控制

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