fix(prediction): 适配预测服务最小请求字段

.env.example

@@ -1,8 +1,12 @@
 DATABASE_URL=mysql://user:password@localhost:3306/database
 
+# 默认关闭公开 OpenAPI 文档/规格；仅在受控本地或内网演示环境显式启用。
+# ENABLE_API_DOCS=false
+
 # 必填：外部 SoH 预测服务地址
 SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
 # SOH_PREDICTION_CACHE_TTL_SECONDS=86400
+# SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS=300
 # SOH_PREDICTION_TIMEOUT_MS=10000
 
 # 可选：日志级别与输出格式

README.md

@@ -40,10 +40,21 @@ DATABASE_URL=mysql://user:password@host:3306/database
 ```bash
 SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
 SOH_PREDICTION_CACHE_TTL_SECONDS=86400
+SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS=300
 SOH_PREDICTION_TIMEOUT_MS=10000
 ```
 
-服务端会调用 `${SOH_PREDICTION_API_BASE_URL}/predict`，使用返回的当前健康度、30 天趋势、90 天趋势和风险评分生成看板视图。预测结果会按设备与最新采集记录缓存，默认 24 小时；单台设备预测失败或历史数据不足时，仅该设备显示为“预测不可用”。
+服务端会调用 `${SOH_PREDICTION_API_BASE_URL}/predict`，使用返回的当前健康度、30 天趋势、90 天趋势和风险评分生成看板视图。预测结果会按设备与最新采集记录缓存，默认 24 小时；单台设备预测失败或历史数据不足时会短暂缓存不可用状态，默认 5 分钟，避免反复打满预测服务，同时仅该设备显示为“预测不可用”。
+
+## 接口文档
+
+OpenAPI 文档和规格默认不公开，生产或生产类运行环境应保持默认值：
+
+```bash
+ENABLE_API_DOCS=false
+```
+
+仅在受控本地开发或内网演示环境显式设置 `ENABLE_API_DOCS=true` 后，才会开放 `http://localhost:3000/api/docs` 与 `http://localhost:3000/api/spec.json`。`/api/rpc` 不受此开关影响。
 
 ## 快速开始
 
@@ -57,7 +68,7 @@ bun run dev
 
 - `http://localhost:3000/`：设备健康运营看板
 - `http://localhost:3000/batteries`：设备状态明细
-- `http://localhost:3000/api/docs`：接口文档
+- `http://localhost:3000/api/docs`：接口文档（需设置 `ENABLE_API_DOCS=true`）
 
 ## 本地演示环境
 
@@ -73,6 +84,8 @@ Compose 会启动：
 - `seed`：初始化本地 `ls_battery_info` 演示数据
 - `app`：启动应用服务
 
