🏃 跑步星球 · API 文档

一、总体架构

跑步星球的云端数据存储基于 Supabase（supabase.co）PostgreSQL 数据库。应用通过 Supabase 匿名 Key 直连数据库，没有自建后端服务。客户端使用用户名（username）作为业务主键进行读写。

二、数据表结构

1. run_data — 用户数据总表（核心）

整包存储：用户的跑步记录、跳绳记录、积分、商城已兑换商品、挑战进度、跑团列表等全部 userData 字段，以单行密文形式保存。

create table run_data (
  username   text primary key,   -- 用户名（业务主键）
  data       text,               -- 整包 userData 加密后的密文（见加密方式）
  updated_at timestamptz         -- 最后更新时间
);
alter table run_data disable row level security;

2. club_data — 跑团归属表

单独存储每个用户的跑团归属信息（团号、加入时间等）。

create table club_data (
  username   text primary key,
  data       text,
  updated_at timestamptz
);
alter table club_data disable row level security;

3. club_chat — 跑团聊天表

跑团内实时聊天消息，明文存储，客户端轮询获取；云端自动清理 7 天前的消息以节省空间并缩小隐私暴露面。

create table club_chat (
  id       bigint generated always as identity primary key,
  club_id  text,      -- 跑团号
  username text,      -- 发送者
  msg      text,      -- 消息内容
  ts       bigint     -- 时间戳(ms)
);

4. risk_review — 异常记录审批表

疑似异常运动记录自动上传，由管理员通过 / 驳回；record_id 带唯一约束用于去重。

create table risk_review (
  id          bigint generated always as identity primary key,
  username    text,
  record_id   bigint unique,     -- 关联本地记录ID（唯一去重）
  distance    real,
  time        real,
  pace        real,
  sport       text,
  risk_reason text,
  create_time bigint,
  status      integer,           -- 审批状态
  updated_at  bigint
);
alter table risk_review disable row level security;

5. rank_interactions — 排行榜互动表（用户自建，自动降级）

排行榜点赞 / 评论 / 送花数据。该表需在 Supabase 后台手动执行 SQL 创建；未创建时应用自动降级隐藏互动入口，不影响其他功能。

create table rank_interactions (
  id          bigint generated always as identity primary key,
  target_user text not null,     -- 被互动用户
  actor_user  text not null,     -- 互动用户
  type        text not null,     -- like / comment / flower
  content     text,
  create_time bigint
);
alter table rank_interactions disable row level security;

6. beacon_share — 实时位置分享表（独立）

跨设备双向实时位置共享：分享者与接收者各自 upsert 自己的位置字段，每约 3 秒轮询一次展示双方位置；任一方停止即标记失效。

create table beacon_share (
  id          text primary key,   -- 分享链接ID
  host_user   text,
  host_lat    double precision,
  host_lon    double precision,
  host_ts     bigint,
  host_active boolean,
  guest_user  text,
  guest_lat   double precision,
  guest_lon   double precision,
  guest_ts    bigint,
  guest_active boolean,
  updated_at  timestamptz default now()
);

三、加密方式（如实说明）

• 客户端在写入前调用 _secureEncrypt 进行 XOR + Base64 混淆，密文以 rp2: 前缀标识。
• 读取时先解密并解析 JSON，解析失败则原样返回，不阻塞同步流程。
• 密码仅保存哈希值，不存储明文。
• 本地数据（游客模式）仅保存在设备 localStorage，不经过云端。

四、同步机制

• 登录用户的数据以 username 为键 upsert 到 run_data，实现跨设备覆盖同步。
• 断网时记录标记为「待同步」（pending），联网后自动补传；同步失败每 30 秒兜底重试。
• 排行榜数据复用 run_data 全表，拉取后解密在本地计算周榜 / 月榜。
• 管理员通过 risk_review 表审批异常记录；club_chat 聊天自动清理 7 天前数据。

五、限制与说明

• 本项目为个人开发，无独立后端服务器，所有云端依赖 Supabase 免费额度，请勿将本应用用于生产级商业场景。
• 跨设备位置分享需双方保持网络可用；未登录用户仅可单向查看分享者位置，无法上传自身位置。
• 本页文档仅描述应用真实使用的存储结构，不包含任何虚构能力。