add auth check

server/features.md

@@ -17,10 +17,38 @@
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
 | `POST` | `/` | 主业务 API |
+| `POST` | `/device` | ReinLoop 设备侧 API（license -> deviceToken） |
 | `POST` | `/upload/:token` | 根据上传凭证接收 multipart 文件 |
-| `GET` | `/files/:fileID` | 下载已存储文件 |
+| `GET` | `/downloads/:ticket` | 使用一次性临时下载票据获取文件 |
+| `GET` | `/files/:fileID` | 旧直链下载入口（已停用，固定返回 403） |
 | `GET` | `/health` | 服务存活检查 |
 
+## 设备侧鉴权与分路由
+
+`/device` 仅用于 ReinLoop 客户端，禁止使用 `adminToken`。
+
+调用方式：
+
+1. 先 `POST /device`，`type=deviceAuth`，字段 `licenseId`、`deviceId`。
+2. 服务端校验许可证状态（存在、未过期、未撤销、deviceId 匹配）后签发 `deviceToken`。
+3. ReinLoop 后续调用 `/device` 白名单接口时携带 `deviceToken`。
+
+`deviceToken` 默认有效期由 `DEVICE_TOKEN_TTL_MS` 控制（默认 15 分钟）。
+
+离线宽限由 ReinLoop 客户端控制，当前默认 `REINLOOP_LICENSE_OFFLINE_HOURS=100`（100 小时）。
+
+## 下载安全调用链
+
+统一链路为：业务 `POST /`（鉴权） -> 返回临时 URL -> `GET /downloads/:ticket`（一次性消费）。
+
+安全校验点：
+
+- `POST /`：按业务类型执行权限校验。
+- `GET /downloads/:ticket`：
+	- 票据存在且未过期（`DOWNLOAD_URL_TTL_MS`，兼容旧环境变量 `DOWNLOAD_TOKEN_TTL_MS`）。
+	- 票据仅可消费一次，成功下载或校验失败后均失效。
+	- 下载请求来源 IP 必须与签发票据的 `POST` 请求来源 IP 一致。
+
 ## 设备心跳与组织
 
 | type | 鉴权 | 请求字段 | 功能与响应要点 |
@@ -51,13 +79,19 @@ Panel 应每 10 秒调用 `listOrganizations` 刷新在线状态，不应自行
 | `uploadDataFile` | 视目录而定 | `fileName`、`folder` | 签发通用两步上传凭证。目录为 `*/model_config` 时必须 Admin；其他既有 ReinLoop 数据上传保持兼容。 |
 | `issueModelUpload` | Admin | `deviceId`、`fileName`、可选 `modelName`、`overwrite` | `fileName` 是本地原始文件名；传入 `modelName` 时以该名称存储和识别模型，并保留 `originalFileName`。同名模型已存在时返回 `conflict: true`；仅 `overwrite: true` 可签发覆盖凭证。 |
 | `listModels` | 无 | `folder` | 返回 `files` 当前模型名数组和 `fileList` 元数据数组，最多 100 条；每条同时包含 `fileName` 和 `originalFileName`。 |
-| `downloadModel` | 视文件而定 | `fileID` | 模型保持兼容；非模型文件要求 Admin 并返回短期签名下载 URL。 |
+| `downloadModel` | Admin | `fileID` | 返回一次性临时下载 URL（`/downloads/:ticket`）。 |
 | `deleteFile` | Admin | `fileID`，或 `folder` 与 `fileName` | 删除文件及元数据；同名文件不唯一时必须使用 `fileID`。 |
 | `deleteModel` | Admin | 同 `deleteFile` | 模型删除的明确管理端别名。 |
 
 上传分两步：先调用 `uploadDataFile` 或 `issueModelUpload`，再将文件作为 `multipart/form-data` 的 `file` 字段提交到响应中的 `uploadMetadata.url`。上传成功返回 HTTP `204`；响应中的 `fileID` 可用于下载和删除。
 模型重命名不会修改文件格式，因此 `modelName` 与原始 `fileName` 的扩展名必须一致。未传 `modelName` 时两者相同，旧客户端行为不变。
 