+Compose 的 `app` 服务会为本地演示显式启用 `ENABLE_API_DOCS=true`；生产部署不应沿用该设置，除非已通过网络边界或上游认证限制访问。
+
 也可以手动初始化本地数据：
 
 ```bash

compose.yaml

@@ -41,6 +41,7 @@ services:
     environment:
       - DATABASE_URL=mysql://battery:battery@db:3306/battery_soh
       - SOH_PREDICTION_API_BASE_URL=http://host.docker.internal:8000
+      - ENABLE_API_DOCS=true
 
 volumes:
   mysql_data:

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "fullstack-starter",
+  "name": "battery-soh",
   "version": "1.0.0",
   "private": true,
   "type": "module",
@@ -43,7 +43,6 @@
     "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-virtual": "^3.13.24",
     "citty": "^0.2.2",
-    "drizzle-orm": "^0.45.2",
     "lru-cache": "^11.3.6",
     "lucide-react": "^1.14.0",
     "motion": "^12.38.0",
@@ -62,6 +61,7 @@
     "@tanstack/react-router-devtools": "^1.166.13",
     "@types/bun": "^1.3.13",
     "@vitejs/plugin-react": "^6.0.1",
+    "drizzle-orm": "^0.45.2",
     "drizzle-seed": "^0.3.1",
     "nitro": "npm:nitro-nightly@3.0.1-20260424-182106-f8cf6ccc",
     "tailwindcss": "^4.2.4",

src/components/motion.tsx

@@ -16,7 +16,7 @@ export function MotionHeader({
 
   return (
     <motion.header
-      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 10 }}
+      initial={shouldReduceMotion ? false : { opacity: 0, y: 10 }}
       animate={{ opacity: 1, y: 0 }}
       transition={{ duration: 0.5, delay, ease: [0.25, 0.1, 0.25, 1] }}
       className={className}
@@ -37,7 +37,7 @@ export function MotionSection({
 
   return (
     <motion.section
-      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 10 }}
+      initial={shouldReduceMotion ? false : { opacity: 0, y: 10 }}
       animate={{ opacity: 1, y: 0 }}
       transition={{ duration: 0.5, delay, ease: [0.25, 0.1, 0.25, 1] }}
       className={className}
@@ -58,7 +58,7 @@ export function MotionDiv({
 
   return (
     <motion.div
-      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 10 }}
+      initial={shouldReduceMotion ? false : { opacity: 0, y: 10 }}
       animate={{ opacity: 1, y: 0 }}
       transition={{ duration: 0.5, delay, ease: [0.25, 0.1, 0.25, 1] }}
       className={className}
@@ -112,9 +112,11 @@ export function MotionTableRow({
   className,
   ...props
 }: { children: ReactNode } & ComponentPropsWithoutRef<typeof motion.tr>) {
+  const { shouldReduceMotion } = useMotionConfig()
+
   return (
     <motion.tr
-      initial={{ opacity: 0 }}
+      initial={shouldReduceMotion ? false : { opacity: 0 }}
       animate={{ opacity: 1 }}
       transition={{ duration: 0.3 }}
       className={className}

src/components/ui.tsx

@@ -152,3 +152,30 @@ export function SectionTitle({ icon, title, description }: { icon?: ReactNode; t
     </div>
   )
 }
+
+export function Skeleton({ className, ...props }: ComponentPropsWithoutRef<'div'>) {
+  return <div className={cn('rounded-md bg-white/5 motion-safe:animate-pulse', className)} {...props} />
+}
+
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  className,
+}: {
+  icon?: ReactNode
+  title: string
+  description?: string
+  action?: ReactNode
+  className?: string
+}) {
+  return (
+    <div className={cn('flex flex-col items-center justify-center py-12 text-center', className)}>
+      {icon && <div className="mb-4 text-zinc-500">{icon}</div>}
+      <h3 className="text-sm font-medium text-zinc-200">{title}</h3>
+      {description && <p className="mt-1 text-sm text-zinc-500 max-w-sm">{description}</p>}
+      {action && <div className="mt-6">{action}</div>}
+    </div>
+  )
+}

src/domain/battery.constants.ts

@@ -35,7 +35,7 @@ export function toMysqlBoolean(value: boolean) {
 
 export function fromMysqlBoolean(value: string | boolean) {
   if (typeof value === 'boolean') return value
-  return value.toLowerCase() === MYSQL_BOOLEAN.TRUE
+  return value.trim().toLowerCase() === MYSQL_BOOLEAN.TRUE
 }
 
 export const DEVICE_STATUS = {

src/domain/battery.test.ts

@@ -3,6 +3,7 @@ import {
   createBatteriesResponse,
   createDashboardSnapshot,
   DEVICE_STATUS,
+  fromMysqlBoolean,
   getDeviceStatus,
   MYSQL_BOOLEAN,
   POWER_STATUS,
@@ -27,7 +28,7 @@ const rows = [
     userId: 7,
     mac: 'RING-B11',
     devModel: '2402-B',
-    devName: 'RING-B11',
+    devName: '',
     isLowPower: MYSQL_BOOLEAN.TRUE,
     powerStatus: POWER_STATUS.CHARGING,
     power: 84,
@@ -43,6 +44,11 @@ describe('battery domain', () => {
     expect(getDeviceStatus(85)).toBe(DEVICE_STATUS.WARNING)
   })
 
+  test('trims MySQL boolean strings before normalization', () => {
+    expect(fromMysqlBoolean(' true ')).toBe(true)
+    expect(fromMysqlBoolean(' false ')).toBe(false)
+  })
+
   test('builds batteries response counters from records', () => {
     const now = new Date('2026-05-11T00:00:00.000Z')
     const items = rows.map(toBatteryInfo)
@@ -75,14 +81,18 @@ describe('battery domain', () => {
     const snapshot = createDashboardSnapshot(rows.map(toBatteryInfo), now)
 
     expect(snapshot.devices).toHaveLength(2)
+    expect(snapshot.devices[0]?.id).toBe('RING-A03')
+    expect(snapshot.devices[0]?.displayName).toBe('RING-A03')
+    expect(snapshot.devices[1]?.id).toBe('RING-B11')
+    expect(snapshot.devices[1]?.displayName).toBe('RING-B11')
     expect(snapshot.devices.every((device) => device.sohSource === 'unavailable')).toBe(true)
     expect(snapshot.devices.every((device) => device.soh === null)).toBe(true)
     expect(snapshot.devices.every((device) => device.soh30d === null)).toBe(true)
     expect(snapshot.devices.every((device) => device.soh90d === null)).toBe(true)
     expect(snapshot.devices.every((device) => device.soh60d === null)).toBe(true)
-    expect(snapshot.devices.every((device) => device.cycles === 0)).toBe(true)
-    expect(snapshot.devices.every((device) => device.temperature === 0)).toBe(true)
-    expect(snapshot.devices.every((device) => device.chargeEfficiency === 0)).toBe(true)
+    expect(snapshot.devices.every((device) => device.cycles === null)).toBe(true)
+    expect(snapshot.devices.every((device) => device.temperature === null)).toBe(true)
+    expect(snapshot.devices.every((device) => device.chargeEfficiency === null)).toBe(true)
     expect(snapshot.devices[0]?.firmware).toBe('v3.8.2')
     expect(snapshot.devices[1]?.firmware).toBe('未提供')
     expect(snapshot.soh.history).toHaveLength(0)
@@ -130,8 +140,8 @@ describe('battery domain', () => {
     expect(predicted?.cycles).toBe(6)
     expect(predicted?.firmware).toBe('v3.8.2')
     expect(predicted?.status).toBe(DEVICE_STATUS.WARNING)
-    expect(predicted?.temperature).toBe(0)
-    expect(predicted?.chargeEfficiency).toBe(0)
+    expect(predicted?.temperature).toBeNull()
+    expect(predicted?.chargeEfficiency).toBeNull()
     expect(snapshot.soh.history).toHaveLength(0)
     expect(snapshot.soh.forecast).toHaveLength(3)
     expect(snapshot.soh.forecast[0]).toEqual({ month: '当前', value: 60 })

src/domain/battery.ts

@@ -54,17 +54,18 @@ export type BatteryInfo = z.infer<typeof batteryInfoSchema>
 
 export const fleetUnitSchema = z.object({
   id: z.string(),
+  displayName: z.string(),
   batch: z.string(),
   firmware: z.string(),
-  cycles: z.number().int(),
+  cycles: z.number().int().nullable(),
   soh: z.number().nullable(),
   sohSource: z.union([z.literal('prediction'), z.literal('unavailable')]),
   soh30d: z.number().nullable(),
   soh60d: z.number().nullable(),
   soh90d: z.number().nullable(),
-  temperature: z.number(),
+  temperature: z.number().nullable(),
   riskScore: z.number().int(),
-  chargeEfficiency: z.number(),
+  chargeEfficiency: z.number().nullable(),
   status: deviceStatusSchema,
   riskFactors: z.array(z.string()),
 })
@@ -259,18 +260,19 @@ function toFleetUnit(item: BatteryInfo, prediction?: BatteryPrediction): FleetUn
   const soh30d = prediction ? round1(clamp(prediction.monthSoh, 0, 100)) : null
   const soh90d = prediction ? round1(clamp(prediction.trmonthSoh, 0, 100)) : null
   const soh60d = null
-  const temperature = 0
-  const chargeEfficiency = 0
+  const temperature = null
+  const chargeEfficiency = null
   const fallbackRiskScore =
     (item.isLowPower || item.power <= SOH_THRESHOLDS.LOW_POWER ? 60 : 0) +
     (item.powerStatus === POWER_STATUS.CHARGING ? 20 : 0)
   const riskScore = Math.round(clamp(prediction?.riskScore ?? fallbackRiskScore, 0, 100))
 
   return {
-    id: item.devName || item.mac,
+    id: item.mac,
+    displayName: item.devName || item.mac,
     batch: item.devModel,
     firmware: item.remark ?? '未提供',
-    cycles: prediction?.cyclesUsed ?? 0,
+    cycles: prediction?.cyclesUsed ?? null,
     soh,
     sohSource: prediction ? 'prediction' : 'unavailable',
     soh30d,

src/env.ts

@@ -4,11 +4,13 @@ import { z } from 'zod'
 export const env = createEnv({
   server: {
     DATABASE_URL: z.url({ protocol: /^mysql$/ }),
+    ENABLE_API_DOCS: z.stringbool().default(false),
     LOG_DB: z.stringbool().default(false),
     LOG_FORMAT: z.enum(['pretty', 'json']).optional(),
     LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warning', 'error', 'fatal']).default('info'),
     SOH_PREDICTION_API_BASE_URL: z.url({ protocol: /^https?$/ }),
     SOH_PREDICTION_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(86_400),
+    SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(300),
     SOH_PREDICTION_TIMEOUT_MS: z.coerce.number().int().positive().default(10_000),
   },
   clientPrefix: 'VITE_',

src/routes/api/$.ts

@@ -4,24 +4,27 @@ import { onError } from '@orpc/server'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
 import { createFileRoute } from '@tanstack/react-router'
 import { name, version } from '#package'
+import { env } from '@/env'
 import { handleValidationError, logError } from '@/server/api/interceptors'
 import { router } from '@/server/api/routers'
 
 const handler = new OpenAPIHandler(router, {
-  plugins: [
-    new OpenAPIReferencePlugin({
-      docsProvider: 'scalar',
-      schemaConverters: [new ZodToJsonSchemaConverter()],
-      specGenerateOptions: {
-        info: {
-          title: name,
-          version,
-        },
-      },
-      docsPath: '/docs',
-      specPath: '/spec.json',
-    }),
-  ],
+  plugins: env.ENABLE_API_DOCS
+    ? [
+        new OpenAPIReferencePlugin({
+          docsProvider: 'scalar',
+          schemaConverters: [new ZodToJsonSchemaConverter()],
+          specGenerateOptions: {
+            info: {
+              title: name,
+              version,
+            },
+          },
+          docsPath: '/docs',
+          specPath: '/spec.json',
+        }),
+      ]
+    : [],
   interceptors: [onError(logError)],
   clientInterceptors: [onError(handleValidationError)],
 })
@@ -30,6 +33,8 @@ export const Route = createFileRoute('/api/$')({
   server: {
     handlers: {
       ANY: async ({ request }) => {
+        if (!env.ENABLE_API_DOCS) return new Response('Not Found', { status: 404 })
+
         const { response } = await handler.handle(request, {
           prefix: '/api',
           context: {

src/routes/batteries.tsx

@@ -1,12 +1,12 @@
 import { useQuery } from '@tanstack/react-query'
 import { createFileRoute, Link, useNavigate } from '@tanstack/react-router'
 import { createColumnHelper, flexRender, getCoreRowModel, useReactTable } from '@tanstack/react-table'
-import { ArrowLeft, Battery, BatteryCharging, BatteryLow, FilterX, Search, Zap } from 'lucide-react'
+import { ArrowLeft, Battery, BatteryCharging, BatteryLow, FilterX, Search, X, Zap } from 'lucide-react'
 import { useEffect, useMemo, useState } from 'react'
 import { z } from 'zod'
 import { orpc } from '@/client/orpc'
 import { MotionCardDiv, MotionHeader, MotionSection, MotionTableRow } from '@/components/motion'
-import { Badge, Button, Card, Input, SectionTitle, Select, SelectOption } from '@/components/ui'
+import { Badge, Button, Card, EmptyState, Input, SectionTitle, Select, SelectOption, Skeleton } from '@/components/ui'
 import type { BatteryInfo, BatteryListSort, PowerStatus } from '@/domain/battery'
 import { BATTERY_LIST_SORT, BATTERY_LIST_SORT_VALUES, POWER_STATUS, POWER_STATUS_VALUES } from '@/domain/battery'
 
@@ -14,6 +14,7 @@ const pageSizeOptions = [20, 50, 100] as const
 type PageSizeOption = (typeof pageSizeOptions)[number]
 const firstPageCursor = '__FIRST_PAGE__'
 const allPowerStatusValue = 'all'
+const loadingRowKeys = Array.from({ length: 10 }, (_, index) => `loading-row-${index}`)
 
 const searchFilterSchema = z.preprocess(
   (value) => (typeof value === 'string' ? value.trim() || undefined : value),
@@ -314,10 +315,20 @@ function BatteriesPage() {
                     type="text"
                     placeholder="搜索设备名称或编号..."
                     maxLength={100}
-                    className="pl-9"
+                    className="pl-9 pr-9"
                     value={localSearch}
                     onChange={(e) => setLocalSearch(e.target.value)}
                   />
+                  {localSearch && (
+                    <button
+                      type="button"
+                      aria-label="清空搜索内容"
+                      onClick={() => setLocalSearch('')}
+                      className="absolute right-3 top-1/2 -translate-y-1/2 text-zinc-500 hover:text-zinc-300"
+                    >
+                      <X className="size-4" />
+                    </button>
+                  )}
                 </div>
               </div>
 
@@ -421,9 +432,9 @@ function BatteriesPage() {
           </Card>
 
           <Card className="overflow-hidden">
-            <div className="overflow-x-auto">
+            <div className="overflow-x-auto max-h-[600px]">
               <table className={`w-full border-collapse text-left text-sm ${isPlaceholderData ? 'opacity-60' : ''}`}>
-                <thead>
+                <thead className="sticky top-0 z-10 bg-zinc-950/90 backdrop-blur-sm">
                   {table.getHeaderGroups().map((headerGroup) => (
                     <tr key={headerGroup.id} className="border-b border-white/5 bg-white/[0.02]">
                       {headerGroup.headers.map((header) => (
@@ -436,15 +447,46 @@ function BatteriesPage() {
                 </thead>
                 <tbody className="divide-y divide-white/[0.02]">
                   {isPending && !isPlaceholderData ? (
-                    <tr>
-                      <td colSpan={columns.length} className="h-32 text-center text-zinc-500">
-                        加载中…
-                      </td>
-                    </tr>
+                    loadingRowKeys.map((key) => (
+                      <tr key={key}>
+                        <td className="px-6 py-4">
+                          <Skeleton className="h-5 w-32" />
+                          <Skeleton className="mt-1.5 h-3 w-24" />
+                        </td>
+                        <td className="px-6 py-4">
+                          <Skeleton className="h-4 w-20" />
+                        </td>
+                        <td className="px-6 py-4">
+                          <div className="flex items-center gap-3">
+                            <Skeleton className="h-4 w-8" />
+                            <Skeleton className="h-1.5 w-16 rounded-full" />
+                          </div>
+                        </td>
+                        <td className="px-6 py-4">
+                          <Skeleton className="h-6 w-16 rounded-full" />
+                        </td>
+                        <td className="px-6 py-4">
+                          <Skeleton className="h-4 w-32" />
+                        </td>
+                      </tr>
+                    ))
                   ) : data?.items.length === 0 ? (
                     <tr>
-                      <td colSpan={columns.length} className="h-32 text-center text-zinc-500">
-                        未找到符合条件的设备
+                      <td colSpan={columns.length} className="h-64">
+                        <EmptyState
+                          icon={<Battery className="size-8" />}
+                          title="未找到符合条件的设备"
+                          description={
+                            hasActiveFilters ? '尝试调整筛选条件或清除筛选以查看更多设备。' : '当前暂无设备数据接入。'
+                          }
+                          action={
+                            hasActiveFilters ? (
+                              <Button onClick={clearFilters}>
+                                <FilterX className="size-4" /> 清除筛选
+                              </Button>
+                            ) : undefined
+                          }
+                        />
                       </td>
                     </tr>
                   ) : (

src/routes/index.tsx

@@ -15,7 +15,7 @@ import {
 import type { NameType, ValueType } from 'recharts/types/component/DefaultTooltipContent'
 import { orpc } from '@/client/orpc'
 import { MotionCardArticle, MotionCardDiv, MotionHeader, MotionSection } from '@/components/motion'
-import { Badge, Card, SectionTitle } from '@/components/ui'
+import { Badge, Card, EmptyState, SectionTitle } from '@/components/ui'
 import type { DashboardSnapshot, DeviceStatus } from '@/domain/battery'
 import { BATTERY_LIST_SORT, DEVICE_STATUS } from '@/domain/battery'
 
@@ -93,7 +93,11 @@ function formatPercentWithUnit(value: number | null) {
 
 function formatDelta(from: number | null, to: number | null) {
   if (from === null || to === null) return '预测不可用'
-  return `${(from - to).toFixed(1)}% 衰减`
+  const delta = from - to
+
+  if (delta < 0) return `${Math.abs(delta).toFixed(1)}% 改善`
+  if (delta === 0) return '0.0% 持平'
+  return `${delta.toFixed(1)}% 衰减`
 }
 
 function widthPercent(value: number | null) {
@@ -266,19 +270,19 @@ function Dashboard() {
                   <ComposedChart data={chartData} margin={{ top: 24, right: 24, bottom: 8, left: 0 }}>
                     <defs>
                       <linearGradient id="historyFill" x1="0" y1="0" x2="0" y2="1">
-                        <stop offset="0%" stopColor="#2DD4BF" stopOpacity={0.15} />
+                        <stop offset="0%" stopColor="#2DD4BF" stopOpacity={0.25} />
                         <stop offset="100%" stopColor="#2DD4BF" stopOpacity={0} />
                       </linearGradient>
                       <linearGradient id="forecastFill" x1="0" y1="0" x2="0" y2="1">
-                        <stop offset="0%" stopColor="#818CF8" stopOpacity={0.15} />
+                        <stop offset="0%" stopColor="#818CF8" stopOpacity={0.25} />
                         <stop offset="100%" stopColor="#818CF8" stopOpacity={0} />
                       </linearGradient>
                     </defs>
                     <CartesianGrid stroke="#ffffff" strokeOpacity={0.05} vertical={false} />
-                    <XAxis dataKey="month" tick={{ fill: '#71717A', fontSize: 11 }} axisLine={false} tickLine={false} />
+                    <XAxis dataKey="month" tick={{ fill: '#A1A1AA', fontSize: 12 }} axisLine={false} tickLine={false} />
                     <YAxis
                       domain={[(min: number) => Math.floor(min) - 2, (max: number) => Math.ceil(max) + 2]}
-                      tick={{ fill: '#71717A', fontSize: 11 }}
+                      tick={{ fill: '#A1A1AA', fontSize: 12 }}
                       axisLine={false}
                       tickLine={false}
                       tickFormatter={(v: number) => `${v}%`}
@@ -291,20 +295,21 @@ function Dashboard() {
                         borderRadius: 8,
                         fontSize: 13,
                         color: '#F4F4F5',
+                        boxShadow: '0 10px 15px -3px rgba(0, 0, 0, 0.5)',
                       }}
-                      itemStyle={{ color: '#A1A1AA' }}
+                      itemStyle={{ color: '#E4E4E7', fontWeight: 500 }}
                       formatter={formatChartTooltip}
-                      labelStyle={{ color: '#71717A', marginBottom: 4 }}
+                      labelStyle={{ color: '#A1A1AA', marginBottom: 6 }}
                     />
                     <ReferenceLine
                       y={85}
                       stroke="#F87171"
-                      strokeOpacity={0.4}
+                      strokeOpacity={0.6}
                       strokeDasharray="4 4"
                       label={{
                         value: '85% 预警线',
                         fill: '#F87171',
-                        fontSize: 11,
+                        fontSize: 12,
                         position: 'right',
                       }}
                     />
@@ -354,8 +359,12 @@ function Dashboard() {
                   </ComposedChart>
                 </ResponsiveContainer>
               ) : (
-                <div className="flex h-full items-center justify-center rounded-xl border border-dashed border-white/10 bg-white/[0.02] text-sm text-[#71717A]">
-                  暂无可用的健康趋势数据。
+                <div className="flex h-full items-center justify-center rounded-xl border border-dashed border-white/10 bg-white/[0.02]">
+                  <EmptyState
+                    icon={<TrendingDown className="size-8" />}
+                    title="暂无健康趋势数据"
+                    description="当前设备数据不足以生成可靠的健康趋势预测，请等待系统收集更多数据。"
+                  />
                 </div>
               )}
             </div>
@@ -540,7 +549,7 @@ function Dashboard() {
                       .sort((a, b) => b.riskScore - a.riskScore)
                       .map((unit) => (
                         <tr key={unit.id} className="transition-colors hover:bg-white/[0.04]">
-                          <td className="px-6 py-4 font-medium text-white">{unit.id}</td>
+                          <td className="px-6 py-4 font-medium text-white">{unit.displayName}</td>
                           <td className="px-6 py-4 text-[#A1A1AA]">{unit.batch}</td>
                           <td className="px-6 py-4 tabular-nums text-white">{formatPercentWithUnit(unit.soh)}</td>
                           <td className="px-6 py-4 tabular-nums text-[#A1A1AA]">
@@ -586,8 +595,12 @@ function Dashboard() {
                       ))
                   ) : (
                     <tr>
-                      <td colSpan={8} className="px-6 py-8 text-center text-[#71717A]">
-                        暂无设备数据
+                      <td colSpan={8} className="px-6 py-12">
+                        <EmptyState
+                          icon={<Activity className="size-8" />}
+                          title="暂无设备数据"
+                          description="当前没有可用于健康分析的设备记录。"
+                        />
                       </td>
                     </tr>
                   )}

src/server/battery/mysql.ts

@@ -54,6 +54,7 @@ function getBatteryPool() {
     waitForConnections: true,
     connectionLimit: 5,
     namedPlaceholders: true,
+    dateStrings: true,
   })
 
   return pool
@@ -166,7 +167,7 @@ function createLatestWhere(input: LatestBatteryPageInput, cursor: PageCursor | n
   }
 
   if (input.lowPower !== undefined) {
-    clauses.push('current_record.is_low_power = :lowPower')
+    clauses.push('LOWER(TRIM(current_record.is_low_power)) = :lowPower')
     params.lowPower = toMysqlBoolean(input.lowPower)
   }
 
@@ -294,7 +295,7 @@ export async function getLatestBatteryPage(input: LatestBatteryPageInput): Promi
     `
       SELECT
         COUNT(*) AS total,
