ericwyuan/GarminHealthLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[阶段5.1] 开机自启 + 接入真实 garminconnect，修复同步的三处 API 误用

Browse Source 
fix(garmin): 同步代码调用的 garminconnect API 全是错的

装上库核对签名后发现（garminconnect 0.2.8），原代码从未被真正
执行过，三处调用都不成立：

1. get_activities(date) —— 该方法签名是 (start, limit)，收的是
   分页下标和条数，不是日期。传日期等于在问"第 2026-08-23 条运动"，
   而且少传一个参数必然 TypeError。
   改为 get_activities_by_date(start, end)，整个窗口一次取回，
   顺带把原来"每天一次调用"减为一次。

2. 睡眠数据不在 get_user_summary 里，是独立的 get_sleep_data(cdate)；
   原代码从 summary 里读 sleep 字段，结果会把每一晚都记成无睡眠数据。
   HRV 同理，走 get_hrv_data(cdate)。

3. 字段名不符：实际是 totalSteps / totalKilocalories /
   averageStressLevel，原代码用的是 steps / calories.total /
   stress.average。

其他改进:
- 运动记录改用 Garmin 自己的 activityId 作主键，重复同步同一窗口
  不再产生重复行（原来每次同步都会把同一条运动再插一遍）
- 某天无数据时返回全 None，不再写入空行让读端点再过滤掉
- 原来 bare except 吞掉每天的异常，全部失败也报 success；
  现在全窗口失败会如实返回 error 并记录原因
- 同步天数、是否走 Garmin 中国区改为环境变量可配

tests/test_garmin_sync.py (23 通过):
- 用 StubClient 模拟真实 0.2.8 的接口形状，无需库、凭证或网络
- 回归用例覆盖上述三处误用：活动必须按日期区间一次取回、
  睡眠与 HRV 必须走各自端点
- 重复同步不产生重复的天和重复的运动记录
- 单天失败跳过、全窗口失败报错、登录失败如实上报

部署:
- NAS 安装 garminconnect（pydantic-core 有 cp38 x86_64 轮子，
  无需 gcc）
- 新增 deploy/S99garmin.sh 开机自启脚本，与 NAS 上既有的
  S99frpc.sh 同一套惯例；以 root 启动但降权到 ericwyuan 运行，
  因为服务不需要特权而 .env 里有数据库和 API 凭证
- PID 文件放应用目录而非 /var/run（非特权用户写不了）

NAS 真机全量测试: 240 passed

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
ericwyuan
2026-08-23 19:05:19 +08:00
parent 5f07dad019
commit 6de7562cd8
5 changed files with 535 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

303
backend/services/garmin.py
View File

