@mzzsfy/dsh-usage-dash 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@
 
 设置页「使用统计」区块:
 
-- 三粒度视图:天(7/30/90 天/自定义日期段)、小时(24 小时/3 天/7 天/15 天)、分钟(3 小时/24 小时/3 天/7 天,10 分钟桶粒度),后两者为滚动窗口;各视图时间范围统一 4 挡,时/分选择上限与数据保留期一致
+- 三粒度视图,全部支持自定义时间范围:天(7/30/90 天/自定义日期段)、小时(24 小时/3 天/7 天/15 天/自定义时刻段)、分钟(3 小时/24 小时/3 天/7 天/自定义时刻段,10 分钟桶粒度),预设挡为滚动窗口;自定义时刻段为起止 datetime 双输入,两端归一到桶边界(小时取所在整点、分钟起点对齐 10 分钟且终点保留原分钟,均闭区间),跨度上限与数据保留期一致(小时 15 天、分钟 7 天,超限自动钳起点),首次切到自定义挡预填最近 24 小时,时/分两视图共享同一对自定义输入;已知限制:自定义输入残缺(任一端为空)时面板不发请求且图表静默空白,与天视图行为一致,交互反馈留待后续增强
 - 汇总卡六张:Tokens 用量(服务商总口径)、会话数量、请求数量、最常用模型、平均缓存命中率、活跃天数(恒按天口径,不随视图切换);配置定价规则后 Tokens 卡头部行右侧显示估算费用
 - 活动热力图:GitHub 风格周列×星期行,26 周窗口,五档色阶,悬停明细;仅按天视图展示
 - 缓存命中率曲线:日粒度命中率 + 右侧副轴,并叠加平均生成速度曲线与首 token 延迟曲线(各自单独颜色,读数走悬停;仅含配对数据的槽参与,整图无数据不绘制),悬停显示当前时段命中率、平均生成速度、首 token 延迟与 token 明细(配置定价规则后附当前时段估算费用行,受「费用显示」开关;三粒度趋势图通用)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-usage-dash",
   "description": "用量统计面板:天/小时/分钟三粒度 token 与请求统计,26 周活跃热力图,会话底栏信息接管与官方动作行回合费用芯片,多条件分时段定价规则与费用估算;复刻自 github.com/HaoyueQin/dsh-usage-statistics-panel,感谢原作者 HaoyueQin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -77,9 +77,76 @@ function resolveMinuteRange(presetId, now = new Date()) {
   return { from, to: minuteBucket(now) }
 }
 
