YG_FT/UI测试手册.md

第 1~4 周功能 · 界面人工测试手册

用途：你按这份手册在浏览器里点一遍，验证第 1~4 周的功能（登录、租户/项目、资源 ACL、审计日志、审批中心、数据处理 C 模块、写操作自动审计与审批拦截）。 功能代码层均已联调通过（含此前修复的 audit.ts/approval.ts 双重解包、审计接口 /system 前缀、审批模块 include_router 启动崩溃）。下面是给你的人工回归步骤。

---

0. 环境与入口

服务	地址	状态
前端 dev server	http://localhost:16801	你自己起：在 Windows 终端执行 npm run dev（见下方命令）
后端 API	http://localhost:17861 （前缀 /modelTF，前端已配 proxy，不用管）	需 WSL 内 uvicorn 以 --host 0.0.0.0 启动（见下方）

你自己启动前端（务必在 Windows 的 PowerShell / CMD 里，不要用 WSL 终端）：

cd e:\yg_ft\frontend
npm run dev

启动后终端会打印 Local: http://localhost:16801/，浏览器开这个地址即可。vite.config.ts 里 server.port: 16801，所以 npm run dev 默认就是 16801。

为什么必须用 Windows 终端、不能用 WSL：在 WSL 里跑 npm run dev 时，vite 要从 /mnt/e/... 读 node_modules（WSL 挂载的 Windows 盘），每次文件请求都跨文件系统桥，启动要 10 秒、热更新和菜单加载都明显慢。在 Windows 原生跑，node_modules 在 NTFS 上，启动 ~1 秒，开发体验快很多。后端代理在 Windows 下也能连到 WSL 里的 17861。

登录账号（种子数据）：

• 账号：admin
• 密码：admin123

打开浏览器，访问 http://localhost:16801 ，会被引导到登录页。

后端启动命令（务必带 --host 0.0.0.0） —— 你的 .wslconfig 是 networkingMode=mirrored（镜像网络），uvicorn 必须绑 0.0.0.0 才会把端口暴露给 Windows 的 localhost；只绑 127.0.0.1（即省略 --host）时，Windows 侧 localhost:17861 会连不上。在 WSL 终端里跑：

cd /mnt/e/yg_ft/backend
uvicorn app.main:app --host 0.0.0.0 --port 17861 --reload

看到 Application startup complete. 即成功。若仍连不上，把 uvicorn 终端日志贴给我。

---

1. 登录（第 1 周）

1. 账号框输入 admin，密码框输入 admin123
2. 点「登录」按钮
3. 预期：进入仪表盘（Dashboard），侧边栏底部显示当前用户名 admin
4. 验证点：没报错、没跳回登录页，即登录 + 当前用户信息 + 权限码加载都正常

看板空状态（预期）：当前平台暂无真实运行数据，登录后仪表盘的「登录时长排行」等卡片会显示「暂无数据」，待处理告警数为 0。这是预期行为（数据源未接入、不捏造数据），不要当成 bug。

---

1.4 用户设置 → 创建用户（系统设置）

入口：左侧菜单「系统设置 → 用户设置」页右上「创建用户」按钮（或 /user-settings/create），对应后端 POST /modelTF/users。新建的账号用于后续 1.5 各项验证（重置密码 / 启停 / 权限）。

1.4.1 创建普通账号

1. 进入「用户设置」，点「创建用户」
2. 填：
   • 账号：test-user-manual
   • 显示名称：测试用户
   • 初始密码：留默认 platform123（或自定义）
   • 角色：选「操作员」（非 admin，便于后续测启停/权限）
   • 状态：保持「启用」
   • 页面权限：默认已勾 dashboard，按需增删
3. 点「保存」
4. 预期：提示「用户已创建」，跳回列表，列表出现 test-user-manual
5. 验证：退出后该账号 + platform123 应能登录成功；登录后左侧菜单按角色/权限显示（操作员无「用户设置」）

