分享模块实现教程

// CreateShare 创建分享链接或提取码分享（修正点：补归属校验/类型校验/过期校验/失败即报错）
func (uc *ShareUsecase) CreateShare(ctx context.Context, userID uint64, itemType, itemID uint64, shareType, password string, expireAt *time.Time) (*Share, string, error) {
    // 修正点：校验分享类型与资源类型合法，拒绝脏输入
    if shareType != "link" && shareType != "code" {
        return nil, "", errors.BadRequest("SHARE_TYPE_INVALID", "分享类型仅支持 link/code")
    }
    if itemType != "file" && itemType != "folder" {
        return nil, "", errors.BadRequest("ITEM_TYPE_INVALID", "资源类型仅支持 file/folder")
    }

    // 修正点：校验资源归属，禁止分享他人文件（防越权）
    if itemType == "file" {
        f, err := uc.fileRepo.FindByID(ctx, itemID)
        if err != nil {
            return nil, "", ErrFileNotFound
        }
        if f.UserID != userID { // 不是自己的文件
            return nil, "", ErrForbidden
        }
        if f.Status != 0 { // 已移回收站/已删除的文件不可分享
            return nil, "", ErrFileNotFound
        }
    } else {
        folder, err := uc.folderRepo.FindByID(ctx, itemID)
        if err != nil {
            return nil, "", ErrFolderNotFound
        }
        if folder.UserID != userID {
            return nil, "", ErrForbidden
        }
    }

    // 修正点：过期时间不能早于当前，拒绝"创建即过期"
    if expireAt != nil && expireAt.Before(time.Now()) {
        return nil, "", ErrShareExpired
    }

    uuid, err := newUUID()
    if err != nil {
        return nil, "", err
    }

    shareCode := ""
    if shareType == "code" {
        // 修正点：生成失败直接返回错误，不再降级为可预测时间戳
        shareCode, err = generateShareCode()
        if err != nil {
            return nil, "", err
        }
    }

    hashedPassword := ""
    if password != "" {
        // 修正点：哈希失败直接返回错误，绝不让分享带着明文/伪哈希创建
        hashedPassword, err = hashPassword(password)
        if err != nil {
            return nil, "", err
        }
    }

    share := &Share{
        UUID: uuid, UserID: userID, ItemType: itemType, ItemID: itemID,
        ShareType: shareType, ShareCode: shareCode, Password: hashedPassword,
        ExpireAt: expireAt, Status: 1,
    }
    created, err := uc.shareRepo.Create(ctx, share)
    if err != nil {
        return nil, "", err
    }
    if uc.eventPublisher != nil {
        _ = uc.eventPublisher.Publish(ctx, EventShareCreated, &SharePayload{
            UserID: userID, ShareID: created.ID, UUID: created.UUID, Action: "created",
        })
    }
    url := fmt.Sprintf("/share/%s", uuid)
    if shareCode != "" {
        url += "?code=" + shareCode
    }
    return created, url, nil
}

// generateShareCode 生成提取码（修正点：8 字节≈2^64 熵，失败即报错不兜底）
func generateShareCode() (string, error) {
    b := make([]byte, 8) // 修正点：从 4 字节提到 8 字节，字符集为 16 位十六进制
    if _, err := rand.Read(b); err != nil {
        return "", err // 修正点：crypto/rand 失败直接报错，不降级为可预测时间戳
    }
    return hex.EncodeToString(b), nil
}

// hashPassword 使用 bcrypt 对密码进行哈希（修正点：返回 error，失败不存明文）
func hashPassword(password string) (string, error) {
    hashed, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
    if err != nil {
        return "", err // 修正点：哈希失败直接失败，不让分享创建
    }
    return string(hashed), nil
}

// checkPassword 校验密码（保留历史明文兼容，但建议访问时迁移为 bcrypt）
func checkPassword(hashed, password string) bool {
    if len(hashed) == 0 {
        return false
    }
    if len(hashed) < 10 || hashed[0] != '$' {
        return hashed == password // 历史明文兼容分支（应逐步迁移）
    }
    return bcrypt.CompareHashAndPassword([]byte(hashed), []byte(password)) == nil
}