+// 自定义挡 id 与时/分自定义跨度上限(与数据保留期一致:小时桶固定 15 天,分钟桶上限 7 天)
+const CUSTOM_RANGE_ID = 'custom'
+const HOUR_CUSTOM_MAX_HOURS = 15 * 24
+const MINUTE_CUSTOM_MAX_MINUTES = 7 * 24 * 60
+// 选中自定义挡且无历史输入时的预填窗口
+const POINT_CUSTOM_DEFAULT_HOURS = 24
+
+const DATETIME_INPUT_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/
+
+// datetime-local 输入值解析为本地时刻,形态或日历非法(13 月/2 月 30 日/回卷)返回 null
+function parseLocalDateTime(value) {
+  if (typeof value !== 'string') return null
+  const match = DATETIME_INPUT_PATTERN.exec(value)
+  if (!match) return null
+  const [year, month, day, hour, minute, second] = match.slice(1)
+  const parts = [Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second ?? 0)]
+  const date = new Date(...parts)
+  const components = [date.getFullYear(), date.getMonth(), date.getDate(), date.getHours(), date.getMinutes()]
+  // 数字分量构造对超界值静默回卷,逐分量回读比对拦截
+  const legal = parts.slice(0, 5).every((part, index) => components[index] === part)
+  return legal ? date : null
+}
+
+const formatDateTimeInput = (date) => `${formatDate(date)}T${pad(date.getHours())}:${pad(date.getMinutes())}`
+
+// 小时自定义范围:两端归一到所在小时桶(闭区间),跨度超保留期钳起点
+function resolveHourCustomRange(fromValue, toValue) {
+  const from = parseLocalDateTime(fromValue)
+  const to = parseLocalDateTime(toValue)
+  if (!from || !to || from > to) return null
+  const clampedFrom = new Date(Math.max(from.getTime(), to.getTime() - HOUR_CUSTOM_MAX_HOURS * MS_PER_HOUR))
+  return { from: hourBucket(clampedFrom), to: hourBucket(to) }
+}
+
+// 分钟自定义范围:from 对齐 10 分钟桶边界,to 保持原始分钟(闭区间上界),跨度超保留期钳起点
+function resolveMinuteCustomRange(fromValue, toValue) {
+  const from = parseLocalDateTime(fromValue)
+  const to = parseLocalDateTime(toValue)
+  if (!from || !to || from > to) return null
+  const clampedFrom = Math.max(
+    minuteBucketFloor(from.getTime()),
+    minuteBucketFloor(to.getTime()) - MINUTE_CUSTOM_MAX_MINUTES * MS_PER_MINUTE,
+  )
+  return { from: minuteBucket(new Date(clampedFrom)), to: minuteBucket(to) }
+}
+
+// 时/分查询请求与缓存键:预设挡键为挡位 id,自定义挡键含归一后桶串(范围变化即换键防误命中)
+function resolvePointQuery(view, preset, customFrom, customTo, now = new Date()) {
+  if (view === 'hour') {
+    if (preset === CUSTOM_RANGE_ID) {
+      const range = resolveHourCustomRange(customFrom, customTo)
+      return range ? { request: range, key: `${CUSTOM_RANGE_ID}:${range.from}:${range.to}` } : null
+    }
+    return { request: resolveHourRange(preset, now), key: preset }
+  }
+  if (view === 'minute') {
+    if (preset === CUSTOM_RANGE_ID) {
+      const range = resolveMinuteCustomRange(customFrom, customTo)
+      return range ? { request: range, key: `${CUSTOM_RANGE_ID}:${range.from}:${range.to}` } : null
+    }
+    return { request: resolveMinuteRange(preset, now), key: preset }
+  }
+  return null
+}
+
 function maxSlotsFor(view, presetId) {
-  if (view === 'hour') return hourValueOf(presetId) + 1
-  if (view === 'minute') return minuteValueOf(presetId) / MINUTE_BUCKET_SPAN_MINUTES + 1
+  if (view === 'hour') return (presetId === CUSTOM_RANGE_ID ? HOUR_CUSTOM_MAX_HOURS : hourValueOf(presetId)) + 1
+  if (view === 'minute') {
+    return (presetId === CUSTOM_RANGE_ID ? MINUTE_CUSTOM_MAX_MINUTES : minuteValueOf(presetId)) / MINUTE_BUCKET_SPAN_MINUTES + 1
+  }
   return DAY_MAX_SLOTS
 }
 
