# oapi 课表查询接口 · 调用手册

> 服务：AcaSyllabu（课程表）　接口：`GET /oapi/timetable/Get`　更新：2026-10-13

按「用户 + 角色 + 学校」查询其可见范围内所有班级的当前学年学期课程表。身份由调用方显式传入（不依赖浏览器登录态），适用于平台内其他应用（首页卡片、移动端、大屏等）服务端直调。

| 调用方身份 | 可见班级 | 可见科目 |
|---|---|---|
| 管理员（roleId=7）/ 校领导（roleId=2） | 全部班级 | 全部科目 |
| 班主任 | 所带班级（正/副班主任） | 全部科目 |
| 任教老师（roleId=1） | 任教班级 | 仅任教科目（其余科目格清空返回） |
| 学生（roleId=3） | 本人所在班级 | 全部科目 |

- `roleId` 不传时**默认按普通教师（1）**处理。
- 一个用户兼任多重身份（如既是班主任又任教其他班）时，取并集：班主任班给全部科目，任教班只给任教科目。
- 无任何可见范围（如普通教师没有任教记录）时返回空数组 `data: []`，不报错。

---

## 1. 请求

```
GET {base}/oapi/timetable/Get?userid={userId}&roleId={roleId}&schId={schId}
```

- 本地联调：`http://localhost:8109`（无 context-path）
- 生产：`http://{host}/acasyllabu`（context-path `/acasyllabu`，以网关实际地址为准）

| 参数 | 必填 | 说明 |
|---|---|---|
| `userid` | 是 | 平台用户ID。教师=教师ID；学生=学生树里的学生节点ID |
| `roleId` | 否 | 角色：1 教师（默认）、2 校领导、3 学生、7 管理员 |
| `schId` | 是 | 学校ID（数据严格限定在该校范围内） |

## 2. 签名鉴权（必须）

接口在 `/oapi/*` 强制验签下：浏览器/匿名直访一律 **401**，只有注册应用带上签名三件套才能通过。

### 2.1 请求头

| Header | 说明 |
|---|---|
| `X-App-Key` | 调用方应用ID（在服务方 `trusted-apps` 白名单登记的 appKey） |
| `X-Timestamp` | 当前毫秒时间戳。**有效期默认 5 分钟**，过期拒绝，请用当前时间 |
| `X-Signature` | 签名，算法见下 |

### 2.2 签名算法

```
待签串  = 请求方法 + "\n" + target + "\n" + X-Timestamp
target  = 请求路径 + "?" + 查询参数（按参数名字典序排列后的 k=v&k=v）
签名    = Base64( HmacSHA256( 待签串, appSecret ) )
```

要点：
- 方法用大写 `GET`；分隔符是换行 `\n`，共两处；
- query 参数**按参数名排序**后再拼（如 `roleId` 在 `schId` 在 `userid` 前），排序后**原样拼接、不做 URL 编码**；
- 密钥即服务方 `trusted-apps` 里登记的该 appKey 对应 secret（找 AcaSyllabu 管理员索取）。

### 2.3 接入新调用方

服务方在 `application.yml`（生产为 Nacos `acasyllabu.yaml`）的 `yh.app-auth.trusted-apps` 下追加一行：

```yaml
yh:
  app-auth:
    trusted-apps:
      "100021": "d3ee380e..."   # 既有
      "100xxx": "新调用方密钥"    # 新增
```

> 生产环境接了中央密钥链（Redis 注册表）后可改走 `trust-registry`，届时以平台注册为准，无需手工维护白名单。

## 3. 响应

外层为平台统一包装：

```json
{ "code": 0, "msg": "", "data": [ …班级数组… ] }
```

`data` 数组每项：

| 字段 | 说明 |
|---|---|
| `classId` / `className` / `gradeName` | 班级ID / 班级名 / 年级名 |
| `headTeacher` | 该用户在本班是否班主任 |
| `viewAllSubjects` | 是否全部科目可见（班主任/管理员/校领导/学生=true，仅任教=false） |
| `subjects` | 任教科目列表（仅 viewAllSubjects=false 时非空） |
| `timetable` | 该班课表，结构同 `TimetableVo`（见下） |

`timetable`：

| 字段 | 说明 |
|---|---|
| `year` / `term` | 课表所属学年学期（term：1 上学期 2 下学期） |
| `photoFileId` / `photoName` / `photoSize` | 照片课表附件（未上传为 null） |
| `slots[]` | 节次数组；`slotNo` 从 1 起，`start`/`end` 为 HH:mm |
| `slots[].subjects` | 固定 7 位，下标 0~6 = 周一~周日，空串=未排课 |

