路由参考
下表就是契约门禁里的路由表：路由增减而契约未写，测试即红。口径行（basis）原样随每个响应的 meta 返回。
路由
“任一层级”指带任何有效密钥即可调用，返回内容按层级过滤。
| 方法 | 路径 | 要求层级 | 返回 | 口径行（meta.basis） |
|---|---|---|---|---|
| GET | /v1/health | 无需密钥 | ok、service、service_version; meta 只含 api_version 与 request_id | 无 |
| GET | /v1/listings | 任一层级 | 游标分页的列表：items（每条带 provenance）、next_cursor、count；过滤 city / status / channel / source / motivation_tag / q; limit 上限 200 | listings visible to the caller's tier; one row per asset announcement under our permanent UID |
| GET | /v1/listings/{listing_uid} | 任一层级 | 单条 listing 及其 provenance | 同上 (listings) |
| GET | /v1/listings/{listing_uid}/passport | 任一层级 | 护照：listing、verification、distress_timeline、transactions、sources、disclosure、notice、changes、building | single-asset record: listing, verification state, distress timeline, transactions, lineage, change log |
| GET | /v1/listings/{listing_uid}/sources | 任一层级 | 来源谱系：解析到该标的的每条外部记录（source_system、source_url、first_seen、last_seen; source_id 仅 internal） | 同上 (passport) |
| GET | /v1/listings/{listing_uid}/brief | 任一层级 | 标的简报：brief（数据）与 markdown，附规则附录与 notice | 同上 (passport) |
| GET | /v1/coverage | 任一层级 | 按来源与城市的计数、司法字段完整度、三态分布、数据层状态；internal 另有实体计数与待解析队列 | counts and non-null ratios over rows visible to the tier, computed live at generated_at |
| GET | /v1/runs | internal | 管线运行记录：latest_by_source 与 recent | ingestion_runs rows as recorded by the pipelines |
| POST | /v1/calc/{kind} | 任一层级 | 测算：kind 为 investment / transfer / daiya / two_outcomes；结果一律为 估算 态，带 calc_version 与免责说明 | formula outputs from caller inputs; always an estimate |
| GET | /v1/methodology | 任一层级 | 本接口应用的规则：层级、可见性、状态说明、核验依据、来源分级、速率配额、城市归属口径 | rules this API applies; versioned with the service |
| POST | /v1/listings/{listing_uid}/report | 任一能看到该记录的层级 | 202；回执：report_uid、kind、status、received_at、due_at、due_hours | a dispute filed against one record; answered within due_hours |
| GET | /v1/reports | internal | 更正队列：items 与 counts (open / acknowledged / resolved / rejected) | open and answered disputes (internal tier) |
| POST | /v1/reports/{report_uid}/respond | internal | 答复一条请求（status、response、responder）；返回更新后的记录 | 同 report |
| GET | /v1/ops/overview | internal | 运营台：告警、源健康、三态趋势、事件流、更正队列、回测、城市；参数 city、days (7-180) | operations console: live water levels and counts over all rows, computed at generated_at over window_days (internal tier) |
| GET | /v1/listings/{listing_uid}/asof?at= | 任一层级 | 时点重现：该记录在 at 时刻的样子，由 changes_log 反向重建；含 fields 与 reverted 列表 | the record as it stood at the requested instant, rebuilt by reversing changes_log entries after it |
| GET | /v1/events | 任一层级 | 近期处置事件流（可按 city 过滤，limit 上限 200），附阶段说明 | recent distress events over rows visible to the tier, newest first |
| GET | /v1/observation/{period} | authorized 及以上 | 月度观察包（period 为 YYYY-MM 或 latest） | monthly observation pack per pilot city; an observation |
| POST | /v1/dossier | authorized 及以上 | 清单匹配：rows (client_ref / address / case_number / city / source_url) 进，每行的匹配结果与公开面时间线出；多候选如实报告 | client list matched to records by URL / case number / address; ambiguity reported, never guessed |
口径随行
数字从不单独出现。每条 listing 带一个 provenance 对象，契约门禁要求其中 source、updated_at、status、status_label 非空。
- source
- 来源系统标识（如 gpai、sdcqjy、amc_famc）
- source_tier
- 来源分级 A / B / C
- source_url
- 该记录最后读取的公开页
- confidence
- 0-1 置信度
- updated_at
- 该记录的数据时点
- status
- 三态之一：confirmed / estimated / unverified
- status_label
- 对应中文名：多源公告一致 / 估算 / 未核验
- status_note
- 该状态的说明，一律以“核验依据为公开公告的跨源一致；非登记簿核验，非现场核验”结尾
- verified_at
- 最近一次核验时刻（可为空）
- verification_status / price_status
- 双轴原始状态（事实维 / 价格维），供核对推导
- city_basis
- 城市归属口径：司法拍卖为 asset_location；授权供给为 debtor_registered_city（债务人注册地，不是资产所在地）
- rights
- 权利层级：public_record / internal_only / sellable
其它记录种类各有自己的必带字段：处置事件与交易带 source；变更记录带 source、actor、changed_at；披露评估带 source、assessed_at、basis_version；测算结果恒为 估算 态。任何响应里出现未登记形状的对象，门禁即红。