@@ -113,8 +180,8 @@ const MESSAGES_ZH = {
   'rangePreset.30': '30 天',
   'rangePreset.90': '90 天',
   rangeCustom: '自定义',
-  from: '开始日期',
-  to: '结束日期',
+  from: '开始',
+  to: '结束',
   refresh: '刷新',
   loading: '正在扫描历史会话。安装插件后首次会全量回扫,数据量大时耗时较久,期间尽量减少操作以免服务变卡',
   tokens: 'Tokens 用量',
@@ -824,29 +891,33 @@ function heatLevel(tokens, max) {
   return tokens === 0 ? 0 : 1 + Math.floor((tokens / max) * HEAT_LEVEL_BANDS)
 }
 
-// ChartTip 定位:锚定区装得下贴内顶(趋势图悬停区即绘图区,悬浮窗留在图表内),装不下上翻、再下翻、末了钳边界顶
+// ChartTip 定位:进入命中区时锚定指针,先放指针右下,右侧或下方越界翻对侧,仍越界钳进边界
 const TIP_GAP_PX = 8
 const TIP_MARGIN_PX = 8
 
+// 悬停锚点:指针事件取指针坐标;焦点事件无坐标,回退目标矩形中心保键盘可访问
+const pointerAt = (event) => {
+  if (event.clientX != null && event.clientY != null) return { x: event.clientX, y: event.clientY }
+  const rect = event.currentTarget.getBoundingClientRect()
+  return { x: (rect.left + rect.right) / 2, y: (rect.top + rect.bottom) / 2 }
+}
+
 // 回合费用芯片与前置官方芯片(结束时钟)的间距
 const TURN_COST_GAP_PX = 8
 
 function tipPlace(anchor, tip, bounds, gap = TIP_GAP_PX, margin = TIP_MARGIN_PX) {
   if (!tip || tip.width <= 0 || tip.height <= 0) return null
-  if (!anchor || (anchor.left === 0 && anchor.top === 0 && anchor.right === 0 && anchor.bottom === 0)) return null
+  if (!anchor || !Number.isFinite(anchor.x) || !Number.isFinite(anchor.y)) return null
   const minX = bounds.left + margin
   const minY = bounds.top + margin
-  const maxX = bounds.right - margin
-  const maxY = bounds.bottom - margin
-  const left = Math.max(minX, Math.min((anchor.left + anchor.right) / 2 - tip.width / 2, maxX - tip.width))
-  const inside = anchor.top + gap
-  const above = anchor.top - gap - tip.height
-  const below = anchor.bottom + gap
-  let top
-  if (inside + tip.height <= anchor.bottom) top = inside
-  else if (above >= minY) top = above
-  else if (below + tip.height <= maxY) top = below
-  else top = minY
+  const maxLeft = bounds.right - margin - tip.width
+  const maxTop = bounds.bottom - margin - tip.height
+  const left = anchor.x + gap + tip.width <= bounds.right - margin
+    ? anchor.x + gap
+    : Math.max(minX, Math.min(anchor.x - gap - tip.width, maxLeft))
+  const top = anchor.y + gap + tip.height <= bounds.bottom - margin
+    ? anchor.y + gap
+    : Math.max(minY, Math.min(anchor.y - gap - tip.height, maxTop))
   return { left, top }
 }
 
@@ -2105,7 +2176,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
       const hoverRatePoint = showRate && hoverSlot ? ratePoints.find((point) => point.day === hoverSlot.day) : null
       const hoverSpeedPoint = hoverSlot ? speedPoints.find((point) => point.day === hoverSlot.day) : null
       const hoverTtftPoint = hoverSlot ? ttftPoints.find((point) => point.day === hoverSlot.day) : null
-      const pick = (index) => (event) => setHover({ index, anchor: event.currentTarget })
+      const pick = (index) => (event) => setHover({ index, anchor: pointerAt(event) })
       const clear = () => setHover(null)
       const otherEntries = hoverSlot
         ? Object.entries(hoverSlot.otherByModel ?? {}).sort((a, b) => b[1] - a[1])
@@ -2209,7 +2280,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
           ? panel.getBoundingClientRect()
           : { left: 0, top: 0, right: window.innerWidth, bottom: window.innerHeight }
         const next = tipPlace(
-          anchor ? anchor.getBoundingClientRect() : null,
+          anchor,
           { width: tip.offsetWidth, height: tip.offsetHeight },
           bounds,
         )
@@ -2261,7 +2332,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
       const display = geom ? heatDisplayDays(days, geom.cols) : null
       const grid = display ? heatGrid(display, geom.size) : null
       const peak = display ? Math.max(1, ...display.map((slot) => slot.tokens)) : 1
-      const pick = (cell) => (event) => setHover({ ...cell, anchor: event.currentTarget })
+      const pick = (cell) => (event) => setHover({ ...cell, anchor: pointerAt(event) })
       const clear = () => setHover(null)
       return h('div', { className: 'ud-section' },
         h('div', { className: 'ud-section-head' },
@@ -2310,7 +2381,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
       const displayName = (model) => (model === OTHER_MODEL ? t('other') : model)
       const pick = (model) => (event) => {
         setHover(model)
-        setTip({ model, anchor: event.currentTarget })
+        setTip({ model, anchor: pointerAt(event) })
       }
       const clear = () => {
         setHover(null)
@@ -2952,6 +3023,9 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
       const [error, setError] = useState('')
       const [hourPreset, setHourPreset] = useState(DEFAULT_HOUR_PRESET)
       const [minutePreset, setMinutePreset] = useState(DEFAULT_MINUTE_PRESET)
+      // 自定义挡 datetime 输入,时/分视图共享一对,各视图按桶粒度分别归一
+      const [pointCustomFrom, setPointCustomFrom] = useState('')
+      const [pointCustomTo, setPointCustomTo] = useState('')
       const [pointStats, setPointStats] = useState(null)
       const [pointStatus, setPointStatus] = useState('idle')
       const [fetchTick, setFetchTick] = useState(0)
@@ -3018,17 +3092,16 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
         load()
       }, [load])
 
-      const presetId = view === 'hour' ? hourPreset : view === 'minute' ? minutePreset : null
+      const rawPreset = view === 'hour' ? hourPreset : view === 'minute' ? minutePreset : null
+      // 自定义挡输入不完整时 query 为 null:不发请求,已取数据留存缓存,输入恢复即按键命中
+      const activeQuery = view === 'day' ? null : resolvePointQuery(view, rawPreset, pointCustomFrom, pointCustomTo)
 
       useEffect(() => {
-        if (view === 'day') return
-        if (pointStatsMatches(pointStats, view, presetId)) return
-        const request = view === 'hour'
-          ? resolveHourRange(presetId, new Date())
-          : resolveMinuteRange(presetId, new Date())
+        if (!activeQuery) return
+        if (pointStatsMatches(pointStats, view, activeQuery.key)) return
         const generation = ++pointGenerationRef.current
         setPointStatus('loading')
-        requestPost(view === 'hour' ? ENDPOINTS.hours : ENDPOINTS.minutes, request).then((result) => {
+        requestPost(view === 'hour' ? ENDPOINTS.hours : ENDPOINTS.minutes, activeQuery.request).then((result) => {
           if (pointGenerationRef.current !== generation) return
           if (!result.ok) {
             setPointStatus('error')
@@ -3037,9 +3110,9 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
           }
           setError('')
           setPointStatus('ok')
-          setPointStats({ view, preset: presetId, value: result.value })
+          setPointStats({ view, preset: activeQuery.key, value: result.value })
         })
-      }, [view, presetId, fetchTick])
+      }, [view, rawPreset, pointCustomFrom, pointCustomTo, fetchTick])
 
       const refreshPoints = useCallback(() => {
         setPointStats(null)
@@ -3060,6 +3133,16 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
         if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current)
       }, [])
 
+      // 切换时/分挡位;切到自定义挡且无历史输入时预填最近窗口,即点即用
+      const selectPointPreset = (id) => {
+        if (id === CUSTOM_RANGE_ID && !pointCustomFrom && !pointCustomTo) {
+          setPointCustomFrom(formatDateTimeInput(new Date(Date.now() - POINT_CUSTOM_DEFAULT_HOURS * MS_PER_HOUR)))
+          setPointCustomTo(formatDateTimeInput(new Date()))
+        }
+        if (view === 'hour') setHourPreset(id)
+        else setMinutePreset(id)
+      }
+
       const refresh = () => {
         setError('')
         if (view === 'day') load()
@@ -3105,7 +3188,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
       }, [])
 
       const grouped = useMemo(() => (stats ? groupStats(stats) : null), [stats])