// signShareToken 生成短期分享访问令牌：HMAC-SHA256(uuid.exp)+签名，Base64URL 编码。
// 修正点：用短期签名令牌替代直接返回 UUID，避免 UUID 成为永久免密凭证。
func signShareToken(uuid string, secret []byte, ttl time.Duration) (string, error) {
    exp := time.Now().Add(ttl).Unix()
    payload := uuid + "." + strconv.FormatInt(exp, 10)
    mac := hmac.New(sha256.New, secret)
    mac.Write([]byte(payload))
    sig := hex.EncodeToString(mac.Sum(nil))
    return base64.RawURLEncoding.EncodeToString([]byte(payload + "." + sig)), nil
}

// verifyShareToken 校验短期令牌，返回其中的 UUID（过期/篡改均拒绝）。
func verifyShareToken(token string, secret []byte) (string, error) {
    raw, err := base64.RawURLEncoding.DecodeString(token)
    if err != nil {
        return "", ErrShareInvalidToken
    }
    parts := strings.Split(string(raw), ".")
    if len(parts) != 3 {
        return "", ErrShareInvalidToken
    }
    mac := hmac.New(sha256.New, secret)
    mac.Write([]byte(parts[0] + "." + parts[1]))
    if !hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(parts[2])) {
        return "", ErrShareInvalidToken // 签名不符 → 篡改/伪造
    }
    exp, err := strconv.ParseInt(parts[1], 10, 64)
    if err != nil || time.Now().Unix() > exp {
        return "", ErrShareExpired // 令牌过期
    }
    return parts[0], nil
}

const shareMaxFails = 5 // 提取码/密码连续错误上限

// AccessShare 验证分享访问权限，依次执行四关校验，通过后下发短期令牌
func (uc *ShareUsecase) AccessShare(ctx context.Context, shareUUID, shareCode, password, clientIP string) (*Share, string, error) {
    share, err := uc.shareRepo.FindByUUID(ctx, shareUUID)
    if err != nil {
        return nil, "", err
    }
    if share.Status == 0 {
        return nil, "", ErrShareCancelled
    }
    if share.ExpireAt != nil && time.Now().After(*share.ExpireAt) {
        return nil, "", ErrShareExpired
    }

    // 修正点：提取码/密码失败计数防爆破（Redis 维度按 UUID）
    if uc.cache != nil {
        if fails, _ := uc.cache.GetInt(ctx, "share:err:"+share.UUID); fails >= shareMaxFails {
            return nil, "", ErrSharePasswordMismatch // 触发验证码/临时锁定
        }
    }

    if share.ShareType == "code" && shareCode != share.ShareCode {
        uc.incShareFail(ctx, share.UUID) // 修正点：失败计数 +1
        return nil, "", ErrSharePasswordMismatch
    }
    if share.Password != "" && !checkPassword(share.Password, password) {
        uc.incShareFail(ctx, share.UUID)
        return nil, "", ErrSharePasswordMismatch
    }

    // 修正点：校验通过清空失败计数
    if uc.cache != nil {
        _ = uc.cache.Del(ctx, "share:err:"+share.UUID)
    }
    if err := uc.shareRepo.IncrementVisit(ctx, share.ID); err != nil {
        log.Warn("share: failed to increment visit count", "shareID", share.ID, "err", err)
    }

    // 修正点：下发短期签名访问令牌（30 分钟），而非把 UUID 当长期凭证
    token, err := signShareToken(share.UUID, uc.shareSecret, 30*time.Minute)
    if err != nil {
        return nil, "", err
    }
    return share, token, nil
}

// incShareFail 累加某分享的提取码/密码失败次数（带 TTL，自动衰减）
func (uc *ShareUsecase) incShareFail(ctx context.Context, uuid string) {
    if uc.cache == nil {
        return
    }
    key := "share:err:" + uuid
    _ = uc.cache.Incr(ctx, key)
    _ = uc.cache.Expire(ctx, key, 30*time.Minute)
}

