codebase-design audit

booking-backend
架构审计报告

Matt Pocock codebase-design 视角下,对 luying-booking-backend 全部 18 个源文件的模块深度评估。识别 6 个重构建议,dev 估时总计约 6.5 天。

审计日期
2026-06-21
源文件
18
重构建议
6
dev 估时
~6.5
01 / 方法论

codebase-design 视角

词汇约定(严格使用)

module vs. component/service

任意有 interface + implementation 的单元。可以是函数、类、包或跨层切片。

interface vs. API/signature

调用方需要知道的一切:签名 + 不变量 + 错误模式 + 性能特征。

depth

多少行为藏在多小的接口后面。深度 = 调用方的 leverage。

seam Michael Feathers

可在不修改此处的前提下改行为的位置。seam 放哪是独立的设计决策。

adapter

坐在 seam 上满足 interface 的具体物。描述「角色」而非「内容」。

leverage / locality

leverage = 调用方收益;locality = 维护者收益(改动 / bug / 知识集中在一处)。

三个判断尺

RULE 01
deletion test

删掉这个 module,复杂度集中消失 = pass-through;散落到 N 个 caller = earning its keep。

RULE 02
interface is the test surface

调用方和测试穿过同一个 seam。接口越复杂,能测的越少。

RULE 03
one/two adapter rule

一个 adapter 是假 seam(hypothetical);两个 adapter 是真 seam(real)。

02 / 热力图

18 个源文件 · 深度评估

悬停 / 点击单元格查看评估理由。

← 悬停单元格查看详情
03 / 重构建议

6 个 finding

按 ROI 排序 · 全部已发到 GitHub Issue · 标签 audit,enhancement

04 / 两类 issue 分流

与已有 bug 审计的关系

核心结论:两类 issue 不混淆

本项目此前已有 4 个真实 bug / 安全问题(label audit,security)。本次 codebase-design 视角的 6 个重构建议 完全不是 bug——代码功能正常,仅结构优化。dev 侧应优先修 bug,重构建议排期自定。

#37
🟡 中
clientIp() 信任 X-Forwarded-For 头
可伪造 IP 绕过业绩归属
#38
🟡 中
管理员接口无省区 scope 隔离
同一 admin 可操作任意省份 partner
#41
🟢 低
营地发布查重 TOCTOU 竞争
同窗口并发提交可能双写
#42
🟡 中
短信 mock 万能码依赖 NODE_ENV 守卫
存在误配绕过风险
05 / 排期

推荐 dev 排期

按"投入产出比 + 风险"排序,从最简单可逆的改动开始