zhifu-platform/docs/reading-routes

源码阅读路线

代码依据：2026-09-30 当前工作区。每条路线以具体业务场景为入口，提供代码文件、关键函数、调用关系、数据状态和测试阅读位置。

路线入口

1. 一次咨询的全过程：消费者页面、消息接口、数据库事件、SSE 续传、人工接管与回复。适合作为共同入门路线。
2. Agent 如何完成任务：运行创建、发布配置、worker 调度、LangGraph、工具调用、补充信息与业务等待恢复。
3. 一笔换货申请如何完成：业务资格、方案版本、客户确认、主管审批、数量预占与 OMS 履约。
4. 资料与记忆如何参与回答：资料发布、混合检索、引用复验、客户授权与沟通习惯记忆。
5. 多个商家如何共用平台：租户与店铺、登录会话、资源归属、操作权限、后台复验与平台独立身份。
6. 模型资源与费用：并发预留、租户调度、token 与金额预占、实际用量结算、账单与双人审批。
7. 外部渠道与可靠消息：签名验证、身份关联、Inbox、Outbox、RabbitMQ、消费收据和渠道投递。
8. 运行管理与效果验证：应用启动、发布检查、心跳、监控、故障恢复入口、Agent 评测与检索评测。

跟踪方法

打开一条路线后，从图中的入口函数开始，在源码中寻找图上标注的下一次调用。每到一个节点，记录当前输入、身份、读取的数据、写入的数据和返回结果。遇到数据库任务、HTTP 或消息队列时，沿箭头上的说明进入对应接收端或工作进程。

后端图中以 modules/、core/、operations/、oms/ 开始的路径相对 src/zhifu/；frontend/、scripts/、tests/ 与 compose 文件从仓库根目录开始。各路线提供节点编号和源码导航，点击带行号的链接可以定位对应定义。

图中的连续箭头表示当前进程内的函数调用、返回后继续执行或带条件的分支；具体含义写在箭头上。间断箭头标注 HTTP、数据库持久记录、消息队列、框架回调或后续独立请求。函数名称和所有状态名称保持源码标识。

函数嵌套定义会注明所属外层函数，例如 build_graph.model 表示 build_graph 内部的 model。同一文件出现多个 execute_one 或 emit 时，以文件路径和所属类确认定义。内部 节点说明当前函数中的关键处理位置。

阅读每幅图后，用源码回答文末的三个检查问题，并查看相应测试用例中的输入、调用和断言。测试文件承担行为说明的作用；实际运行时遵循项目的环境要求、数据范围和模型调用限制。

交叉阅读位置

• 路线 1 到达 Agent worker 后，进入路线 2；遇到售后卡片、客户确认和审批时，进入路线 3。
• 路线 2 中的 search_knowledge、记忆读取、BudgetCallback 分别连接路线 4 与路线 6。
• 路线 3 的 BusinessEvent、消费收据和 OMS 请求连接路线 7；业务权限检查连接路线 5。
• 路线 8 根据运行记录、费用记录、检索资料版本和业务断言核对前面各条路线的结果。

已有的会话消息流程文档 提供完整对话时序，可以与路线 1、路线 2 配合阅读。

核对范围

本组文档按当前源码核对文件、函数、分支、持久记录与进程边界。文档检查覆盖 Mermaid 语法、本地链接及带行号的源码位置。本文档编写过程没有执行业务验收、外部履约或生成模型请求；测试文件链接供学员阅读。