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

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>

backend/requirements.txt

@@ -4,6 +4,5 @@ PyMySQL>=1.1
 PyJWT>=2.8
 python-dotenv>=1.0
 gunicorn>=21.2
-# Optional — only needed to run live Garmin syncs:
-# garminconnect>=0.13
 requests>=2.31
+garminconnect>=0.2.8

backend/services/garmin.py

@@ -1,43 +1,51 @@
 """
 Garmin sync service.
 
-Pulls up to 7 days of daily summaries + activities through the `garminconnect`
+Pulls daily summaries + activities through the `garminconnect` library and
-library and upserts them. The library and real Garmin credentials are required
+upserts them. The library and real Garmin credentials are required to actually
-to actually run a sync; without them the endpoint reports a clear error instead
+run a sync; without them the endpoint reports a clear error instead of
-of crashing (mirrors the original Node behaviour).
+crashing.
 
-Garmin credentials: the app only stores a scrypt *hash* of the Garmin password
+Garmin credentials: the app only stores a scrypt/PBKDF2 *hash* of the Garmin
-(so it cannot be recovered), therefore a live sync needs the plaintext
+password (so it cannot be recovered), therefore a live sync needs the
-garminEmail/garminPassword supplied in the request body.
+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(
+        updates = ", ".join(f"{c}=VALUES({c})" for c in cols if c != "user_id")
-            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(
+        updates = ", ".join(f"{c}=excluded.{c}" for c in cols if c != "user_id")
-            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, [user_id, status, now] + list(fields.values()))
-    execute(sql, params)
 
 
 def get_sync_status(user_id):
@@ -57,11 +65,8 @@ def get_sync_status(user_id):
     }
 
 
-def sync_data(user_id, creds):
+def _connect(creds):
-    now = datetime.datetime.utcnow().isoformat()
+    """Log in to Garmin Connect. Separated so tests can substitute a client."""
-    _set_sync_status(user_id, "syncing", now, records_synced=0)
-
-    try:
     try:
         from garminconnect import Garmin
     except ImportError:
@@ -69,82 +74,178 @@ def sync_data(user_id, creds):
             "GARMIN_LIB_MISSING: 请先运行 `pip install garminconnect` 以启用同步"
         )
 
-        client = Garmin(email=creds["garminEmail"], password=creds["garminPassword"])
+    # 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
 
-        records_synced = 0
+
-        for i in range(7):
+def _num(*values):
-            d = datetime.datetime.utcnow() - datetime.timedelta(days=i)
+    """First value that is a usable number."""
-            date_str = d.strftime("%Y-%m-%d")
+    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:
-                daily = client.get_user_summary(date_str)
+        sleep = (client.get_sleep_data(date_str) or {}).get("dailySleepDTO") or {}
-                if daily:
+        sleep_seconds = _num(sleep.get("sleepTimeSeconds"))
-                    sleep_sec = (daily.get("sleep") or {}).get("sleepingSeconds") or daily.get(
+        sleep_quality = _num(sleep.get("sleepScores", {}).get("overall", {}).get("value")
-                        "sleepingSeconds"
+                             if isinstance(sleep.get("sleepScores"), dict) else None)
-                    )
+    except Exception:
-                    health.upsert_health_daily(
+        pass  # a missing night must not abort the whole day
-                        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 []
+    hrv = None
-                for a in activities or []:
+    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")
-                    start_ms = start and datetime.datetime.strptime(
+        activity_type = (
-                        start, "%Y-%m-%dT%H:%M:%S" if "T" in (start or "") else "%Y-%m-%d %H:%M:%S"
+            (a.get("activityType") or {}).get("typeKey")
-                    ).timestamp() if start else None
+            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,
             {
-                            "activityType": (a.get("activityType") or {}).get("typeKey")
+                "id": str(garmin_id) if garmin_id is not None else None,
-                            or a.get("type")
+                "activityType": activity_type,
-                            or "unknown",
                 "startTime": start,
-                            "endTime": (
+                "endTime": _activity_end(start, duration),
-                                start
+                "duration": duration,
-                                if start_ms is None or not a.get("duration")
+                "distance": _num(a.get("distance")),
-                                else datetime.datetime.utcfromtimestamp(
+                "calories": _num(a.get("calories")),
-                                    start_ms + (a.get("duration") or 0)
+                "heartRateAverage": _num(a.get("averageHR")),
-                                ).isoformat()
+                "heartRateMax": _num(a.get("maxHR")),
-                            ),
-                            "duration": a.get("duration"),
-                            "distance": a.get("distance"),
-                            "calories": a.get("calories"),
-                            "heartRateAverage": a.get("averageHR"),
-                            "heartRateMax": a.get("maxHR"),
             },
         )
-            except Exception:
+        stored += 1
-                # skip a single bad day and continue
+    return stored
-                continue
 
-        _set_sync_status(user_id, "idle", now, records_synced=records_synced)
+
-        return {
+def sync_data(user_id, creds, days=None, client=None):
-            "status": "success",
+    """Pull the last `days` days from Garmin Connect into the local database.
-            "recordsSynced": records_synced,
+
-            "message": f"同步完成，新增/更新 {records_synced} 天数据",
+    `client` exists so tests can inject a stub instead of reaching Garmin.
-            "lastSyncTime": now,
+    """
-        }
+    days = days or DEFAULT_SYNC_DAYS
+    now = datetime.datetime.utcnow().isoformat(timespec="seconds")
+    _set_sync_status(user_id, "syncing", now, records_synced=0)
+
+    try:
+        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}
+
+    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": "error",
+        "status": "success",
-            "recordsSynced": 0,
+        "recordsSynced": days_synced,
+        "activitiesSynced": activities_synced,
         "message": message,
         "lastSyncTime": now,
     }

backend/services/health.py

@@ -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",

backend/tests/test_garmin_sync.py

@@ -0,0 +1,282 @@
+"""
+Unit tests for the Garmin sync service.
+
+A stub client stands in for `garminconnect`, so the suite runs without the
+library, without credentials and without touching Garmin.
+
+The stub mirrors the real 0.2.8 API shapes on purpose — the original code
+called `get_activities(date)` when that method actually takes `(start, limit)`
+pagination arguments, a mistake that only surfaces once something exercises it.
+"""
+import datetime
+
+import pytest
+
+from services import garmin as garmin_svc
+from services import health as health_svc
+
+
+def day(offset=0):
+    return (datetime.date.today() - datetime.timedelta(days=offset)).isoformat()
+
+
+def summary(steps=8000, rhr=60, stress=40, kcal=2200):
+    return {
+        "totalSteps": steps,
+        "restingHeartRate": rhr,
+        "averageStressLevel": stress,
+        "totalKilocalories": kcal,
+    }
+
+
+def sleep(hours=7.5, score=82):
+    return {
+        "dailySleepDTO": {
+            "sleepTimeSeconds": int(hours * 3600),
+            "sleepScores": {"overall": {"value": score}},
+        }
+    }
+
+
+def hrv(value=48):
+    return {"hrvSummary": {"lastNightAvg": value}}
+
+
+def activity(activity_id=1001, type_key="running", duration=1800):
+    return {
+        "activityId": activity_id,
+        "activityType": {"typeKey": type_key},
+        "startTimeLocal": f"{day()}T07:00:00",
+        "duration": duration,
+        "distance": 5000.0,
+        "calories": 320.0,
+        "averageHR": 145,
+        "maxHR": 168,
+    }
+
+
+class StubClient:
+    """Stands in for garminconnect.Garmin, recording how it was called."""
+
+    def __init__(self, summaries=None, sleeps=None, hrvs=None, activities=None,
+                 fail_days=(), fail_activities=False):
+        self._summaries = summaries if summaries is not None else {}
+        self._sleeps = sleeps if sleeps is not None else {}
+        self._hrvs = hrvs if hrvs is not None else {}
+        self._activities = activities if activities is not None else []
+        self._fail_days = set(fail_days)
+        self._fail_activities = fail_activities
+        self.calls = []
+
+    def get_user_summary(self, cdate):
+        self.calls.append(("summary", cdate))
+        if cdate in self._fail_days:
+            raise RuntimeError(f"upstream error for {cdate}")
+        return self._summaries.get(cdate, summary())
+
+    def get_sleep_data(self, cdate):
+        self.calls.append(("sleep", cdate))
+        return self._sleeps.get(cdate, sleep())
+
+    def get_hrv_data(self, cdate):
+        self.calls.append(("hrv", cdate))
+        return self._hrvs.get(cdate, hrv())
+
+    def get_activities_by_date(self, startdate, enddate, activitytype=None):
+        self.calls.append(("activities", startdate, enddate))
+        if self._fail_activities:
+            raise RuntimeError("activities endpoint down")
+        return self._activities
+
+
+CREDS = {"garminEmail": "g@example.com", "garminPassword": "pw"}
+
+
+class TestHappyPath:
+    def test_reports_success(self, db, user):
+        out = garmin_svc.sync_data(user["id"], CREDS, days=3, client=StubClient())
+        assert out["status"] == "success"
+        assert out["recordsSynced"] == 3
+
+    def test_stores_the_days(self, db, user):
+        garmin_svc.sync_data(user["id"], CREDS, days=3, client=StubClient())
+        rows = health_svc.get_summary(user["id"])
+        assert len(rows) == 3
+
+    def test_maps_every_metric(self, db, user):
+        client = StubClient(
+            summaries={day(): summary(steps=9500, rhr=57, stress=33, kcal=2450)},
+            sleeps={day(): sleep(hours=8.0, score=91)},
+            hrvs={day(): hrv(52)},
+        )
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+        row = health_svc.get_summary(user["id"])[0]
+
+        assert row["steps"] == 9500
+        assert row["heartRate"] == 57
+        assert row["stress"] == 33
+        assert row["caloriesBurned"] == 2450
+        assert row["heartRateVariability"] == 52
+        assert row["sleep"] == {"duration": 8.0, "quality": 91}
+
+    def test_sleep_and_hrv_come_from_their_own_endpoints(self, db, user):
+        """Regression: both live outside get_user_summary. Reading only the
+        summary recorded every night as having no sleep data."""
+        client = StubClient()
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+
+        kinds = {c[0] for c in client.calls}
+        assert "sleep" in kinds
+        assert "hrv" in kinds
+
+    def test_seconds_are_converted_to_hours(self, db, user):
+        client = StubClient(sleeps={day(): sleep(hours=6.5)})
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+        assert health_svc.get_summary(user["id"])[0]["sleep"]["duration"] == 6.5
+
+
+class TestActivities:
+    def test_fetched_by_date_range_in_one_call(self, db, user):
+        """Regression: the old code called get_activities(date), but that
+        method takes (start, limit) pagination arguments, not a date."""
+        client = StubClient(activities=[activity()])
+        garmin_svc.sync_data(user["id"], CREDS, days=7, client=client)
+
+        activity_calls = [c for c in client.calls if c[0] == "activities"]
+        assert len(activity_calls) == 1, "one range call, not one call per day"
+        _, start, end = activity_calls[0]
+        assert start == day(6) and end == day(0)
+
+    def test_stored_with_fields_mapped(self, db, user):
+        garmin_svc.sync_data(
+            user["id"], CREDS, days=1, client=StubClient(activities=[activity()])
+        )
+        rows = health_svc.get_activities(user["id"])
+        assert len(rows) == 1
+        assert rows[0]["activity_type"] == "running"
+        assert rows[0]["heart_rate_average"] == 145
+
+    def test_count_is_reported(self, db, user):
+        client = StubClient(activities=[activity(1), activity(2)])
+        out = garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+        assert out["activitiesSynced"] == 2
+
+    def test_resync_does_not_duplicate(self, db, user):
+        """Garmin activity ids are stable, so a re-synced window must skip
+        what is already stored."""
+        client = StubClient(activities=[activity(1001)])
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+        out = garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+
+        assert len(health_svc.get_activities(user["id"])) == 1
+        assert out["activitiesSynced"] == 0
+
+    def test_end_time_derived_from_duration(self, db, user):
+        client = StubClient(activities=[activity(duration=1800)])
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+        row = health_svc.get_activities(user["id"])[0]
+        assert row["start_time"] != row["end_time"]
+
+    def test_failure_does_not_lose_the_daily_data(self, db, user):
+        out = garmin_svc.sync_data(
+            user["id"], CREDS, days=2, client=StubClient(fail_activities=True)
+        )
+        assert out["status"] == "success"
+        assert len(health_svc.get_summary(user["id"])) == 2
+
+
+class TestResync:
+    def test_same_day_is_updated_not_duplicated(self, db, user):
+        garmin_svc.sync_data(
+            user["id"], CREDS, days=1,
+            client=StubClient(summaries={day(): summary(steps=5000)}),
+        )
+        garmin_svc.sync_data(
+            user["id"], CREDS, days=1,
+            client=StubClient(summaries={day(): summary(steps=9000)}),
+        )
+        rows = health_svc.get_summary(user["id"])
+        assert len(rows) == 1
+        assert rows[0]["steps"] == 9000
+
+
+class TestPartialAndTotalFailure:
+    def test_one_bad_day_is_skipped_not_fatal(self, db, user):
+        client = StubClient(fail_days=[day(1)])
+        out = garmin_svc.sync_data(user["id"], CREDS, days=3, client=client)
+
+        assert out["status"] == "success"
+        assert out["recordsSynced"] == 2
+        assert "跳过" in out["message"]
+
+    def test_every_day_failing_is_reported_as_an_error(self, db, user):
+        """A systemic failure reported as a clean success would hide it."""
+        client = StubClient(fail_days=[day(0), day(1), day(2)])
+        out = garmin_svc.sync_data(user["id"], CREDS, days=3, client=client)
+
+        assert out["status"] == "error"
+        assert out["recordsSynced"] == 0
+
+    def test_login_failure_is_reported(self, db, user, monkeypatch):
+        def boom(_creds):
+            raise RuntimeError("401 Unauthorized")
+
+        monkeypatch.setattr(garmin_svc, "_connect", boom)
+        out = garmin_svc.sync_data(user["id"], CREDS, days=1)
+
+        assert out["status"] == "error"
+        assert "401" in out["message"]
+
+    def test_days_without_data_are_not_stored(self, db, user):
+        """Garmin returns all-None for a day it has nothing for; an empty row
+        would just have to be filtered back out by every read endpoint."""
+        client = StubClient(
+            summaries={day(): {}}, sleeps={day(): {}}, hrvs={day(): {}}
+        )
+        out = garmin_svc.sync_data(user["id"], CREDS, days=1, client=client)
+        assert out["recordsSynced"] == 0
+        assert health_svc.get_summary(user["id"]) == []
+
+
+class TestSyncStatus:
+    def test_idle_before_any_sync(self, db, user):
+        assert garmin_svc.get_sync_status(user["id"])["status"] == "idle"
+
+    def test_success_leaves_status_idle(self, db, user):
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=StubClient())
+        status = garmin_svc.get_sync_status(user["id"])
+        assert status["status"] == "idle"
+        assert status["recordsSynced"] == 1
+        assert status["lastSyncTime"]
+
+    def test_total_failure_leaves_status_error(self, db, user):
+        garmin_svc.sync_data(
+            user["id"], CREDS, days=2, client=StubClient(fail_days=[day(0), day(1)])
+        )
+        status = garmin_svc.get_sync_status(user["id"])
+        assert status["status"] == "error"
+        assert status["lastError"]
+
+    def test_a_later_success_clears_the_error(self, db, user):
+        garmin_svc.sync_data(
+            user["id"], CREDS, days=1, client=StubClient(fail_days=[day(0)])
+        )
+        garmin_svc.sync_data(user["id"], CREDS, days=1, client=StubClient())
+        status = garmin_svc.get_sync_status(user["id"])
+        assert status["status"] == "idle"
+        assert not status["lastError"]
+
+
+class TestEndpoint:
+    def test_requires_auth(self, client):
+        assert client.post("/api/garmin/sync", json={}).status_code == 401
+
+    def test_missing_password_is_refused_with_a_reason(self, client, auth):
+        r = client.post("/api/garmin/sync", headers=auth, json={})
+        assert r.status_code == 400
+        assert "garminPassword" in r.get_json()["message"]
+
+    def test_status_endpoint(self, client, auth):
+        r = client.get("/api/garmin/status", headers=auth)
+        assert r.status_code == 200
+        assert r.get_json()["status"] == "idle"

deploy/S99garmin.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+# Garmin Health Lab — DSM boot script.
+# Mirrors the convention already used by S99frpc.sh on this NAS.
+APP=/var/services/homes/ericwyuan/apps/garmin-health-lab
+RUNAS=ericwyuan
+# Kept inside the app dir, not /var/run: the service runs as an unprivileged
+# user, which cannot write there.
+PIDFILE="$APP/app.pid"
+
+start() {
+  if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; then
+    echo "already running (pid $(cat "$PIDFILE"))"
+    return 0
+  fi
+  # Runs as the owning user: the service needs nothing privileged and its
+  # .env holds database and API credentials.
+  # setsid + closed stdio so it survives the invoking shell and never holds
+  # an SSH session open.
+  if [ "$(id -un)" = "$RUNAS" ]; then
+    sh "$APP/start.sh" >/dev/null 2>&1 </dev/null
+  else
+    su - "$RUNAS" -c "sh $APP/start.sh" >/dev/null 2>&1 </dev/null
+  fi
+  sleep 2
+  echo "started (pid $(cat "$PIDFILE" 2>/dev/null))"
+}
+
+stop() {
+  [ -f "$PIDFILE" ] && kill "$(cat "$PIDFILE")" 2>/dev/null
+  rm -f "$PIDFILE"
+  pkill -f "gunicorn.*8123" 2>/dev/null
+  echo "stopped"
+}
+
+case "$1" in
+  start)   start ;;
+  stop)    stop ;;
+  restart) stop; sleep 2; start ;;
+  status)
+    if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; then
+      echo "running (pid $(cat "$PIDFILE"))"
+    else
+      echo "not running"
+    fi ;;
+  *) echo "Usage: $0 {start|stop|restart|status}" ;;
+esac