@hedeqiang/dsh-nl2sql 0.0.0-stage → 0.10.0

package/service/alerts.js

@@ -0,0 +1,233 @@
+/**
+ * Nl2SqlService methods: alerts.
+ * Mixed into the service prototype by index.js; `this` is the service.
+ */
+import { evaluateAlert } from '../analysis.js'
+import { admitSql } from '../sql-guard.js'
+import { UserError, clampInt, newId, oneOf, requireText, upsert } from './shared.js'
+
+export const methods = {
+  // ---------------------------------------------------------------- alerts
+
+  /**
+   * Alert: a metric (from the library) or a SQL query returning a time series
+   * (first column time, value column), evaluated on a schedule; triggers push
+   * to a channel.
+   */
+  listAlerts() {
+    return (this.state.alerts ?? []).map(a => ({ ...a, datasourceName: this.findDatasource(a.datasourceId)?.name ?? a.datasourceId, channelName: this.state.channels.find(c => c.id === a.channelId)?.name ?? null }))
+  },
+
+  /** Validate an alert definition (shared by save and preview). */
+  async normalizeAlert(input, forceId) {
+    const existing = input.id ? (this.state.alerts ?? []).find(a => a.id === input.id) : undefined
+    if (input.id && !existing) throw new UserError('nl2sql/invalid', '告警不存在')
+    const ds = this.requireDatasource(input.datasourceId ?? existing?.datasourceId)
+    const a = existing ? { ...existing } : { id: forceId ?? newId('al'), createdAt: Date.now(), state: 'ok' }
+    a.name = requireText(input.name ?? a.name, 'name', 60)
+    a.datasourceId = ds.id
+    a.source = oneOf(input.source ?? a.source ?? 'metric', ['metric', 'sql'], 'source')
+    if (a.source === 'metric') {
+      const m = this.findMetric(ds, input.metric ?? a.metric)
+      if (!m) throw new UserError('nl2sql/unknown-metric', '指标库中没有这个指标')
+      a.metric = m.name
+      a.grain = oneOf(input.grain ?? a.grain ?? 'day', ['hour', 'day', 'week', 'month'], 'grain')
+      a.filters = Array.isArray(input.filters) ? input.filters : (a.filters ?? [])
+      delete a.sql
+    } else {
+      a.sql = requireText(input.sql ?? a.sql, 'sql', 20000)
+      admitSql(a.sql, { dialect: ds.type ?? 'mysql' })
+      delete a.metric
+    }
+    const cond = input.condition ?? a.condition ?? { type: 'threshold', op: '>', value: 0 }
+    a.condition = { ...cond, type: oneOf(cond.type, ['threshold', 'change', 'anomaly', 'missing'], 'condition.type') }
+    a.every = oneOf(input.every ?? a.every ?? 'hour', ['15m', 'hour', 'day'], 'every')
+    a.at = /^\d{2}:\d{2}$/.test(String(input.at ?? a.at ?? '')) ? (input.at ?? a.at) : '09:00'
+    a.channelId = input.channelId !== undefined ? (this.state.channels.some(c => c.id === input.channelId) ? input.channelId : null) : (a.channelId ?? null)
+    a.mention = input.mention !== undefined ? Boolean(input.mention) : Boolean(a.mention)
+    a.cooldownMin = clampInt(input.cooldownMin ?? a.cooldownMin ?? 60, 0, 10080, 'cooldownMin')
+    a.enabled = input.enabled !== undefined ? Boolean(input.enabled) : (a.enabled ?? true)
+    a.updatedAt = Date.now()
+    return a
+  },
+
+  async saveAlert(input) {
+    const a = await this.normalizeAlert(input)
+    this.state.alerts = upsert(this.state.alerts ?? [], a)
+    await this.save()
+    this.scheduleAlerts()
+    return a
+  },
+
+  async deleteAlert(id) {
+    this.state.alerts = (this.state.alerts ?? []).filter(a => a.id !== id)
+    await this.save()
+    return { deleted: id }
+  },
+
+  /** Evaluate one alert now; pushes when it triggers (respecting cooldown) unless dryRun. */
+  async checkAlert(id, opts = {}) {
+    if (opts.dryRun) return this.checkAlertInner(id, opts)
+    return this.withJobLock(`alert:${id}`, () => this.checkAlertInner(id, opts))
+  },
+
+  /** Evaluate an unsaved alert definition (form "dry run"): nothing is stored or pushed. */
+  async previewAlert(input) {
+    const tmpId = `preview-${newId('al')}`
+    const saved = this.state.alerts
+    try {
+      const draft = await this.normalizeAlert({ ...input, id: undefined }, tmpId)
+      this.state.alerts = [...(saved ?? []), draft]
+      return await this.checkAlertInner(tmpId, { dryRun: true })
+    } finally {
+      this.state.alerts = saved
+    }
+  },
+
+  async checkAlertInner(id, { dryRun = false, force = false } = {}) {
+    const a = (this.state.alerts ?? []).find(x => x.id === id)
+    if (!a) throw new UserError('nl2sql/invalid', '告警不存在')
+    const ds = this.requireDatasource(a.datasourceId)
+    let result
+    if (a.source === 'metric') {
+      const range = a.grain === 'hour' ? 'last7d' : a.grain === 'month' ? 'thisYear' : a.grain === 'week' ? 'last90d' : 'last30d'
+      result = await this.queryMetric({ datasourceId: ds.id, metric: a.metric, grain: a.grain, range, filters: a.filters, title: `告警 · ${a.name}`, source: 'alert' })
+    } else {
+      result = await this.runQuery({ sql: a.sql, datasourceId: ds.id, title: `告警 · ${a.name}`, source: 'alert', confirmScan: true })
+    }
+    // Series: first column = time/category, last numeric column = value.
+    const vi = [...result.columns.keys()].reverse().find(i => result.columns[i].kind === 'number')
+    const series = vi === undefined ? [] : result.rows.map(r => ({ t: r[0], v: r[vi] === null ? null : Number(r[vi]) }))
+    if (a.condition.type !== 'missing' && result.columns.length === 1 && vi === 0) series.splice(0, series.length, ...result.rows.map((r, i) => ({ t: i, v: Number(r[0]) })))
+    const ev = evaluateAlert(a.condition, series, { now: Date.now() })
+    a.lastCheckedAt = Date.now()
+    a.lastValue = ev.value ?? null
+    a.lastResultId = result.resultId
+    const cooled = !a.lastFiredAt || Date.now() - a.lastFiredAt >= a.cooldownMin * 60000
+    let pushed = false
+    if (ev.triggered) {
+      a.state = 'firing'
+      if (!dryRun && (cooled || force)) {
+        a.lastFiredAt = Date.now()
+        const event = { id: newId('ae'), alertId: a.id, name: a.name, at: Date.now(), value: ev.value ?? null, message: ev.message, resultId: result.resultId }
+        this.records.put('alertEvent', event)
+        if (a.channelId) {
+          try {
+            await this.sendToChannel({ channelId: a.channelId, title: `⚠️ 数据告警：${a.name}`, text: `${a.mention ? '<at id=all></at> ' : ''}**${ev.message}**\n\n<font color='grey'>数据源：${ds.name} · 检查时间：${new Date().toLocaleString('zh-CN', { hour12: false })}</font>`, resultIds: [result.resultId], source: 'alert' })
+            pushed = true
+            event.pushed = true
+          } catch (error) {
+            event.pushError = error.message
+          }
+          this.records.put('alertEvent', event)
+        }
+      }
+    } else if (a.state === 'firing') {
+      a.state = 'ok'
+      if (!dryRun && a.channelId && a.notifyRecovery !== false) {
+        try { await this.sendToChannel({ channelId: a.channelId, title: `✅ 告警恢复：${a.name}`, text: ev.message, source: 'alert' }) } catch {}
+      }
+    } else {
+      a.state = 'ok'
+    }
+    await this.save()
+    return { ...ev, pushed, resultId: result.resultId, state: a.state }
+  },
+
+  listAlertEvents(alertId) {
+    return this.records.list('alertEvent', { ref: alertId, limit: 200 })
+  },
+
+  /**
+   * In-process scheduler (alerts + daily schema check). The Harness schedule
+   * service only delivers prompts to agent sessions, so deterministic checks run
+   * here. Reliability:
+   *   - a first tick 20 s after start catches up on anything missed while
+   *     Harness was closed (each job keeps its own last-run time, so a missed
+   *     daily slot runs once, not once per missed day);
+   *   - per-job in-flight locks (manual "check now" and the tick never overlap);
+   *   - jobs run concurrently with a timeout, so one slow query does not block others;
+   *   - every tick is recorded and shown on the page.
+   */
+  scheduleAlerts() {
+    if (this.alertTimer || this.disposed) return
+    const tick = () => { this.tickAlerts().catch(error => { this.state.scheduler = { ...(this.state.scheduler ?? {}), lastError: error.message } }) }
+    this.alertTimer = setInterval(tick, 60000)
+    this.alertTimer.unref?.()
+    this.alertKick = setTimeout(tick, this.config.schedulerDelayMs ?? 20000)
+    this.alertKick.unref?.()
+  },
+
+  /** Next due time (ms) of an alert after its last check. */
+  alertDueAt(a, now = Date.now()) {
+    const last = a.lastCheckedAt ?? 0
+    if (a.every === '15m') return last + 15 * 60000
+    if (a.every === 'hour') return last + 60 * 60000
+    // daily at HH:MM local time: the most recent slot not yet covered by lastCheckedAt.
+    const [hh, mm] = String(a.at ?? '09:00').split(':').map(Number)
+    const slot = new Date(now)
+    slot.setHours(hh, mm, 0, 0)
+    if (slot.getTime() > now) slot.setDate(slot.getDate() - 1)
+    return last < slot.getTime() ? slot.getTime() : (() => { const n = new Date(slot); n.setDate(n.getDate() + 1); return n.getTime() })()
+  },
+
+  async withJobLock(key, fn) {
+    this.jobLocks ??= new Set()
+    if (this.jobLocks.has(key)) throw new UserError('nl2sql/busy', '该任务正在执行，请稍后再试')
+    this.jobLocks.add(key)
+    try { return await fn() } finally { this.jobLocks.delete(key) }
+  },
+
+  async tickAlerts(now = new Date()) {
+    if (this.alertBusy || this.disposed) return
+    this.alertBusy = true
+    const started = Date.now()
+    const ran = []
+    try {
+      const due = (this.state.alerts ?? []).filter(a => a.enabled && this.alertDueAt(a, now.getTime()) <= now.getTime())
+      const timeoutMs = this.config.alertTimeoutMs ?? 120000
+      await Promise.all(due.map(async (a) => {
+        try {
+          await Promise.race([
+            this.checkAlert(a.id),
+            new Promise((_, rej) => { const t = setTimeout(() => rej(new Error(`检查超过 ${Math.round(timeoutMs / 1000)} 秒`)), timeoutMs); t.unref?.() }),
+          ])
+          a.lastError = undefined
+          ran.push({ id: a.id, ok: true })
+        } catch (error) {
+          if (error.code === 'nl2sql/busy') return
+          a.lastError = error.message
+          a.lastCheckedAt = Date.now()
+          ran.push({ id: a.id, ok: false, error: error.message })
+        }
+      }))
+      // Daily schema watch (catches up once after downtime).
+      const at = this.state.settings.schemaCheckDaily
+      if (at) {
+        const [hh, mm] = at.split(':').map(Number)
+        const slot = new Date(now)
+        slot.setHours(hh, mm, 0, 0)
+        if (slot > now) slot.setDate(slot.getDate() - 1)
+        if ((this.state.lastSchemaCheck ?? 0) < slot.getTime()) {
+          this.state.lastSchemaCheck = Date.now()
+          try { await this.withJobLock('schema-check', () => this.checkAllSchemas()); ran.push({ id: 'schema', ok: true }) } catch (error) { ran.push({ id: 'schema', ok: false, error: error.message }) }
+        }
+      }
+      this.state.scheduler = { lastTickAt: started, lastTickMs: Date.now() - started, lastRan: ran.slice(0, 50), lastError: undefined }
+      await this.save()
+    } finally {
+      this.alertBusy = false
+    }
+  },
+
+  schedulerStatus() {
+    const now = Date.now()
+    return {
+      ...(this.state.scheduler ?? {}),
+      running: Boolean(this.alertTimer),
+      nextAlerts: (this.state.alerts ?? []).filter(a => a.enabled).map(a => ({ id: a.id, name: a.name, dueAt: this.alertDueAt(a, now) })).sort((x, y) => x.dueAt - y.dueAt).slice(0, 20),
+      schemaCheckDaily: this.state.settings.schemaCheckDaily || null,
+      lastSchemaCheck: this.state.lastSchemaCheck ?? null,
+    }
+  },
+}