-        COALESCE(SUM(CASE WHEN current_record.is_low_power = '${MYSQL_BOOLEAN.TRUE}' THEN 1 ELSE 0 END), 0) AS lowPower,
+        COALESCE(SUM(CASE WHEN LOWER(TRIM(current_record.is_low_power)) = '${MYSQL_BOOLEAN.TRUE}' THEN 1 ELSE 0 END), 0) AS lowPower,
         COALESCE(SUM(CASE WHEN current_record.power_status = ${POWER_STATUS.CHARGING} THEN 1 ELSE 0 END), 0) AS charging
       FROM ls_battery_info AS current_record
       WHERE ${countWhere.whereSql}

src/server/prediction/client.test.ts

@@ -0,0 +1,97 @@
+import { beforeAll, describe, expect, test } from 'bun:test'
+import type { BatteryInfo } from '@/domain/battery'
+import { MYSQL_BOOLEAN, POWER_STATUS, toBatteryInfo } from '@/domain/battery'
+import type { normalizePrediction as normalizePredictionType } from './client'
+
+type PredictionClientModule = typeof import('./client')
+
+const battery = toBatteryInfo({
+  id: 10,
+  userId: 7,
+  mac: 'RING-A03',
+  devModel: '2401-A',
+  devName: 'RING-A03',
+  isLowPower: MYSQL_BOOLEAN.FALSE,
+  powerStatus: POWER_STATUS.FULL,
+  power: 94,
+  createTime: '2026-05-10 23:00:00',
+  remark: null,
+})
+
+const predictionResponse = {
+  battery_id: 10,
+  mac: 'RING-A03',
+  now_soh: 91,
+  month_soh: 89,
+  trmonth_soh: 84,
+  risk_score: null,
+  risk_level: null,
+  status: null,
+  model_name: 'xgboost',
+  cycles_used: 6,
+  updated_at: '2026-05-11T00:00:00.000Z',
+}
+
+let createPredictionRequest: PredictionClientModule['createPredictionRequest']
+let isPredictionForBattery: PredictionClientModule['isPredictionForBattery']
+let normalizePrediction: typeof normalizePredictionType
+
+beforeAll(async () => {
+  process.env.DATABASE_URL = 'mysql://user:password@localhost:3306/database'
+  process.env.SOH_PREDICTION_API_BASE_URL = 'http://127.0.0.1:8000'
+
+  const client = await import('./client')
+  createPredictionRequest = client.createPredictionRequest
+  isPredictionForBattery = client.isPredictionForBattery
+  normalizePrediction = client.normalizePrediction
+})
+
+describe('prediction client helpers', () => {
+  test('normalizes prediction response shape without fake fallback values', () => {
+    const prediction = normalizePrediction(predictionResponse)
+
+    expect(prediction).toEqual({
+      batteryId: 10,
+      mac: 'RING-A03',
+      nowSoh: 91,
+      monthSoh: 89,
+      trmonthSoh: 84,
+      riskScore: null,
+      riskLevel: null,
+      status: null,
+      modelName: 'xgboost',
+      cyclesUsed: 6,
+      updatedAt: '2026-05-11T00:00:00.000Z',
+    })
+  })
+
+  test('requires prediction responses to belong to the requested battery', () => {
+    expect(isPredictionForBattery(normalizePrediction(predictionResponse), battery)).toBe(true)
+    expect(isPredictionForBattery({ batteryId: 11, mac: battery.mac }, battery as BatteryInfo)).toBe(false)
+    expect(isPredictionForBattery({ batteryId: battery.id, mac: 'RING-B11' }, battery as BatteryInfo)).toBe(false)
+  })
+
+  test('returns null for history-insufficient prediction requests', () => {
+    expect(createPredictionRequest(battery, [battery, battery, battery, battery])).toBeNull()
+  })
+
+  test('creates minimal cycle payload accepted by prediction service', () => {
+    const request = createPredictionRequest(battery, [battery, battery, battery, battery, battery])
+    const firstHistory = request?.history[0]
+
+    expect(request?.battery).toMatchObject({
+      id: battery.id,
+      user_id: battery.userId,
+      mac: battery.mac,
+      power: battery.power,
+    })
+    expect(firstHistory).toEqual({
+      cycle: 1,
+      charge_capacity_ah: 3.01,
+      discharge_capacity_ah: 2.89,
+      timestamp: battery.createTime,
+    })
+    expect(Object.hasOwn(firstHistory ?? {}, 'charge_energy_wh')).toBe(false)
+    expect(Object.hasOwn(firstHistory ?? {}, 'coulombic_efficiency_pct')).toBe(false)
+  })
+})

