chore: snapshot production code before Apple Design UI refinement

vehicle-data-platform/apps/api/internal/openplatform/assets/docs.html

@@ -81,7 +81,7 @@
 
       <section class="section" id="daily-hydrogen"><div class="section-head"><div><h2>车辆单日用氢量</h2><div class="endpoint"><span class="method">POST</span>/api/v1/vehicles/hydrogen-consumption/query</div><p>查询车辆单日用氢量，单位 kg。NORMAL + OK + PRELIMINARY 仅供初步监控；正式报表要求 FINAL 并核对证据与版本。两个日统计接口没有共同快照，区间缺失或不同不能直接计算百公里氢耗。</p></div><a class="anchor" href="#daily-hydrogen">#</a></div><div class="grid"><div><h3 class="subhead">请求参数</h3><table class="param-table"><tr><th>字段</th><th>必填</th><th>说明</th></tr><tr><td>date</td><td class="required">是</td><td>日期，格式 yyyy-MM-dd</td></tr><tr><td>plateNumbers</td><td class="optional">否</td><td>车牌数组；省略或 [] 时查询全部授权车辆</td></tr></table></div><div><h3 class="subhead">成功返回 · 200</h3><pre class="code">{<br>  <span class="key">"code"</span>: <span class="string">"SUCCESS"</span>,<br>  <span class="key">"data"</span>: [{<br>    <span class="key">"plateNumber"</span>: <span class="string">"浙F06618F"</span>,<br>    <span class="key">"hydrogenConsumptionKg"</span>: <span class="number">12.315</span>,<br>    <span class="key">"status"</span>: <span class="string">"NORMAL"</span><br>  }]<br>}</pre><ul class="errors"><li>400：日期或车牌格式不正确</li><li>401：appKey 无效、停用或过期</li><li>403：指定车辆未授权</li></ul></div></div></section>
 
