feat: swag.

controllers/lesson_plan.go

@@ -53,6 +53,18 @@ func NewLessonPlanController() *LessonPlanController {
 	return &LessonPlanController{DB: config.DB}
 }
 
+// @Summary 上传教案文件
+// @Description 上传 .docx 格式的教案文件，支持MD5去重，最大10MB
+// @Tags 教案管理
+// @Accept multipart/form-data
+// @Produce json
+// @Param file formData file true "教案文件(.docx)"
+// @Security BearerAuth
+// @Success 201 {object} SwagAPIResponse "上传成功"
+// @Failure 400 {object} SwagAPIResponse "请求参数错误"
+// @Failure 401 {object} SwagAPIResponse "未认证"
+// @Failure 409 {object} SwagAPIResponse "文件已存在"
+// @Router /lesson-plans/upload [post]
 func (lc *LessonPlanController) Upload(c *gin.Context) {
 	fileHeader, err := c.FormFile(lessonPlanFieldName)
 	if err != nil {
@@ -152,6 +164,14 @@ func (lc *LessonPlanController) Upload(c *gin.Context) {
 	writeSuccess(c, http.StatusCreated, "upload success", record)
 }
 
+// @Summary 获取教案列表
+// @Description 获取教案文件列表（非分页），按创建时间倒序
+// @Tags 教案管理
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Failure 401 {object} SwagAPIResponse "未认证"
+// @Router /lesson-plans [get]
 func (lc *LessonPlanController) List(c *gin.Context) {
 	userID, _, ok := currentUser(c)
 	if !ok {
@@ -173,6 +193,22 @@ func (lc *LessonPlanController) List(c *gin.Context) {
 	writeSuccess(c, http.StatusOK, "query success", records)
 }
 
+// @Summary 分页查询教案
+// @Description 分页获取教案文件列表，支持文件名模糊搜索、上传者搜索、区域筛选、排序
+// @Tags 教案管理
+// @Produce json
+// @Param pageNum query int false "页码(默认1)"
+// @Param pageSize query int false "每页数量(默认10,最大100)"
+// @Param keyword query string false "文件名模糊搜索"
+// @Param uploaderName query string false "上传者名模糊搜索"
+// @Param regionId query int false "区域ID"
+// @Param sortBy query string false "排序字段: file_size | created_at"
+// @Param sortOrder query string false "排序方向: asc | desc"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Failure 400 {object} SwagAPIResponse "请求参数错误"
+// @Failure 401 {object} SwagAPIResponse "未认证"
+// @Router /lesson-plans/page [get]
 func (lc *LessonPlanController) Page(c *gin.Context) {
 	userID, _, ok := currentUser(c)
 	if !ok {
@@ -312,6 +348,17 @@ func (lc *LessonPlanController) Page(c *gin.Context) {
 	})
 }
 
+// @Summary 下载教案文件
+// @Description 通过ID下载教案文件，自动更新下载计数和最后下载时间
+// @Tags 教案管理
+// @Produce application/octet-stream
+// @Param id path int true "教案ID"
+// @Security BearerAuth
+// @Success 200 {file} binary "教案文件"
+// @Failure 401 {object} SwagAPIResponse "未认证"
+// @Failure 403 {object} SwagAPIResponse "无权限"
+// @Failure 404 {object} SwagAPIResponse "文件不存在"
+// @Router /lesson-plans/{id}/download [get]
 func (lc *LessonPlanController) Download(c *gin.Context) {
 	record, err := lc.findLessonPlan(c.Param("id"))
 	if err != nil {
@@ -344,6 +391,17 @@ func (lc *LessonPlanController) Download(c *gin.Context) {
 	c.FileAttachment(record.FilePath, record.OriginalFilename)
 }
 
+// @Summary 生成分享码
+// @Description 为教案文件生成6位数字分享码，有效期5分钟，每次生成会失效之前的分享码
+// @Tags 教案管理
+// @Produce json
+// @Param id path int true "教案ID"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "生成成功"
+// @Failure 401 {object} SwagAPIResponse "未认证"
+// @Failure 403 {object} SwagAPIResponse "无权限"
+// @Failure 404 {object} SwagAPIResponse "文件不存在"
+// @Router /lesson-plans/{id}/share-code [post]
 func (lc *LessonPlanController) GenerateShareCode(c *gin.Context) {
 	record, err := lc.findLessonPlan(c.Param("id"))
 	if err != nil {
@@ -399,6 +457,15 @@ func (lc *LessonPlanController) GenerateShareCode(c *gin.Context) {
 	})
 }
 
+// @Summary 通过分享码下载教案
+// @Description 通过6位分享码下载教案文件（无需认证）
+// @Tags 教案管理
+// @Produce application/octet-stream
+// @Param code path string true "6位分享码"
+// @Success 200 {file} binary "教案文件"
+// @Failure 400 {object} SwagAPIResponse "分享码无效"
+// @Failure 404 {object} SwagAPIResponse "分享码过期或不存在"
+// @Router /lesson-plans/share/{code}/download [get]
 func (lc *LessonPlanController) DownloadByShareCode(c *gin.Context) {
 	shareCode := strings.TrimSpace(c.Param("code"))
 	if len(shareCode) != shareCodeDigits {
@@ -439,6 +506,17 @@ func (lc *LessonPlanController) DownloadByShareCode(c *gin.Context) {
 	c.FileAttachment(record.FilePath, record.OriginalFilename)
 }
 
+// @Summary 删除教案文件
+// @Description 删除教案文件及其关联的分享码
+// @Tags 教案管理
+// @Produce json
+// @Param id path int true "教案ID"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "删除成功"
+// @Failure 401 {object} SwagAPIResponse "未认证"
+// @Failure 403 {object} SwagAPIResponse "无权限"
+// @Failure 404 {object} SwagAPIResponse "文件不存在"
+// @Router /lesson-plans/{id} [delete]
 func (lc *LessonPlanController) Delete(c *gin.Context) {
 	record, err := lc.findLessonPlan(c.Param("id"))
 	if err != nil {