1.4.2 创建时即禁用（可选）

• 新建时「状态」选「禁用」再保存，预期列表该账号状态为「禁用」，且用该账号登录会失败（后端 login 校验 status != 'active' 拒绝）。

---

1.5 用户设置 → 账号操作（系统设置）

入口：左侧菜单「系统设置 → 用户设置」。该页是账号列表，每行「操作」列有「重置密码」按钮，对应后端 POST /modelTF/users/{id}/reset-password。

1.5.1 自定义密码重置

1. 进入「用户设置」，在目标账号（如 u_admin 或任一非 admin 普通账号）行点「重置密码」
2. 弹窗显示账号名，「新密码」输入框填一个自定义密码（如 Newpass123）
3. 点「确定」
4. 预期：提示「密码已重置」，弹窗关闭
5. 验证：退出后用该账号 + 新密码 Newpass123 重新登录，应能登录成功

1.5.2 留空 → 回退默认密码

1. 再点该账号「重置密码」，这次「新密码」留空直接点「确定」
2. 预期：提示「密码已重置」
3. 验证：用该账号 + 默认密码 platform123 登录，应能登录成功（留空即重置为默认密码）

1.5.3 保护账号拒绝重置（预期拦截）

• admin 是内置保护账号（protected），不可被重置。点 admin 行「重置密码」并提交，后端会返回错误提示「protected user cannot be reset」，前端弹「重置失败」。
• 验证：点 admin 行「重置密码」→ 确定，预期出现错误提示，且 admin 密码不变（仍可用 admin123 登录）。

1.5.4 启用 / 禁用账号

操作列对 admin 保护账号隐藏启停按钮（避免锁死管理员自身）；普通账号可见「禁用 / 启用」按钮，对应后端 PUT /modelTF/users/{id}（status 字段）。

1. 在任一非 admin 普通账号行，点「禁用」
2. 预期：状态标签由「启用」变「禁用」，操作按钮变「启用」
3. 验证：用该账号尝试登录，预期登录失败（后端 login 校验 status != 'active' 直接拒绝）
4. 再点「启用」，预期状态恢复「启用」，该账号可重新登录

1.5.5 页面权限精细控制

操作列「权限」按钮进入「权限设置」页（/user-settings/:id/permission），勾选可访问页面码后保存，对应后端 PUT /modelTF/users/{id}（permissions 字段，直接覆盖该用户权限清单）。

1. 在目标账号行点「权限」，进入「权限设置」页
2. 页内列出 12 个页面权限码（仪表盘 / 模型微调 / … / 用户设置），当前已勾选项为该用户现有权限
3. 取消某几项（如去掉 user-settings），点「保存」
4. 预期：提示「权限已保存」，跳回用户列表
5. 验证：用该账号登录后，其权限菜单应不再包含被取消的页面（前端 hasPermission 基于 users.permissions 实时判断）

1.5.6 删除账号

操作列「删除」按钮仅对非保护账号、且非当前登录自己显示，点击触发二次确认，对应后端 DELETE /modelTF/users/{id}（带 current_username 防删自己）。

1. 在 1.4.1 创建的 test-user-manual（或任一非 admin 普通账号）行，点「删除」
2. 弹出二次确认「确定删除该账号？此操作不可恢复」，点「删除」
3. 预期：提示「用户已删除」，列表不再显示该账号
4. 验证：用该账号 + platform123 登录，预期失败（账号已不存在）
5. 边界：admin 保护账号行无「删除」按钮；当前登录账号自身也无「删除」按钮（防误删自己）

---

2. 租户管理（第 2 周）

2.1 创建租户

1. 左侧菜单「平台治理 → 租户管理」
2. 点「新建租户」
3. 填：
   • 租户名称：test-tenant-manual
   • 其他必填按需填写（编码/描述可选）
4. 点「确定」
5. 预期：列表里出现 test-tenant-manual 这一行

2.2 查看租户详情

