总览 / 使用导读
这套文档怎么用
面向产品、运营、业务、开发、测试、第三方对接六类读者。先选你的角色，再看图例，最后按需查接口。
1. 选你的角色
产品 / 业务看能力边界
按业务域翻「这个域里有哪些业务对象、每个对象能做什么」→ 目录页每行都有中文摘要与在用状态，不用读代码。
运营看状态含义遇到「订单状态=3」「卡类型=2」不知道是什么？状态字典给出后端枚举里的原值与中文含义，并标出哪些接口会返回它。
开发（新接手）先看这一页渠道前缀怎么拼、鉴权头带什么、响应外层包装、分页参数真实字段名（是 pageNo 不是 pageNum）。
每张卡片顶部直接写「谁在用 / 需不需要登录 / 入参几个字段 / 读写哪几张表」，改字段前先确认影响范围。
测试 / 排查反查从数据表反查接口、从字段名反查接口，比按路径翻更快。
第三方对接（三省卡）外部平台接口三省一卡通平台 yikatongApi 的 70 条对接接口目录（含状态与响应示例），与本仓库接口分开看。
第三方 / 各端对接看对接方开放与对接域按对接方分组（银行 / 支付 / 景区 / 政务）；各端调用数量见前端调用总览。
2. 一张接口卡片怎么读
第一行＝方法 + 路径 + 渠道 + 状态标记；
第二行（人话）＝
第三行（影响面）＝谁在用 · 需不需要登录 · 入参/返回字段数 · 读写哪些表；
调用地址＝拼好的完整 URL，可复制 URL 或整条
请求 / 响应＝字段表（必填标红，枚举直接给值＝含义），可一键「只看必填」或复制成 Markdown；
实现细节＝调用链、数据表、源码注释、示例，默认折叠，给要看代码的人。
第二行（人话）＝
动作「业务对象」＋源码注释里的摘要；第三行（影响面）＝谁在用 · 需不需要登录 · 入参/返回字段数 · 读写哪些表；
调用地址＝拼好的完整 URL，可复制 URL 或整条
curl；请求 / 响应＝字段表（必填标红，枚举直接给值＝含义），可一键「只看必填」或复制成 Markdown；
实现细节＝调用链、数据表、源码注释、示例，默认折叠，给要看代码的人。
3. 标记图例（全站一致）
已确认在用 · 某端 7 个前端源码里找到调用点，卡片底部给出 文件:行 证据
本次扫描未发现调用 仅表示扫描范围内没有，不等于可以下线
免鉴权 源码
@Route(auth=false)，不校验登录态（共 430 个）旧版误判·未使用 旧站标了未使用，重扫发现有调用（共 45 个）
推断名 源码没有 javadoc，名称由提交说明/方法名推断（共 340 个）
幽灵接口·源码无此映射 源码里已注释/删除，旧文档还在写
无契约条目 连源码都没定位到，仅旧文档留了一行路径
4. 常用操作
⌘K / Ctrl+K / / | 聚焦搜索；↑↓ 选择、Enter 打开、Esc 关闭 |
j / k | 在本页接口卡片间上下跳转 |
| 只看必填字段 | 隐藏非必填行，选择会被记住 |
| 复制为 Markdown | 把字段表复制成 Markdown，直接贴进需求/评审文档 |
| 复制链接 / 收藏 | 链接可精确到单个接口；收藏与最近查看存在本机浏览器 |
| 深/浅 | 主题切换（跟随系统，也可手动） |
5. 三个最容易踩的坑
- 分页参数是
pageNo，不是pageNum：旧文档写错了 241 个接口，v2 已按源码修正。 - 「本次扫描未发现调用」不能当下线依据：只扫了 7 个前端仓库源码字面量，服务端互调、定时任务、未纳入的端都不在内。
- 生产域名未确认：文档里的完整 URL 用 dev 主机示意，见调用手册 §1。