src/server/prediction/client.ts

@@ -1,12 +1,6 @@
 import { LRUCache } from 'lru-cache'
 import { z } from 'zod'
-import {
-  type BatteryInfo,
-  type BatteryPrediction,
-  POWER_STATUS,
-  type PowerStatus,
-  toMysqlBoolean,
-} from '@/domain/battery'
+import { type BatteryInfo, type BatteryPrediction, type PowerStatus, toMysqlBoolean } from '@/domain/battery'
 import { env } from '@/env'
 import { getLogger } from '@/server/logger'
 
@@ -29,11 +23,6 @@ type PredictionHistoryItem = {
   cycle: number
   charge_capacity_ah: number
   discharge_capacity_ah: number
-  charge_energy_wh: number
-  discharge_energy_wh: number
-  charge_time: string
-  discharge_time: string
-  coulombic_efficiency_pct: number
   timestamp: string
 }
 
@@ -72,7 +61,12 @@ const cache = new LRUCache<string, SohPrediction>({
   max: 5_000,
   ttl: env.SOH_PREDICTION_CACHE_TTL_SECONDS * 1000,
 })
+const negativeCache = new LRUCache<string, true>({
+  max: 5_000,
+  ttl: env.SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS * 1000,
+})
 const inFlightRequests = new Map<string, Promise<SohPrediction | null>>()