-      <section class="section" id="daily-mileage"><div class="section-head"><div><h2>车辆单日里程</h2><div class="endpoint"><span class="method">POST</span>/api/v1/vehicles/mileage/query</div><p>返回当日行驶里程、当日累计总里程和实际选用的数据协议，单位 km。</p></div><a class="anchor" href="#daily-mileage">#</a></div><div class="grid"><div><h3 class="subhead">请求参数</h3><table class="param-table"><tr><th>字段</th><th>必填</th><th>说明</th></tr><tr><td>date</td><td class="required">是</td><td>日期，格式 yyyy-MM-dd</td></tr><tr><td>plateNumbers</td><td class="optional">否</td><td>省略时查询全部授权车辆</td></tr><tr><td>protocolPriority</td><td class="optional">否</td><td>协议选源顺序，例如 ["GB32960","MQTT","JT808"]</td></tr></table><div class="note"><strong>缺数规则：</strong>若当日没有有效里程，日里程为 0；累计总里程沿用上一个有效统计周期，计算时间也显示该周期时间。</div></div><div><h3 class="subhead">成功返回 · 200</h3><pre class="code">{<br>  <span class="key">"code"</span>: <span class="string">"SUCCESS"</span>,<br>  <span class="key">"data"</span>: [{<br>    <span class="key">"dailyMileageKm"</span>: <span class="number">182.437</span>,<br>    <span class="key">"totalMileageKm"</span>: <span class="number">12345.679</span>,<br>    <span class="key">"sourceProtocol"</span>: <span class="string">"GB32960"</span>,<br>    <span class="key">"status"</span>: <span class="string">"NORMAL"</span><br>  }]<br>}</pre><ul class="errors"><li>400：日期、车牌或协议参数错误</li><li>403：授权期未覆盖查询日</li><li>无统计：单车以 NO_DATA 返回</li></ul></div></div></section>
+      <section class="section" id="daily-mileage"><div class="section-head"><div><h2>车辆单日里程</h2><div class="endpoint"><span class="method">POST</span>/api/v1/vehicles/mileage/query</div><p>返回当日行驶里程、当日累计总里程和实际选用的数据协议，单位 km。</p></div><a class="anchor" href="#daily-mileage">#</a></div><div class="grid"><div><h3 class="subhead">请求参数</h3><table class="param-table"><tr><th>字段</th><th>必填</th><th>说明</th></tr><tr><td>date</td><td class="required">是</td><td>日期，格式 yyyy-MM-dd</td></tr><tr><td>plateNumbers</td><td class="optional">否</td><td>省略时查询全部授权车辆</td></tr><tr><td>protocolPriority</td><td class="optional">否</td><td>协议选源顺序，例如 ["GB32960","MQTT","JT808"]</td></tr></table><div class="note"><strong>缺数规则：</strong>日里程按同来源相邻日累计差计算；缺报日沿用累计值、日里程补 0（CARRIED_FORWARD），跨缺报期增量计入恢复日。首次基线、来源切换或累计回退返回 DATA_ANOMALY，日里程为 null。GPS 估算不参与本接口。</div></div><div><h3 class="subhead">成功返回 · 200</h3><pre class="code">{<br>  <span class="key">"code"</span>: <span class="string">"SUCCESS"</span>,<br>  <span class="key">"data"</span>: [{<br>    <span class="key">"dailyMileageKm"</span>: <span class="number">182.437</span>,<br>    <span class="key">"totalMileageKm"</span>: <span class="number">12345.679</span>,<br>    <span class="key">"sourceProtocol"</span>: <span class="string">"GB32960"</span>,<br>    <span class="key">"status"</span>: <span class="string">"NORMAL"</span><br>  }]<br>}</pre><ul class="errors"><li>400：日期、车牌或协议参数错误</li><li>403：授权期未覆盖查询日</li><li>无统计：单车以 NO_DATA 返回</li></ul></div></div></section>
 
       <section class="section" id="mileage-range"><div class="section-head"><div><h2>车辆区间日里程</h2><div class="endpoint"><span class="method">POST</span>/api/v1/vehicles/mileage/range/query</div><p>按车辆、日期分页返回区间日里程，最长查询区间为 366 天。</p></div><a class="anchor" href="#mileage-range">#</a></div><div class="grid"><div><h3 class="subhead">请求参数</h3><table class="param-table"><tr><th>字段</th><th>必填</th><th>说明</th></tr><tr><td>startDate / endDate</td><td class="required">是</td><td>日期区间，yyyy-MM-dd</td></tr><tr><td>plateNumbers</td><td class="optional">否</td><td>车牌数组，最多 5000 辆</td></tr><tr><td>protocolPriority</td><td class="optional">否</td><td>协议选源顺序</td></tr><tr><td>pageSize / cursor</td><td class="optional">否</td><td>分页大小及下一页游标</td></tr></table></div><div><h3 class="subhead">成功返回 · 200</h3><pre class="code">{<br>  <span class="key">"code"</span>: <span class="string">"SUCCESS"</span>,<br>  <span class="key">"data"</span>: [{<br>    <span class="key">"date"</span>: <span class="string">"2026-08-06"</span>,<br>    <span class="key">"dailyMileageKm"</span>: <span class="number">182.437</span>,<br>    <span class="key">"totalMileageKm"</span>: <span class="number">12345.679</span><br>  }],<br>  <span class="key">"nextCursor"</span>: <span class="string">null</span><br>}</pre><ul class="errors"><li>400：区间超限或游标与原参数不一致</li><li>403：授权未完整覆盖查询区间</li></ul></div></div></section>
 

vehicle-data-platform/apps/api/internal/openplatform/assets/openapi.yaml

@@ -102,9 +102,9 @@ paths:
       summary: 查询车辆单日里程
       description: |
         plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。
-        protocolPriority 传入时，逐车按数组顺序选择第一个有效协议，未列出的协议完全禁用且不会兜底；省略时保持平台默认选源行为。
-        NORMAL 结果同时包含日里程、日末累计总里程、实际来源协议、源数据时间和投影更新时间。日里程可由 GPS 轨迹估算；累计总里程读取每日统计中的 day_end_total_mileage_km，始终优先采用同协议终端上报的累计里程，不会使用 GPS 日里程估算值冒充累计里程。
-        当日无有效里程时，日里程补 0，累计总里程、来源协议、dataTime 和 updatedAt 沿用此前最近的有效统计；updatedAt 仍为上一统计周期的计算时间。
+        protocolPriority 传入时，逐车按数组顺序选择截至查询日已有有效累计读数的第一个协议；高优先级协议缺报时沿用其历史累计值，不切换累计基准，未列出的协议完全禁用且不会兜底；省略时保持平台默认选源行为。
+        NORMAL 结果同时包含日里程、日末累计总里程、实际来源协议、源数据时间和投影更新时间。日里程按同来源相邻自然日累计读数之差计算，缺报期间增量计入恢复上报日；GPS 估算不参与本接口。首次基线、来源切换、累计回退返回 DATA_ANOMALY、dailyMileageKm=null 和 dataQuality。
+        当日缺报时，日里程补 0，累计总里程、来源协议、dataTime 和 updatedAt 沿用同协议历史读数，dataQuality=CARRIED_FORWARD。
       operationId: queryDailyMileage
       security:
         - AppKeyAuth: []
