Enhance API and error handling for video services

- Updated .gitignore to exclude cache files.
- Refactored main.go to streamline route registration and improve code organization.
- Added detailed comments in auth_handler.go, video_handler.go, and service files for better clarity on request handling and service logic.
- Improved error messages in video_handler.go to provide clearer feedback to users in Chinese.
- Introduced context handling in service methods to manage request timeouts effectively.

internal/service/mini_program_service.go

@@ -9,6 +9,8 @@ import (
 )
 
 type MiniProgramService struct {
+	// service 层负责“业务能力”，通常会依赖数据库/第三方客户端等基础设施。
+	// 这里通过结构体字段持有 db（依赖注入），而不是在方法里自己创建连接。
 	db *gorm.DB
 }
 
@@ -17,6 +19,7 @@ func NewMiniProgramService(db *gorm.DB) *MiniProgramService {
 }
 
 func (s *MiniProgramService) GetByID(ctx context.Context, id uint) (*model.MiniProgram, error) {
+	// WithContext(ctx) 能把请求的超时/取消信号传递给数据库层，避免慢请求一直挂着。
 	var mp model.MiniProgram
 	if err := s.db.WithContext(ctx).Where("id = ?", id).First(&mp).Error; err != nil {
 		return nil, err

internal/service/video_service.go

@@ -21,6 +21,7 @@ import (
 const removeWatermarkEndpoint = "https://api.23bt.cn/api/d1w/index"
 
 var (
+	// 从用户输入的文本里“抓取 URL”的简单正则（找到第一个 http/https 链接）
 	urlPattern            = regexp.MustCompile(`https?://[^\s]+`)
 	ErrURLNotFound        = errors.New("no valid url found in content")
 	ErrShortVideoAPIKey   = errors.New("short video api key is not configured")
@@ -28,12 +29,18 @@ var (
 )
 
 type VideoService struct {
+	// VideoService 封装“去水印”相关业务：
+	// - 限额（每天免费次数）
+	// - 调用第三方解析接口
+	// - 记录解析日志（便于排查问题/统计）
 	db     *gorm.DB
 	cfg    config.ShortVideoConfig
 	client *http.Client
 }
 
 type RemoveWatermarkResult struct {
+	// json.RawMessage 表示“原始 JSON 字节”，不强制把第三方返回结构定义成 Go struct。
+	// 对接不稳定/字段多的第三方接口时，这种做法更灵活。
 	Provider      string          `json:"provider"`
 	Raw           json.RawMessage `json:"raw"`
 	FreeQuotaUsed bool            `json:"free_quota_used"`
@@ -51,6 +58,7 @@ func (e *ThirdPartyError) Error() string {
 func NewVideoService(db *gorm.DB, cfg config.ShortVideoConfig) (*VideoService, error) {
 	timeout := cfg.RequestTimeout
 	if timeout <= 0 {
+		// 不配置就给一个默认超时，避免请求卡住占用 goroutine
 		timeout = 5 * time.Second
 	}
 
@@ -66,6 +74,11 @@ func NewVideoService(db *gorm.DB, cfg config.ShortVideoConfig) (*VideoService, e
 }
 
 func (s *VideoService) RemoveWatermark(ctx context.Context, user *model.User, content string) (*RemoveWatermarkResult, error) {
+	// RemoveWatermark 的整体流程：
+	// 1) 从 content 里提取链接
+	// 2) 检查每日免费额度（或是否已解锁）
+	// 3) 调用第三方接口解析
+	// 4) 写入解析日志（无论成功/失败都记一条，方便定位问题）
 	link, err := extractFirstURL(content)
 	if err != nil {
 		return nil, ErrURLNotFound
@@ -118,6 +131,7 @@ func (s *VideoService) RemoveWatermark(ctx context.Context, user *model.User, co
 }
 
 func (s *VideoService) UnlockForToday(ctx context.Context, user *model.User) error {
+	// “看广告解锁”的实现方式：在当天写一条 unlock 记录即可（存在则更新时间戳）
 	startOfDay, _ := dayRange(time.Now())
 
 	var unlock model.VideoParseUnlock
@@ -145,6 +159,9 @@ func (s *VideoService) UnlockForToday(ctx context.Context, user *model.User) err
 }
 
 func (s *VideoService) ensureQuota(ctx context.Context, user *model.User) (bool, error) {
+	// ensureQuota 返回值 freeQuotaUsed 的含义：
+	// - true：这次调用会消耗一次“免费额度”
+	// - false：不消耗（例如今日已解锁或未启用限额）
 	if s.cfg.FreeDailyQuota <= 0 {
 		return false, nil
 	}
@@ -208,6 +225,7 @@ func (s *VideoService) callThirdParty(ctx context.Context, link string) (int, []
 }
 
 func extractFirstURL(content string) (string, error) {
+	// 从文本里提取第一个 URL，并做简单 trim，把末尾可能粘上的标点去掉。
 	if content == "" {
 		return "", ErrURLNotFound
 	}
@@ -219,6 +237,8 @@ func extractFirstURL(content string) (string, error) {
 }
 
 func dayRange(ts time.Time) (time.Time, time.Time) {
+	// 计算“当天的起止时间”：[00:00, 次日00:00)
+	// 用本地时区 loc，避免跨时区导致的日期偏移。
 	loc := ts.Location()
 	start := time.Date(ts.Year(), ts.Month(), ts.Day(), 0, 0, 0, 0, loc)
 	end := start.Add(24 * time.Hour)
@@ -226,6 +246,7 @@ func dayRange(ts time.Time) (time.Time, time.Time) {
 }
 
 func truncateString(input string, max int) string {
+	// 截断字符串，避免把第三方错误响应原样写入导致日志过大
 	if len(input) <= max {
 		return input
 	}