╔══════════════════════════════════════════════════════════════════════════════════╗ ║ 分享状态与生命周期管理 ║ ║ 技术文档 ║ ║ 版本 v1.0 | 2026-03-26 ║ ╚══════════════════════════════════════════════════════════════════════════════════╝ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 一、分享状态定义 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ 【活跃 - ACTIVE】 │ │ ├── 分享正常可用，用户可以访问、预览和下载文件 │ │ ├── 可执行操作：撤销、延长有效期、复制链接、查看统计 │ │ └── 状态码：200 OK │ │ │ │ 【已过期 - EXPIRED】 │ │ ├── 分享已超过设定的有效期，自动失效 │ │ ├── 可执行操作：延长有效期（恢复）、复制链接、查看统计 │ │ ├── 不可操作：撤销（已失效）、下载文件 │ │ └── 状态码：410 Gone │ │ │ │ 【已撤销 - REVOKED】 │ │ ├── 用户主动撤销分享，链接永久失效 │ │ ├── 可执行操作：查看统计 │ │ ├── 不可操作：撤销、延长有效期、复制链接、下载文件 │ │ └── 状态码：403 Forbidden │ │ │ │ 【已归档 - ARCHIVED】 │ │ ├── 过期的旧分享自动归档，便于后续查阅 │ │ ├── 可执行操作：查看统计 │ │ ├── 不可操作：任何修改或访问操作 │ │ └── 状态码：404 Not Found │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 二、撤销 vs 过期 - 核心区别 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────┬─────────────────────────┬─────────────────────────┐ │ │ │ 对比项 │ 撤销 │ 过期 │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ 触发方式 │ 👤 用户主动操作 │ 🤖 系统自动触发 │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ 触发时机 │ 点击"撤销分享"按钮 │ expiresAt < 当前时间 │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ 原因 │ 用户不想再分享该文件 │ 到达设定的有效期 │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ 可逆性 │ ❌ 不可逆（需重新创建） │ ✅ 可延长有效期恢复 │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ HTTP状态码 │ 403 Forbidden │ 410 Gone │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ 用户提示 │ "该分享已被撤销" │ "该分享已过期" │ │ │ ├─────────────────────┼─────────────────────────┼─────────────────────────┤ │ │ │ 示例场景 │ 分享链接泄露，立即撤销 │ 设置7天有效期，自动过期 │ │ │ └─────────────────────┴─────────────────────────┴─────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 三、状态流转图 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ │ │ │ 创建分享 │ │ │ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ ACTIVE │ │ │ │ 活跃状态 │ │ │ └──────┬──────┘ │ │ │ │ │ ┌───────────────────────┼───────────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 撤销操作 │ │ 时间到期 │ │ 延长有效期 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ ▼ ▼ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ │ REVOKED │ │ EXPIRED │◄──────────────┘ │ │ │ 已撤销 │ │ 已过期 │ │ │ └─────────────┘ └──────┬──────┘ │ │ │ │ │ ▼ (30天后自动归档) │ │ ┌─────────────┐ │ │ │ ARCHIVED │ │ │ │ 已归档 │ │ │ └─────────────┘ │ │ │ │ 状态说明： │ │ • ACTIVE → REVOKED: 用户主动撤销，不可逆 │ │ • ACTIVE → EXPIRED: 自动过期，可延长恢复 │ │ • EXPIRED → ACTIVE: 延长有效期后重新激活 │ │ • EXPIRED → ARCHIVED: 过期30天后自动归档 │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 四、用户访问流程 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ 用户访问分享链接 │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ 检查分享状态 │ │ │ │ │ └──────────┬──────────┘ │ │ │ │ │ │ │ │ │ ┌───────────────────┼───────────────────┐ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ ACTIVE │ │ EXPIRED │ │ REVOKED │ │ │ │ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ 显示错误页面 │ │ 显示错误页面 │ │ │ │ │ │ │ "已过期" │ │ "已撤销" │ │ │ │ │ │ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ 检查分享类型 │ │ │ │ │ └──────────┬──────────┘ │ │ │ │ │ │ │ │ │ ┌───────┴───────┐ │ │ │ │ ▼ ▼ │ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ │ │ 公开分享 │ │ 内部分享 │ │ │ │ │ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ │ │ 需要密码 │ │ 需要登录 │ │ │ │ │ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ │ │ │ └───────┬───────┘ │ │ │ │ ▼ │ │ │ │ ┌─────────────┐ │ │ │ │ │ 验证通过 │ │ │ │ │ └──────┬──────┘ │ │ │ │ ▼ │ │ │ │ ┌─────────────┐ │ │ │ │ │ 显示文件列表 │ │ │ │ │ └──────┬──────┘ │ │ │ │ ▼ │ │ │ │ ┌─────────────┐ │ │ │ │ │ 下载文件 │ │ │ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 五、数据库关键字段 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────┬───────────────────┬─────────────────────────────────┐ │ │ │ 字段名 │ 类型 │ 说明 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ status │ enum │ 状态：active/expired/revoked │ │ │ │ │ │ /archived/limited │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ expires_at │ timestamp │ 过期时间（NULL表示永久有效） │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ revoked_at │ timestamp │ 撤销时间（撤销时记录） │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ revoked_reason │ varchar │ 撤销原因 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ created_at │ timestamp │ 创建时间 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ updated_at │ timestamp │ 更新时间 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ last_accessed_at │ timestamp │ 最后访问时间 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ view_count │ int │ 浏览次数 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ download_count │ int │ 下载次数 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ max_views │ int │ 最大浏览次数限制 │ │ │ ├─────────────────────┼───────────────────┼─────────────────────────────────┤ │ │ │ max_downloads │ int │ 最大下载次数限制 │ │ │ └─────────────────────┴───────────────────┴─────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 六、状态码与用户提示 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┬───────────────┬─────────────────────────────────────────────┐ │ │ │ 状态 │ 状态码 │ 用户提示 │ │ │ ├─────────────┼───────────────┼─────────────────────────────────────────────┤ │ │ │ active │ 200 OK │ 正常访问，显示文件内容 │ │ │ ├─────────────┼───────────────┼─────────────────────────────────────────────┤ │ │ │ expired │ 410 Gone │ "该分享已过期，无法访问" │ │ │ │ │ │ "请联系分享者延长有效期" │ │ │ ├─────────────┼───────────────┼─────────────────────────────────────────────┤ │ │ │ revoked │ 403 Forbidden│ "该分享已被撤销，无法访问" │ │ │ │ │ │ "分享者已取消此分享" │ │ │ ├─────────────┼───────────────┼─────────────────────────────────────────────┤ │ │ │ archived │ 404 Not Found│ "该分享已归档，无法访问" │ │ │ │ │ │ "此分享已进入归档状态" │ │ │ └─────────────┴───────────────┴─────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 七、前端展示逻辑 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ 我的分享页面 │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ 【活跃中 - ACTIVE】 │ │ │ │ ├── 显示绿色标签 "活跃" │ │ │ │ ├── 可操作：撤销、延长有效期、复制链接 │ │ │ │ └── 显示浏览次数、下载次数 │ │ │ │ │ │ │ │ 【已过期 - EXPIRED】 │ │ │ │ ├── 显示灰色标签 "已过期" │ │ │ │ ├── 可操作：延长有效期（可恢复） │ │ │ │ ├── 不可操作：撤销（已失效） │ │ │ │ └── 链接显示为灰色，可点击但提示过期 │ │ │ │ │ │ │ │ 【已撤销 - REVOKED】 │ │ │ │ ├── 显示红色标签 "已撤销" │ │ │ │ ├── 不可操作：任何操作 │ │ │ │ └── 显示撤销时间 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ 公开分享广场 │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ 【未过期】 │ │ │ │ ├── 正常显示卡片 │ │ │ │ ├── 可点击访问 │ │ │ │ └── 显示"未过期"或"X天后过期" │ │ │ │ │ │ │ │ 【已过期】 │ │ │ │ ├── 灰色背景 + 删除线标题 │ │ │ │ ├── 红色边框 + 过期横幅 │ │ │ │ ├── 可点击（显示过期提示） │ │ │ │ └── 显示"已过期"红色徽章 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 八、用户可执行操作 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┬───────────────────────┬─────────────────────────────────┐ │ │ │ 操作 │ 适用状态 │ 说明 │ │ │ ├─────────────────┼───────────────────────┼─────────────────────────────────┤ │ │ │ 📋 复制链接 │ active / expired │ 复制分享链接和提取码 │ │ │ ├─────────────────┼───────────────────────┼─────────────────────────────────┤ │ │ │ ⏰ 延长有效期 │ active / expired │ 延长7/30天，可恢复过期分享 │ │ │ ├─────────────────┼───────────────────────┼─────────────────────────────────┤ │ │ │ 🗑️ 撤销分享 │ active │ 永久撤销，不可恢复 │ │ │ ├─────────────────┼───────────────────────┼─────────────────────────────────┤ │ │ │ 📊 查看统计 │ 所有状态 │ 查看浏览次数、下载次数等 │ │ │ ├─────────────────┼───────────────────────┼─────────────────────────────────┤ │ │ │ 📥 下载文件 │ active │ 需要密码验证或登录验证 │ │ │ └─────────────────┴───────────────────────┴─────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 九、相关API接口 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────┬──────────┬──────────────────────────┐ │ │ │ 接口 │ 方法 │ 说明 │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /api/shares │ POST │ 创建分享 │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /api/shares/:id/extend │ POST │ 延长有效期 │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /api/shares/:id/revoke │ POST │ 撤销分享 │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /api/shares/:id/reactivate │ POST │ 重新激活已过期的分享 │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /s/:code │ GET │ 访问分享（短链接） │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /api/shares/public/list │ GET │ 获取公开分享广场列表 │ │ │ ├─────────────────────────────────────┼──────────┼──────────────────────────┤ │ │ │ /api/shares/stats │ GET │ 获取分享统计数据 │ │ │ └─────────────────────────────────────┴──────────┴──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 十、总结对比表 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┬─────────────────────────┬─────────────────────────────┐ │ │ │ 特性 │ 撤销 │ 过期 │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 触发方式 │ 用户主动 │ 系统自动 │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 原因 │ 用户不想分享了 │ 时间到了 │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 可逆性 │ ❌ 不可逆 │ ✅ 可延长恢复 │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 状态码 │ 403 Forbidden │ 410 Gone │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 用户操作 │ 点击"撤销"按钮 │ 设置有效期 │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 提示信息 │ "已被撤销" │ "已过期" │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 统计保留 │ ✅ 保留 │ ✅ 保留 │ │ │ ├─────────────────┼─────────────────────────┼─────────────────────────────┤ │ │ │ 链接状态 │ 永久失效 │ 可恢复 │ │ │ └─────────────────┴─────────────────────────┴─────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ═══════════════════════════════════════════════════════════════════════════════════ 文档结束 - 智能文件管理系统 ═══════════════════════════════════════════════════════════════════════════════════