代码图解

解决什么问题

接手一个陌生仓库时，最常见的困境是：文档缺失或过期，README 停留在两年前的版本，架构图散落在各处截图里。通读代码效率低，靠猜则容易得出错误结论——而且这种错误很难被发现。

代码图解把「理解一个系统」变成一件可核查的事：生成一份自包含的 HTML 报告，覆盖架构图、调用链、ER 图、安全链路、部署流水线、依赖地图等十个维度。每个图元素都绑定真实的 file:line 引用，点击即可看到代码片段。报告遵循「宏观 → 核心链路 → 微观」的阅读路径——先给分层地图，再追踪一两条核心业务流的完整跳转，最后落到配置、错误码、鉴权拦截点这些细节。

工作流程

• 扫描取证：scan_project.py 离线预填依赖清单、带行号的配置键、入口点候选、路由与数据模型候选，写入 report_input.json，全程仅用标准库。
• 图先行：把组件归入接入层、业务层、数据层等，节点和边分别引用定义处与调用点的 file:line。
• 线贯穿：挑 1–3 条核心业务流，从入口到响应逐步实际读代码核实每一跳，并附关键代码片段。
• 点突破：补全 config、data_model、security、errors、deploy 等段落。
• 渲染输出：build_report.py 生成清新配色的 SVG 架构图、ER 图与 HTML 时间线，内联 CSS，不发起任何外部请求。

适用边界

• 结论必须有证据：任何无法用读代码证实的事实，标注为「推测（待验证）」而非断言。报告的价值在于可核实，堆不出来的部分宁可留空。
• 适合中大型仓库的理解与交接场景；超大仓库需调 --max-files 参数，扫描结果以已提取的事实为准。
• schema 是开放的：消息队列、状态机、测试覆盖等维度，可在 report_input.json 追加键并在渲染器中扩展分支。
• 生成的是理解产物而非活文档，代码变更后需要重新扫描更新。