-      const pointView = pointStatsMatches(pointStats, view, presetId) ? pointStats.value : null
+      const pointView = activeQuery && pointStatsMatches(pointStats, view, activeQuery.key) ? pointStats.value : null
       const pointGrouped = useMemo(() => (pointView ? groupPointSlots(pointView.daily) : null), [pointView])
       const colorFor = useMemo(() => colorForModel(stats ? stats.models : []), [stats])
 
@@ -3113,7 +3196,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
       const trendSource = pointActive
         ? (pointGrouped ? { slots: pointGrouped.daily, models: pointGrouped.models, value: pointView } : null)
         : (grouped ? { slots: grouped.daily, models: grouped.models, value: stats } : null)
-      const maxSlots = pointActive ? maxSlotsFor(view, presetId) : DAY_MAX_SLOTS
+      const maxSlots = pointActive ? maxSlotsFor(view, rawPreset) : DAY_MAX_SLOTS
       const trimmedSlots = trendSource ? trimSlots(trendSource.slots, maxSlots) : null
       const notes = []
       if (trendSource && trendSource.slots.length > trimmedSlots.length) notes.push(trendLimitedText(t, view, trimmedSlots.length))
@@ -3134,13 +3217,33 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
                 onClick: () => setView(tab.id),
               }, viewLabel(t, tab.id)))),
             pointActive
