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 终端）：

```powershell
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 终端**里跑：
> ```bash
> 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. 「归档项目」当前是**直接执行无确认弹窗**——功能正确，建议后续补个二次确认，避免误操作。
4. 控制台偶见的 `ERR_ABORTED` 是导航时浏览器正常中止旧 CSS 请求，无害；Google Fonts 外网字体加载失败不影响功能。
5. 审计「操作人」列 = 登录 token（当前登录用户标识），由前端 `Authorization: Bearer <token>` 透传，非真实姓名。

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

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