claude-code-hub/docs/dashboard-logs-callchain.md

Dashboard Logs（Usage Logs）入口与调用链盘点

本文用于锁定 /dashboard/logs 的真实入口与关键调用链边界，避免后续需求实现与验收口径跑偏。

1) 路由入口（Server）

• 路由：/dashboard/logs
• 入口页面：src/app/[locale]/dashboard/logs/page.tsx
  • 登录态校验：getSession()（未登录重定向到 /login）
  • 数据区块入口：UsageLogsDataSection（src/app/[locale]/dashboard/logs/_components/usage-logs-sections.tsx）

2) 真实渲染链路（Client）

当前页面实际使用“虚拟列表”链路：

• 虚拟列表入口：UsageLogsViewVirtualized（src/app/[locale]/dashboard/logs/_components/usage-logs-view-virtualized.tsx）
  • URL -> filters 解析：parseLogsUrlFilters()（src/app/[locale]/dashboard/logs/_utils/logs-query.ts）
  • filters -> URL 回填：buildLogsUrlQuery()（src/app/[locale]/dashboard/logs/_utils/logs-query.ts）
  • Filters 面板：UsageLogsFilters
  • 列表：VirtualizedLogsTable
  • 统计面板：UsageLogsStatsPanel

仓库内仍存在“非虚拟表格”实现（目前不被路由引用，属于历史/备用路径）：

• UsageLogsView（src/app/[locale]/dashboard/logs/_components/usage-logs-view.tsx）
• UsageLogsTable（src/app/[locale]/dashboard/logs/_components/usage-logs-table.tsx）

3) 过滤器 / URL / 时间语义

• URL 参数解析/构建（统一入口）：src/app/[locale]/dashboard/logs/_utils/logs-query.ts
  • sessionId：字符串（trim 后空值不落盘）
  • startTime/endTime：毫秒时间戳
• 秒级时间工具：src/app/[locale]/dashboard/logs/_utils/time-range.ts
  • UI endTime 为“包含式”秒；对后端转换为“排他上界”（endExclusive = endInclusive + 1s）
  • 后端查询语义保持：created_at >= startTime 且 created_at < endTime

4) 数据获取链路（Actions -> Repository）

列表（无限滚动）

• Action：src/actions/usage-logs.ts#getUsageLogsBatch
• Repo：src/repository/usage-logs.ts#findUsageLogsBatch

统计（折叠面板按需加载）

• Action：src/actions/usage-logs.ts#getUsageLogsStats
• Repo：src/repository/usage-logs.ts#findUsageLogsStats

导出 CSV

• Action：src/actions/usage-logs.ts#exportUsageLogs
• Repo：src/repository/usage-logs.ts#findUsageLogsWithDetails
• CSV 生成：src/actions/usage-logs.ts#generateCsv

Session ID 联想（候选查询）

• Action：src/actions/usage-logs.ts#getUsageLogSessionIdSuggestions
• Repo：src/repository/usage-logs.ts#findUsageLogSessionIdSuggestions

匹配语义与边界（2026-01-15 更新）

• 前端约束：
  • 最小长度：SESSION_ID_SUGGESTION_MIN_LEN（src/lib/constants/usage-logs.constants.ts）
  • 最大长度截断：SESSION_ID_SUGGESTION_MAX_LEN（src/actions/usage-logs.ts 内对输入 trim 后截断）
  • 每次返回数量：SESSION_ID_SUGGESTION_LIMIT
• 后端匹配：
  • 语义：仅支持「字面量前缀匹配」（term%），不再支持包含匹配（%term%）
  • 安全：输入中的 % / _ / \\ 会被统一转义，避免被当作 LIKE 通配符
  • SQL（核心条件）：session_id LIKE '<escapedTerm>%' ESCAPE '\\'
  • 转义实现：src/repository/_shared/like.ts#escapeLike
• 行为变更示例：
  • 之前：输入 abc 可能命中 xxxabcxxx（包含匹配）
  • 之后：仅命中 abc...（前缀匹配）
  • 之前：输入 % / _ 可主动触发通配
  • 之后：% / _ 按字面量处理（例如输入 %a 只匹配以 %a 开头的 session_id）

索引与迁移（前缀匹配性能）

• 已有索引：idx_message_request_session_id（message_request.session_id，partial: deleted_at IS NULL）
• 新增索引（前缀匹配）：idx_message_request_session_id_prefix
  • opclass：varchar_pattern_ops
  • partial：deleted_at IS NULL AND (blocked_by IS NULL OR blocked_by <> 'warmup')
  • 迁移文件：drizzle/0055_neat_stepford_cuckoos.sql

5) 本需求相关影响面（文件/符号清单）

前端（logs 页面内聚）：

• URL/过滤器：src/app/[locale]/dashboard/logs/_utils/logs-query.ts
• 秒级时间：src/app/[locale]/dashboard/logs/_utils/time-range.ts
• 过滤器 UI：src/app/[locale]/dashboard/logs/_components/usage-logs-filters.tsx
• 虚拟列表：src/app/[locale]/dashboard/logs/_components/virtualized-logs-table.tsx
• 非虚拟表格：src/app/[locale]/dashboard/logs/_components/usage-logs-table.tsx
• 统计面板：src/app/[locale]/dashboard/logs/_components/usage-logs-stats-panel.tsx

后端（Actions/Repo）：

• Actions：src/actions/usage-logs.ts
  • getUsageLogsBatch/getUsageLogsStats/exportUsageLogs/getUsageLogSessionIdSuggestions
• Repo：src/repository/usage-logs.ts
  • findUsageLogsBatch/findUsageLogsWithDetails/findUsageLogsStats/findUsageLogSessionIdSuggestions

i18n（用户可见文案）：

• messages/*/dashboard.json（dashboard.logs.filters.* / dashboard.logs.columns.*）

6) 边界说明（在范围内 / 不在范围内）

在范围内（本次需求直接相关）：

• sessionId 精确筛选 + URL 回填 + UI 展示（列/复制/tooltip）
• 秒级时间输入与 endExclusive 语义对齐（< endTime）
• Session ID 联想（最小成本：minLen + debounce + limit）

不在范围内（需另开 issue/评审确认后再做）：

• 针对联想查询的索引/物化/离线表（优化类工程）
• 大规模改动数据库 schema 或重建索引策略（例如 CONCURRENTLY/离线重建）
• Logs 页面其它过滤项语义调整（非本需求验收口径）