chore: commit mileage updates and accumulated project artifacts

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（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="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

@@ -103,7 +103,7 @@ paths:
       description: |
         plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。
         protocolPriority 传入时，逐车按数组顺序选择截至查询日已有有效累计读数的第一个协议；高优先级协议缺报时沿用其历史累计值，不切换累计基准，未列出的协议完全禁用且不会兜底；省略时保持平台默认选源行为。
-        NORMAL 结果同时包含日里程、日末累计总里程、实际来源协议、源数据时间和投影更新时间。日里程按同来源相邻自然日累计读数之差计算，缺报期间增量计入恢复上报日；GPS 估算不参与本接口。首次基线、来源切换、累计回退返回 DATA_ANOMALY、dailyMileageKm=null 和 dataQuality。
+        NORMAL 结果同时包含日里程、日末累计总里程、实际来源协议、源数据时间和投影更新时间。日里程优先采用中台已选中且质量通过的终端日统计及其同来源基线，跨缺报期增量计入恢复上报日；来源切换本身不会否定已验证的日统计。无已验证日统计时按同来源累计差计算，首次基线、来源切换或累计回退无法验证时返回 DATA_ANOMALY、dailyMileageKm=null 和 dataQuality。GPS 估算不参与本接口。
         当日缺报时，日里程补 0，累计总里程、来源协议、dataTime 和 updatedAt 沿用同协议历史读数，dataQuality=CARRIED_FORWARD。
       operationId: queryDailyMileage
       security:
@@ -141,7 +141,7 @@ paths:
         首次请求返回 snapshotId 和 nextCursor；后续请求保持原参数并传回 nextCursor。
         快照仅固化授权车辆清单，逐页读取已建立索引的日统计投影，不扫描原始时序明细。
         protocolPriority 对区间内每辆车、每个自然日独立生效；未列出的协议完全禁用。
-        某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。若终端累计里程回退，返回 DATA_ANOMALY 与 dataQuality=TOTAL_MILEAGE_ROLLBACK。日里程与累计值使用同一终端来源；日里程为相邻自然日累计差，GPS 估算不参与本接口。单日、区间和分页共用相同计算规则。
+        某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。若终端累计里程回退，返回 DATA_ANOMALY 与 dataQuality=TOTAL_MILEAGE_ROLLBACK。日里程与累计值使用同一终端来源；日里程优先采用中台已验证的日统计及其同来源基线，来源切换不单独触发异常；缺少已验证日统计时才使用相邻自然日累计差。GPS 估算不参与本接口。单日、区间和分页共用相同计算规则。
       operationId: queryDailyMileageRange
       security:
         - AppKeyAuth: []