@@ -141,7 +141,7 @@ paths:
         首次请求返回 snapshotId 和 nextCursor；后续请求保持原参数并传回 nextCursor。
         快照仅固化授权车辆清单，逐页读取已建立索引的日统计投影，不扫描原始时序明细。
         protocolPriority 对区间内每辆车、每个自然日独立生效；未列出的协议完全禁用。
-        某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。若终端累计里程回退，返回 DATA_ANOMALY 与 dataQuality=TOTAL_MILEAGE_ROLLBACK，绝不沿用历史值伪装为正常数据。日里程与日末累计总里程独立统计：GPS 轨迹估算仅用于日里程，累计总里程读取每日统计字段 day_end_total_mileage_km。
+        某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。若终端累计里程回退，返回 DATA_ANOMALY 与 dataQuality=TOTAL_MILEAGE_ROLLBACK。日里程与累计值使用同一终端来源；日里程为相邻自然日累计差，GPS 估算不参与本接口。单日、区间和分页共用相同计算规则。
       operationId: queryDailyMileageRange
       security:
         - AppKeyAuth: []
@@ -784,7 +784,7 @@ components:
           type: number
           format: double
           nullable: true
-          description: 单日里程，km；当日无记录但存在历史累计里程时为 0
+          description: 相邻自然日同来源累计值之差，km；跨缺报期增量计入恢复日；缺报日为 0；首次基线、来源变化和累计异常时为 null
         totalMileageKm:
           type: number
           format: double
@@ -794,7 +794,7 @@ components:
           type: string
           format: date-time
           nullable: true
-          description: 当日统计所选来源的最早 first_event_time，跨日基线可早于当日零点，不是自然日起始；历史结转补零或无数据时为 null
+          description: 日里程起点累计读数的时间；可跨越多个缺报日；历史结转补零或无数据时为 null
         statisticsEndTime:
           type: string
           format: date-time
@@ -818,8 +818,8 @@ components:
         dataQuality:
           type: string
           nullable: true
-          enum: [TOTAL_MILEAGE_ROLLBACK]
-          description: status=DATA_ANOMALY 时的异常原因；累计里程回退时为 TOTAL_MILEAGE_ROLLBACK
+          enum: [TOTAL_MILEAGE_ROLLBACK, ODOMETER_SOURCE_CHANGED, NO_PREVIOUS_BASELINE, PREVIOUS_ODOMETER_ANOMALY, CARRIED_FORWARD, outside_daily_range, INVALID_DELTA]
+          description: CARRIED_FORWARD 表示缺报结转；其他值表示无法连续对账的原因，此时 dailyMileageKm 为 null，保留累计读数及来源证据
         status:
           $ref: '#/components/schemas/DataStatus'
     MileageRangeResult:
@@ -862,8 +862,8 @@ components:
         dataQuality:
           type: string
           nullable: true
-          enum: [TOTAL_MILEAGE_ROLLBACK]
-          description: status=DATA_ANOMALY 时的异常原因；累计里程回退时为 TOTAL_MILEAGE_ROLLBACK
+          enum: [TOTAL_MILEAGE_ROLLBACK, ODOMETER_SOURCE_CHANGED, NO_PREVIOUS_BASELINE, PREVIOUS_ODOMETER_ANOMALY, CARRIED_FORWARD, outside_daily_range, INVALID_DELTA]
+          description: CARRIED_FORWARD 表示缺报结转；其他值表示无法连续对账的原因，此时 dailyMileageKm 为 null，保留累计读数及来源证据
         status:
           $ref: '#/components/schemas/DataStatus'
     DataStatus:

vehicle-data-platform/apps/api/internal/openplatform/mileage_reconciliation.go

