# DESIGN-001 Core Concepts

# 终端 (Terminal)

终端是驿站的核心实体，类比聊天软件中的"设备"概念。每个浏览器实例或设备是一个独立终端。

属性	说明
terminal_id	唯一标识（UUID）
account_id	所属账号
name	终端名称（用户自定义，如"手机浏览器"、“工作电脑”）
device_info	设备信息（UA、OS 等）
permission	权限等级：admin / user
is_primary	主终端标志（首个注册，固定 admin）
is_temporary	浏览器终端默认 true，关闭/断线后自动注销
status	在线状态：online / offline / deregistered
created_at	创建时间

临时终端：所有浏览器创建的终端（含主终端）默认为临时终端（is_temporary: true），WebSocket 断线后自动标记为 deregistered。重开浏览器且 localStorage 有 terminal_token → 恢复旧终端（标记 online）。若 token 丢失且账号无 admin → 自动创建新 admin。终端名称从 User-Agent 自动生成（如 “Chrome/Windows”），可事后改名。

# 权限模型

权限	能力	约束
admin	管理账号下所有终端（添加/删除/重命名）、修改其他终端权限	每个账号至少保留一个 admin 终端（主终端）；主终端不可删除/降级
user	文件传输、查看历史、创建群组、加入/退出群组	不能管理终端或修改权限

主终端：账号注册时自动创建的第一个终端，固定为 admin。主终端不可被删除，不可降级为 user。其他终端默认为 user，可由 admin 提升。所有终端（含 user）均可创建群组。

# 传输模式

模式	说明	适用场景
P2P 直传	WebRTC DataChannel，文件不经服务器	同局域网或网络条件好时
中继传输	文件经服务器中转	P2P 不可达时（NAT 穿透失败）
离线排队	文件暂存服务器，接收方上线后自动传输	接收方离线时

传输协商流程：发送方发起 → 接收方在线？→ 是：尝试 P2P → 超时降级中继 / 否：文件暂存服务器（24h TTL），上线后自动拉取。

并发模型：同一对终端间串行传输，不同终端对可并行。

# 群组

群组是终端的集合，用于广播传输。任何终端均可创建群组，创建者自动成为群主。广播传输时逐个处理：在线成员立即传输，离线成员排队（24h TTL）。

属性	说明
group_id	唯一标识
account_id	所属账号
name	群组名称
members	终端列表
created_by	创建者终端
created_at	创建时间