口径草稿:从业务文档抽定义,再从一次真实运行接上取数路径

新增 caliber_drafts 表与 /api/ledger/drafts 一组接口:抽取在后台跑,文档缺失整单拒绝,
有未决问题时停在 questions_open,问题清完才到 path_pending。

接上运行沿用从运行固化的建图逻辑,定义按同名或同义词并入指标卡,expression 与 id 不动;
文档引用记进 origin.documents,复核能落回具体段落。接入只产出可试跑的草稿,不发布、不发起运行。
This commit is contained in:
ThearchyHelios
2026-11-03 22:50:14 +08:00
parent 51daa7b96c
commit 7f66985dba
5 changed files with 973 additions and 2 deletions
+342 -2
View File
@@ -18,24 +18,30 @@
每组的结论、「另有 M 组未重算」、手动接着算(app/ledger/recall.py)。版本用量(workflow-versions)另加问数回答、导出、召回。
- 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)。
这几个新接口都不放给访问密钥(auth/keys.KEY_ROUTES 不登记)。
"""
from __future__ import annotations
import asyncio
import logging
from typing import Any
from datetime import datetime
from fastapi import APIRouter, Depends, HTTPException, Query
from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query
from pydantic import BaseModel, Field
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.db.base import SessionLocal, get_session
from app.db.models import Run, Workflow
from app.db.models import CaliberDraft, Chunk, DataSource, Document, Run, Workflow
from app.db.models_process import ActionRecord
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/ledger", tags=["ledger"])
#: 口径账本里按运行读的那几个(一个答案里每个数的口径标签等,docs/design/next-round/02-口径账本.md):挂在
#: /api/runs/{run_id}/ledger… 下,和证据接口同一道门(main.py 挂 evidence_scope:使用者只读、而且要能读这次运行)
@@ -373,3 +379,337 @@ async def trial_caliber(workflow_id: str, version: int, node_id: str, payload: T
for m in card.get("metrics") or [] if isinstance(m, dict) and m.get("id")
]
return out
# --------------------------------------------------------------------------
# 从业务文档起草口径(app/ledger/docdraft.py;attach 是 app/ledger/docattach.py)
# --------------------------------------------------------------------------
#: 草稿被驳回的审计(和 certify.dismiss 同一个写法:subject 是草稿 id)
DRAFT_DISMISS_ACTION = "ledger.docdraft.dismiss"
DRAFT_SUBJECT_KIND = "ledger_draft"
def _question_count(payload: dict[str, Any]) -> int:
"""未决问题数:跨指标的 open_questions + 各指标自己的。status 就按它算,PATCH 之后重算也用它。"""
def count(items: Any) -> int:
return len([q for q in items if isinstance(q, str) and q.strip()]) if isinstance(items, list) else 0
total = count(payload.get("open_questions"))
metrics = payload.get("metrics")
for metric in metrics if isinstance(metrics, list) else []:
if isinstance(metric, dict):
total += count(metric.get("open_questions"))
return total
def _status_for(payload: dict[str, Any]) -> str:
"""还有问题 → questions_open,否则 path_pending(等一次真实运行补取数路径)。"""
return "questions_open" if _question_count(payload) else "path_pending"
def _draft_summary(draft: CaliberDraft) -> dict[str, Any]:
payload = draft.payload if isinstance(draft.payload, dict) else {}
metrics = payload.get("metrics")
return {"id": draft.id, "title": draft.title, "status": draft.status,
"metric_count": len(metrics) if isinstance(metrics, list) else 0,
"question_count": _question_count(payload), "workflow_id": draft.workflow_id,
"created_at": draft.created_at.isoformat() if draft.created_at else None, "error": draft.error}
async def _draft_view(session: AsyncSession, draft: CaliberDraft) -> dict[str, Any]:
"""一份草稿的完整样子:payload 摊平在上层(界面直接读 metrics / open_questions),另加状态和关联工作流名。"""
payload = draft.payload if isinstance(draft.payload, dict) else {}
workflow = await session.get(Workflow, draft.workflow_id) if draft.workflow_id else None
return {**payload, **_draft_summary(draft),
"collection": draft.collection, "datasource_id": draft.datasource_id,
"origin": draft.origin if isinstance(draft.origin, dict) else {},
"model_id": draft.model_id or payload.get("model_id"), "created_by": draft.created_by,
"updated_at": draft.updated_at.isoformat() if draft.updated_at else None,
"workflow_name": workflow.name if workflow is not None else None}
async def _draft_or_404(session: AsyncSession, draft_id: str) -> CaliberDraft:
draft = await session.get(CaliberDraft, draft_id)
if draft is None:
raise HTTPException(404, "口径草稿不存在,可能已被删除")
return draft
async def _published_metrics(session: AsyncSession) -> list[dict[str, Any]]:
"""已发布口径里的每一项指标,给 docdraft.alignment 用:{workflow_id, version, node_id, name, synonyms, unit,
definition_text}。直接复用 descriptor.list_calibers 的认法(只看最新已发布且未退役版本的源头口径卡)。"""
from app.ledger.descriptor import list_calibers
out: list[dict[str, Any]] = []
for described in await list_calibers(session):
for metric in described.get("metrics") or []:
if not isinstance(metric, dict):
continue
definition = metric.get("definition")
text = definition.get("text") if isinstance(definition, dict) else None
name = metric.get("name") or metric.get("id")
if not name:
continue
out.append({"workflow_id": described["workflow_id"], "version": described["version"],
"node_id": described["card"]["node_id"], "name": str(name),
"synonyms": metric.get("synonyms") if isinstance(metric.get("synonyms"), list) else [],
"unit": metric.get("unit") or "", "definition_text": text or ""})
return out
def _doc_title(docs: list[Document]) -> str:
"""草稿标题取第一份文档的名字;多份文档写明还有几份。"""
first = docs[0]
title = (first.title or first.source or first.id).strip() or first.id
return (f"{title}等 {len(docs)} 份文档" if len(docs) > 1 else title)[:200]
async def _extract_in_background(draft_id: str) -> None:
"""后台起草:读文档的段落、调一次模型、和已发布口径对齐,结果写回这一行。
用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。失败写进 error、状态留在 drafting——
草稿不是「被驳回」,人改完文档还能再来一次。
"""
from app.ledger import docdraft
async with SessionLocal() as session:
draft = await session.get(CaliberDraft, draft_id)
if draft is None or draft.status != "drafting":
return
origin = draft.origin if isinstance(draft.origin, dict) else {}
wanted = [str(d) for d in origin.get("documents") or []]
docs: list[Document] = []
for doc_id in wanted:
doc = await session.get(Document, doc_id)
if doc is not None:
docs.append(doc)
chunks: dict[str, dict[str, Any]] = {}
entries: list[dict[str, Any]] = []
for doc in docs:
rows = (await session.execute(select(Chunk).where(Chunk.document_id == doc.id)
.order_by(Chunk.ordinal, Chunk.id))).scalars()
chunk_ids: list[str] = []
for chunk in rows:
chunks[chunk.id] = {"ordinal": chunk.ordinal, "content": chunk.content or "",
"document_id": doc.id}
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}
try:
result = await docdraft.extract(session, docs=entries, chunks=chunks,
guidance=str(origin.get("guidance") or ""), datasource=datasource)
# 对齐要扫所有已发布口径:某一份读不出来不该让整份草稿失败,照实不做对齐(alignment 三个空列表)
try:
existing = await _published_metrics(session)
except Exception: # noqa: BLE001 - 对齐是辅助信息,不是草稿本身
logger.exception("读已发布口径失败,草稿 %s 不做对齐", draft_id)
existing = []
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"],
}
except docdraft.DraftUnavailable as e:
draft.error = str(e) or "AI 起草不可用"
await session.commit()
return
except Exception as e: # noqa: BLE001 - 后台出错要写回这一行,不然界面永远停在「起草中」
logger.exception("从文档起草口径出错(草稿 %s)", draft_id)
draft.error = f"起草出错:{e}"
await session.commit()
return
draft.payload = payload
draft.model_id = result["model_id"] or None
draft.error = None
draft.status = _status_for(payload)
await session.commit()
class DraftExtractIn(BaseModel):
"""从哪几份文档起草、起草时给模型看的附加要求。数据源只用来写清适用范围,不给表结构。"""
documents: list[str] = Field(min_length=1, max_length=20)
collection: str | None = Field(default=None, max_length=100)
datasource_id: str | None = Field(default=None, max_length=32)
guidance: str = Field(default="", max_length=2000)
@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 立刻返回,模型在后台跑。
文档必须都存在(缺的回 422,一个草稿都不建);数据源给了也必须存在。草稿只产出定义,不产出取数,也不写进
workflows.graph——path_pending 不是合法的图。抽取完的 payload / status 用 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, "至少要给一份文档")
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:
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"),
datasource_id=payload.datasource_id or None, status="drafting", payload={},
origin={"documents": doc_ids, "guidance": payload.guidance.strip()},
created_by=current_principal().username)
session.add(draft)
await session.commit()
background.add_task(_extract_in_background, draft.id)
return {"draft_id": draft.id, "status": draft.status}
@router.get("/drafts")
async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / questions_open / "
"path_pending / attached / rejected"),
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""口径草稿列表,最近改过的在前。只给计数和状态,正文用 GET /api/ledger/drafts/{id} 看。"""
from app.api.deps import ensure_role
from app.ledger import docdraft
ensure_role("builder")
query = select(CaliberDraft).order_by(CaliberDraft.updated_at.desc(), CaliberDraft.id.desc())
if status:
if status not in docdraft.STATUSES:
raise HTTPException(422, f"不认识的状态:{status}")
query = query.where(CaliberDraft.status == status)
rows = (await session.execute(query)).scalars()
return {"drafts": [_draft_summary(draft) for draft in rows]}
@router.get("/drafts/{draft_id}")
async def get_draft(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""一份草稿的完整内容:指标(含引用和 span)、丢弃原因、未决问题、和已发布口径的对齐结果、关联工作流名。"""
from app.api.deps import ensure_role
ensure_role("builder")
return await _draft_view(session, await _draft_or_404(session, draft_id))
def _check_metrics(metrics: Any) -> list[dict[str, Any]]:
"""PATCH 换指标时只做结构校验(不重跑引用核对:引用是模型交的,人改过的段落没法再逐字对一遍)。"""
if not isinstance(metrics, list):
raise HTTPException(422, "metrics 要是数组")
for position, metric in enumerate(metrics, start=1):
if not isinstance(metric, dict):
raise HTTPException(422, f"第 {position} 条指标不是一个对象")
name = metric.get("name")
if not isinstance(name, str) or not name.strip():
raise HTTPException(422, f"第 {position} 条指标缺少名称")
for key in ("synonyms", "open_questions"):
value = metric.get(key)
if value is not None and (not isinstance(value, list) or not all(isinstance(v, str) for v in value)):
raise HTTPException(422, f"第 {position} 条指标的 {key} 要是字符串数组")
if metric.get("definition") is not None and not isinstance(metric.get("definition"), dict):
raise HTTPException(422, f"第 {position} 条指标的 definition 要是一个对象")
return [dict(metric) for metric in metrics]
class DraftPatchIn(BaseModel):
"""改标题、整体换掉指标、或把已经答清的问题消掉。"""
title: str | None = Field(default=None, max_length=200)
metrics: list[dict[str, Any]] | None = None
resolved: list[str] | None = None
@router.patch("/drafts/{draft_id}")
async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSession = Depends(get_session)
) -> dict[str, Any]:
"""改一份草稿:metrics 整体替换(只做结构校验,不重跑引用核对);resolved 里的问题从跨指标和各指标的问题里删掉。
据此重算状态(还有问题 → questions_open,否则 path_pending)。已经 attach 或驳回的草稿不改状态——那时它说的
已经不是一份草稿了。"""
from app.api.deps import ensure_role
ensure_role("builder")
draft = await _draft_or_404(session, draft_id)
body = draft.payload if isinstance(draft.payload, dict) else {}
payload_data = dict(body)
if payload.title is not None:
if not payload.title.strip():
raise HTTPException(422, "标题不能为空")
draft.title = payload.title.strip()
if payload.metrics is not None:
payload_data["metrics"] = _check_metrics(payload.metrics)
if payload.resolved is not None:
drop = {q.strip() for q in payload.resolved if isinstance(q, str) and q.strip()}
questions = payload_data.get("open_questions")
payload_data["open_questions"] = [q for q in questions if isinstance(q, str) and q.strip() not in drop] \
if isinstance(questions, list) else []
metrics = payload_data.get("metrics")
for metric in metrics if isinstance(metrics, list) else []:
if not isinstance(metric, dict) or not isinstance(metric.get("open_questions"), list):
continue
metric["open_questions"] = [q for q in metric["open_questions"]
if not (isinstance(q, str) and q.strip() in drop)]
if payload.metrics is not None or payload.resolved is not None:
draft.payload = payload_data
if draft.status in ("drafting", "questions_open", "path_pending"):
draft.status = _status_for(payload_data)
await session.commit()
return await _draft_view(session, draft)
class DraftDismissIn(BaseModel):
note: str | None = Field(default=None, max_length=500)
@router.post("/drafts/{draft_id}/dismiss")
async def dismiss_draft(draft_id: str, payload: DraftDismissIn,
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""这份草稿不是口径:置 rejected,写一条审计(ledger.docdraft.dismiss),以后不再出现在待办里。"""
from app.api.deps import ensure_role
from app.auth.audit import record
ensure_role("builder")
draft = await _draft_or_404(session, draft_id)
draft.status = "rejected"
await record(session, DRAFT_DISMISS_ACTION, DRAFT_SUBJECT_KIND, draft.id,
data={k: v for k, v in {"title": draft.title, "note": payload.note}.items() if v})
await session.commit()
return {"ok": True, "draft_id": draft.id, "status": draft.status}
class DraftAttachIn(BaseModel):
"""按哪次运行补取数路径:运行里执行过的查询就是这份口径的取数,不另写 SQL。"""
run_id: str = Field(min_length=1, max_length=64)
@router.post("/drafts/{draft_id}/attach")
async def attach_draft(draft_id: str, payload: DraftAttachIn,
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""把定义接到一次真实运行上(app/ledger/docattach.py):由它建工作流和版本,交回 {workflow_id, version, metrics,
warnings}。成功后草稿记下工作流 id、置 attached。接不上时照 docattach 自己的状态码和说法回。"""
from app.api.deps import ensure_role
from app.ledger.docattach import attach
ensure_role("builder")
draft = await _draft_or_404(session, draft_id)
try:
out = await attach(session, payload=draft.payload, name=draft.title, run_id=payload.run_id,
draft_id=draft.id)
except Exception as e: # noqa: BLE001 - docattach 的拒绝带着 status_code / message,照原样交回
status = getattr(e, "status_code", None)
if isinstance(status, int) and getattr(e, "message", None):
raise HTTPException(status, e.message) from e
raise
draft.workflow_id = out.get("workflow_id") or draft.workflow_id
draft.status = "attached"
draft.error = None
await session.commit()
return out
+37
View File
@@ -1088,6 +1088,43 @@ class WebhookDelivery(Base):
created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
# --------------------------------------------------------------------------
# 口径账本(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)
# --------------------------------------------------------------------------
class CaliberDraft(Base, TimestampMixin):
"""从业务文档起草的一份口径(app/ledger/docdraft.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 上。
"""
__tablename__ = "caliber_drafts"
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")
# 起草时给模型看的数据源(只给名字和类型,用来写清适用范围);源删了草稿照旧在,只丢这一条线索
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
status: Mapped[str] = mapped_column(String(20), default="drafting", index=True)
payload: Mapped[dict[str, Any]] = mapped_column(default=dict)
# 这份草稿从哪来:{"documents": [文档 id], "guidance": 用户补充要求}
origin: Mapped[dict[str, Any]] = mapped_column(default=dict)
workflow_id: Mapped[str | None] = mapped_column(
ForeignKey("workflows.id", ondelete="SET NULL"), default=None
)
# 起草失败的说法(没有可用模型、模型回的东西取不出 JSON……)。草稿不置成 rejected:人改完还能再试
error: Mapped[str | None] = mapped_column(Text, default=None)
created_by: Mapped[str | None] = mapped_column(String(120), default=None)
model_id: Mapped[str | None] = mapped_column(String(120), default=None)
# --------------------------------------------------------------------------
# 应用平台(docs/design/app-platform-and-look.md §3.1):按领域分文件,这里统一导入,
# 让 init_db 的 create_all 和其他模块 `from app.db.models import ...` 都认得到
+186
View File
@@ -0,0 +1,186 @@
"""文档草稿接上一次真实运行:定义来自文档,取数路径来自运行(docs/design/next-round/02-口径账本.md 做法 8 的另一半)。
**为什么必须由运行接上。** 文档里写的是业务说法,不是库里的表、列和 SQL(见 ledger/docdraft)。取数路径只能来自一次真的跑过、
结果对得上的运行:查了什么、结果长什么样、报告引用了哪一条,都在这次运行的封存范围里。所以接上之后工作流里的取数节点照抄
运行里那条查询(跨轮变化的字面量按 certify.build_graph 的办法变成入口参数),文档只贡献定义。
**为什么只并定义、不改式子。** 草稿不知道取数,改写 expression 或指标 id 会破坏已经证明过的算法。并进同名或同义词的指标,
expression、id、单位这些原样保留;对不上的指标名进 warnings,由人决定是新建一条还是忽略,而不是让整次接入失败。
**为什么要记文档引用。** 定义的事实来源是文档里那几句原文。origin.documents 按指标定义里的引用汇总去重,记下 document_id、
chunk_id、ordinal 和逐字 quote:之后复核、追责都能落回具体段落,不必再相信「草稿就是这么写的」。ordinal 从库里补(草稿的
引用只带 chunk,段落序号只有 chunks 表知道),chunk 已被删掉时照抄引用里的值,读不到就留空。
**为什么这一路不发布、不发起运行、不写审计。** 接入只产出一份可试跑的草稿:发布是人的决定,发起运行是另一个动作。
它和 freeze 的区别只在定义从哪来、以及 origin 里多记了 draft_id 和 documents。
"""
from __future__ import annotations
from collections.abc import Mapping
from typing import Any
from sqlalchemy import select
from app.db.models import Run
#: 接不上时的说法(给人看)
NOT_FOUND = "运行记录不存在,或没有权限读这次运行"
NOT_SUCCEEDED = "这次运行没有成功结束,不能接上文档草稿"
NOT_MATCHED = "这次运行还没有比对口径,比对完才能把文档草稿接上取数"
NO_QUERIES = "这次运行的报告没有引用任何查询结果,没有可接上的取数"
SNAPSHOT = "查询快照读不出来(文件缺失或与哈希不一致),不能接上文档草稿"
UNPARSED = "查询无法规范化({reason}),不能接上文档草稿"
NOT_MERGED = "这次运行没有单行结果的数值列,草稿里的定义没有可并入的口径卡"
DESCRIPTION = ("从业务文档起草的口径:定义来自文档草稿,{n} 个指标,取数路径接自运行 {run_id};"
"经人工审核后再发布")
class AttachRefused(Exception):
"""接不上。status 是给接口用的 HTTP 状态(现在都是 409),message 给人看。"""
def __init__(self, status: int, message: str) -> None:
super().__init__(message)
self.status = status
self.message = message
@property
def status_code(self) -> int:
return self.status
def _citation_rows(payload: dict[str, Any]) -> list[dict[str, Any]]:
"""草稿各指标的定义引用,按 (document_id, chunk, quote) 去重,先后照草稿。"""
rows: list[dict[str, Any]] = []
seen: set[tuple[str, str, str]] = set()
metrics = payload.get("metrics")
for metric in metrics if isinstance(metrics, list) else []:
if not isinstance(metric, Mapping):
continue
definition = metric.get("definition")
citations = definition.get("citations") if isinstance(definition, Mapping) else None
if not isinstance(citations, list):
citations = metric.get("citations")
for citation in citations if isinstance(citations, list) else []:
if not isinstance(citation, Mapping):
continue
chunk_id = citation.get("chunk") or citation.get("chunk_id") or citation.get("chunkId")
quote = citation.get("quote")
if not isinstance(chunk_id, str) or not chunk_id:
continue
if not isinstance(quote, str) or not quote.strip():
continue
document_id = str(citation.get("document_id") or "")
key = (document_id, chunk_id, quote)
if key in seen:
continue
seen.add(key)
ordinal = citation.get("ordinal")
rows.append({"document_id": document_id, "chunk_id": chunk_id,
"ordinal": ordinal if isinstance(ordinal, int) else None, "quote": quote})
return rows
async def _documents(session: Any, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""引用补上库里记的 document_id / ordinal(见模块说明);库里查不到的照抄引用里的值。"""
from app.db.models import Chunk
ids = list(dict.fromkeys(row["chunk_id"] for row in rows))
found: dict[str, tuple[str, int]] = {}
if ids:
for chunk_id, document_id, ordinal in (await session.execute(
select(Chunk.id, Chunk.document_id, Chunk.ordinal).where(Chunk.id.in_(ids)))).all():
found[str(chunk_id)] = (str(document_id), int(ordinal))
for row in rows:
if row["chunk_id"] in found:
row["document_id"], row["ordinal"] = found[row["chunk_id"]]
return rows
async def attach(session: Any, *, payload: dict, name: str, run_id: str, draft_id: str = "",
principal: Any = None) -> dict:
"""把文档草稿接上一次真实运行,落库成新的草稿工作流。
返回 {workflow_id, version, metrics, warnings}:metrics 是口径卡上并完定义之后的指标(id / expression 没动),warnings 是
合并时对不上的那些指标(原样交给界面)。不能接时抛 AttachRefused(409)。payload 的形状是草稿接口交出来的那一份:
{question?, metrics: [docdraft 的指标对象]}。不发布、不发起运行、不写审计。
"""
from app.api.deps import can_read_run, current_principal, ensure_role
from app.api.evidence import _sealed
from app.core.artifact_store import graph_hash, load
from app.db.models import DataSource, Workflow, WorkflowVersion
from app.ledger import certify, docdraft, store
ensure_role("builder")
principal = principal if principal is not None else current_principal()
run = await session.get(Run, run_id)
if run is None or not await can_read_run(principal, run):
raise AttachRefused(409, NOT_FOUND)
if run.status != "succeeded":
raise AttachRefused(409, NOT_SUCCEEDED)
recorded = await store.latest(run_id)
if recorded is None or recorded.content is None:
raise AttachRefused(409, NOT_MATCHED)
queries = certify.referenced_queries(recorded.content)
if not queries:
raise AttachRefused(409, NO_QUERIES)
kinds = {n: k for n, k in (await session.execute(select(DataSource.name, DataSource.kind))).all()}
# 封存的查询快照(和 freeze 同一个读法):比对工件只认封存范围内的查询,这里再按形状解析一次
await _sealed(run_id)
shapes: list[certify.Shape] = []
snaps: list[dict[str, Any]] = []
for artifact in queries:
try:
snap = load(artifact)
except ValueError:
raise AttachRefused(409, SNAPSHOT) from None
shape = certify.shape_of(snap, kinds)
if shape is None:
raise AttachRefused(409, SNAPSHOT)
if shape.problem:
raise AttachRefused(409, UNPARSED.format(reason=shape.problem))
shapes.append(shape)
snaps.append(snap)
question = payload.get("question")
if not isinstance(question, str) or not question.strip():
question = name
graph, _fields, _metrics, _multi = await certify.build_graph(
shapes=shapes, snaps=snaps, kinds=kinds,
labels=lambda snap, source: certify._labels(session, snap, source),
name=name, question=question)
# 定义并进同名 / 同义词的指标;表达式与 id 不动(见模块说明)
drafts = payload.get("metrics")
drafts = drafts if isinstance(drafts, list) else []
card = next((n for n in graph.get("nodes") or []
if isinstance(n, dict) and n.get("type") == "metrics"), None)
merged: list[dict[str, Any]] = []
warnings: list[str] = []
if card is None:
warnings.append(NOT_MERGED)
else:
config = card.setdefault("data", {}).setdefault("config", {})
card_metrics = config.get("metrics")
merged, warnings = docdraft.merge_definition(
card_metrics if isinstance(card_metrics, list) else [], drafts)
config["metrics"] = merged
if name.strip():
config["caliber"] = name.strip()[:40]
documents = await _documents(session, _citation_rows(payload))
workflow = Workflow(
name=(name.strip() or "文档口径草稿")[:200],
description=DESCRIPTION.format(n=len(merged), run_id=run_id),
graph=graph, status="draft", tags=["doc_draft"],
origin={"run_id": run_id, "freeze": True, "sources": [{"run_id": run_id}],
"draft_id": draft_id, "documents": documents})
session.add(workflow)
await session.flush()
session.add(WorkflowVersion(workflow_id=workflow.id, version=1, graph=graph, graph_hash=graph_hash(graph),
note=f"从文档草稿接上运行 {run_id}"))
await session.commit()
return {"workflow_id": workflow.id, "version": 1, "metrics": merged, "warnings": warnings}
__all__ = ["AttachRefused", "attach"]
@@ -0,0 +1,149 @@
"""文档草稿接上一次真实运行(app/ledger/docattach.py)。
真的跑一次问数据(虚构店铺库),等后台比对做完,再把文档草稿接上这次运行:
- 取数路径来自运行,定义并进口径卡的同名指标,expression / id 一字不改;
- origin 记着用到的文档段落(document_id / chunk_id / ordinal / quote,引用去重)和 draft_id;
- 没成功、没比对、报告没引用查询的运行都接不上(409);
- 草稿里对不上的指标名进 warnings,不拦这一次接入;
- 只落草稿:不发布、不发起运行。
"""
from __future__ import annotations
import uuid
import pytest
from sqlalchemy import select
from app.core.artifact_store import graph_hash
from app.db.base import SessionLocal
from app.db.models import Chunk, Conversation, ConversationTurn, Document, Run, Workflow, WorkflowVersion
from app.engine.runner import run_manager
from app.ledger import docattach
from app.ledger import match as ledger_match
from tests import ledger_samples as S
#: 每个用例一句话的问题:问句进全站唯一的聚类,和别的用例用同一句会在 certify 的队列里互相看见
QUESTION = f"文档接上运行后卖了多少({uuid.uuid4().hex[:8]})"
START, END = "2026-09-01", "2026-09-08"
SQL = (f"SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' AND paid_at >= '{START}' "
f"AND paid_at < '{END}'")
@pytest.fixture(autouse=True)
async def engine_up(tmp_path):
await run_manager.setup()
await S.fresh_source(tmp_path / "shop.db")
yield
await ledger_match.drain()
await run_manager.shutdown()
async def ask(monkeypatch) -> Run:
"""问数据的一轮:建对话和轮次、跑一次探索运行、等比对做完。"""
async with SessionLocal() as session:
conv = Conversation(title="问销售", kind="chat")
session.add(conv)
await session.commit()
turn = ConversationTurn(conversation_id=conv.id, question=QUESTION)
session.add(turn)
await session.commit()
turn_id = turn.id
S.script(monkeypatch, "这一周销售额 [[v:Q1.r0.gmv]]。")
run = await run_manager.start(graph=S.explore_graph(SQL), input_payload={"question": QUESTION},
origin_kind="chat", origin={"conversation_id": conv.id, "turn_id": turn_id})
row = await S.wait(run.id)
assert row.status == "succeeded", row.error
async with SessionLocal() as session:
(await session.get(ConversationTurn, turn_id)).run_id = row.id
await session.commit()
await ledger_match.drain()
return row
async def document() -> tuple[str, str]:
"""一份业务文档和其中的一段原文(口径定义的事实来源)。"""
async with SessionLocal() as session:
doc = Document(title="销售口径说明", content="销售额按已支付订单统计,退款订单不计入。")
session.add(doc)
await session.flush()
chunk = Chunk(document_id=doc.id, ordinal=3, content="销售额按已支付订单统计,退款订单不计入。")
session.add(chunk)
await session.commit()
return doc.id, chunk.id
def payload(document_id: str, chunk_id: str, *, name: str = "gmv") -> dict:
citation = {"chunk": chunk_id, "document_id": document_id, "quote": "销售额按已支付订单统计"}
return {"question": QUESTION, "metrics": [{
"name": name, "synonyms": ["销售额"], "unit": "元",
"definition": {"text": "按已支付订单统计,退款不计入", "citations": [citation, dict(citation)]}}]}
async def test_attach_merges_the_definition_into_the_run_derived_draft(monkeypatch):
run = await ask(monkeypatch)
doc_id, chunk_id = await document()
async with SessionLocal() as session:
made = await docattach.attach(session, payload=payload(doc_id, chunk_id), name="周销售口径",
run_id=run.id, draft_id="draft-1")
assert made["version"] == 1 and made["warnings"] == []
[metric] = made["metrics"]
assert metric["id"] == "m1" and metric["expression"] == "cell(nodes.fetch, 0, 'gmv')"
assert metric["definition"]["text"] == "按已支付订单统计,退款不计入"
async with SessionLocal() as session:
wf = await session.get(Workflow, made["workflow_id"])
version = (await session.execute(
select(WorkflowVersion).where(WorkflowVersion.workflow_id == wf.id))).scalar_one()
assert wf.status == "draft" and wf.tags == ["doc_draft"] and wf.published_version is None
assert version.version == 1 and version.graph_hash == graph_hash(wf.graph)
assert version.note == f"从文档草稿接上运行 {run.id}"
card = next(n for n in wf.graph["nodes"] if n["type"] == "metrics")["data"]["config"]
[card_metric] = card["metrics"]
assert card_metric["id"] == "m1" and card_metric["expression"] == "cell(nodes.fetch, 0, 'gmv')", \
"草稿只并定义,不改取数路径"
assert card_metric["definition"]["text"] == "按已支付订单统计,退款不计入"
assert card["caliber"] == "周销售口径"
# 取数路径照抄运行:字面量都是常量、没有入口参数,SQL 原样
fetch = next(n for n in wf.graph["nodes"] if n["type"] == "tool")
assert fetch["data"]["config"]["args"]["sql"] == SQL and fetch["data"]["config"]["tool"] == S.tool()
# origin:来源运行、草稿 id、引用的文档段落(两条一样的引用去重,ordinal 从库里补)
assert wf.origin["run_id"] == run.id and wf.origin["freeze"] is True
assert wf.origin["sources"] == [{"run_id": run.id}] and wf.origin["draft_id"] == "draft-1"
assert wf.origin["documents"] == [{"document_id": doc_id, "chunk_id": chunk_id, "ordinal": 3,
"quote": "销售额按已支付订单统计"}]
assert "1 个指标" in wf.description and run.id in wf.description
async def test_attach_refuses_runs_that_are_missing_failed_or_not_matched(monkeypatch):
async with SessionLocal() as session:
session.add(Run(id="failed-run", status="failed", graph={}, input={}, output={}))
session.add(Run(id="unmatched-run", status="succeeded", graph={}, input={}, output={}))
await session.commit()
for run_id, message in (("nope", docattach.NOT_FOUND),
("failed-run", docattach.NOT_SUCCEEDED),
("unmatched-run", docattach.NOT_MATCHED)):
with pytest.raises(docattach.AttachRefused) as caught:
await docattach.attach(session, payload={}, name="周销售口径", run_id=run_id)
assert caught.value.status == 409 and caught.value.message == message
# 成功、也比对过,但报告没引用任何查询:没有可接上的取数
row = await S.explore(monkeypatch, S.ELSEWHERE, text="一共几家店,没有引用。")
async with SessionLocal() as session:
with pytest.raises(docattach.AttachRefused) as caught:
await docattach.attach(session, payload={}, name="周销售口径", run_id=row.id)
assert caught.value.status == 409 and caught.value.message == docattach.NO_QUERIES
async def test_a_metric_name_that_does_not_meet_the_card_goes_to_warnings(monkeypatch):
run = await ask(monkeypatch)
doc_id, chunk_id = await document()
async with SessionLocal() as session:
made = await docattach.attach(session, payload=payload(doc_id, chunk_id, name="毛利率"),
name="毛利口径", run_id=run.id)
assert len(made["warnings"]) == 1 and "毛利率" in made["warnings"][0]
[metric] = made["metrics"]
assert metric["id"] == "m1" and "definition" not in metric, "对不上的定义不往指标上写"
async with SessionLocal() as session:
wf = await session.get(Workflow, made["workflow_id"])
assert wf is not None and wf.status == "draft"
+259
View File
@@ -0,0 +1,259 @@
"""从业务文档起草口径(app/ledger/docdraft.py,/api/ledger/drafts…):草稿独立于工作流存在。
- 抽取先建一行 drafting、在后台跑模型,结果写回 payload;缺文档 422、一个草稿都不建;
- 草稿只产出定义:payload 里是 metrics / dropped / open_questions / alignment,没有 SQL;
- PATCH 整体换指标、消掉已答清的问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排。
模型一律 monkeypatch 掉(docdraft.extract 换成一个固定结果),测试不发真实请求。
"""
from __future__ import annotations
import copy
import sys
import types
import pytest
from httpx import ASGITransport, AsyncClient
from sqlalchemy import delete, select
from app.db.base import SessionLocal
from app.db.models import AuditEvent, CaliberDraft, Chunk, Document, Workflow
from app.ledger import docdraft
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": ["退款算不算已支付当天的"],
}
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}
@pytest.fixture
async def client():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
yield c
@pytest.fixture
async def documents():
"""建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。段落 id 带上文档 id,测试之间不撞。
测试结束删掉这几份文档、它们的段落和所有草稿。"""
made: list[str] = []
async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default",
chunks=((2, "退款率 = 已支付后退款的订单数 / 已支付订单数"), (1, "退款率按门店拆"))) -> str:
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))
await session.commit()
made.append(doc_id)
return doc_id
yield make
async with SessionLocal() as session:
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)
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])
monkeypatch.setattr(docdraft, "extract", extract)
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)
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 看
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 [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["alignment"]["new"] == ["已支付退款率"]
assert made["truncated"] is False
assert made["origin"] == {"documents": [doc], "guidance": "只看已支付的订单"}
# 草稿不写进工作流:库里没有从它建出的图
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"] == "已支付退款率"
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"
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
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"]})
assert res.status_code == 422 and "d-nope" in res.text
listed = (await client.get("/api/ledger/drafts")).json()
assert listed["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"]
fixed_metric = {**copy.deepcopy(METRIC), "open_questions": [], "name": "已支付退款率(按支付日)"}
res = await client.patch(f"/api/ledger/drafts/{draft_id}",
json={"title": "退款率口径", "metrics": [fixed_metric],
"resolved": ["按哪个时区结算", "退款算不算已支付当天的"]})
assert res.status_code == 200, res.text
made = res.json()
assert made["title"] == "退款率口径" and made["status"] == "path_pending"
assert [m["name"] for m in made["metrics"]] == ["已支付退款率(按支付日)"]
assert made["open_questions"] == [] and made["question_count"] == 0
# 结构不对的指标 422,草稿不动
bad = await client.patch(f"/api/ledger/drafts/{draft_id}", json={"metrics": [{"synonyms": ["x"]}]})
assert bad.status_code == 422
still = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()
assert [m["name"] for m in still["metrics"]] == ["已支付退款率(按支付日)"]
# 还有问题(只换指标、带着新问题)→ questions_open
res = await client.patch(f"/api/ledger/drafts/{draft_id}",
json={"metrics": [{**fixed_metric, "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"]
res = await client.post(f"/api/ledger/drafts/{draft_id}/dismiss", json={"note": "已经有口径了"})
assert res.status_code == 200 and res.json()["status"] == "rejected"
async with SessionLocal() as session:
event = (await session.execute(select(AuditEvent).where(
AuditEvent.action == "ledger.docdraft.dismiss", AuditEvent.subject_id == draft_id))).scalars().one()
assert event.subject_kind == "ledger_draft" and event.data["note"] == "已经有口径了"
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"]
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
only = (await client.get("/api/ledger/drafts", params={"status": "questions_open"})).json()["drafts"]
assert [d["id"] for d in only] == [one]
assert (await client.get("/api/ledger/drafts", params={"status": "nope"})).status_code == 422
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 unavailable(session, **kwargs):
raise docdraft.DraftUnavailable("还没有接入可用的起草模型")
monkeypatch.setattr(docdraft, "extract", unavailable)
body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
assert made["status"] == "drafting" 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"]
seen: dict = {}
async def attach(session, *, payload, name, run_id, draft_id):
seen.update(payload=payload, name=name, run_id=run_id, draft_id=draft_id)
return {"workflow_id": "wf-docdraft", "version": 1, "metrics": ["m1"], "warnings": []}
module = types.ModuleType("app.ledger.docattach")
module.attach = attach
monkeypatch.setitem(sys.modules, "app.ledger.docattach", module)
async with SessionLocal() as session:
session.add(Workflow(id="wf-docdraft", name="退款率口径"))
await session.commit()
try:
res = await client.post(f"/api/ledger/drafts/{draft_id}/attach", json={"run_id": "run-1"})
assert res.status_code == 200, res.text
assert res.json() == {"workflow_id": "wf-docdraft", "version": 1, "metrics": ["m1"], "warnings": []}
assert (seen["run_id"], seen["name"], seen["draft_id"]) == ("run-1", "销售口径.md", draft_id)
assert seen["payload"]["metrics"][0]["name"] == "已支付退款率"
made = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()
assert made["status"] == "attached" and made["workflow_id"] == "wf-docdraft"
assert made["workflow_name"] == "退款率口径"
finally:
async with SessionLocal() as session:
workflow = await session.get(Workflow, "wf-docdraft")
if workflow is not None:
await session.delete(workflow)
await session.commit()