# 开放API-学生列表授权 技术设计方案

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

---

## 一、总体架构

### 1.1 请求链路

```
外部请求 GET /open/api/student/list?pageNum=1&pageSize=10
  → 不经过 Sa-Token 登录校验（security.excludes 排除 /open/api/**）
  → ApiAuthInterceptor 拦截 /open/api/**
      → 校验 X-App-Id、X-Timestamp、X-Sign
      → 查应用信息、校验接口授权
  → OpenApiStudentController.list() → IPgStudentService.selectPageList()
  → 返回 TableDataInfo<StudentVo>
```

### 1.2 模块与职责

| 模块/组件 | 职责 |
|-----------|------|
| Security 配置 | 将 `/open/api/**` 加入排除路径，不校验登录 |
| ApiAuthInterceptor | 仅对 `/open/api/**` 生效：校验头、签名、接口授权 |
| OpenApiStudentController | 提供 GET `/open/api/student/list`，委托现有 StudentService |
| IPgApplicationService | 新增 selectByAppCode、checkApiPermission；新增/编辑时同步 pg_app_api |
| PgAppApiMapper | 新增按 appCode 查授权 api_path 列表方法（联表 pg_api_dict） |
| pg_api_dict | 增加「学生列表」开放接口记录，api_path=/open/api/student/list |

---

## 二、安全与鉴权

### 2.1 请求头约定

| 请求头 | 必填 | 说明 |
|--------|------|------|
| X-App-Id | 是 | 应用编码（appCode） |
| X-Timestamp | 是 | 当前时间毫秒时间戳，防重放 |
| X-Sign | 是 | 签名，见 2.2 |

### 2.2 签名算法

1. 将请求参数（Query 与 Body，仅一层 key-value）按参数名 ASCII 升序排序。
2. 拼接为：`key1=value1&key2=value2&...&appSecret=应用密钥`（appSecret 为服务端存储的密钥）。
3. 对上述字符串做 **MD5**，结果转为 **大写**，即 X-Sign。

示例（GET，无 body）：

- 请求：GET /open/api/student/list?pageNum=1&pageSize=10  
- 假设 appSecret=abc123  
- 参数字符串：`pageNum=1&pageSize=10&appSecret=abc123`  
- sign = MD5(参数字符串).toUpperCase()

### 2.3 时间戳防重放

- 服务端收到 X-Timestamp 后，与当前服务器时间比较，若 |now - timestamp| > 5 分钟，返回 400「请求已过期」。

### 2.4 接口授权校验

- 请求 URI 取 path（如 `/open/api/student/list`），与当前应用在 pg_app_api + pg_api_dict 中关联的 api_path 集合比对；不在集合内则返回 403「无权访问该接口」。

---

## 三、接口设计

### 3.1 开放接口：学生列表

| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | /open/api/student/list |
| 鉴权 | 应用签名 + 接口授权 |
| 参数 | 与现有 /business/student/list 一致：studentName、studentNo、schoolId、schoolGradeId、schoolClassId、status 等；分页 pageNum、pageSize |
| 响应 | 与现有一致：`{ code, msg, rows, total }`（TableDataInfo） |

### 3.2 错误响应

| HTTP 状态 | 场景 | 示例 msg |
|-----------|------|----------|
| 400 | 缺少认证参数 / 时间戳格式错误 / 请求已过期 | 缺少认证参数 |
| 401 | 应用不存在 / 应用已停用 / 签名验证失败 | 签名验证失败 |
| 403 | 未授权该接口 | 无权访问该接口 |

---

## 四、数据与缓存

### 4.1 表使用

- **pg_application**：已有；需按 app_code 查询（selectByAppCode）。
- **pg_api_dict**：已有；需新增一条 api_path=`/open/api/student/list` 的记录，供授权勾选与校验。
- **pg_app_api**：已有；新增/编辑应用时按 apiCodes 写入/更新；鉴权时按 app_id 联表 pg_api_dict 得到 api_path 列表。

### 4.2 授权生效

- 方案 A：每次请求查库（或查缓存）。  
- 方案 B：应用授权变更时更新缓存，校验时先查缓存。  
本期可采用**不缓存**或**短 TTL（如 5 分钟）缓存**「应用授权 path 集合」，技术实现时在 Service 中按 appCode 查授权 path 列表即可；若后续性能有要求再加 Redis。

---

## 五、实现清单

### 5.1 配置

- **application.yml**：security.excludes 增加 `/open/api/**`。

### 5.2 应用模块（application）

- **IPgApplicationService**：新增 `PgApplication selectByAppCode(String appCode)`、`boolean checkApiPermission(String appCode, String apiPath)`。
- **PgApplicationServiceImpl**：实现上述方法；insert/update 时增加对 apiCodes 的处理，同步 pg_app_api（先删后插）。
- **PgApplication**：增加 `@TableField(exist = false) private List<String> apiCodes;`，用于接收前端与返回详情。
- **PgAppApiMapper**：新增方法，如 `List<String> selectApiPathsByAppCode(String appCode)`（联表 pg_api_dict 取 api_path）。
- **PgAppApiMapper.xml**：对应 SQL（a.app_id = app_id 且 a.api_id = d.api_id，d.api_path）。

### 5.3 开放 API 模块（新建或放在 business 下）

- **OpenApiConfig**：WebMvcConfigurer，注册 ApiAuthInterceptor，仅 addPathPatterns("/open/api/**")。
- **ApiAuthInterceptor**：preHandle 中取 X-App-Id、X-Timestamp、X-Sign；校验时间戳 → selectByAppCode → 校验签名 → checkApiPermission(uri) → 通过则 return true。
- **OpenApiStudentController**：GET `/open/api/student/list`，参数与 PgStudentController.list 一致，委托 IPgStudentService.selectPageList。

### 5.4 接口字典数据

- 在 pg_api_dict 中 INSERT 一条：api_code=OPEN_STUDENT_LIST，api_name=学生列表，api_path=/open/api/student/list，api_method=GET，status=0。可使用 SQL 脚本或启动时初始化。

### 5.5 前端

- 已有接口授权勾选（apiCodes）与 apiList 接口；只需保证后端保存/回显 apiCodes 与 pg_app_api 一致即可，无需改前端逻辑（若当前未回显 apiCodes，需后端在查询应用详情时填充 apiCodes）。

---

## 六、调用测试说明

- 提供「开放API-学生列表授权-调用测试说明.md」或同目录下测试脚本：
  - 签名算法说明与示例（含 GET 示例）。
  - 示例：在管理端创建应用并勾选「学生列表」，记录 appCode、appSecret，用 curl 或 Postman 调用 GET /open/api/student/list，携带正确 X-App-Id、X-Timestamp、X-Sign。
  - 预期：授权应用返回 200 与列表数据；未授权或错误签名返回 401/403。

---

## 七、评审要点

1. 开放路径仅限 `/open/api/**`，与现有 /business、/h5 隔离，且不校验用户登录。
2. 签名算法与请求头约定是否满足安全与对接方实现成本平衡。
3. 学生列表参数与响应与现有一致，避免业务逻辑重复。
4. 应用管理侧保存/回显接口授权与 pg_app_api、pg_api_dict 数据一致性。
5. 后续扩展其他开放接口时，仅需在 pg_api_dict 加记录、新增对应 OpenApiXxxController 即可，鉴权与拦截器复用。