# 开放API-学生列表 调用测试说明

> 作者：pangu  
> 创建时间：2026-02-04

---

## 一、前置条件

1. **执行接口字典数据**（若尚未执行）：
   ```bash
   # 在数据库中执行
   mysql -u用户 -p 库名 < backend/pangu-modules/pangu-business/sql/open_api_dict_data.sql
   ```
   或在客户端执行 `open_api_dict_data.sql` 中的 INSERT 语句。

2. **应用管理中**：
   - 新增或编辑一个应用，在「接口授权」中勾选 **学生列表**，保存。
   - 记录该应用的 **应用编码（appCode）** 和 **应用密钥（appSecret）**（重置密钥后可查看）。

---

## 二、签名算法

1. 将请求参数（仅 Query 参数，按参数名 **ASCII 升序**）拼接：  
   `key1=value1&key2=value2&...`
2. 末尾追加：`&appSecret=你的应用密钥`
3. 对整串做 **MD5**，结果转为 **大写**，即 `X-Sign`。

**示例（GET）**：
- 请求：`/open/api/student/list?pageNum=1&pageSize=10`
- 参数排序后：`pageNum=1&pageSize=10`
- 假设 appSecret=`abc123`，则参数字符串：`pageNum=1&pageSize=10&appSecret=abc123`
- sign = MD5(`pageNum=1&pageSize=10&appSecret=abc123`).toUpperCase()

---

## 三、请求头

| 请求头       | 说明                    |
|-------------|-------------------------|
| X-App-Id    | 应用编码（appCode）     |
| X-Timestamp | 当前时间毫秒时间戳      |
| X-Sign      | 按上述算法计算的签名    |

---

## 四、curl 示例

假设：
- 应用编码：`YY000001`
- 应用密钥：`a1b2c3d4e5f6789012345678901234ab`
- 基础地址：`http://localhost:8080`

**1. 先计算签名（示例用当前时间戳）**

参数：`pageNum=1&pageSize=10&appSecret=a1b2c3d4e5f6789012345678901234ab`  
可用在线 MD5 或命令行（见下方脚本）得到大写 MD5 作为 X-Sign。

**2. 调用**

```bash
# 将 TIMESTAMP 和 SIGN 替换为实际值
TIMESTAMP=$(date +%s)000
# SIGN 需根据 当前参数+appSecret 用 MD5 计算，此处为占位
SIGN="这里填计算出的32位大写MD5"

curl -s -X GET "http://localhost:8080/open/api/student/list?pageNum=1&pageSize=10" \
  -H "X-App-Id: YY000001" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Sign: $SIGN"
```

---

## 五、测试脚本（含签名计算）

在项目根目录执行：

```bash
./scripts/openapi-student-list-test.sh <appCode> <appSecret> [baseUrl]
```

示例：

```bash
./scripts/openapi-student-list-test.sh YY000001 a1b2c3d4e5f6789012345678901234ab
# 指定环境
./scripts/openapi-student-list-test.sh YY000001 your_secret http://192.168.1.100:8080
```

---

## 六、预期结果

| 场景           | HTTP 状态 | 说明                         |
|----------------|-----------|------------------------------|
| 签名正确且已授权 | 200       | 返回 rows、total 等分页数据  |
| 未勾选学生列表   | 403       | 无权访问该接口               |
| 签名错误        | 500       | 签名验证失败（业务异常）     |
| 时间戳过期      | 500       | 请求已过期                   |
| 缺少请求头      | 500       | 缺少认证参数                 |

---

## 七、可选：学生列表查询参数

与后台 `/business/student/list` 一致，例如：

- `pageNum`、`pageSize`：分页
- `studentName`：学生姓名（模糊）
- `studentNo`：学号（模糊）
- `schoolId`：学校 ID  
等，按需传递；**参与签名的参数需包含所有本次请求的 Query 参数**（按参数名排序后拼接再加 appSecret 做 MD5）。