+设备侧（`/device`）模型访问约束：
+
+- `listModels` 固定返回当前 `deviceId/model_config` 目录。
+- `downloadModel` 仅允许下载当前 `deviceId/model_config` 下文件。
+- 设备侧不允许模型上传与删除。
+
 上传到 `<deviceId>/ind_data` 的 `.csv`、`.json` 会自动进入 Panel inbox。
 
 ## 配置发布与读取
@@ -67,7 +101,7 @@ Panel 应每 10 秒调用 `listOrganizations` 刷新在线状态，不应自行
 | `publishIdentificationConfig` | Admin | `deviceId`、`parameters` | 校验辨识参数并为 `<deviceId>/identification_config/identification_config.csv` 签发上传凭证。 |
 | `getIdentificationConfig` | 无 | `deviceId` | 返回该设备辨识 CSV 的 `fileID` 和 `url`。 |
 | `publishVolumeConfig` | Admin | `parameters` | 校验容积参数并签发 `volume_config.json` 上传凭证。上传完成后更新功能参数记录。 |
-| `getVolumeConfigFile` | 无 | 无 | 返回已发布容积 JSON 的 `fileID`、`cloudPath`、`url`。 |
+| `getVolumeConfigFile` | Admin | `deviceId` | 返回指定设备已发布容积 JSON 的 `fileID`、`cloudPath`、`url`。 |
 | `getFunctionConfig` | 无 | `configType: "volume"` | 返回已发布容积参数的 `parameters`、`version`、`updateTime`。 |
 
 发布接口仅签发上传凭证；客户端完成二步上传后，读取接口才会返回新文件或参数。
@@ -83,7 +117,7 @@ Panel 应每 10 秒调用 `listOrganizations` 刷新在线状态，不应自行
 | `getPendingPanelFile` | Admin | `deviceId` | 获取指定设备下一条待处理 CSV/JSON；无数据时 `pending: false`，有数据时返回文件信息和 `url`。 |
 | `ackPanelFile` | Admin | `deviceId`、`fileID` | Panel 处理完成后确认，移除 inbox 项并标记历史记录为 `processed`，不立即删除文件。 |
 | `listIdentificationFiles` | Admin | `deviceId`、可选 `mediaType`、`status`、`page`、`pageSize` | 分页返回设备的辨识 CSV/JSON 暂存历史。 |
-| `getIdentificationFileDownload` | Admin | `fileID` | 返回原始辨识文件的短期签名下载 URL。 |
+| `getIdentificationFileDownload` | Admin | `fileID` | 返回原始辨识文件的一次性临时下载 URL。 |
 | `deleteIdentificationFile` | Admin | `fileID` | 显式删除辨识文件、历史记录及待处理消息。 |
 
 CSV 辨识文件须先以同名 `runId` 调用 `registerIdentificationResult`，才会出现在 `getPendingPanelFile`；初始行程 JSON 可直接获取。
@@ -97,7 +131,7 @@ CSV 辨识文件须先以同名 `runId` 调用 `registerIdentificationResult`，
 | `createVolumeConfigRequest` | 无 | `deviceId` | ReinLoop 创建一次性上传请求，返回 `requestId`、`createdAtMs`、`expiresAtMs`。同设备旧请求会被替换。 |
 | `getPendingVolumeConfigRequest` | 无 | `deviceId` | 查询是否存在待上传请求，返回 `pending` 和请求时间信息。 |
 | `submitVolumeConfigFile` | 无 | `deviceId`、`requestId`、`fileID`、可选 `fileName` | 将已上传到 `<deviceId>/volume_config_requests/<requestId>/` 的文件绑定至请求。 |
-| `getVolumeConfigRequest` | 无 | `deviceId`、`requestId` | 轮询配置是否就绪，返回 `ready`、`expired`；就绪时包含下载 `url`。 |
+| `getVolumeConfigRequest` | 无 | `deviceId`、`requestId` | 轮询配置是否就绪，返回 `ready`、`expired`；就绪时包含一次性临时下载 `url`。 |
 | `ackVolumeConfigRequest` | 无 | `deviceId`、`requestId` | ReinLoop 下载完成后确认，清理请求及关联文件。 |
 
 请求有效期由 `VOLUME_REQUEST_TTL_MS` 控制，默认 300000 毫秒（5 分钟）。