1. 在 test-tenant-manual 那一行点「详情」
2. 预期：跳到租户详情页，能看到租户基本信息、配额、成员等卡片
3. 返回列表

2.3 更新租户（可选）

1. 在列表行点「编辑」
2. 改个描述或配额，点「确定」
3. 预期：列表/详情里反映修改

---

3. 项目空间（第 2 周）

3.1 创建项目

1. 左侧菜单「平台治理 → 项目空间」
2. 点「新建项目」
3. 填：
   • 项目名称：test-project-manual
   • 关联租户：选刚才的 test-tenant-manual
4. 点「确定」
5. 预期：列表里出现 test-project-manual
6. 记下该项目 ID：进入详情页后，浏览器地址栏形如 http://localhost:16801/projects/<项目ID>，把 <项目ID> 复制下来，第 5 周审批拦截测试要用。

3.2 项目详情

1. 在 test-project-manual 行点「详情」
2. 预期：进入项目详情页，显示项目信息、成员、底部有「归档项目」「资源授权 (ACL)」按钮

3.3 添加项目成员

1. 在详情页「项目成员」卡片点「添加成员」
2. 选用户（如 u_admin 或任意存在的用户），设角色
3. 点「确定」
4. 预期：成员列表里出现该用户
5. 可顺手测：改成员角色（下拉切换）、移除成员（点「移除」确认）

3.4 资源授权 ACL（第 2 周）

1. 在详情页点「资源授权 (ACL)」按钮（右上角区域）
2. 弹出「资源授权 (ACL)」对话框，标题为「资源授权 (ACL)」，宽度 640px
3. 点「添加授权项」，新增一行：
   • 主体类型：选「用户」或「项目角色」
   • 主体 ID：填用户 ID 或角色名（如 u_admin）
   • 权限：勾选所需项（read / write / execute / download / delete / share）
4. 可继续「添加授权项」加多条；点每行右「删除」可移除
5. 点对话框底部「保存」
6. 预期：提示「ACL 已保存」，弹窗关闭
7. 重新打开该对话框，预期：刚才的授权项还在（已落库）

3.5 归档项目

1. 在详情页点「归档项目」
2. 预期：项目状态变为 archived（注意：归档是直接执行，没有二次确认弹窗）
3. 如需后续做审批拦截测试，归档前请先跳过此步（见第 5.4）。

3.6 写操作自动审计（预期行为，第 4 周验证用）

以下写操作在执行后会自动产生一条审计记录（无需手动触发），到「审计日志」页可查：

• 租户：创建 / 更新 / 删除
• 项目：创建 / 更新 / 归档 / 删除
• 项目成员：添加 / 更新角色 / 移除

即第 2、3 步里你做的创建租户、创建项目、加成员、归档，都会在第 4 周「审计日志」里看到对应条目。

---

4. 审计日志（第 3 周）

4.1 查看与过滤

1. 左侧菜单「平台治理 → 审计日志」
2. 页面顶部筛选栏，可组合：
   • 租户（下拉）/ 项目（下拉）
   • 操作人 ID（输入框，回车查询）
   • 动作（输入框，如 project.create；回车查询）
   • 目标类型（输入框，如 project；回车查询）
3. 点「查询」刷新列表
4. 列表列：时间 / 租户 / 项目 / 操作人 / 动作 / 目标类型 / 目标 ID / 详情 / IP
5. 验证：把「动作」填 project.create 查询，应能查到第 3.1 步创建项目的记录；「操作人」即登录 token（当前登录用户标识）
6. 底部分页（total / 上一页 / 下一页）可翻页

4.2 导出 CSV

1. 先设好筛选条件（如限定某个租户或某个动作，导出会按当前筛选导出）
2. 点「导出 CSV」
3. 预期：浏览器下载 audit_logs.csv
4. 打开文件，预期列与页面一致：time,tenant_id,project_id,actor_id,action,target_type,target_id,detail,client_ip，内容与页面过滤结果一致