// AccessShare 验证对分享的访问权限，返回短期访问令牌。
func (s *ShareService) AccessShare(ctx context.Context, req *v1.AccessShareRequest) (*v1.AccessShareReply, error) {
    // 修正点：传入客户端 IP 用于失败计数维度
    clientIP := clientIPFromContext(ctx)
    share, token, err := s.uc.AccessShare(ctx, req.Uuid, req.ShareCode, req.Password, clientIP)
    if err != nil {
        return nil, err
    }
    return &v1.AccessShareReply{
        Valid: true,
        Token: token, // 修正点：这是短期签名令牌，不再是裸 UUID
        Share: toShareItem(share, false), // 修正点：不回显提取码
    }, nil
}

// GetShareDetail 返回分享详情和内容（修正点：先验短期令牌 + 补过期校验）
func (uc *ShareUsecase) GetShareDetail(ctx context.Context, token string) (*Share, []*File, []*Folder, error) {
    // 修正点：先校验短期签名令牌，拒绝伪造/过期，避免 UUID 被直接当凭证
    uuid, err := verifyShareToken(token, uc.shareSecret)
    if err != nil {
        return nil, nil, nil, err
    }
    share, err := uc.shareRepo.FindByUUID(ctx, uuid)
    if err != nil {
        return nil, nil, nil, err
    }
    if share.Status == 0 {
        return nil, nil, nil, ErrShareCancelled
    }
    // 修正点：补过期校验，原实现只在 AccessShare 校验，导致已过期分享经此接口仍可见
    if share.ExpireAt != nil && time.Now().After(*share.ExpireAt) {
        return nil, nil, nil, ErrShareExpired
    }

    var files []*File
    var folders []*Folder
    if share.ItemType == "file" {
        file, err := uc.fileRepo.FindByID(ctx, share.ItemID)
        if err == nil && file.Status == 0 {
            files = append(files, file)
        }
    } else {
        pid := share.ItemID
        fileList, _, err := uc.fileRepo.ListByParent(ctx, share.UserID, &pid, 0, "", 1000, "name", "asc")
        if err == nil {
            files = fileList
        }
        folderList, _, err := uc.folderRepo.ListByParent(ctx, share.UserID, &pid, "", 1000, "name", "asc")
        if err == nil {
            folders = folderList
        }
    }
    return share, files, folders, nil
}

// toShareItem 将 biz.Share 转为 v1.ShareItem（修正点：extractCode=false 时不回显提取码）
func toShareItem(share *biz.Share, withCode bool) *v1.ShareItem {
    if share == nil {
        return nil
    }
    item := &v1.ShareItem{
        Id: share.ID, Uuid: share.UUID, ItemType: share.ItemType, ItemId: share.ItemID,
        ShareType: share.ShareType, HasPassword: share.Password != "",
        Status: share.Status, VisitCount: share.VisitCount,
        CreatedAt: share.CreatedAt.Format("2006-01-02 15:04:05"),
    }
    if share.ExpireAt != nil {
        item.ExpireAt = share.ExpireAt.Format("2006-01-02 15:04:05")
    }
    // 修正点：访问者不应看到提取码本身（防信息泄露）
    if withCode {
        item.ShareCode = share.ShareCode
    }
    return item
}

// GetShareDetail 返回分享详情（修正点：补填 creator_name）
func (s *ShareService) GetShareDetail(ctx context.Context, req *v1.GetShareDetailRequest) (*v1.GetShareDetailReply, error) {
    share, files, folders, err := s.uc.GetShareDetail(ctx, req.Token)
    if err != nil {
        return nil, err
    }
    items := make([]*v1.FileItem, 0, len(files)+len(folders))
    for _, f := range files {
        items = append(items, &v1.FileItem{Id: f.ID, Uuid: f.UUID, Name: f.Name, IsFolder: false, Size: f.Size, Type: f.Type})
    }
    for _, f := range folders {
        items = append(items, &v1.FileItem{Id: f.ID, Name: f.Name, IsFolder: true})
    }
    // 修正点：补充创建者昵称（需 userUC 查，避免暴露 UserID 亦可）
    creatorName := ""
    if s.uc.userUC != nil {
        if u, err := s.uc.userUC.GetUserInfo(ctx, share.UserID); err == nil {
            creatorName = u.Nickname
        }
    }
    return &v1.GetShareDetailReply{
        Share:       toShareItem(share, false),
        CreatorName: creatorName, // 修正点：proto 已定义但未填，此处补上
        Items:       items,
    }, nil
}