+const nominalCapacityAh = 3.2
 
 const round2 = (value: number) => Math.round(value * 100) / 100
 
@@ -91,22 +85,13 @@ function createCacheKey(battery: BatteryInfo, history: BatteryInfo[]) {
 }
 
 function createHistoryItem(item: BatteryInfo, index: number): PredictionHistoryItem {
-  const sohRatio = Math.max(0.5, Math.min(1, item.power / 100))
-  const chargeCapacity = round2(3.2 * sohRatio)
-  const efficiency = round2(Math.max(80, Math.min(99, 92 + item.power / 12 - (item.isLowPower ? 4 : 0))))
-  const dischargeCapacity = round2(chargeCapacity * (efficiency / 100))
-  const chargeEnergy = round2(chargeCapacity * 3.75)
-  const dischargeEnergy = round2(dischargeCapacity * 3.7)
+  const observedCapacityRatio = Math.max(0.5, Math.min(1, item.power / 100))
+  const chargeCapacityAh = round2(nominalCapacityAh * observedCapacityRatio)
 
   return {
     cycle: index + 1,
-    charge_capacity_ah: chargeCapacity,
-    discharge_capacity_ah: dischargeCapacity,
-    charge_energy_wh: chargeEnergy,
-    discharge_energy_wh: dischargeEnergy,
-    charge_time: item.powerStatus === POWER_STATUS.CHARGING ? '01:20:00' : '01:18:00',
-    discharge_time: item.isLowPower ? '00:58:00' : '01:10:00',
-    coulombic_efficiency_pct: efficiency,
+    charge_capacity_ah: chargeCapacityAh,
+    discharge_capacity_ah: round2(chargeCapacityAh * 0.96),
     timestamp: normalizeMysqlDateTime(item.createTime),
   }
 }
