Sync from GitHub via hub-sync

api/auth-service/alembic/versions/0008_create_run_sensor_records.py

@@ -0,0 +1,73 @@
+"""create persisted wearable running sensor records
+
+Revision ID: 0008_create_run_sensor_records
+Revises: 0007_create_community_tables
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+revision = "0008_create_run_sensor_records"
+down_revision = "0007_create_community_tables"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    if inspector.has_table("run_sensor_records"):
+        return
+
+    op.create_table(
+        "run_sensor_records",
+        sa.Column("run_session_id", sa.BigInteger(), primary_key=True),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column(
+            "sensor_summary",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default=sa.text("'{}'::jsonb"),
+        ),
+        sa.Column(
+            "sensor_samples",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default=sa.text("'[]'::jsonb"),
+        ),
+        sa.Column(
+            "analysis",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default=sa.text("'{}'::jsonb"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.ForeignKeyConstraint(["run_session_id"], ["run_sessions.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+    )
+    op.create_index(
+        "idx_run_sensor_records_user_updated",
+        "run_sensor_records",
+        ["user_id", "updated_at"],
+    )
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    if inspector.has_table("run_sensor_records"):
+        op.drop_index("idx_run_sensor_records_user_updated", table_name="run_sensor_records")
+        op.drop_table("run_sensor_records")

api/auth-service/app/api/v1/endpoints/running_coaching.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_user, get_db
+from app.models.user import User
+from app.services.running_coaching import (
+    build_run_analysis,
+    build_running_profile,
+    ensure_running_coaching_table,
+)
+
+
+router = APIRouter(prefix="/auth/running-coaching", tags=["running-coaching"])
+
+
+def _json_object(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            return {}
+        return parsed if isinstance(parsed, dict) else {}
+    return {}
+
+
+@router.get("/profile")
+def get_running_profile(
+    limit: int = Query(default=12, ge=3, le=30),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Return the user's explainable, sensor-only running profile."""
+
+    ensure_running_coaching_table(db)
+    rows = db.execute(
+        text(
+            """
+            SELECT
+                rsr.sensor_summary,
+                rs.avg_bpm,
+                rs.distance_km,
+                rs.duration_sec,
+                rs.avg_pace_sec_per_km,
+                rs.finished_at
+            FROM run_sensor_records rsr
+            JOIN run_sessions rs ON rs.id = rsr.run_session_id
+            WHERE rsr.user_id = :user_id
+            ORDER BY COALESCE(rs.finished_at, rs.started_at) DESC, rsr.updated_at DESC
+            LIMIT :limit
+            """
+        ),
+        {"user_id": current_user.id, "limit": limit},
+    ).mappings().all()
+
+    records = []
+    for row in rows:
+        records.append(
+            {
+                "sensor_summary": _json_object(row.get("sensor_summary")),
+                "avg_bpm": row.get("avg_bpm"),
+                "distance_km": row.get("distance_km"),
+                "duration_sec": row.get("duration_sec"),
+                "avg_pace_sec_per_km": row.get("avg_pace_sec_per_km"),
+                "finished_at": row.get("finished_at").isoformat()
+                if row.get("finished_at")
+                else None,
+            }
+        )
+
+    return {"profile": build_running_profile(records), "records_considered": len(records)}
+
+
+@router.get("/runs/{run_session_id}")
+def get_run_coaching(
+    run_session_id: int,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    ensure_running_coaching_table(db)
+    row = db.execute(
+        text(
+            """
+            SELECT
+                rs.id,
+                rs.distance_km,
+                rs.duration_sec,
+                rs.avg_pace_sec_per_km,
+                rs.avg_bpm,
+                rsr.sensor_summary,
+                rsr.analysis
+            FROM run_sessions rs
+            LEFT JOIN run_sensor_records rsr ON rsr.run_session_id = rs.id
+            WHERE rs.id = :run_session_id
+              AND rs.user_id = :user_id
+            LIMIT 1
+            """
+        ),
+        {"run_session_id": run_session_id, "user_id": current_user.id},
+    ).mappings().first()
+    if not row:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Run session not found.")
+
+    stored_analysis = _json_object(row.get("analysis"))
+    summary = _json_object(row.get("sensor_summary"))
+    analysis = stored_analysis or build_run_analysis(
+        summary,
+        distance_km=float(row.get("distance_km") or 0),
+        duration_sec=int(row.get("duration_sec") or 0),
+        avg_pace_sec_per_km=row.get("avg_pace_sec_per_km"),
+    )
+    return {
+        "run_session_id": int(row["id"]),
+        "sensor_summary": summary,
+        "analysis": analysis,
+    }

api/auth-service/app/api/v1/endpoints/runs.py

@@ -19,6 +19,11 @@ from app.schemas.run import (
     RunSessionCreateResponse,
     RunSessionRatingUpdate,
 )
+from app.services.running_coaching import (
+    build_run_analysis,
+    build_sensor_summary,
+    ensure_running_coaching_table,
+)
 
 router = APIRouter(prefix="/auth", tags=["runs"])
 
@@ -107,6 +112,68 @@ def _parse_polyline(value: object) -> list[list[float]]:
     return points
 
 
+def _load_recent_watch_sensor_summary(
+    db: Session,
+    *,
+    user_id: int,
+    run_id: str | None,
+    session_id: str | None,
+) -> dict[str, object]:
+    """Use the companion's last persisted snapshot when finish URL has no metrics.
+
+    The snapshot must be fresh and, when supplied, match the native run/session id.
+    That prevents an earlier run's state from being attached to a new record.
+    """
+
+    try:
+        table_name = db.execute(text("SELECT to_regclass('watch_run_live_states')")).scalar()
+        if not table_name:
+            return {}
+        row = db.execute(
+            text(
+                """
+                SELECT payload
+                FROM watch_run_live_states
+                WHERE user_id = :user_id
+                  AND updated_at >= NOW() - INTERVAL '20 minutes'
+                LIMIT 1
+                """
+            ),
+            {"user_id": user_id},
+        ).mappings().first()
+    except SQLAlchemyError:
+        return {}
+
+    if not row:
+        return {}
+    raw_payload = row.get("payload")
+    if isinstance(raw_payload, str):
+        try:
+            raw_payload = json.loads(raw_payload)
+        except json.JSONDecodeError:
+            return {}
+    if not isinstance(raw_payload, dict):
+        return {}
+    state = raw_payload.get("run_state")
+    if not isinstance(state, dict):
+        return {}
+
+    requested_ids = {value for value in (run_id, session_id) if value}
+    state_ids = {
+        str(value)
+        for value in (state.get("run_id"), state.get("session_id"))
+        if value is not None and str(value)
+    }
+    if requested_ids and state_ids and requested_ids.isdisjoint(state_ids):
+        return {}
+
+    form_metrics = state.get("form_metrics")
+    if not isinstance(form_metrics, dict):
+        form_metrics = {}
+    heart_rate = state.get("average_heart_rate") or state.get("current_heart_rate")
+    return build_sensor_summary(form_metrics, [], heart_rate)
+
+
 @router.post("/runs", response_model=RunSessionCreateResponse, status_code=status.HTTP_201_CREATED)
 def create_run_session(
     payload: RunSessionCreate,
@@ -129,8 +196,32 @@ def create_run_session(
     route_id: int | None = None
     normalized_polyline = _normalize_polyline(payload.polyline or [])
     has_map_image_column = _routes_has_map_image_column(db)
+    sensor_samples = [sample.model_dump(exclude_none=True) for sample in payload.sensor_samples]
+    sensor_summary = build_sensor_summary(
+        payload.form_metrics.model_dump(exclude_none=True) if payload.form_metrics else None,
+        sensor_samples,
+        payload.avg_bpm,
+    )
+    if not sensor_summary:
+        sensor_summary = _load_recent_watch_sensor_summary(
+            db,
+            user_id=current_user.id,
+            run_id=payload.run_id,
+            session_id=payload.session_id,
+        )
+    run_analysis = build_run_analysis(
+        sensor_summary,
+        distance_km=payload.distance_km,
+        duration_sec=payload.duration_sec,
+        avg_pace_sec_per_km=payload.avg_pace_sec_per_km,
+    )
 
     try:
+        # The migration formally owns this table.  The idempotent check also lets
+        # the deployed service accept the first companion-app record immediately.
+        if sensor_summary:
+            ensure_running_coaching_table(db)
+
         if len(normalized_polyline) >= 2:
             center_lat = payload.center_lat if payload.center_lat is not None else normalized_polyline[0][0]
             center_lng = payload.center_lng if payload.center_lng is not None else normalized_polyline[0][1]
@@ -287,6 +378,42 @@ def create_run_session(
             },
         ).first()
 
+        if run_row and sensor_summary:
+            db.execute(
+                text(
+                    """
+                    INSERT INTO run_sensor_records (
+                        run_session_id,
+                        user_id,
+                        sensor_summary,
+                        sensor_samples,
+                        analysis,
+                        updated_at
+                    )
+                    VALUES (
+                        :run_session_id,
+                        :user_id,
+                        CAST(:sensor_summary AS jsonb),
+                        CAST(:sensor_samples AS jsonb),
+                        CAST(:analysis AS jsonb),
+                        NOW()
+                    )
+                    ON CONFLICT (run_session_id) DO UPDATE SET
+                        sensor_summary = EXCLUDED.sensor_summary,
+                        sensor_samples = EXCLUDED.sensor_samples,
+                        analysis = EXCLUDED.analysis,
+                        updated_at = NOW()
+                    """
+                ),
+                {
+                    "run_session_id": int(run_row[0]),
+                    "user_id": current_user.id,
+                    "sensor_summary": json.dumps(sensor_summary, ensure_ascii=False),
+                    "sensor_samples": json.dumps(sensor_samples, ensure_ascii=False),
+                    "analysis": json.dumps(run_analysis, ensure_ascii=False),
+                },
+            )
+
         db.commit()
     except SQLAlchemyError as exc:
         db.rollback()
@@ -301,7 +428,11 @@ def create_run_session(
             detail="Failed to save run session.",
         )
 
-    return RunSessionCreateResponse(run_session_id=int(run_row[0]), route_id=route_id)
+    return RunSessionCreateResponse(
+        run_session_id=int(run_row[0]),
+        route_id=route_id,
+        run_analysis=run_analysis,
+    )
 
 
 @router.patch("/runs/{run_session_id}/rating", status_code=status.HTTP_204_NO_CONTENT)

api/auth-service/app/api/v1/endpoints/watch_run.py

@@ -5,7 +5,7 @@ import threading
 from datetime import datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 from sqlalchemy import text
 from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.orm import Session
@@ -47,6 +47,8 @@ def _normalize_point(value: object) -> list[float] | None:
 class WatchRunLiveState(BaseModel):
     is_running: bool
     is_paused: bool = False
+    run_id: str | None = Field(default=None, max_length=160)
+    session_id: str | None = Field(default=None, max_length=160)
     elapsed_sec: int = Field(default=0, ge=0)
     distance_meters: float = Field(default=0, ge=0)
     distance_km: float | None = Field(default=None, ge=0)
@@ -62,9 +64,28 @@ class WatchRunLiveState(BaseModel):
     current_position: LatLng | None = None
     target_route: list[list[float]] = Field(default_factory=list)
     actual_route: list[list[float]] = Field(default_factory=list)
+    form_metrics: dict[str, float | int | bool] = Field(default_factory=dict)
     sync_status: str = Field(default="sync_ok", max_length=32)
     updated_at_epoch_ms: int | None = Field(default=None, ge=0)
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_companion_field_names(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        normalized = dict(value)
+        aliases = {
+            "runId": "run_id",
+            "sessionId": "session_id",
+            "formMetrics": "form_metrics",
+            "currentHeartRate": "current_heart_rate",
+            "averageHeartRate": "average_heart_rate",
+        }
+        for source, destination in aliases.items():
+            if destination not in normalized and source in normalized:
+                normalized[destination] = normalized[source]
+        return normalized
+
     @field_validator("current_position", mode="before")
     @classmethod
     def normalize_current_position(cls, value: object) -> object:
@@ -89,6 +110,49 @@ class WatchRunLiveState(BaseModel):
             normalized.append(point)
         return normalized
 
+    @field_validator("form_metrics", mode="before")
+    @classmethod
+    def normalize_form_metrics(cls, value: object) -> dict[str, float | int | bool]:
+        if not isinstance(value, dict):
+            return {}
+        aliases = {
+            "accelerometerAvailable": "accelerometer_available",
+            "totalMotionSamples": "sample_count",
+            "estimatedCadenceSpm": "avg_cadence_spm",
+            "cadenceSpm": "avg_cadence_spm",
+            "groundContactTimeMs": "avg_ground_contact_time_ms",
+            "flightTimeMs": "avg_flight_time_ms",
+            "verticalOscillationCm": "avg_vertical_oscillation_cm",
+            "leftRightAsymmetryPct": "avg_left_right_asymmetry_pct",
+        }
+        normalized: dict[str, float | int | bool] = {}
+        allowed = {
+            "accelerometer_available",
+            "sample_count",
+            "avg_cadence_spm",
+            "avg_ground_contact_time_ms",
+            "avg_flight_time_ms",
+            "avg_vertical_oscillation_cm",
+            "avg_left_right_asymmetry_pct",
+            "heart_rate_rise_bpm",
+            "pace_variability_pct",
+        }
+        for raw_key, raw_value in value.items():
+            key = aliases.get(str(raw_key), str(raw_key))
+            if key not in allowed:
+                continue
+            if key == "accelerometer_available":
+                normalized[key] = bool(raw_value)
+                continue
+            try:
+                numeric = float(raw_value)
+            except (TypeError, ValueError):
+                continue
+            if numeric < 0 or numeric > 200_000:
+                continue
+            normalized[key] = int(round(numeric)) if key == "sample_count" else round(numeric, 2)
+        return normalized
+
 
 class WatchRunLiveStateEnvelope(BaseModel):
     run_state: WatchRunLiveState
@@ -138,9 +202,8 @@ def _to_envelope_payload(payload: WatchRunLiveStateEnvelope) -> dict:
 
 
 def _normalize_run_state_fields(state: WatchRunLiveState) -> None:
-    # Heart-rate must stay watch-local unless explicitly required.
-    state.current_heart_rate = None
-    state.average_heart_rate = None
+    # This is an authenticated, user-authorized snapshot. Keep heart-rate and
+    # form values so the browser can coach from server-persisted wearable data.
 
     if state.distance_km is None:
         state.distance_km = round(max(0.0, float(state.distance_meters)) / 1000.0, 3)

api/auth-service/app/api/v1/router.py

@@ -1,10 +1,20 @@
 from fastapi import APIRouter
 
-from app.api.v1.endpoints import auth, community, runs, stats, watch_auth, watch_routes, watch_run
+from app.api.v1.endpoints import (
+    auth,
+    community,
+    running_coaching,
+    runs,
+    stats,
+    watch_auth,
+    watch_routes,
+    watch_run,
+)
 
 api_router = APIRouter()
 api_router.include_router(auth.router)
 api_router.include_router(runs.router)
+api_router.include_router(running_coaching.router)
 api_router.include_router(stats.router)
 api_router.include_router(community.router)
 api_router.include_router(watch_routes.router)

api/auth-service/app/schemas/run.py

@@ -1,6 +1,90 @@
 from datetime import datetime
+from typing import Any
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class RunningFormMetrics(BaseModel):
+    """Sensor-derived running form summary supplied by the companion app.
+
+    The watch calculates these values from accelerometer/heart-rate samples.  They
+    are deliberately optional because every Wear OS device and permission setup
+    does not expose every signal.
+    """
+
+    accelerometer_available: bool | None = None
+    sample_count: int | None = Field(default=None, ge=0, le=200_000)
+    avg_heart_rate_bpm: int | None = Field(default=None, ge=0, le=260)
+    avg_cadence_spm: float | None = Field(default=None, ge=40, le=300)
+    avg_ground_contact_time_ms: float | None = Field(default=None, ge=20, le=1_500)
+    avg_flight_time_ms: float | None = Field(default=None, ge=0, le=1_000)
+    avg_vertical_oscillation_cm: float | None = Field(default=None, ge=0, le=100)
+    avg_left_right_asymmetry_pct: float | None = Field(default=None, ge=0, le=100)
+    heart_rate_rise_bpm: float | None = Field(default=None, ge=-100, le=150)
+    pace_variability_pct: float | None = Field(default=None, ge=0, le=200)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_companion_field_names(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        normalized = dict(value)
+        aliases = {
+            "accelerometerAvailable": "accelerometer_available",
+            "totalMotionSamples": "sample_count",
+            "estimatedSampleCount": "sample_count",
+            "averageHeartRateBpm": "avg_heart_rate_bpm",
+            "avgHeartRateBpm": "avg_heart_rate_bpm",
+            "estimatedCadenceSpm": "avg_cadence_spm",
+            "cadenceSpm": "avg_cadence_spm",
+            "groundContactTimeMs": "avg_ground_contact_time_ms",
+            "estimatedGroundContactTimeMs": "avg_ground_contact_time_ms",
+            "flightTimeMs": "avg_flight_time_ms",
+            "estimatedFlightTimeMs": "avg_flight_time_ms",
+            "verticalOscillationCm": "avg_vertical_oscillation_cm",
+            "estimatedVerticalOscillationCm": "avg_vertical_oscillation_cm",
+            "leftRightAsymmetryPct": "avg_left_right_asymmetry_pct",
+            "estimatedLeftRightAsymmetryPct": "avg_left_right_asymmetry_pct",
+            "heartRateRiseBpm": "heart_rate_rise_bpm",
+            "paceVariabilityPct": "pace_variability_pct",
+        }
+        for source, destination in aliases.items():
+            if destination not in normalized and source in normalized:
+                normalized[destination] = normalized[source]
+        return normalized
+
+
+class RunningSensorSample(BaseModel):
+    elapsed_sec: int | None = Field(default=None, ge=0, le=172_800)
+    heart_rate_bpm: int | None = Field(default=None, ge=0, le=260)
+    pace_sec_per_km: int | None = Field(default=None, ge=0, le=7_200)
+    cadence_spm: float | None = Field(default=None, ge=40, le=300)
+    ground_contact_time_ms: float | None = Field(default=None, ge=20, le=1_500)
+    flight_time_ms: float | None = Field(default=None, ge=0, le=1_000)
+    vertical_oscillation_cm: float | None = Field(default=None, ge=0, le=100)
+    left_right_asymmetry_pct: float | None = Field(default=None, ge=0, le=100)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_companion_field_names(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        normalized = dict(value)
+        aliases = {
+            "elapsedSec": "elapsed_sec",
+            "heartRateBpm": "heart_rate_bpm",
+            "currentHeartRate": "heart_rate_bpm",
+            "paceSecPerKm": "pace_sec_per_km",
+            "cadenceSpm": "cadence_spm",
+            "groundContactTimeMs": "ground_contact_time_ms",
+            "flightTimeMs": "flight_time_ms",
+            "verticalOscillationCm": "vertical_oscillation_cm",
+            "leftRightAsymmetryPct": "left_right_asymmetry_pct",
+        }
+        for source, destination in aliases.items():
+            if destination not in normalized and source in normalized:
+                normalized[destination] = normalized[source]
+        return normalized
 
 
 class RunSessionCreate(BaseModel):
@@ -8,6 +92,8 @@ class RunSessionCreate(BaseModel):
     animal_label: str | None = Field(default=None, max_length=40)
     source: str = Field(default="nearby")
     place_text: str | None = None
+    run_id: str | None = Field(default=None, max_length=160)
+    session_id: str | None = Field(default=None, max_length=160)
     started_at: datetime | None = None
     finished_at: datetime | None = None
     duration_sec: int = Field(..., ge=0)
@@ -22,6 +108,30 @@ class RunSessionCreate(BaseModel):
     center_lng: float | None = Field(default=None, ge=-180, le=180)
     polyline: list[list[float]] | None = None
     map_image_url: str | None = Field(default=None, max_length=500)
+    form_metrics: RunningFormMetrics | None = None
+    sensor_samples: list[RunningSensorSample] = Field(default_factory=list, max_length=3_600)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_sensor_payload_names(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        normalized = dict(value)
+        if "form_metrics" not in normalized:
+            for key in ("formMetrics", "sensor_summary", "sensorSummary"):
+                if key in normalized:
+                    normalized["form_metrics"] = normalized[key]
+                    break
+        if "sensor_samples" not in normalized:
+            for key in ("sensorSamples", "samples"):
+                if key in normalized:
+                    normalized["sensor_samples"] = normalized[key]
+                    break
+        aliases = {"runId": "run_id", "sessionId": "session_id"}
+        for source, destination in aliases.items():
+            if destination not in normalized and source in normalized:
+                normalized[destination] = normalized[source]
+        return normalized
 
     @field_validator("source")
     @classmethod
@@ -54,6 +164,7 @@ class RunSessionCreate(BaseModel):
 class RunSessionCreateResponse(BaseModel):
     run_session_id: int
     route_id: int | None = None
+    run_analysis: dict[str, Any] | None = None
 
 
 class RunSessionRatingUpdate(BaseModel):

api/auth-service/app/services/running_coaching.py

@@ -0,0 +1,531 @@
+"""Deterministic running-form coaching based on persisted wearable summaries.
+
+The service intentionally uses conservative wording.  Wearable values are estimates,
+not a diagnosis or a substitute for professional medical advice.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import threading
+from statistics import mean, pstdev
+from typing import TYPE_CHECKING, Any, Iterable
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+
+_schema_ready = False
+_schema_lock = threading.Lock()
+
+_SAMPLE_TO_SUMMARY = {
+    "heart_rate_bpm": "avg_heart_rate_bpm",
+    "cadence_spm": "avg_cadence_spm",
+    "ground_contact_time_ms": "avg_ground_contact_time_ms",
+    "flight_time_ms": "avg_flight_time_ms",
+    "vertical_oscillation_cm": "avg_vertical_oscillation_cm",
+    "left_right_asymmetry_pct": "avg_left_right_asymmetry_pct",
+}
+
+
+def ensure_running_coaching_table(db: Session) -> None:
+    """Make the feature deploy-safe while Alembic is applied on the next deploy."""
+
+    from sqlalchemy import text
+    from sqlalchemy.exc import SQLAlchemyError
+
+    global _schema_ready
+    if _schema_ready:
+        return
+
+    with _schema_lock:
+        if _schema_ready:
+            return
+        try:
+            db.execute(
+                text(
+                    """
+                    CREATE TABLE IF NOT EXISTS run_sensor_records (
+                        run_session_id BIGINT PRIMARY KEY
+                            REFERENCES run_sessions(id) ON DELETE CASCADE,
+                        user_id INTEGER NOT NULL
+                            REFERENCES users(id) ON DELETE CASCADE,
+                        sensor_summary JSONB NOT NULL DEFAULT '{}'::jsonb,
+                        sensor_samples JSONB NOT NULL DEFAULT '[]'::jsonb,
+                        analysis JSONB NOT NULL DEFAULT '{}'::jsonb,
+                        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                    )
+                    """
+                )
+            )
+            db.execute(
+                text(
+                    """
+                    CREATE INDEX IF NOT EXISTS idx_run_sensor_records_user_updated
+                    ON run_sensor_records (user_id, updated_at DESC)
+                    """
+                )
+            )
+            db.commit()
+            _schema_ready = True
+        except SQLAlchemyError:
+            db.rollback()
+            raise
+
+
+def _number(value: Any) -> float | None:
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if math.isfinite(parsed) else None
+
+
+def _mean(values: Iterable[Any]) -> float | None:
+    numbers = [value for value in (_number(item) for item in values) if value is not None]
+    return mean(numbers) if numbers else None
+
+
+def _round(value: float | None, digits: int = 1) -> float | None:
+    return round(value, digits) if value is not None else None
+
+
+def _compact(values: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def build_sensor_summary(
+    form_metrics: dict[str, Any] | None,
+    sensor_samples: list[dict[str, Any]] | None,
+    avg_bpm: int | None,
+) -> dict[str, Any]:
+    """Fill a compact summary from a native summary and optional raw samples."""
+
+    summary = dict(form_metrics or {})
+    samples = [sample for sample in (sensor_samples or []) if isinstance(sample, dict)]
+    if summary.get("sample_count") is None and samples:
+        summary["sample_count"] = len(samples)
+    if avg_bpm and avg_bpm > 0 and summary.get("avg_heart_rate_bpm") is None:
+        summary["avg_heart_rate_bpm"] = avg_bpm
+
+    for sample_field, summary_field in _SAMPLE_TO_SUMMARY.items():
+        if summary.get(summary_field) is None:
+            value = _mean(sample.get(sample_field) for sample in samples)
+            if value is not None:
+                summary[summary_field] = _round(value)
+
+    heart_rates = [
+        value
+        for value in (_number(sample.get("heart_rate_bpm")) for sample in samples)
+        if value is not None
+    ]
+    if summary.get("heart_rate_rise_bpm") is None and len(heart_rates) >= 8:
+        window = max(2, len(heart_rates) // 4)
+        summary["heart_rate_rise_bpm"] = _round(
+            mean(heart_rates[-window:]) - mean(heart_rates[:window])
+        )
+
+    paces = [
+        value
+        for value in (_number(sample.get("pace_sec_per_km")) for sample in samples)
+        if value is not None and value > 0
+    ]
+    if summary.get("pace_variability_pct") is None and len(paces) >= 5:
+        average_pace = mean(paces)
+        if average_pace > 0:
+            summary["pace_variability_pct"] = _round((pstdev(paces) / average_pace) * 100)
+
+    numeric_fields = {
+        "sample_count": 0,
+        "avg_heart_rate_bpm": 0,
+        "avg_cadence_spm": 1,
+        "avg_ground_contact_time_ms": 1,
+        "avg_flight_time_ms": 1,
+        "avg_vertical_oscillation_cm": 1,
+        "avg_left_right_asymmetry_pct": 1,
+        "heart_rate_rise_bpm": 1,
+        "pace_variability_pct": 1,
+    }
+    for field, digits in numeric_fields.items():
+        value = _number(summary.get(field))
+        if value is None:
+            summary.pop(field, None)
+        elif field == "sample_count":
+            summary[field] = max(0, int(round(value)))
+        else:
+            summary[field] = round(value, digits)
+
+    if summary.get("accelerometer_available") is not None:
+        summary["accelerometer_available"] = bool(summary["accelerometer_available"])
+    return _compact(summary)
+
+
+def _coaching_item(
+    key: str,
+    title: str,
+    message: str,
+    action: str,
+    severity: int,
+) -> dict[str, Any]:
+    return {
+        "key": key,
+        "title": title,
+        "message": message,
+        "action": action,
+        "severity": severity,
+    }
+
+
+def build_run_analysis(
+    summary: dict[str, Any] | None,
+    *,
+    distance_km: float = 0,
+    duration_sec: int = 0,
+    avg_pace_sec_per_km: int | None = None,
+) -> dict[str, Any]:
+    """Return a small, actionable after-run coaching result."""
+
+    metrics = build_sensor_summary(summary, [], None)
+    sample_count = int(metrics.get("sample_count") or 0)
+    has_motion = any(
+        key in metrics
+        for key in (
+            "avg_cadence_spm",
+            "avg_ground_contact_time_ms",
+            "avg_vertical_oscillation_cm",
+            "avg_left_right_asymmetry_pct",
+        )
+    )
+    has_heart = "avg_heart_rate_bpm" in metrics
+
+    if not has_motion and not has_heart:
+        return {
+            "status": "waiting_for_sensor_data",
+            "headline": "센서 기반 러닝 코칭을 준비 중이에요.",
+            "strengths": [],
+            "focus": [],
+            "next_action": "워치의 신체 활동·심박 권한을 허용한 뒤 러닝을 기록해 주세요.",
+            "sample_count": sample_count,
+            "disclaimer": "워치 센서의 추정값을 바탕으로 한 러닝 안내입니다.",
+        }
+
+    strengths: list[dict[str, Any]] = []
+    focus: list[dict[str, Any]] = []
+
+    heart_rise = _number(metrics.get("heart_rate_rise_bpm"))
+    avg_hr = _number(metrics.get("avg_heart_rate_bpm"))
+    if heart_rise is not None and heart_rise >= 12 and (avg_hr or 0) >= 120:
+        focus.append(
+            _coaching_item(
+                "heart_rate",
+                "후반 강도",
+                f"후반 심박이 약 {heart_rise:.0f} BPM 올라갔어요.",
+                "다음 구간은 보폭을 조금 줄이고, 문장으로 말할 수 있는 호흡을 유지해 보세요.",
+                4,
+            )
+        )
+    elif avg_hr is not None:
+        strengths.append(
+            {
+                "key": "heart_rate",
+                "title": "러닝 강도 기록",
+                "message": f"평균 심박 {avg_hr:.0f} BPM을 다음 러닝의 비교 기준으로 저장했어요.",
+            }
+        )
+
+    cadence = _number(metrics.get("avg_cadence_spm"))
+    if cadence is not None:
+        if cadence < 150:
+            focus.append(
+                _coaching_item(
+                    "cadence",
+                    "러닝 리듬",
+                    f"평균 케이던스가 {cadence:.0f} SPM으로 낮게 기록됐어요.",
+                    "보폭을 억지로 늘리기보다 발을 짧고 가볍게 옮겨 리듬을 높여 보세요.",
+                    3,
+                )
+            )
+        elif cadence >= 165:
+            strengths.append(
+                {
+                    "key": "cadence",
+                    "title": "안정적인 리듬",
+                    "message": f"평균 케이던스 {cadence:.0f} SPM으로 가벼운 리듬을 유지했어요.",
+                }
+            )
+
+    contact = _number(metrics.get("avg_ground_contact_time_ms"))
+    flight = _number(metrics.get("avg_flight_time_ms"))
+    if contact is not None and contact >= 310:
+        extra = " 체공 시간이 짧게 함께 기록됐어요." if flight is not None and flight < 90 else ""
+        focus.append(
+            _coaching_item(
+                "ground_contact",
+                "지면 접촉",
+                f"발이 지면에 머문 추정 시간이 {contact:.0f}ms로 길어졌어요.{extra}",
+                "발밑을 오래 누르기보다 지면을 가볍게 밀고 다음 발로 넘어가 보세요.",
+                2,
+            )
+        )
+    elif contact is not None and contact < 290:
+        strengths.append(
+            {
+                "key": "ground_contact",
+                "title": "가벼운 지면 접촉",
+                "message": f"추정 접지 시간 {contact:.0f}ms로 발의 전환이 가볍게 기록됐어요.",
+            }
+        )
+
+    vertical = _number(metrics.get("avg_vertical_oscillation_cm"))
+    if vertical is not None and vertical >= 10.5:
+        focus.append(
+            _coaching_item(
+                "vertical_oscillation",
+                "상하 움직임",
+                f"상하 움직임이 약 {vertical:.1f}cm로 크게 기록됐어요.",
+                "시선은 정면에 두고, 위로 튀기보다 몸을 앞으로 부드럽게 보내는 데 집중해 보세요.",
+                2,
+            )
+        )
+    elif vertical is not None and vertical <= 8.5:
+        strengths.append(
+            {
+                "key": "vertical_oscillation",
+                "title": "전진 중심 움직임",
+                "message": f"상하 움직임이 약 {vertical:.1f}cm로 안정적으로 기록됐어요.",
+            }
+        )
+
+    asymmetry = _number(metrics.get("avg_left_right_asymmetry_pct"))
+    if asymmetry is not None and asymmetry >= 8:
+        focus.append(
+            _coaching_item(
+                "asymmetry",
+                "좌우 균형",
+                f"좌우 비대칭 추정치가 {asymmetry:.1f}%로 반복됐어요.",
+                "피로가 쌓인 구간에는 속도를 낮추고, 워치 착용 위치도 함께 확인해 보세요.",
+                3,
+            )
+        )
+    elif asymmetry is not None and asymmetry <= 4:
+        strengths.append(
+            {
+                "key": "asymmetry",
+                "title": "좌우 리듬",
+                "message": f"좌우 비대칭 추정치 {asymmetry:.1f}%로 균형 있게 기록됐어요.",
+            }
+        )
+
+    pace_variability = _number(metrics.get("pace_variability_pct"))
+    if pace_variability is not None and pace_variability >= 18:
+        focus.append(
+            _coaching_item(
+                "pace_stability",
+                "페이스 변화",
+                f"구간별 페이스 변화가 약 {pace_variability:.0f}%로 컸어요.",
+                "첫 5분은 한 단계 여유 있는 속도로 시작해 페이스 변화를 줄여 보세요.",
+                1,
+            )
+        )
+
+    focus.sort(key=lambda item: int(item["severity"]), reverse=True)
+    strengths = strengths[:2]
+    focus = focus[:2]
+    pace_text = ""
+    if avg_pace_sec_per_km and avg_pace_sec_per_km > 0:
+        pace_text = f" 평균 페이스 {avg_pace_sec_per_km // 60}'{avg_pace_sec_per_km % 60:02d}''와 함께 비교해 볼 수 있어요."
+
+    status = "ready" if has_motion and sample_count >= 20 else "partial"
+    headline = (
+        "이번 러닝에서 가장 먼저 다듬을 한 가지를 골라 안내했어요."
+        if focus
+        else "센서로 확인한 러닝 리듬이 전반적으로 안정적이에요."
+    )
+    return {
+        "status": status,
+        "headline": headline + pace_text,
+        "strengths": strengths,
+        "focus": focus,
+        "next_action": (
+            focus[0]["action"]
+            if focus
+            else "다음 러닝에서도 같은 센서 권한을 유지해 내 리듬의 기준을 쌓아 보세요."
+        ),
+        "sample_count": sample_count,
+        "disclaimer": "워치 센서의 추정값을 바탕으로 한 러닝 안내입니다. 통증·어지럼 등 이상이 있으면 운동을 멈추고 휴식하세요.",
+        "metrics": metrics,
+    }
+
+
+def _trend(
+    values: list[float],
+    *,
+    lower_is_better: bool,
+    tolerance: float,
+) -> str:
+    if len(values) < 4:
+        return "collecting"
+    split = max(1, len(values) // 2)
+    older = mean(values[:split])
+    newer = mean(values[split:])
+    delta = newer - older
+    if abs(delta) <= tolerance:
+        return "stable"
+    improved = delta < 0 if lower_is_better else delta > 0
+    return "improving" if improved else "needs_attention"
+
+
+def build_running_profile(records: list[dict[str, Any]]) -> dict[str, Any]:
+    """Build an explainable long-term profile from the latest persisted runs."""
+
+    normalized: list[dict[str, Any]] = []
+    for record in reversed(records):
+        raw_summary = record.get("sensor_summary") or record.get("summary") or {}
+        if isinstance(raw_summary, str):
+            try:
+                raw_summary = json.loads(raw_summary)
+            except json.JSONDecodeError:
+                raw_summary = {}
+        if not isinstance(raw_summary, dict):
+            continue
+        summary = build_sensor_summary(raw_summary, [], record.get("avg_bpm"))
+        if any(
+            key in summary
+            for key in (
+                "avg_cadence_spm",
+                "avg_ground_contact_time_ms",
+                "avg_vertical_oscillation_cm",
+                "avg_left_right_asymmetry_pct",
+                "avg_heart_rate_bpm",
+            )
+        ):
+            normalized.append(summary)
+
+    sample_size = len(normalized)
+    if sample_size == 0:
+        return {
+            "status": "waiting_for_sensor_data",
+            "sample_size": 0,
+            "required_sample_size": 3,
+            "headline": "센서가 기록된 러닝을 쌓으면 나만의 러닝 특성을 보여드릴게요.",
+            "characteristics": [],
+            "next_focus": None,
+            "recommendations": ["워치의 신체 활동·심박 권한을 허용하고 러닝을 3회 이상 기록해 주세요."],
+        }
+
+    config = [
+        (
+            "cadence",
+            "러닝 리듬",
+            "avg_cadence_spm",
+            "SPM",
+            False,
+            4.0,
+            lambda value: value < 150,
+            "보폭을 조금 줄이고 가벼운 발걸음으로 리듬을 맞춰 보세요.",
+        ),
+        (
+            "ground_contact",
+            "지면 접촉",
+            "avg_ground_contact_time_ms",
+            "ms",
+            True,
+            12.0,
+            lambda value: value >= 310,
+            "발을 오래 누르기보다 지면을 가볍게 밀고 다음 발로 넘어가 보세요.",
+        ),
+        (
+            "vertical_oscillation",
+            "상하 움직임",
+            "avg_vertical_oscillation_cm",
+            "cm",
+            True,
+            0.5,
+            lambda value: value >= 10.5,
+            "시선을 정면에 두고 위로 튀기보다 앞으로 나아가는 리듬을 만들어 보세요.",
+        ),
+        (
+            "asymmetry",
+            "좌우 균형",
+            "avg_left_right_asymmetry_pct",
+            "%",
+            True,
+            0.8,
+            lambda value: value >= 8,
+            "피로한 날에는 속도를 낮추고 양쪽 발이 같은 리듬인지 확인해 보세요.",
+        ),
+    ]
+
+    characteristics: list[dict[str, Any]] = []
+    candidates: list[tuple[float, str, str]] = []
+    for key, title, field, unit, lower_is_better, tolerance, needs_work, action in config:
+        values = [
+            value
+            for value in (_number(item.get(field)) for item in normalized)
+            if value is not None
+        ]
+        if not values:
+            continue
+        average = mean(values)
+        flagged_ratio = sum(1 for value in values if needs_work(value)) / len(values)
+        characteristics.append(
+            {
+                "key": key,
+                "title": title,
+                "average": _round(average),
+                "unit": unit,
+                "recorded_runs": len(values),
+                "trend": _trend(values, lower_is_better=lower_is_better, tolerance=tolerance),
+                "summary": f"최근 {len(values)}회 평균 {average:.1f}{unit}",
+            }
+        )
+        if flagged_ratio > 0:
+            candidates.append((flagged_ratio, title, action))
+
+    heart_values = [
+        value
+        for value in (_number(item.get("avg_heart_rate_bpm")) for item in normalized)
+        if value is not None
+    ]
+    if heart_values:
+        avg_heart = mean(heart_values)
+        characteristics.append(
+            {
+                "key": "heart_rate",
+                "title": "러닝 강도 기준",
+                "average": _round(avg_heart),
+                "unit": "BPM",
+                "recorded_runs": len(heart_values),
+                "trend": "collecting" if len(heart_values) < 4 else "stable",
+                "summary": f"최근 {len(heart_values)}회 평균 {avg_heart:.0f}BPM",
+            }
+        )
+
+    candidates.sort(key=lambda item: item[0], reverse=True)
+    next_focus = None
+    recommendations: list[str] = []
+    if candidates:
+        _, title, action = candidates[0]
+        next_focus = {"title": title, "action": action}
+        recommendations.append(action)
+    else:
+        recommendations.append("현재 리듬을 유지하면서 같은 조건의 러닝 데이터를 더 쌓아 보세요.")
+    if sample_size < 3:
+        recommendations.append("3회 이상 기록되면 최근 변화 추세도 함께 보여드릴 수 있어요.")
+
+    return {
+        "status": "ready" if sample_size >= 3 else "collecting",
+        "sample_size": sample_size,
+        "required_sample_size": 3,
+        "headline": (
+            "최근 러닝의 반복되는 리듬을 바탕으로 다음 한 가지를 제안해요."
+            if sample_size >= 3
+            else "아직 표본을 모으는 중이에요. 지금 기록도 다음 코칭의 기준이 됩니다."
+        ),
+        "characteristics": characteristics,
+        "next_focus": next_focus,
+        "recommendations": recommendations,
+        "disclaimer": "워치 센서의 추정값을 비교한 러닝 특성입니다. 건강 상태 판단에는 사용하지 마세요.",
+    }

api/auth-service/tests/test_running_coaching.py

@@ -0,0 +1,53 @@
+import unittest
+
+from app.services.running_coaching import build_run_analysis, build_running_profile
+
+
+class RunningCoachingTests(unittest.TestCase):
+    def test_prioritizes_high_load_and_low_cadence(self):
+        analysis = build_run_analysis(
+            {
+                "sample_count": 80,
+                "avg_heart_rate_bpm": 154,
+                "heart_rate_rise_bpm": 16,
+                "avg_cadence_spm": 142,
+                "avg_ground_contact_time_ms": 330,
+                "avg_vertical_oscillation_cm": 11.4,
+                "avg_left_right_asymmetry_pct": 9.2,
+            }
+        )
+
+        self.assertEqual([item["key"] for item in analysis["focus"]], ["heart_rate", "cadence"])
+        self.assertIn("보폭", analysis["focus"][1]["action"])
+
+    def test_does_not_warn_when_form_values_are_stable(self):
+        analysis = build_run_analysis(
+            {
+                "sample_count": 80,
+                "avg_heart_rate_bpm": 148,
+                "avg_cadence_spm": 170,
+                "avg_ground_contact_time_ms": 280,
+                "avg_vertical_oscillation_cm": 8.0,
+                "avg_left_right_asymmetry_pct": 3.1,
+            }
+        )
+
+        self.assertEqual(analysis["focus"], [])
+        self.assertGreaterEqual(len(analysis["strengths"]), 2)
+
+    def test_profile_uses_repeated_sensor_records(self):
+        profile = build_running_profile(
+            [
+                {"sensor_summary": {"avg_cadence_spm": 142, "avg_ground_contact_time_ms": 325}},
+                {"sensor_summary": {"avg_cadence_spm": 145, "avg_ground_contact_time_ms": 320}},
+                {"sensor_summary": {"avg_cadence_spm": 148, "avg_ground_contact_time_ms": 315}},
+            ]
+        )
+
+        self.assertEqual(profile["status"], "ready")
+        self.assertEqual(profile["next_focus"]["title"], "러닝 리듬")
+        self.assertEqual(profile["sample_size"], 3)
+
+
+if __name__ == "__main__":
+    unittest.main()

main/app/_components/TopBar.tsx

@@ -20,6 +20,7 @@ const menuSections = [
       { label: "총 이동 거리", href: "/stats/total-length" },
       { label: "총 시간", href: "/stats/total-time" },
       { label: "완주 캘린더", href: "/stats/complete-number" },
+      { label: "나의 러닝 특성", href: "/running-profile" },
     ],
   },
   { title: "저장된 루트", href: "/saved-routes", items: [] },

main/app/_utils/runningCoaching.ts

@@ -0,0 +1,156 @@
+export type RunningFormMetrics = {
+  accelerometer_available?: boolean;
+  sample_count?: number;
+  avg_heart_rate_bpm?: number;
+  avg_cadence_spm?: number;
+  avg_ground_contact_time_ms?: number;
+  avg_flight_time_ms?: number;
+  avg_vertical_oscillation_cm?: number;
+  avg_left_right_asymmetry_pct?: number;
+  heart_rate_rise_bpm?: number;
+  pace_variability_pct?: number;
+};
+
+export type RunningCoachItem = {
+  key: string;
+  title: string;
+  message: string;
+  action?: string;
+  severity?: number;
+};
+
+export type RunAnalysis = {
+  status: "ready" | "partial" | "waiting_for_sensor_data" | string;
+  headline: string;
+  strengths: RunningCoachItem[];
+  focus: RunningCoachItem[];
+  next_action: string;
+  sample_count: number;
+  disclaimer: string;
+  metrics?: RunningFormMetrics;
+};
+
+export type WatchRunStateForCoaching = {
+  is_running: boolean;
+  is_paused?: boolean;
+  current_heart_rate?: number | null;
+  average_heart_rate?: number | null;
+  form_metrics?: RunningFormMetrics | null;
+};
+
+const FIELD_ALIASES: Record<string, keyof RunningFormMetrics> = {
+  accelerometerAvailable: "accelerometer_available",
+  totalMotionSamples: "sample_count",
+  estimatedSampleCount: "sample_count",
+  averageHeartRateBpm: "avg_heart_rate_bpm",
+  avgHeartRateBpm: "avg_heart_rate_bpm",
+  estimatedCadenceSpm: "avg_cadence_spm",
+  cadenceSpm: "avg_cadence_spm",
+  groundContactTimeMs: "avg_ground_contact_time_ms",
+  estimatedGroundContactTimeMs: "avg_ground_contact_time_ms",
+  flightTimeMs: "avg_flight_time_ms",
+  estimatedFlightTimeMs: "avg_flight_time_ms",
+  verticalOscillationCm: "avg_vertical_oscillation_cm",
+  estimatedVerticalOscillationCm: "avg_vertical_oscillation_cm",
+  leftRightAsymmetryPct: "avg_left_right_asymmetry_pct",
+  estimatedLeftRightAsymmetryPct: "avg_left_right_asymmetry_pct",
+  heartRateRiseBpm: "heart_rate_rise_bpm",
+  paceVariabilityPct: "pace_variability_pct",
+};
+
+function finiteNumber(value: unknown): number | null {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function parseRunningFormMetrics(raw: string | null): RunningFormMetrics | null {
+  if (!raw) return null;
+  const candidates = [raw];
+  try {
+    candidates.unshift(decodeURIComponent(raw));
+  } catch {
+    // Use the original value if it was not URI encoded.
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate) as unknown;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      const normalized: RunningFormMetrics = {};
+      for (const [rawKey, rawValue] of Object.entries(parsed)) {
+        const key = FIELD_ALIASES[rawKey] ?? (rawKey as keyof RunningFormMetrics);
+        if (key === "accelerometer_available") {
+          normalized[key] = Boolean(rawValue);
+          continue;
+        }
+        const numeric = finiteNumber(rawValue);
+        if (numeric !== null) {
+          normalized[key] = numeric;
+        }
+      }
+      return Object.keys(normalized).length > 0 ? normalized : null;
+    } catch {
+      // Try a once-decoded value before rejecting the URL parameter.
+    }
+  }
+  return null;
+}
+
+export function buildLiveSensorCoachMessage(
+  state: WatchRunStateForCoaching
+): { key: string; message: string } | null {
+  if (!state.is_running || state.is_paused) return null;
+  const metrics = state.form_metrics ?? {};
+  const currentHeartRate = finiteNumber(state.current_heart_rate);
+  const averageHeartRate = finiteNumber(state.average_heart_rate);
+  if (
+    currentHeartRate !== null &&
+    averageHeartRate !== null &&
+    averageHeartRate >= 120 &&
+    currentHeartRate - averageHeartRate >= 12
+  ) {
+    return {
+      key: "heart_rate",
+      message:
+        "현재 심박이 이번 러닝 평균보다 올라갔어요. 보폭을 조금 줄이고 편한 호흡으로 속도를 조절해 보세요.",
+    };
+  }
+
+  const cadence = finiteNumber(metrics.avg_cadence_spm);
+  if (cadence !== null && cadence < 150) {
+    return {
+      key: "cadence",
+      message:
+        "러닝 리듬이 느려졌어요. 보폭을 무리하게 늘리지 말고 발을 짧고 가볍게 옮겨 보세요.",
+    };
+  }
+
+  const asymmetry = finiteNumber(metrics.avg_left_right_asymmetry_pct);
+  if (asymmetry !== null && asymmetry >= 8) {
+    return {
+      key: "asymmetry",
+      message:
+        "좌우 리듬이 한쪽으로 치우쳐 기록되고 있어요. 속도를 조금 낮추고 균형 있는 발걸음을 확인해 보세요.",
+    };
+  }
+
+  const contact = finiteNumber(metrics.avg_ground_contact_time_ms);
+  if (contact !== null && contact >= 310) {
+    return {
+      key: "ground_contact",
+      message:
+        "발이 지면에 머무는 시간이 길어졌어요. 지면을 가볍게 밀고 다음 발로 넘어가 보세요.",
+    };
+  }
+
+  const vertical = finiteNumber(metrics.avg_vertical_oscillation_cm);
+  if (vertical !== null && vertical >= 10.5) {
+    return {
+      key: "vertical_oscillation",
+      message:
+        "위아래 움직임이 커졌어요. 시선은 정면에 두고 앞으로 부드럽게 나아가 보세요.",
+    };
+  }
+
+  return null;
+}

main/app/run/[id]/finish/page.tsx

@@ -7,6 +7,10 @@ import TopBar from "../../../_components/TopBar";
 import LeafletMap from "../../../_components/LeafletMap";
 import { FLOW_KEYS, isUiFlowPermitValid } from "../../../_utils/uiFlowGuard";
 import { isNativeAppEnvironment } from "../../../_utils/nativeWearBridge";
+import {
+  parseRunningFormMetrics,
+  type RunAnalysis,
+} from "../../../_utils/runningCoaching";
 
 const DEFAULT_CENTER: [number, number] = [37.5665, 126.978];
 const MANUAL_CENTER: [number, number] = [35.1796, 129.0756];
@@ -26,6 +30,7 @@ type StoredActual = {
 type RunSessionCreateResponse = {
   run_session_id?: number;
   route_id?: number | null;
+  run_analysis?: RunAnalysis | null;
 };
 
 function parseNumber(value: string | null, fallback = 0): number {
@@ -210,6 +215,8 @@ function RunFinishPageContent() {
   const lngParam = searchParams.get("lng");
   const polylineParam = searchParams.get("polyline");
   const actualPolylineParam = searchParams.get("actualPolyline");
+  const sensorSummaryParam =
+    searchParams.get("sensorSummary") ?? searchParams.get("formMetrics");
   const nativeResult = searchParams.get("nativeResult") === "1";
 
   const apiBase = process.env.NEXT_PUBLIC_API_BASE_URL ?? "";
@@ -222,6 +229,7 @@ function RunFinishPageContent() {
   const [actualMarker, setActualMarker] = useState<Point | null>(null);
   const [runSessionId, setRunSessionId] = useState<number | null>(null);
   const [savedRouteId, setSavedRouteId] = useState<number | null>(null);
+  const [runAnalysis, setRunAnalysis] = useState<RunAnalysis | null>(null);
   const [rating, setRating] = useState(0);
   const [isSavingRun, setIsSavingRun] = useState(false);
   const [hasAccessToken, setHasAccessToken] = useState<boolean | null>(null);
@@ -354,12 +362,15 @@ function RunFinishPageContent() {
     const achievementPct = parseNumber(achievement, 0);
     const caloriesValue = Math.round(parseNumber(calories, 0));
     const bpmValue = Math.round(parseNumber(bpm, 0));
+    const formMetrics = parseRunningFormMetrics(sensorSummaryParam);
 
     const payload = {
       route_title: routeTitle,
       animal_label: animal || null,
       source: mode === "manual" ? "manual" : "nearby",
       place_text: place || address || null,
+      run_id: runKey || null,
+      session_id: runKey || null,
       finished_at: new Date().toISOString(),
       duration_sec: durationSec,
       distance_km: distanceKm,
@@ -373,6 +384,7 @@ function RunFinishPageContent() {
       center_lng: centerFromPolyline?.[1] ?? null,
       polyline: routePolylineForSave.length > 1 ? routePolylineForSave : null,
       map_image_url: image || null,
+      form_metrics: formMetrics,
     };
 
     fetch(`${apiBase}/api/v1/auth/runs`, {
@@ -394,6 +406,9 @@ function RunFinishPageContent() {
         if (typeof responseJson.route_id === "number") {
           setSavedRouteId(responseJson.route_id);
         }
+        if (responseJson.run_analysis) {
+          setRunAnalysis(responseJson.run_analysis);
+        }
         window.sessionStorage.removeItem("tranimal-stats-bundle-v1");
       })
       .catch(() => {
@@ -408,6 +423,7 @@ function RunFinishPageContent() {
     actualKey,
     polylineParam,
     actualPolylineParam,
+    sensorSummaryParam,
     time,
     pace,
     distance,
@@ -611,6 +627,57 @@ function RunFinishPageContent() {
           </div>
         </div>
 
+        {runAnalysis && (
+          <section className="rounded-2xl border border-[#b9d7ff] bg-[#f4f9ff] px-4 py-4">
+            <div className="flex items-start justify-between gap-3">
+              <div>
+                <h2 className="text-base font-bold text-[#123a67]">센서 기반 러닝 코칭</h2>
+                <p className="mt-1 text-sm leading-5 text-[#315b87]">{runAnalysis.headline}</p>
+              </div>
+              {runAnalysis.sample_count > 0 && (
+                <span className="shrink-0 rounded-full bg-white px-2 py-1 text-xs font-semibold text-[#315b87]">
+                  {runAnalysis.sample_count}개 샘플
+                </span>
+              )}
+            </div>
+
+            {runAnalysis.strengths?.length > 0 && (
+              <div className="mt-4">
+                <p className="text-xs font-bold text-[#315b87]">잘 유지한 점</p>
+                <div className="mt-2 flex flex-col gap-2">
+                  {runAnalysis.strengths.map((item) => (
+                    <div key={item.key} className="rounded-xl bg-white px-3 py-2 text-sm text-[#24496f]">
+                      <span className="font-semibold">{item.title}</span> · {item.message}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {runAnalysis.focus?.length > 0 && (
+              <div className="mt-4">
+                <p className="text-xs font-bold text-[#315b87]">다음 러닝에서 한 가지</p>
+                <div className="mt-2 flex flex-col gap-2">
+                  {runAnalysis.focus.map((item) => (
+                    <div key={item.key} className="rounded-xl border border-[#d8e8fb] bg-white px-3 py-3 text-sm text-[#24496f]">
+                      <p className="font-semibold">{item.title}</p>
+                      <p className="mt-1 leading-5">{item.message}</p>
+                      {item.action && <p className="mt-2 font-medium text-[#1565b5]">{item.action}</p>}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {runAnalysis.focus?.length === 0 && (
+              <p className="mt-4 rounded-xl bg-white px-3 py-3 text-sm leading-5 text-[#24496f]">
+                {runAnalysis.next_action}
+              </p>
+            )}
+            <p className="mt-3 text-xs leading-4 text-[#5f7d9d]">{runAnalysis.disclaimer}</p>
+          </section>
+        )}
+
         {saveError && (
           <div className="rounded-xl border border-[#ffcccc] bg-[#fff1f1] px-4 py-3 text-sm text-[#a61d1d]">
             {saveError}

main/app/run/[id]/page.tsx

@@ -8,6 +8,10 @@ import YouTubeAudioPlayer, {
 } from "../../_components/YouTubeAudioPlayer";
 import { FLOW_KEYS, isUiFlowPermitValid, issueUiFlowPermit } from "../../_utils/uiFlowGuard";
 import { sendNativeWearControl } from "../../_utils/nativeWearBridge";
+import {
+  buildLiveSensorCoachMessage,
+  type WatchRunStateForCoaching,
+} from "../../_utils/runningCoaching";
 
 const routeDetails = [
   { id: "1", title: "강아지 코스", distance: "3.2km" },
@@ -109,6 +113,16 @@ const parseDistance = (value: string) => {
   return Number.isNaN(parsed) ? 0 : parsed;
 };
 
+const getCookieValue = (name: string): string | null => {
+  if (typeof document === "undefined") return null;
+  return (
+    document.cookie
+      .split("; ")
+      .find((row) => row.startsWith(`${name}=`))
+      ?.split("=")[1] ?? null
+  );
+};
+
 const toRad = (deg: number) => (deg * Math.PI) / 180;
 
 const segmentLengthKm = (
@@ -156,6 +170,10 @@ type RunProgressSnapshot = {
   elapsedSec: number;
 };
 
+type WatchRunLiveEnvelope = {
+  run_state?: WatchRunStateForCoaching & { run_id?: string | null; session_id?: string | null };
+};
+
 const interpolateElapsedAtDistance = (
   targetDistanceKm: number,
   previous: RunProgressSnapshot,
@@ -222,6 +240,7 @@ function RunPageContent({ params }: { params: { id: string } }) {
   const halfDistanceNotifiedRef = useRef(false);
   const finish500mNotifiedRef = useRef(false);
   const goalDistanceNotifiedRef = useRef(false);
+  const lastSensorGuideRef = useRef({ key: "", sentAt: 0 });
   const lastGpsPointRef = useRef<{
     lat: number;
     lon: number;
@@ -414,6 +433,52 @@ function RunPageContent({ params }: { params: { id: string } }) {
     speech.speak(utterance);
   }, []);
 
+  useEffect(() => {
+    if (!flowAllowed || isPaused || typeof window === "undefined") {
+      return;
+    }
+
+    const accessToken = localStorage.getItem("access_token") ?? getCookieValue("access_token");
+    if (!accessToken) {
+      return;
+    }
+
+    const apiBase = process.env.NEXT_PUBLIC_API_BASE_URL ?? "";
+    let disposed = false;
+    const pollWearableSnapshot = async () => {
+      try {
+        const response = await fetch(`${apiBase}/api/v1/auth/watch/run/live-state`, {
+          headers: { Authorization: `Bearer ${accessToken}` },
+          cache: "no-store",
+        });
+        if (!response.ok || response.status === 204 || disposed) return;
+        const payload = (await response.json()) as WatchRunLiveEnvelope;
+        const state = payload.run_state;
+        if (!state || (runKey && state.run_id && state.run_id !== runKey)) return;
+
+        const guide = buildLiveSensorCoachMessage(state);
+        if (!guide) return;
+        const now = Date.now();
+        const previous = lastSensorGuideRef.current;
+        const cooldown = previous.key === guide.key ? 120_000 : 90_000;
+        if (now - previous.sentAt < cooldown) return;
+        if (window.speechSynthesis?.speaking) return;
+
+        lastSensorGuideRef.current = { key: guide.key, sentAt: now };
+        speakRunGuide(guide.message);
+      } catch {
+        // A temporary network loss should not interrupt GPS tracking or the run.
+      }
+    };
+
+    void pollWearableSnapshot();
+    const timer = window.setInterval(() => void pollWearableSnapshot(), 5_000);
+    return () => {
+      disposed = true;
+      window.clearInterval(timer);
+    };
+  }, [flowAllowed, isPaused, runKey, speakRunGuide]);
+
   useEffect(() => {
     if (!flowAllowed || distanceKm <= 0) {
       return;

main/app/running-profile/page.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import TopBar from "../_components/TopBar";
+
+type Characteristic = {
+  key: string;
+  title: string;
+  average: number;
+  unit: string;
+  recorded_runs: number;
+  trend: "collecting" | "stable" | "improving" | "needs_attention" | string;
+  summary: string;
+};
+
+type RunningProfile = {
+  status: "ready" | "collecting" | "waiting_for_sensor_data" | string;
+  sample_size: number;
+  required_sample_size: number;
+  headline: string;
+  characteristics: Characteristic[];
+  next_focus: { title: string; action: string } | null;
+  recommendations: string[];
+  disclaimer?: string;
+};
+
+function getAccessToken(): string | null {
+  if (typeof window === "undefined") return null;
+  const cookieToken = document.cookie
+    .split("; ")
+    .find((row) => row.startsWith("access_token="))
+    ?.split("=")[1];
+  return localStorage.getItem("access_token") ?? cookieToken ?? null;
+}
+
+function trendLabel(trend: Characteristic["trend"]): string {
+  if (trend === "improving") return "최근 개선";
+  if (trend === "needs_attention") return "최근 확인";
+  if (trend === "stable") return "안정적";
+  return "데이터 수집 중";
+}
+
+export default function RunningProfilePage() {
+  const [profile, setProfile] = useState<RunningProfile | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const token = getAccessToken();
+    if (!token) {
+      setError("러닝 특성은 로그인 후 확인할 수 있어요.");
+      setLoading(false);
+      return;
+    }
+    const apiBase = process.env.NEXT_PUBLIC_API_BASE_URL ?? "";
+    fetch(`${apiBase}/api/v1/auth/running-coaching/profile`, {
+      headers: { Authorization: `Bearer ${token}` },
+      cache: "no-store",
+    })
+      .then(async (response) => {
+        if (!response.ok) throw new Error("profile request failed");
+        return (await response.json()) as { profile?: RunningProfile };
+      })
+      .then((payload) => setProfile(payload.profile ?? null))
+      .catch(() => setError("러닝 특성을 불러오지 못했어요. 잠시 후 다시 시도해 주세요."))
+      .finally(() => setLoading(false));
+  }, []);
+
+  return (
+    <main className="min-h-screen bg-[#f7f9fc] text-black">
+      <TopBar />
+      <section className="mx-auto w-full max-w-3xl px-6 py-8 sm:px-10">
+        <Link href="/stats" className="text-sm font-medium text-[#1565b5] hover:underline">
+          ← 통계로 돌아가기
+        </Link>
+        <div className="mt-4">
+          <p className="text-sm font-semibold text-[#1565b5]">WEARABLE RUNNING INSIGHT</p>
+          <h1 className="mt-1 text-3xl font-bold">나의 러닝 특성</h1>
+          <p className="mt-2 text-sm leading-6 text-[#5b6675]">
+            워치가 저장한 심박·움직임 데이터를 최근 러닝끼리 비교해, 다음에 다듬을 한 가지를 알려드려요.
+          </p>
+        </div>
+
+        {loading && <p className="mt-8 text-sm text-[#667085]">러닝 기록을 분석하고 있어요...</p>}
+        {error && <div className="mt-8 rounded-2xl border border-[#ffd1d1] bg-white px-4 py-4 text-sm text-[#a61d1d]">{error}</div>}
+
+        {profile && (
+          <div className="mt-7 flex flex-col gap-4">
+            <section className="rounded-2xl border border-[#cfe1f6] bg-[#eef7ff] px-5 py-5">
+              <div className="flex flex-wrap items-start justify-between gap-3">
+                <div>
+                  <h2 className="text-lg font-bold text-[#123a67]">이번 주의 러닝 방향</h2>
+                  <p className="mt-2 text-sm leading-6 text-[#315b87]">{profile.headline}</p>
+                </div>
+                <span className="rounded-full bg-white px-3 py-1.5 text-xs font-bold text-[#315b87]">
+                  센서 기록 {profile.sample_size}회
+                </span>
+              </div>
+              {profile.next_focus && (
+                <div className="mt-4 rounded-xl bg-white px-4 py-3 text-sm text-[#24496f]">
+                  <p className="font-semibold">집중할 항목: {profile.next_focus.title}</p>
+                  <p className="mt-1 leading-5">{profile.next_focus.action}</p>
+                </div>
+              )}
+            </section>
+
+            {profile.characteristics.length > 0 && (
+              <section>
+                <h2 className="text-lg font-bold">기록에서 보인 특성</h2>
+                <div className="mt-3 grid gap-3 sm:grid-cols-2">
+                  {profile.characteristics.map((item) => (
+                    <article key={item.key} className="rounded-2xl border border-black/10 bg-white px-4 py-4 shadow-sm">
+                      <div className="flex items-start justify-between gap-2">
+                        <h3 className="font-semibold">{item.title}</h3>
+                        <span className="rounded-full bg-[#f2f5f8] px-2 py-1 text-[11px] font-semibold text-[#536273]">
+                          {trendLabel(item.trend)}
+                        </span>
+                      </div>
+                      <p className="mt-4 text-2xl font-bold">
+                        {item.average} <span className="text-sm font-medium text-[#667085]">{item.unit}</span>
+                      </p>
+                      <p className="mt-2 text-sm text-[#667085]">{item.summary}</p>
+                    </article>
+                  ))}
+                </div>
+              </section>
+            )}
+
+            <section className="rounded-2xl border border-black/10 bg-white px-5 py-5">
+              <h2 className="text-lg font-bold">올바른 러닝을 위한 다음 단계</h2>
+              <ul className="mt-3 flex list-disc flex-col gap-2 pl-5 text-sm leading-6 text-[#4b5563]">
+                {profile.recommendations.map((recommendation) => (
+                  <li key={recommendation}>{recommendation}</li>
+                ))}
+              </ul>
+              {profile.status === "collecting" && (
+                <p className="mt-4 text-xs leading-5 text-[#667085]">
+                  최근 {profile.required_sample_size}회 이상 센서 기록이 모이면 변화 추세까지 더 정확하게 비교할 수 있어요.
+                </p>
+              )}
+              {profile.disclaimer && <p className="mt-4 text-xs leading-5 text-[#667085]">{profile.disclaimer}</p>}
+            </section>
+          </div>
+        )}
+      </section>
+    </main>
+  );
+}