diff --git a/backend/app/api/catalog.py b/backend/app/api/catalog.py index 8810486c..250a48ad 100644 --- a/backend/app/api/catalog.py +++ b/backend/app/api/catalog.py @@ -844,7 +844,9 @@ async def review_catalog_batch(source_id: str, payload: CatalogBatchReviewIn, async def catalog_table_runs(source_id: str, table: str, limit: int = Query(20, ge=1, le=catalog_review.RUNS_LIMIT_MAX), session: AsyncSession = Depends(get_session)) -> dict[str, Any]: - """用过这张表的运行(total 是几次运行),新的在前;取法同使用次数(catalog.table_usage)。""" + """用过这张表的运行,新的在前。按运行计:total 是几次运行,一次运行查了这张表几次都只算一次。和表清单的使用次数 + (catalog.table_usage)数的是同一批查询快照,但使用次数按查询计(同一次运行里查了两次算两次),所以使用次数可能比 total + 大。""" _, source = await _resolved(session, source_id) key, _ = await _table_key(session, source, table) return await catalog_review.table_runs(session, source, key, limit=limit) diff --git a/backend/app/data/catalog_review.py b/backend/app/data/catalog_review.py index 78eb3438..e9d47172 100644 --- a/backend/app/data/catalog_review.py +++ b/backend/app/data/catalog_review.py @@ -24,8 +24,8 @@ 一张表冲突、写不进去不影响别的表;路径不对、表不存在逐条报(results 和请求一一对应)。审阅的规则同单项审阅 (catalog.review_item)。写进去之后影响数字的项被驳回了的,口径账本在后台标依据了它的答案「依据有变」 (catalog.after_review → ledger/recall,next-round 02 做法 7 二)。 -- **被哪些运行用过**(table_runs,GET /catalog/{table}/usage):取法同使用次数(catalog.query_snapshot_tables),按运行 - 去重,新的在前;total 是运行次数。 +- **被哪些运行用过**(table_runs,GET /catalog/{table}/usage):和使用次数数的是同一批查询快照(catalog.query_snapshot_tables), + 但按运行去重,新的在前;total 是运行次数。使用次数按查询计,同一次运行里查了几次这张表,使用次数就比 total 多几。 - **进度**(review_progress,GET /catalog/review-progress):常用表(使用次数前 TOP_N 张,和起草对话框「使用次数最多的 20 张表」是同一批:catalog.default_tables 的取法,用到的不够 TOP_N 张时按表结构的顺序补齐)、全部、影响数字的项各自的 确认情况。项的范围和队列一样:表结构里没有的表、列不算。 @@ -391,7 +391,8 @@ async def review_batch(session: AsyncSession, source: Any, items: Iterable[Batch async def table_runs(session: AsyncSession, source: Any, table: str, *, limit: int = 20) -> dict[str, Any]: - """用过这张表的运行:{total, runs},新的在前(按开始时间,没开始的按建立时间)。取法同使用次数。""" + """用过这张表的运行:{total, runs},新的在前(按开始时间,没开始的按建立时间)。数的是和使用次数同一批查询快照 + (catalog.query_snapshot_tables),但按运行去重:total 是运行次数,使用次数按查询计、可能比它大。""" run_ids = {run for run, hit in await catalog.query_snapshot_tables(session, source) if table in hit} if not run_ids: return {"total": 0, "runs": []} diff --git a/backend/tests/test_catalog_review_queue.py b/backend/tests/test_catalog_review_queue.py index 239694d2..107528d7 100644 --- a/backend/tests/test_catalog_review_queue.py +++ b/backend/tests/test_catalog_review_queue.py @@ -359,6 +359,27 @@ async def test_table_usage_lists_runs_newest_first(client): assert (await client.get(f"{_base(sid)}/ghost/usage")).status_code == 404 +async def test_usage_counts_queries_and_the_runs_list_counts_runs(client): + """两个数口径不同、说明照实:表的「使用次数」按查询计(同一次运行里查了两次算两次),「用过这张表的运行」按运行计。 + 接口说明以前写「取法同使用次数」,看着该是同一个数,验收时 4 对 3 对不上。""" + sid = await _source() + async with SessionLocal() as session: + name = (await session.get(DataSource, sid)).name + runs = await _use(sid, name, {"orders": 3}) + async with SessionLocal() as session: + session.add(Artifact(id=uuid.uuid4().hex, run_id=runs[0], kind=catalog.QUERY_SNAPSHOT_KIND, + meta={"source_id": sid, "source": name, "tables": ["orders"]})) + await session.commit() + listed = (await client.get(f"/api/datasources/{sid}/catalog")).json() + assert next(t for t in listed["tables"] if t["table_name"] == "orders")["usage"] == 4 + assert (await client.get(f"{_base(sid)}/orders/usage")).json()["total"] == 3 + doc = _fastapi_app.openapi()["paths"]["/api/datasources/{source_id}/catalog/{table}/usage"]["get"]["description"] + assert "取法同使用次数" not in doc and "按运行" in doc and "按查询" in doc, doc + from app.data import catalog_review + + assert "取法同使用次数" not in (catalog_review.table_runs.__doc__ or "") + + # -------------------------------------------------------------------------- # 进度 # -------------------------------------------------------------------------- diff --git a/frontend/src/lib/terms.ts b/frontend/src/lib/terms.ts index c42470aa..f3f335eb 100644 --- a/frontend/src/lib/terms.ts +++ b/frontend/src/lib/terms.ts @@ -2311,7 +2311,7 @@ export const CATALOG_TEXT = { missing: '表结构中已没有这张表', noCatalog: '没有目录', usage: (n: number) => `使用 ${formatNumber(n)} 次`, - usageHint: '被运行查询过的次数,同一次运行中结果相同的重复查询只算一次', + usageHint: '按查询算:被运行查询过的次数,同一次运行里查了几次算几次(结果相同的重复查询只算一次);「用过这张表的运行」按运行算,两个数可能不一样', relationCount: (n: number) => `${formatNumber(n)} 个关联`, countTitle: (label: string, n: number) => `${label} ${formatNumber(n)} 项`, noMatch: '没有符合条件的表',