@@ -1,43 +1,51 @@
"""
Garmin sync service.
Pulls up to 7 days of daily summaries + activities through the `garminconnect`
library and upserts them. The library and real Garmin credentials are required
to actually run a sync; without them the endpoint reports a clear error instead
of crashing (mirrors the original Node behaviour).
Pulls daily summaries + activities through the `garminconnect` library and
upserts them. The library and real Garmin credentials are required to actually
run a sync; without them the endpoint reports a clear error instead of
crashing.
Garmin credentials: the app only stores a scrypt *hash* of the Garmin password
(so it cannot be recovered), therefore a live sync needs the plaintext
garminEmail/garminPassword supplied in the request body.
Garmin credentials: the app only stores a scrypt/PBKDF2 *hash* of the Garmin
password (so it cannot be recovered), therefore a live sync needs the
plaintext garminEmail/garminPassword supplied in the request body.
On the library's API — these were verified against garminconnect 0.2.8:
* get_user_summary(cdate) -> one day of daily totals
* get_sleep_data(cdate) -> sleep, NOT part of the summary
* get_hrv_data(cdate) -> HRV, also separate
* get_activities_by_date(start, end) -> activities in a date range
* get_activities(start, limit) -> PAGINATION, not dates
The last two are easy to confuse: `get_activities` takes an offset and a count,
so passing it a date silently asks for activity number "2026-08-23".
"""
import datetime
import os
from db import execute, query_one, query_all
from db import execute, query_one
from config import DB_TYPE
from services import health
# How many days back a sync reaches.
DEFAULT_SYNC_DAYS = int(os.environ.get("GARMIN_SYNC_DAYS") or 7)
def _set_sync_status(user_id, status, now, **fields):
cols = ["user_id", "status", "last_sync_time"] + list(fields.keys())
placeholders = ", ".join(["?"] * len(cols))
if DB_TYPE == "mariadb":
updates = ", ".join(
f"{c}=VALUES({c})" for c in cols if c != "user_id"
)
updates = ", ".join(f"{c}=VALUES({c})" for c in cols if c != "user_id")
sql = (
f"INSERT INTO sync_status ({', '.join(cols)}) VALUES ({placeholders}) "
f"ON DUPLICATE KEY UPDATE {updates}"
)
else:
updates = ", ".join(
f"{c}=excluded.{c}" for c in cols if c != "user_id"
)
updates = ", ".join(f"{c}=excluded.{c}" for c in cols if c != "user_id")
sql = (
f"INSERT INTO sync_status ({', '.join(cols)}) VALUES ({placeholders}) "
f"ON CONFLICT(user_id) DO UPDATE SET {updates}"
)
params = [user_id, status, now] + list(fields.values())
execute(sql, params)
execute(sql, [user_id, status, now] + list(fields.values()))
def get_sync_status(user_id):
@@ -57,94 +65,187 @@ def get_sync_status(user_id):
}
def sync_data(user_id, creds):
now = datetime.datetime.utcnow().isoformat()
def _connect(creds):
"""Log in to Garmin Connect. Separated so tests can substitute a client."""
try:
from garminconnect import Garmin
except ImportError:
raise RuntimeError(
"GARMIN_LIB_MISSING: 请先运行 `pip install garminconnect` 以启用同步"
)
# is_cn selects Garmin's China service, which is a different backend with
# separate accounts. This project tracks an international account.
is_cn = (os.environ.get("GARMIN_IS_CN") or "").lower() in ("1", "true", "yes")
client = Garmin(email=creds["garminEmail"], password=creds["garminPassword"], is_cn=is_cn)
client.login()
return client
def _num(*values):
"""First value that is a usable number."""
for v in values:
if isinstance(v, (int, float)) and not isinstance(v, bool):
return v
return None
def _extract_daily(client, date_str):
"""One day of metrics, assembled from the endpoints that carry them.
Sleep and HRV are separate endpoints in this library — they are not part
of the daily summary — so a sync that only read the summary would record
every night as "no sleep data".
"""
summary = client.get_user_summary(date_str) or {}
sleep_seconds = None
sleep_quality = None
try:
sleep = (client.get_sleep_data(date_str) or {}).get("dailySleepDTO") or {}
sleep_seconds = _num(sleep.get("sleepTimeSeconds"))
sleep_quality = _num(sleep.get("sleepScores", {}).get("overall", {}).get("value")
if isinstance(sleep.get("sleepScores"), dict) else None)
except Exception:
pass # a missing night must not abort the whole day
hrv = None
try:
hrv_body = client.get_hrv_data(date_str) or {}
summary_block = hrv_body.get("hrvSummary") or {}
hrv = _num(summary_block.get("lastNightAvg"), summary_block.get("weeklyAvg"))
except Exception:
pass
return {
"date": date_str,
"steps": _num(summary.get("totalSteps")),
"heartRate": _num(summary.get("restingHeartRate"),
summary.get("averageHeartRate")),
"heartRateVariability": hrv,
"sleepDuration": round(sleep_seconds / 3600, 1) if sleep_seconds else None,
"sleepQuality": sleep_quality,
"stress": _num(summary.get("averageStressLevel")),
"caloriesBurned": _num(summary.get("totalKilocalories")),
}
def _activity_end(start, duration_seconds):
if not start or not duration_seconds:
return start
for fmt in ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S.%f"):
try:
dt = datetime.datetime.strptime(start[:26], fmt)
return (dt + datetime.timedelta(seconds=duration_seconds)).isoformat()
except ValueError:
continue
return start
def _sync_activities(client, user_id, start_date, end_date):
"""Fetch the window's activities in one call and store the new ones."""
activities = client.get_activities_by_date(start_date, end_date) or []
stored = 0
for a in activities:
start = a.get("startTimeLocal") or a.get("startTime")
activity_type = (
(a.get("activityType") or {}).get("typeKey")
if isinstance(a.get("activityType"), dict)
else a.get("activityType")
) or "unknown"
duration = _num(a.get("duration"))
# Garmin activity ids are stable, so re-syncing a window must not
# duplicate what is already stored.
garmin_id = a.get("activityId")
if garmin_id is not None:
existing = query_one(
"SELECT id FROM activities WHERE user_id = ? AND id = ?",
[user_id, str(garmin_id)],
)
if existing:
continue
health.insert_activity(
user_id,
{
"id": str(garmin_id) if garmin_id is not None else None,
"activityType": activity_type,
"startTime": start,
"endTime": _activity_end(start, duration),
"duration": duration,
"distance": _num(a.get("distance")),
"calories": _num(a.get("calories")),
"heartRateAverage": _num(a.get("averageHR")),
"heartRateMax": _num(a.get("maxHR")),
},
)
stored += 1
return stored
def sync_data(user_id, creds, days=None, client=None):
"""Pull the last `days` days from Garmin Connect into the local database.
`client` exists so tests can inject a stub instead of reaching Garmin.
"""
days = days or DEFAULT_SYNC_DAYS
now = datetime.datetime.utcnow().isoformat(timespec="seconds")
_set_sync_status(user_id, "syncing", now, records_synced=0)
try:
try:
from garminconnect import Garmin
except ImportError:
raise RuntimeError(
"GARMIN_LIB_MISSING: 请先运行 `pip install garminconnect` 以启用同步"
)
client = Garmin(email=creds["garminEmail"], password=creds["garminPassword"])
client.login()
records_synced = 0
for i in range(7):
d = datetime.datetime.utcnow() - datetime.timedelta(days=i)
date_str = d.strftime("%Y-%m-%d")
try:
daily = client.get_user_summary(date_str)
if daily:
sleep_sec = (daily.get("sleep") or {}).get("sleepingSeconds") or daily.get(
"sleepingSeconds"
)
health.upsert_health_daily(
user_id,
{
"date": date_str,
"steps": daily.get("steps"),
"heartRate": daily.get("restingHeartRate")
or daily.get("averageHeartRate"),
"heartRateVariability": daily.get("hrv")
or daily.get("heartRateVariability"),
"sleepDuration": round(sleep_sec / 3600, 1) if sleep_sec else None,
"sleepQuality": (daily.get("sleep") or {}).get("sleepQuality"),
"stress": (daily.get("stress") or {}).get("average")
or daily.get("averageStress"),
"caloriesBurned": (daily.get("calories") or {}).get("total")
or daily.get("totalCalories"),
},
)
records_synced += 1
activities = client.get_activities(date_str) or []
for a in activities or []:
start = a.get("startTimeLocal") or a.get("startTime")
start_ms = start and datetime.datetime.strptime(
start, "%Y-%m-%dT%H:%M:%S" if "T" in (start or "") else "%Y-%m-%d %H:%M:%S"
).timestamp() if start else None
health.insert_activity(
user_id,
{
"activityType": (a.get("activityType") or {}).get("typeKey")
or a.get("type")
or "unknown",
"startTime": start,
"endTime": (
start
if start_ms is None or not a.get("duration")
else datetime.datetime.utcfromtimestamp(
start_ms + (a.get("duration") or 0)
).isoformat()
),
"duration": a.get("duration"),
"distance": a.get("distance"),
"calories": a.get("calories"),
"heartRateAverage": a.get("averageHR"),
"heartRateMax": a.get("maxHR"),
},
)
except Exception:
# skip a single bad day and continue
continue
_set_sync_status(user_id, "idle", now, records_synced=records_synced)
return {
"status": "success",
"recordsSynced": records_synced,
"message": f"同步完成，新增/更新 {records_synced} 天数据",
"lastSyncTime": now,
}
client = client or _connect(creds)
except Exception as e:
message = str(e)
_set_sync_status(user_id, "error", now, records_synced=0, last_error=message)
return {
"status": "error",
"recordsSynced": 0,
"message": message,
"lastSyncTime": now,
}
return {"status": "error", "recordsSynced": 0, "message": message,
"lastSyncTime": now}
today = datetime.date.today()
start_date = (today - datetime.timedelta(days=days - 1)).isoformat()
days_synced = 0
day_errors = []
for i in range(days):
date_str = (today - datetime.timedelta(days=i)).isoformat()
try:
record = _extract_daily(client, date_str)
except Exception as e:
day_errors.append(f"{date_str}: {e}")
continue
# A day Garmin has no data for comes back all-None; storing it would
# create an empty row that the metric endpoints then have to filter.
if any(record[k] is not None for k in record if k != "date"):
health.upsert_health_daily(user_id, record)
days_synced += 1
activities_synced = 0
try:
activities_synced = _sync_activities(
client, user_id, start_date, today.isoformat()
)
except Exception as e:
day_errors.append(f"activities: {e}")
# Every single day failing means something systemic (expired session,
# API change) — reporting that as a clean success would hide it.
if days_synced == 0 and len(day_errors) >= days:
message = "; ".join(day_errors[:3])
_set_sync_status(user_id, "error", now, records_synced=0, last_error=message)
return {"status": "error", "recordsSynced": 0,
"message": f"同步失败：{message}", "lastSyncTime": now}
_set_sync_status(
user_id, "idle", now, records_synced=days_synced,
last_error="; ".join(day_errors[:3]) if day_errors else None,
)
message = f"同步完成，更新 {days_synced} 天数据、{activities_synced} 条运动记录"
if day_errors:
message += f"（{len(day_errors)} 天跳过）"
return {
"status": "success",
"recordsSynced": days_synced,
"activitiesSynced": activities_synced,
"message": message,
"lastSyncTime": now,
}

5
backend/services/health.py
View File

@@ -134,7 +134,10 @@ def upsert_health_daily(user_id, record):
def insert_activity(user_id, activity):
aid = str(uuid.uuid4())
# Prefer Garmin's own activity id when the caller has one: it is stable
# across syncs, which is what lets a re-synced window skip what is already
# stored instead of inserting it again.
aid = str(activity.get("id") or uuid.uuid4())
cols = [
"id", "user_id", "activity_type", "start_time", "end_time",
"duration", "distance", "calories", "heart_rate_average", "heart_rate_max",