---

5. 审批中心（第 4 周）

5.0 审批流程说明

• 审批模板：定义审批步骤（多级审批），在「平台治理 → 审批模板」页创建。
• 审批实例：在「平台治理 → 审批中心」发起，可选模板（多步）或不选（单步），生成待审批实例后逐步通过/拒绝。

5.1 创建审批模板（多步审批，可选）

1. 浏览器访问 http://localhost:16801/approvals/templates
2. 点「新建模板」
3. 填「模板名称」（如 project-change-2step）
4. 「审批步骤」下：
   • 第 1 步：审批人 ID 填某人（如 u_admin），或留空表示「任意审批人」
   • 点「+ 添加步骤」加第 2 步，填审批人 ID
   • 可用每行「删」移除步骤
5. 点「确定」
6. 预期：列表出现 project-change-2step，「审批步骤数」=2，步骤标签显示 #1 xxx #2 xxx
7. 注：模板创建后不会自动发起实例，需到审批中心用该模板发起（5.2）。

5.2 发起审批（实例）

1. 左侧菜单「审批中心」（或 /approvals）
2. 点「发起审批」
3. 弹窗字段：
   • 模板：可选；下拉选 5.1 建的模板（多步），或不选（单步）
   • 资源类型：默认 project，保持
   • 租户：选该项目所在的租户（默认带出项目空间当前租户）
   • 资源 ID：必填，下拉选第 3.1 步建的项目（显示项目名，无需手填 ID）
   • 申请人：必填，下拉选一个用户
4. 点「发起」
5. 预期：列表新增一行，状态 pending（黄），当前步 0（或 1，取决于后端 0/1 基）
6. 验证多步：若选了 2 步模板，点「详情/审批」打开后，「审批步骤」用 el-steps 显示 2 步

5.3 审批（通过 / 拒绝）

1. 在列表行点「详情/审批」
2. 弹窗显示：资源、申请人、状态标签、审批步骤进度条
3. 当状态为 pending 时，下方出现审批表单：
   • 审批人：必填，下拉选一个用户
   • 结果：选「通过」或「拒绝」
   • 意见：可填
4. 点「提交审批」
5. 预期：
   • 单步 / 最后一步「通过」→ 状态变 approved（绿）
   • 任一步「拒绝」→ 状态变 rejected（红），后续步骤终止
   • 多步中前几步「通过」→ 状态仍 pending，当前步前进，需再打开提交下一步
6. 验证：状态标签颜色与值正确；rejected 后不再能提交

5.4 审批拦截（端到端治理，重点）

逻辑：项目「归档」「删除」前，若已存在针对该项目的**待审批（pending）**实例，会被拦截返回 409「存在待审批的变更，请先完成审批」，直到审批通过/拒绝。

测试步骤：

1. 前置：确保第 3.1 步项目未被归档（若已归档，先新建一个测试项目并记下 ID）。
2. 在「审批中心」发起审批，资源类型选 project、租户选该项目所在租户、资源 ID 下拉选该项目、申请人任选（单步即可）。
3. 进入该项目详情页（/projects/<项目ID>），点「归档项目」。
4. 预期：归档被拦截，页面提示「存在待审批的变更，请先完成审批」，项目状态不会变 archived。
5. 回「审批中心」对该实例「详情/审批」→ 提交「通过」。
6. 状态变 approved 后，再回项目详情点「归档项目」。
7. 预期：归档成功，状态变 archived。
8. 去「审计日志」查 project.archive 动作，应能看到这条记录（验证写操作审计 + 拦截放行后落库）。

5.5 删除拦截（可选，同逻辑）

• 对项目发起 pending 审批实例后，尝试删除该项目（列表或详情的删除），预期同样被 409 拦截；审批结束后方可删除。

---

6. 数据处理（C 模块 · 第 2 周）