示例（节选）：

```json
{
  "code": 0, "msg": "",
  "data": [
    {
      "classId": 371, "className": "2班", "gradeName": "高一",
      "headTeacher": false, "viewAllSubjects": false,
      "subjects": ["语文"],
      "timetable": {
        "classId": 371, "year": 2026, "term": 1,
        "className": "2班", "gradeName": "高一",
        "photoFileId": null, "photoName": null, "photoSize": null,
        "slots": [
          { "slotNo": 1, "start": "08:20", "end": "09:00",
            "subjects": ["语文", "", "", "", "", "", ""] }
        ],
        "viewAllSubjects": false, "mySubjects": ["语文"]
      }
    }
  ]
}
```

## 4. 错误情况

| 现象 | 原因 |
|---|---|
| HTTP 401 `missing app signature` | 未带签名三件套 |
| HTTP 401 `invalid signature or expired` | 密钥错误、待签串拼错或时间戳超过 5 分钟 |
| HTTP 401 `unknown appKey` | appKey 未在服务方 `trusted-apps` 登记 |
| HTTP 200 `{"code":6,"msg":"内部服务错误"}` | 缺 `userid`/`schId` 等必填参数 |
| HTTP 200 `code=0, data=[]` | 该身份在该校无可见班级（如无任教记录的教师） |

## 5. 调用示例

### 5.1 Node.js（可直接运行）

```js
const crypto = require('crypto');

const BASE = 'http://localhost:8109';
const APP_KEY = '100xxx';
const APP_SECRET = '你的密钥';

function get(pathAndQuery) {
  const q = pathAndQuery.indexOf('?');
  const path = q < 0 ? pathAndQuery : pathAndQuery.substring(0, q);
  const pairs = q < 0 ? [] : pathAndQuery.substring(q + 1).split('&').sort();
  const target = path + (pairs.length ? '?' + pairs.join('&') : '');
  const ts = String(Date.now());
  const sign = crypto.createHmac('sha256', APP_SECRET)
    .update(`GET\n${target}\n${ts}`)
    .digest('base64');
  return fetch(BASE + pathAndQuery, {
    headers: { 'X-App-Key': APP_KEY, 'X-Timestamp': ts, 'X-Signature': sign },
  }).then(r => r.json());
}

// 管理员查全校
get('/oapi/timetable/Get?userid=1&roleId=7&schId=3').then(console.log);
```

### 5.2 Java（平台内服务，有 yh-utils-core 依赖）

```java
String pathAndQuery = "/oapi/timetable/Get?userid=1&roleId=7&schId=3";
// query 按参数名排序后拼回
String target = "/oapi/timetable/Get?roleId=7&schId=3&userid=1";
String ts = String.valueOf(System.currentTimeMillis());
String sign = SignUtil.signRequest("GET", target, ts, appSecret); // 平台工具，同款算法

HttpHeaders headers = new HttpHeaders();
headers.set("X-App-Key", appKey);
headers.set("X-Timestamp", ts);
headers.set("X-Signature", sign);
restTemplate.exchange(baseUrl + pathAndQuery, HttpMethod.GET, new HttpEntity<>(headers), String.class);
```

> 平台 Feign 客户端加 `SignFeignInterceptor` 可自动签名，无需手工拼。

### 5.3 curl（Git Bash，签名用 openssl 生成）

```bash
SECRET="你的密钥"
TARGET="/oapi/timetable/Get?roleId=7&schId=3&userid=1"   # 参数已按名排序
TS=$(date +%s000)
SIGN=$(printf "GET\n%b\n%b" "$TARGET" "$TS" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)

curl -s "http://localhost:8109$TARGET" \
  -H "X-App-Key: 100xxx" -H "X-Timestamp: $TS" -H "X-Signature: $SIGN"
```

> 注意 curl 的 URL 必须与参与签名的 target 完全一致（含参数顺序）。

## 6. 本地联调

- 服务方后端：8109 端口（devtools 热重启）；本地验签白名单只收了本应用 `100021`（application.yml `trusted-apps`）。
- 现成冒烟脚本：`E:\YHXT\java\gui-test-screenshots\oapi-sign-smoke.js`（用法 `node oapi-sign-smoke.js "/oapi/timetable/Get?userid=1&roleId=7&schId=3"`，密钥内置 100021）。
- 真实数据参考（schId=3）：管理员 userid=1 返回全部班级；教师 10008 = 班主任(1班 全部科目) + 任教(2班 仅语文)；学生 10066 = 仅 1 班。