@@ -0,0 +1,171 @@
+package openplatform
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"sort"
+	"strings"
+	"time"
+)
+
+// ReconciledMileageRange uses terminal odometers, including one preceding
+// observation per protocol. The same function serves single days and every
+// range page: neither the requested start date nor page size changes a result.
+func (r *MySQLRepository) ReconciledMileageRange(ctx context.Context, vins []string, start, end string, protocols []string) (map[string]DailyMileage, error) {
+	if len(vins) == 0 {
+		return map[string]DailyMileage{}, nil
+	}
+	if len(protocols) == 0 {
+		protocols = []string{"GB32960", "YUTONG_MQTT", "JT808"}
+	}
+	placeholders := func(n int) string { return strings.TrimRight(strings.Repeat("?,", n), ",") }
+	// Unknown-protocol legacy imports and GPS distance are not terminal odometers.
+	eligible := func(alias string) string {
+		return fmt.Sprintf(`%[1]s.quality_status IN ('OK','INVALID_DELTA')
+ AND %[1]s.latest_total_mileage_km > 0
+ AND COALESCE(%[1]s.quality_reason,'') <> 'gps_coordinate_accumulation'
+ AND %[1]s.source_ip NOT IN ('legacy-mysql.lingniu-prod','manual-lingniu-prod-day-mileage')
+ AND %[1]s.latest_event_time IS NOT NULL
+ AND %[1]s.latest_event_time < TIMESTAMP(%[1]s.stat_date)+INTERVAL 1 DAY`, alias)
+	}
+	filter := `vin IN (` + placeholders(len(vins)) + `) AND protocol IN (` + placeholders(len(protocols)) + `)`
+	query := `WITH wanted AS (
+ SELECT DISTINCT vin,protocol,stat_date FROM vehicle_daily_mileage_source p
+ WHERE ` + filter + ` AND stat_date BETWEEN ? AND ? AND ` + eligible("p") + `
+ UNION ALL
+ SELECT vin,protocol,MAX(stat_date) AS stat_date FROM vehicle_daily_mileage_source p
+ WHERE ` + filter + ` AND stat_date<? AND ` + eligible("p") + ` GROUP BY vin,protocol
+ )
+ SELECT s.vin,DATE_FORMAT(s.stat_date,'%Y-%m-%d'),s.protocol,s.source_key,
+ s.daily_mileage_km,s.latest_total_mileage_km,
+ DATE_FORMAT(s.latest_event_time,'%Y-%m-%dT%H:%i:%s+08:00'),
+ DATE_FORMAT(s.updated_at,'%Y-%m-%dT%H:%i:%s+08:00'),
+ COALESCE(DATE_FORMAT(s.first_event_time,'%Y-%m-%dT%H:%i:%s+08:00'),''),
+ CASE WHEN s.quality_status='INVALID_DELTA' THEN COALESCE(s.quality_reason,'INVALID_DELTA') ELSE '' END
+ FROM wanted w JOIN vehicle_daily_mileage_source s
+ ON s.vin=w.vin AND s.protocol=w.protocol AND s.stat_date=w.stat_date
+ WHERE ` + eligible("s") + `
+ ORDER BY s.stat_date,s.vin,s.protocol,s.is_selected DESC,
+ CASE WHEN s.quality_status='OK' THEN 0 ELSE 1 END,s.latest_event_time DESC,s.sample_count DESC,s.source_key`
+	args := make([]any, 0, 2*(len(vins)+len(protocols))+3)
+	for _, v := range vins {
+		args = append(args, v)
+	}
+	for _, p := range protocols {
+		args = append(args, p)
+	}
+	args = append(args, start, end)
+	for _, v := range vins {
+		args = append(args, v)
+	}
+	for _, p := range protocols {
+		args = append(args, p)
+	}
+	args = append(args, start)
+	rows, err := r.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var points []DailyMileage
+	seen := map[string]bool{}
+	for rows.Next() {
+		var v DailyMileage
+		if err := rows.Scan(&v.VIN, &v.Date, &v.Protocol, &v.SourceKey, &v.MileageKm, &v.TotalMileageKm, &v.DataTime, &v.UpdatedAt, &v.StatisticsStartTime, &v.DataQuality); err != nil {
+			return nil, err
+		}
+		key := v.VIN + "|" + v.Date + "|" + v.Protocol
+		if !seen[key] {
+			points = append(points, v)
+			seen[key] = true
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return reconcileMileage(points, vins, start, end, protocols)
+}
+
+func reconcileMileage(points []DailyMileage, vins []string, start, end string, protocols []string) (map[string]DailyMileage, error) {
+	loc := time.FixedZone("Asia/Shanghai", 8*3600)
+	first, err := time.ParseInLocation("2006-01-02", start, loc)
+	if err != nil {
+		return nil, err
+	}
+	last, err := time.ParseInLocation("2006-01-02", end, loc)
+	if err != nil {
+		return nil, err
+	}
+	if last.Before(first) {
+		return nil, fmt.Errorf("invalid mileage interval")
+	}
+	if len(protocols) == 0 {
+		protocols = []string{"GB32960", "YUTONG_MQTT", "JT808"}
+	}
+	sort.SliceStable(points, func(i, j int) bool { return points[i].Date < points[j].Date })
+	state := map[string]map[string]DailyMileage{}
+	pick := func(vin string) (DailyMileage, bool) {
+		for _, p := range protocols {
+			if v, ok := state[vin][p]; ok {
+				return v, true
+			}
+		}
+		return DailyMileage{}, false
+	}
+	put := func(v DailyMileage) {
+		if state[v.VIN] == nil {
+			state[v.VIN] = map[string]DailyMileage{}
+		}
+		state[v.VIN][v.Protocol] = v
+	}
+	i := 0
+	for i < len(points) && points[i].Date < start {
+		put(points[i])
+		i++
+	}
+	out := map[string]DailyMileage{}
+	for day := first; !day.After(last); day = day.AddDate(0, 0, 1) {
+		date := day.Format("2006-01-02")
+		before := map[string]DailyMileage{}
+		for _, vin := range vins {
+			if p, ok := pick(vin); ok {
+				before[vin] = p
+			}
+		}
+		for i < len(points) && points[i].Date == date {
+			put(points[i])
+			i++
+		}
+		for _, vin := range vins {
+			current, ok := pick(vin)
+			if !ok {
+				continue
+			}
+			result := current
+			previous, hasPrevious := before[vin]
+			if current.Date < date {
+				result.MileageKm = 0
+				result.StatisticsStartTime = ""
+				if result.DataQuality == "" {
+					result.DataQuality = "CARRIED_FORWARD"
+				}
+			} else if current.DataQuality != "" {
+				result.MileageKm = 0
+			} else if !hasPrevious {
+				result.DataQuality = "NO_PREVIOUS_BASELINE"
+			} else if current.Protocol != previous.Protocol || current.SourceKey != previous.SourceKey {
+				result.DataQuality = "ODOMETER_SOURCE_CHANGED"
+			} else if current.TotalMileageKm < previous.TotalMileageKm {
+				result.DataQuality = mileageTotalRollbackQuality
+			} else if previous.DataQuality != "" {
+				result.DataQuality = "PREVIOUS_ODOMETER_ANOMALY"
+			} else {
+				result.MileageKm = math.Round((current.TotalMileageKm-previous.TotalMileageKm)*1000) / 1000
+				result.StatisticsStartTime = previous.DataTime
+			}
+			out[dailyMileageKey(vin, date)] = result
+		}
+	}
+	return out, nil
+}

vehicle-data-platform/apps/api/internal/openplatform/mileage_reconciliation_test.go

@@ -0,0 +1,83 @@
+package openplatform
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestReconciliationRecoveryAndPagination(t *testing.T) {
+	points := []DailyMileage{
+		{VIN: "v", Date: "2026-09-13", Protocol: "GB32960", SourceKey: "a", TotalMileageKm: 14366, DataTime: "2026-09-13T07:17:27+08:00"},
+		{VIN: "v", Date: "2026-09-15", Protocol: "GB32960", SourceKey: "a", TotalMileageKm: 14467.4, DataTime: "2026-09-15T20:57:04+08:00"},
+	}
+	all, err := reconcileMileage(points, []string{"v"}, "2026-09-14", "2026-09-15", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if all["v\x002026-09-15"].MileageKm != 101.4 {
+		t.Fatalf("recovery=%+v", all)
+	}
+	for _, date := range []string{"2026-09-14", "2026-09-15"} {
+		one, _ := reconcileMileage(points, []string{"v"}, date, date, nil)
+		if !reflect.DeepEqual(one[dailyMileageKey("v", date)], all[dailyMileageKey("v", date)]) {
+			t.Fatal("page changes result")
+		}
+	}
+}
+func TestReconciliationPinsProtocolThroughMissingDays(t *testing.T) {
+	points := []DailyMileage{{VIN: "v", Date: "2026-09-11", Protocol: "GB32960", SourceKey: "a", TotalMileageKm: 100}, {VIN: "v", Date: "2026-09-12", Protocol: "YUTONG_MQTT", SourceKey: "b", TotalMileageKm: 9000}, {VIN: "v", Date: "2026-09-14", Protocol: "GB32960", SourceKey: "a", TotalMileageKm: 120}}
+	got, _ := reconcileMileage(points, []string{"v"}, "2026-09-12", "2026-09-14", nil)
+	if got[dailyMileageKey("v", "2026-09-12")].TotalMileageKm != 100 || got[dailyMileageKey("v", "2026-09-14")].MileageKm != 20 {
+		t.Fatalf("%+v", got)
+	}
+}
+func TestReconciliationMarksDiscontinuities(t *testing.T) {
+	for _, tc := range []struct {
+		name, source string
+		total        float64
+		want         string
+	}{{"rollback", "a", 90, mileageTotalRollbackQuality}, {"replacement", "b", 120, "ODOMETER_SOURCE_CHANGED"}} {
+		t.Run(tc.name, func(t *testing.T) {
+			got, _ := reconcileMileage([]DailyMileage{{VIN: "v", Date: "2026-09-12", Protocol: "JT808", SourceKey: "a", TotalMileageKm: 100}, {VIN: "v", Date: "2026-09-13", Protocol: "JT808", SourceKey: tc.source, TotalMileageKm: tc.total}}, []string{"v"}, "2026-09-13", "2026-09-13", []string{"JT808"})
+			v := got[dailyMileageKey("v", "2026-09-13")]
+			var response MileageResult
+			fillMileageResult(&response, v, v.MileageKm)
+			if response.DailyMileageKm != nil || response.Status != StatusDataAnomaly || v.DataQuality != tc.want {
+				t.Fatalf("%+v %+v", v, response)
+			}
+		})
+	}
+}
+
+func TestReconciliationFirstObservationHasNoInventedDistance(t *testing.T) {
+	got, _ := reconcileMileage([]DailyMileage{{VIN: "v", Date: "2026-09-12", Protocol: "JT808", SourceKey: "a", TotalMileageKm: 100, DataTime: "2026-09-12T10:00:00+08:00"}}, []string{"v"}, "2026-09-12", "2026-09-12", nil)
+	v := got[dailyMileageKey("v", "2026-09-12")]
+	var result MileageResult
+	fillMileageResult(&result, v, v.MileageKm)
+	if result.DailyMileageKm != nil || result.TotalMileageKm == nil || *result.DataQuality != "NO_PREVIOUS_BASELINE" {
+		t.Fatalf("%+v", result)
+	}
+}
+
+// A source replacement is flagged only on its boundary; starting a new page
+// must not hide that boundary or change the following day's odometer delta.
+func TestReconciliationSourceReplacementAcrossPageBoundary(t *testing.T) {
+	points := []DailyMileage{
+		{VIN: "v", Date: "2026-09-11", Protocol: "JT808", SourceKey: "old", TotalMileageKm: 9000},
+		{VIN: "v", Date: "2026-09-12", Protocol: "JT808", SourceKey: "new", TotalMileageKm: 100},
+		{VIN: "v", Date: "2026-09-14", Protocol: "JT808", SourceKey: "new", TotalMileageKm: 140},
+	}
+	all, _ := reconcileMileage(points, []string{"v"}, "2026-09-12", "2026-09-14", nil)
+	if all[dailyMileageKey("v", "2026-09-12")].DataQuality != "ODOMETER_SOURCE_CHANGED" {
+		t.Fatal(all)
+	}
+	if all[dailyMileageKey("v", "2026-09-14")].MileageKm != 40 {
+		t.Fatal(all)
+	}
+	for _, day := range []string{"2026-09-12", "2026-09-13", "2026-09-14"} {
+		one, _ := reconcileMileage(points, []string{"v"}, day, day, nil)
+		if !reflect.DeepEqual(one[dailyMileageKey("v", day)], all[dailyMileageKey("v", day)]) {
+			t.Fatal(day)
+		}
+	}
+}

vehicle-data-platform/apps/api/internal/openplatform/model.go

@@ -314,6 +314,8 @@ type DailyHydrogen struct {
 }
 
 type DailyMileage struct {
+	SourceKey           string
+	DataQuality         string
 	StatisticsStartTime string
 	VIN                 string
 	Date                string

vehicle-data-platform/apps/api/internal/openplatform/service.go

@@ -29,6 +29,7 @@ var (
 )
 
 type Repository interface {
+	ReconciledMileageRange(context.Context, []string, string, string, []string) (map[string]DailyMileage, error)
 	Authenticate(context.Context, [sha256.Size]byte, time.Time, time.Time, time.Time) (AppCredential, error)
 	AuthorizedVehicles(context.Context, uint64, []string, time.Time, time.Time) (map[string]AuthorizedVehicle, error)
 	DailyHydrogen(context.Context, []string, string) (map[string]DailyHydrogen, error)
@@ -435,35 +436,17 @@ func (s *Service) QueryMileage(ctx context.Context, appKey, traceID string, requ
 		plates = vehiclePlates(vehicles)
 	}
 	vins := vehicleVINs(vehicles)
-	values, err := s.repository.DailyMileage(ctx, vins, date, protocols)
+	values, err := s.repository.ReconciledMileageRange(ctx, vins, date, date, protocols)
 	if err != nil {
 		_ = s.repository.Audit(ctx, app.ID, "mileage_query", "error", traceID, len(plates), err.Error())
 		return nil, err
 	}
-	rollbacks, err := s.repository.MileageRollbacks(ctx, vins, date, date, protocols)
-	if err != nil {
-		_ = s.repository.Audit(ctx, app.ID, "mileage_query", "error", traceID, len(plates), err.Error())
-		return nil, err
-	}
-	missingVINs := missingMileageVINs(vins, values, rollbacks, date)
-	carried := map[string]DailyMileage{}
-	if len(missingVINs) > 0 {
-		carried, err = s.repository.LatestMileageBefore(ctx, missingVINs, date, protocols)
-		if err != nil {
-			_ = s.repository.Audit(ctx, app.ID, "mileage_query", "error", traceID, len(plates), err.Error())
-			return nil, err
-		}
-	}
 	results := make([]MileageResult, 0, len(plates))
 	for _, plate := range plates {
 		vehicle := vehicles[plate]
 		item := MileageResult{VIN: vehicle.VIN, PlateNumber: plate, Date: date, Status: StatusNoData}
-		if value, ok := values[vehicle.VIN]; ok && validDailyMileage(value) {
+		if value, ok := values[dailyMileageKey(vehicle.VIN, date)]; ok {
 			fillMileageResult(&item, value, value.MileageKm)
-		} else if rollbacks[dailyMileageKey(vehicle.VIN, date)] {
-			fillMileageAnomaly(&item)
-		} else if value, ok := carried[vehicle.VIN]; ok && validDailyMileage(value) {
-			fillMileageResult(&item, value, 0)
 		}
 		results = append(results, item)
 	}
@@ -556,35 +539,17 @@ func (s *Service) QueryMileageRange(ctx context.Context, appKey, traceID string,
 		vinSet[vehicle.VIN] = struct{}{}
 	}
 	values := map[string]DailyMileage{}
-	carried := map[string]DailyMileage{}
-	rollbacks := map[string]bool{}
 	if len(positions) > 0 {
 		vins := make([]string, 0, len(vinSet))
 		for vin := range vinSet {
 			vins = append(vins, vin)
 		}
 		sort.Strings(vins)
-		values, err = s.repository.DailyMileageRange(ctx, vins, queryStart.Format("2006-01-02"), queryEnd.Format("2006-01-02"), protocols)
+		values, err = s.repository.ReconciledMileageRange(ctx, vins, queryStart.Format("2006-01-02"), queryEnd.Format("2006-01-02"), protocols)
 		if err != nil {
 			_ = s.repository.Audit(ctx, app.ID, "mileage_range_query", "error", traceID, snapshot.VehicleCount, err.Error())
 			return MileageRangeResponse{}, err
 		}
-		rollbacks, err = s.repository.MileageRollbacks(ctx, vins, queryStart.Format("2006-01-02"), queryEnd.Format("2006-01-02"), protocols)
-		if err != nil {
-			_ = s.repository.Audit(ctx, app.ID, "mileage_range_query", "error", traceID, snapshot.VehicleCount, err.Error())
-			return MileageRangeResponse{}, err
-		}
-		missingVINs := missingMileageRangeInitialVINs(positions, values, rollbacks)
-		if len(missingVINs) > 0 {
-			carried, err = s.repository.LatestMileageBefore(ctx, missingVINs, queryStart.Format("2006-01-02"), protocols)
-			if err != nil {
-				_ = s.repository.Audit(ctx, app.ID, "mileage_range_query", "error", traceID, snapshot.VehicleCount, err.Error())
-				return MileageRangeResponse{}, err
-			}
-			if carried == nil {
-				carried = map[string]DailyMileage{}
-			}
-		}
 	}
 	results := make([]MileageRangeResult, 0, len(positions))
 	for _, position := range positions {
@@ -594,14 +559,8 @@ func (s *Service) QueryMileageRange(ctx context.Context, appKey, traceID string,
 			Date:        position.date,
 			Status:      StatusNoData,
 		}
-		if value, ok := values[dailyMileageKey(position.vehicle.VIN, position.date)]; ok && validDailyMileage(value) {
+		if value, ok := values[dailyMileageKey(position.vehicle.VIN, position.date)]; ok {
 			fillMileageRangeResult(&item, value, value.MileageKm)
-			carried[position.vehicle.VIN] = value
-		} else if rollbacks[dailyMileageKey(position.vehicle.VIN, position.date)] {
-			fillMileageRangeAnomaly(&item)
-			delete(carried, position.vehicle.VIN)
-		} else if value, ok := carried[position.vehicle.VIN]; ok && validDailyMileage(value) {
-			fillMileageRangeResult(&item, value, 0)
 		}
 		results = append(results, item)
 	}
@@ -1001,6 +960,10 @@ func missingMileageRangeInitialVINs(positions []mileageRangePosition, values map
 }
 
 func fillMileageResult(item *MileageResult, value DailyMileage, dailyMileage float64) {
+	if value.DataQuality != "" && value.DataTime == "" {
+		fillMileageAnomaly(item)
+		return
+	}
 	if value.Date == item.Date {
 		item.StatisticsStartTime, item.StatisticsEndTime = validatedStatisticsInterval(value.StatisticsStartTime, value.DataTime)
 	}
@@ -1014,9 +977,20 @@ func fillMileageResult(item *MileageResult, value DailyMileage, dailyMileage flo
 	sourceProtocol := externalMileageProtocol(value.Protocol)
 	item.SourceProtocol = &sourceProtocol
 	item.Status = StatusNormal
+	if value.DataQuality != "" {
+		item.DataQuality = stringPointer(value.DataQuality)
+		if value.DataQuality != "CARRIED_FORWARD" {
+			item.Status = StatusDataAnomaly
+			item.DailyMileageKm = nil
+		}
+	}
 }
 
 func fillMileageRangeResult(item *MileageRangeResult, value DailyMileage, dailyMileage float64) {
+	if value.DataQuality != "" && value.DataTime == "" {
+		fillMileageRangeAnomaly(item)
+		return
+	}
 	item.DailyMileageKm = &dailyMileage
 	totalMileage := value.TotalMileageKm
 	item.TotalMileageKm = &totalMileage
@@ -1027,6 +1001,13 @@ func fillMileageRangeResult(item *MileageRangeResult, value DailyMileage, dailyM
 	sourceProtocol := externalMileageProtocol(value.Protocol)
 	item.SourceProtocol = &sourceProtocol
 	item.Status = StatusNormal
+	if value.DataQuality != "" {
+		item.DataQuality = stringPointer(value.DataQuality)
+		if value.DataQuality != "CARRIED_FORWARD" {
+			item.Status = StatusDataAnomaly
+			item.DailyMileageKm = nil
+		}
+	}
 }
 
 const mileageTotalRollbackQuality = "TOTAL_MILEAGE_ROLLBACK"

vehicle-data-platform/apps/api/internal/openplatform/service_test.go

@@ -47,6 +47,56 @@ func (f *fakeRepository) AuthorizedVehicles(_ context.Context, _ uint64, plates
 	f.requestedPlates = append([]string(nil), plates...)
 	return f.vehicles, nil
 }
+
+// Repository stub retains fixture values; reconciliation itself is tested with
+// actual dated observations in mileage_reconciliation_test.go.
+func (f *fakeRepository) ReconciledMileageRange(ctx context.Context, vins []string, start, end string, protocols []string) (map[string]DailyMileage, error) {
+	f.dailyVINs = append([]string(nil), vins...)
+	f.rangeVINs = append([]string(nil), vins...)
+	f.dailyProtocols = protocols
+	out := map[string]DailyMileage{}
+	carried := map[string]DailyMileage{}
+	var missing []string
+	for _, vin := range vins {
+		v, ok := f.mileage[dailyMileageKey(vin, start)]
+		if !ok {
+			v, ok = f.mileage[vin]
+		}
+		if (!ok || !validDailyMileage(v)) && !f.rollbacks[dailyMileageKey(vin, start)] {
+			missing = append(missing, vin)
+		}
+	}
+	if len(missing) > 0 {
+		prior, _ := f.LatestMileageBefore(ctx, missing, start, protocols)
+		for vin, v := range prior {
+			carried[vin] = v
+		}
+	}
+	first, _ := time.Parse("2006-01-02", start)
+	last, _ := time.Parse("2006-01-02", end)
+	for day := first; !day.After(last); day = day.AddDate(0, 0, 1) {
+		date := day.Format("2006-01-02")
+		for _, vin := range vins {
+			key := dailyMileageKey(vin, date)
+			v, ok := f.mileage[key]
+			if !ok {
+				v, ok = f.mileage[vin]
+			}
+			if ok && validDailyMileage(v) {
+				out[key] = v
+				carried[vin] = v
+			} else if f.rollbacks[key] {
+				out[key] = DailyMileage{DataQuality: mileageTotalRollbackQuality}
+				delete(carried, vin)
+			} else if v, ok = carried[vin]; ok && validDailyMileage(v) {
+				v.MileageKm = 0
+				out[key] = v
+			}
+		}
+	}
+	return out, nil
+}
+
 func (f *fakeRepository) DailyHydrogen(_ context.Context, vins []string, _ string) (map[string]DailyHydrogen, error) {
 	f.dailyVINs = append([]string(nil), vins...)
 	return f.hydrogen, nil