From 13f1158191f3b1aa926ae6fd0e7937901a746205 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Wed, 4 Nov 2026 00:30:26 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8F=A3=E5=BE=84=E8=B5=B7=E8=8D=89=E4=B8=80?= =?UTF-8?q?=E6=AC=A1=E5=88=B0=E4=BD=8D=EF=BC=9A=E7=94=9F=E6=88=90=E5=8F=96?= =?UTF-8?q?=E6=95=B0=E5=9B=BE=E5=B9=B6=E8=87=AA=E5=8A=A8=E8=AF=95=E8=BF=90?= =?UTF-8?q?=E8=A1=8C=EF=BC=8C=E4=B8=8D=E5=86=8D=E8=A6=81=E6=B1=82=E4=BA=BA?= =?UTF-8?q?=E5=B7=A5=E6=8E=A5=E4=B8=80=E6=AC=A1=E8=BF=90=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 「不从指标定义编译 SQL」管的是事后比对的基准,不是起草。起草照样让模型写 SQL,但只允许 目录里的表和列、单条只读 SELECT、入口字段必须先声明;每条定义仍要能逐字对上原文。 起草成功即建工作流与 v1;试运行只跑取数与口径卡(derive.caliber_probe),不触发报告撰写, 也不会因为没有可用模型就判这份口径不行。接上一次运行保留为辅助入口。 --- backend/app/api/ledger.py | 291 +++++++++++-- backend/app/db/models.py | 14 +- backend/app/ledger/docdraft.py | 22 +- backend/app/ledger/draftplan.py | 450 ++++++++++++++++++++ backend/tests/test_ledger_docdraft_api.py | 486 ++++++++++++++++------ backend/tests/test_ledger_draftplan.py | 200 +++++++++ 6 files changed, 1298 insertions(+), 165 deletions(-) create mode 100644 backend/app/ledger/draftplan.py create mode 100644 backend/tests/test_ledger_draftplan.py diff --git a/backend/app/api/ledger.py b/backend/app/api/ledger.py index 00ae98e2..6e9c0f70 100644 --- a/backend/app/api/ledger.py +++ b/backend/app/api/ledger.py @@ -19,8 +19,10 @@ - GET /api/ledger/calibers、GET /api/ledger/calibers/{workflow_id}/{version}/{node_id}(router,搭建者):口径可调用描述 (app/ledger/descriptor.py):入口字段的 JSON Schema、依赖、能不能组合和出具;不返回 SQL 和参数值。 - POST /api/ledger/drafts/extract、GET /api/ledger/drafts、GET/PATCH /api/ledger/drafts/{id}、POST …/{id}/dismiss、 - POST …/{id}/attach(router,搭建者):从业务文档起草口径(app/ledger/docdraft.py),草稿独立存在、不写进 - workflows.graph;attach 才按一次真实运行补上取数路径(app/ledger/docattach.py)。 + POST …/{id}/attach、GET …/{id}/trial(router,搭建者):从业务文档起草口径。主路径一次到位:模型读文档和数据目录, + 产出定义 + 取数 SQL + 入口字段 + 指标表达式(app/ledger/draftplan.py),服务端校验收成草稿图、建草稿工作流和 v1, + 后台自动只读试跑;草稿页给「定义 + 数 + 原文引用」。attach 保留为辅助入口:已经有跑对的答案时让它认这份定义 + (app/ledger/docattach.py)。 这几个新接口都不放给访问密钥(auth/keys.KEY_ROUTES 不登记)。 """ from __future__ import annotations @@ -404,8 +406,142 @@ def _question_count(payload: dict[str, Any]) -> int: def _status_for(payload: dict[str, Any]) -> str: - """还有问题 → questions_open,否则 path_pending(等一次真实运行补取数路径)。""" - return "questions_open" if _question_count(payload) else "path_pending" + """还有问题 → questions_open;没有问题且有图 → ready;没有图的老草稿 → path_pending。 + + questions_open 现在也有图和数,只是问题还没清完,不阻断试跑;path_pending 只留给这次改版之前起草、还没有取数路径的草稿。 + """ + if _question_count(payload): + return "questions_open" + if payload.get("workflow_id") and payload.get("sql"): + return "ready" + return "path_pending" + + +#: 试跑最多等多久(秒)和轮询间隔:和 trial_caliber 的 300 × 0.1 一致 +TRIAL_TIMEOUT_S = 30 +TRIAL_POLL_S = 0.1 +#: 运行到这里就是终态了(interrupted 归到 failed,接口契约只有三种状态) +TERMINAL_RUN_STATUSES = ("succeeded", "failed", "cancelled", "interrupted") + + +def _run_status(status: Any) -> str: + """运行状态 → 接口契约里的 succeeded / failed / running。""" + if status == "succeeded": + return "succeeded" + if status in ("failed", "cancelled", "interrupted"): + return "failed" + return "running" + + +def _source_tables(source: DataSource) -> dict[str, Any]: + cache = source.schema_cache if isinstance(source.schema_cache, dict) else {} + tables = cache.get("tables") + return tables if isinstance(tables, dict) else {} + + +async def _schema_material(session: AsyncSession, source: DataSource) -> tuple[str, set[str]]: + """这个数据源给模型看的表结构 + 数据目录文本,以及 SQL 允许出现的表名集合。 + + 给模型的是「库概览 + 紧凑表名索引 + 前几十张表的字段/目录」(schema_view 的现成渲染),表名一律照目录原文,模型照着抄。 + allowed_tables 收全部探查到的表(含 schema 前缀写法):文本里被截掉详情的表也允许,因为索引里有名字。 + """ + from app.data import catalog, schema_view + + cache = source.schema_cache if isinstance(source.schema_cache, dict) else {} + tables = _source_tables(source) + if not tables: + return "", set() + entries = await catalog.read_catalog(session, source.id) + notes = {table: entry.notes for table, entry in entries.items()} + lines = [schema_view.overview_line(source, catalog_tables=sum( + 1 for entry in entries.values() if catalog.visible_notes(entry.notes)))] + lines.append(schema_view.table_index(source, notes)) + for position, table in enumerate(tables): + if position >= 60: + break + lines.append(schema_view.table_detail(source, table, catalog_notes=notes)) + schema = cache.get("schema") + allowed: set[str] = set() + for table in tables: + allowed.add(str(table)) + if isinstance(schema, str) and schema: + allowed.add(f"{schema}.{table}") + return "\n\n".join(line for line in lines if line), allowed + + +async def _save_trial(draft_id: str, trial: dict[str, str]) -> None: + """把试跑状态写进 draft.payload["trial"](用新会话:后台这一段和起草那段不是同一个事务)。""" + async with SessionLocal() as fresh: + row = await fresh.get(CaliberDraft, draft_id) + if row is None or not isinstance(row.payload, dict): + return + body = dict(row.payload) + body["trial"] = trial + row.payload = body + await fresh.commit() + + +async def _run_trial(*, draft_id: str, workflow_id: str, graph: dict[str, Any], values: dict[str, Any], + started_by: str | None) -> dict[str, str]: + """后台试跑草稿的取数与口径卡,返回 payload["trial"] 的形状(run_id / status / error)。 + + 跑的是**探针图**(取数 + 口径卡,`derive.caliber_probe`),不是整张草稿图:草稿图里带着报告撰写节点, + 试跑只关心数对不对,不该为了一次试跑多花一次模型调用、也不该因为没有可用模型就判这份口径不行。 + + 不复用 trial_caliber:那里要求「已发布」,草稿本来就没发布。来源记 caliber_trial;起来之后先写一次 run_id, + 页面这时就能去看运行;轮询到终态或者等满 TRIAL_TIMEOUT_S,没跑完就照实答 running。 + """ + from app.engine.runner import run_manager + from app.ledger.derive import NotDerivable, caliber_probe, load_pinned + + card_id = next((n.get("id") for n in graph.get("nodes") or [] + if isinstance(n, dict) and n.get("type") == "metrics"), None) + if not card_id: + return {"run_id": "", "status": "failed", "error": "这份草稿没有口径卡,没有可试运行的指标"} + try: + async with SessionLocal() as read: + pinned = await load_pinned(read, workflow_id, 1, str(card_id)) + target = caliber_probe(pinned).graph + except NotDerivable as e: + return {"run_id": "", "status": "failed", "error": f"口径卡不能派生探针:{e.message}"} + + try: + run = await run_manager.start( + graph=target, input_payload=values, run_class="exploratory", origin_kind="caliber_trial", + origin={"kind": "caliber_trial", "draft_id": draft_id, "workflow_id": workflow_id, "version": 1, + "node_id": str(card_id)}, + started_by=started_by) + except Exception as e: # noqa: BLE001 - 试跑发起失败不该把已经生成的草稿弄没 + logger.exception("草稿 %s 的试运行没有发起", draft_id) + return {"run_id": "", "status": "failed", "error": f"试运行没有发起:{e}"} + await _save_trial(draft_id, {"run_id": run.id, "status": "running", "error": ""}) + row: Run | None = None + for _ in range(int(TRIAL_TIMEOUT_S / TRIAL_POLL_S)): + async with SessionLocal() as poll: + row = await poll.get(Run, run.id) + if row is None or row.status in TERMINAL_RUN_STATUSES: + break + await asyncio.sleep(TRIAL_POLL_S) + status = _run_status(row.status if row is not None else "running") + error = str(row.error or "") if row is not None and status == "failed" else "" + return {"run_id": run.id, "status": status, "error": error} + + +async def _trial_metrics(run_id: str) -> list[dict[str, Any]]: + """试跑运行里口径卡上的指标值:复用证据接口读封存的现成函数,不另写指标集解析。""" + from app.api.evidence import _sealed, _sealed_cards + + try: + sealed = await _sealed(run_id) + cards = {node_id: card for node_id, _, card in _sealed_cards(sealed)} + except Exception: # noqa: BLE001 - 证据读不出来就只给状态,不编造指标值 + logger.exception("试跑 %s 的指标值读不出来", run_id) + return [] + card = cards.get("card") or next(iter(cards.values()), None) + if not isinstance(card, dict): + return [] + return [{k: m.get(k) for k in ("id", "name", "rendered", "value") if m.get(k) is not None} + for m in card.get("metrics") or [] if isinstance(m, dict) and m.get("id")] def _draft_summary(draft: CaliberDraft) -> dict[str, Any]: @@ -466,12 +602,15 @@ def _doc_title(docs: list[Document]) -> str: async def _extract_in_background(draft_id: str) -> None: - """后台起草:读文档的段落、调一次模型、和已发布口径对齐,结果写回这一行。 + """后台起草:读文档的段落和数据目录、调一次模型、校验收成草稿图、建草稿工作流、再跑一次试跑。 - 用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。失败写进 error、状态留在 drafting—— - 草稿不是「被驳回」,人改完文档还能再来一次。 + 用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。没有数据源或没有表结构时起草必须失败——SQL 只能 + 对照真实目录写,没有目录就不让模型猜。个别指标不合格只丢那一条、写进 dropped / open_questions;SQL 本身不合格才整份 + 失败(图跑不了,留着也没有意义)。 """ - from app.ledger import docdraft + from app.core.artifact_store import graph_hash + from app.db.models import WorkflowVersion + from app.ledger import docdraft, draftplan async with SessionLocal() as session: draft = await session.get(CaliberDraft, draft_id) @@ -496,25 +635,69 @@ async def _extract_in_background(draft_id: str) -> None: chunk_ids.append(chunk.id) entries.append({"document_id": doc.id, "title": doc.title or doc.source or doc.id, "chunk_ids": chunk_ids}) - datasource = None - if draft.datasource_id: - source = await session.get(DataSource, draft.datasource_id) - if source is not None: - datasource = {"name": source.name, "type": source.kind, "description": source.description} + + source = await session.get(DataSource, draft.datasource_id) if draft.datasource_id else None + if source is None: + draft.error = "没有数据源:生成取数 SQL 必须对照数据目录里的表和列" + draft.status = "failed" + await session.commit() + return + tables_text, allowed_tables = await _schema_material(session, source) + if not allowed_tables: + draft.error = "这个数据源还没有表结构:先探查表结构,再起草口径" + draft.status = "failed" + await session.commit() + return + datasource = {"name": source.name, "type": source.kind, "description": source.description} + + guidance = str(origin.get("guidance") or "") + alignment: dict[str, list[Any]] = {"new": [], "duplicate": [], "conflict": []} try: - result = await docdraft.extract(session, docs=entries, chunks=chunks, - guidance=str(origin.get("guidance") or ""), datasource=datasource) + result = await draftplan.plan(session, docs=entries, chunks=chunks, guidance=guidance, + datasource=datasource, tables_text=tables_text) + plan, problems = draftplan.normalize_plan(result, chunks, allowed_tables=allowed_tables) + base = { + "documents": entries, "metrics": plan["metrics"], "entry_fields": plan["entry_fields"], + "sql": plan["sql"], "version": 1, + "trial": {"run_id": "", "status": "running", "error": ""}, + "dropped": problems, "truncated": result["truncated"], "model_id": result["model_id"], + } + if not plan["sql"] or not plan["metrics"]: + error = _problems_text(problems) or "模型没有给出可用的取数 SQL 和指标" + draft.payload = {**base, "trial": {"run_id": "", "status": "failed", "error": error}} + draft.model_id = result["model_id"] or None + draft.error = error + draft.status = "failed" + await session.commit() + return # 对齐要扫所有已发布口径:某一份读不出来不该让整份草稿失败,照实不做对齐(alignment 三个空列表) try: existing = await _published_metrics(session) except Exception: # noqa: BLE001 - 对齐是辅助信息,不是草稿本身 logger.exception("读已发布口径失败,草稿 %s 不做对齐", draft_id) existing = [] + alignment = docdraft.alignment(plan["metrics"], existing) + + plan["datasource"] = source.name + graph = draftplan.build_graph(plan, name=draft.title, + question=guidance or draft.title) + questions = list(plan["open_questions"]) + [ + f"{p['name']}:{p['reason']}" for p in problems + if p.get("name") not in ("sql", "metrics")] + workflow = Workflow( + name=(draft.title.strip() or "文档口径草稿")[:200], + description=(f"从业务文档起草的口径:{len(plan['metrics'])} 个指标,取数 SQL 由模型对照数据目录生成," + f"后台自动只读试运行;人工审改后按受管级别发布"), + graph=graph, status="draft", tags=["doc_draft"], + origin={"kind": "doc_draft", "draft_id": draft.id, "datasource_id": source.id, + "documents": [doc.id for doc in docs], "guidance": guidance}) + session.add(workflow) + await session.flush() + session.add(WorkflowVersion(workflow_id=workflow.id, version=1, graph=graph, + graph_hash=graph_hash(graph), note="从业务文档一次生成")) payload = { - "documents": entries, "metrics": result["metrics"], "dropped": result["dropped"], - "open_questions": result["open_questions"], - "alignment": docdraft.alignment(result["metrics"], existing), - "truncated": result["truncated"], "model_id": result["model_id"], + **base, "workflow_id": workflow.id, "open_questions": questions, + "alignment": alignment, } except docdraft.DraftUnavailable as e: draft.error = str(e) or "AI 起草不可用" @@ -528,14 +711,31 @@ async def _extract_in_background(draft_id: str) -> None: await session.commit() return draft.payload = payload + draft.workflow_id = workflow.id draft.model_id = result["model_id"] or None draft.error = None draft.status = _status_for(payload) await session.commit() + values = {field["name"]: field.get("default") for field in plan["entry_fields"] + if field.get("default") not in (None, "")} + + try: + trial = await _run_trial(draft_id=draft_id, workflow_id=workflow.id, graph=graph, values=values, + started_by=draft.created_by) + except Exception as e: # noqa: BLE001 - 试运行出错也要写进 payload,不能让界面停在「试运行中」 + logger.exception("草稿 %s 的试运行出错", draft_id) + trial = {"run_id": "", "status": "failed", "error": f"试运行出错:{e}"} + await _save_trial(draft_id, trial) + + +def _problems_text(problems: list[dict[str, Any]]) -> str: + """把校验问题拼成一句给人看的原因(接口的 error 只有一个字段)。""" + return ";".join(f"{p.get('name') or '问题'}:{p.get('reason') or ''}".strip(":") + for p in problems if p.get("reason"))[:2000] class DraftExtractIn(BaseModel): - """从哪几份文档起草、起草时给模型看的附加要求。数据源只用来写清适用范围,不给表结构。""" + """从哪几份文档起草、起草时给模型看的附加要求。数据源必须给:它的表结构和目录是 SQL 的唯一依据。""" documents: list[str] = Field(min_length=1, max_length=20) collection: str | None = Field(default=None, max_length=100) @@ -546,23 +746,29 @@ class DraftExtractIn(BaseModel): @router.post("/drafts/extract", status_code=201) async def draft_extract(payload: DraftExtractIn, background: BackgroundTasks, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: - """从业务文档起草一份口径(app/ledger/docdraft.py):先建一行 drafting 立刻返回,模型在后台跑。 + """从业务文档起草一份口径(app/ledger/draftplan.py):先建一行 drafting 立刻返回,模型在后台跑。 - 文档必须都存在(缺的回 422,一个草稿都不建);数据源给了也必须存在。草稿只产出定义,不产出取数,也不写进 - workflows.graph——path_pending 不是合法的图。抽取完的 payload / status 用 GET 看。""" + 文档必须都存在(缺的回 422,一个草稿都不建);数据源必须给、必须存在,而且已经探查到表结构——SQL 只能对照真实目录 + 写,没有目录时让模型猜表,图跑不了。模型产出定义 + SQL + 入口字段后由服务端校验收成草稿图和 v1,后台自动只读试跑。 + 起草完的 payload / status / trial 用 GET 看。""" from app.api.deps import current_principal, ensure_role ensure_role("builder") doc_ids = list(dict.fromkeys(str(d) for d in payload.documents if str(d).strip())) if not doc_ids: raise HTTPException(422, "至少要给一份文档") + if not payload.datasource_id: + raise HTTPException(422, "生成取数 SQL 需要数据源:请选一个已经探查过表结构的数据源") found = {doc.id: doc for doc in (await session.execute( select(Document).where(Document.id.in_(doc_ids)))).scalars()} missing = [doc_id for doc_id in doc_ids if doc_id not in found] if missing: raise HTTPException(422, f"文档不存在,可能已被删除:{'、'.join(missing)}") - if payload.datasource_id and await session.get(DataSource, payload.datasource_id) is None: + source = await session.get(DataSource, payload.datasource_id) + if source is None: raise HTTPException(422, "数据源不存在,可能已被删除") + if not _source_tables(source): + raise HTTPException(422, "这个数据源还没有表结构:先探查表结构,再起草口径") docs = [found[doc_id] for doc_id in doc_ids] draft = CaliberDraft(title=_doc_title(docs), collection=payload.collection or (docs[0].collection or "default"), @@ -576,8 +782,8 @@ async def draft_extract(payload: DraftExtractIn, background: BackgroundTasks, @router.get("/drafts") -async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / questions_open / " - "path_pending / attached / rejected / failed"), +async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / ready / " + "questions_open / path_pending / attached / rejected / failed"), session: AsyncSession = Depends(get_session)) -> dict[str, Any]: """口径草稿列表,最近改过的在前。只给计数和状态,正文用 GET /api/ledger/drafts/{id} 看。""" from app.api.deps import ensure_role @@ -595,13 +801,38 @@ async def list_drafts(status: str | None = Query(default=None, description="按 @router.get("/drafts/{draft_id}") async def get_draft(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: - """一份草稿的完整内容:指标(含引用和 span)、丢弃原因、未决问题、和已发布口径的对齐结果、关联工作流名。""" + """一份草稿的完整内容:指标(含引用和 span)、取数 SQL、入口字段、试跑状态、丢弃原因、未决问题、和已发布口径的对齐 + 结果、关联工作流名。""" from app.api.deps import ensure_role ensure_role("builder") return await _draft_view(session, await _draft_or_404(session, draft_id)) +@router.get("/drafts/{draft_id}/trial") +async def get_draft_trial(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]: + """这份草稿的试跑:{run_id, status, metrics: [{id, name, rendered, value}], error}。 + + 状态只有 succeeded / failed / running 三种;指标值读试跑运行封存的口径卡(和口径试跑同一个读法)。还没试跑(老草稿、 + 起草失败)回 404。只读,不发起运行。""" + from app.api.deps import ensure_role + + ensure_role("builder") + draft = await _draft_or_404(session, draft_id) + payload = draft.payload if isinstance(draft.payload, dict) else {} + trial = payload.get("trial") if isinstance(payload.get("trial"), dict) else {} + run_id = trial.get("run_id") + if not isinstance(run_id, str) or not run_id: + raise HTTPException(404, "这份草稿还没有试运行") + run = await session.get(Run, run_id) + if run is None: + return {"run_id": run_id, "status": _run_status(trial.get("status")), "metrics": [], + "error": str(trial.get("error") or "")} + status = _run_status(run.status) + metrics = await _trial_metrics(run.id) if status == "succeeded" else [] + return {"run_id": run.id, "status": status, "metrics": metrics, "error": str(run.error or "")} + + def _check_metrics(metrics: Any) -> list[dict[str, Any]]: """PATCH 换指标时只做结构校验(不重跑引用核对:引用是模型交的,人改过的段落没法再逐字对一遍)。""" if not isinstance(metrics, list): @@ -633,8 +864,8 @@ class DraftPatchIn(BaseModel): async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSession = Depends(get_session) ) -> dict[str, Any]: """改一份草稿:metrics 整体替换(只做结构校验,不重跑引用核对);resolved 里的问题从跨指标和各指标的问题里删掉。 - 据此重算状态(还有问题 → questions_open,否则 path_pending)。已经 attach 或驳回的草稿不改状态——那时它说的 - 已经不是一份草稿了。""" + 据此重算状态(还有问题 → questions_open,否则有图 → ready、没有图的老草稿 → path_pending)。已经 attach 或驳回的 + 草稿不改状态——那时它说的已经不是一份草稿了。""" from app.api.deps import ensure_role ensure_role("builder") @@ -663,7 +894,7 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio metrics = payload_data.get("metrics") # 起草失败的草稿补上真指标后要能往前走;没有指标时不重算,免得空草稿被当成「待接数据路径」 if isinstance(metrics, list) and metrics and draft.status in ("drafting", "questions_open", - "path_pending", "failed"): + "path_pending", "ready", "failed"): draft.status = _status_for(payload_data) await session.commit() return await _draft_view(session, draft) diff --git a/backend/app/db/models.py b/backend/app/db/models.py index f9b76c0b..0681990d 100644 --- a/backend/app/db/models.py +++ b/backend/app/db/models.py @@ -1094,12 +1094,12 @@ class WebhookDelivery(Base): class CaliberDraft(Base, TimestampMixin): - """从业务文档起草的一份口径(app/ledger/docdraft.py 的产出)。 + """从业务文档起草的一份口径(app/ledger/draftplan.py 的产出)。 - 草稿在 path_pending 下没有取数路径,不是合法图(validate_graph 会挡),所以不写进 workflows.graph:另存一行, - 等 attach(app/ledger/docattach.py)按一次真实运行补上取数路径、人审过再进版本。payload 的形状见 - docdraft.extract 的返回(documents / metrics / dropped / open_questions / alignment / truncated / model_id), - origin 记这一份草稿从哪些文档、用哪句话问出来的,attach 之后工作流 id 记在 workflow_id 上。 + 主路径一次到位:模型读文档和数据目录,产出定义 + 取数 SQL + 入口字段 + 指标表达式;服务端校验收成草稿图,建一个 + status="draft" 的工作流和 v1,后台自动只读试跑。payload 的形状见接口契约(documents / metrics / entry_fields / sql / + workflow_id / version / trial / open_questions / alignment / dropped / truncated / model_id),这张草稿对应的工作流 id + 记在 workflow_id 上。attach(app/ledger/docattach.py)保留为辅助入口:已经有跑对的答案时让它认这份定义。 """ __tablename__ = "caliber_drafts" @@ -1107,11 +1107,11 @@ class CaliberDraft(Base, TimestampMixin): id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) title: Mapped[str] = mapped_column(String(200), default="") collection: Mapped[str] = mapped_column(String(100), default="default") - # 起草时给模型看的数据源(只给名字和类型,用来写清适用范围);源删了草稿照旧在,只丢这一条线索 + # 起草时给模型看的数据源:表结构和数据目录是取数 SQL 的唯一依据;源删了草稿照旧在,只丢这一条线索 datasource_id: Mapped[str | None] = mapped_column( ForeignKey("data_sources.id", ondelete="SET NULL"), default=None ) - # 同 docdraft.STATUSES:drafting | questions_open | path_pending | attached | rejected + # 同 docdraft.STATUSES:drafting | ready | questions_open | path_pending | attached | rejected | failed status: Mapped[str] = mapped_column(String(20), default="drafting", index=True) payload: Mapped[dict[str, Any]] = mapped_column(default=dict) # 这份草稿从哪来:{"documents": [文档 id], "guidance": 用户补充要求} diff --git a/backend/app/ledger/docdraft.py b/backend/app/ledger/docdraft.py index 7d070dbd..3c5879dd 100644 --- a/backend/app/ledger/docdraft.py +++ b/backend/app/ledger/docdraft.py @@ -1,12 +1,12 @@ -"""业务文档 → 口径草稿:只产出定义,不产出取数(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)。 +"""业务文档 → 口径草稿的定义抽取,以及草稿共用的引用核对、对齐和合并(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)。 -**为什么草稿只到定义为止。** 文档里写的是业务说法(名称、同义词、粒度、时间字段、过滤、分子分母、维度),不是库里的 -表、列和 SQL。取数必须来自一次真实运行:运行里执行过什么、结果对不对,只有运行本身能证明。所以这个模块的产出固定为 -定义卡需要的那几项,模型回复里一旦出现 SQL / 表名 / 列名字段,整条指标丢弃,不带着它往下走。 +**这条抽取路径只产出定义。** 主路径(定义 + 取数 SQL 一次到位)在 ledger/draftplan.py:那边读数据目录、由模型写 SQL、 +服务端建图并试跑。这里的 extract 仍然只抽定义,留给「已经有跑对的答案,让它认这份定义」的辅助路径(docattach);引用核对、 +对齐、合并定义这些规则两边共用,所以留在这个模块。 -**为什么草稿不写成图。** path_pending 的草稿还没有取数路径,不是合法图(validate_graph 会挡),写进 workflows.graph -只会让工作流列表和画布读到一个跑不了的版本。草稿先独立存在,等取数路径有了、人审过了再进版本。这个模块因此不碰 -数据库:纯逻辑 + 一次模型调用,调用方拿到结果自己决定存哪里。 +**为什么这个模块不写成图。** 它只负责把原文里的业务说法抽成定义卡需要的那几项:不碰取数、不碰数据库,纯逻辑加一次模型 +调用,调用方拿到结果自己决定存哪里。建图(取数 SQL → start / fetch / card / write / out)在 draftplan.build_graph, +docattach 接上运行的那一路用的是 certify.build_graph。 **为什么引用要逐字核对。** 「文档里说过」是这份草稿唯一的事实来源。模型转述得再像,也要能在原文里按归一化空白 (换行、制表、全角空格)定位到那一句;定位不到就不算引用。span 是原文下标,界面据此高亮,也是之后复核的依据。 @@ -21,9 +21,11 @@ import re from collections.abc import Iterable, Mapping from typing import Any -#: 草稿的状态。path_pending 不是合法图,attached 之后取数路径才来自一次真实运行。 -#: failed 是起草这一步没跑成(没有可用模型、模型回复读不懂),和 rejected(人判它不是口径)不是一回事。 -STATUSES = ("drafting", "questions_open", "path_pending", "attached", "rejected", "failed") +#: 草稿的状态。ready 是主路径的常态:图已生成(含取数 SQL)、没有未决问题、可试跑可签字发布;questions_open 有图也有数, +#: 只是问题还没清完(不阻断试跑);path_pending 只留给这次改版之前起草、还没有取数路径的老草稿;attached 是经辅助入口接上 +#: 一次真实运行之后的。failed 是起草这一步没跑成(没有可用模型、模型回复读不懂、SQL 不合格),和 rejected(人判它不是口径) +#: 不是一回事。 +STATUSES = ("drafting", "ready", "questions_open", "path_pending", "attached", "rejected", "failed") #: 一次发给模型的总字数上限(按 chunk 边界截断,见 extract) MAX_INPUT_CHARS = 40000 diff --git a/backend/app/ledger/draftplan.py b/backend/app/ledger/draftplan.py new file mode 100644 index 00000000..b0e49731 --- /dev/null +++ b/backend/app/ledger/draftplan.py @@ -0,0 +1,450 @@ +"""业务文档 + 数据目录 → 一份一次到位的口径草稿:定义、取数 SQL、入口字段、指标表达式(docs/design 做法 8 的主路径)。 + +**为什么这次要模型写 SQL。** 文档里只有业务说法,没有表名。但只抽定义,人还得自己去问一次数、再把运行 id 接回来,等于把 +「口径怎么写」拆成两段,谁都说不清草稿什么时候算数。主路径改成一次产出可试跑的图:模型读文档、对照数据目录写一条只读 +SELECT,服务端把 SQL、入口字段、口径卡、报告串成图,后台跑一次,草稿页直接给「定义 + 数 + 原文引用」。 + +**为什么目录是唯一依据。** 文档里没有表名列名,模型只能从调用方给的目录里挑。所以没有数据源、或数据源还没探查表结构时, +调用方必须拒收(api/ledger 的 422):让模型凭空猜表,猜出来的图跑不了,还不如不做。normalize_plan 再核对一遍 SQL 里出现的 +表都在目录里,防止模型从示例、同义词里编出表名。 + +**为什么 SQL 只收单条只读 SELECT。** 草稿会在后台自动跑一次。多语句、DML/DDL、注释后藏的第二条都可能在试跑时改库; +这里按 sqlglot 解析后的语句数判定,不靠字符串里有没有分号(字符串字面量里的分号不算)。注释里的第二条照样会被解析成 +第二条语句,所以也拒。 + +**为什么表达式必须是 cell(nodes.fetch, 0, '列名')。** 试跑和之后按口径出具都从口径卡读值。取数节点固定叫 fetch(见 +build_graph),单行结果取第 0 行的某一列;写成别的样子,卡上就没有值,图能建但出不了数。 + +**为什么引用核对还是照 docdraft 的老规矩。** 定义的事实来源还是文档原文。模型转述得再像,也要能在原文里逐字定位;一条 +引用都核不上的指标整条丢弃,写进 problems 交给人看。这里只做校验,不改 docdraft 的规则。 + +**为什么不落库、不导 app.api。** 这个模块是纯逻辑加一次模型调用:从哪读文档、允许哪些表、结果存成什么,都由调用方决定。 +测试注入假模型,不会发真实请求。 +""" +from __future__ import annotations + +import re +from collections.abc import Mapping +from typing import Any + +from app.ledger import docdraft + +#: 一次发给模型的材料上限(按 chunk 边界截断;表目录先截到这个数以内) +MAX_INPUT_CHARS = docdraft.MAX_INPUT_CHARS +MAX_TABLES_CHARS = 24000 +#: 取数 SQL 的长度上限(字符)。再长的查询不是草稿该承载的 +MAX_SQL_CHARS = 20000 + +#: 入口字段能写的类型(apps/spec.FORM_TYPES 的子集;日期用 string + description 说清) +ENTRY_TYPES = ("string", "number", "integer", "boolean") +#: 指标里固定出现的字段(顺序照接口契约) +METRIC_FIELDS = ("id", "name", "synonyms", "unit", "decimals", "expression", "definition", "open_questions") + +#: SQL 模板里的入口占位符:{{ input.x }}(引号内外都认) +_INPUT = re.compile(r"\{\{\s*input\.([A-Za-z_][\w-]*)\s*\}\}") +#: 口径卡的取值表达式,列名可以用单引号或双引号 +_EXPRESSION = re.compile(r"^cell\(\s*nodes\.fetch\s*,\s*0\s*,\s*['\"]([^'\"]+)['\"]\s*\)$") +#: 只读查询的根节点:普通 SELECT,或各分支都是 SELECT 的 UNION +_WRITE_NODES = ("Insert", "Update", "Delete", "Create", "Drop", "Alter", "Merge", "TruncateTable", "Command") + +_SYSTEM = """你是业务口径与取数模板的起草助手。读给定的业务文档和数据目录,一次产出一份可试跑的口径。 + +硬性约束: +1. 只输出一个 JSON 对象,不要写解释,不要写 Markdown 代码块之外的话。 +2. sql 是取数模板,只能是**一条只读 SELECT**:不要多语句、不要 INSERT/UPDATE/DELETE/DDL,也不要在注释后面再藏一条。 + 表和列只能来自「数据目录」,表名、列名照抄,不许猜、不许编。 +3. sql 里需要按入口筛选时写 '{{ input.字段名 }}'(字符串)或 {{ input.字段名 }}(数),并在 entry_fields 里声明同名 + 字段;不要把日期、门店之类的字面量写死。 +4. 每条指标都要有 expression,固定写成 cell(nodes.fetch, 0, '列名'),列名是 sql 最外层 SELECT 的输出列名。 +5. 每条指标的定义必须带 citations:引用逐字抄原文,chunk 写材料里方括号内的 id。核对不上、或原文里没有依据的定义 + 不要写进指标,写进 open_questions。 +6. 拿不准的不要猜,写进 open_questions,用一句问得清的话。不要编造文档里没有的数字、单位、生效日期。 + +输出格式: +{ + "entry_fields": [ + {"name": "start", "type": "string", "required": true, "default": "", "description": "开始日期,格式 YYYY-MM-DD"} + ], + "sql": "SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.start }}'", + "metrics": [ + { + "id": "m1", + "name": "指标名称", + "synonyms": ["同义词"], + "unit": "单位(文档没写就留空)", + "decimals": 2, + "expression": "cell(nodes.fetch, 0, 'gmv')", + "definition": { + "text": "口径说明", + "scope": "适用范围", + "exclusions": ["不包含的情况"], + "owner": "文档写明的负责人或部门", + "effective_from": "生效日期(文档原文写法)", + "citations": [{"chunk": "c1", "quote": "逐字原文"}] + }, + "open_questions": ["还没说清、需要业务确认的问题"] + } + ], + "open_questions": ["跨指标、以及整条 SQL 还没把握的问题"] +} +""" + + +def _collapse(text: str) -> str: + return re.sub(r"\s+", " ", text).strip() + + +def _order(chunks: Mapping[str, dict]) -> list[str]: + def key(chunk_id: str) -> tuple[int, str]: + chunk = chunks[chunk_id] if isinstance(chunks[chunk_id], Mapping) else {} + ordinal = chunk.get("ordinal") + return (ordinal if isinstance(ordinal, int) else 0, chunk_id) + + return sorted(chunks, key=key) + + +def _doc_line(doc: Any) -> str: + if not isinstance(doc, Mapping): + return str(doc) + doc_id = doc.get("document_id") or doc.get("id") or "" + title = doc.get("title") or doc.get("filename") or doc.get("name") or doc_id + return f"- {doc_id}:{title}" + + +def _chunk_block(chunk_id: str, chunk: Any) -> str: + chunk = chunk if isinstance(chunk, Mapping) else {} + ordinal = chunk.get("ordinal") + where = f" · 第 {ordinal} 段" if isinstance(ordinal, int) else "" + document = chunk.get("document_id") or "" + return f"[{chunk_id}](文档 {document}{where})\n{chunk.get('content') or ''}" + + +def _human(docs: list[dict], chunks: Mapping[str, dict], guidance: str, datasource: dict | None, + tables_text: str) -> str: + parts = ["文档清单:", *(_doc_line(doc) for doc in docs), "", + "逐段原文(引用时 chunk 写方括号里的 id,quote 逐字抄):"] + parts.extend(_chunk_block(chunk_id, chunks[chunk_id]) for chunk_id in _order(chunks)) + parts.append("") + if datasource: + bits = [str(datasource.get(key)) for key in ("name", "type", "dialect", "description") + if datasource.get(key)] + parts.append("数据源:{}".format(" · ".join(bits))) + parts.append("数据目录(sql 只能用这里的表和列,表名列名照抄):") + parts.append(tables_text.strip() or "(没有给出表结构,不能写 sql)") + parts.append("") + parts.append("用户补充要求:{}".format(guidance.strip() if guidance and guidance.strip() else "(无)")) + return "\n".join(parts) + + +def prompt(docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None, + tables_text: str = "") -> list[Any]: + """构造 system + human:文档原文 + 数据目录。目录是 sql 的唯一依据,和原文一样原样交给模型。""" + from langchain_core.messages import HumanMessage, SystemMessage + + return [SystemMessage(content=_SYSTEM), + HumanMessage(content=_human(docs, chunks, guidance, datasource, tables_text))] + + +def _chars(messages: list[Any]) -> int: + return sum(len(str(getattr(message, "content", "") or "")) for message in messages) + + +def _fit(docs: list[dict], chunks: dict[str, dict], guidance: str, + datasource: dict | None, tables_text: str) -> tuple[dict[str, dict], str, bool]: + """把材料压到 MAX_INPUT_CHARS 以内:先截表目录尾部,再从后往前按 chunk 边界丢,最后截仅剩的那一段。 + + 表目录先截:SQL 必须写在目录里的表上,目录比文档的细枝末节更硬;被截掉的是表详情,表名索引还在最前面。 + """ + kept = dict(chunks) + tables = tables_text + truncated = False + if len(tables) > MAX_TABLES_CHARS: + tables = tables[:MAX_TABLES_CHARS] + truncated = True + + def size() -> int: + return _chars(prompt(docs, kept, guidance, datasource, tables)) + + order = _order(kept) + while size() > MAX_INPUT_CHARS and len(order) > 1: + kept.pop(order.pop()) + truncated = True + if size() > MAX_INPUT_CHARS and order: + chunk_id = order[0] + chunk = dict(kept[chunk_id]) if isinstance(kept[chunk_id], Mapping) else {} + content = str(chunk.get("content") or "") + excess = size() - MAX_INPUT_CHARS + chunk["content"] = content[:max(0, len(content) - excess)] + kept[chunk_id] = chunk + truncated = True + if size() > MAX_INPUT_CHARS: + excess = size() - MAX_INPUT_CHARS + tables = tables[:max(0, len(tables) - excess)] + truncated = True + return kept, tables, truncated + + +async def plan(session: Any, *, docs: list[dict], chunks: dict[str, dict], guidance: str = "", + datasource: dict | None = None, tables_text: str = "", model: Any = None) -> dict: + """一次模型调用,返回 {entry_fields, sql, metrics, open_questions, model_id, truncated}(未校验)。 + + 不落库。model 可注入(测试用假对象:有 async ainvoke(messages),回复有 .content);不给就按设置解析,模型不可用时抛 + docdraft.DraftUnavailable。SQL 的对错、引用能不能核对,交给 normalize_plan。 + """ + from app.engine.state import message_text + + if model is None: + from app.data.recipe_ai import resolve_draft_model + + model, model_id, availability = await resolve_draft_model(session) + if model is None or not getattr(availability, "available", False): + raise docdraft.DraftUnavailable(getattr(availability, "reason", "") or "AI 起草不可用") + else: + named = getattr(model, "model_name", None) or getattr(model, "model", None) + model_id = named if isinstance(named, str) else "" + + kept, tables, truncated = _fit(docs, chunks, guidance, datasource, tables_text) + reply = await model.ainvoke(prompt(docs, kept, guidance, datasource, tables)) + data = docdraft.parse_reply(message_text(reply)) + metrics = data.get("metrics") + questions = data.get("open_questions") + return { + "entry_fields": data.get("entry_fields") if isinstance(data.get("entry_fields"), list) else [], + "sql": data.get("sql") if isinstance(data.get("sql"), str) else "", + "metrics": metrics if isinstance(metrics, list) else [], + "open_questions": [q for q in questions if isinstance(q, str) and q.strip()] + if isinstance(questions, list) else [], + "model_id": model_id, + "truncated": truncated, + } + + +# ========================================================================== +# 校验 +# ========================================================================== + + +def _entry_fields(value: Any, problems: list[dict]) -> list[dict]: + """入口字段归一化:名字必填、不重名;类型落回能认的几种,认不出的按文字。""" + out: list[dict] = [] + seen: set[str] = set() + for position, item in enumerate(value if isinstance(value, list) else [], start=1): + if not isinstance(item, Mapping): + problems.append({"name": f"第 {position} 个入口字段", "reason": "不是一个对象"}) + continue + name = item.get("name") + if not isinstance(name, str) or not name.strip(): + problems.append({"name": f"第 {position} 个入口字段", "reason": "缺少字段名"}) + continue + name = name.strip() + if name in seen: + problems.append({"name": name, "reason": "入口字段重名"}) + continue + seen.add(name) + kind = item.get("type") + if kind not in ENTRY_TYPES: + kind = "string" + default = item.get("default") + if not isinstance(default, (str, int, float, bool)): + default = None + description = item.get("description") + out.append({"name": name, "type": kind, "required": bool(item.get("required")), + "default": default, + "description": description.strip() if isinstance(description, str) else ""}) + return out + + +def _sql_problem(sql: str, allowed_tables: set[str]) -> str | None: + """单条只读 SELECT、表都在目录里;不满足时返回一句给人看的原因。""" + if len(sql) > MAX_SQL_CHARS: + return f"SQL 超过 {MAX_SQL_CHARS} 字,草稿不承载这么长的查询" + body = _INPUT.sub("?", sql) + try: + import sqlglot + from sqlglot import exp + except ImportError: # pragma: no cover - sqlglot 是现有依赖,装不上时照实拒 + return "没有 SQL 解析器,不能校验这条查询" + try: + statements = [item for item in sqlglot.parse(body) if item is not None] + except Exception as e: # noqa: BLE001 - 语法错、方言特性:都按解析不了 + return f"SQL 解析不了:{e}" + if len(statements) != 1: + return "只能是一条语句:多语句、或注释后藏着第二条语句的,一律不收" + tree = statements[0] + if not isinstance(tree, (exp.Select, exp.Union)): + return "只能是只读 SELECT" + if isinstance(tree, exp.Union) and not all(isinstance(part, exp.Select) for part in tree.find_all(exp.Select)): + return "只能是只读 SELECT" + if any(tree.find(getattr(exp, name)) is not None for name in _WRITE_NODES): + return "只能是只读 SELECT,不能有写操作或建表、删表这类语句" + if isinstance(tree, exp.Select) and tree.args.get("into"): + return "只能是只读 SELECT,不能把结果写进另一张表" + cte_names = {str(cte.alias or "").casefold() for cte in tree.find_all(exp.CTE)} + allowed = {str(name).casefold() for name in allowed_tables} + used: list[str] = [] + for table in tree.find_all(exp.Table): + name = str(table.name or "") + short = name.rsplit(".", 1)[-1] + if not name or name.casefold() in cte_names or short.casefold() in cte_names: + continue + db = str(table.db or "") + keys = {name.casefold(), short.casefold()} + if db: + keys.add(f"{db}.{name}".casefold()) + if not (keys & allowed): + used.append(name) + if used: + return f"SQL 用了数据目录里没有的表:{'、'.join(dict.fromkeys(used))}" + if not any(True for table in tree.find_all(exp.Table) + if str(table.name or "").casefold() not in cte_names): + return "SQL 没有引用任何表:请对照数据目录写取数" + return None + + +def _metric(item: Mapping, position: int, problems: list[dict]) -> dict | None: + """一条已经过 docdraft 引用核对的指标:再查 expression,归一成契约里的字段。""" + name = str(item.get("name") or "").strip() + expression = item.get("expression") + if not isinstance(expression, str) or not _EXPRESSION.match(expression.strip()): + problems.append({"name": name or f"第 {position} 条", + "reason": "expression 必须是 cell(nodes.fetch, 0, '列名'),列名用 sql 的输出列名"}) + return None + definition = item.get("definition") if isinstance(item.get("definition"), Mapping) else {} + citations = definition.get("citations") if isinstance(definition.get("citations"), list) else [] + decimals = item.get("decimals") + if isinstance(decimals, bool) or not isinstance(decimals, int): + decimals = None + synonyms = item.get("synonyms") + questions = item.get("open_questions") + return { + "id": str(item.get("id") or "").strip(), + "name": name, + "synonyms": [s.strip() for s in synonyms if isinstance(s, str) and s.strip()] + if isinstance(synonyms, list) else [], + "unit": item.get("unit") if isinstance(item.get("unit"), str) else "", + "decimals": decimals, + "expression": expression.strip(), + "definition": { + "text": definition.get("text") if isinstance(definition.get("text"), str) else "", + "scope": definition.get("scope") if isinstance(definition.get("scope"), str) else "", + "exclusions": [str(v) for v in definition.get("exclusions") or [] if isinstance(v, str)] + if isinstance(definition.get("exclusions"), list) else [], + "owner": definition.get("owner") if isinstance(definition.get("owner"), str) else "", + "effective_from": definition.get("effective_from") + if isinstance(definition.get("effective_from"), str) else "", + "citations": citations, + }, + "open_questions": [q for q in questions if isinstance(q, str) and q.strip()] + if isinstance(questions, list) else [], + } + + +def normalize_plan(raw: Any, chunks: Mapping[str, dict], *, allowed_tables: set[str]) -> tuple[dict, list[dict]]: + """校验模型交回的草案。返回 (可落库的 plan, problems)。 + + problems 的形状是 {"name": …, "reason": …},name 能认出是哪一条就用名字,认不出按序号说。硬规则:SQL 单条只读、表都在 + 目录里;每条指标的 expression 是 cell(nodes.fetch, 0, '列名');至少一条引用能在原文里逐字核对上(复用 + docdraft.normalize_metrics 的核对)。个别指标不合格只丢那一条,problems 里写清为什么;SQL 不合格时 plan["sql"] 为空, + 由调用方决定整份草稿算失败。 + """ + body = raw if isinstance(raw, Mapping) else {} + problems: list[dict] = [] + entry_fields = _entry_fields(body.get("entry_fields"), problems) + + sql = body.get("sql") + sql_text = sql.strip() if isinstance(sql, str) else "" + if not sql_text: + problems.append({"name": "sql", "reason": "没有给出取数 SQL"}) + else: + reason = _sql_problem(sql_text, allowed_tables) + if reason: + problems.append({"name": "sql", "reason": reason}) + sql_text = "" + else: + declared = {field["name"] for field in entry_fields} + missing = sorted(set(_INPUT.findall(sql_text)) - declared) + if missing: + problems.append({"name": "sql", + "reason": f"SQL 用了没有声明的入口字段:{'、'.join(missing)}"}) + sql_text = "" + + checked, dropped = docdraft.normalize_metrics(body.get("metrics"), dict(chunks)) + problems.extend(dropped) + metrics: list[dict] = [] + seen_ids: set[str] = set() + for position, item in enumerate(checked, start=1): + metric = _metric(item, position, problems) + if metric is None: + continue + if not metric["id"] or metric["id"] in seen_ids: + metric["id"] = f"m{len(metrics) + 1}" + while metric["id"] in seen_ids: + metric["id"] += "_" + seen_ids.add(metric["id"]) + metrics.append(metric) + if not metrics: + problems.append({"name": "metrics", "reason": "没有一条指标通过校验"}) + + questions = body.get("open_questions") + plan_out = { + "entry_fields": entry_fields, + "sql": sql_text, + "metrics": metrics, + "open_questions": [q.strip() for q in questions if isinstance(q, str) and q.strip()] + if isinstance(questions, list) else [], + } + return plan_out, problems + + +# ========================================================================== +# 建图(确定性,和 certify.build_graph 同一个形状) +# ========================================================================== + + +def build_graph(plan: dict, *, name: str, question: str = "") -> dict: + """草案 → 草稿图:start(input) → fetch(tool) → card(metrics) → write(report) → out(output),过 auto_layout。 + + plan["datasource"] 是取数节点指向的数据源名(调用方按这次的数据源补,不采信模型回复里的名字)。调用两次结果逐字一致: + 节点 id、坐标都由输入决定,没有时间戳。报告配置、出口契约照 certify.build_graph 的写法,发布门禁认的就是这一套 + (REPORT_POLICY、metrics_from、required)。 + """ + from app.engine.governance import REPORT_POLICY + from app.engine.layout import auto_layout + from app.engine.schema import GraphSpec + from app.ledger.certify import REPORT_INSTRUCTIONS, REPORT_INSTRUCTIONS_PARAMS + from app.tools.datasource import QUERY_PREFIX + + fields = [dict(f) for f in plan.get("entry_fields") or []] + metrics = [dict(m) for m in plan.get("metrics") or []] + source = str(plan.get("datasource") or "") + report_cfg: dict[str, Any] = {} + if fields: + report_cfg["instructions"] = REPORT_INSTRUCTIONS_PARAMS.format( + params=",".join(f"{f['name']} = {{{{ input.{f['name']} }}}}" for f in fields)) + else: + report_cfg["instructions"] = REPORT_INSTRUCTIONS.format(question=question or name or "(问题)") + report_cfg.update({key: value for key, value, _ in REPORT_POLICY}) + report_cfg["metrics_from"] = ["card"] + contract: dict[str, Any] = {"report_from": "write", "metrics_from": "card", + "required": [m["id"] for m in metrics]} + chain = [ + {"id": "start", "type": "input", "position": {"x": 0, "y": 0}, + "data": {"label": "入口", "config": {"fields": fields}}}, + {"id": "fetch", "type": "tool", "position": {"x": 0, "y": 0}, + "data": {"label": "取数", "config": {"tool": f"{QUERY_PREFIX}{source}", + "args": {"sql": str(plan.get("sql") or "")}}}}, + {"id": "card", "type": "metrics", "position": {"x": 0, "y": 0}, + "data": {"label": "口径卡", "config": {"caliber": (name.strip() or question or "口径")[:40], + "caliber_version": "v1", "metrics": metrics}}}, + {"id": "write", "type": "report", "position": {"x": 0, "y": 0}, + "data": {"label": "报告", "config": report_cfg}}, + {"id": "out", "type": "output", "position": {"x": 0, "y": 0}, + "data": {"label": "出口", "config": {"fields": [{"name": "报告", "value": "{{ nodes.write.text }}"}], + "contract": contract}}}, + ] + edges = [{"source": a["id"], "target": b["id"]} for a, b in zip(chain, chain[1:])] + return auto_layout(GraphSpec.model_validate({"nodes": chain, "edges": edges})).model_dump(mode="json") + + +__all__ = ["ENTRY_TYPES", "MAX_INPUT_CHARS", "MAX_SQL_CHARS", "MAX_TABLES_CHARS", "METRIC_FIELDS", + "build_graph", "normalize_plan", "plan", "prompt"] diff --git a/backend/tests/test_ledger_docdraft_api.py b/backend/tests/test_ledger_docdraft_api.py index c203c532..f90bab31 100644 --- a/backend/tests/test_ledger_docdraft_api.py +++ b/backend/tests/test_ledger_docdraft_api.py @@ -1,47 +1,87 @@ -"""从业务文档起草口径(app/ledger/docdraft.py,/api/ledger/drafts…):草稿独立于工作流存在。 +"""从业务文档起草口径(app/ledger/draftplan.py + /api/ledger/drafts…):一次产出定义、SQL、入口和图。 -- 抽取先建一行 drafting、在后台跑模型,结果写回 payload;缺文档 422、一个草稿都不建; -- 草稿只产出定义:payload 里是 metrics / dropped / open_questions / alignment,没有 SQL; -- PATCH 整体换指标、消掉已答清的问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排。 +- 抽取先建一行 drafting、在后台跑模型;结果写成草稿:payload 里有 metrics / sql / entry_fields / trial,工作流和 v1 已建; +- 没有数据源、或数据源没有表结构时 422,一个草稿都不建;SQL 对照不上目录时草稿 failed; +- 有未决问题 → questions_open(图和试跑照样有),没有 → ready; +- PATCH 换指标 / 消问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排; +- GET /drafts/{id}/trial 交回契约里的形状。 -模型一律 monkeypatch 掉(docdraft.extract 换成一个固定结果),测试不发真实请求。 +模型一律注入假模型(monkeypatch resolve_draft_model),试跑也换成假的(不启动引擎),测试不发真实请求。 """ from __future__ import annotations import copy +import json import sys import types +import uuid import pytest from httpx import ASGITransport, AsyncClient from sqlalchemy import delete, select +from app.api import ledger as api_ledger +from app.data import recipe_ai from app.db.base import SessionLocal -from app.db.models import AuditEvent, CaliberDraft, Chunk, Document, Workflow -from app.ledger import docdraft +from app.db.models import (AuditEvent, CaliberDraft, Chunk, DataSource, Document, Run, Workflow, + WorkflowVersion) +from app.engine.schema import GraphSpec, validate_graph from app.main import app -METRIC = { - "name": "已支付退款率", - "synonyms": ["退款率"], - "unit": "%", - "grain": "日", - "time_field": "支付时间", - "filters": ["只算已支付"], - "numerator": "已支付后退款的订单数", - "denominator": "已支付订单数", - "dimensions": ["门店"], - "definition": {"text": "已支付订单里发生退款的比例", "scope": "全部门店", "exclusions": [], "owner": "运营", - "effective_from": "2026-01-01", - "citations": [{"chunk": "c1", "document_id": "d1", "span": [0, 2], "quote": "退款率"}]}, - "open_questions": ["退款算不算已支付当天的"], -} +#: 真实的试跑实现:autouse 的 fake_trial 会把它换掉,这一个用例换回来跑真引擎 +REAL_RUN_TRIAL = api_ledger._run_trial + +#: 文档原文:两段,退款率的事实来源 +CHUNK_ONE = "退款率 = 已支付后退款的订单数 / 已支付订单数" +CHUNK_TWO = "退款率按门店拆,只算已支付的订单" -def result(metrics=None, questions=None, model_id="fake-model"): - return {"metrics": copy.deepcopy(metrics if metrics is not None else [METRIC]), - "dropped": [{"name": "第 2 条", "reason": "没有一条引用能在原文里逐字核对上"}], - "open_questions": list(questions or []), "truncated": False, "model_id": model_id} +def plan_reply(chunk_id: str, *, questions=None, sql: str | None = None, metrics=None) -> str: + """模型回复:一条指标,引用逐字抄原文。""" + metric = { + "id": "m1", "name": "已支付退款率", "synonyms": ["退款率"], "unit": "%", "decimals": 2, + "expression": "cell(nodes.fetch, 0, 'refund_rate')", + "definition": {"text": "已支付订单里发生退款的比例", "scope": "全部门店", "exclusions": [], + "owner": "运营", "effective_from": "2026-01-01", + "citations": [{"chunk": chunk_id, "quote": "只算已支付的订单"}]}, + "open_questions": [], + } + return json.dumps({ + "entry_fields": [{"name": "store", "type": "string", "required": False, "default": "", + "description": "门店(留空是全部门店)"}], + "sql": sql or "SELECT COUNT(*) * 1.0 AS refund_rate FROM orders WHERE status = 'paid' " + "AND store = '{{ input.store }}'", + "metrics": metrics if metrics is not None else [metric], + "open_questions": list(questions or []), + }, ensure_ascii=False) + + +class FakeModel: + """起草模型:ainvoke 返回带 .content 的对象;按顺序交回复,交完重复最后一份。""" + + model_name = "fake-model" + + def __init__(self, replies: list[str]) -> None: + self.replies = list(replies) + self.calls: list[list] = [] + + async def ainvoke(self, messages): + self.calls.append(list(messages)) + from types import SimpleNamespace + + return SimpleNamespace(content=self.replies.pop(0) if len(self.replies) > 1 else self.replies[0]) + + +def fake_model(monkeypatch, *replies: str) -> FakeModel: + model = FakeModel(list(replies)) + + async def resolve(_session): + from types import SimpleNamespace + + return model, model.model_name, SimpleNamespace(available=True, reason="") + + monkeypatch.setattr(recipe_ai, "resolve_draft_model", resolve) + return model @pytest.fixture @@ -50,114 +90,230 @@ async def client(): yield c -@pytest.fixture -async def documents(): - """建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。段落 id 带上文档 id,测试之间不撞。 - 测试结束删掉这几份文档、它们的段落和所有草稿。""" +@pytest.fixture(autouse=True) +async def fake_trial(monkeypatch): + """试跑换成写一行 succeeded 的运行:不启动引擎、不查库,接口和 payload 的形状照真的一样。""" made: list[str] = [] - async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default", - chunks=((2, "退款率 = 已支付后退款的订单数 / 已支付订单数"), (1, "退款率按门店拆"))) -> str: + async def start(*, draft_id, workflow_id, graph, values, started_by): + run_id = f"run-draft-{uuid.uuid4().hex[:10]}" + async with SessionLocal() as session: + session.add(Run(id=run_id, workflow_id=workflow_id, status="succeeded", graph=graph, + input=values, run_class="exploratory", origin_kind="caliber_trial", + origin={"kind": "caliber_trial", "draft_id": draft_id, + "workflow_id": workflow_id, "version": 1})) + await session.commit() + made.append(run_id) + return {"run_id": run_id, "status": "succeeded", "error": ""} + + monkeypatch.setattr(api_ledger, "_run_trial", start) + yield made + async with SessionLocal() as session: + for run_id in made: + row = await session.get(Run, run_id) + if row is not None: + await session.delete(row) + await session.commit() + + +@pytest.fixture +async def documents(): + """建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。测试结束删文档、段落、草稿和草稿建出的工作流。""" + made: list[str] = [] + + async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default") -> str: + chunks = ((2, CHUNK_TWO), (1, CHUNK_ONE)) async with SessionLocal() as session: session.add(Document(id=doc_id, collection=collection, title=title, source=title, content="".join(content for _, content in chunks), chunk_count=len(chunks))) for ordinal, content in chunks: - session.add(Chunk(id=f"{doc_id}-{ordinal}", document_id=doc_id, ordinal=ordinal, content=content)) + session.add(Chunk(id=f"{doc_id}-{ordinal}", document_id=doc_id, ordinal=ordinal, + content=content)) await session.commit() made.append(doc_id) return doc_id yield make async with SessionLocal() as session: + drafts = (await session.execute(select(CaliberDraft))).scalars().all() + workflow_ids = [draft.workflow_id for draft in drafts if draft.workflow_id] + # attach 会把 workflow_id 换成接上的那一份;起草时建的那份仍在 payload 里,照样要清掉 + workflow_ids += [draft.payload.get("workflow_id") for draft in drafts + if isinstance(draft.payload, dict) and draft.payload.get("workflow_id")] + workflow_ids = list(dict.fromkeys(workflow_ids)) + for draft in drafts: + await session.delete(draft) + if workflow_ids: + await session.execute(delete(WorkflowVersion).where(WorkflowVersion.workflow_id.in_(workflow_ids))) + await session.execute(delete(Workflow).where(Workflow.id.in_(workflow_ids))) for doc_id in made: await session.execute(delete(Chunk).where(Chunk.document_id == doc_id)) doc = await session.get(Document, doc_id) if doc is not None: await session.delete(doc) - for draft in (await session.execute(select(CaliberDraft))).scalars(): - await session.delete(draft) await session.commit() -def fake_extract(monkeypatch, *results: dict, seen: dict | None = None) -> None: - """把 docdraft.extract 换成固定结果:每次调用按顺序交一份,交完了重复最后一份。""" - queue = list(results) +@pytest.fixture +async def datasource(): + """一个有表结构的数据源:SQL 只能照这里的表写。""" + source_id = f"ds-{uuid.uuid4().hex[:10]}" - async def extract(session, *, docs, chunks, guidance="", datasource=None, model=None): - if seen is not None: - seen.update(docs=docs, chunks=chunks, guidance=guidance, datasource=datasource) - return copy.deepcopy(queue.pop(0) if len(queue) > 1 else queue[0]) + async def make(*, tables: bool = True) -> str: + cache = {"tables": {"orders": {"columns": [ + {"name": "status", "type": "TEXT"}, {"name": "store", "type": "TEXT"}, + {"name": "amount", "type": "NUMERIC"}, {"name": "paid_at", "type": "TEXT"}]}}, "total": 1} \ + if tables else {} + async with SessionLocal() as session: + session.add(DataSource(id=source_id, name=f"shop_{uuid.uuid4().hex[:8]}", kind="sqlite", + description="销售库", schema_cache=cache)) + await session.commit() + return source_id - monkeypatch.setattr(docdraft, "extract", extract) + yield make + async with SessionLocal() as session: + row = await session.get(DataSource, source_id) + if row is not None: + await session.delete(row) + await session.commit() -async def test_extract_reads_documents_in_order_and_stores_a_questions_open_draft(client, documents, monkeypatch): - doc = await documents("d-draft-1") - seen: dict = {} - fake_extract(monkeypatch, result(questions=["按哪个时区结算"]), seen=seen) +async def extract(client, doc: str, source_id: str, **extra) -> dict: + body = (await client.post("/api/ledger/drafts/extract", + json={"documents": [doc], "datasource_id": source_id, **extra})).json() + return body - res = await client.post("/api/ledger/drafts/extract", - json={"documents": [doc], "guidance": "只看已支付的订单"}) - assert res.status_code == 201, res.text - body = res.json() - assert set(body) == {"draft_id", "status"} - # 抽取在后台跑:建行那一刻回 drafting,结果用 GET 看 + +# ========================================================================== +# 主路径 +# ========================================================================== + +async def test_extract_produces_a_ready_draft_with_a_graph_and_a_trial(client, documents, datasource, monkeypatch): + doc = await documents("dd-1") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + + body = await extract(client, doc, source_id) assert body["status"] == "drafting" - # 交给模型的是按 ordinal 排好的段落,标题和 guidance 也传下去了 - first, second = f"{doc}-1", f"{doc}-2" - assert seen["docs"] == [{"document_id": doc, "title": "销售口径.md", "chunk_ids": [first, second]}] - assert [seen["chunks"][c]["ordinal"] for c in (first, second)] == [1, 2] - assert seen["chunks"][first]["document_id"] == doc - assert seen["guidance"] == "只看已支付的订单" and seen["datasource"] is None - made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() - assert made["status"] == "questions_open" and made["title"] == "销售口径.md" - assert made["workflow_id"] is None and made["workflow_name"] is None - assert made["model_id"] == "fake-model" + assert made["status"] == "ready" + assert made["title"] == "销售口径.md" + assert made["workflow_id"] and made["workflow_name"] == "销售口径.md" + assert made["metric_count"] == 1 and made["question_count"] == 0 assert [m["name"] for m in made["metrics"]] == ["已支付退款率"] - assert made["metrics"][0]["definition"]["citations"][0]["span"] == [0, 2] - assert made["open_questions"] == ["按哪个时区结算"] - assert made["dropped"] == [{"name": "第 2 条", "reason": "没有一条引用能在原文里逐字核对上"}] - assert set(made["alignment"]) == {"new", "duplicate", "conflict"} + assert made["metrics"][0]["expression"] == "cell(nodes.fetch, 0, 'refund_rate')" + assert made["metrics"][0]["definition"]["citations"][0]["span"] == [8, 16] + assert made["sql"].startswith("SELECT COUNT(*)") and "{{ input.store }}" in made["sql"] + assert [f["name"] for f in made["entry_fields"]] == ["store"] + assert made["trial"]["run_id"] and made["trial"]["status"] == "succeeded" + assert [d["document_id"] for d in made["documents"]] == [doc] + assert made["documents"][0]["chunk_ids"] == [f"{doc}-1", f"{doc}-2"] assert made["alignment"]["new"] == ["已支付退款率"] - assert made["truncated"] is False - assert made["origin"] == {"documents": [doc], "guidance": "只看已支付的订单"} - # 草稿不写进工作流:库里没有从它建出的图 + assert made["truncated"] is False and made["model_id"] == "fake-model" + assert made["datasource_id"] == source_id + + # 工作流和 v1 已建:合法的草稿图,取数指向这个数据源 async with SessionLocal() as session: row = await session.get(CaliberDraft, body["draft_id"]) - assert row.workflow_id is None and row.payload["metrics"][0]["name"] == "已支付退款率" + workflow = await session.get(Workflow, row.workflow_id) + version = (await session.execute(select(WorkflowVersion).where( + WorkflowVersion.workflow_id == row.workflow_id))).scalars().one() + assert workflow.status == "draft" and workflow.tags == ["doc_draft"] + assert version.version == 1 and version.graph == workflow.graph + assert [n["id"] for n in workflow.graph["nodes"]] == ["start", "fetch", "card", "write", "out"] + assert validate_graph(GraphSpec.model_validate(workflow.graph)).ok + + # 试跑只读接口:契约里的形状 + trial = (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).json() + assert set(trial) == {"run_id", "status", "metrics", "error"} + assert trial["run_id"] == made["trial"]["run_id"] and trial["status"] == "succeeded" -async def test_extract_without_open_questions_is_path_pending(client, documents, monkeypatch): - doc = await documents("d-draft-2") - fake_extract(monkeypatch, result(metrics=[{**METRIC, "open_questions": []}])) - body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json() - assert body["status"] == "drafting" +async def test_open_questions_keep_the_draft_in_questions_open_but_still_run_it( + client, documents, datasource, monkeypatch): + doc = await documents("dd-2") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2", questions=["退款算在哪一天"])) + + body = await extract(client, doc, source_id) made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() - assert made["status"] == "path_pending" - assert made["open_questions"] == [] and made["question_count"] == 0 + assert made["status"] == "questions_open" + assert made["open_questions"] == ["退款算在哪一天"] + assert made["workflow_id"] and made["sql"] + assert made["trial"]["status"] == "succeeded" -async def test_a_missing_document_is_refused_and_no_draft_is_created(client): - res = await client.post("/api/ledger/drafts/extract", json={"documents": ["d-nope"]}) +async def test_a_missing_or_empty_datasource_is_refused_and_no_draft_is_created(client, documents, datasource): + doc = await documents("dd-3") + without = await client.post("/api/ledger/drafts/extract", json={"documents": [doc]}) + assert without.status_code == 422 and "数据源" in without.text + unknown = await client.post("/api/ledger/drafts/extract", + json={"documents": [doc], "datasource_id": "ds-nope"}) + assert unknown.status_code == 422 and "数据源不存在" in unknown.text + empty_source = await datasource(tables=False) + empty = await client.post("/api/ledger/drafts/extract", + json={"documents": [doc], "datasource_id": empty_source}) + assert empty.status_code == 422 and "表结构" in empty.text + assert (await client.get("/api/ledger/drafts")).json()["drafts"] == [] + + +async def test_a_missing_document_is_refused_and_no_draft_is_created(client, datasource): + source_id = await datasource() + res = await client.post("/api/ledger/drafts/extract", + json={"documents": ["d-nope"], "datasource_id": source_id}) assert res.status_code == 422 and "d-nope" in res.text - listed = (await client.get("/api/ledger/drafts")).json() - assert listed["drafts"] == [] + assert (await client.get("/api/ledger/drafts")).json()["drafts"] == [] -async def test_patch_replaces_metrics_and_clears_resolved_questions(client, documents, monkeypatch): - doc = await documents("d-draft-3") - fake_extract(monkeypatch, result(questions=["按哪个时区结算"])) - draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"] +async def test_sql_outside_the_catalog_fails_the_draft_with_a_reason(client, documents, datasource, monkeypatch): + doc = await documents("dd-4") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2", sql="SELECT * FROM secrets")) - fixed_metric = {**copy.deepcopy(METRIC), "open_questions": [], "name": "已支付退款率(按支付日)"} + body = await extract(client, doc, source_id) + made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() + assert made["status"] == "failed" and made["workflow_id"] is None + assert "secrets" in made["error"] and "数据目录" in made["error"] + assert any("secrets" in d["reason"] for d in made["dropped"]) + assert not made.get("sql") + assert (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).status_code == 404 + + +async def test_a_metric_with_a_bad_expression_is_dropped_but_the_draft_still_goes_on( + client, documents, datasource, monkeypatch): + doc = await documents("dd-5") + source_id = await datasource() + reply = json.loads(plan_reply(f"{doc}-2")) + reply["metrics"].append({**reply["metrics"][0], "id": "m2", "name": "订单数", "expression": "SUM(amount)"}) + fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False)) + + body = await extract(client, doc, source_id) + made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() + # 一条好、一条坏:坏的那条进 dropped / open_questions,草稿照样 ready 之外还有图 + assert [m["id"] for m in made["metrics"]] == ["m1"] + assert any(d["name"] == "订单数" and "cell(nodes.fetch, 0" in d["reason"] for d in made["dropped"]) + assert any("订单数" in q for q in made["open_questions"]) + assert made["status"] == "questions_open" and made["workflow_id"] + + +# ========================================================================== +# 改、驳回、列表、试跑接口 +# ========================================================================== + +async def test_patch_replaces_metrics_and_clears_resolved_questions(client, documents, datasource, monkeypatch): + doc = await documents("dd-6") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2", questions=["按哪个时区结算"])) + draft_id = (await extract(client, doc, source_id))["draft_id"] + + fixed = {**copy.deepcopy(json.loads(plan_reply(f"{doc}-2"))["metrics"][0]), "name": "已支付退款率(按支付日)"} res = await client.patch(f"/api/ledger/drafts/{draft_id}", - json={"title": "退款率口径", "metrics": [fixed_metric], - "resolved": ["按哪个时区结算", "退款算不算已支付当天的"]}) + json={"title": "退款率口径", "metrics": [fixed], + "resolved": ["按哪个时区结算"]}) assert res.status_code == 200, res.text made = res.json() - assert made["title"] == "退款率口径" and made["status"] == "path_pending" + assert made["title"] == "退款率口径" and made["status"] == "ready" assert [m["name"] for m in made["metrics"]] == ["已支付退款率(按支付日)"] assert made["open_questions"] == [] and made["question_count"] == 0 @@ -169,14 +325,15 @@ async def test_patch_replaces_metrics_and_clears_resolved_questions(client, docu # 还有问题(只换指标、带着新问题)→ questions_open res = await client.patch(f"/api/ledger/drafts/{draft_id}", - json={"metrics": [{**fixed_metric, "open_questions": ["按哪个门店口径"]}]}) + json={"metrics": [{**fixed, "open_questions": ["按哪个门店口径"]}]}) assert res.json()["status"] == "questions_open" and res.json()["question_count"] == 1 -async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, monkeypatch): - doc = await documents("d-draft-4") - fake_extract(monkeypatch, result()) - draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"] +async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, datasource, monkeypatch): + doc = await documents("dd-7") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + draft_id = (await extract(client, doc, source_id))["draft_id"] res = await client.post(f"/api/ledger/drafts/{draft_id}/dismiss", json={"note": "已经有口径了"}) assert res.status_code == 200 and res.json()["status"] == "rejected" @@ -187,23 +344,23 @@ async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, mon assert (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["status"] == "rejected" -async def test_list_counts_orders_by_last_change_and_filters_by_status(client, documents, monkeypatch): - first = await documents("d-draft-5", title="一.md") - second = await documents("d-draft-6", title="二.md") - fake_extract(monkeypatch, - result(metrics=[METRIC, {**METRIC, "name": "退款金额", "open_questions": []}], - questions=["按哪个时区结算"]), - result(metrics=[{**METRIC, "open_questions": []}])) - one = (await client.post("/api/ledger/drafts/extract", json={"documents": [first]})).json()["draft_id"] - two = (await client.post("/api/ledger/drafts/extract", json={"documents": [second]})).json()["draft_id"] +async def test_list_counts_orders_by_last_change_and_filters_by_status(client, documents, datasource, monkeypatch): + first = await documents("dd-8", title="一.md") + second = await documents("dd-9", title="二.md") + source_id = await datasource() + fake_model(monkeypatch, + plan_reply(f"{first}-2", questions=["按哪个时区结算"]), + plan_reply(f"{second}-2")) + one = (await extract(client, first, source_id))["draft_id"] + two = (await extract(client, second, source_id))["draft_id"] listed = (await client.get("/api/ledger/drafts")).json()["drafts"] assert [d["id"] for d in listed] == [two, one] latest, earlier = listed assert (latest["title"], latest["status"], latest["metric_count"], latest["question_count"]) == \ - ("二.md", "path_pending", 1, 0) - assert (earlier["status"], earlier["metric_count"], earlier["question_count"]) == ("questions_open", 2, 2) - assert earlier["workflow_id"] is None and earlier["created_at"] and earlier["error"] is None + ("二.md", "ready", 1, 0) + assert (earlier["status"], earlier["metric_count"], earlier["question_count"]) == ("questions_open", 1, 1) + assert earlier["workflow_id"] and earlier["created_at"] and earlier["error"] is None only = (await client.get("/api/ledger/drafts", params={"status": "questions_open"})).json()["drafts"] assert [d["id"] for d in only] == [one] @@ -211,24 +368,57 @@ async def test_list_counts_orders_by_last_change_and_filters_by_status(client, d assert (await client.get("/api/ledger/drafts/d-nope")).status_code == 404 -async def test_a_model_that_is_unavailable_leaves_the_draft_with_an_error(client, documents, monkeypatch): - doc = await documents("d-draft-7") +async def test_trial_endpoint_returns_metric_values_from_the_run(client, documents, datasource, monkeypatch): + doc = await documents("dd-10") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + draft_id = (await extract(client, doc, source_id))["draft_id"] - async def unavailable(session, **kwargs): - raise docdraft.DraftUnavailable("还没有接入可用的起草模型") + async def metrics(_run_id): + return [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}] - monkeypatch.setattr(docdraft, "extract", unavailable) - body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json() + monkeypatch.setattr(api_ledger, "_trial_metrics", metrics) + res = await client.get(f"/api/ledger/drafts/{draft_id}/trial") + assert res.status_code == 200, res.text + body = res.json() + assert body == {"run_id": body["run_id"], "status": "succeeded", + "metrics": [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}], + "error": ""} + + # 没有试跑的老草稿 + async with SessionLocal() as session: + session.add(CaliberDraft(id=f"draft-old-{uuid.uuid4().hex[:8]}", title="老草稿", status="path_pending", + payload={"metrics": []})) + await session.commit() + old = (await session.execute(select(CaliberDraft.id).where( + CaliberDraft.status == "path_pending"))).scalars().first() + assert (await client.get(f"/api/ledger/drafts/{old}/trial")).status_code == 404 + + +async def test_a_model_that_is_unavailable_leaves_the_draft_with_an_error(client, documents, datasource, + monkeypatch): + doc = await documents("dd-11") + source_id = await datasource() + + async def unavailable(_session): + from types import SimpleNamespace + + return None, "", SimpleNamespace(available=False, reason="还没有接入可用的起草模型") + + monkeypatch.setattr(recipe_ai, "resolve_draft_model", unavailable) + body = await extract(client, doc, source_id) made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json() assert made["status"] == "failed" and made["error"] == "还没有接入可用的起草模型" assert made["metric_count"] == 0 and not made.get("metrics") -async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(client, documents, monkeypatch): - """attach 只按约定调 app.ledger.docattach.attach(另一路实现):这里换成一个假的模块,看接线和写回。""" - doc = await documents("d-draft-8") - fake_extract(monkeypatch, result(metrics=[{**METRIC, "open_questions": []}])) - draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"] +async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(client, documents, datasource, + monkeypatch): + """attach 只按约定调 app.ledger.docattach.attach(辅助入口):这里换成一个假的模块,看接线和写回。""" + doc = await documents("dd-12") + source_id = await datasource() + fake_model(monkeypatch, plan_reply(f"{doc}-2")) + draft_id = (await extract(client, doc, source_id))["draft_id"] seen: dict = {} @@ -257,3 +447,63 @@ async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(clie if workflow is not None: await session.delete(workflow) await session.commit() + + +async def test_a_real_trial_run_feeds_the_trial_endpoint(client, documents, tmp_path, monkeypatch): + """真引擎跑一次草稿图:数从取数节点进口径卡,GET /trial 交回指标值(不 mock 试跑)。""" + from app.engine.runner import run_manager + from tests import ledger_samples as S + + await run_manager.setup() + run_id = None + try: + name = await S.fresh_source(tmp_path / "shop.db") + async with SessionLocal() as session: + row = (await session.execute(select(DataSource).where(DataSource.name == name))).scalar_one() + row.schema_cache = {"tables": {"orders": {"columns": [ + {"name": "status", "type": "TEXT"}, {"name": "region", "type": "TEXT"}, + {"name": "amount", "type": "REAL"}, {"name": "paid_at", "type": "TEXT"}]}}, "total": 1} + await session.commit() + source_id = row.id + doc = await documents("dd-real") + reply = json.loads(plan_reply(f"{doc}-2")) + reply["entry_fields"] = [{"name": "region", "type": "string", "required": False, + "default": "east", "description": "区域"}] + reply["sql"] = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' " + "AND region = '{{ input.region }}'") + reply["metrics"][0].update({"expression": "cell(nodes.fetch, 0, 'gmv')", "name": "已支付销售额", + "unit": "元", "decimals": 2}) + fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False)) + # 报告节点也要一个模型:用品自带的 mock 模型,正文引用卡上的指标,核对规则照过 + S.script(monkeypatch, "已支付销售额 [[m:m1]]。") + monkeypatch.setattr(api_ledger, "_run_trial", REAL_RUN_TRIAL) + + draft_id = (await extract(client, doc, source_id))["draft_id"] + made = (await client.get(f"/api/ledger/drafts/{draft_id}")).json() + assert made["status"] == "ready" and made["trial"]["status"] == "succeeded", made.get("error") + run_id = made["trial"]["run_id"] + + trial = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json() + assert trial["status"] == "succeeded" and trial["error"] == "" + assert [m["id"] for m in trial["metrics"]] == ["m1"] + assert trial["metrics"][0]["name"] == "已支付销售额" + assert float(trial["metrics"][0]["value"]) == 156.5 + async with SessionLocal() as session: + run = await session.get(Run, run_id) + assert run.origin_kind == "caliber_trial" and run.run_class == "exploratory" + assert not [n for n in (run.graph or {}).get("nodes") or [] if n.get("type") == "report"], \ + "试跑只跑取数与口径卡,不该触发报告撰写" + assert run.origin["kind"] == "caliber_trial" and run.origin["draft_id"] == draft_id + assert run.origin["workflow_id"] == made["workflow_id"] and run.origin["version"] == 1 + finally: + await run_manager.shutdown() + async with SessionLocal() as session: + if run_id: + row = await session.get(Run, run_id) + if row is not None: + await session.delete(row) + source = (await session.execute(select(DataSource).where( + DataSource.name == S.CURRENT["source"]))).scalars().first() + if source is not None: + await session.delete(source) + await session.commit() diff --git a/backend/tests/test_ledger_draftplan.py b/backend/tests/test_ledger_draftplan.py new file mode 100644 index 00000000..3e5f20ff --- /dev/null +++ b/backend/tests/test_ledger_draftplan.py @@ -0,0 +1,200 @@ +"""口径一次起草的纯逻辑(app/ledger/draftplan.py)。 + +- SQL 只收单条只读 SELECT:多语句、注释后藏的第二条、写操作、目录外的表一律拒; +- 指标表达式必须是 cell(nodes.fetch, 0, '列名');引用核不上的整条丢弃; +- build_graph 两次调用逐字一致,且能过 GraphSpec / validate_graph; +- plan 注入假模型(不发真实请求),材料里有表目录和原文。 +""" +from __future__ import annotations + +import json +from types import SimpleNamespace + +import pytest + +from app.engine.schema import GraphSpec, validate_graph +from app.ledger import draftplan + +CHUNK = "销售额按已支付订单的支付时间归期统计,退款订单不计入销售额。" +CHUNKS = {"c1": {"ordinal": 1, "content": CHUNK, "document_id": "d1"}} +TABLES = {"orders", "customers"} + +METRIC = { + "id": "m1", + "name": "销售额", + "synonyms": ["gmv"], + "unit": "元", + "decimals": 2, + "expression": "cell(nodes.fetch, 0, 'gmv')", + "definition": {"text": "已支付订单的销售额", "scope": "全部", "exclusions": [], "owner": "运营", + "effective_from": "2026-01-01", + "citations": [{"chunk": "c1", "quote": "销售额按已支付订单的支付时间归期统计"}]}, + "open_questions": [], +} + + +def raw(**extra): + body = { + "entry_fields": [{"name": "start", "type": "string", "required": True, "default": "2026-09-01", + "description": "开始日期"}], + "sql": "SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.start }}'", + "metrics": [dict(METRIC)], + "open_questions": [], + } + body.update(extra) + return body + + +def sql_problem(sql: str) -> str | None: + plan, problems = draftplan.normalize_plan(raw(sql=sql), CHUNKS, allowed_tables=TABLES) + assert plan["sql"] == "" + reasons = [p["reason"] for p in problems if p["name"] == "sql"] + assert reasons, problems + return reasons[0] + + +# ========================================================================== +# normalize_plan:SQL 的硬规则 +# ========================================================================== + +def test_a_read_only_select_over_the_catalog_is_kept(): + plan, problems = draftplan.normalize_plan(raw(), CHUNKS, allowed_tables=TABLES) + assert plan["sql"].endswith("'{{ input.start }}'") + assert [m["id"] for m in plan["metrics"]] == ["m1"] + assert plan["entry_fields"][0]["name"] == "start" + assert not [p for p in problems if p["name"] == "sql"] + + +def test_multiple_statements_and_a_hidden_second_statement_are_refused(): + assert "只能是一条语句" in sql_problem( + "SELECT SUM(amount) AS gmv FROM orders; DROP TABLE orders") + # 注释后藏的第二条也解析成第二条语句 + assert "只能是一条语句" in sql_problem( + "SELECT SUM(amount) AS gmv FROM orders; -- 收尾\nDELETE FROM orders") + + +def test_writes_and_ddl_are_refused(): + assert "只读 SELECT" in sql_problem("DELETE FROM orders") + assert "只读 SELECT" in sql_problem("UPDATE orders SET amount = 0") + assert "只读 SELECT" in sql_problem("DROP TABLE orders") + + +def test_tables_outside_the_catalog_are_refused(): + reason = sql_problem("SELECT * FROM secrets") + assert "secrets" in reason and "数据目录" in reason + # CTE 名字不是表;真正的表没在目录里照样拒 + reason = sql_problem("WITH x AS (SELECT * FROM secrets) SELECT * FROM x") + assert "secrets" in reason + + +def test_a_cte_over_a_catalog_table_is_allowed(): + plan, problems = draftplan.normalize_plan( + raw(sql="WITH paid AS (SELECT amount FROM orders) SELECT SUM(amount) AS gmv FROM paid"), + CHUNKS, allowed_tables=TABLES) + assert plan["sql"].startswith("WITH paid") + assert not [p for p in problems if p["name"] == "sql"] + + +def test_an_undeclared_template_field_invalidates_the_sql(): + plan, problems = draftplan.normalize_plan( + raw(sql="SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.nope }}'"), + CHUNKS, allowed_tables=TABLES) + assert plan["sql"] == "" + assert any("nope" in p["reason"] for p in problems) + + +# ========================================================================== +# normalize_plan:指标 +# ========================================================================== + +def test_a_bad_expression_drops_only_that_metric(): + plan, problems = draftplan.normalize_plan( + raw(metrics=[{**METRIC, "expression": "SUM(amount)"}, {**dict(METRIC), "id": "m2"}]), + CHUNKS, allowed_tables=TABLES) + assert [m["id"] for m in plan["metrics"]] == ["m2"] + assert any(p["name"] == "销售额" and "cell(nodes.fetch, 0" in p["reason"] for p in problems) + + +def test_a_metric_whose_quotes_do_not_match_the_source_is_dropped(): + plan, problems = draftplan.normalize_plan( + raw(metrics=[{**METRIC, "definition": {**METRIC["definition"], + "citations": [{"chunk": "c1", "quote": "原文里没有这句"}]}}]), + CHUNKS, allowed_tables=TABLES) + assert plan["metrics"] == [] + assert any(p["name"] == "销售额" and "引用" in p["reason"] for p in problems) + assert any(p["name"] == "metrics" for p in problems) + + +def test_metric_ids_are_unique_and_entry_fields_are_normalized(): + plan, _problems = draftplan.normalize_plan( + raw(entry_fields=[{"name": "start", "type": "date", "required": 1, "default": "2026-09-01"}], + metrics=[dict(METRIC), {**dict(METRIC), "name": "订单数"}]), + CHUNKS, allowed_tables=TABLES) + assert [m["id"] for m in plan["metrics"]] == ["m1", "m2"] + assert plan["entry_fields"][0]["type"] == "string" + assert plan["entry_fields"][0]["required"] is True + + +# ========================================================================== +# build_graph +# ========================================================================== + +def test_build_graph_is_deterministic_and_passes_validation(): + plan, _ = draftplan.normalize_plan(raw(), CHUNKS, allowed_tables=TABLES) + plan["datasource"] = "shop" + first = draftplan.build_graph(plan, name="销售额口径", question="上周销售额") + second = draftplan.build_graph(plan, name="销售额口径", question="上周销售额") + assert first == second + assert [node["id"] for node in first["nodes"]] == ["start", "fetch", "card", "write", "out"] + fetch = next(node for node in first["nodes"] if node["id"] == "fetch") + assert fetch["data"]["config"] == {"tool": "db_query__shop", "args": {"sql": plan["sql"]}} + card = next(node for node in first["nodes"] if node["id"] == "card") + assert card["data"]["config"]["metrics"][0]["id"] == "m1" + contract = next(node for node in first["nodes"] if node["id"] == "out")["data"]["config"]["contract"] + assert contract["metrics_from"] == "card" and contract["required"] == ["m1"] + report = next(node for node in first["nodes"] if node["id"] == "write")["data"]["config"] + assert report["numbers"] == "strict" and report["metrics_from"] == ["card"] + result = validate_graph(GraphSpec.model_validate(first)) + assert result.ok, [issue.message for issue in result.issues if issue.level == "error"] + + +# ========================================================================== +# plan:注入假模型 +# ========================================================================== + +class FakeModel: + model_name = "fake-plan-model" + + def __init__(self, text: str) -> None: + self.text = text + self.messages: list = [] + + async def ainvoke(self, messages): + self.messages = messages + return SimpleNamespace(content=self.text) + + +async def test_plan_hands_the_model_the_table_catalog_and_the_source_text(): + model = FakeModel(json.dumps({**raw(), "model_id": "ignored"}, ensure_ascii=False)) + result = await draftplan.plan( + None, docs=[{"document_id": "d1", "title": "销售口径.md"}], chunks=CHUNKS, + guidance="只看已支付", datasource={"name": "shop", "type": "sqlite"}, + tables_text="表 orders(订单)\n amount 金额", model=model) + assert result["model_id"] == "fake-plan-model" + assert result["sql"].startswith("SELECT SUM(amount)") + assert result["metrics"][0]["name"] == "销售额" + human = model.messages[-1].content + assert "表 orders" in human and "amount 金额" in human + assert CHUNK in human and "只看已支付" in human + + +async def test_plan_refuses_when_no_draft_model_is_available(monkeypatch): + from app.data import recipe_ai + from app.ledger import docdraft + + async def resolve(_session): + return None, "", SimpleNamespace(available=False, reason="还没有接入可用的起草模型") + + monkeypatch.setattr(recipe_ai, "resolve_draft_model", resolve) + with pytest.raises(docdraft.DraftUnavailable, match="起草模型"): + await draftplan.plan(None, docs=[], chunks={})