// SaveShare 将分享的文件/文件夹复制到目标用户空间（修正点：先验令牌/过期 + 失败补偿）
func (uc *ShareUsecase) SaveShare(ctx context.Context, targetUserID uint64, token string, targetParentID *uint64) error {
    // 修正点：先校验短期令牌并取出详情（GetShareDetail 内含状态/过期/归属校验），
    // 已过期或带密码未通过的分享无法拿到 token，自然不能保存。
    share, files, _, err := uc.GetShareDetail(ctx, token)
    if err != nil {
        return err
    }
    _ = share

    if len(files) == 0 {
        return ErrFileNotFound
    }
    var totalSize int64
    for _, f := range files {
        totalSize += f.Size
    }
    if uc.userUC != nil {
        if err := uc.userUC.CheckStorageAvailable(ctx, targetUserID, totalSize); err != nil {
            return err
        }
    }

    // 记录已创建的文件 ID，用于补偿回滚
    createdIDs := make([]uint64, 0, len(files))
    for _, f := range files {
        uuid, err := newUUID()
        if err != nil {
            uc.rollbackCreatedFiles(ctx, createdIDs) // 修正点：补偿
            return err
        }
        copyFile := &File{
            UUID: uuid, UserID: targetUserID, Name: f.Name, Size: f.Size,
            Type: f.Type, Hash: f.Hash, Path: f.Path, // 复用同一物理文件
            ParentID: targetParentID, Status: 0,
        }
        created, err := uc.fileRepo.Create(ctx, copyFile)
        if err != nil {
            uc.rollbackCreatedFiles(ctx, createdIDs) // 修正点：补偿
            return err
        }
        createdIDs = append(createdIDs, created.ID)
    }

    // 修正点：扣减配额失败则补偿回滚已建文件，保证一致性（理想是同一 DB 事务）
    if uc.userUC != nil {
        if err := uc.userUC.AddUsedStorage(ctx, targetUserID, totalSize); err != nil {
            uc.rollbackCreatedFiles(ctx, createdIDs) // 关键：回滚，避免"有文件无配额"
            return err
        }
    }
    return nil
}

// rollbackCreatedFiles 补偿回滚：删除已复制的文件元数据，撤销部分成功
func (uc *ShareUsecase) rollbackCreatedFiles(ctx context.Context, ids []uint64) {
    for _, id := range ids {
        if f, err := uc.fileRepo.FindByID(ctx, id); err == nil {
            _ = uc.fileRepo.Delete(ctx, f) // 仅删元数据；物理文件因被分享者复用，不删
        }
    }
}

// CancelShare 取消分享（归属校验已实现，保留）
func (uc *ShareUsecase) CancelShare(ctx context.Context, userID, shareID uint64) error {
    share, err := uc.shareRepo.FindByID(ctx, shareID)
    if err != nil {
        return err
    }
    if share.UserID != userID { // 已正确：仅创建者可取消
        return ErrForbidden
    }
    if err := uc.shareRepo.Cancel(ctx, shareID); err != nil {
        return err
    }
    if uc.eventPublisher != nil {
        _ = uc.eventPublisher.Publish(ctx, EventShareCancelled, &SharePayload{
            UserID: userID, ShareID: shareID, UUID: share.UUID, Action: "cancelled",
        })
    }
    return nil
}

// CancelSharesByItem 当文件/文件夹被删除时，取消其所有有效分享（修正点：消除悬空分享）
func (uc *ShareUsecase) CancelSharesByItem(ctx context.Context, itemType string, itemID uint64) error {
    return uc.shareRepo.CancelByItemID(ctx, itemType, itemID)
}

