diff --git a/frontend/src/api/caliberLedger.ts b/frontend/src/api/caliberLedger.ts index 02aad7e1..4e9a6432 100644 --- a/frontend/src/api/caliberLedger.ts +++ b/frontend/src/api/caliberLedger.ts @@ -13,7 +13,8 @@ */ import type { CaliberDescriptor, CaliberDraft, CaliberDraftAttachOut, CaliberDraftSummary, CaliberTrialOut, CertifyQueue, DraftMetric, - FreezeOut, LedgerFeedbackOut, LedgerFeedbackVerdict, LedgerIssueOut, LedgerReconcileIn, LedgerReconcileOut, RunLedger, + DraftTrialOut, FreezeOut, LedgerFeedbackOut, LedgerFeedbackVerdict, LedgerIssueOut, LedgerReconcileIn, LedgerReconcileOut, + RunLedger, } from '../typesLedger' import { get, patch, post, type RequestOptions } from './http' @@ -48,19 +49,21 @@ export const caliberLedger = { { inputs }, ), /** - * 从业务文档起草口径(app/ledger/docdraft.py,搭建者):草稿只产出定义,不产出取数。发起后立刻返回 drafting,模型在后台跑, - * 结果用 draft() 反复取,直到状态离开 drafting + * 从业务文档起草口径(app/ledger/docdraft.py,搭建者):发起后立刻返回 drafting,模型在后台读文档、对照数据目录 + * 写定义和取数,落成草稿图并自动试运行;结果用 draft() 反复取,直到状态离开 drafting */ drafts: (status?: string, opts?: RequestOptions) => get<{ drafts: CaliberDraftSummary[] }>(`/ledger/drafts${status ? `?status=${encodeURIComponent(status)}` : ''}`, opts), - /** 一份草稿的完整内容:payload 摊平在上层(metrics / dropped / open_questions / alignment) */ + /** 一份草稿的完整内容:payload 摊平在上层(metrics / entry_fields / dropped / open_questions / alignment / trial) */ draft: (draftId: string, opts?: RequestOptions) => get(draftAt(draftId), opts), + /** 起草后自动发起的那次只读试运行:状态和每个指标的值,running 时轮询到终态 */ + draftTrial: (draftId: string, opts?: RequestOptions) => get(`${draftAt(draftId)}/trial`, opts), /** 选文档发起起草:documents 是要用的知识库文档 id,guidance 是给模型看的附加要求 */ extractDraft: (body: { documents: string[]; collection?: string; datasource_id?: string; guidance?: string }) => post<{ draft_id: string; status: string }>('/ledger/drafts/extract', body), /** * 改标题、整体换掉指标、或把答清的问题消掉(resolved 是问题原文)。服务端据此重算状态:还有问题 → questions_open, - * 否则 path_pending;已经接上或驳回的不改状态 + * 否则 ready;已经接上或驳回的不改状态 */ patchDraft: (draftId: string, body: { title?: string; metrics?: DraftMetric[]; resolved?: string[] }) => patch(draftAt(draftId), body), diff --git a/frontend/src/lib/termsLedger.ts b/frontend/src/lib/termsLedger.ts index 25a5ae1c..df1e733e 100644 --- a/frontend/src/lib/termsLedger.ts +++ b/frontend/src/lib/termsLedger.ts @@ -227,12 +227,13 @@ export const LEDGER_UI = { drafts: { entry: '从业务文档起草', title: '从业务文档起草口径', - subtitle: '文档里写的是业务说法,这里整理成定义草稿;取数路径接上一次真实运行', + subtitle: '文档整理成定义和取数,自动试运行一次;去画布审改后由人签字发布', back: '返回口径目录', refresh: '刷新', - /** 列表按状态筛:全部加五种落点,起草中的只出现在全部里 */ + /** 列表按状态筛:全部加六种落点,起草中的只出现在全部里 */ filter: { all: '全部', + ready: '待签字发布', questions_open: '待确认问题', path_pending: '待接数据路径', attached: '已接上', @@ -241,6 +242,7 @@ export const LEDGER_UI = { } as Record, status: { drafting: '起草中', + ready: '待签字发布', questions_open: '待确认问题', path_pending: '待接数据路径', attached: '已接上', @@ -252,7 +254,7 @@ export const LEDGER_UI = { questions ? `${formatNumber(questions)} 个未决问题` : '没有未决问题'}`, loadFailed: '无法读取口径草稿', empty: '还没有口径草稿', - emptyBody: '选一份业务文档,把里面的指标整理成定义草稿', + emptyBody: '选一份业务文档,把里面的指标整理成定义和取数草稿', emptyFiltered: '这个状态下没有草稿,换个状态看看', // ---- 发起:选文档、可选数据源和起草要求 ---- @@ -262,22 +264,32 @@ export const LEDGER_UI = { noDocuments: '知识库里还没有已完成的文档', noDocumentsBody: '先在知识页上传业务文档,切块完成后再来起草', documentMeta: (collection: string, chunks: number) => `${collection} · ${formatNumber(chunks)} 段`, - datasource: '数据源(可选)', - datasourceHint: '只写进适用范围,不读表结构', - datasourceNone: '不指定', + datasource: '数据源(必选)', + datasourceHint: '取数 SQL 对照这个库的真实表和列写,先探查过表结构才能起草', guidance: '起草要求(可选)', guidancePlaceholder: '例如:只整理和月度结算有关的指标', submit: '开始起草', submitting: '正在发起…', needDoc: '请至少选一份文档', - started: '已开始起草,完成后指标会出现在下面', + started: '已开始起草,完成并试运行后指标和数会出现在下面', // ---- 抽取中 ---- drafting: '正在抽取指标…', - draftingHint: '模型在后台读文档、核对引用,通常不到一分钟;离开页面不影响结果', + draftingHint: '模型在后台读文档、对照数据目录写定义和取数,通常不到一分钟;离开页面不影响结果', draftingTimeout: '起草超过一分钟还没有结果:稍后刷新再看;失败原因会写在这份草稿上', draftingFailed: '起草没有完成', + // ---- 自动试运行 ---- + trial: '自动试运行', + trialHint: '发起时按草稿图只读运行一次,只用来看数和定义对不对得上', + trialRunning: '正在试运行…', + trialSucceeded: '试运行已完成', + trialFailed: '试运行没有成功', + trialTimeout: '试运行超过一分钟还没有结果:稍后刷新再看', + trialNoMetrics: '这次试运行没有产出指标值', + trialUnavailable: '暂时无法读取试运行状态', + trialRun: '看这次运行', + // ---- 详情 ---- documentsUsed: (n: number) => `${formatNumber(n)} 份文档`, truncated: '文档太长,后面的段落没有参与起草:可以少选几份,或先拆分文档', @@ -286,6 +298,9 @@ export const LEDGER_UI = { noMetricsBody: '文档里没有能逐字核对上引用的指标定义,可以换一份文档或补充起草要求后重来', synonyms: (list: string) => `又称:${list}`, unit: '单位', + decimals: '小数位', + expression: '表达式', + definition: '定义', grain: '粒度', timeField: '时间字段', dimensions: '维度', @@ -306,7 +321,7 @@ export const LEDGER_UI = { resolveNeed: '请先勾选已经问清的问题', resolved: (n: number) => `已移除 ${formatNumber(n)} 个问题`, dropped: '被丢弃的条目', - droppedHint: '只产出定义:带 SQL、表名痕迹,或引用无法逐字核对上的指标不留下', + droppedHint: '带不了能对照数据目录的取数,或引用无法逐字核对上的指标不留下', alignment: '和已发布口径对齐', alignmentNew: '新的', alignmentDuplicate: '已有出处', @@ -314,9 +329,20 @@ export const LEDGER_UI = { model: (id: string) => `起草模型:${id}`, createdBy: (who: string) => `起草人:${who}`, - // ---- 接上一次运行 ---- - attach: '接上一次真实运行', - attachHint: '取数路径照抄这次运行里执行过的查询,文档只贡献定义;接上后产出可试运行的工作流版本,不发布', + // ---- 入口字段与发布 ---- + entryFields: '入口字段', + entryFieldsHint: '发布后按这些字段收参数;缺省值可以不填', + entryFieldNone: '这份草稿的图没有入口字段', + required: '必填', + optional: '可选', + defaultValue: (value: string) => `缺省 ${value}`, + publish: '去画布审改并发布', + publishHint: '在画布上核对图、改完再发布;发布这一步由人签字', + workflowVersion: (version: number) => `工作流 v${version}`, + + // ---- 接上一次运行(辅助入口) ---- + attach: '接上一次运行', + attachHint: '已经有一次运行得出的答案,让它认这份定义:取数照抄那次运行执行过的查询,不重新生成;接上后产出可试运行的工作流版本,不发布', runId: '运行 id', runIdPlaceholder: '粘贴运行记录里的 id', recentRuns: '最近成功的运行', diff --git a/frontend/src/pages/ledger/CaliberDrafts.tsx b/frontend/src/pages/ledger/CaliberDrafts.tsx index d70a93a0..d3150729 100644 --- a/frontend/src/pages/ledger/CaliberDrafts.tsx +++ b/frontend/src/pages/ledger/CaliberDrafts.tsx @@ -1,19 +1,20 @@ /** * 从业务文档起草口径(/ledger/drafts;服务端 app/ledger/docdraft.py、docattach.py)。 * - * 业务文档写的是业务说法(名称、粒度、分子分母、过滤),不是库里的表和 SQL。这一页做三段: - * - 发起:选知识库文档,可选数据源(只写进适用范围)和一段起草要求。模型在后台读文档、核对引用,页面轮询详情直到状态离开 - * drafting(最多一分钟),期间显示抽取中; - * - 审读:每条指标带单位、粒度、定义和逐字核对过的引用原文(第 N 段),逐条的未决问题可以勾掉;被丢弃的条目单独列出原因。 - * 引用的段落正文按需从知识库取,省得一次读几十份文档的全部段落; - * - 接上:草稿只到定义为止,取数路径必须来自一次真实运行。填运行 id(也可以从最近成功的运行里选),attach 之后产出可试运行 - * 的工作流版本,不发布;不是口径就驳回并记一条审计。 + * 主路径一次到位:选文档 → 模型读文档、对照数据目录产出定义 + 取数 + 入口字段 + 指标表达式 → 服务端校验后落成草稿图 + * → 后台自动只读试运行 → 这里展示「定义 + 数 + 原文引用」→ 人去画布审改并发布。发布才需要人签字。 + * - 发起:选知识库文档,可选数据源(只写进适用范围)和一段起草要求,页面轮询详情直到状态离开 drafting(最多一分钟); + * - 试运行:草稿顶部显示这次自动试运行的状态和每个指标的值,running 时每两秒取一次,最多等一分钟;失败照实写原因; + * - 审读:每条指标带单位、粒度、指标表达式、定义和逐字核对过的引用原文(第 N 段),逐条的未决问题可以勾掉;被丢弃 + * 的条目单独列出原因;入口字段列出名字、类型、必填和缺省值; + * - 发布:主按钮去画布审改并发布。「接上一次运行」只是辅助入口:已经有答案时让它认这份定义。 * - * 状态由服务端算(还有问题 → questions_open,否则 path_pending;attach 之后 attached),页面只按状态画。 + * 页面不显示 SQL,取数到画布上看。状态由服务端算(还有问题 → questions_open,否则 ready;旧路径可能停在 path_pending), + * 页面只按状态画。 */ import { useCallback, useEffect, useMemo, useRef, useState } from 'react' import { Link } from 'react-router-dom' -import { ChevronLeft, FileText, RefreshCw, ScrollText } from 'lucide-react' +import { ChevronLeft, FileText, PenLine, RefreshCw, ScrollText } from 'lucide-react' import clsx from 'clsx' import { api } from '../../api/client' import { EmptyState, ErrorState, Notice, PageHeader, Skeleton, Spinner, promptDialog, toast } from '../../components/ui' @@ -21,18 +22,18 @@ import { formatDateTime, formatTime } from '../../lib/format' import { LEDGER_UI } from '../../lib/termsLedger' import type { DataSourceName, KbDocument, Run } from '../../types' import type { - CaliberDraft, CaliberDraftStatus, CaliberDraftSummary, DraftAlignment, DraftCitation, DraftMetric, + CaliberDraft, CaliberDraftStatus, CaliberDraftSummary, DraftAlignment, DraftCitation, DraftMetric, DraftTrialOut, } from '../../typesLedger' const D = LEDGER_UI.drafts -/** 列表的状态筛:全部加四种落点,起草中的只出现在全部里 */ +/** 列表的状态筛:全部加六种落点,起草中的只出现在全部里 */ type Filter = '' | Exclude -const FILTERS: Filter[] = ['', 'questions_open', 'path_pending', 'attached', 'rejected', 'failed'] +const FILTERS: Filter[] = ['', 'ready', 'questions_open', 'path_pending', 'attached', 'rejected', 'failed'] -/** 状态标签:起草中 / 待确认问题 / 待接数据路径 / 已接上 / 已驳回 / 起草失败 */ +/** 状态标签:起草中 / 待签字发布 / 待确认问题 / 待接数据路径 / 已接上 / 已驳回 / 起草失败 */ function StatusPill({ status }: { status: CaliberDraftStatus }) { - const color = status === 'attached' ? 'var(--ok)' : status === 'rejected' ? 'var(--text-faint)' + const color = status === 'ready' || status === 'attached' ? 'var(--ok)' : status === 'rejected' ? 'var(--text-faint)' : status === 'drafting' ? 'var(--accent)' : status === 'failed' ? 'var(--err)' : 'var(--warn)' return ( (null) const [listError, setListError] = useState(null) @@ -122,6 +130,12 @@ export function CaliberDrafts() { const [pollingId, setPollingId] = useState(null) const [pollTimedOut, setPollTimedOut] = useState(false) + /** 这次自动试运行的结果;running 时单独轮询,和草稿抽取的轮询互不相干 */ + const [trial, setTrial] = useState(null) + const [trialPollId, setTrialPollId] = useState(null) + const [trialTimedOut, setTrialTimedOut] = useState(false) + const [trialError, setTrialError] = useState(null) + /** 引用所在段落的正文和段号:按文档懒取,取过的记在这里 */ const [chunks, setChunks] = useState>({}) const asked = useRef(new Set()) @@ -141,7 +155,12 @@ export function CaliberDrafts() { api.kb.documents().then((rows) => { setDocs(rows); setDocsError(null) }, (e) => { setDocs([]); setDocsError(e) }) api.datasources.names().then( - (all) => setSources(all.filter((s) => s.enabled !== false)), + (all) => { + const enabled = all.filter((s) => s.enabled !== false) + setSources(enabled) + // 数据源必选(取数 SQL 要对照这个库的表和列写),默认选中第一个,别让人对着 422 才知道要填 + setDatasourceId((cur) => cur || (enabled[0]?.id ?? '')) + }, () => setSources([]), ) }, []) @@ -170,6 +189,10 @@ export function CaliberDrafts() { setRecentRuns(null) setPollingId(null) setPollTimedOut(false) + setTrial(null) + setTrialPollId(null) + setTrialTimedOut(false) + setTrialError(null) try { const draft = await api.caliberLedger.draft(id) if (seq !== openSeq.current) return @@ -213,6 +236,63 @@ export function CaliberDrafts() { return () => { alive = false; clearInterval(timer) } }, [pollingId, loadList]) + /** 草稿有了试运行就取一次结果;还在 running 就交给下面的轮询 */ + useEffect(() => { + const id = detail?.id + const run = detail?.trial?.run_id + if (!id || !run) return + let alive = true + setTrial((cur) => (cur?.run_id === run ? cur : { + run_id: run, status: detail?.trial?.status ?? 'running', metrics: [], error: detail?.trial?.error ?? '', + })) + api.caliberLedger.draftTrial(id).then((out) => { + if (!alive) return + setTrial(out) + setTrialError(null) + setTrialTimedOut(false) + if (out.status === 'running') setTrialPollId(id) + }, (e) => { + if (!alive) return + setTrialError(e) + setTrialPollId(null) + }) + return () => { alive = false } + }, [detail?.id, detail?.trial?.run_id]) + + /** 试运行还在跑:每两秒取一次,超过一分钟就停;收尾时顺带刷新详情(状态可能已变成待签字发布) */ + useEffect(() => { + if (!trialPollId) return + const until = Date.now() + 60_000 + let alive = true + const timer = setInterval(() => { + api.caliberLedger.draftTrial(trialPollId).then((out) => { + if (!alive) return + setTrial(out) + setTrialError(null) + if (out.status === 'running') { + if (Date.now() > until) { + setTrialPollId(null) + setTrialTimedOut(true) + } + return + } + setTrialPollId(null) + setTrialTimedOut(false) + loadList() + const seq = openSeq.current + api.caliberLedger.draft(trialPollId).then((fresh) => { + if (seq !== openSeq.current) return + setDetail((cur) => (cur && cur.id === fresh.id ? fresh : cur)) + }, () => undefined) + }, (e) => { + if (!alive) return + setTrialPollId(null) + setTrialError(e) + }) + }, 2000) + return () => { alive = false; clearInterval(timer) } + }, [trialPollId, loadList]) + useEffect(() => { for (const doc of detail?.documents ?? []) ensureChunks(doc.document_id) }, [detail, ensureChunks]) @@ -231,6 +311,7 @@ export function CaliberDrafts() { const paragraphOf = (citation: DraftCitation): number | null => { const ordinal = chunks[citation.chunk]?.ordinal if (typeof ordinal === 'number') return ordinal + if (typeof citation.ordinal === 'number') return citation.ordinal const documentId = citation.document_id || chunkDoc[citation.chunk] const doc = detail?.documents?.find((d) => d.document_id === documentId) const at = doc?.chunk_ids.indexOf(citation.chunk) ?? -1 @@ -354,11 +435,93 @@ export function CaliberDrafts() { ) } + /** 自动试运行:状态、每个指标的值(名字和值成对)、失败原因;没有试运行就整块不画 */ + const renderTrial = (draft: CaliberDraft) => { + const status = trial?.status ?? draft.trial?.status + if (!status) return null + const rows = trial?.metrics ?? [] + const color = status === 'succeeded' ? 'var(--ok)' : status === 'failed' ? 'var(--err)' : 'var(--accent)' + const label = status === 'succeeded' ? D.trialSucceeded : status === 'failed' ? D.trialFailed : D.trialRunning + const unitOf = (id: string) => (draft.metrics ?? []).find((m) => m.id === id)?.unit + return ( +
+
+

{D.trial}

+ {label} + {trial?.run_id && ( + + {D.trialRun} + + )} + {D.trialHint} +
+ {status === 'running' && ( +

+ {D.trialRunning} +

+ )} + {status === 'running' && trialTimedOut &&
{D.trialTimeout}
} + {status === 'failed' && ( +
+ {D.trialFailed}:{trial?.error || draft.trial?.error || D.loadFailed} +
+ )} + {status === 'succeeded' && (rows.length > 0 ? ( +
    + {rows.map((row) => { + const unit = unitOf(row.id) + return ( +
  • + {row.name || row.id} + + {row.rendered ?? (row.value == null ? '—' : String(row.value))}{unit ? ` ${unit}` : ''} + +
  • + ) + })} +
+ ) : ( +

{D.trialNoMetrics}

+ ))} + {trialError != null &&
{D.trialUnavailable}
} +
+ ) + } + + /** 入口字段:发布后按这些字段收参数 */ + const renderEntryFields = (draft: CaliberDraft) => { + const fields = draft.entry_fields + if (!fields) return null + return ( +
+

{D.entryFields}

+

{D.entryFieldsHint}

+ {fields.length > 0 ? ( +
    + {fields.map((field) => { + const hasDefault = field.default !== undefined && field.default !== null && field.default !== '' + return ( +
  • + {field.name} + {field.type || 'string'} + {field.required ? D.required : D.optional} + {hasDefault && {D.defaultValue(defaultText(field.default))}} + {field.description && {field.description}} +
  • + ) + })} +
+ ) :

{D.entryFieldNone}

} +
+ ) + } + const renderMetric = (metric: DraftMetric, index: number) => { const definition = metric.definition ?? {} const citations = definition.citations ?? [] const rows = [ [D.unit, metric.unit], + [D.decimals, metric.decimals != null ? String(metric.decimals) : ''], [D.grain, metric.grain], [D.timeField, metric.time_field], [D.numerator, metric.numerator], @@ -371,7 +534,7 @@ export function CaliberDrafts() { [D.exclusions, definition.exclusions?.join(';')], ].filter(([, value]) => typeof value === 'string' && value.trim()) as [string, string][] return ( -
  • +
  • {metric.name} {!!metric.synonyms?.length && {D.synonyms(metric.synonyms.join('、'))}} @@ -386,7 +549,20 @@ export function CaliberDrafts() { ))} )} - {definition.text &&

    {definition.text}

    } + {metric.expression && ( +
    +

    {D.expression}

    + + {metric.expression} + +
    + )} + {definition.text && ( +
    +

    {D.definition}

    +

    {definition.text}

    +
    + )} {citations.length > 0 && (

    {D.citations}

    @@ -417,9 +593,10 @@ export function CaliberDrafts() { {draft.created_at && {formatTime(draft.created_at)}} {draft.created_by && {D.createdBy(draft.created_by)}} {draft.model_id && {D.model(draft.model_id)}} - {draft.workflow_id && draft.status === 'attached' && ( + {draft.workflow_id && draft.status !== 'rejected' && ( {D.openWorkflow}{draft.workflow_name ? `:${draft.workflow_name}` : ''} + {draft.version != null ? ` · ${D.workflowVersion(draft.version)}` : ''} )}
    @@ -439,6 +616,9 @@ export function CaliberDrafts() { {drafting && pollTimedOut && {D.draftingTimeout}} {draft.truncated && {D.truncated}} + {renderTrial(draft)} + {renderEntryFields(draft)} +

    {D.metrics}

    @@ -485,9 +665,18 @@ export function CaliberDrafts() { {draft.alignment && } + {!drafting && !terminal && draft.workflow_id && ( +
    + + {D.publish} + + {D.publishHint} +
    + )} + {!drafting && !terminal && ( -
    -

    {D.attach}

    +
    + {D.attach}

    {D.attachHint}

    -
    -
    + )} {attachOut && ( @@ -593,8 +782,8 @@ export function CaliberDrafts() {