-              ? h('div', { className: 'ud-group', role: 'group', 'aria-label': t('range') },
-                  (view === 'hour' ? HOUR_PRESETS : MINUTE_PRESETS).map((id) => h('button', {
-                    key: id,
-                    className: cx('ud-seg-item', presetId === id && 'ud-seg-item--on'),
-                    'aria-pressed': presetId === id,
-                    onClick: () => (view === 'hour' ? setHourPreset(id) : setMinutePreset(id)),
-                  }, presetLabel(t, view, id))))
+              ? h(React.Fragment, null,
+                  h('div', { className: 'ud-group', role: 'group', 'aria-label': t('range') },
+                    (view === 'hour' ? HOUR_PRESETS : MINUTE_PRESETS).map((id) => h('button', {
+                      key: id,
+                      className: cx('ud-seg-item', rawPreset === id && 'ud-seg-item--on'),
+                      'aria-pressed': rawPreset === id,
+                      onClick: () => selectPointPreset(id),
+                    }, presetLabel(t, view, id))),
+                    h('button', {
+                      className: cx('ud-seg-item', rawPreset === CUSTOM_RANGE_ID && 'ud-seg-item--on'),
+                      'aria-pressed': rawPreset === CUSTOM_RANGE_ID,
+                      onClick: () => selectPointPreset(CUSTOM_RANGE_ID),
+                    }, t('rangeCustom'))),
+                  rawPreset === CUSTOM_RANGE_ID
+                    ? h('div', { className: 'ud-custom-range' },
+                        h('input', {
+                          type: 'datetime-local', className: 'ud-date-input', 'aria-label': t('from'),
+                          value: pointCustomFrom, max: pointCustomTo || undefined,
+                          onChange: (event) => setPointCustomFrom(event.target.value),
+                        }),
+                        h('span', { className: 'ud-custom-sep' }, '–'),
+                        h('input', {
+                          type: 'datetime-local', className: 'ud-date-input', 'aria-label': t('to'),
+                          value: pointCustomTo, min: pointCustomFrom || undefined, max: formatDateTimeInput(new Date()),
+                          onChange: (event) => setPointCustomTo(event.target.value),
+                        }))
+                    : null)
               : h(React.Fragment, null,
                   h('div', { className: 'ud-group', role: 'group', 'aria-label': t('range') },
                     DAY_PRESETS.map((id) => h('button', {

package/test/client.test.mjs

@@ -75,6 +75,7 @@ const {
   otherDetailItems,
   parseEnvelope,
   partitionGroupOf,
+  pointerAt,
   providerOf,
   rateAxisTicks,
   removeRulesAt,
@@ -82,6 +83,11 @@ const {
   resolveDayRange,
   resolveHourRange,
   resolveMinuteRange,
+  resolveHourCustomRange,
+  resolveMinuteCustomRange,
+  resolvePointQuery,
+  formatDateTimeInput,
+  parseLocalDateTime,
   shortDay,
   smoothPath,
   tipPlace,
@@ -177,6 +183,112 @@ test('pointStats 缓存命中须视图与挡位双匹配', () => {
   assert.equal(pointStatsMatches(null, 'hour', '24h'), false)
 })
 
+// —— 时/分自定义时间范围:归一语义与预设挡一致(小时 floor 整点桶,分钟 from 对齐 10 分钟桶、to 保原分钟) ——
+
+const CUSTOM_FROM = '2026-03-14T09:45'
+const CUSTOM_TO = '2026-03-15T14:10'
+
+test('hour 自定义范围两端 floor 到所在小时桶', () => {
+  // Given datetime 输入含分钟偏移 When 解析 Then 两端均取所在小时桶起点(闭区间)
+  assert.deepEqual(resolveHourCustomRange(CUSTOM_FROM, CUSTOM_TO), { from: '2026-03-14T09', to: '2026-03-15T14' })
+  assert.deepEqual(resolveHourCustomRange('2026-03-14T09:00', '2026-03-15T14:59'), { from: '2026-03-14T09', to: '2026-03-15T14' })
+})
+
+test('hour 自定义跨度超保留期钳起点,临界窗经 floor 与原窗输出等价', () => {
+  // Given 跨度 16 天 When 解析 Then 起点钳到终点前 15 天整点;15 天余零头的窗钳后 floor 输出不变
+  assert.deepEqual(
+    resolveHourCustomRange('2026-02-27T00:00', '2026-03-15T14:10'),
+    { from: '2026-02-28T14', to: '2026-03-15T14' },
+  )
+  assert.deepEqual(
+    resolveHourCustomRange('2026-02-28T14:00', '2026-03-15T14:10'),
+    { from: '2026-02-28T14', to: '2026-03-15T14' },
+  )
+})
+
+test('hour 自定义非法输入返回 null', () => {
+  // Given 空值/垃圾串/from 晚于 to When 解析 Then 恒 null,不发请求
+  assert.equal(resolveHourCustomRange('', CUSTOM_TO), null)
+  assert.equal(resolveHourCustomRange(CUSTOM_FROM, ''), null)
+  assert.equal(resolveHourCustomRange('junk', CUSTOM_TO), null)
+  assert.equal(resolveHourCustomRange('2026-13-40T09:00', CUSTOM_TO), null)
+  assert.equal(resolveHourCustomRange(CUSTOM_TO, CUSTOM_FROM), null)
+})
+
+test('parseLocalDateTime 拒绝数字分量回卷的日历非法值', () => {
+  // Given 超界分量(13 月/2 月 30 日/25 时)在 Date 构造下静默回卷 When 解析 Then 逐分量回读拦截为 null
+  assert.equal(parseLocalDateTime('2026-13-01T00:00'), null)
+  assert.equal(parseLocalDateTime('2026-02-30T10:00'), null)
+  assert.equal(parseLocalDateTime('2026-03-14T25:00'), null)
+  assert.deepEqual(parseLocalDateTime('2026-03-14T09:45'), new Date(2026, 2, 14, 9, 45))
+})
+
+test('hour 自定义拒绝回卷后仍保序的非法日历输入', () => {
+  // Given 13 月回卷为次年 1 月且整体仍早于 to When 解析 Then 恒 null,不静默改写查询时段
+  assert.equal(resolveHourCustomRange('2026-13-01T00:00', '2027-06-01T00:00'), null)
+})
+
+test('minute 自定义 from 对齐 10 分钟桶,to 保持原始分钟', () => {
+  // Given from 含非对齐分钟 When 解析 Then from floor 到桶边界,to 原值保留(闭区间上界)
+  assert.deepEqual(resolveMinuteCustomRange(CUSTOM_FROM, CUSTOM_TO), { from: '2026-03-14T09:40', to: '2026-03-15T14:10' })
+  assert.deepEqual(resolveMinuteCustomRange('2026-03-14T09:40', '2026-03-15T14:17'), { from: '2026-03-14T09:40', to: '2026-03-15T14:17' })
+})
+
+test('minute 自定义跨度超保留期钳起点', () => {
+  // Given 跨度 8 天 When 解析 Then 起点钳到终点前 7 天的 10 分钟桶边界
+  assert.deepEqual(
+    resolveMinuteCustomRange('2026-03-06T00:00', '2026-03-15T14:10'),
+    { from: '2026-03-08T14:10', to: '2026-03-15T14:10' },
+  )
+})
+
+test('minute 自定义非法输入返回 null', () => {
+  assert.equal(resolveMinuteCustomRange('', CUSTOM_TO), null)
+  assert.equal(resolveMinuteCustomRange('junk', CUSTOM_TO), null)
+  assert.equal(resolveMinuteCustomRange(CUSTOM_TO, CUSTOM_FROM), null)
+})
+
+test('resolvePointQuery 预设挡返回挡位键与滚动窗口请求', () => {
+  // Given 时/分预设挡 When 解析查询 Then 键为挡位 id,请求与既有 resolve 同构
+  const hour = resolvePointQuery('hour', '24h', '', '', NOW)
+  assert.equal(hour.key, '24h')
+  assert.deepEqual(hour.request, resolveHourRange('24h', NOW))
+  const minute = resolvePointQuery('minute', '3h', '', '', NOW)
+  assert.equal(minute.key, '3h')
+  assert.deepEqual(minute.request, resolveMinuteRange('3h', NOW))
+})
+
+test('resolvePointQuery 自定义挡键含归一范围且随范围变化', () => {
+  // Given 同视图同挡不同范围 When 解析查询 Then 键互异;同范围键稳定(缓存可命中)
+  const first = resolvePointQuery('hour', 'custom', CUSTOM_FROM, CUSTOM_TO, NOW)
+  assert.deepEqual(first.request, { from: '2026-03-14T09', to: '2026-03-15T14' })
+  assert.equal(first.key, 'custom:2026-03-14T09:2026-03-15T14')
+  const again = resolvePointQuery('hour', 'custom', CUSTOM_FROM, CUSTOM_TO, NOW)
+  assert.equal(again.key, first.key)
+  const shifted = resolvePointQuery('hour', 'custom', '2026-03-14T10:45', CUSTOM_TO, NOW)
+  assert.notEqual(shifted.key, first.key)
+  const minute = resolvePointQuery('minute', 'custom', CUSTOM_FROM, CUSTOM_TO, NOW)
+  assert.deepEqual(minute.request, { from: '2026-03-14T09:40', to: '2026-03-15T14:10' })
+  assert.notEqual(minute.key, first.key)
+})
+
+test('resolvePointQuery 自定义输入不完整返回 null', () => {
+  // Given 任一端为空 When 解析查询 Then null,面板不发请求不误清缓存
+  assert.equal(resolvePointQuery('hour', 'custom', '', CUSTOM_TO, NOW), null)
+  assert.equal(resolvePointQuery('minute', 'custom', CUSTOM_FROM, '', NOW), null)
+})
+
+test('maxSlotsFor custom 挡取保留期桶数上限', () => {
+  // Given 自定义挡受保留期钳制 When 取渲染上限 Then 小时为 15 天小时桶数,分钟为 7 天 10 分钟桶数
+  assert.equal(maxSlotsFor('hour', 'custom'), 15 * 24 + 1)
+  assert.equal(maxSlotsFor('minute', 'custom'), (7 * 24 * 60) / 10 + 1)
+})
+
+test('formatDateTimeInput 产出 datetime-local 分钟粒度值', () => {
+  assert.equal(formatDateTimeInput(new Date(2026, 2, 15, 9, 5)), '2026-03-15T09:05')
+  assert.equal(formatDateTimeInput(NOW), '2026-03-15T14:30')
+})
+
 test('每视图渲染上限等于闭区间桶数', () => {
   assert.equal(maxSlotsFor('day', '90'), DAY_MAX_SLOTS)
   assert.equal(maxSlotsFor('hour', '24h'), 25)
@@ -476,50 +588,57 @@ test('heatLevel 零值为空档其余按峰值四分位', () => {
   assert.equal(heatLevel(1, 1), 5)
 })
 
-const TIP_ANCHOR = { left: 100, top: 100, right: 140, bottom: 114 }
+const TIP_ANCHOR = { x: 100, y: 100 }
 const TIP_SIZE = { width: 80, height: 40 }
 const TIP_BOUNDS = { left: 0, top: 0, right: 800, bottom: 600 }
 
-test('tipPlace 小锚点默认翻上方水平居中', () => {
-  assert.deepEqual(tipPlace(TIP_ANCHOR, TIP_SIZE, TIP_BOUNDS), { left: 80, top: 52 })
+test('tipPlace 指针右下空位放右下', () => {
+  assert.deepEqual(tipPlace(TIP_ANCHOR, TIP_SIZE, TIP_BOUNDS), { left: 108, top: 108 })
+})
+
+test('tipPlace 右侧越界翻左侧', () => {
+  assert.deepEqual(tipPlace({ x: 730, y: 100 }, TIP_SIZE, TIP_BOUNDS), { left: 642, top: 108 })
 })
 
-test('tipPlace 锚定区装得下提示框贴内顶', () => {
-  const anchor = { left: 100, top: 100, right: 240, bottom: 460 }
-  assert.deepEqual(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS), { left: 130, top: 108 })
+test('tipPlace 下方越界翻上方', () => {
+  assert.deepEqual(tipPlace({ x: 100, y: 570 }, TIP_SIZE, TIP_BOUNDS), { left: 108, top: 522 })
 })
 
-test('tipPlace 上方不足翻下方', () => {
-  const anchor = { left: 100, top: 20, right: 140, bottom: 60 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS).top, 68)
+test('tipPlace 右下均越界双翻', () => {
+  assert.deepEqual(tipPlace({ x: 730, y: 570 }, TIP_SIZE, TIP_BOUNDS), { left: 642, top: 522 })
 })
 
-test('tipPlace 候选边界等号归属', () => {
-  assert.deepEqual(tipPlace({ left: 100, top: 100, right: 240, bottom: 148 }, TIP_SIZE, TIP_BOUNDS), { left: 130, top: 108 })
-  assert.equal(tipPlace({ left: 100, top: 56, right: 140, bottom: 96 }, TIP_SIZE, TIP_BOUNDS).top, 8)
-  assert.equal(tipPlace({ left: 100, top: 8, right: 140, bottom: 48 }, TIP_SIZE, { left: 0, top: 0, right: 800, bottom: 104 }).top, 56)
+test('tipPlace 双翻后仍越界钳进边界', () => {
+  assert.deepEqual(tipPlace({ x: 798, y: 598 }, TIP_SIZE, TIP_BOUNDS), { left: 710, top: 550 })
 })
 
-test('tipPlace 下方放不下翻转上方', () => {
-  const anchor = { ...TIP_ANCHOR, top: 540, bottom: 580 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS).top, 492)
+test('tipPlace 恰贴右缘等号归属放右侧', () => {
+  assert.deepEqual(tipPlace({ x: 704, y: 100 }, TIP_SIZE, TIP_BOUNDS), { left: 712, top: 108 })
 })
 
-test('tipPlace 两侧均放不下钳到边界顶', () => {
-  const bounds = { left: 0, top: 0, right: 800, bottom: 50 }
-  const anchor = { left: 100, top: 20, right: 140, bottom: 50 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, bounds).top, 8)
+test('tipPlace 左上角指针放右下不翻转', () => {
+  assert.deepEqual(tipPlace({ x: 2, y: 2 }, TIP_SIZE, TIP_BOUNDS), { left: 10, top: 10 })
 })
 
-test('tipPlace 水平越界钳到边界左缘', () => {
-  const anchor = { left: 2, top: 100, right: 10, bottom: 114 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS).left, 8)
+test('tipPlace 提示框宽于边界钳贴左缘', () => {
+  assert.equal(tipPlace({ x: 400, y: 100 }, { width: 900, height: 40 }, TIP_BOUNDS).left, 8)
+})
+
+test('pointerAt 指针事件取指针坐标', () => {
+  assert.deepEqual(pointerAt({ clientX: 12, clientY: 34 }), { x: 12, y: 34 })
+})
+
+test('pointerAt 焦点事件回退目标矩形中心', () => {
+  const event = {
+    currentTarget: { getBoundingClientRect: () => ({ left: 10, top: 20, right: 30, bottom: 60 }) },
+  }
+  assert.deepEqual(pointerAt(event), { x: 20, y: 40 })
 })
 
-test('tipPlace 零尺寸或全零锚定矩形返回隐藏', () => {
+test('tipPlace 零尺寸或非法锚点返回隐藏', () => {
   assert.equal(tipPlace(TIP_ANCHOR, { width: 0, height: 0 }, TIP_BOUNDS), null)
-  assert.equal(tipPlace({ left: 0, top: 0, right: 0, bottom: 0 }, TIP_SIZE, TIP_BOUNDS), null)
   assert.equal(tipPlace(null, TIP_SIZE, TIP_BOUNDS), null)
+  assert.equal(tipPlace({ x: Number.NaN, y: 100 }, TIP_SIZE, TIP_BOUNDS), null)
 })
 
 // —— S8 命中率曲线 ——