入口：左侧菜单「数据治理 → 数据处理」（/data-process），对应后端 /modelTF/data-process/*。该模块为本次合并从 yg_ft1 并入的可运行子系统（后端 app/modules/data_process/ + 前端 views/data-process/）。 创建任务为六步向导：创建任务 → 大模型选择 → 上传文件 → 数据预览 → 开始生成 → 结果编辑与保存。后端启动时会自动建表（002_data_process.sql），无需手动迁移。

6.1 列表与入口

1. 左侧菜单「数据治理 → 数据处理」
2. 预期：进入列表页 /data-process，展示已有数据处理任务（空状态显示「暂无数据」属正常，不要当成 bug）
3. 点右上「新建数据处理」进入创建向导

6.2 创建任务（六步向导）

步骤 1 · 创建任务

1. 填任务名称（如 test-dp-manual）、描述（可选）
2. 选处理类型：
   • 结构化数据（structured）：按行生成 QA 对
   • 非结构化数据（unstructured）：文档切片（chunk 方法/大小/重叠/保留表格代码块等）
   • 外部数据源（external）：接 PostgreSQL 等外部库
3. 配置处理选项（预处理、语义增强、数据集切分比例、输出类型、温度等，保持默认即可）
4. 点「继续：选择大模型」

步骤 2 · 大模型选择

1. 从模型下拉选一个生成模型（需「模型管理」里已登记可用模型；若下拉为空，先到「模型管理」登记一个基座/API 模型）
2. 设输出要求（生成模型、提示词、输出类型、reasoning、温度、max_tokens、质量过滤开关等）
3. 点「继续：上传文件」

步骤 3 · 上传文件

• 结构化/非结构化：点「上传」选本地文件（jsonl/csv/pdf/docx/xlsx/txt 等，按处理类型校验扩展名）；或点「使用样例文件」快速载入示例 finance_qa.jsonl
• 外部数据源：填连接（postgresql URL、认证模式、只读 SELECT 查询），点「测试连接」→ 联通后「拉取数据」

1. 选/拉取至少一个源文件，等待上传完成（状态变 ready）
2. 点「继续：数据预览」，系统自动按配置切分（进度条，可能耗时；失败会提示原因，可重试）

步骤 4 · 数据预览

1. 切分完成后进入预览，左侧为源文件 / 分片列表，右侧为预览内容
2. 可编辑预览条目内容、新增 / 删除条目、还原为原文（不影响源文件）
3. 切换不同源文件核对切分结果
4. 点「确认预览并继续」

步骤 5 · 开始生成

1. 进入生成页，显示任务摘要（任务名、处理类型、文件、预览条目数、修改条数）
2. 点「开始生成」启动处理（调用所选大模型）
3. 等待生成完成：状态 running → completed（失败显示原因，可「重新生成」）
4. 生成成功后点「查看生成结果」

步骤 6 · 结果编辑与保存

1. 进入结果编辑页，逐条检查结果（问题 / 答案等），可编辑字段、单条或批量「重新生成」
2. 校验通过后点「保存任务」
3. 预期：提示「生成结果已确认」，跳转到任务详情页 /data-process/<任务ID>

6.3 任务详情

1. 列表点目标任务「详情」（或保存后自动进入）
2. 预期：详情页展示任务信息、处理配置、源文件、预览条目、生成结果
3. 支持「重新生成」（/data-process/:id/regenerate）与「任务进度」（/data-process/:id/workflow）两个子页，均复用创建向导

6.4 重新生成（可选）

1. 详情页或列表进入「重新生成」子页
2. 调整配置（保持原处理类型），保存后按新配置重新切分 / 生成；原生成结果与已发布数据在点击「开始生成」前保持不变
3. 验证：提交重新生成后，进度可在「任务进度」页查看

6.5 发布数据集（第 2 周验收点）

1. 结果确认后，在详情页点「发布数据集」（对应 POST /modelTF/data-process/{id}/publish）
2. 填目标数据集元信息（名称 / 项目归属等），确认发布
3. 预期：生成数据集记录，可在「数据集管理」看到该发布数据集，来源链路保留

6.6 删除任务（可选）

1. 列表行点「删除」，二次确认后删除
2. 预期：列表不再显示该任务

---

7. 验收清单（打勾）

第 1~2 周

• 1. 登录成功，进仪表盘，显示 admin
• 2. 租户：新建 → 列表出现 → 详情渲染正常
• 3. 项目：新建 → 列表出现 → 详情渲染正常
• 4. 项目成员：添加 / 改角色 / 移除 均成功
• 5. 资源 ACL：添加授权项 + 勾选权限 + 点「保存」成功，重开仍在
• 6. 归档：点后状态变 archived
• 7. 用户设置：创建用户（账号/显示名/初始密码/角色/状态/页面权限均可设，列表出现新账号）、重置密码（自定义生效 / 留空回退 platform123 / admin 被拒）、启用禁用账号（禁用后登录失败、启用后恢复）、页面权限精细控制（取消权限后登录即生效）、删除账号（二次确认后列表移除、登录失败）

第 2 周（数据处理 · C 模块）

• 16. 数据处理入口可见（数据治理 → 数据处理），列表 / 空状态正常
• 17. 创建向导六步可走通：创建任务 → 选模型 → 上传/拉取源文件 → 切分预览（可编辑/增删/还原）→ 生成 → 结果保存并跳详情
• 18. 结构 / 非结构化 / 外部数据源三类处理类型均可配置并产出预览条目
• 19. 生成结果可编辑、可单条 / 批量重新生成，保存后跳详情
• 20. 发布数据集成功，「数据集管理」可见且保留来源链路
• 21. 全程浏览器控制台（F12 → Console）在数据处理流程中无红色报错

第 3 周（审计）

• 8. 审计日志：按 动作/操作人/项目 过滤均能返回正确结果
• 9. 审计日志：导出 CSV 成功，列与内容正确
• 10. 写操作自动留痕：创建/归档项目等操作在审计页可查到对应 action

第 4 周（审批 + 拦截）

• 11. 审批模板：新建模板（多步）成功，列表显示步骤数
• 12. 发起审批：生成 pending 实例
• 13. 审批：通过（单步→approved / 多步→逐步前进）、拒绝（→rejected 终止）
• 14. 审批拦截：项目有 pending 实例时归档被 409 拦截；审批通过后归档成功
• 15. 全程浏览器控制台（F12 → Console）无红色报错

---

8. 我自测已覆盖（你不用重复，除非想验证）

• 后端真实导入：import app.main → IMPORT_OK，启动崩溃已修复（approval/__init__.py 补 re-export router）。
• 前端 type-check 全绿：audit.ts/approval.ts 双重解包已改 get/post；审计接口已加 /system 前缀（/system/audit-logs、/system/audit-logs/export）。
• 接口链路已用真实代码核对：审计查询/导出（system）、审批模板/实例/逐步决策（approvals）、项目写操作自动 record_audit 与 _require_no_pending_approval 拦截均按上述行为实现。

9. 已知非 bug / 注意事项（仅供参考）

1. 前端由你自己在 Windows 终端 跑 npm run dev 启动（默认 16801）。不要从 WSL 终端启动（会慢 8 倍）。
2. 「归档项目」当前是直接执行无确认弹窗——功能正确，建议后续补个二次确认，避免误操作。
3. 控制台偶见的 ERR_ABORTED 是导航时浏览器正常中止旧 CSS 请求，无害；Google Fonts 外网字体加载失败不影响功能。
4. 审计「操作人」列 = 登录 token（当前登录用户标识），由前端 Authorization: Bearer <token> 透传，非真实姓名。

10. 清理测试数据（可选）

手动建的 test-tenant-manual / test-project-manual、审批实例/模板可在对应列表里删除，或告诉我帮你清库（后端连 PostgreSQL，PlatformStore 启动时自动建表）。