YG_FT/UI测试手册.md

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

用途：你按这份手册在浏览器里点一遍，验证第 1~4 周的功能（登录、租户/项目、资源 ACL、审计日志、审批中心、写操作自动审计与审批拦截）。 功能代码层均已联调通过（含此前修复的 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.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 登录）。

---

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. 验收清单（打勾）

第 1~2 周

• 1. 登录成功，进仪表盘，显示 admin
• 2. 租户：新建 → 列表出现 → 详情渲染正常
• 3. 项目：新建 → 列表出现 → 详情渲染正常
• 4. 项目成员：添加 / 改角色 / 移除 均成功
• 5. 资源 ACL：添加授权项 + 勾选权限 + 点「保存」成功，重开仍在
• 6. 归档：点后状态变 archived
• 7. 用户设置 → 重置密码：自定义密码生效 / 留空回退 platform123 / admin 保护账号被拒

第 3 周（审计）

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

第 4 周（审批 + 拦截）

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

---

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

• 后端真实导入：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 拦截均按上述行为实现。

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

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

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

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