# 课程资源分享（门户管理）API 文档（已拆分）

> 重要说明：为对齐“门户/管理”分层实践，本文档已拆分为两份更清晰的文档：
> - 门户端：docs/api/课程资源-门户.md
> - 管理端：docs/api/课程资源-管理.md
>
> 本文件暂时保留作为过渡与速查，内容以门户端为主。请优先参考上面两份文档。

## 概览
- 业务说明：面向登录用户的“我的资源”管理能力，支持新增、编辑、删除、提交上架（转待审）、下架。审核流（通过/驳回/最佳）仍在管理端进行。
- 角色权限：仅需登录（isAuthenticated）；写操作在服务层按“仅本人可操作”强约束。
- 依赖表：tb_course_resource、tb_course、tb_major、tb_course_resource_best（只读）
- baseURL：`http://localhost:8080`
- 认证：`Authorization: Bearer <token>`（登录后获取）

## 路由清单

### 我的资源列表
- 方法：GET
- 路径：/portal/resource/my/list
- 权限：登录
- 请求参数（query，可选）：
  - pageNum (int) 默认 1
  - pageSize (int) 默认 10
  - majorId (long) 过滤专业
  - courseId (long) 过滤课程
  - status (int) 过滤状态（0待审 1通过 2驳回 3下架）
  - resourceName (string) 模糊匹配名称
- 返回示例：
```json
{
  "code": 200,
  "msg": "操作成功",
  "rows": [{
    "id": 101,
    "majorId": 1,
    "courseId": 11,
    "resourceName": "数据结构复习资料",
    "resourceType": 0,
    "fileUrl": "https://...",
    "status": 0,
    "downloadCount": 0,
    "uploaderId": 1001,
    "uploaderName": "student",
    "majorName": "天佑学院",
    "courseName": "数据结构"
  }],
  "total": 1
}
```
- 常见错误码：
  - 401 未登录

### 新增资源（进入待审）
- 方法：POST
- 路径：/portal/resource
- 权限：登录
- 请求体（json）：
```json
{
  "majorId": 1,
  "courseId": 11,
  "resourceName": "数据结构复习资料",
  "resourceType": 0,
  "fileUrl": "https://...",    
  "fileHash": "<sha256|etag>",
  "fileSize": 1234567,
  "linkUrl": null,
  "description": "章节要点与期末整理"
}
```
- 返回示例：
```json
{ "code": 200, "msg": "操作成功", "data": { "id": 101 } }
```
- 备注：
  - 前置：请先获取有效的 `majorId` 与 `courseId`（可调用 `/portal/major/list` 与 `/portal/course/list` 获取）
  - resourceType=0（文件）时需提供 fileUrl/fileHash/fileSize；=1（外链）时需提供 linkUrl。
  - 上传文件推荐使用门户上传网关：POST /portal/upload/oss（scene=resource.archive）。
- 常见错误码：
  - 401 未登录
  - 500 参数校验或唯一约束失败（同课程相同文件哈希/外链 URL）

### 编辑资源（仅本人，编辑后回到待审）
- 方法：PUT
- 路径：/portal/resource
- 权限：登录
- 请求体（json）：
```json
{
  "id": 101,
  "resourceName": "数据结构复习资料-更新",
  "resourceType": 0,
  "fileUrl": "https://...",
  "fileHash": "<sha256|etag>",
  "fileSize": 2222,
  "linkUrl": null,
  "description": "补充历年题"
}
```
- 返回：`{ "code": 200 }`
- 常见错误码：
  - 401 未登录
  - 500 越权（非本人）或状态冲突（已通过需先下架）

### 删除资源（仅本人；待审/驳回/下架可删）
- 方法：DELETE
- 路径：/portal/resource/{id}
- 权限：登录
- 返回：`{ "code": 200 }`
- 常见错误码：
  - 401 未登录
  - 500 越权（非本人）或状态冲突（已通过不可删）

### 提交上架（转待审）
- 方法：PUT
- 路径：/portal/resource/{id}/online
- 权限：登录
- 返回：`{ "code": 200 }`
- 备注：仅本人可操作；已通过资源无需再次提交；驳回/下架转“待审”。
- 常见错误码：
  - 401 未登录
  - 500 越权（非本人）

### 下架资源（仅本人或有权者）
- 方法：PUT
- 路径：/portal/resource/{id}/offline
- 权限：登录
- 请求体（json，可选）：`{ "reason": "不再维护" }`
- 返回：`{ "code": 200 }`
- 常见错误码：
  - 401 未登录
  - 500 越权（非本人且非有权者）或状态冲突（非通过状态）

## 备注
- 分页与排序：沿用 RuoYi 通用分页（pageNum/pageSize），默认按“最佳优先、ID倒序”。
- 幂等与约束：
  - 新增对“同课程+文件哈希/外链 URL”有唯一约束，避免重复提交。
  - 编辑会将状态重置为“待审”。
- 错误码：当前服务使用 ServiceException 返回 500 + 明确错误信息用于提示用户。