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

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

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

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