OneAuth/scripts/tests/README.md

# 测试脚本说明

本目录包含 VBase 的集成测试脚本，使用 bash + curl 测试 API 功能。

## ⚠️ 重要注意事项 (必读)

1. **环境重置与管理员权限**：
   - 系统设计为：**数据库重置后第一个注册的用户自动获得 Admin (超级管理员) 权限**。
   - 后续注册的用户默认为普通 User 权限。
   - 很多权限测试（如 `02_resource_perm.sh`）依赖于这个机制。如果数据库未清理，新注册的用户可能只是普通用户，导致 Admin 权限测试失败。
   - **强烈建议使用 `clean_run.sh` 脚本运行测试**。该脚本会自动清理数据库 (`/tmp/vb.sqlite`) 并重启服务，确保环境一致性。

2. **BASE_URL 配置**：
   - 测试脚本依赖 `BASE_URL` 环境变量连接服务。
   - 如果你的系统环境变量中设置了其他的 `BASE_URL`（例如生产环境地址），直接运行脚本可能会导致连接错误或误操作。
   - `clean_run.sh` 会强制设置 `BASE_URL=http://localhost:4000`，确保测试在本地隔离环境中运行。

## 目录结构

```text
scripts/tests/
├── README.md                 # 本说明文件
├── lib.sh                    # 公共函数库
├── clean_run.sh              # [推荐] 一键清理环境、重启服务并运行所有测试
├── run_all.sh                # 运行所有测试脚本 (不负责清理环境)
├── 00_none_auth.sh           # 1. 未登录访问测试
├── 01_setup_users.sh         # 2. 用户初始化与基础认证
├── 02_resource_perm.sh       # 3. 资源权限交叉测试
├── 03_org_permission.sh      # 4. 组织权限测试
└── 04_org_load_middleware.sh # 5. LoadOrg 中间件测试
```

## 推荐运行方式

### 方式一：一键清理并运行 (强烈推荐)

最稳健的测试方式，自动处理数据库清理、服务重启和环境变量配置：

```bash
# 在项目根目录下或 scripts/tests 目录下运行
bash scripts/tests/clean_run.sh
```

### 方式二：手动运行

如果你需要手动运行单个脚本进行调试，请确保：
1. 服务已启动 (`go run cli/main.go ...`)。
2. `BASE_URL` 指向正确的本地服务。
3. 如果测试依赖 Admin 权限，请确保你使用的 Token 属于 Admin 用户。

```bash
# 1. 设置环境变量
export BASE_URL=http://localhost:4000
export TEST_TIMESTAMP=$(date +%s) # 生成统一时间戳，避免数据冲突

# 2. 运行特定测试
bash scripts/tests/02_resource_perm.sh
```

## 测试脚本详情

### 00_none_auth.sh

**测试内容**：未登录状态下访问受保护接口
- 验证 API 是否正确拦截未携带 Token 的请求
- 覆盖 Users, Orgs, Roles, Settings 等核心模块

### 01_setup_users.sh

**测试内容**：用户初始化与基础功能验证
- 注册三个核心账户：Admin, User1, User2
- 验证注册与登录流程
- 验证基础功能：修改个人信息、修改密码、Token 刷新、用户登出

### 02_resource_perm.sh

**测试内容**：跨用户资源访问权限验证
- 场景 1: Admin 修改任意用户信息 (允许)
- 场景 2: User1 修改自己信息 (允许)
- 场景 3: User1 修改 User2 信息 (禁止 403)
- 场景 4: User1 修改 Admin 信息 (禁止 403)
- 场景 5: User2 修改 User1 信息 (禁止 403)

### 03_org_permission.sh

**测试内容**：组织权限控制
- admin 创建组织
- user 不能修改他人创建的组织
- admin 邀请 user 加入组织
- 普通成员不能修改组织信息
- 只有 admin/owner 可以修改组织

### 04_org_load_middleware.sh

**测试内容**：LoadOrg 中间件验证
- 验证 `X-Org-ID` 头部的处理
- 验证用户是否为组织成员的检查逻辑
- 验证非成员访问组织资源被拒绝 (403)
- 验证成员访问组织资源被允许 (200)

## 测试环境变量参考

| 变量 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `BASE_URL` | `http://localhost:4000` | 测试服务的 API 地址 |
| `TEST_TIMESTAMP` | `date +%s` | 测试运行的时间戳，用于生成唯一的用户名/邮箱 |

## 常见问题与踩坑记录 (Troubleshooting)

### 1. 权限测试失败：Admin 用户无法修改他人信息

**现象**：
运行 `02_resource_perm.sh` 时，提示 `Admin 修改 User1 失败` 或返回 403。

**原因**：
VBase 的逻辑是**系统初始化的第一个用户自动获得 Admin 权限**。如果你在测试前没有清理数据库，数据库中可能已经存在其他用户，导致你测试脚本中注册的 "Admin" 用户实际上只获得了普通 User 权限。

**解决**：
使用 `clean_run.sh` 运行测试，或者手动删除数据库文件 `/tmp/vb.sqlite` 后重启服务。

### 2. 连接被拒绝 (Connection refused) 或 404

**现象**：
测试脚本提示无法连接到服务器，或者返回非预期的 404。

**原因**：
- 服务未启动。
- `BASE_URL` 环境变量配置错误（例如系统环境中设置了生产环境地址）。

**解决**：
- 确保服务正在运行且监听端口与 `BASE_URL` 一致（默认 4000）。
- 强制指定 `BASE_URL`：`export BASE_URL=http://localhost:4000`。

### 3. 端口被占用 (Address already in use)

**现象**：
运行 `go run cli/main.go ...` 时提示端口 4000 被占用。

**原因**：
之前的测试服务没有正常关闭，或者有其他服务占用了该端口。

**解决**：
查找并关闭占用端口的进程：
```bash
lsof -i :4000
kill -9 <PID>
```
`clean_run.sh` 脚本已内置了此清理逻辑。

### 4. 数据不一致 / 用户不存在

**现象**：
手动运行多个脚本时，提示用户不存在或登录失败。

**原因**：
测试脚本使用 `TEST_TIMESTAMP` 生成唯一的用户名（如 `user1_1712345678`）。如果你分别运行两个脚本且没有固定 `TEST_TIMESTAMP`，第二个脚本会生成新的时间戳，导致无法找到第一个脚本创建的用户。

**解决**：
在手动运行一系列脚本前，先导出时间戳：
```bash
export TEST_TIMESTAMP=$(date +%s)
bash 01_setup_users.sh
bash 02_resource_perm.sh
```