func (r *shareRepo) ListByUser(ctx context.Context, userID uint64, cursor string, limit int) ([]*biz.Share, string, error) {
    query := r.db.WithContext(ctx).Model(&model.Share{}).
        Where("user_id = ? AND status = 1", userID)
    if cursor != "" {
        query = query.Where("created_at < ?", cursor)
    }
    var pos []model.Share
    if err := query.Order("created_at DESC").Limit(limit + 1).Find(&pos).Error; err != nil { // 多查1条
        return nil, "", err
    }
    hasMore := len(pos) > limit
    if hasMore {
        pos = pos[:limit] // 截断
    }
    nextCursor := ""
    if len(pos) > 0 {
        nextCursor = pos[len(pos)-1].CreatedAt.Format("2006-01-02 15:04:05")
    }
    shares := make([]*biz.Share, len(pos))
    for i := range pos {
        shares[i] = toBizShare(&pos[i])
    }
    return shares, nextCursor, nil
}

// CleanExpiredShares 批量清理过期分享（修正点：新增调度逻辑）
func (r *shareRepo) CleanExpiredShares(ctx context.Context, before time.Time, batch int) (int64, error) {
    var n int64
    for {
        // 分批更新，避免长时间锁表
        res := r.db.WithContext(ctx).Model(&model.Share{}).
            Where("status = 1 AND expire_at IS NOT NULL AND expire_at < ?", before).
            Limit(batch).Update("status", 0) // 软取消即可，保留审计
        if res.Error != nil {
            return n, res.Error
        }
        n += res.RowsAffected
        if res.RowsAffected < int64(batch) {
            break
        }
    }
    return n, nil
}

// StartShareCleanupScheduler 启动定时清理（在 main/wire 里调用一次）
func StartShareCleanupScheduler(repo biz.ShareRepo, interval time.Duration) {
    go func() {
        ticker := time.NewTicker(interval)
        defer ticker.Stop()
        for range ticker.C {
            ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
            if n, err := repo.CleanExpiredShares(ctx, time.Now(), 500); err != nil {
                log.Error("share: cleanup expired failed", "err", err)
            } else if n > 0 {
                log.Info("share: cleaned expired shares", "count", n)
            }
            cancel()
        }
    }()
}

// ShareAccessLog 分享访问审计记录
type ShareAccessLog struct {
    VisitorUserID uint64    // 访问者（登录用户则有，匿名为 0）
    VisitorIP     string    // 客户端 IP
    UUID          string    // 被访问的分享 UUID
    Action        string    // "access" / "save"
    CreatedAt     time.Time
}

// RecordShareAccess 记录一次分享访问审计（修正点：新增）
func (uc *ShareUsecase) RecordShareAccess(ctx context.Context, visitorUserID uint64, ip, uuid, action string) {
    log.Info("share.access",
        "visitor", visitorUserID, "ip", ip, "uuid", uuid, "action", action,
        "time", time.Now().Format(time.RFC3339))
    if uc.eventPublisher != nil {
        _ = uc.eventPublisher.Publish(ctx, EventShareAccessed, &ShareAccessPayload{
            VisitorUserID: visitorUserID, IP: ip, UUID: uuid, Action: action,
        })
    }
}

// RateLimitMiddleware 修正点：客户端 IP 取不可伪造的 X-Real-IP，而非 X-Forwarded-For 首值
func RateLimitMiddleware(maxRequests int, window time.Duration) middleware.Middleware {
    // ... 同原结构，仅替换 IP 提取：
    var clientIP string
    if tr, ok := transport.FromServerContext(ctx); ok {
        if ht, ok := tr.(interface{ Request() *http.Request }); ok {
            // 修正点：优先 X-Real-IP（由 nginx 从 $remote_addr 填，客户端不可伪造）
            clientIP = ht.Request().Header.Get("X-Real-IP")
            if clientIP == "" {
                clientIP = ht.Request().RemoteAddr
            }
        }
    }
    if clientIP == "" {
        clientIP = "unknown"
    }
    // ... 后续计数逻辑不变
}