feat: 添加用户端链接状态查询接口及自动刷新逻辑
主要修改: 1. 在LinkController中新增获取用户链接状态的接口，支持通过linkId或codeNo查询。 2. 在LinkStatusService中实现用户链接状态查询逻辑，包含自动刷新和二维码更新功能。 3. 更新LinkTask实体，添加needRefresh、refreshTime、qrCreatedAt和qrExpireAt字段以支持新功能。 4. 在ScriptClient中新增检查空闲设备、选区、刷新、检查上号状态等操作的实现。 5. 更新SecurityConfig，允许用户端获取链接状态接口公开访问。 技术细节: - 新增UserLinkStatusResponse DTO以支持用户链接状态的返回格式。 - 通过脚本端接口实现链接状态的自动刷新和二维码信息更新。
This commit is contained in:
zyh
128
docs/终端用户接口文档.md
Normal file
128
docs/终端用户接口文档.md
Normal file
@@ -0,0 +1,128 @@
|
||||
根据需求文档分析，我理解的后端需要实现以下接口和业务逻辑：
|
||||
|
||||
## 后端接口设计文档
|
||||
|
||||
### 1. 获取链接状态接口
|
||||
|
||||
**接口：** `GET /api/link/status?code={code}`
|
||||
|
||||
**业务逻辑：**
|
||||
1. 解密和验证code参数（包含linkId、签发时间、过期时间等）
|
||||
2. 检查链接是否过期（默认24小时）
|
||||
3. 从数据库查询链接当前状态
|
||||
4. 如果状态为USING，检查二维码是否仍有效
|
||||
5. 返回链接状态和相关信息
|
||||
|
||||
**需要的数据表字段：**
|
||||
```sql
|
||||
link_task表需要字段：
|
||||
- id (链接ID)
|
||||
- code_no (编号，全局唯一)
|
||||
- status (状态: NEW/USING/LOGGED_IN/REFUNDED/EXPIRED)
|
||||
- region (选择的区域: Q/V/null)
|
||||
- need_refresh (是否需要刷新)
|
||||
- refresh_time (刷新时间，用于10秒等待逻辑)
|
||||
- qr_created_at (二维码创建时间)
|
||||
- qr_expire_at (二维码过期时间)
|
||||
- created_at (链接创建时间)
|
||||
- expire_at (链接过期时间，默认24小时)
|
||||
- times (次数)
|
||||
- quantity (数量)
|
||||
```
|
||||
|
||||
### 2. 选区接口
|
||||
|
||||
**接口：** `POST /api/link/select-region`
|
||||
**请求体：** `{ code: string, region: "Q" | "V" }`
|
||||
|
||||
**业务逻辑：**
|
||||
1. 验证code和region参数
|
||||
2. 检查链接状态，只有NEW状态才能选区
|
||||
3. 如果need_refresh=true，检查是否已等待10秒
|
||||
4. 调用脚本端分配空闲设备： `GET http://36.138.184.60:1234/yijianwan_netfile/readAllMsg?文件名=判断分数`
|
||||
5. 调用脚本端选区： `POST http://36.138.184.60:1234/yijianwan_netfile/saveMsg?文件名=判断系统&编号={region}`
|
||||
6. 等待脚本端生成二维码（轮询检查二维码文件是否存在）
|
||||
7. 更新数据库状态为USING，记录二维码创建和过期时间
|
||||
8. 返回二维码信息
|
||||
|
||||
**数据库操作：**
|
||||
- 更新link_task状态为USING
|
||||
- 记录region、qr_created_at、qr_expire_at
|
||||
- 设置need_refresh=false
|
||||
|
||||
### 3. 刷新接口
|
||||
|
||||
**接口：** `POST /api/link/refresh`
|
||||
**请求体：** `{ code: string }`
|
||||
|
||||
**业务逻辑：**
|
||||
1. 验证code参数
|
||||
2. 调用脚本端刷新： `POST http://36.138.184.60:1234/yijianwan_netfile/saveMsg?文件名=判断刷新&编号=刷新`
|
||||
3. 设置need_refresh=true，记录refresh_time
|
||||
4. 返回等待时间（默认10秒）
|
||||
|
||||
**数据库操作：**
|
||||
- 设置need_refresh=true
|
||||
- 记录refresh_time为当前时间
|
||||
|
||||
### 4. 轮询上号接口
|
||||
|
||||
**接口：** `GET /api/link/poll-login?code={code}`
|
||||
|
||||
**业务逻辑：**
|
||||
1. 验证code参数
|
||||
2. 检查链接状态，只有USING状态才能轮询
|
||||
3. 调用脚本端检查上号状态： `GET http://36.138.184.60:1234/yijianwan_netfile/readMsg?文件名=判断上号&对象名={code_no}`
|
||||
4. 如果返回"已上号"，更新状态为LOGGED_IN
|
||||
5. 返回上号结果和资源信息
|
||||
|
||||
**数据库操作：**
|
||||
- 如果已上号，更新status为LOGGED_IN
|
||||
|
||||
### 5. 二维码代理接口（可选）
|
||||
|
||||
**接口：** `GET /api/link/qr.png?code={code}`
|
||||
|
||||
**业务逻辑：**
|
||||
1. 验证code参数
|
||||
2. 获取对应的编号
|
||||
3. 代理请求： `http://36.138.184.60:12345/{编号}/二维码.png`
|
||||
4. 返回图片数据
|
||||
|
||||
### 6. 脚本端适配服务类
|
||||
|
||||
需要创建ScriptClient服务来封装与脚本端的交互：
|
||||
|
||||
**方法包括：**
|
||||
- `checkAvailableDevice()` - 检查空闲设备
|
||||
- `selectRegion(codeNo, region)` - 选区
|
||||
- `refresh(codeNo)` - 刷新
|
||||
- `checkLoginStatus(codeNo)` - 检查上号状态
|
||||
- `getQrCodeUrl(codeNo)` - 获取二维码URL
|
||||
- `getTargetScore(codeNo)` - 获取目标分数
|
||||
|
||||
### 7. 需要的配置项
|
||||
|
||||
在system_config表中需要配置：
|
||||
- `qr_expire_seconds` - 二维码有效期（默认60秒）
|
||||
- `refresh_wait_seconds` - 刷新等待时间（默认10秒）
|
||||
- `link_expire_hours` - 链接有效期（默认24小时）
|
||||
|
||||
### 8. 错误处理
|
||||
|
||||
- 401/403：链接无效或已篡改
|
||||
- 410：链接已过期
|
||||
- 423：需要刷新等待
|
||||
- 504：脚本端超时
|
||||
|
||||
### 9. 日志记录
|
||||
|
||||
需要记录的操作日志：
|
||||
- 链接访问
|
||||
- 选区操作
|
||||
- 二维码生成
|
||||
- 上号结果
|
||||
- 刷新操作
|
||||
- 错误信息
|
||||
|
||||
这个接口设计是否符合你的理解？有什么需要调整的地方吗？确认无误后我就开始实现代码。
|
||||
Reference in New Issue
Block a user