# 开放API-学生列表授权 需求设计方案

> 作者：pangu  
> 创建时间：2026-02-04  
> 评审状态：待评审

---

## 一、背景与目标

### 1.1 背景

盘古用户认证中心已具备「应用管理」能力：可创建第三方应用、分配应用编码（appCode）与密钥（appSecret），并在管理后台为应用勾选「接口授权」。当前缺少**对外暴露的开放 API** 及**基于应用身份的签名鉴权与接口授权校验**，外部系统无法在未登录用户的前提下，以应用身份安全调用已授权接口。

### 1.2 目标

- **需求侧**：支持外部系统以「应用身份」调用指定已授权接口（首期以**学生列表查询**为真实场景），不依赖用户登录 Token。
- **安全侧**：请求必须携带应用编码、时间戳、签名，服务端校验签名并校验该应用是否已授权访问该接口，未授权或签名错误一律拒绝。
- **可评审**：提供完整需求说明与技术方案，便于评审与后续扩展更多开放接口。

---

## 二、范围与边界

### 2.1 本期范围

| 序号 | 内容 | 说明 |
|------|------|------|
| 1 | 开放 API 机制 | 统一路径前缀 `/open/api/**`，请求头鉴权（X-App-Id、X-Timestamp、X-Sign） |
| 2 | 学生列表查询 | 提供 GET `/open/api/student/list`，与现有业务逻辑一致，仅鉴权方式不同 |
| 3 | 应用管理侧 | 新增/编辑应用时保存「接口授权」到 pg_app_api；查询应用详情时回显已选接口 |
| 4 | 接口字典 | pg_api_dict 中至少包含「学生列表」开放接口配置，供授权勾选与校验使用 |

### 2.2 边界（本期不做）

- 仅实现「学生列表」一个开放接口作为示例；其他业务接口（如学校、会员等）后续按同机制扩展。
- 不涉及 OAuth2/第三方登录；仅做「应用级」签名鉴权与接口授权。

---

## 三、用户角色与使用场景

### 3.1 角色

| 角色 | 说明 |
|------|------|
| 运营/管理员 | 在应用管理中创建应用、为应用勾选「学生列表」等接口授权 |
| 外部系统 | 使用 appCode + appSecret 对请求签名，调用 GET `/open/api/student/list` 获取学生列表（分页、筛选与现有一致） |

### 3.2 典型场景

1. **配置授权**  
   管理员在「应用管理」中新增应用「XX 学情系统」，保存后获得 appCode（如 YY000001）、appSecret（32 位）。在编辑该应用时勾选「学生列表」接口授权并保存。

2. **外部调用**  
   XX 学情系统在服务端使用 appCode、appSecret 生成签名，请求 GET `/open/api/student/list?pageNum=1&pageSize=10`，并携带请求头 X-App-Id、X-Timestamp、X-Sign。平台校验通过且该应用已授权「学生列表」后返回分页数据。

3. **未授权/签名错误**  
   若未勾选「学生列表」或签名错误，返回 401/403 及明确错误信息，不返回业务数据。

---

## 四、功能需求

### 4.1 开放 API 鉴权与授权

- **FR-1** 请求必须携带请求头：`X-App-Id`（应用编码）、`X-Timestamp`（毫秒时间戳）、`X-Sign`（签名）。
- **FR-2** 时间戳与服务器时间差超过 5 分钟视为过期，拒绝请求。
- **FR-3** 根据 X-App-Id 查询应用信息；应用不存在或已停用则拒绝。
- **FR-4** 签名算法：请求参数（query+body 按参数名 ASCII 排序）拼接为 `key1=value1&key2=value2&...&appSecret=应用密钥`，再对该字符串做 MD5，结果转大写，与 X-Sign 比对；不一致则拒绝。
- **FR-5** 请求 URI 对应的「开放接口」必须在当前应用的授权列表中（以 pg_api_dict.api_path 与 pg_app_api 关联为准），否则拒绝访问。

### 4.2 学生列表开放接口

- **FR-6** 提供 GET `/open/api/student/list`，支持与现有学生列表一致的查询参数（如 studentName、studentNo、schoolId 等）及分页参数（pageNum、pageSize）。
- **FR-7** 响应格式与现有管理端学生列表一致（TableDataInfo：rows、total 等），便于对接方使用。

### 4.3 应用管理侧

- **FR-8** 新增/编辑应用时，请求体可携带接口授权标识（如 apiCodes：接口编码列表）；保存时同步更新 pg_app_api（先删该应用原有授权，再按 apiCodes 插入）。
- **FR-9** 查询应用详情（含列表展示）时，返回该应用已授权的接口信息（如 apiCodes 或等效），供前端勾选回显。

### 4.4 接口字典

- **FR-10** pg_api_dict 中至少有一条「学生列表」开放接口记录：api_path 为 `/open/api/student/list`，api_method 为 GET，供应用管理勾选与鉴权校验使用。

---

## 五、非功能需求

- **NFR-1** 鉴权失败时返回 HTTP 状态码与 JSON 错误信息（如 401 签名错误、403 无权限、400 参数缺失/过期）。
- **NFR-2** 授权关系变更后，建议在较短时间内生效（可为实时或短 TTL 缓存，技术方案中约定）。
- **NFR-3** 文档与示例：提供开放 API 调用说明及学生列表调用示例（含签名算法与示例请求），便于对接方自测与联调。

---

## 六、验收标准

1. 在应用管理中为某应用勾选「学生列表」并保存后，该应用使用正确签名调用 GET `/open/api/student/list` 可返回学生列表数据。
2. 未勾选「学生列表」的应用调用同一接口，返回 403 无权限。
3. 错误签名或过期时间戳，返回 401 或 400，且不返回业务数据。
4. 应用管理新增/编辑时接口授权勾选可保存并回显；列表/详情中可看到已授权接口信息。

---

## 七、附录：术语

| 术语 | 说明 |
|------|------|
| appCode | 应用编码，如 YY000001，唯一标识一个应用 |
| appSecret | 应用密钥，32 位，用于参与签名计算，需保密 |
| 接口授权 | 应用与 pg_api_dict 中某条 API 的关联关系，存储在 pg_app_api |
| 开放 API | 以 `/open/api/**` 为前缀、使用应用签名鉴权的接口，无需用户登录 |