@@ -133,7 +118,7 @@ export function createPredictionRequest(battery: BatteryInfo, history: BatteryIn
   }
 }
 
-function normalizePrediction(response: z.infer<typeof predictionResponseSchema>): SohPrediction {
+export function normalizePrediction(response: z.infer<typeof predictionResponseSchema>): SohPrediction {
   return {
     batteryId: response.battery_id,
     mac: response.mac,
@@ -149,15 +134,24 @@ function normalizePrediction(response: z.infer<typeof predictionResponseSchema>)
   }
 }
 
+export function isPredictionForBattery(prediction: Pick<SohPrediction, 'batteryId' | 'mac'>, battery: BatteryInfo) {
+  return prediction.batteryId === battery.id && prediction.mac === battery.mac
+}
+
 export function isPredictionEnabled() {
   return true
 }
 
 export async function predictSoh(battery: BatteryInfo, history: BatteryInfo[]): Promise<SohPrediction | null> {
-  const request = createPredictionRequest(battery, history)
-  if (!request) return null
-
   const cacheKey = createCacheKey(battery, history)
+  if (negativeCache.has(cacheKey)) return null
+
+  const request = createPredictionRequest(battery, history)
+  if (!request) {
+    negativeCache.set(cacheKey, true)
+    return null
+  }
+
   const cached = cache.get(cacheKey)
   if (cached) return cached
   const pendingRequest = inFlightRequests.get(cacheKey)
@@ -191,24 +185,41 @@ async function requestPrediction(
 
     if (!response.ok) {
       logger.warn('SOH prediction request failed', { mac: battery.mac, status: response.status })
-      return null
+      return cacheNegativePrediction(cacheKey)
     }
 
     const json = await response.json()
     const prediction = normalizePrediction(predictionResponseSchema.parse(json))
+    if (!isPredictionForBattery(prediction, battery)) {
+      logger.warn('SOH prediction response mismatched requested battery', {
+        requestedBatteryId: battery.id,
+        requestedMac: battery.mac,
+        responseBatteryId: prediction.batteryId,
+        responseMac: prediction.mac,
+      })
+      return cacheNegativePrediction(cacheKey)
+    }
+
     cache.set(cacheKey, prediction)
+    negativeCache.delete(cacheKey)
 
     return prediction
   } catch (error) {
     logger.warn('SOH prediction request errored', { mac: battery.mac, error })
-    return null
+    return cacheNegativePrediction(cacheKey)
   } finally {
     clearTimeout(timeout)
     inFlightRequests.delete(cacheKey)
   }
 }
 
+function cacheNegativePrediction(cacheKey: string) {
+  negativeCache.set(cacheKey, true)
+  return null
+}
+
 export function clearPredictionCache() {
   cache.clear()
+  negativeCache.clear()
   inFlightRequests.clear()
 }