package/service/dashboards.js

@@ -0,0 +1,359 @@
+/**
+ * Nl2SqlService methods: dashboards.
+ * Mixed into the service prototype by index.js; `this` is the service.
+ */
+import { normalizeFilters } from '../filters.js'
+import { referencedTables } from '../policy.js'
+import { admitSql } from '../sql-guard.js'
+import { UserError, newId, overviewPlans, requireText, upsert } from './shared.js'
+
+/** Widget width: 'third' | 'half' | 'full' (anything else → 'half'). */
+export function widgetWidth(width) {
+  return width === 'full' || width === 'third' ? width : 'half'
+}
+
+export const methods = {
+  // ------------------------------------------------------------ dashboard
+
+  listDashboard(dashboardId) {
+    return (dashboardId ? this.requireDashboard(dashboardId) : this.currentDashboardObj()).widgets
+  },
+
+  requireDashboard(id) {
+    const d = this.state.dashboards.find(x => x.id === id)
+    if (!d) throw new UserError('nl2sql/unknown-dashboard', '看板不存在')
+    return d
+  },
+
+  listDashboards() {
+    return { current: this.currentDashboardObj().id, dashboards: this.state.dashboards.map(d => ({ id: d.id, name: d.name, description: d.description ?? '', widgets: d.widgets.length, filters: d.filters?.length ?? 0, createdAt: d.createdAt, updatedAt: d.updatedAt })) }
+  },
+
+  async saveDashboard({ id, name, description, copyFrom }) {
+    let d = id ? this.requireDashboard(id) : undefined
+    const nm = requireText(name ?? d?.name, 'name', 40)
+    if (this.state.dashboards.some(x => x.name === nm && x.id !== d?.id)) throw new UserError('nl2sql/duplicate', `看板名称已存在：${nm}`)
+    if (!d) {
+      const src = copyFrom ? this.requireDashboard(copyFrom) : undefined
+      d = { id: newId('db'), name: nm, description: '', widgets: src ? src.widgets.map(w => ({ ...w, id: newId('w') })) : [], filters: src ? [...(src.filters ?? [])] : [], createdAt: Date.now() }
+      this.state.dashboards.push(d)
+      this.state.currentDashboard = d.id
+    }
+    d.name = nm
+    if (description !== undefined) d.description = String(description).slice(0, 300)
+    d.updatedAt = Date.now()
+    this.syncLegacyDashboard()
+    await this.save()
+    return this.listDashboards()
+  },
+
+  async deleteDashboard(id) {
+    if (this.state.dashboards.length <= 1) throw new UserError('nl2sql/invalid', '至少保留一个看板')
+    this.requireDashboard(id)
+    this.state.dashboards = this.state.dashboards.filter(d => d.id !== id)
+    if (this.state.currentDashboard === id) this.state.currentDashboard = this.state.dashboards[0].id
+    for (const r of this.state.reports) if (r.dashboardId === id) delete r.dashboardId
+    this.syncLegacyDashboard()
+    await this.save()
+    return this.listDashboards()
+  },
+
+  async selectDashboard(id) {
+    this.requireDashboard(id)
+    this.state.currentDashboard = id
+    this.syncLegacyDashboard()
+    await this.save()
+    return this.listDashboards()
+  },
+
+  /** Move or copy a widget into another dashboard. */
+  async transferWidget({ id, toDashboardId, copy = false }) {
+    const target = this.requireDashboard(toDashboardId)
+    const from = this.state.dashboards.find(d => d.widgets.some(w => w.id === id))
+    if (!from) throw new UserError('nl2sql/unknown-widget', '看板组件不存在')
+    const w = from.widgets.find(x => x.id === id)
+    target.widgets.push(copy ? { ...w, id: newId('w') } : w)
+    if (!copy) from.widgets = from.widgets.filter(x => x.id !== id)
+    this.syncLegacyDashboard()
+    await this.save()
+    return { ok: true }
+  },
+
+  async pinWidget({ title, sql, datasourceId, chart, width, dashboardId }) {
+    const ds = this.requireDatasource(datasourceId)
+    admitSql(sql, { dialect: ds.type ?? 'mysql' })
+    const d = dashboardId ? this.requireDashboard(dashboardId) : this.currentDashboardObj()
+    const widget = { id: newId('w'), title: String(title || 'Untitled').slice(0, 120), sql, datasourceId: ds.id, chart: chart ?? { type: 'table' }, width: widgetWidth(width), createdAt: Date.now() }
+    d.widgets.push(widget)
+    this.syncLegacyDashboard()
+    await this.save()
+    return widget
+  },
+
+  findWidget(id) {
+    for (const d of this.state.dashboards) {
+      const w = d.widgets.find(x => x.id === id)
+      if (w) return { w, d }
+    }
+    return {}
+  },
+
+  async unpinWidget(id) {
+    for (const d of this.state.dashboards) d.widgets = d.widgets.filter(w => w.id !== id)
+    this.syncLegacyDashboard()
+    await this.save()
+    return { deleted: id }
+  },
+
+  async runWidget(id, filters, { useCache = true, actor } = {}) {
+    const { w, d } = this.findWidget(id)
+    if (!w) throw new UserError('nl2sql/unknown-widget', '看板组件不存在')
+    return this.runQuery({ governed: true, sql: w.sql, datasourceId: w.datasourceId, title: w.title, chart: w.chart, source: 'dashboard', confirmScan: true, filters: filters ?? d.filters ?? [], useCache, actor })
+  },
+
+  async updateWidget({ id, title, chart, width, sql }) {
+    const { w } = this.findWidget(id)
+    if (!w) throw new UserError('nl2sql/unknown-widget', '看板组件不存在')
+    if (title !== undefined) w.title = requireText(title, 'title', 120)
+    if (chart !== undefined) w.chart = chart
+    if (width !== undefined) w.width = widgetWidth(width)
+    if (sql !== undefined) { admitSql(sql, { dialect: this.findDatasource(w.datasourceId)?.type ?? 'mysql' }); w.sql = sql }
+    await this.save()
+    return w
+  },
+
+  /** Set the widget order of a dashboard; `ids` must be a permutation of its widget ids. */
+  async reorderWidgets({ dashboardId, ids } = {}) {
+    const d = dashboardId ? this.requireDashboard(dashboardId) : this.currentDashboardObj()
+    if (!Array.isArray(ids)) throw new UserError('nl2sql/invalid', 'ids 必须是数组')
+    const byId = new Map(d.widgets.map(w => [w.id, w]))
+    if (ids.length !== d.widgets.length || new Set(ids).size !== ids.length || ids.some(id => !byId.has(id))) throw new UserError('nl2sql/invalid', 'ids 必须恰好包含该看板的全部组件（不能重复或缺少）')
+    d.widgets = ids.map(id => byId.get(id))
+    d.updatedAt = Date.now()
+    this.syncLegacyDashboard()
+    await this.save()
+    return d.widgets
+  },
+
+  async moveWidget({ id, delta }) {
+    const list = this.findWidget(id).d?.widgets ?? []
+    const i = list.findIndex(x => x.id === id)
+    const j = i + (delta < 0 ? -1 : 1)
+    if (i < 0 || j < 0 || j >= list.length) return list
+    ;[list[i], list[j]] = [list[j], list[i]]
+    await this.save()
+    return list
+  },
+
+  listHistory({ limit = 100, datasourceId, status, source, search, actorId } = {}) {
+    const q = search ? String(search).toLowerCase() : ''
+    return this.records.list('history', { limit: Math.min(limit, 1000), ref: datasourceId, filter: (h) =>
+      (!actorId || h.actor?.id === actorId) &&
+      (!status || h.status === status || (status === 'ok' && h.status === undefined)) &&
+      (!source || h.source === source) &&
+      (!q || h.sql.toLowerCase().includes(q) || (h.title ?? '').toLowerCase().includes(q)) })
+  },
+
+  /**
+   * Delete history entries: one id, a list of ids, or every entry of the same
+   * question (`title`) for a data source (used by "最近的提问" where one row
+   * stands for repeated asks of the same question).
+   */
+  async deleteHistory({ id, ids, title, datasourceId } = {}) {
+    const list = [...new Set([...(ids ?? []), ...(id ? [id] : [])].map(String))]
+    if (!list.length && !title) throw new UserError('nl2sql/invalid', '缺少要删除的历史记录')
+    let deleted = 0
+    for (const x of list) {
+      if (this.records.get('history', x)) { this.records.delete('history', x); deleted++ }
+    }
+    if (title) {
+      const same = this.records.list('history', { ref: datasourceId, limit: 100000, filter: h => h.title === title && h.source === 'agent' })
+      for (const h of same) { this.records.delete('history', h.id); deleted++ }
+    }
+    if (!deleted) throw new UserError('nl2sql/not-found', '历史记录不存在或已删除')
+    this.auditAdmin('history.delete', title ? `「${String(title).slice(0, 60)}」${deleted} 条` : `${deleted} 条`)
+    await this.save()
+    return { deleted }
+  },
+
+  async clearHistory() {
+    this.records.clear('history')
+    await this.save()
+    return { cleared: true }
+  },
+
+  // ----------------------------------------------------- scheduled reports
+
+  scheduleService() {
+    const schedule = this.ctx.get('schedule')
+    if (!schedule) throw new UserError('nl2sql/no-schedule', '当前 Harness 没有启用定时任务服务（dsh-schedule），无法创建定时报告。')
+    return schedule
+  },
+
+  reportPrompt(report, ds) {
+    const dash = (report.dashboardId && this.state.dashboards.find(d => d.id === report.dashboardId)) || this.currentDashboardObj()
+    const scope = report.scope === 'dashboard'
+      ? `请依次执行「数据问答」看板「${dash.name}」中属于该数据源的全部图表对应的查询（SQL 见下），用 nl2sql_query 重新查询并生成图表：\n${dash.widgets.filter(w => w.datasourceId === ds.id).map((w, i) => `${i + 1}. ${w.title}\n${w.sql}`).join('\n\n') || '（看板暂无该数据源的图表，请根据下面的分析要求自行选择指标）'}`
+      : `分析要求：${report.question}`
+    return [
+      `[数据问答定时报告] ${report.title}`,
+      `先调用 nl2sql_datasource action=use datasource=${ds.id}（${ds.name}）绑定数据源，然后完成以下分析。`,
+      scope,
+      report.instructions ? `补充要求：${report.instructions}` : '',
+      report.channelId && this.state.channels.some(c => c.id === report.channelId) ? `完成后调用 nl2sql_send，channel=${report.channelId}（${this.state.channels.find(c => c.id === report.channelId).name}），title="${report.title}"，text 为你的报告摘要（Markdown），resultIds 为本次关键查询的 resultId（最多 6 个）。` : '',
+      `最后用中文写一段报告摘要：关键数字、与上一周期相比的变化（${report.period === 'weekly' ? '周环比' : '日环比'}，若可计算）、异常点和建议关注事项。不要逐行复述表格数据。`,
+    ].filter(Boolean).join('\n\n')
+  },
+
+  timingFor(report) {
+    const tz = report.timeZone || Intl.DateTimeFormat().resolvedOptions().timeZone
+    if (report.period === 'weekly') return { kind: 'weekly', weekly: { time: report.time, time_zone: tz, weekdays: report.weekdays?.length ? report.weekdays : [1] } }
+    return { kind: 'daily', daily: { time: report.time, time_zone: tz } }
+  },
+
+  async listReports() {
+    let catalog = []
+    try { catalog = await this.ctx.get('schedule')?.catalog() ?? [] } catch {}
+    const byId = new Map(catalog.map(e => [e.id, e]))
+    return this.state.reports.map(r => {
+      const e = byId.get(r.scheduleId)
+      return { ...r, channelName: this.state.channels.find(c => c.id === r.channelId)?.name ?? null, status: e?.status ?? (r.paused && !r.scheduleId ? 'paused' : 'missing'), scheduledAt: e?.scheduledAt ?? null, lastDelivery: e?.lastDelivery ?? null, datasourceName: this.findDatasource(r.datasourceId)?.name ?? r.datasourceId }
+    })
+  },
+
+  async saveReport(input) {
+    const ds = this.requireDatasource(input.datasourceId)
+    const schedule = this.scheduleService()
+    const existing = input.id ? this.state.reports.find(r => r.id === input.id) : undefined
+    const report = {
+      id: existing?.id ?? newId('rp'),
+      title: requireText(input.title, 'title', 80),
+      datasourceId: ds.id,
+      scope: input.scope === 'dashboard' ? 'dashboard' : 'question',
+      question: input.scope === 'dashboard' ? String(input.question ?? '') : requireText(input.question, 'question', 2000),
+      instructions: String(input.instructions ?? '').slice(0, 1000),
+      period: input.period === 'weekly' ? 'weekly' : 'daily',
+      time: /^\d{2}:\d{2}$/.test(String(input.time)) ? `${input.time}:00` : /^\d{2}:\d{2}:\d{2}$/.test(String(input.time)) ? String(input.time) : '09:00:00',
+      weekdays: Array.isArray(input.weekdays) ? [...new Set(input.weekdays.map(Number).filter(n => n >= 1 && n <= 7))].sort() : [1],
+      timeZone: String(input.timeZone || Intl.DateTimeFormat().resolvedOptions().timeZone),
+      target: input.target === 'new' ? 'new' : 'new_once',
+      channelId: input.channelId && this.state.channels.some(c => c.id === input.channelId) ? input.channelId : undefined,
+      dashboardId: input.dashboardId && this.state.dashboards.some(d => d.id === input.dashboardId) ? input.dashboardId : undefined,
+      createdAt: existing?.createdAt ?? Date.now(),
+      updatedAt: Date.now(),
+    }
+    const request = {
+      title: `数据报告：${report.title}`.slice(0, 120),
+      prompt: this.reportPrompt(report, ds),
+      timing: this.timingFor(report),
+    }
+    let entry
+    if (existing?.scheduleId) {
+      entry = await schedule.edit({ id: existing.scheduleId, action: 'update', patch: { ...request, ...(existing.target !== report.target ? { target: { kind: report.target, create: { agentPreset: 'nl2sql' } } } : {}) } })
+      if (entry?.code === 'schedule_not_found') entry = undefined
+    }
+    if (!entry) {
+      entry = await schedule.create({ ...request, target: { kind: report.target, create: { agentPreset: 'nl2sql' } } })
+    }
+    report.scheduleId = entry.id
+    this.state.reports = upsert(this.state.reports, report)
+    await this.save()
+    return report
+  },
+
+  async setReportActive({ id, active }) {
+    const report = this.state.reports.find(r => r.id === id)
+    if (!report) throw new UserError('nl2sql/unknown-report', '报告不存在')
+    // Imported without a schedule service: activating creates the schedule now.
+    if (!report.scheduleId) {
+      if (!active) return { id: report.id, status: 'paused' }
+      const { paused: _p, ...def } = report
+      return this.saveReport({ ...def, time: def.time })
+    }
+    const res = await this.scheduleService().edit({ id: report.scheduleId, action: 'update', patch: { active: Boolean(active) } })
+    if (res?.code) throw new UserError('nl2sql/schedule', `更新定时任务失败：${res.code}`)
+    return res
+  },
+
+  async runReportNow(id) {
+    const report = this.state.reports.find(r => r.id === id)
+    if (!report) throw new UserError('nl2sql/unknown-report', '报告不存在')
+    const res = await this.scheduleService().run({ id: report.scheduleId })
+    if (res?.code === 'schedule_execution_pending') throw new UserError('nl2sql/schedule', '报告正在执行中，请稍后再试')
+    if (res?.code) throw new UserError('nl2sql/schedule', `执行失败：${res.code}`)
+    return res
+  },
+
+  async deleteReport(id) {
+    const report = this.state.reports.find(r => r.id === id)
+    if (!report) return { deleted: id }
+    try { await this.ctx.get('schedule')?.edit({ id: report.scheduleId, action: 'delete' }) } catch {}
+    this.state.reports = this.state.reports.filter(r => r.id !== id)
+    await this.save()
+    return { deleted: id }
+  },
+
+  // --------------------------------------------------------- auto overview
+
+  /** Build overview widgets for one table from its column roles; runs each query and returns results. */
+  async tableOverview({ datasourceId, table, pin = false }) {
+    const ds = this.requireDatasource(datasourceId)
+    const schema = await this.visibleSchema(ds)
+    const t = schema.tables.find(x => x.name === table)
+    if (!t) throw new UserError('nl2sql/unknown-table', `表不存在或无权访问：${table}`)
+    const plans = overviewPlans(ds.type ?? 'mysql', t, this.knowledgeFor(ds.id))
+    const results = []
+    for (const plan of plans) {
+      try {
+        const r = await this.runQuery({ sql: plan.sql, datasourceId: ds.id, title: plan.title, chart: plan.chart, source: 'ui', confirmScan: true })
+        results.push(r)
+        if (pin) await this.pinWidget({ title: plan.title, sql: plan.sql, datasourceId: ds.id, chart: r.chart, width: plan.width })
+      } catch (error) {
+        results.push({ title: plan.title, sql: plan.sql, error: error.message })
+      }
+    }
+    return { table: t.name, results }
+  },
+
+  // ------------------------------------------------------ dashboard filters
+
+  /** Columns dashboard filters can target, from the visible schema of the widgets' tables. */
+  async filterCandidates(dashboardId) {
+    const time = new Map()
+    const dims = new Map()
+    for (const w of (dashboardId ? this.requireDashboard(dashboardId) : this.currentDashboardObj()).widgets) {
+      const ds = this.findDatasource(w.datasourceId)
+      if (!ds) continue
+      let schema
+      try { schema = await this.visibleSchema(ds) } catch { continue }
+      const refs = referencedTables(w.sql, schema.tables, { dialect: ds.type ?? 'mysql' })
+      for (const t of schema.tables.filter(x => refs.includes(x.name))) {
+        for (const c of t.columns) {
+          if (c.roles.includes('time') && /date|time|stamp/.test(c.dataType)) {
+            time.set(c.name, { column: c.name, label: c.comment || c.name, tables: [...new Set([...(time.get(c.name)?.tables ?? []), t.name])] })
+          } else if ((c.roles.includes('enum') || c.roles.includes('geo')) && !c.roles.includes('sensitive')) {
+            const prev = dims.get(c.name)
+            dims.set(c.name, {
+              column: c.name, label: prev?.label || c.comment || c.name,
+              tables: [...new Set([...(prev?.tables ?? []), t.name])],
+              values: [...new Set([...(prev?.values ?? []), ...(c.values ?? []).map(v => String(v.value))])].slice(0, 50),
+            })
+          }
+        }
+      }
+    }
+    return { time: [...time.values()], dims: [...dims.values()].sort((a, b) => b.tables.length - a.tables.length).slice(0, 30) }
+  },
+
+  getDashboardFilters(dashboardId) {
+    return (dashboardId ? this.requireDashboard(dashboardId) : this.currentDashboardObj()).filters ?? []
+  },
+
+  async saveDashboardFilters(filters, dashboardId) {
+    const d = dashboardId ? this.requireDashboard(dashboardId) : this.currentDashboardObj()
+    d.filters = normalizeFilters(filters)
+    this.syncLegacyDashboard()
+    await this.save()
+    return d.filters
+  },
+}