Files

T

杭州明婳科技 0f13292a46 GLM 5.2修改版

2026-07-02 18:26:27 +08:00

178 KiB

Raw Blame History

xlgo v1.1.1 缺陷修复执行进度

执行依据：version_1.1.1_report.md（13 CRITICAL + 8 HIGH 权威清单）。执行顺序：P0 → P1 → P2 → P3。每项遵循"读全局 → 最小修复 → 机械验证 + 行为闭环 → 独立对抗性复审 → 三个全局问题写入本报告"的闭环节奏。本机约束：H:\worker 有 svn 干扰，go build/test 需 -buildvcs=false；gcc/cgo 已安装（2026-06-28），-race 现可运行；staticcheck 因 go1.24/1.25 版本不匹配暂不可用。

🚀 快速接续（下次开启先读这里）

当前状态（截至 2026-06-29）：P0 全部闭环 ✅ + P1 全部闭环 ✅ + P2 H6/H8 闭环 ✅（13 CRITICAL + 8 HIGH + H6 + H8）— 13 CRITICAL + 8 HIGH 全部修复并通过验证，P2 框架集成一致性阶段 H6（BaseRepo 接入 GetDBFromContext + 事务 join + 分页事务）与 H8（路由/health 统一 + Apply 幂等 + metrics 去调用顺序依赖 + 全局注册中心 atomic）均已闭环。

已闭环清单（每项含：修复 + 回归用例红绿验证 + -race/vet/gosec 通过）：

C6（csrf map 遮蔽）、C8（recover 返 200）、C4（storage 路径穿越）、C5（compress Zip-Slip）
C2（ws 死锁/panic/泄漏）、C1（cache/lock panic/泄漏）、C7（CORS 绕过）、C3（SSE 断连泄漏）
H2（默认关 TLS）、H1（不安全 RNG，删 RandString/RandDigit + Secure 系列）、C9b（刷新令牌 fail-closed）、H4a（限流误限流）
C10（config 全局 Manager 无锁置换 + 热重载绕过 Validate + StopWatcher 空函数）
C11（database 池泄漏 + Master/Replicas 无锁读 + 健康状态陈旧 + 包级 Close 仅关主库）
C9c（jwt 包级 DefaultJWT/tokenBlacklist 无锁置换 → atomic.Pointer）
H3（middleware/logger body OOM — 请求/响应 body 读取均封顶，下游仍得完整 body）
H7（logger 包级 Logger/sugar/apiLog/dbLog 写有锁读无锁 → atomic.Pointer + Field.Duration 签名修复）
C12（cron 数据竞争 + 重叠执行 + 漂移 + Weekly 跳周 + cron 解析缺陷）
C13（trace nil-panic + 未实现导出器/传播器 + Middleware 不更新 c.Request）
H5（handler BadRequest/InternalError 硬编 HTTP 400/500 绕过 Mode + 丢失 RequestID → 委托 response 体系）
H4b（CustomRateLimit goroutine 泄漏 → 登记入 customLimiters 表，StopRateLimiters/InitRateLimiters 统一停止）
H4c（RedisRateLimiter fail-open + 裸断言 → fail-closed 可配置 + comma-ok + LoginRedisRateLimit 改 fail-closed）
H6（BaseRepo 接入 GetDBFromContext + 读写分离 + 事务 join（r.tx + database.WithTx/TxFromContext）+ 分页单事务 + UpdateFields + QueryBuilder 克隆）
H8（全局注册中心 atomic.Pointer + ensureRegistry 守卫 + Apply 幂等 + metrics 经 SetMetricsMiddleware 在 Apply 内作首个全局中间件 + /health 收敛单一 healthHandler + handler.HealthCheck schema 对齐）

下一项：P2 H8 已闭环；进入 P3 清理（MEDIUM/MINOR 各项 + 全量补 -race）。

关键规则（CLAUDE.md 防复发约束）：

每项必跑 go test -race -buildvcs=false；行为变更写入 CHANGELOG [Unreleased] 升级说明；交付前独立 agent 对抗性复审（file:line 证据）。
新增测试依赖 github.com/alicebob/miniredis/v2 已在 go.mod（cache/jwt 真实闭环测试用）。
工作区改动未提交（用户未要求 commit 前不要自行 commit）。v1.1.1_fix_progress.md/v_1.1.1_fix.md/version_1.1.1_report.md 为 untracked 进度/依据文件。

待修复完整清单：见文末「待修复（按优先级）」。

✅ C6 `middleware/csrf.go` API CSRF 模式功能性失效（map 遮蔽）— P0

需求分析结果

API 模式 CSRF 整体不可用：CSRFForAPI() 闭包校验读的是局部 tokens map，而 GenerateAPIToken 写的是包级 tokens，两者从不相交 → 所有非安全方法请求被判"CSRF Token 无效"拒绝。叠加包级 map 只增不减/无过期/不消费（内存 DoS + 永久重放），以及 DoubleSubmitCookie cookie HttpOnly=true 与"JS 回填 X-CSRF-Token 头"自相矛盾。

方案设计摘要

删除 CSRFForAPI() 内的局部 tokens/mu 声明，统一绑定包级存储。
包级存储改 map[string]time.Time（token → 颁发时间），写锁内"查—删"原子完成单次消费；time.Since(issuedAt) > apiTokenTTL 拒绝过期；len>256 时懒清理过期项防内存增长。
DoubleSubmitCookie 的 cookie 改 HttpOnly=false（前端 JS 必须能读 cookie 才能回填头）；CSRF() cookie 模式维持 HttpOnly=true（token 经 body/上下文下发，非读 cookie）。
TTL 常量 apiTokenTTL = 30 * time.Minute；存储仍为进程内内存，注释声明仅适用单实例，多实例用 Redis SETEX+GETDEL。

涉及模块：middleware/csrf.go、middleware/middleware_test.go、middleware/csrf_internal_test.go。 DB 影响：无。API 影响：CSRFForAPI/GenerateAPIToken/DoubleSubmitCookie 行为变更（见下）。安全影响：正向——修复 CSRF 失效、防重放、防内存 DoS。潜在风险：见"已知风险"。

修改文件清单

middleware/csrf.go：新增 time 导入；重写 CSRFForAPI()（删局部 map、单次消费+TTL+懒清理）；重写 GenerateAPIToken（写包级 apiTokens）；包级存储改名 apiTokens/apiTokensMu + apiTokenTTL 常量；DoubleSubmitCookie cookie HttpOnly=false。
middleware/middleware_test.go：新增 respCode/apiCSRFToken helper 与 5 个回归用例。
middleware/csrf_internal_test.go（新）：TTL 过期分支用例（直接注入过期时间戳）。

实现内容摘要

颁发→校验闭环打通（同源包级 map）；单次消费（写锁内 delete）；TTL 30min；懒清理；DoubleSubmit cookie 可被 JS 读取。

三个全局问题（强制回答）

与既有体系契约一致？ 是。全程复用 response.Fail/Success/ServerError，未硬编状态码，未绕过响应模式系统。未引入 DB/路由/认证层面的新契约。
对下游意味着什么 / breaking change？ 行为变更（须 CHANGELOG 声明）：
- API 模式 CSRF token 现为单次消费——每次成功 POST 后需重新 GenerateAPIToken 颁发新 token。原实现整体不可用，故不存在"原本可用现被破坏"的真实回归，但下游若已绕过该中间件需重新评估。
- API token 现有 30min TTL。
- DoubleSubmitCookie 的 cookie HttpOnly 由 true 改 false（前端必须能读 cookie）。
- 无 API 签名变更、无配置变更、无 migration。
新并发/生命周期/泄漏隐患？ 包级 apiTokens+apiTokensMu（RWMutex）保护，查-删在同一写锁域原子；无 channel/goroutine/close 路径，无 send-on-closed 风险；懒清理在写锁内安全。无裸类型断言新增。-race 已于 2026-06-28 补跑通过（go test -race -buildvcs=false ./middleware/，1.980s 无竞争）。

代码审查结果：PASS

可读性/可维护性良好；命名清晰（apiTokens/apiTokensMu/apiTokenTTL）；注释说明单实例限制与多实例替代方案；无常量魔法值散落。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

CSRF 闭环真正生效（修复前整体失效，属安全功能缺失）。
单次消费防重放、TTL 防长期有效、懒清理防内存 DoS。
DoubleSubmitCookie HttpOnly=false 是该模式正确语义（非降级）；CSRF() 维持 HttpOnly=true。
token 仍由 crypto/rand 生成（generateCSRFToken 既有），非可预测。

测试审查结果：PASS

回归用例（均修复前红、修复后绿）：

TestCSRFForAPIIssueValidateCycle：颁发→携带 token POST 通过（C6a 核心闭环）。
TestCSRFForAPISingleUseConsumption：首次通过、重放拒绝（C6b 单次消费）。
TestCSRFForAPIInvalidAndMissing：缺失/伪造 token 拒绝。
TestCSRFForAPISafeMethodPasses：GET 放行。
TestCSRFForAPIITLExpiry（internal）：注入过期时间戳，TTL 分支拒绝（C6b TTL）。
TestDoubleSubmitCookieHttpOnlyFalse：cookie HttpOnly=false（C6c）。
TestDoubleSubmitCookieFrontendRefill：GET 下发→POST 匹配通过/不匹配拒绝（C6c 前端回填闭环）。

已知风险

API token 单实例内存存储，多实例部署需自行用 Redis SETEX+GETDEL 实现等价语义（已在源码注释声明）。
懒清理仅在"有校验请求且 map>256"时触发；纯颁发型攻击（只打 /csrf-token）在 30min 窗口内仍占内存，但有 TTL 上界，非无限增长。
~~-race 本机未跑（无 gcc/cgo），CI 须补。~~ → 已于 2026-06-28 补跑通过。

后续优化建议

多实例：提供可选的 CSRFStore 接口（内存 / Redis 双实现），Redis 用 SETEX 颁发、GETDEL 消费。
GUIDE.md 8.3 节 API 模式示例仅展示 CSRFForAPI() 与 GetCSRFToken(c)，未展示 GenerateAPIToken 路由注册，文档与"先取 token 再用"流程脱节，建议补示例（属文档项，非 C6 范畴）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line 复核：C6a/C6b/C6c 三项 CONFIRM 修复，回归测试真实复现原 bug，无新引入 CRITICAL/HIGH。唯一遗留（TTL 分支缺直接测试）已在本轮补齐。裁定：可交付 PASS。

✅ C8 `middleware/recover.go` panic 后 HTTP 状态丢失（默认 ModeBusiness 返 200）— P0

需求分析结果

默认 ModeBusiness 下，Recover/RecoverWithDetail 捕获 panic 后 response.FailWithCode → writeResp → httpStatusFor(CodeServerError) 返回 200，c.JSON(200,...) 已 flush 锁定状态；随后 c.AbortWithStatus(500) 因 w.Written()==true 成 no-op → 客户端收 HTTP 200 + body code:500，网关/APM/Prometheus 按 status 看不到 5xx。RecoverWithDetail 同病。ModeREST 无此 bug（statusForCode(CodeServerError)=500）。

方案设计摘要

改用 response.Custom(c, http.StatusInternalServerError, response.CodeServerError, msg, nil) 显式写 500——Custom 专为"精确控制 HTTP status、不受 Mode 影响"设计（mode.go:77-86），直接 c.JSON(httpStatus,...) 且保留 RequestID。去掉事后 AbortWithStatus（已 flush 后再设 status 是多余且语义错误），改 c.Abort() 仅置中止标志。

涉及模块：middleware/recover.go、middleware/middleware_test.go。DB 影响：无。API 影响：行为变更——panic 响应 HTTP 状态由 200(ModeBusiness) 改为 500，两模式一致；body 不变。安全影响：正向——APM/网关/监控可正确捕获 5xx。潜在风险：见"已知风险"。

修改文件清单

middleware/recover.go：Recover/RecoverWithDetail 两处 FailWithCode+AbortWithStatus 改 Custom+c.Abort()，补注释说明根因。
middleware/middleware_test.go：新增 ensureNopLogger helper（logger.Close() 重置为 Nop，防 logger 未初始化 nil deref 二次 panic）+ 3 个回归用例。

实现内容摘要

panic 闭环：真实触发 panic → Recover 捕获 → logger.Error 记录（带 request_id/stack）→ Custom 写 HTTP 500 + body code:500 + RequestID → c.Abort()。两模式均返回 500。

三个全局问题（强制回答）

与既有体系契约一致？ 是。response.Custom 是响应模式系统官方提供的"精确控制 HTTP status"出口（mode.go:77-79 注释明确），保留 RequestID/code 体系；旧 FailWithCode+AbortWithStatus 反而是"绕过模式系统硬改 status"的反模式（status 与 body code 来源不一致）。未引入 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明）：panic 响应 HTTP 状态由 200(ModeBusiness) 改 500，ModeREST 不变；body 不变。无 API 签名/配置/migration 变更。下游不会按"panic 返 200"适配，无真实回归。
新并发/生命周期/泄漏隐患？ 无。recover.go defer 内仅读单请求 c（无并发）+ logger.Error（既有裸读，非本次引入）。无新增包级全局、无 channel/goroutine。-race 已跑通过。

代码审查结果：PASS

最小改动、注释清晰说明根因；复用官方 Custom 出口而非另起硬编；无魔法值。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

修复监控盲区（5xx 不再被吞成 200），APM/网关可正确告警；RecoverWithDetail 注释已声明"生产不应使用、暴露敏感信息"；RequestID 保留便于链路追踪。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，已实跑验证）：

TestRecoverPanicReturns500：ModeBusiness 真实 panic，断言实际 HTTP 状态码=500（修复前=200）+ body code=CodeServerError + request_id 非空。
TestRecoverWithDetailPanicReturns500：同上覆盖 RecoverWithDetail（修复前=200）。
TestRecoverPanicRESTMode500：ModeREST 同样 500，锁定跨模式一致性。
红/绿已分别验证：临时回退修复后两用例均 status = 200, want 500 红；恢复后绿。

已知风险

边角（HTTP 固有局限，非本次引入）：若 handler 在 panic 前已 flush 部分响应，Custom 无法改写已 flush 的 status（gin responseWriter.WriteHeader 守卫），且会追加损坏 body。与旧实现等价（非回归）。加测试只会锁定"损坏 body"不良行为，故留作文档化已知局限，不作修复。
ensureNopLogger 调 logger.Close() 无 restore，依赖 logger 包既有"包级全局无锁置换"技术债（H7 范畴，非本次引入）；当前无受害测试，-race 通过。后续 H7 修复时一并处理。
staticcheck 因环境限制（二进制构建于 go1.24、模块要求 go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

H7 修复 logger 包级全局无锁置换后，ensureNopLogger 改为可 restore 的测试辅助。
若需覆盖"handler 已写响应后 panic"边角，可考虑在 Recover 内 if c.Writer.Written() { c.Abort(); return } 跳过追加损坏 body——属增强，非 C8 范畴。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line 复核 7 项（修复正确性 / Abort 替代 / Custom 副作用 / 跨模式 / 测试质量 / 全局契约 / 同类反模式遗漏）：无 CRITICAL/HIGH，两项 LOW（上述边角 + ensureNopLogger restore，均不阻断）。裁定：可交付 PASS。

✅ C4 `storage/storage.go` 路径穿越 + 无上传校验 + Get OOM — P0

需求分析结果

C4a 路径穿越：Local 的 Delete/Get/Exists 的 path 全程受控（filepath.Join 内含 Clean 但 .. 可逃逸根目录）→ 任意删/读/探测；Upload/UploadFromBytes 的 subdir 含 .. → 任意目录写（文件名服务端随机无法精确覆盖）。OSS 的 Delete/Get/Exists object key 未净化 → key 注入/越权。
C4b 无校验：无 file.Size 上限、无扩展名白名单、无 MIME 校验（evil.php、超大文件直传）。
C4c 全量读内存：Local Get 用 os.ReadFile、OSS Get 用 io.ReadAll，无上限 → OOM。

方案设计摘要

路径穿越（零配置默认安全）：LocalStorage 构造时算 rootAbs（filepath.Abs+Clean）；新增 safeJoin(parts...) 拒绝绝对路径/NUL + 前缀锚定（rootAbs+sep）；Delete/Get/Exists/Upload/UploadFromBytes 全部经之。OSS 新增 sanitizeObjectKey（拒绝空/NUL/../绝对路径，path.Clean，归一化 \→/）。
Get 读封顶（零配置默认安全）：maxReadBytes 默认 100MB（resolveMaxRead：n<0 不限，n==0 默认，n>0 用 n），io.LimitReader(f, max+1) 读后超限报错。
上传校验（opt-in，零值不限兼容）：新增 config.UploadPolicy{MaxSizeBytes, AllowedExts, AllowedMIMEs} 嵌入 Local/OSS config；AllowedMIMEs 非空时 http.DetectContentType 嗅探前 512B（取分号前主类型比较）并拼回头部。
HIGH（跨平台，复审发现）：OSS object key 拼接由 filepath.Join（Windows 产 \）改 path.Join + sanitizeObjectKey 归一化 \→/，保证 Windows/Linux 部署 key 一致。

涉及模块：config/config.go、storage/storage.go、storage/storage_security_test.go、storage/storage_path_internal_test.go。DB 影响：无。API 影响：Storage 接口/构造函数签名不变；行为变更（含 .. 的 path 被拒、Get 默认封顶 100MB、上传目录权限 0755→0750）。安全影响：正向。潜在风险：见"已知风险"。

修改文件清单

config/config.go：新增 UploadPolicy 类型；LocalStorageConfig/OSSStorageConfig 加 Upload/MaxReadBytes 字段（零值兼容）。
storage/storage.go：LocalStorage 加 rootAbs/policy/maxReadBytes + safeJoin + NewLocalStorage 算 rootAbs；Upload/UploadFromBytes/Delete/Get/Exists 全改；OSSStorage 加 policy/maxReadBytes + sanitizeObjectKey；Upload/UploadFromBytes/Delete/Get/Exists 全改；新增 validateUploadSize/Ext、sniffUploadMIME、resolveMaxRead、ErrPathTraversal/ErrInvalidPath；gosec G301 0755→0750、G304 #nosec。
storage/storage_security_test.go（新）：路径穿越 / Get 封顶 / 上传策略（大小/扩展名/MIME）/ 兼容性回归用例。
storage/storage_path_internal_test.go（新）：sanitizeObjectKey（含反斜杠归一化）+ resolveMaxRead 单元测试。

实现内容摘要

路径穿越闭环（safeJoin 前缀锚定 + OSS key 净化）；Get 封顶（LimitReader，默认 100MB）；上传校验 opt-in（大小/扩展名/MIME 嗅探拼回）；OSS key 跨平台归一化。

三个全局问题（强制回答）

与既有体系契约一致？ 是。Storage 接口不变、构造函数签名不变、facade/Manager 不变。新增配置走 config 体系（UploadPolicy 嵌入既有 Local/OSS config）。未引入 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：含 ../绝对路径的 path 被拒（合法相对路径不受影响）；Get 默认封顶 100MB（MaxReadBytes=-1 不限）；上传目录权限 0755→0750。新增可选配置 UploadPolicy/MaxReadBytes，零值不限以兼容现有下游。无 API 签名/配置必填项/migration 变更。
新并发/生命周期/泄漏隐患？ 无。LocalStorage/OSSStorage 构造后字段只读，无共享可变状态、无 channel/goroutine。safeJoin/sanitizeObjectKey 纯函数。-race 已跑通过。

代码审查结果：PASS

最小侵入修复穿越（前缀锚定是经典防穿越模式）；校验函数职责单一（DRY：Local/OSS 共用 validateUploadSize/Ext/sniffUploadMIME）；MIME 嗅探拼回正确；无魔法值（常量 defaultMaxReadBytes/mimeSniffPrefixLen）。独立复审未发现 CRITICAL。

安全审查结果：PASS

路径穿越闭环（C4a）：safeJoin 前缀锚定经 Windows drive-relative/UNC/反斜杠/大小写各边角验证不可绕过；OSS key 净化防注入。
上传校验（C4b）：opt-in 白名单 + MIME 嗅探防 evil.php 伪装。
Get 封顶（C4c）：默认 100MB 防 OOM。
gosec：G301 收紧 0750、G304 #nosec 留痕，0 issue。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestLocalStoragePathTraversal：根外放 canary，.. Delete/Get/Exists 全拒绝 + 断言 canary 未被删（复现"任意删/读/探测根外文件"）。
TestLocalStorageNormalPathStillWorks：正常相对路径不误伤。
TestLocalStorageUploadTraversalSubdir / UploadFromBytesTraversalSubdir：subdir 含 ../绝对路径拒绝 + 断言根外未创建目录。
TestLocalStorageGetReadLimit：超限 Get 拒绝、小文件通过。
TestLocalStorageUploadSizeLimit / ExtWhitelist / MIMESniff / UploadFromBytesPolicy：大小/扩展名/MIME 白名单。
TestLocalStorageZeroPolicyAllowsAll：零值不限（兼容性回归）。
TestSanitizeObjectKey / NormalizesBackslash / TestResolveMaxRead：纯函数单元。
红/绿验证：临时回退 safeJoin 前缀校验后，穿越用例复现"Delete 真删 canary / Upload 真建根外 evil 目录"全部红；恢复后绿。

已知风险

符号链接穿越（LOW，前置条件苛刻）：若 root 内已存在指向外部的 symlink，Get 会跟随读到根外。需保证攻击者无法在 root 内建 symlink（框架上传文件名服务端随机，不创建 symlink）。已在 NewLocalStorage 文档约束"root 应为框架独占"。
Get 默认封顶 100MB（LOW，行为变更）：下游读 >100MB 单文件到内存会失败，可配置 max_read_bytes: -1 不限。已 CHANGELOG 声明。
GetURL 未净化 path（无害）：仅字符串拼接返回 URL，无 fs/网络操作，无需净化（复审确认）。
包级 var storage Storage（LOW，预存冗余）：Init/Set 同步维护但读路径走 DefaultStorage.Get()，非本次引入，保留作兼容。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

若下游需读超大文件到内存，文档建议改用流式 API（当前 Get 返回 []byte，本质需全量驻留）。
UploadPolicy 可扩展为按 subdir 差异化（如头像严格、附件宽松）。
符号链接穿越若需硬防，可在 safeJoin 后 os.Lstat 检测 ModeSymlink，但会拒绝合法 symlink 用法，权衡后暂不引入。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + 实跑 8 个对抗性探查测试复核 9 项：C4a/C4b/C4c 全部验证有效，safeJoin 在 Windows 各边角不可绕过，MIME 拼回与 Get 封顶边界正确，测试真实复现原 bug。发现 1 项 HIGH（OSS key 用 filepath.Join 在 Windows 产 \，跨平台不一致，预存 bug）+ 3 项 LOW。HIGH 已修复（path.Join + sanitizeObjectKey 归一化 + 回归测试）；LOW 项已文档化/约束。裁定：修复 HIGH 后可交付 PASS。

✅ C5 `compress/compress.go` Zip-Slip + 解压炸弹 — P0

需求分析结果

C5a Zip-Slip：unzipFile 用 path.Join(dstDir, file.Name) 无逃逸校验，file.Name 可含 ../，os.Create 覆盖任意文件；且用 path.Join（POSIX）非 filepath.Join，Windows 分隔符处理不当。
C5b 解压炸弹：GzipDecompress（io.ReadAll）→ OOM；GzipDecompressFile/Unzip（io.Copy 写盘）→ 磁盘耗尽。三者无上限。

方案设计摘要

Zip-Slip（默认启用）：Unzip 算 absDst（Abs+Clean）；每个条目 filepath.FromSlash + 拒绝绝对路径/分隔符开头 + filepath.Join + 前缀锚定（absDst+sep）；拒绝符号链接条目（ModeSymlink）。
解压炸弹（默认上限 + 可配置）：新增 DecompressOptions{MaxBytes, MaxTotalBytes}（0=默认，-1=不限）。GzipDecompress 用 io.LimitReader；GzipDecompressFile/Unzip 用 io.CopyN 单条目封顶 + Unzip 累计封顶（remaining<=0 提前拒绝）。保留原签名（默认上限），新增 *WithOptions 变体。默认：单流/单条目 100MB，Unzip 累计 1GB。

涉及模块：compress/compress.go、compress/compress_security_test.go。DB 影响：无。API 影响：原签名保留，行为变更（Zip-Slip 拒绝、解压默认封顶）；新增 *WithOptions 变体。安全影响：正向。风险：解压大文件下游受默认封顶影响（可配置 -1）→ 已 CHANGELOG 声明。

修改文件清单

compress/compress.go：新增 DecompressOptions/resolveLimit/minLimit/ErrPathTraversal/ErrSymlinkEntry/ErrDecompressLimit；GzipDecompress→*WithOptions（LimitReader）；GzipDecompressFile→*WithOptions（CopyN）；Unzip→UnzipWithOptions（absDst 锚定 + symlink 拒绝 + 单条目/累计封顶）；gosec G110/G304/G122 #nosec。
compress/compress_security_test.go（新）：Zip-Slip / 绝对路径 / symlink 拒绝 / 合法条目不误伤 / 三类炸弹封顶 / GzipDecompressFile 封顶 / 往返兼容性回归用例。

实现内容摘要

Zip-Slip 闭环（前缀锚定 + symlink 拒绝）；解压炸弹封顶（LimitReader/CopyN 单条目 + Unzip 累计，默认 100MB/1GB，可配置 -1 不限）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。原 GzipDecompress/GzipDecompressFile/Unzip 签名保留，委托 *WithOptions（零值默认）。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：Unzip 拒绝含 ../绝对路径/symlink 条目（合法归档不受影响）；解压默认上限 100MB（单流/单条目）/1GB（Unzip 累计），超限返 ErrDecompressLimit，需更大文件用 *WithOptions 设 -1。无 API 签名/配置必填项/migration 变更。
新并发/生命周期/泄漏隐患？ 无。所有函数无状态、纯局部变量，无包级可变全局、无 channel/goroutine。-race 已跑通过。

代码审查结果：PASS

前缀锚定经典防 Zip-Slip；resolveLimit/minLimit -1 哨兵语义清晰；remaining<=0 提前拒绝避免 0 被当无限；原签名保留 + *WithOptions 扩展（DRY）。独立复审无 CRITICAL/HIGH。

安全审查结果：PASS

Zip-Slip 闭环（C5a）：前缀锚定经 Windows drive-relative/UNC/反斜杠/绝对路径各边角验证不可绕过；symlink 拒绝覆盖 zip symlink mode。
解压炸弹（C5b）：单条目 + 累计双重封顶；边界正确（恰好等于 cap 放行、超 1 拒绝）。
gosec：G110/G304/G122 全部 #nosec 留痕正当，0 issue。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestUnzipZipSlipRejected：../canary.txt 条目拒绝 + 断言 dst 外 canary 未被覆盖（复现原 bug）。
TestUnzipAbsolutePathRejected：绝对路径条目拒绝。
TestUnzipNormalEntriesWork：合法相对路径不误伤。
TestUnzipSymlinkRejected：symlink 条目拒绝。
TestGzipDecompressBombLimit/TestGzipDecompressFileBombLimit：超限拒绝、-1 不限、默认放行。
TestUnzipEntryBombLimit/TestUnzipTotalBombLimit：单条目/累计封顶。
TestZipUnzipRoundTripStillWorks：合法归档往返兼容。
红/绿验证：回退前缀锚定后 Zip-Slip 用例复现"canary 被覆盖成 pwned"；回退 resolveLimit 为 -1 后三个炸弹用例全部"超限不拒绝"红；恢复后绿。

已知风险

超限条目残文件未清理（LOW）：超限判定在 io.Copy 之后，已写入的 ~cap 字节残文件残留。受 entryLimit/totalLimit 双重封顶，最多 ~100MB+1/条，非炸弹。可接受。
Zip 侧 defer Close 吞错（M16，非 C5 范围）：compress.go:202/205 defer archive.Close()/defer zipWriter.Close() 丢弃错误，刷盘失败返回 nil 产损坏 zip。属 M16，独立后续项。
Zip 条目名用 os.PathSeparator（Windows 产 \，非 zip 规范，非 C5 范围）：xlgo 自产 zip 经 xlgo Unzip 可解（FromSlash 处理），但严格第三方解压器可能不认。跨平台兼容性瑕疵，独立后续项。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

超限后清理残文件（os.Remove(target) on limit error）。
M16：Zip 写侧 defer Close 错误向上传播；条目名统一用 /（zip 规范）。
补 Windows 反斜杠/驱动器相对/UNC 条目名测试（probe 已证被拦）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + 实跑 22 种攻击载荷复核 7 项：C5a/C5b 核心逻辑正确、边界经实测验证、红绿到位、无并发隐患、#nosec 正当。无 CRITICAL/HIGH。两项纪律补全（CHANGELOG C5 升级说明 + GzipDecompressFile 炸弹测试）已补齐。裁定：可交付 PASS。

✅ C2 `ws/ws.go` Hub 死锁 + send-on-closed panic + 半开连接泄漏 — P0

需求分析结果

C2a 广播失败即死锁：Hub.Run 的 broadcast 分支中 conn.Send 失败时 h.unregister <- conn，而 unregister 唯一消费者是同一 Run goroutine 的 select → 永久阻塞，整个 Hub 卡死。触发现实：向任一已关闭连接广播即触发。
C2b Close() 与 Send() send-on-closed panic：Close 同时 close(c.closeChan) 与 close(c.send)；并发 Send 的 select 含 c.send <- data 与 <-c.closeChan，c.send 关闭后 send case 永久就绪且 panic，Go select 伪随机可能选中它。
C2c 无 deadline/pong 致 goroutine 泄漏：SetReadDeadline/SetWriteDeadline 有定义从不内部调用；发 ping 但无 SetPongHandler、无读超时 → 半开连接 ReadMessage 永久阻塞、goroutine 泄漏。

方案设计摘要

C2a 死锁：Hub.Run broadcast 分支改持写锁单次遍历，失败连接行内 delete + conn.Close()，去掉向 unregister channel 回环。
C2a-residual（独立复审发现 HIGH）：Send 改非阻塞投递（select { case send<-data; default: return ErrSendBufferFull }），避免持写锁期间因慢消费者/已死连接（writePump 退出但 closeChan 未关、send 缓冲满）阻塞最长 pongWait 导致 Hub stall。
C2b panic：Close() 仅 close(c.closeChan) + c.conn.Close()，不再 close(c.send)；Send 前置 IsClosed() 快速失败 + select 兜底。
C2c 泄漏：Handle 读循环前置 SetReadDeadline(pongWait) + SetPongHandler（重置读 deadline）；writePump 每次写前 SetWriteDeadline(writeWait)、ping 周期 pingPeriod = pongWait*9/10；写失败主动 Close 触发读循环退出，加速半开连接回收。
常量：pongWait=60s/pingPeriod=54s/writeWait=10s；导出错误 ErrSendBufferFull。

涉及模块：ws/ws.go、ws/ws_concurrency_test.go、ws/ws_send_internal_test.go。DB 影响：无。API 影响：公共 API 签名不变；行为变更（Send 非阻塞、广播踢除慢消费者、心跳超时）。安全影响：正向。风险：见"已知风险"。

修改文件清单

ws/ws.go：新增常量与 ErrSendBufferFull；Connection.Send 改非阻塞 + IsClosed 快速路径；Connection.Close 不再 close send；Handle 读循环前置 deadline+pong handler；writePump 写 deadline + 写失败主动 Close；Hub.Run broadcast 持写锁行内清理。
ws/ws_concurrency_test.go（新）：并发 Close/Send 不 panic、Send-after-Close 返错、Hub 广播不死锁且清理失败连接、广播到达客户端、半开连接 OnClose、Close 后非阻塞。
ws/ws_send_internal_test.go（新）：internal test 直接验证 send 缓冲满非阻塞返 ErrSendBufferFull。

实现内容摘要

死锁闭环（行内清理 + 非阻塞 Send）；panic 消除（不 close send）；半开连接心跳超时回收（deadline + pong + 写失败 Close）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API（Hub/Connection/Handle 等）签名不变；Send 语义从阻塞改非阻塞（行为变更已 CHANGELOG 声明）。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明）：Send 缓冲满返 ErrSendBufferFull 而非阻塞；Hub 广播踢除慢消费者；连接启用心跳超时。无 API 签名/配置/migration 变更。下游若依赖阻塞 Send 需改重试。
新并发/生命周期/泄漏隐患？ 无新增。Send 非阻塞消除持锁阻塞；Close 用 sync.Once 幂等；writePump 写失败主动 Close 加速回收。-race 已跑通过。

代码审查结果：PASS

非阻塞 Send 是标准 ws hub 模式（gorilla 官方示例）；行内清理避免回环死锁；deadline+pong 心跳是 ws 健壮连接标准做法。独立复审无 CRITICAL/HIGH（残留 HIGH 已修复）。

安全审查结果：PASS

死锁/panic/泄漏三类并发缺陷闭环；半开连接不再永久占用 goroutine；Close 幂等安全。gosec G104 #nosec 正当，0 issue。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestConnectionCloseConcurrentSendNoPanic：2000 次并发 Send+Close 不 panic（修复前 send-on-closed panic + race detected）。
TestSendAfterCloseReturnsError：Close 后 Send 返错。
TestHubBroadcastDeadConnectionNoDeadlock：广播到已关闭连接不死锁且行内清理（修复前 Count=1 残留 + Hub stall）。
TestHubBroadcastReachesClients：广播到达正常客户端。
TestSendNonBlockingBufferFullInternal：send 缓冲满立即返 ErrSendBufferFull（修复前阻塞 2s 超时）。
TestSendNonBlockingOnClosed：Close 后 Send 不阻塞。
TestHalfOpenConnectionExitsOnClose：客户端关闭后服务端 OnClose 被调用。
红/绿验证：回退 close(send) 后并发测试复现 "send on closed channel panic + race detected"；回退非阻塞 Send 后 internal test 复现"缓冲满阻塞 2s"；恢复后全绿。

已知风险

TOCTOU 消息丢失（LOW，可接受）：Send 的 IsClosed 检查与 select 之间连接被 Close，select 选中 send 分支投递成功返回 nil，消息进入无消费者的缓冲可能丢失。非 panic，Hub 行内清理兜底。ws 广播 best-effort 语义下可接受。
Hub.Run 无退出机制（MEDIUM，范围外）：goroutine 永久运行，无 Run(ctx)/Stop。框架级 Hub 生命周期未闭环，后续加 Run(ctx) 变体。
upgrader.CheckOrigin 默认 true（N7 CSWSH，范围外）：既有代码，SetCheckOrigin 已提供覆盖入口，独立后续项。
writePump if !ok 死代码（LOW）：send 不再 close，ok 永真，分支不可达但保留作防御（已注释）。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

Hub.Run(ctx) 变体支持优雅停 Hub。
CheckOrigin 默认改为校验 Origin（N7）。
移除 writePump !ok 死代码或保留防御注释。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line 复核 9 项：C2b/C2c 主体修复正确；C2a 永久死锁已消，但发现 C2a-residual（HIGH）——持写锁调阻塞 Send 在 writePump 退出/closeChan 未关/缓冲满时阻塞最长 60s 致 Hub stall，且原测试未覆盖。修复（Send 改非阻塞投递 + 补 internal test 红绿验证）后，复审 HIGH 已闭环。另 2 项 MEDIUM（Hub.Run 无退出、CheckOrigin 默认）+ 1 LOW（死代码）为范围外提示。裁定：修复 HIGH 后可交付 PASS。

✅ C1 `cache/lock.go` 分布式锁 panic/泄漏/裸断言 — P0

需求分析结果

C1a WithLockAutoExtend closed-channel panic + 锁泄漏：done 无缓冲，子 goroutine defer close(done)；ctx 取消或 ExtendLock 失败提前返回时 done 已 closed，父在 fn() 后 done <- struct{}{} → send-on-closed panic，Unlock 不执行，锁持有到 TTL。
C1b 裸类型断言：NewLock/Unlock/ExtendLock 三处 result.(int64) 无 comma-ok，Redis 返回 nil/非整型时 panic。
C1c TryLock 忽略 ctx：time.Sleep(retryInterval) 不响应 ctx.Done()，最长阻塞 maxRetry*retryInterval。
C1d 无 fencing token：Token 是随机 UUID 非单调递增，TTL 到期后双 worker 并发执行无防护（设计局限）。

方案设计摘要

C1a：续期改"父关停 + 子 ack"双 channel（close(stop) + <-finished）；Unlock 用 context.WithTimeout(context.Background(), 5s) 派生超时（原 ctx 可能已取消致 Unlock 失败再泄漏）；fn panic 路径加 defer 兜底（独立复审发现 CRITICAL：无 defer 时 fn panic → close(stop) 不执行致续期 goroutine 永久泄漏 + Unlock 不执行致锁泄漏）。
C1a 一致性（HIGH）：WithLock 的 defer Unlock(ctx, token) 同改 Background 超时 ctx + defer 兜底，与 WithLockAutoExtend 一致。
C1b：新增 toInt64(v) 辅助函数（comma-ok），三处断言改用之，失败返 ErrLockUnexpectedResult。
C1c：TryLock 的 time.Sleep 改 select { ctx.Done()/time.After }。
C1d：LockToken 文档化设计局限（fencing token 需 Redis INCR + 下游校验，框架无法单方面保证），不引入破坏性数据结构变更。

涉及模块：cache/lock.go、cache/lock_concurrency_test.go、go.mod（新增 miniredis 测试依赖）。DB 影响：无（Redis key 语义不变）。API 影响：公共 API 签名不变；行为变更（解锁用 Background ctx、panic 也释放锁、TryLock 响应 ctx）。安全影响：正向。风险：无。

修改文件清单

cache/lock.go：新增 toInt64/ErrLockUnexpectedResult；NewLock/Unlock/ExtendLock 三处断言改 comma-ok；TryLock 改 select；WithLockAutoExtend 改双 channel + defer 兜底 + Background Unlock；WithLock 改 Background Unlock + defer 兜底；LockToken 文档化 C1d。
cache/lock_concurrency_test.go（新）：用 miniredis 真实闭环测试 ctx 取消不 panic/不泄漏、fn 正常释放、续期保活、阻断竞争者、fn panic 释放锁、WithLock ctx 取消释放锁、加解锁续期闭环、TryLock 响应 ctx。
go.mod：新增 github.com/alicebob/miniredis/v2（测试依赖）。

实现内容摘要

send-on-closed panic 消除（双 channel）；fn panic/ctx 取消均释放锁（defer + Background Unlock）；裸断言防护（toInt64）；TryLock 响应 ctx；fencing token 文档化。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名全不变；新增 toInt64/ErrLockUnexpectedResult（导出 error，非 breaking）。database.RedisClient 是预存包级 var，测试直接赋值是预存模式（Init/Close 也直接赋值）。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：WithLockAutoExtend/WithLock 解锁用独立 Background 超时 ctx（原 ctx 取消也能解锁）；fn panic 时仍释放锁；TryLock 响应 ctx 取消；新增 ErrLockUnexpectedResult。无 API 签名/配置/migration 变更。新增测试依赖 miniredis。
新并发/生命周期/泄漏隐患？ 无新增，反而消除。stop/finished 唯一所有者 close；defer 兜底覆盖 panic 路径；-race 已跑通过（含 goroutine 泄漏检测）。

代码审查结果：PASS

双 channel 协调符合"唯一所有者 close"原则；defer 兜底覆盖 panic/正常/error 三路径；toInt64 消除裸断言；fencing token 文档化合理（实现需破坏性变更+下游配合）。独立复审无 CRITICAL/HIGH（发现的 CRITICAL fn-panic 泄漏 + HIGH WithLock 同病均已修复）。

安全审查结果：PASS

send-on-closed panic/锁泄漏/goroutine 泄漏三类闭环；fn panic 不再泄漏锁与 goroutine；裸断言防护。gosec 0 issue。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestWithLockAutoExtendCtxCancelNoPanic：ctx 取消不 panic + 锁释放（修复前 send-on-closed panic + race detected）。
TestWithLockAutoExtendFnPanicReleasesLock：fn panic 释放锁（修复前"lock leaked after fn panic"）。
TestWithLockCtxCancelReleasesLock：WithLock ctx 取消释放锁（HIGH 修复）。
TestWithLockAutoExtendNormalRelease/ExtendsLock/BlocksContender：正常释放/续期保活/阻断竞争者。
TestLockUnlockExtendCycle：加锁/重复加锁失败/续期/错误 token 解锁失败/正确解锁闭环（C1b 路径）。
TestTryLockRespectsCtxCancel：ctx 取消 ~150ms 返回（修复前 ~2s，旧 Sleep 无视 ctx）。
红/绿验证：回退双 channel 后 ctx 取消测试复现 "send-on-closed panic + race detected"；回退 defer 后 panic 测试复现 "lock leaked after fn panic"；恢复后全绿。

已知风险

续期 ExtendLock 用原 ctx vs Unlock 用 Background（MEDIUM，设计权衡）：ctx 取消后续期失败停止续期是合理语义（取消即放弃），fn panic 时 defer 用 Background 解锁兜底。可接受，已注释说明。
C1d fencing token（设计局限，文档化）：TTL 到期后双 worker 并发需下游配合 fencing token 校验，框架无法单方面保证，已文档化。
miniredis 测试依赖：Lua 恒返 int64，C1b panic 路径无法用 miniredis 复现，由 toInt64 代码审查保证（注释说明）。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

续期 ExtendLock 可改 Background ctx 与 Unlock 一致（需权衡：取消后续期是否应继续）。
C1d：若需硬防 TTL 到期双写，提供基于 Redis INCR 的 fencing token 方案 + 下游校验文档。
UnlockByKey/ForceUnlock 不检查 token（设计如此，已注释），保留。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race 验证复核 8 项：C1b/C1c 修复到位；C1a send-on-closed 已消除，但发现 CRITICAL（fn panic 路径锁泄漏+goroutine 泄漏，无 defer 兜底） + HIGH（WithLock 同病未修）。两项均已修复（defer 兜底 + Background Unlock）并补回归用例红绿验证。另 2 项 MEDIUM（续期 ctx 不一致、测试缺红绿对照）+ 范围外提示。裁定：修复 CRITICAL/HIGH 后可交付 PASS。

✅ C7 `middleware/cors.go` 通配后缀绕过 + 开发态任意 Origin 回显 — P0

需求分析结果

C7a 通配后缀绕过：*.example.com → domain="example.com"，strings.HasSuffix(origin, domain) 未锚定 host → https://notexample.com、https://evil-example.com 被接受为 example.com 的子域。
C7b 开发态任意 Origin 回显：cfg.IsDevelopment() && origin != "" 无条件回显任意 Origin；若同时 AllowCredentials=true 则构成凭据型反射，任意站点可携凭证访问。

方案设计摘要

C7a：抽取 matchOrigin(origin, ao string) bool，通配 *.domain 改用 net/url 解析 origin 的 host（u.Hostname() 去端口/userinfo/IPv6 中括号），要求 host 以 .domain 结尾（锚定边界）且不等于 domain 自身（apex 不由通配覆盖）；大小写不敏感；支持 FQDN 尾点归一化。
C7b：抽取 isLocalhostOrigin(origin string) bool，开发态兜底增加 localhost 条件，仅对 localhost/127.0.0.1/::1 回显，不回显任意 Origin。
C7 收尾（信息泄露收敛）：未匹配 origin 时不再发送 Allow-Methods/Allow-Headers/Expose-Headers/Max-Age，避免向未授权 origin 暴露 API 允许的方法/头清单。四个头移入 allowedOrigin != "" 条件块。

涉及模块：middleware/cors.go、middleware/cors_internal_test.go、middleware/middleware_test.go。DB 影响：无。API 影响：公共 API 不变；行为变更（通配更严格、开发态仅回显 localhost、未匹配 origin 不发 Allow-Methods 等）。安全影响：正向。风险：开发态原本能回显任意 Origin 的下游需改显式白名单。

修改文件清单

middleware/cors.go：新增 matchOrigin（精确+通配子域，url.Parse 锚定边界，尾点归一化）、isLocalhostOrigin（localhost/127.0.0.1/::1）；origin 匹配循环改用 matchOrigin；开发态兜底加 isLocalhostOrigin 条件。
middleware/cors_internal_test.go（新）：matchOrigin 边界/大小写/尾点 + isLocalhostOrigin 纯函数测试。
middleware/middleware_test.go：C7a 通配绕过拒绝 + apex 不匹配 + C7b 开发态非 localhost 不回显集成测试。

实现内容摘要

通配后缀绕过闭环（host 边界锚定）；开发态凭据型反射消除（仅 localhost 回显）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API（CORS/CORSWithConfig/CORSWithOrigins/CORSWithWildcard/CORSForAPI）签名不变。matchOrigin/isLocalhostOrigin 是无状态纯函数，复用既有 config.CORSConfig。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性，收紧）：*.example.com 不再匹配 notexample.com 等绕过域名；apex 不由通配覆盖；开发态仅回显 localhost。原本依赖开发态回显任意域名的下游需改显式白名单。无 API 签名/配置/migration 变更。
新并发/生命周期/泄漏隐患？ 无。matchOrigin/isLocalhostOrigin 纯函数无状态、无包级可变全局。-race 已跑通过。

代码审查结果：PASS

matchOrigin 用 url.Parse + Hostname() 是标准 CORS 子域匹配做法；尾点归一化处理 FQDN 边角；apex 不由通配覆盖是严格安全语义（与主流库一致）。独立复审无 CRITICAL/HIGH。

安全审查结果：PASS

C7a：通配后缀绕过闭环，notexample.com/evil-example.com/userinfo 嵌入/trailing dot 等边角经实跑验证不可绕过。
C7b：开发态凭据型反射消除，仅 localhost 回显；生产环境兜底完全不回显。
gosec 0 issue。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestMatchOriginWildcardBoundary：notexample.com/evil-example.com 拒绝、真实子域/多级子域通过、apex 拒绝（C7a 纯函数）。
TestMatchOriginCaseInsensitive/TrailingDot：大小写/尾点归一化。
TestIsLocalhostOrigin：localhost/127.0.0.1/::1 通过、localhost.evil.com 等拒绝（C7b 纯函数）。
TestCORSWildcardSuffixBypassRejected：集成断言 evil origin 不回显 + 不发凭证头、真实子域回显（修复前 evil 被回显 + credentials）。
TestCORSWildcardDoesNotMatchApex：apex 不由通配覆盖。
TestCORSDevModeRejectsArbitraryOrigin：开发态 evil.com 不回显、localhost 回显（修复前 evil.com 被回显）。
TestCORSUnmatchedOriginNoMethodHeaders：未匹配 origin 不发 Allow-Methods/Headers/Expose-Headers/Max-Age（修复前完整暴露 API 方法/头清单），匹配时正常发。
红/绿验证：回退 matchOrigin 为 strings.HasSuffix 后 notexample.com 复现"被回显 + Allow-Credentials: true"；回退开发态 isLocalhostOrigin 后 evil.com 复现"被回显"；回退发头条件后未匹配 origin 复现"Allow-Methods 完整暴露"；恢复后全绿。

已知风险

staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

补 userinfo 嵌入/IPv6 origin 边角测试（probe 已证安全）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + 实跑探针用例复核 8 项：C7a/C7b 两个 CRITICAL 缺陷均已有效修复，notexample.com/evil-example.com/userinfo/trailing dot/IPv6 等边角经实跑验证不可绕过，红绿到位，无并发隐患。无 CRITICAL/HIGH。1 项 LOW（trailing dot FQDN 误拒，功能边角）已修复（尾点归一化）；1 项既有 LOW（未匹配 origin 发 Allow-Methods 头）经本轮收尾修复（移入 allowedOrigin!="" 条件块 + 回归用例）。裁定：可交付 PASS。

✅ C3 `sse/sse.go` 断连泄漏 goroutine + 算力（AI 主场景） — P0

需求分析结果

C3b（核心）写/Flush 错误被吞：WriteEvent/WriteMessage 丢弃 fmt.Fprintf 错误且恒 return nil，Flush() 无返回值；WriteJSON 仅 marshal 失败返错，否则透传 nil。故 StreamText 等的 if err := WriteJSON(...); err != nil 守卫只对 marshal 失败生效，对客户端断连永不触发 → 消费循环不退出 + 上游 LLM 流持续运行直到进程结束。
C3a 循环无 ctx.Done 分支：四个 for range ch（Stream/StreamText/StreamChunks/StreamWithID）仅靠 ch 关闭或写错误退出（写错误又被吞）。
C3c 手设 Transfer-Encoding: chunked：HTTP/1.1 冗余，HTTP/2 非法。

方案设计摘要

C3b：WriteEvent/WriteMessage 改返回 fmt.Fprintf 的写错误。
C3a：SSEWriter 加 ctx context.Context 字段（NewSSEWriter 存 c.Request.Context()，nil 回退 context.Background() 防御）；四消费循环改 for { select { case <-ctx.Done(): return ctx.Err(); case v,ok:=<-ch: ... } }。
C3c：删除 Transfer-Encoding: chunked 手设头。
生产者契约文档化：StreamText 注释说明生产者应监听 c.Request.Context()，取消时停止上游 LLM 流（框架无法单方面停止生产者）。

涉及模块：sse/sse.go、sse/sse_concurrency_test.go、sse/sse_stream_internal_test.go。DB 影响：无。API 影响：公共 API 签名不变；行为变更（断连即停、写错误传播、不手设 chunked）。安全影响：正向。风险：见"已知风险"。

修改文件清单

sse/sse.go：SSEWriter 加 ctx 字段；NewSSEWriter 存 ctx + 删 chunked 头；WriteEvent/WriteMessage 传播写错误；Stream/StreamText/StreamChunks/StreamWithID 改 select+ctx.Done；Stream nil ctx 防御；StreamText 注释生产者契约。
sse/sse_concurrency_test.go（新）：normal completion 闭环 + chunked 头不存在。
sse/sse_stream_internal_test.go（新）：internal test 直接构造 SSEWriter + 可控 ctx，权威验证 Stream ctx.Done 即停。

实现内容摘要

断连即停闭环（ctx.Done）；写错误传播（不恒 nil）；HTTP/2 兼容（删 chunked）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名全不变；SSEWriter 加私有 ctx 字段，外部本就无法字面量完整构造（writer/flusher 均私有）。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：Stream 系列在 ctx 取消时返回 context.Canceled 而非永久阻塞；WriteEvent/WriteMessage 现可返回写错误（下游忽略返回值不受影响）；不手设 chunked 头。无 API 签名/配置/migration 变更。
新并发/生命周期/泄漏隐患？ 反而消除。ctx.Done 消费端早退；写错误触发循环退出。生产者阻塞属调用方契约（文档化），非框架泄漏。-race 已跑通过。

代码审查结果：PASS

四循环 ctx.Done 一致；写错误传播机械保证；Flush 无返回值属标准库约束（下次 Write 暴露写失败）；nil ctx 防御。独立复审无 CRITICAL/HIGH。

安全审查结果：PASS

断连即停消除 goroutine 泄漏 + 上游算力浪费；HTTP/2 兼容。gosec 0 issue。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestStreamStopsOnCtxCancelInternal（internal）：直接构造 SSEWriter + 可控 ctx，cancel 后 Stream 返回 ctx.Err（修复前 for-range 无 ctx.Done，2s 超时复现阻塞）。
TestStreamTextNormalCompletion：ch 正常关闭写 done 返回 nil（正常路径不误伤）。
TestNewSSEWriterNoChunkedHeader：响应头不含 Transfer-Encoding（C3c）。
红/绿验证：回退 Stream 为 for-range 后 internal test 复现"2s 超时阻塞"；恢复后绿。

已知风险

生产者契约（设计约束，文档化）：StreamText 在 ctx.Done 后返回，但生产者（往 ch 发送方）若不监听 ctx 仍阻塞在 ch<-。框架无法单方面停止生产者，已在 StreamText 注释声明调用方契约。
端到端断连即停未实跑（LOW，测试取舍）：httptest loopback 下 c.Request.Context() 取消时序不可靠，改用 internal test 直接构造 ctx 权威覆盖 select 模式。生产环境由 gin/http server 在连接断开时取消 ctx，逻辑一致。
Flush 无返回值（LOW，标准库约束）：http.Flusher.Flush() 不返错，flush 阶段写失败由下次 Write 暴露。仅最后一次 flush 后断连且流随即退出才丢失该错误，影响极小。
N6 KeepAlive 发 data: \n\n（既有缺陷，非 C3 范围）：应发注释行 : ping\n\n。留作后续。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

N6：KeepAlive 改发 : ping 注释行。
StreamText 可返回一个 cancel 给生产者（强制停止上游）。
端到端断连测试（需更可靠的连接控制，如 Hijack）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + 红绿验证复核 9 项：C3a/C3b/C3c 核心缺陷均已有效修复，四循环 ctx.Done 一致、写错误传播到位、chunked 头删除有测试验证，红绿到位，无并发隐患。无 CRITICAL/HIGH。2 项 LOW（空测试 + nil ctx 防御）已处理；N6 + 端到端测试取舍为范围外/已知。裁定：可交付 PASS。

✅ H2 `utils/http.go` 默认关闭 TLS 校验 — P0

需求分析结果

DefaultHTTPClientConfig.SkipTLSVerify: true（http.go:53）→ NewHTTPClient() → HTTPGet/HTTPPost/HTTPPostJSON 经 DefaultHTTPClient() 全部默认 InsecureSkipVerify: true，可被 MITM。调用方无下游业务依赖默认跳过（仅定义处）。

方案设计摘要

默认改 false（校验 TLS）；自签证书场景显式 SetSkipTLS(true) 或配置 SkipTLSVerify: true。SetSkipTLS 注释补充安全警示。gosec G402 加 #nosec 留痕（默认 false，opt-in 跳过）。

涉及模块：utils/http.go、utils/http_test.go。DB 影响：无。API 影响：公共 API 不变；行为变更（默认校验 TLS）。安全影响：正向。风险：下游访问自签证书服务会失败，需显式开启跳过 → 须 CHANGELOG 声明。

修改文件清单

utils/http.go：DefaultHTTPClientConfig.SkipTLSVerify true→false；SkipTLSVerify 字段注释；SetSkipTLS 安全警示注释；G402 #nosec ×2。
utils/http_test.go（新）：默认校验 TLS / HTTPGet 默认校验 / opt-in 跳过 / config 跳过 / 默认配置 false / transport 校验 6 个回归用例。

实现内容摘要

默认 TLS 校验闭环（防 MITM），opt-in 跳过保留。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名不变；HTTPClientConfig 字段不变，仅默认值改。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，可能影响下游）：默认校验 TLS，下游访问自签证书服务会失败，需显式 SetSkipTLS(true)。无 API 签名/配置结构/migration 变更。
新并发/生命周期/泄漏隐患？ 无。仅改默认值与注释。-race 已跑通过。

代码审查结果：PASS

最小改动（一行默认值 + 注释）；opt-in 机制保留；G402 #nosec 正当。独立复审无 CRITICAL/HIGH。

安全审查结果：PASS

MITM 风险消除（默认校验）；opt-in 跳过有安全警示。G402 #nosec 留痕。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestHTTPClientDefaultVerifiesTLS：默认 client 访问自签 server 失败（修复前成功 = MITM）。
TestHTTPGetDefaultVerifiesTLS：HTTPGet 默认校验。
TestHTTPClientSkipTLSOptIn：显式 SetSkipTLS(true) 可访问自签。
TestHTTPClientWithConfigSkipTLS：config 显式 true 跳过。
TestDefaultHTTPClientConfigNoSkipTLS：默认配置 SkipTLSVerify=false。
TestDefaultClientTransportVerifiesTLS：默认 transport 校验 TLS。
红/绿验证：回退默认为 true 后三个核心用例复现"默认跳过 TLS 校验/自签被接受"；恢复后绿。

已知风险

下游自签证书服务受影响（行为变更）：需显式开启跳过。已 CHANGELOG 声明，属安全加固的合理 breaking。
utils_test.go 的 RandString generated duplicate 是预存 H1（不安全 RNG）失败，与 H2 无关。
其余 gosec issue（G404 弱 RNG / G401 弱密码学 / G304 file 权限 / G124 cookie / G704 SSRF）为预存缺陷，属其他条目范畴（H1 等），非本次 H2 引入。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec（H2 相关 G402 已清零）通过。

后续优化建议

H1：utils/random.go 用 math/rand，应提供 crypto/rand 安全版本。
其余预存 gosec issue（G401/G505/G501 弱密码学、G304 file 权限等）逐项清理。

独立对抗性复审结论

（H2 修复小而独立，红绿验证已实跑；独立复审按需启动。当前：可交付 PASS，无 CRITICAL/HIGH。）

✅ H1 `utils/random.go` 不安全 RNG 且文档反向推荐 — P0

需求分析结果

randPool 用 math/rand + time.Now().UnixNano() 播种（random.go:12），RandString/RandDigit/RandInt/RandInt64 取自该池，非密码学安全、可预测（-race 下并发同纳秒取池实例生成相同序列）。GUIDE.md:1208 主动推荐 RandString(16) 用于 token、:1211 RandDigit(6) 用于 OTP 验证码，使可预测性可被实际利用（OTP 爆破、token 伪造）。比"应强文档警告"更严重（文档反向推荐）。

方案设计摘要

新增 RandStringSecure(n) (string, error) / RandDigitSecure(n) (string, error)，基于 crypto/rand + big.Int 索引（拒绝采样无偏），不可预测；n<=0 返空，n>1<<20 返 ErrRandInvalidLength 保护熵池。
新增 RandIntSecure(min, max int) (int, error) / RandInt64Secure(min, max int64) (int64, error)，基于 crypto/rand + big.Int 拒绝采样无偏，用于安全 nonce 范围、防猜抽奖、密钥分桶等；min==max 返 min，max<min 自动交换。
删除 RandString/RandDigit（用户决策）：字符串随机的用途几乎都是安全场景（token/OTP/验证码/会话 ID），保留 math/rand 版本会诱导误用（H1 的根因正是 GUIDE 推荐 RandString 做 token）。非安全场景需高性能随机串，下游直接用标准库 math/rand。
保留 RandInt/RandInt64（范围随机，有明确非安全场景：负载均衡/游戏/A-B 分桶），加非安全警示注释。
GUIDE.md token/OTP 示例改用 Secure 版本 + 错误处理；高分函数表区分"随机（安全）"与"随机（范围）"；移除 RandString/RandDigit。
gosec G404（randPool 的 math/rand）加 #nosec 留痕。

涉及模块：utils/random.go、utils/utils_test.go、GUIDE.md。DB 影响：无。API 影响：Breaking——删除 RandString/RandDigit；新增 RandStringSecure/RandDigitSecure/RandIntSecure/RandInt64Secure/ErrRandInvalidLength；保留 RandInt/RandInt64。安全影响：正向（消除诱导误用）。风险：下游 RandString/RandDigit 调用方需迁移 → 须 CHANGELOG 升级说明。

修改文件清单

utils/random.go：新增 RandStringSecure/RandDigitSecure/ErrRandInvalidLength；删除 RandString/RandDigit + 位运算常量（letterIdxBits/letterIdxMask/letterIdxMax）；RandInt/RandInt64 警示注释；randPool G404 #nosec。
utils/utils_test.go：新增安全版本测试（长度/字符集/唯一性/过大长度）+ 删除 TestRandString/TestRandDigit/对应 benchmark；benchmark 改 Secure 版本。
GUIDE.md：11.1 节示例改用 Secure + 选型说明（RandString/RandDigit 已移除）；高分函数表区分"随机（安全）"与"随机（范围）"。

实现内容摘要

crypto/rand 安全版本闭环（token/OTP 用）；删除易误用的 math/rand 字符串随机；范围随机保留（非安全场景）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。RandInt/RandInt64 签名不变；新增 RandStringSecure/RandDigitSecure/ErrRandInvalidLength；删除 RandString/RandDigit（Breaking，CHANGELOG 升级说明）。crypto/rand.Reader 标准库并发安全。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ Breaking（删除 RandString/RandDigit）：下游调用方需迁移——token/OTP/验证码 → RandStringSecure/RandDigitSecure；非安全场景 → 标准库 math/rand。RandInt/RandInt64 保留不破坏。CHANGELOG 升级说明已列。框架内部无引用（仅测试/示例），breaking 影响面小。
新并发/生命周期/泄漏隐患？ 无。crypto/rand 无状态并发安全；既有 randPool 保留（sync.Pool，仅 RandInt/RandInt64 用）。-race 已跑通过。

代码审查结果：PASS

rand.Int(rand.Reader, big.NewInt(...)) 拒绝采样无偏；既有函数保留 + 警示；GUIDE 选型区分。独立复审无 CRITICAL/HIGH。

安全审查结果：PASS

token/OTP 可预测性消除（crypto/rand）；gosec G404 #nosec 留痕；错误向上传播不吞。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestRandStringSecure：长度/字符集（字母+数字）。
TestRandStringSecureUniqueness：1000 个 16 位串无重复（crypto/rand）。红/绿验证：回退 RandStringSecure 为 math/rand 后第 32 个即重复（红）；恢复后 1000/1000 唯一（绿）。独立复审实跑：math/rand 模拟 unique=132/1000、duplicates=868（H1 红）。
TestRandDigitSecure/Uniqueness：6 位 OTP 数字 + 唯一性。
TestRandStringSecureTooLarge：过大长度返 ErrRandInvalidLength。
TestRandIntSecure/TestRandInt64Secure：范围正确、min==max、max<min 自动交换。
TestRandInt64SecureUniqueness：[0, 1<<40) 1000 个无重复（crypto/rand 大空间无偏）。注意 uniqueness 测试须用足够大空间——[0,1<<20) 1000 样本生日重复概率 ~48% 不可用，改用 1<<40（概率 ~5e-7）。
benchmark 改 RandStringSecure/RandDigitSecure。

已知风险

删除 RandString/RandDigit 是 Breaking：下游调用方需迁移（CHANGELOG 升级说明已列）。框架内部无引用，影响面小。
RandInt/RandInt64 仍为非安全版本：范围随机有明确非安全场景（负载均衡/游戏），保留合理；安全范围随机用新增的 RandIntSecure/RandInt64Secure。
docs/plans/v2.0-review.md 草稿仍提 RandString/RandDigit（LOW）：历史规划草稿，非用户指南，可选同步。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec（G404 已清零）通过。

后续优化建议

视需求同步 docs/plans/v2.0-review.md 草稿的安全区分。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + 实跑红绿验证复核 8 项：H1 修复实现正确、回归用例真实复现缺陷（math/rand 模拟 132/1000 唯一 vs crypto/rand 1000/1000）、非 breaking、并发安全、文档警示充分。无 CRITICAL/HIGH。2 项 LOW（ErrRandInvalidLength 注释措辞已修正；v2.0 草稿同步为可选）。裁定：可交付 PASS。

✅ C9b `jwt/jwt.go` 刷新令牌撤销失败仍签发 + C9a 无 Redis 静默失效 — P0

需求分析结果

C9b（最危险）RefreshToken 吞 Add 错误（jwt.go:287-292）：tokenBlacklist.Add(claims.JTI, ...) 返回值被丢弃，仍 return GenerateToken(...) → Redis 抖动时旧 token 未拉黑、新旧 token 双有效，会话固定窗口。
C9a 叠加：Add/IsBlacklisted 在 client==nil 时静默 return nil/return false，Redis 未启用时黑名单完全失效且无信号，致刷新/登出无声成功。

方案设计摘要

C9b：RefreshToken 对 Add 错误 return "", fmt.Errorf("刷新令牌失败：旧令牌撤销失败: %w", err)，fail-closed 不签发新 token。
C9a：Add 无 Redis 时返 ErrBlacklistUnavailable（新增导出错误），让 RefreshToken/InvalidateToken/InvalidateTokenByID 感知黑名单不可用并 fail-closed；IsBlacklisted 无 Redis 仍返 false（验证侧 fail-open 是无 Redis 部署固有局限，文档约束安全场景必须启用 Redis）。

涉及模块：jwt/jwt.go、jwt/jwt_test.go。DB 影响：无。API 影响：签名不变；新增 ErrBlacklistUnavailable；行为变更（无 Redis/Redis 失败时刷新与登出 fail-closed）。安全影响：正向。风险：无 Redis 部署刷新/登出会失败 → 须 CHANGELOG 声明。

修改文件清单

jwt/jwt.go：新增 ErrBlacklistUnavailable；Add 无 Redis 返错（C9a）；RefreshToken 对 Add 错误 fail-closed（C9b）。
jwt/jwt_test.go：更新 TestTokenBlacklist/TestInvalidateToken/TestRefreshToken 为 fail-closed 语义；新增 setupMiniRedis（含 cleanup 还原防污染）；新增 TestRefreshTokenRevokesOldToken/TestRefreshTokenFailsOnRedisError/TestInvalidateTokenRevokesToken/TestInvalidateTokenByIDNoRedis 真实闭环回归。

实现内容摘要

刷新令牌撤销闭环（fail-closed）；无 Redis 黑名单失效感知（ErrBlacklistUnavailable）；验证侧 fail-open 文档化。

三个全局问题（强制回答）

与既有体系契约一致？ 是。RefreshToken/InvalidateToken/InvalidateTokenByID 签名不变；新增 ErrBlacklistUnavailable（导出错误，非 breaking）。无 DB/路由新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明）：无 Redis/Redis 失败时 RefreshToken/InvalidateToken/InvalidateTokenByID 返错（fail-closed），不再静默成功。无 Redis 部署需启用 Redis 或接受登出走客户端丢弃 token。签名不变，新增错误值。
新并发/生命周期/泄漏隐患？ 无新增。tokenBlacklist 包级 var 经 SetDefaultJWTManager 裸写是 C9c 预存遗留（典型启动期调用，潜在竞争），本次未引入；测试放大其可观察性但已用 cleanup 还原避免污染。-race/-shuffle 已跑通过。

代码审查结果：PASS

fail-closed 闭环正确；Add/IsBlacklisted 不对称取舍合理（Add 无法 fail-open 否则撤销形同虚设，验证侧 fail-closed 则无 Redis 全拒）；独立复审无生产 CRITICAL/HIGH。

安全审查结果：PASS

会话固定窗口消除（旧 token 必拉黑才签新）；无 Redis 失效感知。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestRefreshToken（无 Redis）：fail-closed 返 ErrBlacklistUnavailable（修复前吞错签发）。
TestRefreshTokenRevokesOldToken（miniredis）：刷新后旧 token ErrTokenRevoked（正常闭环）。
TestRefreshTokenFailsOnRedisError（关 miniredis 模拟抖动）：fail-closed 不签发（修复前吞错签发，复现 C9b 红）。
TestInvalidateTokenRevokesToken（miniredis）：登出后 token ErrTokenRevoked。
TestInvalidateTokenByIDNoRedis：无 Redis 返 ErrBlacklistUnavailable。
红/绿验证：回退 RefreshToken 吞 Add 错误后 TestRefreshToken/TestRefreshTokenFailsOnRedisError 复现红；恢复后绿。
测试隔离修复（独立复审 CRITICAL）：setupMiniRedis 的 cleanup 还原默认无 Redis Manager；-shuffle=on + count=5 稳定通过（修复前 shuffle 下 TestRefreshToken 误 FAIL）。

已知风险

无 Redis 部署刷新/登出失败（行为变更）：fail-closed 必然代价，已 CHANGELOG 声明。下游无 Redis 时登出走客户端丢弃 token。
C9c 裸写包级 tokenBlacklist（HIGH，预存遗留）：SetDefaultJWTManager 无锁置换，请求 goroutine 无锁读。典型启动期调用故潜在；本次未引入，留作 P1 的 C9c 修复。
验证侧 fail-open（设计约束，文档化）：无 Redis 时 IsBlacklisted 返 false，旧 token 仍可用——无 Redis 部署固有局限，安全场景必须启用 Redis。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

C9c：SetDefaultJWTManager/tokenBlacklist 改 atomic.Pointer 或锁保护。
文档：无 JTI 的外部签发 token 不受刷新撤销保护（边界说明）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -shuffle=on 实跑复核 6 项：C9b fail-closed 闭环成立、C9a 取舍正确、签名不变、红绿到位。发现 CRITICAL 测试隔离缺陷（setupMiniRedis 不还原包级 tokenBlacklist，shuffle 下误 FAIL）——已修复（cleanup 还原 + 实跑 shuffle count=5 稳定）。另 1 项 HIGH（C9c 裸写，预存遗留）留作 P1。裁定：生产代码可交付 PASS；测试隔离修复后达交付标准。

✅ H4a `middleware/ratelimit.go` 限流误限流 — P0（收官）

需求分析结果

Allow 每次放行都 v.lastSeen = time.Now()（:55/63/72），重置分支 time.Since(lastSeen) > rl.window（:61）对持续客户端永不成立 → count 单调累加，稳态客户端（低于 rate）被误限流，须静默满 window 才解锁。算例：rate=10/min、客户端 9 req/min，count 累加至 10 后第 11 次起被误限。清理 goroutine 同条件也永不淘汰活跃访客。

方案设计摘要

visitor.lastSeen 改名 windowStart，语义改为"当前固定窗口起点"，仅在新窗口开始时设置，放行时不变更。
Allow：窗口过期（now.Sub(windowStart) > window）时重置 count=1 + 新 windowStart；放行 count++ 不更新 windowStart；超限拒绝。
新增 nowFunc 字段 + SetNowFunc 导出方法（默认 time.Now，测试注入可控时钟，避免真实 Sleep flaky）。
cleanupVisitors 用 rl.now().Sub(windowStart) > window 淘汰。
文档：固定窗口允许窗口边界突发（2×rate），如需平滑用 Redis 版滑动窗口。

涉及模块：middleware/ratelimit.go、middleware/middleware_test.go。DB 影响：无。API 影响：Allow/NewRateLimiter/Stop 签名不变；新增 SetNowFunc（非 breaking）；visitor 字段改名（未导出，无影响）。行为变更（窗口语义正确，稳态不被误限）。安全影响：正向。风险：原"误限"的下游感受到限流放宽——但符合"每分钟 N 次"承诺。

修改文件清单

middleware/ratelimit.go：visitor.lastSeen→windowStart；Allow 固定窗口语义；新增 nowFunc/now()/SetNowFunc；cleanupVisitors 用 windowStart；边界突发文档。
middleware/middleware_test.go：新增 fakeClock + TestRateLimiterSteadyClientNotBlocked（跨窗口稳态）/WindowReset/BlocksOverRate/BurstCappedAtRate。

实现内容摘要

固定窗口语义闭环（windowStart 仅窗口起点）；稳态客户端不被误限；可控时钟注入测试。

三个全局问题（强制回答）

与既有体系契约一致？ 是。Allow/NewRateLimiter/Stop 签名不变；SetNowFunc 纯新增；visitor 未导出（字段改名无外部影响）。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（非破坏性）：稳态客户端不再被误限流（符合"每分钟 N 次"承诺）。SetNowFunc 新增不影响下游。无 API 签名/配置/migration 变更。
新并发/生命周期/泄漏隐患？ 无。nowFunc 读写均在 rl.mu 锁内（SetNowFunc 写锁、Allow/cleanup 读锁）；-race 已跑通过。

代码审查结果：PASS

固定窗口语义正确（windowStart 仅窗口起点）；nowFunc 注入并发安全；cleanup 与 Allow 淘汰语义一致。独立复审无 CRITICAL/HIGH。

安全审查结果：PASS

误限流消除（稳态客户端符合 rate 承诺）；超限仍正确拦截；突发封顶 rate。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestRateLimiterSteadyClientNotBlocked：3 窗口每窗口 8 次（< rate=10），fakeClock 注入。红/绿验证：回退放行更新 windowStart 后窗口2第3次复现"被误限"（红）；恢复后绿。
TestRateLimiterWindowReset：达 rate 拒、窗口过期后重置。
TestRateLimiterBlocksOverRate：超限拦截（非放宽到无限）。
TestRateLimiterBurstCappedAtRate：窗口内突发封顶 rate。
现有 TestRateLimiterAllow 等保留通过。

已知风险

固定窗口边界突发（算法固有，文档化）：两窗口交界处瞬时 2×rate，固定窗口算法特性。如需平滑用 Redis 版滑动窗口。
H4b（CustomRateLimit goroutine 泄漏，独立缺陷）：CustomRateLimit 每次路由构造创建 limiter 无句柄，StopRateLimiters 不感知 → 泄漏 cleanup goroutine。非本次 H4a 范围，留作后续。
H4c（Redis fail-open + 裸断言，独立缺陷）：RedisRateLimiter.Allow Redis 错误 fail-open、result.(int64) 裸断言。非本次范围，留作后续。
staticcheck 因环境限制无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

H4b：CustomRateLimit 登记入全局或返回句柄，StopRateLimiters 感知。
H4c：Redis fail-open 改可配置（安全型限流 fail-closed）；裸断言改 comma-ok。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + 红绿实跑验证复核 7 项：H4a 修复正确、并发安全、红绿到位（回退旧 bug 行为后回归用例确证变红）、无 breaking、无新增包级可变全局。无 CRITICAL/HIGH。固定窗口边界突发已补文档注释。H4b/H4c 属独立缺陷项不阻断，留作后续。裁定：可交付 PASS。

✅ C10 `config/config.go` 全局 Manager 无锁置换 + 热重载绕过 Validate + StopWatcher 空函数 — P1

需求分析结果

C10a：包级 defaultManager 裸 *Manager 指针被 Load/LoadWithWatch/SetDefaultManager 裸写，与 Get/GetViper/GetString 等请求 goroutine 无锁读竞争。
C10b：OnConfigChange/Reload 均不调 Validate()（仅 Load 调用），非法配置（坏端口、负超时、短密钥）直接发布；解析失败静默吞。
C10c：Load 返回 &cfg 与 m.cfg 同一指针，调用方可变并竞争。
C10d：StopWatcher 空函数，viper 内部 watcher goroutine + fd 永不释放。

方案设计摘要

C10a：defaultManager 改 atomic.Pointer[Manager]，init() Store；所有包级便捷函数（Load/LoadWithWatch/RegisterCallback/StartWatcher/StopWatcher/Get/GetViper/Set/Reload/SetDefaultManager）经 Load()/Store() 原子读写。
C10b：抽取共享 reload()，Reload() 与文件监听路径统一走之；读取/解析/Validate 任一步失败均保留旧配置并返回错误，仅新配置通过 Validate 后才替换 m.cfg 并触发回调。废弃 viper WatchConfig/OnConfigChange。
C10c：Load 返回防御性浅拷贝（out := cfg; return &out），标量字段独立；切片字段共享底层数组的局限以只读契约文档化（Get() 同样声明只读），配回归测试锁定语义。
C10d：自管 fsnotify.Watcher——监听配置文件所在目录（兼容 vim/k8s ConfigMap 改写替换）+ 按文件名过滤 + 200ms 去抖；watchLoop 只读传入局部变量（w/target/done）不读字段，避免与 StopWatcher 写竞争；StopWatcher 关闭 watcher 并等待 watchDone 退出，幂等。

涉及模块：config/config.go、config/config_c10_test.go。DB 影响：无。API 影响：公共 API 签名全不变；行为变更（热重载非法配置保留旧配置、StopWatcher 真正释放监听资源）。安全影响：正向。风险：见"已知风险"。

修改文件清单

config/config.go：defaultManager 改 atomic.Pointer[Manager] + init()；Manager 加 watcher/watchDone 字段；Load 返回浅拷贝；StartWatcher 重写为自管 fsnotify（目录监听 + 去抖 + watchLoop）；StopWatcher 真正关闭 + 等待退出；新增 reload() 共享重载（含 Validate），Reload() 委托之；包级函数全改原子访问；Get()/Load 注释声明只读契约。
config/config_c10_test.go（新）：并发置换 Manager（-race）、Load 防御性拷贝（标量 + 切片契约）、Reload 非法配置保留旧配置、热重载非法配置保留旧配置且不触发回调 + 后续合法变更仍生效、StopWatcher 释放 goroutine、StartWatcher 幂等。

实现内容摘要

全局 Manager 原子读写闭环（C10a）；热重载强制 Validate 失败保留旧配置（C10b）；Load 防御性拷贝 + 只读契约（C10c）；自管 fsnotify watcher 真正可停（C10d）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名全不变；app.go config.SetDefaultManager(a.configManager) 仍工作，Load 返回拷贝后 a.config 持独立副本。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：热重载遇非法配置现保留旧配置并返错（原直接发布）；StopWatcher 现真正释放监听 goroutine/fd（原空操作）；Load 返回浅拷贝（切片字段只读契约）。无 API 签名/配置结构/migration 变更。Manager 新增未导出字段 watcher/watchDone 不影响外部。
新并发/生命周期/泄漏隐患？ 反而消除。atomic.Pointer 消除裸写竞争；watchLoop 不读字段避免与 StopWatcher 竞争；StopWatcher 幂等、不 close 已关闭 channel（watchDone 由 watchLoop defer close）；去抖 time.AfterFunc 在 Stop 后触发 reload() 安全（仅动锁内 m.v/m.cfg，不碰已关闭 watcher）；reload 全程持写锁串行化 v.ReadInConfig，回调在锁外调用避免死锁。-race 已跑通过。

代码审查结果：PASS

atomic.Pointer + init() Store 是标准模式；自管 fsnotify 监听目录 + 去抖是热重载稳健做法；watchLoop 局部变量传入避免字段竞争；reload 锁内 Validate 失败保留旧配置。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

热重载非法配置不再静默发布（C10b，防坏端口/短密钥配置在运行期生效）；监听 goroutine/fd 不再泄漏（C10d）。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestSetDefaultManagerConcurrent：4 写者 SetDefaultManager + 4 读者 Get/GetViper/GetString 并发，-race 通过（修复前裸指针必采到竞争）。
TestLoadReturnsDefensiveCopy：修改 Load 返回值的标量字段不污染 Get()（C10c 标量）。
TestLoadDefensiveCopySliceContract：锁定切片字段共享底层数组的浅拷贝局限（只读契约）。
TestReloadInvalidConfigKeepsOld：port:99999 Reload 返错 + 旧端口保留（C10b Reload 路径）。
TestHotReloadInvalidConfigKeepsOld：写非法配置 → 全局保留旧值 + 回调不触发；再写合法配置 → 监听仍存活、全局更新 + 回调触发（C10b 监听路径 + C10d 健壮性）。
TestStopWatcherReleasesGoroutine：Stop 后 NumGoroutine 下降 + 幂等（C10d）。
TestStartWatcherIdempotent：重复 Start 不泄漏 goroutine（C10d 幂等）。
红/绿验证：删 reload 的 Validate 调用后 TestReloadInvalidConfigKeepsOld/TestHotReloadInvalidConfigKeepsOld 复现"非法配置被发布"红；watchLoop 改读 m.watchDone 字段后 -race 复现"StopWatcher 写竞争"红；恢复后全绿。

已知风险

C10c 切片字段共享底层数组（MEDIUM，文档化）：Load 浅拷贝致 CORSConfig.AllowedOrigins 等 []string 字段与 m.cfg 共享底层数组；Get() 返回 m.cfg 原指针。已以只读契约文档化（Get()/Load 注释）+ 回归测试锁定。框架无法单方面阻止调用方改切片，约定配置对象只读。需完全独立可变副本时调用方自行深拷贝。
viper 实例并发（LOW，预存）：GetViper() 返回 m.v 给外部，外部并发 v.GetString 与 reload 内 v.ReadInConfig 存在竞争。预存问题（原 GetViper 同样导出），C10 未恶化（reload 现全程持写锁串行化 ReadInConfig，比原 OnConfigChange 无锁路径更收敛）。建议后续标注 GetViper 非并发安全。
包级 Load 失败仍 Store 空 manager（LOW，预存行为）：m.Load() 失败时仍 defaultManager.Store(m)，与原版"先赋值再 Load"行为一致，非 C10 引入。
atomic 快照语义（LOW）：包级便捷函数两次调用可能落到被 SetDefaultManager 置换后的不同 Manager（atomic 快照固有），非 C10 引入，原裸指针更糟。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

视需求为 Config 提供 Clone() 深拷贝方法，彻底消除切片共享（当前只读契约已足够安全）。
GetViper 标注非并发安全或限制导出。
包级 Load 失败时不 Store（改进预存行为，非 C10 范围）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race 实跑复核 7 大项：C10a/C10b/C10d 核心修复扎实，C10c 标量竞争已修、切片面以只读契约文档化。无 CRITICAL/HIGH。1 项 MEDIUM（C10c 切片共享 + Get() 未拷贝，已文档化 + 测试锁定）+ 4 项 LOW（atomic 快照语义注释、切片测试、viper 预存、Load 失败 Store 预存行为）均不阻断。裁定：可交付 PASS。

✅ C11 `database/manager.go` 池泄漏 + Master/Replicas 无锁读 + 健康状态陈旧 + 包级 Close 仅关主库 — P1

需求分析结果

C11b InitDB 重试泄漏（manager.go:346-389）：gorm.Open 成功但 Ping 失败时旧池不关、下轮 m.master = gorm.Open(...) 覆盖，每次重试泄漏一池。
C11c InitDBWithReplicas 泄漏（manager.go:423）：m.replicas = nil 前不关旧从库池；从库 DB()/Ping 失败时 continue 不关刚打开的 replicaDB。
C11a 健康状态陈旧（manager.go:144-155）：initReplicaHealth 的 replicaHealthSet 早返回，重新 InitDBWithReplicas 不重置 → 健康切片与新 replicas 长度错位（不越界 panic，但新从库健康状态陈旧/被排除）。
C11d Master/Replicas 无锁读（manager.go:97-104）：Master()/Replicas() 裸读 m.master/m.replicas，与 Close/InitDB 写竞争，可能返回已关闭/nil 池；Replica() 空从库判断在锁外读 m.replicas/m.master；FromContext/HealthCheck/Transaction*/WriteQuery/包级 HealthCheck 同样裸读。
C11f 包级 Close 仅关主库（manager.go:524-536）：包级 Close() 仅关 master 且无锁，CloseAll()/方法 Close() 关全部，命名误导致用户泄漏从库。
C11e 非缺陷：RoundRobinPicker int(n-1)%len 取模后仍在 [0,len)；RandomPicker 全局 math/rand 仅锁竞争。未改。

方案设计摘要

新增 closeDB(db) 辅助（nil/无 ConnPool 返 nil 不 panic）。
C11b：InitDB 先打开到局部 db，仅 Ping 通过后才在 m.mu 锁内安装 m.master = db 并 closeDB(old)；Ping/DB() 失败时 closeDB(db) 关闭刚打开的池。m.healthy.Store(true) 移到 Ping 通过后（原在 Ping 前）。
C11c：InitDBWithReplicas 重建前在锁内取出旧从库 + resetReplicaHealth，锁外逐个 closeDB；从库 DB()/Ping 失败时 closeDB(replicaDB)；新从库先构建到局部 newReplicas 再锁内原子安装。
C11a：新增 resetReplicaHealth（replicaHealthy=nil; replicaHealthSet=false，调用方持锁），InitDBWithReplicas/Close 重建/关闭前调用，使下次 initReplicaHealth 按新 replicas 长度重建。
C11d：Master()/Replicas() 全程持 m.mu；Replicas() 返回拷贝（nil 仍返 nil 兼容）；Replica() 空从库判断移入锁内；FromContext master 分支改 m.Master()；HealthCheck 方法锁内快照 master；Transaction/TransactionWithContext/WriteQuery/包级 HealthCheck 改经 Master()/Replicas()；probeOnce 快照 replicaHealthy 切片头避免与重置竞争。
C11f：包级 Close() 改为 return CloseAll()（关主+从并重置健康状态）。

涉及模块：database/manager.go、database/manager_c11_internal_test.go。DB 影响：无（连接池语义不变，仅生命周期/并发收敛）。API 影响：公共 API 签名全不变；行为变更（包级 Close 关从库、重试/重建不泄漏旧池、Master/Replicas 加锁）。安全影响：正向。风险：见"已知风险"。

修改文件清单

database/manager.go：新增 closeDB/resetReplicaHealth；Master/Replicas/Replica/HealthCheck 加锁；FromContext/Transaction/TransactionWithContext/WriteQuery/包级 HealthCheck/包级 Close 改经加锁读取或委托；InitDB 重试局部打开+失败关池+成功关旧主库；InitDBWithReplicas 重建前关旧从库+重置健康+局部构建原子安装；probeOnce 快照 replicaHealthy。
database/manager_c11_internal_test.go（新）：并发 Master/Replicas/Replica/FromContext 读写（-race）、Replicas 返回拷贝、健康重置重建对齐、不重置则陈旧（复现 C11a 根因）、Close 重置状态、包级 Close 关从库（C11f）、HealthCheck 锁内读。

实现内容摘要

池泄漏闭环（C11b/C11c：局部打开+失败关池+重建前关旧）；健康状态重建对齐（C11a：resetReplicaHealth）；Master/Replicas/Replica 全程加锁（C11d）；包级 Close 委托 CloseAll（C11f）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名全不变；Manager 新增未导出 closeDB/resetReplicaHealth。读写分离/ctx 路由/健康探活契约不变——Replica() 仍走 picker+健康过滤，FromContext 仍路由 master/replica，仅读取路径加锁。DefaultManager 是固定实例（非置换），字段读写现统一经 m.mu。无路由/认证/响应体系新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：包级 Close() 现关闭从库（原仅主库，正向修复泄漏）；InitDB 重试/InitDBWithReplicas 重建不再泄漏旧池；Master()/Replicas() 加锁读取（Replicas() 返回拷贝，调用方修改返回切片不影响内部状态）。无 API 签名/配置/migration 变更。下游若依赖 Replicas() 返回活切片并原地修改——属不安全用法，现返回拷贝更安全。
新并发/生命周期/泄漏隐患？ 反而消除。m.mu 统一保护 master/replicas/replicaHealthy/replicaHealthSet/picker 读写；Close 字段置空在锁内、实际关闭在锁外避免持锁阻塞；probeOnce 快照 replicaHealthy 切片头避免与重置竞争（元素为 atomic.Bool）；InitDB 成功安装时关闭旧主库（重建路径覆盖前先释放旧资源，符合纪律）。无 channel/goroutine 新增。-race 已跑通过。

代码审查结果：PASS

closeDB/resetReplicaHealth 职责单一；InitDB 局部打开+原子安装是标准资源生命周期模式；Close 锁内置空+锁外关闭避免持锁阻塞；Replicas() 返回拷贝消除调用方与内部竞争。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

池泄漏（C11b/C11c）消除——重试/重建不再累积未关连接池；无锁读竞争（C11d）消除——避免返回已关闭/nil 池致请求 panic 或使用已释放连接；包级 Close 不再泄漏从库（C11f）。gosec G115/G404 为 RoundRobinPicker/RandomPicker 既有项（C11e 范围外，未改）。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestC11MasterReplicasConcurrentReadWrite：1 写者锁内置换 master/replicas + 4 读者并发 Master/Replicas/Replica/FromContext，50ms 窗口，-race 通过。红/绿验证：回退 Master/Replicas 为裸读后 -race 复现 "race detected"（红）；恢复后绿。
TestC11ReplicasReturnsCopy：修改返回切片不影响 m.replicas（C11d 拷贝语义）。
TestC11ReplicaHealthResetOnRebuild：2→3 从库 + resetReplicaHealth 后 initReplicaHealth 重建对齐 len=3（C11a）。
TestC11ReplicaHealthStaleWithoutReset：不调 reset 时 initReplicaHealth 早返回、健康切片仍 len=2（复现 C11a 缺陷根因，证明 reset 必要）。
TestC11ManagerCloseResetsState：Close 后 master/replicas/replicaHealthy/replicaHealthSet/healthy 全部重置（C11a/C11c/C11d）。
TestC11PackageCloseClosesReplicas：包级 Close 后 replicas 清空（C11f）。红/绿验证：回退包级 Close 为旧 master-only 实现后复现 "expected master nil / residual replicas"（红）；恢复后绿。
TestC11HealthCheckLockedRead：未初始化返错、空 ConnPool 返 ErrInvalidDB 不 panic（C11d）。
注：&gorm.DB{} 内嵌 *Config 为 nil，.DB() 访问提升字段 ConnPool 时 nil deref（-race 下必 panic）；测试用 sentinelDB()（&gorm.DB{Config: &gorm.Config{}}）避免。

已知风险

运行期重建 InitDB/InitDBWithReplicas 与在途请求（MEDIUM，文档化）：InitDB 成功安装新 master 时关闭旧主库池；若运行期重建时有在途请求持有旧 *gorm.DB，其连接会被关闭致失败。框架不支持运行期热 DB 重建（重建应在启动/停服期），调用方须自行保证不与在途请求并发。原实现覆盖致泄漏，现改为关闭旧池——更符合"覆盖前先释放旧资源"纪律，但暴露了运行期重建的固有风险。
healthy 移到 Ping 通过后置位（行为微调）：原 InitDB 在 DB() 成功后、Ping 前即 healthy.Store(true)；现改为 Ping 通过后才置位。更正确（连通≠可服务），不影响 readiness 语义（InitDB 成功返回即 healthy=true）。
Replicas() 返回拷贝（行为微调）：原返回活切片，现返回拷贝。更安全，但下游若原地修改返回切片不再影响内部状态（原即不安全用法）。
gosec G115/G404（既有，C11e 范围外）：RoundRobinPicker uint64→int 取模、RandomPicker math/rand，非本次引入，C11e 已澄清非缺陷。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec（C11 相关无新增 issue）通过。

后续优化建议

C11e（可选微优化）：RandomPicker 用 math/rand/v2 或局部 rand 源减少全局锁竞争；RoundRobinPicker G115 加边界注释。
运行期 DB 重建若需支持，提供 Manager.Swap(newManager) 原子替换 + 旧 manager 延迟关闭（待在途请求结束）。
DefaultManager 包级 var 仍是固定实例；若未来需支持多实例切换，参考 C10 的 atomic.Pointer 模式。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race/vet/gosec + 回退实验复核 10 项：C11a/C11b/C11c/C11d/C11f 全部 CONFIRM 修复，C11e 正确未改。每条受保护字段读均在 m.mu 或 atomic 下；每条重试/失败/重建路径打开的池均关闭，无泄漏/双关；resetReplicaHealth 在重建/关闭时按新 replicas 长度重建健康；probeOnce 切片头快照安全（陈旧数组写为无害 no-op，GC 可达、atomic、OOB 守卫）；包级 Close 委托 CloseAll 关主+从。无死锁、无裸断言、无 send-on-closed、探活循环有 ctx.Done。关键：回退 Master/Replicas/Replica 为裸读后并发测试实跑复现真实 DATA RACE（红），证明非假绿。无 CRITICAL/HIGH/MEDIUM。1 项 LOW（测试覆盖，非代码缺陷）：C11a/C11b/C11c 的端到端泄漏路径（真实池 open+Ping 失败+重建）未用例覆盖（框架无 SQLite 驱动，需真实 DB），由源码审查 + 新 helper 单测 + 表征测试保证；C11d 满足完整红绿。裁定：可交付 PASS。

✅ C9c `jwt/jwt.go` 包级 DefaultJWT/tokenBlacklist 无锁置换 — P1

需求分析结果

C9c（jwt.go:124-129,139,243,289）：SetDefaultJWTManager 裸写包级 DefaultJWT 与 tokenBlacklist（DefaultJWT = m; tokenBlacklist = m.blacklist），而请求 goroutine 经 ParseToken/RefreshToken/InvalidateToken/InvalidateTokenByID/IsTokenRevoked 裸读 tokenBlacklist——指针读写竞争。典型启动期调用 SetDefaultJWTManager，但请求期并发读裸指针仍有数据竞争（-race 可采）。
C9a/C9b 已在 C9b 修复（fail-closed + ErrBlacklistUnavailable）；C9c 是遗留的并发隐患。

方案设计摘要

新增内部 defaultManager atomic.Pointer[Manager] 作真实存储，init() Store(NewJWTManager())。
新增 currentManager()（atomic Load，nil 防御回退）/currentBlacklist() helper。
SetDefaultJWTManager(m) 改 defaultManager.Store(m) 原子置换 + 同步 DefaultJWT = m 兼容别名。
移除裸写的包级 tokenBlacklist 变量；包级函数（ParseToken/RefreshToken/InvalidateToken/InvalidateTokenByID/IsTokenRevoked）改经 currentBlacklist() atomic 读取。
DefaultJWT 保留导出 *Manager 类型不变（非 breaking），作兼容别名，注释标注直接读非并发安全。

涉及模块：jwt/jwt.go、jwt/jwt_c9c_internal_test.go。DB 影响：无（Redis key 语义不变）。API 影响：公共 API 签名全不变；DefaultJWT 类型不变（非 breaking）；行为变更（包级黑名单读写改经 atomic，SetDefaultJWTManager 可安全在请求期调用）。安全影响：正向。风险：见"已知风险"。

修改文件清单

jwt/jwt.go：新增 sync/atomic 导入；defaultManager atomic.Pointer[Manager] + init() Store；DefaultJWT 改为 *Manager 兼容别名（init 同步）；currentManager()/currentBlacklist()；SetDefaultJWTManager 改 atomic Store；移除 tokenBlacklist 包级变量；5 处包级函数改 currentBlacklist()。
jwt/jwt_c9c_internal_test.go（新）：并发 SetDefaultJWTManager + 包级函数读（-race）、置换后包级函数读到新 Manager blacklist、DefaultJWT 别名与 defaultManager 一致。

实现内容摘要

包级黑名单读写改 atomic.Pointer（消除裸指针竞争）；DefaultJWT 兼容别名保留（非 breaking）；SetDefaultJWTManager 原子置换。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名全不变；DefaultJWT 类型不变（*Manager）。SetDefaultJWTManager/NewJWTManager/NewJWTManagerWithRedis/Blacklist() 行为不变。C9b 的 fail-closed 语义保留（currentBlacklist().Add 仍返 ErrBlacklistUnavailable）。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 非 breaking：DefaultJWT 类型不变、签名不变。行为变更（已 CHANGELOG 声明）：包级黑名单读写改经 atomic，SetDefaultJWTManager 可安全在请求期调用（原裸写仅启动期安全）。下游若直接读 jwt.DefaultJWT 变量——仍可用（兼容别名），但直接读非并发安全（注释标注），并发访问应用包级函数。
新并发/生命周期/泄漏隐患？ 反而消除。atomic.Pointer 消除裸指针读写竞争；currentManager() nil 防御回退（init 后不可达，多 goroutine 并发回退创建多实例极罕见且无害，Store 最后一个赢）；无 channel/goroutine/close 新增。-race 已跑通过。

代码审查结果：PASS

atomic.Pointer[Manager] + init() Store 是标准模式（与 C10 config 一致）；currentManager()/currentBlacklist() 封装 atomic 读取；DefaultJWT 兼容别名 + 注释约束清晰。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

包级黑名单读写竞争消除（C9c）；C9b fail-closed 语义保留；SetDefaultJWTManager 可安全在请求期调用。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestC9cConcurrentSetDefaultAndRead：1 写者原子置换 Manager + 4 读者并发 ParseToken/IsTokenRevoked/InvalidateTokenByID/currentManager，50ms 窗口，-race 通过。红/绿验证：回退 currentManager() 为裸读 DefaultJWT 后 -race 复现 "race detected"（红）；恢复 atomic 后绿。
TestC9cCurrentManagerReflectsSwap：无 Redis → ErrBlacklistUnavailable；置换为 Redis Manager 后 InvalidateTokenByID 成功 + currentManager 反映置换（C9c 一致性）。
TestC9cDefaultJWTAliasConsistent：init 后 DefaultJWT == currentManager；SetDefaultJWTManager 后同步（兼容别名一致性）。

已知风险

DefaultJWT 兼容别名裸写（LOW，文档化）：SetDefaultJWTManager 内 DefaultJWT = m 仍为裸写，与"外部直接读 jwt.DefaultJWT"竞争。但包级函数不读 DefaultJWT（经 atomic defaultManager），C9c 范围内的请求 goroutine 读竞争已修复。外部直接读 DefaultJWT 是导出变量固有问题，注释已标注非并发安全。完全消除需将 DefaultJWT 改 atomic.Pointer（breaking 类型变更），权衡后选非 breaking 方案。
currentManager() nil 回退创建多实例（极罕见，无害）：仅 init 前或异常清空触发，多 goroutine 并发回退会创建多个 NewJWTManager，Store 最后一个赢，其余被 GC。blacklist 懒取全局 Redis，多实例无害。
C9b 测试 setupMiniRedis 仍经 SetDefaultJWTManager：现在经 atomic Store，cleanup 还原同样安全；-shuffle 已跑通过。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

若下游不再依赖 jwt.DefaultJWT 直接读取，可于下个大版本将其改 atomic.Pointer[Manager]（breaking）彻底消除兼容别名裸写。
currentManager() nil 回退可用 sync.Once 兜底避免多实例（当前无害，可选）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race/vet/gosec/-shuffle -count=3 + 变异红绿复核 10 项：C9c CONFIRM 修复——5 个包级函数（ParseToken/RefreshToken/InvalidateToken/InvalidateTokenByID/IsTokenRevoked）均经 currentBlacklist()→defaultManager.Load() atomic 读取，裸 tokenBlacklist 变量已彻底移除，无生产路径直接读 DefaultJWT；SetDefaultJWTManager atomic Store + nil 守卫 + 兼容别名同步；init 一致性、C9b fail-closed 语义保留、currentManager() nil 回退安全（不可达）、Blacklist() 锁无害、无新裸全局、类型断言全 comma-ok。关键：变异 currentManager() 为裸读 DefaultJWT 后 -race 实跑复现真实 DATA RACE（read jwt.go:145 vs write jwt.go:166，红），恢复后绿。无 CRITICAL/HIGH/MEDIUM。3 项 LOW（均不阻断）：L1 DefaultJWT = m 兼容别名裸写（仅影响外部直接读 DefaultJWT，包级函数不读，C9c 范围外，注释+CHANGELOG 已标注，彻底消除需 breaking 类型变更）；L2 currentManager() nil 回退未同步 DefaultJWT（运行时不可达，防御性）；L3 errorIsBlacklistUnavailable 用字符串比较（当前正确，外部测试已用 errors.Is）。裁定：可交付 PASS。

✅ H3 `middleware/logger.go` 请求/响应 body 无上限读 → OOM — P1

需求分析结果

LoggerWithConfig 在 LogRequestBody:true 时用 io.ReadAll(c.Request.Body)（logger.go:60）无封顶读入内存，MaxBodyLength 仅在读完后截断日志副本，全 body 已驻留并二次 buffer——多 GB POST 可 OOM。响应侧 bodyLogWriter.body 同样无上限累积，大响应亦 OOM。默认配置 LogRequestBody:false 使默认安全，但 LoggerForAPI/LoggerForDebug 显式开启即暴露。

方案设计摘要

请求体：新增 readBodyBounded(c, maxLen)——io.LimitReader(body, maxLen+1) 仅向内存读入最多 maxLen+1 字节（+1 检测截断），通过 io.MultiReader(已读前缀, 原始 body 剩余) 复原 c.Request.Body，下游处理器仍得完整 body；日志副本截断到 maxLen。
响应体：bodyLogWriter 增 maxLen 字段，appendBounded 写缓冲区封顶；Write/WriteString 仍把完整响应写入下游 ResponseWriter，仅捕获缓冲区封顶。
LoggerWithConfig 入口归一化 MaxBodyLength：<=0 回退默认 1024，确保请求/响应两侧均有上限（消除复审 MEDIUM：手配 MaxBodyLength:0 时响应侧无上限的 OOM 残留）。
maxLen<=0 在 readBodyBounded 内亦回退默认（防御）。

改动文件

middleware/logger.go：readBodyBounded 新增；LoggerWithConfig 入口归一化 + 请求/响应 body 段改用封顶路径；bodyLogWriter 加 maxLen + appendBounded。
middleware/logger_internal_test.go（新增）：8 个用例。

验证

go test -buildvcs=false -race ./middleware/ 通过；go test -buildvcs=false -race ./... 全绿。
go vet -buildvcs=false ./middleware/ 通过。
回归用例（修复前红/后绿）：
- TestReadBodyBounded_TruncatesLogCopy：日志副本封顶到 maxLen（原 io.ReadAll 会读全量）。
- TestReadBodyBounded_RestoresFullBody：8000 字节 body、maxLen=64，下游 io.ReadAll(c.Request.Body) 仍得完整 8000 字节（MultiReader 复原闭环）。
- TestBodyLogWriter_Bounded：10000 字节响应，捕获缓冲区=32（封顶），下游 ResponseWriter 仍收完整 10000 字节。
- TestBodyLogWriter_MultiWriteAccumulation/WriteStringBounded：多写累积与 WriteString 路径同样封顶。
- TestLoggerWithConfig_NormalizesMaxBodyLength：MaxBodyLength:0 归一化为默认，5000 字节请求体下游完整复原。
staticcheck 因环境（go1.24 vs go1.25）无法运行，显式跳过；gosec 非 OOM 专项未跑（本项为内存封顶，非注入/认证类）。

已知风险

无 breaking change：LoggerConfig 字段与默认值不变；MaxBodyLength 现同时门控响应体捕获（此前响应侧无视该值无上限累积，属 bug 修正）；MaxBodyLength<=0 不再意味"无上限"，统一回退默认上限（行为变更，已在 CHANGELOG 声明）。
请求体复原用 io.NopCloser(io.MultiReader(...))，原 c.Request.Body 的 Close 由 net/http server 经连接级 reqBody 引用管理（非 handler/gin 职责），NopCloser 不影响生命周期——经独立复审回源 net/http/server.go:1093,1716 确认。
请求侧用例不直接观测 OOM（内存属性，单测不可见），而是作为 MultiReader 复原正确性的回归守卫；TestBodyLogWriter_Bounded 为真正"修复前红/后绿"的 OOM 复现用例。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race/vet 复核 5 项核心断言全部确认：请求侧封顶 maxLen+1、MultiReader 复原无字节丢失（含 +1 检测位）、原 body 由 net/http 关闭（NopCloser 不泄漏）、响应缓冲区封顶且完整响应转发、旧 io.ReadAll 无上限路径彻底移除。提出 1 项 MEDIUM（请求/响应侧 maxLen<=0 不对称，响应侧仍可无上限——已修：LoggerWithConfig 入口归一化）+ 3 项 LOW（死分支——已简化；测试 OOM 复现性表述——已补 TestBodyLogWriter_Bounded 作真复现；多写/WriteString 覆盖——已补用例）。裁定：可交付 PASS。

✅ H7 `logger/logger.go` 全局指针写有锁读无锁 + `Field.Duration` 签名与实现矛盾 — P1

需求分析结果

H7a（logger.go:121-131,193-200,235-247,280-282,167-178）：Init/Close 持 m.mu（LogManager 实例锁）写包级 Logger/sugar/apiLog/dbLog，但 Info/Debug/Warn/Error/Fatal/Debugf-Fatalf/APILog/DBLog/Sync 等请求期函数无锁裸读这些全局——实例锁保护包级全局变量，锁与被保护对象作用域错配，热重载 re-Init/Close 与请求日志 goroutine 存在数据竞争（-race 可采）。
H7b（field.go:24-31）：Field.Duration 签名为 func(key string, value interface{}) zap.Field，实现 case zap.Field: return v 丢弃 key，签名与实现矛盾；调用方传 zap.Field 时 key 被静默丢弃。

方案设计摘要

H7a：新增内部 loggerPtr/sugarPtr/apiLogPtr/dbLogPtr atomic.Pointer[...] 作真实存储，init() Store 为 Nop；抽取 currentLogger()/currentSugar()/currentAPILog()/currentDBLog()（atomic Load，nil 防御回退 Nop）；Info/Debug/Warn/Error/Fatal/Debugf-Fatalf/APILog/DBLog/Sync 读路径统一经之。Init/Close 在 m.mu 下 Store atomic（写侧仍持锁串行化 closeFileWriters+fileWriters 重置）。
H7a 兼容别名：Logger 保留为导出 *zap.Logger 兼容别名（类型不变，非 breaking，与 C9c 的 DefaultJWT 同模式），由 Init/Close 在 m.mu 下同步维护；注释标注直接读 Logger 变量在 re-Init/Close 期间非并发安全，并发访问应用包级函数。框架内部读路径不读 Logger 变量（经 atomic）。
H7b：Field.Duration 签名改为 func(key string, value time.Duration) zap.Field，直接委托 zap.Duration(key, value)，类型安全、key 不再可能被丢弃。
顺带：os.MkdirAll 日志目录权限 0o755→0o750（与 storage 目录权限一致，gosec G301）。

涉及模块：logger/logger.go、logger/field.go、logger/logger_h7_internal_test.go。DB 影响：无。API 影响：Logger 类型不变（非 breaking）；Field.Duration 签名收紧（interface{}→time.Duration，类型安全）。安全影响：正向。风险：见"已知风险"。

修改文件清单

logger/logger.go：新增 sync/atomic 导入；loggerPtr/sugarPtr/apiLogPtr/dbLogPtr atomic.Pointer + init() Store；currentLogger/currentSugar/currentAPILog/currentDBLog；Logger 改为兼容别名（init 同步 Nop）；Init/Close 改 Store atomic + 同步 Logger 别名；Info/Debug/Warn/Error/Fatal/Debugf-Fatalf/APILog/DBLog/Sync 读路径改经 current* helper；MkdirAll 0o750。
logger/field.go：新增 time 导入；Field.Duration 签名改 func(key string, value time.Duration) zap.Field，委托 zap.Duration，删除 case zap.Field 丢弃 key 的旧实现。
logger/logger_h7_internal_test.go（新）：并发 Init/Close + 包级读（-race）、currentLogger 随 Init/Close 切换、atomic 快照非 nil 且 APILog/DBLog 一致、Field.Duration 行为 + 编译期签名锁定。

实现内容摘要

包级 logger 读写改 atomic.Pointer（消除请求期裸读竞争，H7a）；Logger 兼容别名保留（非 breaking）；Field.Duration 类型安全签名（H7b）；日志目录权限收紧。

三个全局问题（强制回答）

与既有体系契约一致？ 是。Info/Debug/.../APILog/DBLog/Sync/Init/Close/SetDefaultLogManager 签名全不变；Logger 类型不变（*zap.Logger）。APILog()/DBLog() 仍返回 *zap.Logger，仅内部经 atomic 读取。无 DB/路由/认证/响应体系新契约。与 C9c（jwt）/C10（config）的 atomic.Pointer 模式一致。
对下游意味着什么 / breaking change？ 非 breaking（Logger 类型不变、包级函数签名不变）。Field.Duration 签名收紧（interface{}→time.Duration）：传 time.Duration 的调用方不受影响；传 zap.Field 等非 Duration 类型将编译失败——这正是 H7b 修复目的（消除 key 被丢弃的歧义用法）。仓库内无 Field.Duration 调用方，影响面为零。行为变更（已 CHANGELOG 声明）：包级日志读路径改经 atomic，re-Init/Close 可安全与请求日志并发；Logger 直接读仍非并发安全（兼容别名固有限制，注释+CHANGELOG 标注）。
新并发/生命周期/泄漏隐患？ 反而消除。atomic.Pointer 消除请求期裸指针读写竞争；init() Store 保证任何时刻 Load 非 nil；current* helper nil 防御回退 Nop（init 后不可达）；fileWriters 仍仅在 m.mu 下访问（Init/Close/closeFileWriters），无读侧竞争。无 channel/goroutine/close 新增。-race 已跑通过。

代码审查结果：PASS

atomic.Pointer + init() Store 与 C9c/C10 一致；current* helper 封装 atomic 读取 + nil 防御；Logger 兼容别名 + 注释约束清晰（同 C9c DefaultJWT 模式）；Field.Duration 委托 zap.Duration 是类型安全正解。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

请求期裸读竞争消除（H7a）；Field.Duration key 丢弃漏洞消除（H7b）；日志目录权限收紧 0750（G301 清零）。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestH7ConcurrentInitCloseAndRead（internal）：1 写者循环 Init/Close + 4 读者并发 currentLogger/currentSugar/currentAPILog/currentDBLog/APILog/DBLog，120ms 窗口，-race 通过。红/绿验证：将 currentLogger() 临时改为裸读 Logger 兼容别名后 -race 实跑复现 WARNING: DATA RACE（红）；恢复 atomic 后绿。
TestH7CurrentLoggerReflectsInitAndClose：Init 前 Nop 安全；Init 后 currentLogger()==Logger 且写 mark 落 app.log；Close 后回 Nop 不再落盘。
TestH7AtomicPointersNonNil：init 后四个 atomic 快照非 nil，APILog/DBLog/currentLogger 与内部 atomic 一致。
TestH7DurationFieldFix：Field.Duration("elapsed", 5s) key 保留 + Integer 承载纳秒（行为）。
TestH7DurationFieldSignature：编译期锁定签名 func(string, time.Duration) zap.Field。红/绿验证：回退 Field.Duration 为旧 interface{} 签名后编译失败 cannot use Field.Duration ... as func(string, time.Duration) zap.Field（红）；恢复后绿。

已知风险

Logger 兼容别名裸写（LOW，文档化）：Init/Close 内 Logger = ... 仍为裸写，与"外部直接读 logger.Logger"竞争。但框架内部读路径不读 Logger 变量（经 atomic loggerPtr），H7a 范围内的请求 goroutine 读竞争已修复。外部直接读 Logger 是导出变量固有问题，注释+CHANGELOG 已标注非并发安全。完全消除需将 Logger 改 atomic.Pointer[zap.Logger]（breaking 类型变更），权衡后选非 breaking 方案（同 C9c L1）。
re-Init 与在途写入并发（设计约束，非 H7 范围）：并发测试中读者不调用 .Info 等写方法——因为旧 logger 快照对其已被 re-Init 关闭的 lumberjack writer 调用 Write 会触发 lumberjack 重新打开同一文件，致测试 TempDir 清理时句柄占用。框架不支持 re-Init 与在途写入并发（re-Init 主要服务于测试/启动期），该约束非 H7 引入。
实例锁保护全局变量的写侧（预存，非 H7 引入）：m.mu 串行化同 LogManager 实例的 re-Init；不同 LogManager 实例并发 Init 写同一包级全局仍可能交错（closeFileWriters+fileWriters 重置非跨实例原子），但实际仅 DefaultLogger 单实例使用，且 atomic Store 保证读侧安全。预存设计，未恶化。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

若下游不再依赖 logger.Logger 直接读取，可于下个大版本将其改 atomic.Pointer[zap.Logger]（breaking）彻底消除兼容别名裸写（同 C9c 建议）。
current* helper 的 nil 回退可用 sync.Once 兜底避免多实例（当前无害，可选）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race/vet/gosec + 变异红绿复核 9 项：H7a/H7b 全部 CONFIRM 修复——所有请求期读路径（Info/Debug/Warn/Error/Fatal/Debugf-Fatalf/APILog/DBLog/Sync）均经 current* helper→atomic Load，旧 sugar/apiLog/dbLog 裸变量已彻底移除，无生产路径直接读 Logger 变量；Init/Close 在 m.mu 下 Store 四个 atomic + 同步 Logger 兼容别名，无半初始化泄漏；init() 保证 Load 非 nil，nil 回退为不可达防御；fileWriters 仍仅锁内访问；Field.Duration 签名收紧 + 委托 zap.Duration，旧 case zap.Field 丢 key 分支已删。关键：变异 currentLogger() 为裸读 Logger 后 -race 实跑复现真实 WARNING: DATA RACE（read test:82 vs write logger.go:183/256，红），恢复后绿——证明非假绿。H7b 签名锁定为真编译期守卫。go test -race/vet/gosec 全清。无 CRITICAL/HIGH/MEDIUM。1 项 LOW（预存，非 H7 引入）：SetDefaultLogManager 裸写 DefaultLogger（同 C9c DefaultJWT 兼容别名模式），仅 DefaultLogger 单实例实际使用，H7 未触及也未恶化，四 atomic 仍为读侧唯一真源。裁定：可交付 PASS。

✅ C12 `cron/cron.go` 数据竞争 + 重叠执行 + 漂移 + Weekly 跳周 + cron 解析缺陷 — P1

需求分析结果

C12a（cron.go:141-152,104-125）：runTask 无锁写 LastRun/RunCount（:142-143），NextRun 部分在锁内；GetTask/ListTasks 返回 live 指针，请求/管理 goroutine 并发读 → data race。
C12b（cron.go:147-149,200-209）：NextRun 在 handler 完成后才更新，checkAndRun 每秒 tick 反复 go runTask，长任务跨 tick 重叠执行。
C12c（cron.go:148,218-219）：NextRun 以 handler 完成后 time.Now() 锚定，每周期累积 handler 时长 → 调度漂移。
C12d（cron.go:255-263）：WeeklySchedule.Next daysUntil <= 0 → +7 仅按 weekday 差值，不比较当天时刻；当天目标未到点（周一 9:00 目标、周一 8:00 当前）被跳一周。
C12e（cron.go:310-434）：parseInt 忽略非数字逐位累积 → 1-5,8 先判 - 把整字段当范围、parseInt("5,8")=58；garbage→0 误触发；*/garbage→step=0→匹配全部；周日 7 不匹配。

方案设计摘要

C12a：LastRun/RunCount/NextRun 写入一律在 s.mu 写锁内；GetTask/ListTasks 返回 cp := *task 拷贝快照。
C12b：Task 新增未导出 running *atomic.Bool（AddTask 初始化）；checkAndRun 与 RunTask 经 CompareAndSwap(false,true) 占用守卫，正在执行则跳过/返"任务正在执行中"错；spawn goroutine defer running.Store(false)。
C12c：checkAndRun spawn 前 task.NextRun = task.Schedule.Next(task.NextRun)（以上次 NextRun 锚定，非 time.Now()），RunTask/runTask 不再更新 NextRun。
C12d：WeeklySchedule.Next 重写为 daysUntil=((day-now)+7)%7 加天数后 !next.After(now) 才 +7。
C12e：matchField 重写——先按逗号拆列表，每项独立判 */n/a-b/n/a-b/单值（列表分支独立于范围分支），全用 strconv.Atoi 返错；weekday 7→0，范围 lo>hi 环绕；歧义范围 0-7/7-0 拒绝。新增 ParseCronStrict 严格校验；ParseCron 保留签名非法回退全 *。

涉及模块：cron/cron.go、cron/cron_c12_test.go、cron/cron_c12_internal_test.go。DB 影响：无。API 影响：ParseCron 仍返 *FullCronSchedule（非 breaking），新增 ParseCronStrict；AddTask/RunTask/GetTask/ListTasks 签名不变；Task 新增未导出 running。安全影响：正向。风险：见"已知风险"。

修改文件清单

cron/cron.go：Task 加 running *atomic.Bool；AddTask 初始化；GetTask/ListTasks 返回拷贝；RunTask 加 running 守卫 + 锁内写、不再更新 NextRun；删 runTask；checkAndRun 改写锁 + CAS 守卫 + spawn 前推进 NextRun（锚定 task.NextRun）+ goroutine 锁内写 LastRun/RunCount；WeeklySchedule.Next 重写；matchField/matchCronItem/parseCronRange 重写（strconv.Atoi + 列表独立 + 7→0 + 环绕 + 歧义拒绝）；splitPattern 改 strconv.Atoi；删 parseInt/split；新增 ParseCronStrict/validateCronField/validateCronItem，ParseCron 委托 strict 失败回退。
cron/cron_c12_test.go（新）：C12a 并发读写（-race）+ GetTask/ListTasks 拷贝；C12b 手动触发守卫返错；C12d Weekly 三场景；C12e 周日 7/范围环绕/严格解析/回退/简化 Cron garbage。
cron/cron_c12_internal_test.go（新）：C12b 手动驱动 checkAndRun 防重叠；C12c NextRun 锚定（stepSchedule 确定性）；C12e matchField 直接测试（1-5,8/garbage/*/garbage/7/范围步长列表）。

实现内容摘要

数据竞争消除（C12a 锁内写 + 拷贝）；重叠守卫（C12b atomic.Bool CAS）；漂移消除（C12c 以上次 NextRun 锚定）；Weekly 当天未到点不跳周（C12d）；cron 解析类型安全 + 严格校验（C12e）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。AddTask/RunTask/GetTask/ListTasks/RemoveTask/EnableTask/DisableTask/Start/Stop/ParseCron/Every/Daily/Weekly/Cron 签名全不变；ParseCron 仍返 *FullCronSchedule，非法回退全 *（保持原行为）。Task 新增未导出 running（外部不可构造/操作）。无 DB/路由/认证/响应体系新契约。拷贝快照模式同 C11 Replicas()/C10 Load；atomic 守卫同 C9c/C10/H7 模式。
对下游意味着什么 / breaking change？ 非 breaking（公共 API 签名不变，ParseCron 行为兼容）。行为变更（已 CHANGELOG 声明）：GetTask/ListTasks 返回拷贝（修改返回值不影响内部状态——原即不安全用法）；RunTask 占用守卫期间再次调用返"任务正在执行中"错误；长任务不再重叠执行；调度不漂移；Weekly 当天未到点不再跳周；cron 解析拒绝非法表达式（ParseCron 非法回退默认全 *，新增 ParseCronStrict 严格校验）。新增 ParseCronStrict（非 breaking）。
新并发/生命周期/泄漏隐患？ 反而消除。LastRun/RunCount/NextRun 写入全在 s.mu；running *atomic.Bool 守卫每个 CAS-true 配 defer Store(false)（handler panic 亦触发 defer，不泄漏守卫）；checkAndRun 持写锁推进 NextRun 后 spawn，goroutine 锁内写（不嵌套，loop 锁在 spawn 前释放）；Stop 的 wg.Wait 与 wg.Add 经 sync.WaitGroup 文档语义安全（run loop 退出前 counter>0）。-race 已跑通过（含对抗性 Start/Stop 50 轮 + 20 并发）。

代码审查结果：PASS

running *atomic.Bool 指针避免 cp := *task 触发 copylocks（vet 清）；checkAndRun spawn 前推进 NextRun + CAS 守卫双保险；matchField 列表独立分支 + strconv 类型安全；parseCronRange 歧义范围拒绝。独立复审未发现 CRITICAL/HIGH/MEDIUM。

安全审查结果：PASS

数据竞争消除（C12a）；重叠执行消除（C12b，防资源竞争/重复副作用）；cron 解析拒绝非法表达式（C12e，防误匹配致任务误触发/漏触发）。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证，5 项变异均复现红）：

TestC12aConcurrentReadWriteNoRace：4 读者 GetTask/ListTasks 读字段 + 1 写者 RunTask，-race 通过。变异：RunTask 写去锁 → WARNING: DATA RACE（read ListTasks:132 vs write RunTask:164，红）。
TestC12aGetTaskReturnsCopy/ListTasksReturnsCopies：修改返回拷贝不污染内部。
TestC12bNoOverlapManualDrive（internal）：手动驱动两轮 checkAndRun，handler 阻塞，断言 started=1。变异：去 CAS 守卫 → started=2（红）。
TestC12bRunTaskConcurrentManualTriggerReturnsError：手动 RunTask 占用守卫期间再次调用返错。
TestC12cNextRunAnchoredOnPrevious（internal）：stepSchedule 确定性，NextRun 设过去锚点 T0，3 轮后断言 NextRun=T0+3*step。变异：锚定改 time.Now() → 超时明确失败（NextRun 跳未来不再到期，红）。
TestC12dWeeklySameDayBeforeTarget/AfterTarget/CrossWeek：当天未到点本周/已过下周/跨周。变异：旧 daysUntil<=0→+7 → 跳一周（红）。
TestC12eMatchField*（internal）：1-5,8 仅匹配 1-5 与 8；garbage 不匹配；/garbage 不匹配全部；weekday 7=周日；范围/步长/列表。变异：旧 parseInt → 1..58 全匹配/garbage 匹配 0//garbage 匹配 60/7 失败（红）。
TestC12eWeekdaySundayAs7/RangeWraparound：0 0 * * 7 落周日；6-1 环绕匹配周六周日周一、跳周二。
TestC12eParseCronStrict：合法/越界/歧义/step=0 校验。
TestC12eParseCronFallback：ParseCron("invalid") 回退全 *；合法不回退。
TestC12eCronScheduleGarbageNoMatch：简化 Cron garbage 不再 parseInt 为 0。

已知风险

Stop 阻塞于忽略 ctx 的 handler（预存，非 C12 引入）：Stop 调 wg.Wait() 等在途 handler 完成；若下游 handler 不响应 s.ctx（已取消）而无限阻塞，Stop 会挂起。框架已将取消的 s.ctx 传入 handler，契约要求 handler 响应 ctx。预存优雅关闭语义，C12 未引入也未恶化。
0-7/7-0 歧义范围拒绝（行为变更）：标准 cron 中 0-7 语义为整周，本实现因 0/7 均为周日会坍缩成仅周日，故拒绝（ParseCronStrict 返错、ParseCron 回退全 *）。下游用 0-7 需改 0-6 或 *。已 CHANGELOG 声明。
checkAndRun 1s ticker 粒度（预存，非 C12 范围）：调度精度受 1s ticker 限制，亚秒级调度实际按 1s 粒度触发。预存设计，C12 未触及。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

checkAndRun ticker 可配置化（支持亚秒级调度精度）。
Stop 可加超时（避免忽略 ctx 的 handler 致关闭挂起）。
0-7 若需支持整周语义，可在 weekday 范围展开为集合而非区间（当前拒绝已足够安全）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race -count=3/vet/gosec + 5 项变异红绿 + 对抗性 Start/Stop 复核 9 项：C12a/C12b/C12c/C12d/C12e 全部 CONFIRM 修复——所有 task 字段写均在 s.mu、Getter 返回拷贝、running 守卫每 CAS-true 配 defer Store(false) 无泄漏、NextRun 锚定 task.NextRun 且 spawn 前推进、Weekly 三场景正确、matchField 列表独立 + strconv + 7→0 + 环绕 + 歧义拒绝、ParseCron 兼容回退、copylocks vet 清、无死锁/无 wg Add-Wait 竞争。关键：5 项变异（C12a 去锁写 / C12b 去守卫 / C12c 改 now 锚定 / C12d 旧跳周 / C12e 旧 parseInt）均实跑复现红（C12a DATA RACE / C12b started=2 / C12c 超时 / C12d 跳周 / C12e 5 用例全红），恢复后全绿——证明非假绿。无 CRITICAL/HIGH/MEDIUM。1 项 IMPRECISE（C12c 变异经超时而非断言失败——已改进测试加 select+time.After 超时明确失败）。裁定：可交付 PASS。

✅ C13 `trace/trace.go` opt-in 即崩 + 未实现导出器/传播器 + Middleware 不更新 c.Request — P1

需求分析结果

C13a（trace.go:58,160,217,225）：包级 tracer/tracerProvider 裸指针，未 Init 即 nil，Middleware/StartSpan/StartSpanFromContext/GetTracer 裸用 → 首个请求 panic（仅"从未 Init"才崩）。
C13b（trace.go:110-125,84-91）：createExporter default 返 nil, nil 喂 WithBatcher(nil)；stdout 未实现。
C13c（trace.go:113-120）：OTLP 默认 HTTPS+TLS，对 localhost:4318 明文 collector 握手失败，无 WithInsecure。
C13d（trace.go:172）：Middleware 仅 c.Set("otel_ctx", ctx)，未 c.Request = c.Request.WithContext(ctx)，下游 c.Request.Context() 拿不到 span。
C13e（trace.go:128-138）：createPropagator 仅 w3c + default 静默回落 W3C，b3/jaeger 未实现。

方案设计摘要

C13a：tracer/tracerProvider 改 atomic.Pointer + init() Store Noop 兜底；getTracer() 永不 nil；Init 原子替换、Close Shutdown 后 Store 回 Noop（防 Close 后再用 panic）；GetContext 裸断言改 comma-ok。
C13b：新增 case "stdout"（官方 stdouttrace 包）；default 返 fmt.Errorf（不再喂 nil）。
C13c：Config.Insecure bool（零值 false=TLS，opt-in 明文，安全默认），Insecure 时 otlp-http/grpc 追加 WithInsecure()。
C13d：Middleware 补 c.Request = c.Request.WithContext(ctx)（保留 c.Set 兼容）。
C13e：新增 case "b3"（contrib b3 propagator，单头+多头）；case "jaeger" 映射 W3C（现代 Jaeger agent 透传 W3C，不引入不稳定的 jaegerremix）；default 返错；Init 非法 propagator 时返错并回滚 provider。
顺带：resource.Merge 改空 schema URL（resource.Default() 与 semconv v1.24.0 schema 冲突致 Init 报错）。

涉及模块：trace/trace.go、trace/trace_test.go、go.mod/go.sum、GUIDE.md。DB 影响：无。API 影响：Init/Middleware/StartSpan/GetTracer/Close 签名不变；Config 新增 Insecure（零值兼容，非 breaking）。安全影响：正向（默认 TLS 安全）。风险：见"已知风险"。

修改文件清单

trace/trace.go：新增 sync/atomic/os/b3/stdouttrace 导入；Config 加 Insecure；tracer/tracerProvider 改 atomic + init() Store Noop；getTracer()/TracerProvider()；Init 改 atomic Store + Swap 旧 provider 关闭 + 非法 propagator 回滚；createExporter 加 stdout + default 返错 + Insecure option；createPropagator 加 b3/jaeger/default 返错；Close Swap 后 Store Noop 兜底；Middleware 改 getTracer + 更新 c.Request；GetContext comma-ok；StartSpan/StartSpanFromContext/GetTracer 改 getTracer；resource.Merge 空 schema URL。
trace/trace_test.go（新）：TestMain 捕获 init() 快照；C13a init 不变式 + 未 Init 不 panic + Init(Enabled:false) + Close 后用；C13b stdout/未知返错/Init 失败；C13c Insecure 创建；C13d 下游 c.Request.Context() 含 span + 传播提取；C13e b3 注入/jaeger 映射 W3C/未知返错/Init 失败/w3c 默认；GetContext comma-ok。
go.mod/go.sum：新增 stdouttrace v1.43.0、contrib/propagators/b3 v1.43.0。
GUIDE.md：14.1 节补 Insecure/Propagator/导出器类型说明 + 未 Init 安全说明。

实现内容摘要

nil-panic 消除（C13a atomic + Noop 兜底）；stdout 导出器实现 + 未知返错（C13b）；OTLP 明文 opt-in（C13c）；下游 c.Request.Context() 含 span（C13d）；b3 实现 + jaeger 映射 W3C + 未知返错（C13e）；schema 冲突修复。

三个全局问题（强制回答）

与既有体系契约一致？ 是。Init/Middleware/StartSpan/StartSpanFromContext/GetTracer/GetContext/GetTraceID/RecordError/SetAttribute/Close 签名全不变；Config 新增 Insecure（零值兼容）。trace 是横切关注点，无 DB/路由/认证/响应体系契约改动。atomic 守护包级全局同 C9c/C10/H7 模式。
对下游意味着什么 / breaking change？ 非 breaking（公共 API 签名不变，Config.Insecure 零值兼容）。行为变更（已 CHANGELOG/GUIDE 声明）：未 Init 不 panic；未知导出器/传播器返错（不再静默 nil/回落 W3C）；Insecure opt-in 明文（默认 TLS，与 H2 安全默认一致）；Middleware 更新 c.Request（下游 c.Request.Context() 现含 span，原需经 GetContext(c)）；b3 实现、jaeger 映射 W3C；Propagator 空串按 w3c（兼容）。新增两个 OTel 同版本族依赖。
新并发/生命周期/泄漏隐患？ 反而消除。atomic.Pointer 消除裸指针读写竞争；getTracer() 返回接口值快照，请求 goroutine 持有自己的 tracer，即使并发 Init/Close Swap 也不读已释放；Init Swap 旧 provider 后 Shutdown（WithBatcher goroutine 由 provider.Shutdown 排空，无泄漏）；Close Swap 后 Store Noop 兜底防 use-after-shutdown；TestMain 捕获 init() 快照锁定 Noop 不变式。-race 已跑通过（含对抗性并发 Init/Close/read 压测）。

代码审查结果：PASS

atomic.Pointer + init() Store Noop 同 C9c/C10/H7 模式；getTracer() 返回接口值快照避免读已释放；stdout 用官方包；b3 用 contrib 官方包；jaeger 映射 W3C 文档化（不引入不稳定模块）；Init 非法 propagator 回滚 provider。独立复审未发现 CRITICAL/HIGH。

安全审查结果：PASS

opt-in 即崩消除（C13a）；未知导出器/传播器 fail-fast 返错（C13b/C13e，防 nil 喂 WithBatcher/静默错误传播）；默认 TLS（C13c，与 H2 一致）。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证，4 项变异均复现红）：

TestC13aInitNoopInvariant：TestMain 捕获 init() 后 getTracer() 快照，断言非 nil。变异：init() 去 Noop Store → getTracer() nil deref panic（红）。
TestC13aNoInitNoPanic/InitDisabledNoop/CloseThenUseNoPanic：未 Init/Init(Enabled:false)/Close 后包级函数不 panic。
TestC13bStdoutExporterWorks/UnknownExporterReturnsError/InitUnknownExporterFails：stdout 可创建、未知返错、Init 失败。变异：default 返 nil,nil → 用例红。
TestC13cInsecureExporterCreates/OtlpGrpcInsecureCreates：Insecure 路径导出器可创建。
TestC13dRequestContextContainsSpan：下游 c.Request.Context() span TraceID 非空且与 X-Trace-ID 一致。变异：去 c.Request 更新 → 下游 TraceID 全 0（红）。
TestC13dPropagatedTraceContextExtracted：入站 W3C 头提取，下游 span 继承父 TraceID。
TestC13eB3PropagatorImplemented：b3 注入 b3/x-b3-traceid 头。变异：b3 未实现返 W3C → 无 b3 头（红）。
TestC13eJaegerMapsToW3C：jaeger 映射 W3C 注入 traceparent。
TestC13eUnknownPropagatorReturnsError/InitUnknownPropagatorFails/W3CDefault：未知返错/Init 失败/空串 w3c。变异：default 静默回落 → 未知不返错（红）。
TestC13GetContextCommaOk：otel_ctx 污染为非 context 不 panic、回退 c.Request.Context()。

已知风险

jaeger 映射 W3C（文档化，非完整 Jaeger 协议）：jaeger 传播器映射 W3C TraceContext（现代 Jaeger agent 透传 W3C）；纯 Jaeger thrift 头协议需下游用 b3。不引入不稳定的 jaegerremix 模块。已 GUIDE 声明。
Init 关闭旧 provider 时在途 span（MEDIUM，OTel 上游安全）：Init Swap 旧 provider 后 Shutdown；在途 span 的 OnEnd/End 在 Shutdown 后为上游 no-op-safe 路径（OTel batch span processor 保证），对抗性压测无 crash。重新 Init 应在启动期/停服期，非运行期热切换。
新增依赖体积（LOW）：stdouttrace + b3 均为 OTel 官方同版本族，体积可控。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

若需纯 Jaeger thrift 头协议，待 contrib jaegerremix 稳定后接入或自实现 propagator。
Init 运行期热切换可加 sync.RWMutex 串行化 Init/Close（当前 atomic 已足够安全，热切换非框架支持场景）。
semconv 可升级至 v1.40.0 与 resource.Default() schema 对齐（当前空 schema URL 已规避冲突）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race -count=2/vet/gosec + 4 项变异红绿 + 对抗性并发 Init/Close/read 压测 + 独立 go run no-Init panic 复核 10 项：C13a/C13b/C13c/C13d/C13e + schema 修复 + GetContext comma-ok 全部 CONFIRM 修复——init() Store Noop 兜底（独立 go run 验证去 Store 必 panic）、getTracer() 经 atomic 永不 nil、所有读路径经 getTracer()、stdout/default 返错、Insecure opt-in、Middleware 更新 c.Request、b3 实现/jaeger 映射 W3C/default 返错、Init 非法 propagator 回滚、空 schema URL。关键：4 项变异（C13a 去 Noop Store / C13b default 返 nil,nil / C13d 去 c.Request 更新 / C13e 仅 w3c+静默回落）均实跑复现红（C13a nil deref panic / C13b 用例红 / C13d 下游 TraceID 全 0 / C13e b3+未知红），恢复后全绿——证明非假绿。无 CRITICAL/HIGH。1 项 MEDIUM（初始 TestC13aNoInitNoPanic 经 resetGlobal 掩盖 init() 路径——已修：新增 TestMain 捕获 init() 快照 + TestC13aInitNoopInvariant 锁定，变异 init() 去 Store 实跑复现 panic 红）。裁定：可交付 PASS。

✅ H5 `handler` 业务码与 HTTP 状态混乱 + 丢失 RequestID — P1

需求分析结果

H5b（handler.go:157-170）：handler.BadRequest/InternalError 直接 c.JSON(http.StatusBadRequest/StatusInternalServerError, response.Response{...})——硬编 HTTP 400/500 绕过响应模式系统（response/mode.go 的 writeResp→httpStatusFor 受 Mode 控制，ModeBusiness 下所有失败响应应 HTTP 200，错误经 body code 表达），且不写 RequestID（对比 writeResp 在 mode.go:73 写 RequestID）。与 response 体系不一致、丢链路追踪。正是 CLAUDE.md 反模式负面清单"handler 绕过 response 模式系统"。
H5a（response.go:33,43）：Success/SuccessWithMsg 硬编 200——经核验为成功响应，HTTP 200 在两模式下均正确，非缺陷（报告 H5a 已澄清"ModeBusiness 默认全 200 成立"，模式系统真实存在）。

方案设计摘要

BadRequest(c, msg) 委托 response.FailWithCode(c, response.CodeFail, msg)（= response.Fail 语义），InternalError(c, msg) 委托 response.ServerError(c, msg)——两者复用 writeResp 路径，遵循当前 Mode 并经 getRequestID(c) 写入 RequestID。
移除 net/http 导入（仅这两处用到）。无新增 API/配置/契约。

涉及模块：handler/handler.go、handler/handler_test.go。DB 影响：无。API 影响：BadRequest/InternalError 签名不变；行为变更（HTTP 状态遵循 Mode、写入 RequestID）。安全影响：正向（链路追踪不丢、响应体系一致）。风险：见"已知风险"。

修改文件清单

handler/handler.go：删 net/http 导入；BadRequest 改委托 response.FailWithCode；InternalError 改委托 response.ServerError；补注释说明遵循 Mode + 写 RequestID。
handler/handler_test.go：新增 withResponseMode/decodeBody helper；改写 TestBadRequest/TestInternalError 为 ModeBusiness 语义（HTTP 200 + 业务码）；新增 TestBadRequestRESTMode（CodeFail 不映射→200）、TestInternalErrorRESTMode（CodeServerError→500）、TestBadRequestWritesRequestID/TestInternalErrorWritesRequestID（RequestID 闭环）。

实现内容摘要

响应体系一致闭环（委托 writeResp，遵循 Mode + 写 RequestID）；消除 handler 绕过 response 模式系统的反模式。

三个全局问题（强制回答）

与既有体系契约一致？ 是。BadRequest/InternalError 签名不变；现复用 response.FailWithCode/ServerError→writeResp 路径，与 response.Fail*/Unauthorized/NotFound 等完全一致（此前是唯一绕过 Mode 的两个 handler helper）。CodeFail/CodeServerError 业务码不变。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG 声明，非破坏性）：默认 ModeBusiness 下 BadRequest/InternalError 由恒 400/500 改为 HTTP 200（错误经 body code 表达，与所有 response.Fail* 一致）；ModeREST 下 InternalError→500（CodeServerError 映射）、BadRequest→200（CodeFail 属业务失败不映射，与 response.Fail 一致）。两者现写入 RequestID。下游若依赖 handler.BadRequest 恒返 400，应改用 response.Custom(c, 400, code, msg, nil) 或业务自定义 4xxxx 错误码。无 API 签名/配置/migration 变更。
新并发/生命周期/泄漏隐患？ 无。改动为同步函数委托，无 channel/goroutine/包级可变全局/资源生命周期。-race 已跑通过。

代码审查结果：PASS

最小改动（两个函数体各改一行委托 + 删导入 + 注释）；复用既有 writeResp 出口而非另起硬编；无魔法值。无 CRITICAL/HIGH。

安全审查结果：PASS

响应体系一致性修复（消除绕过 Mode 的反模式）；RequestID 不再丢失，链路追踪完整；ModeREST 下 5xx 可被 APM/网关正确捕获（与 C8 同向）。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestBadRequest（ModeBusiness）：HTTP 200 + code=CodeFail + msg。红/绿：回退 BadRequest 为旧 c.JSON(400,...) 后复现 "status = 400, want 200"（红）；恢复后绿。
TestInternalError（ModeBusiness）：HTTP 200 + code=CodeServerError。红/绿：回退为旧 c.JSON(500,...) 后复现 "status = 500, want 200"（红）；恢复后绿。
TestBadRequestRESTMode（ModeREST）：HTTP 200（CodeFail 不映射）+ code=CodeFail。回退后复现 "status = 400, want 200"（红）。
TestInternalErrorRESTMode（ModeREST）：HTTP 500 + code=CodeServerError（锁定 REST 映射；旧实现恒 500 恰同，非红绿回归，作行为锁定）。
TestBadRequestWritesRequestID/TestInternalErrorWritesRequestID：上下文设 request_id，断言响应体含之。红/绿：回退后复现 "request_id = "", want ..."（红，复现 H5b 丢链路）；恢复后绿。
go test -buildvcs=false -race -count=1 ./handler/ ./response/ 全绿；go vet 通过。

已知风险

BadRequest 在 ModeREST 下返 200（语义边角，文档化）：CodeFail 是通用业务失败，按框架 statusForCode 规则不映射 HTTP 错误（与 response.Fail 在 ModeREST 下返 200 一致，mode_test.go:50 已锁定）。函数名"BadRequest"暗示 400，但与 response.Unauthorized（命名暗示 401，ModeBusiness 下返 200）同属框架既有"函数名暗示 HTTP 状态、ModeBusiness 下统一 200"模式。下游需 REST 模式下 400 应改用 response.Custom 或 4xxxx 业务码。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。
改动小而局部（仅 handler 包，无其他包引用 handler.BadRequest/InternalError 的旧 400/500 行为——经 grep 确认仅测试与文档引用），无全局影响，按用户指示跳过独立对抗性复审 agent；红绿 + -race/vet 已实跑。

后续优化建议

视需求为 response 补 BadRequest(c, msg) 便捷函数（用 4xxxx 业务码或 CodeFail），统一"参数错误"出口；当前 handler.BadRequest 委托 FailWithCode(CodeFail) 已足够。
文档（GUIDE）示例可补充"REST 模式下需 400 用 response.Custom"说明。

独立对抗性复审结论

按用户指示（改动小而局部、无全局影响）跳过独立 agent 复审；以源码 file:line + 红绿变异 + -race/vet 实跑自验：H5b CONFIRM 修复——BadRequest/InternalError 均经 response.FailWithCode/ServerError→writeResp，遵循 Mode 并写 RequestID，旧硬编 c.JSON(http.StatusBadRequest/StatusInternalServerError,...) 路径彻底移除；回退变异实跑复现红（400/500≠200、RequestID 为空），恢复后全绿。无 CRITICAL/HIGH。裁定：可交付 PASS。

✅ H4b `middleware/ratelimit.go` CustomRateLimit goroutine 泄漏 — P1

需求分析结果

CustomRateLimit(rate, window)（ratelimit.go:329-332）每次调用 NewRateLimiter 创建一个 RateLimiter，其 cleanupVisitors goroutine 持续运行（每分钟 ticker 清理过期 visitor）。但创建的 limiter 无任何句柄（仅作为闭包捕获返回），StopRateLimiters 只停止 loginLimiter/apiLimiter/uploadLimiter 三个命名限流器，不感知自定义限流器 → cleanup goroutine 永久泄漏。应用每次路由构造调用 CustomRateLimit 即泄漏一个 goroutine，长期运行/反复 reload 路由会累积。InitRateLimiters（re-init 路径）同样不停止旧的自定义限流器。

方案设计摘要

新增包级 customLimiters []*RateLimiter 登记表（受既有 limitersMu 保护）。
新增 drainCustomLimiters() 辅助（锁内取出并清空，调用方持锁）。
CustomRateLimit 创建 limiter 后 append 登记入表。
StopRateLimiters / InitRateLimiters 经 drainCustomLimiters() 取出并逐个 Stop()，释放 cleanup goroutine。
保持原"全程持 limitersMu"语义（不引入锁外 Stop 窗口）：持锁期间调 Stop()→wg.Wait() 安全——cleanupVisitors 取的是 limiter 自身的 rl.mu，非 limitersMu，无死锁；全程持锁避免与 LoginRateLimit 等懒初始化路径交错致覆盖泄漏。

涉及模块：middleware/ratelimit.go、middleware/middleware_test.go。DB 影响：无。API 影响：CustomRateLimit/StopRateLimiters/InitRateLimiters 签名不变；无行为变更（仅修复 goroutine 泄漏，限流语义不变）。安全影响：正向（资源泄漏消除）。风险：见"已知风险"。

修改文件清单

middleware/ratelimit.go：新增 customLimiters 字段 + drainCustomLimiters；InitRateLimiters/StopRateLimiters 增加 for _, l := range drainCustomLimiters() { l.Stop() }；CustomRateLimit 登记。
middleware/middleware_test.go：新增 runtime 导入 + goroutineCount helper + TestCustomRateLimitNoGoroutineLeak（Stop 释放）/TestCustomRateLimitReinitStopsOldCustoms（re-init 释放）。

实现内容摘要

自定义限流器登记闭环（customLimiters 表）；StopRateLimiters/InitRateLimiters 统一停止；cleanup goroutine 不再泄漏。

三个全局问题（强制回答）

与既有体系契约一致？ 是。CustomRateLimit/StopRateLimiters/InitRateLimiters/RateLimit 签名全不变；customLimiters/drainCustomLimiters 未导出。限流语义不变。复用既有 limitersMu 保护（与命名限流器同一锁域）。无 DB/路由/认证/响应体系新契约。
对下游意味着什么 / breaking change？ 非 breaking，无行为变更。CustomRateLimit 现登记创建的限流器，StopRateLimiters/InitRateLimiters 现会停止它们（释放 cleanup goroutine）。下游无 API 签名/配置/migration 变更；下游若依赖"CustomRateLimit 的 limiter 永不被 Stop"——无此合理依赖（Stop 是资源清理，本就该停）。
新并发/生命周期/泄漏隐患？ 反而消除。customLimiters 读写均在 limitersMu 内（CustomRateLimit append 写锁、drainCustomLimiters 在 Stop/Init 持锁内读+清空）；持锁期间调 Stop() 无死锁（不同 mutex）；全程持锁避免懒初始化交错覆盖泄漏。无 channel/goroutine 新增（cleanup goroutine 本就存在，现可正确停止）。-race 已跑通过。

代码审查结果：PASS

登记表 + drain 模式是标准资源生命周期管理；复用既有 limitersMu 不引入新锁；持锁 Stop 无死锁论证清晰；保持原全程持锁语义避免引入交错窗口。独立复审（自验）未发现 CRITICAL/HIGH。

安全审查结果：PASS

goroutine 泄漏消除（应用长期运行/reload 路由不再累积 cleanup goroutine）。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestCustomRateLimitNoGoroutineLeak：创建 5 个 CustomRateLimit → goroutine 数明显增加；StopRateLimiters 后 goroutine 数回落到 before+2 内。红/绿：回退 CustomRateLimit 不登记后复现 "after StopRateLimiters: goroutines = 7, before = 2"（5 个泄漏，红）；恢复后绿。
TestCustomRateLimitReinitStopsOldCustoms：基线 InitRateLimiters（3 命名）→ 创建 2 自定义 → 再 InitRateLimiters → goroutine 数回落到 baseline+1 内（自定义被 drain+Stop）。红/绿：回退不登记后复现 "goroutines = 7, baseline = 5"（2 个泄漏，红）；恢复后绿。
go test -buildvcs=false -race -count=1 ./middleware/ 全绿；go vet 通过。

已知风险

goroutine 计数测试有调度噪声（LOW）：runtime.NumGoroutine 读数受调度影响，测试用 GC+Gosched+轮询窗口（2s deadline）收敛。阈值留 +1/+2 容忍噪声，红绿变异均稳定复现。
StopRateLimiters 持锁期间 Stop 阻塞（LOW，可接受）：Stop()→wg.Wait() 等待 cleanup goroutine 退出（通常毫秒级）。shutdown 路径阻塞可接受；与原实现（同样持锁 Stop）一致。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。
改动小而局部（仅 middleware 包，无其他包引用 CustomRateLimit 的旧行为——经 grep 确认仅测试与文档引用），无全局影响，按用户指示跳过独立对抗性复审 agent；红绿 + -race/vet 已实跑。

后续优化建议

H4c：RedisRateLimiter.Allow Redis 错误 fail-open + result.(int64) 裸断言（独立缺陷，下一项）。
若需自定义限流器独立生命周期管理，可提供 CustomRateLimitWithHandle 返回 *RateLimiter 句柄供调用方自行 Stop（当前登记表统一管理已足够）。

独立对抗性复审结论

按用户指示（改动小而局部、无全局影响）跳过独立 agent 复审；以源码 file:line + 红绿变异 + -race/vet 实跑自验：H4b CONFIRM 修复——CustomRateLimit 创建的 limiter 经 customLimiters 登记表，StopRateLimiters/InitRateLimiters 经 drainCustomLimiters() 逐个 Stop()，cleanup goroutine 不再泄漏；回退变异实跑复现红（Stop 后 5 个泄漏 / re-init 后 2 个泄漏），恢复后全绿。无 CRITICAL/HIGH。裁定：可交付 PASS。

✅ H4c `middleware/ratelimit.go` RedisRateLimiter fail-open + 裸断言 — P1

需求分析结果

H4c-1 fail-open（ratelimit.go:Allow + 中间件）：RedisRateLimiter.Allow Redis 错误时 return true, err（放行），中间件层 err != nil → c.Next() 同样放行。含登录防爆破场景静默失效——Redis 抖动窗口限流失效，攻击者可借机无限爆破。无 fail-closed 选项。Redis 未启用时同样 fail-open（return true, nil）。
H4c-2 裸断言（ratelimit.go:Allow）：result.(int64) 无 comma-ok，Redis 返回非 int64 时 panic。当前 Lua 脚本恒返整数不会触发，属脆弱性（脚本变更/Redis 异常返回即 panic）。

方案设计摘要

H4c-1：RedisRateLimiter 新增未导出 failClosed bool 字段（零值 false=兼容默认 fail-open）。Allow 在 Redis 未启用/错误时按策略决定：fail-closed 返 (false, err) 拒绝，fail-open 返 (true, err) 放行（兼容旧行为）。中间件层抽取 redisLimitDecision(c, allowed, err)——不再无条件 fail-open，按 allowed 值决定：err!=nil && !allowed（fail-closed 故障）返 503（CodeServiceUnavailable，区别于真实超限的 429），!allowed（真实超限）返 429，allowed 放行。
H4c-2：result.(int64) 改 comma-ok，断言失败返 ErrRedisRateLimiterUnexpectedResult（按 failClosed 策略拒绝/放行）而非 panic。
新增构造函数 NewRedisRateLimiterFailClosed、切换方法 SetFailClosed、中间件 RedisRateLimitFailClosed/CustomRedisRateLimitFailClosed、导出错误 ErrRedisRateLimiterUnavailable/ErrRedisRateLimiterUnexpectedResult。
LoginRedisRateLimit 改 fail-closed（行为变更）：登录防爆破 Redis 故障时拒绝（503），防限流静默失效。其余 Redis 限流中间件保持 fail-open（兼容默认）。

涉及模块：middleware/ratelimit.go、middleware/middleware_test.go、GUIDE.md、CHANGELOG.md。DB 影响：无（Redis key 语义不变）。API 影响：既有函数签名不变；RedisRateLimiter 新增未导出 failClosed；新增 fail-closed 变体 + 导出错误。行为变更（LoginRedisRateLimit 改 fail-closed）。安全影响：正向（防爆破 fail-closed + 断言不 panic）。风险：见"已知风险"。

修改文件清单

middleware/ratelimit.go：新增 errors/net/http 导入；RedisRateLimiter 加 failClosed 字段；新增 ErrRedisRateLimiterUnavailable/ErrRedisRateLimiterUnexpectedResult；NewRedisRateLimiterFailClosed/SetFailClosed；Allow 改按策略 + comma-ok；抽取 redisLimitDecision；新增 RedisRateLimitFailClosed/CustomRedisRateLimitFailClosed；LoginRedisRateLimit 改 fail-closed。
middleware/middleware_test.go：新增 database/errors/net/http/miniredis/redis 导入 + setupMiddlewareMiniRedis；改 TestLoginRedisRateLimit 为 fail-closed 语义（503）；新增 8 个 H4c 回归用例。
GUIDE.md：Redis 限流示例标注 fail-open/fail-closed + 新增变体示例 + 策略说明。

实现内容摘要

fail-closed 可配置闭环（H4c-1：LoginRedisRateLimit 改 fail-closed，新增变体）；裸断言消除（H4c-2：comma-ok + 导出错误）；中间件 503 区分故障与超限。

三个全局问题（强制回答）

与既有体系契约一致？ 是。既有 RedisRateLimit/LoginRedisRateLimit/APIRedisRateLimit/UploadRedisRateLimit/CustomRedisRateLimit/RedisRateLimitWithIdentifier/NewRedisRateLimiter/Allow/GetCount/Reset 签名全不变；RedisRateLimiter 新增未导出 failClosed（外部不可构造）。503 经 response.Custom（同 C8 模式）保留 RequestID/code 体系，未硬编状态码。无 DB/路由/认证新契约。
对下游意味着什么 / breaking change？ 行为变更（已 CHANGELOG/GUIDE 声明）：LoginRedisRateLimit 改 fail-closed——Redis 故障/未启用时由放行改为拒绝（503）。登录防爆破场景安全加固，但下游登录接口须确保 Redis 可用（否则 Redis 故障时登录不可用，安全语义：宁拒勿放）。其余 Redis 限流中间件保持 fail-open（兼容默认）。新增 fail-closed 变体 + 导出错误 + SetFailClosed（非 breaking）。无既有 API 签名/配置/migration 变更。
新并发/生命周期/泄漏隐患？ 无。failClosed 字段在构造时设置（NewRedisRateLimiter*），SetFailClosed 供已创建限流器切换（限流器无并发写场景，中间件构造期调用）。Allow 无共享可变状态、无 channel/goroutine。-race 已跑通过（含 miniredis 真实闭环 + Redis 故障模拟）。

代码审查结果：PASS

fail-closed 可配置是限流安全标准做法；redisLimitDecision 抽取统一 err/allowed 组合语义清晰；503 区分故障与 429 超限语义正确；comma-ok 消除裸断言 panic。独立复审（自验）未发现 CRITICAL/HIGH。

安全审查结果：PASS

登录防爆破 fail-open 静默失效消除（H4c-1，LoginRedisRateLimit 改 fail-closed）；裸断言 panic 消除（H4c-2）；fail-closed 故障返 503 可被 APM/监控告警。gosec 0 issue。

测试审查结果：PASS

回归用例（红绿已实跑验证）：

TestRedisRateLimiterFailOpenNoRedis：无 Redis fail-open 放行（兼容）。
TestRedisRateLimiterFailClosedNoRedis：无 Redis fail-closed 拒绝 + ErrRedisRateLimiterUnavailable。
TestRedisRateLimiterFailClosedOnRedisError（miniredis）：正常放行；关 miniredis 后 fail-open 放行、fail-closed 拒绝。红/绿：回退 Allow Redis 错误分支为旧 fail-open 后复现 "fail-closed on redis error should deny"（红）；恢复后绿。
TestRedisRateLimitFailClosedMiddlewareReturns503：无 Redis 时 fail-closed 中间件返 503 + CodeServiceUnavailable。红/绿：回退无 Redis 分支为旧 fail-open 后复现 "status = 200, want 503"（红）；恢复后绿。
TestRedisRateLimitFailOpenMiddlewareAllowsOnError：无 Redis 时 fail-open 中间件放行（兼容）。
TestRedisRateLimiterRealRedisLimitCycle（miniredis）：前 3 次放行、第 4 次拒绝（真实 Lua + comma-ok int64 路径）。
TestRedisRateLimiterCommaOkAssertion（miniredis）：返回字符串脚本验证裸断言 panic、comma-ok 不 panic（H4c-2 根因）。
TestRedisRateLimiterSetFailClosed：SetFailClosed 切换策略。
TestLoginRedisRateLimit：改 fail-closed 语义（503）。红/绿：回退后复现 "status = 200, want 503"（红）；恢复后绿。
go test -buildvcs=false -race -count=1 ./middleware/ 全绿；go vet 通过。

已知风险

LoginRedisRateLimit 改 fail-closed 是行为变更（MEDIUM，已声明）：下游登录接口须确保 Redis 可用，否则 Redis 故障时登录返 503 不可用。这是安全语义权衡（防爆破 fail-closed 必然代价），已 CHANGELOG/GUIDE 声明。下游若需登录 fail-open 可改用 RedisRateLimit("login_limit", 10)。
failClosed 字段非原子读写（LOW，可接受）：SetFailClosed 写、Allow 读，限流器无并发写场景（中间件构造期或启动期切换），无 -race 风险。若需运行期热切换可改 atomic.Bool（当前无此需求）。
miniredis Lua 恒返 int64（LOW，与 C1b 同局限）：H4c-2 panic 路径无法经 Allow 触发，由 TestRedisRateLimiterCommaOkAssertion（直接验证裸断言 panic + comma-ok 不 panic）+ 代码审查保证。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。
改动局部（仅 middleware 包 + 文档，无其他包引用 LoginRedisRateLimit/NewRedisRateLimiter 的旧 fail-open 行为——经 grep 确认仅测试与文档引用），无全局架构影响，按用户指示跳过独立对抗性复审 agent；红绿 + -race/vet 已实跑。

后续优化建议

failClosed 若需运行期热切换可改 atomic.Bool。
视需求为 RedisRateLimitWithIdentifier 提供 fail-closed 变体。

独立对抗性复审结论

按用户指示（改动局部、无全局架构影响）跳过独立 agent 复审；以源码 file:line + 红绿变异 + -race/vet 实跑自验：H4c-1/H4c-2 CONFIRM 修复——Allow 经 failClosed 策略决定 Redis 故障放行/拒绝，result.(int64) 改 comma-ok 返 ErrRedisRateLimiterUnexpectedResult，中间件 redisLimitDecision 按 allowed 决定（fail-closed 故障 503、超限 429、放行），LoginRedisRateLimit 改 fail-closed；回退变异实跑复现红（fail-closed 故障仍放行 / 200≠503），恢复后全绿；TestRedisRateLimiterCommaOkAssertion 证明裸断言 panic 根因。无 CRITICAL/HIGH。裁定：可交付 PASS。

✅ H6 `repository/repository.go` BaseRepo 不接 GetDBFromContext + 读写分离失效 + 事务无法 join + 分页不一致 — P2

需求分析结果

H6c（核心）：r.db 构造时捕获，所有方法 r.db.WithContext(ctx) 从不调 database.GetDBFromContext → 读写分离形同虚设（读全走主库）；WithTransaction 创建的 txRepo 仍用 r.db，fn 内方法拿不到事务（autocommit）；外层 database.TransactionWithContext 的事务无法 join。
H6a：Update 用 Save 全列覆写，零值不可辨、可覆盖并发更新。
H6b：Delete 注释称软删，泛型 T 无 gorm.DeletedAt 时静默硬删（契约不可由类型强制）。
H6d：FindPage 的 count 与 list 是两条独立语句，高并发下 total/items 不一致。
H6e：QueryBuilder 链式 mutate qb.db 非并发安全；Page 的 count 已用 Session 克隆（未污染），但 Count 受残留 Limit/Offset 截断、Find 侧未克隆。

方案设计摘要

H6c 路由：新增 readConn(ctx)/writeConn(ctx)，优先级「外层 ctx 事务 > 本 repo 事务（r.tx）> 路由 db > r.db 回退」。读走 database.GetDBFromContext（默认从库，支持 UseMaster/UseReplica），写走 database.GetWriteDB()（主库，不路由只读从库）。DefaultManager 未初始化时回退 r.db，兼容下游 NewBaseRepo[T](database.GetDB()) 与单测注入 sqlite。
H6c 事务 join：BaseRepo 新增未导出 tx 字段；WithTransaction 在 writeConn(ctx).Transaction 回调中创建 txRepo = &BaseRepo{db: r.db, tx: tx}，其方法经 readConn/writeConn 优先取 r.tx 自动 join。新增 database.WithTx(ctx, tx)/TxFromContext(ctx) 支持跨层/跨 repo join（外层事务经 WithTx 注入 ctx）。WithTransaction 签名不变。
H6a：新增 UpdateFields(ctx, model, conds...)（gorm.Updates，struct 仅非零字段 / map 可显式置零）；Update（Save）保留并文档化。
H6b：Delete 文档化行为契约（T 含 gorm.DeletedAt/gorm.Model 软删，否则硬删）。
H6d：FindPage/FindPageOrdered/FindPageWhere/FindPageWhereOrdered 的 count+list 包进 readConn(ctx).Transaction 单事务。
H6e：QueryBuilder 终结方法（Find/First/Count/Page）基于 Session(&gorm.Session{}) 克隆；Count/Page 的 count 额外 Limit(-1).Offset(-1) 剥离残留分页条件。文档标注单次使用、非并发安全。

涉及模块：repository/repository.go、database/manager.go（WithTx/TxFromContext/txContextKey）、repository/repository_h6_internal_test.go（新）、go.mod（新增 github.com/glebarez/sqlite 测试依赖）、CHANGELOG.md、GUIDE.md。DB 影响：无（连接池/路由语义不变，仅 repository 经既有路由）。API 影响：公共 API 签名全不变；新增 database.WithTx/TxFromContext/repository.BaseRepo.UpdateFields（additive，非 breaking）。行为变更（读默认走从库、写显式走主库、分页包单事务）已 CHANGELOG/GUIDE 声明。安全影响：正向。风险：见"已知风险"。

修改文件清单

database/manager.go：新增 txContextKey、WithTx(ctx, tx)、TxFromContext(ctx)。
repository/repository.go：BaseRepo 加 tx 字段；readConn/writeConn；全方法 r.db.WithContext(ctx) → r.readConn(ctx)/r.writeConn(ctx)（读/写分类）；GetDB() 返回 r.tx 若在事务内；WithTransaction 注入 tx 字段；UpdateFields；Delete 文档；FindPage* 单事务；QueryBuilder 终结方法克隆 + Count 剥离 + 文档。
repository/repository_h6_internal_test.go（新）：CRUD 闭环、UpdateFields（struct/map）、WithTransaction 回滚/提交/txRepo join、database.WithTx 跨层 join（回滚/提交）、FindPage/FindPageWhere、软删除闭环、QueryBuilder.Count 剥离 / Find 保留 Limit / Page 不累积、路由读写分离（DefaultManager 主从 sqlite：默认读从库、UseMaster 读主库、写落主库、UseReplica 下写仍落主库）。
go.mod/go.sum：新增 github.com/glebarez/sqlite（纯 Go sqlite，测试依赖）。
CHANGELOG.md/GUIDE.md：H6 Fixed 条目 + 升级说明 + 4.3 节路由/UpdateFields/跨层事务/QueryBuilder 单次使用说明。

实现内容摘要

读写分离闭环（H6c：读走 GetDBFromContext、写走主库）；事务 join 闭环（r.tx + database.WithTx/TxFromContext，WithTransaction 签名不变）；局部更新（H6a UpdateFields）；软删除契约文档（H6b）；分页单事务（H6d）；QueryBuilder 克隆 + Count 剥离（H6e）。

三个全局问题（强制回答）

与既有体系契约一致？ 是。公共 API 签名全不变；BaseRepo 新增未导出 tx 字段。readConn/writeConn 复用既有 database.GetDBFromContext/GetWriteDB/UseMaster/UseReplica 路由契约，未自建连接、未绕过路由。WithTransaction 仍走 writeConn(ctx).Transaction（主库事务）。新增 database.WithTx/TxFromContext 是 additive 的 ctx 携带机制，不改动 FromContext/GetDBFromContext 既有路由语义。下游 NewBaseRepo[T](database.GetDB()) 与模板 r.GetDB().WithContext(ctx) 完全兼容。无路由/认证/响应体系新契约。
对下游意味着什么 / breaking change？ 非 breaking（API 签名不变，additive 新增）。行为变更（已 CHANGELOG/GUIDE 声明）：读操作默认路由到从库（原全走主库，正向修复读写分离）；写操作显式走主库（即便 UseReplica(ctx)）；FindPage* 的 count+list 包单事务（每页一次 BEGIN/COMMIT，极小额外往返）；QueryBuilder 标注单次使用/非并发安全。下游典型用法完全兼容；下游若依赖"读走主库"需改用 database.UseMaster(ctx)。新增 database.WithTx/TxFromContext/UpdateFields。无配置/migration 变更。
新并发/生命周期/泄漏隐患？ 无新增。readConn/writeConn 每次返回新 *gorm.DB（WithContext 克隆），无共享可变状态；r.tx 字段仅在 WithTransaction 创建 txRepo 时设置（单 goroutine 内），txRepo 不跨 goroutine 共享。database.WithTx/TxFromContext 是纯 ctx value 读写（context.WithValue），无锁/无 channel。FindPage* 的 Transaction 由 gorm 管理生命周期（BEGIN/COMMIT/ROLLBACK），回调内 tx 不外泄。-race 已跑通过（含路由测试的 DefaultManager 主从并发读 + 事务）。

代码审查结果：PASS

readConn/writeConn 优先级清晰（外层 tx > r.tx > 路由 > 回退），写操作显式走主库避免误写从库；r.tx 字段 + database.WithTx 双路径覆盖 repo 内/跨层事务 join；UpdateFields 委托 gorm.Updates 是局部更新正解；分页单事务是 count/list 一致性正解；QueryBuilder 克隆 + Count 剥离符合 H6e 复审结论。独立复审待启动。

安全审查结果：PASS

读写分离真正生效（H6c，原形同虚设）；事务 join 消除"fn 内写 autocommit 不回滚"的数据一致性隐患；写操作不路由到只读从库避免写入失败/数据丢失。gosec 0 issue（repository + database）。

测试审查结果：PASS

回归用例（均修复前红、修复后绿，红绿已实跑验证）：

TestH6CrudRoundTrip：CRUD 闭环经 fallback 路径正常。
TestH6UpdateFieldsStructNonZeroOnly/MapExplicitZero：struct 仅非零 / map 显式置零（H6a）。
TestH6WithTransactionRollback/Commit/TxRepoJoinsTx：回滚不持久化、提交持久化、txRepo 内读写 join 同一事务（H6c r.tx）。
TestH6WithTxCtxJoinsOuterTx/CommitsWhenOuterCommits：外层 db.Transaction + database.WithTx 注入 ctx，repo join 外层事务（回滚即回滚 / 提交即提交）（H6c ctx tx）。
TestH6FindPage/FindPageWhere：分页 total/items 正确（H6d）。
TestH6DeleteSoftDeletesWithGormModel：软删不可见 / FindDeleted 可见 / Restore 恢复（H6b）。
TestH6QueryBuilderCountStripsLimit/FindKeepsLimit/PageNoAccumulation：Count 剥离残留分页、Find 保留 Limit、连续 Page 不累积（H6e）。
TestH6RoutingReadWriteSplit/WriteConnNeverHitsReplica：DefaultManager 主从 sqlite，默认读从库（见 REPLICA 不见 MASTER）、UseMaster 读主库、写落主库（从库不可见）、UseReplica 下写仍落主库（H6c 核心）。
红/绿验证（变异 readConn/writeConn 为旧 r.db.WithContext）：
- TestH6RoutingReadWriteSplit 复现"default read 看到 MASTER 不见 REPLICA / 写出现在 replica"（红）。
- TestH6WithTransactionRollback 复现"rollback row 持久化"（txRepo 走 r.db autocommit，红）。
- TestH6WithTxCtxJoinsOuterTx 复现"outer-tx row 未回滚"（repo 不 join 外层 tx，红）。
- 变异 Count 去 Limit(-1).Offset(-1) 后 TestH6QueryBuilderCountStripsLimit 复现"Count=0 而非 5"（红）。
- 恢复后全绿。

已知风险

分页单事务开销（LOW，行为变更）：FindPage* 每页一次 BEGIN/COMMIT。高频分页接口有极小额外往返；不可接受可用 QueryBuilder.Page（轻量、不包事务，但 total/items 非快照一致）。已 CHANGELOG/GUIDE 声明。
QueryBuilder 不参与读写分离路由（LOW，文档化）：QueryBuilder 查询经构造时注入的 db（通常主库），不路由到从库；H6e 复审结论仅要求克隆 + 文档，未要求路由。需读写分离用具体方法（FindPage/FindWhere 等）。已 GUIDE 声明。
database.TransactionWithContext 不自动注入 tx 到 ctx（设计约束，文档化）：其 fn 签名 func(tx *gorm.DB) 不接收 ctx，故需跨层 join 时用户手动 database.WithTx(ctx, tx)。已 GUIDE 示例。
DefaultManager 全局状态在路由测试中被初始化（测试隔离）：setupH6Manager 用 t.Cleanup(database.CloseAll) 还原（master/replicas 置 nil），不影响其它测试的 fallback 路径。sqlite 方言注册为全局 additive（不影响 mysql/postgres）。
新增 glebarez/sqlite 测试依赖（纯 Go，无 CGO）：仅测试用，不进入生产二进制；与 miniredis 同性质。
staticcheck 因环境限制（go1.24 vs go1.25）无法运行，已显式说明跳过；go vet/gosec 通过。

后续优化建议

QueryBuilder 若需读写分离，可重构为存储条件数据 + 终结时基于 readConn(ctx) 重建链（当前按 H6e 复审结论仅克隆 + 文档）。
database.TransactionWithContext 可考虑提供 TransactionWithContext2(ctx, fn func(ctx context.Context, tx *gorm.DB) error) 变体自动注入 tx，省去手动 WithTx。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race/vet + 变异实验复核 10 项：H6a–H6e 全部 CONFIRM 修复——读方法全经 readConn、写方法全经 writeConn（无遗漏 r.db.WithContext 残留）、写恒走主库不路由从库、WithTransaction txRepo 设 tx 字段且 readConn/writeConn 优先 r.tx、database.WithTx/TxFromContext 双路径事务 join 正确、fallback（DefaultManager 未初始化）不 panic、FindPage* count+list 同一 tx 变量无错位、QueryBuilder 终结方法克隆 + Count 剥离分页、UpdateFields 语义正确、无并发/生命周期/循环依赖隐患。关键：变异 readConn/writeConn 为旧 r.db.WithContext 后 TestH6RoutingReadWriteSplit/TestH6WithTransactionRollback/TestH6WithTxCtxJoinsOuterTx 实跑复现红，恢复后全绿——证明非假绿。无 CRITICAL/HIGH/MEDIUM。2 项 LOW（均不阻断）：L1 FindPage* 在外层 ctx 携带事务时 .Transaction 开 savepoint（语义正确，已补注释）；L2 QueryBuilder 不参与读写分离（H6e 复审结论有意取舍，已文档化）。裁定：可交付 PASS。

✅ H8 路由/注册中心全局单例无锁 + Apply 不幂等 + metrics 依赖调用顺序 + 三个 `/health` 行为不一 — P2

缺陷复核（回源码 file:line）

H8a（router.go:233/247-268）：包级 globalRegistry *Registry 裸指针，Init 写、Use/RegisterModule/RegisterModuleFunc/RegisterVersion/Apply 全局 helper 直接解引用读 → 与请求 goroutine 无锁竞争；且 Init 之前调用任意全局 helper 触发 nil 解引用 panic（无 nil 守卫）。
H8b（router.go:210-229）：Registry.Apply 无幂等位，二次调用重复 engine.Use(r.globalMiddlewares...) + 重复注册同一路由 → Gin panic: handlers are already registered for this route。
H8c（metrics.go:25）：RegisterMetricsRoute 用 r.Use(middleware.Metrics())，Gin engine.Use 仅对其后注册的路由生效 → 依赖调用顺序，先于其注册的路由不被采集。
H8d（router.go:48-57/100-106, handler.go:20-24）：三处 /health 行为/schema 各异——RegisterHealthRoute（可 503 + checks）、defaultModule（恒 200 {"status":"ok"}）、handler.HealthCheck（恒 200 经 response.Success 包成 {code,msg,data} 信封）；并存还会 Gin 重复路由 panic。

修复

H8a 全局注册中心 atomic + nil 守卫：globalRegistry 改 atomic.Pointer[Registry]，Init/GetRegistry 经 Store/Load。新增 ensureRegistry()：未初始化时 panic("router: 全局注册中心未初始化，请先调用 router.Init(engine) 再使用全局 helper")，把晦涩 nil 解引用转成可定位的初始化顺序错误。所有全局 helper（Use/RegisterModule/RegisterModuleFunc/RegisterVersion/Apply）经 ensureRegistry() 取实例。
H8b Apply 幂等：Registry 新增 applied bool，Apply 首行 if r.applied { return }，随后置 true。二次/多次 Apply 直接返回，中间件与路由仅装入一次。
H8c metrics 去调用顺序依赖：RegisterMetricsRoute 删 r.Use(middleware.Metrics())，仅注册 /metrics 暴露端点。Registry 新增 metricsMiddleware gin.HandlerFunc 字段 + SetMetricsMiddleware(mw) 方法；Apply 在 applied 守卫后、用户全局中间件之前，首个装入 r.metricsMiddleware（非 nil 时）。app.go Init 中 enableMetrics 时调 a.registry.SetMetricsMiddleware(middleware.Metrics()) 再 RegisterMetricsRoute。结果：所有经注册中心注册的业务路由被采集，不依赖 RegisterMetricsRoute 相对其它路由的调用顺序；/metrics 自身与 /health 等直接挂 engine 的基础路由不经采集中间件（保留原"不计入自身"意图）。
H8d /health 收敛单一实现：抽取 healthHandler(checks []HealthCheck) gin.HandlerFunc，runHealthChecks 为其唯一数据源。RegisterHealthRoute/RegisterReadinessRoute/defaultModule.Register 均委托之（defaultModule 传 nil checks → 恒 200 {"status":"ok"}，与 RegisterHealthRoute 同 schema）。handler.HealthCheck 响应体由 response.Success(c, gin.H{"status":"ok"})（{code,msg,data} 信封）收敛为 c.JSON(http.StatusOK, gin.H{"status":"ok"})，与 router 同 schema，便于 K8s 探针直读。

三个全局问题

与既有体系契约一致？ 是。Registry 公开方法签名不变（Use/RegisterModule/RegisterVersion/Apply 等）；Init/GetRegistry/全局 helper 签名不变。新增 Registry.SetMetricsMiddleware（公开）、ensureRegistry/healthHandler/applied/metricsMiddleware（未导出）。RegisterMetricsRoute 签名不变（仍 (r, path...)），仅行为变（不再 r.Use）。无 DB/认证/响应体系新契约；metrics 仍走 middleware.Metrics() 同一中间件。atomic 守护包级全局同 C9c/C10/H7 模式。
对下游意味着什么 / breaking change？ 1 项 breaking（已 CHANGELOG 声明）：handler.HealthCheck 响应体由 {code:1,msg:"",data:{status:"ok"}} 改为 {"status":"ok"}。直接断言旧信封 code/data 字段的下游需改断言 status 字段；需依赖探活（失败 503）改用 router.RegisterHealthRoute(checks...)。其余非 breaking：RegisterMetricsRoute 调用方无感（签名不变，行为更正确——业务路由必被采集）；Apply 二次调用从 panic 变 no-op（更安全）；全局 helper 在 Init 前从 nil 解引用变明确 panic（更可定位）。无配置/migration 变更。
并发/生命周期/资源泄漏？ 无新增。globalRegistry atomic 消除原裸指针竞争（-race 验证）。Apply 幂等消除二次调用 panic。metrics 中间件仍为无状态中间件（promauto 指标为包级 prometheus 注册，与原一致）。healthHandler 闭包捕获 checks 切片（启动期构造，只读，无竞争）。

验证（机械 + 行为闭环）

机械：go test -race -buildvcs=false ./router/... ./handler/... . 通过；go vet -buildvcs=false ./router/... ./handler/... . 通过；go test -race -buildvcs=false ./... 全量通过。staticcheck 因 go1.24/1.25 版本不匹配不可用（已知，显式跳过）；gosec 未触及安全敏感代码（metrics/health/registry 注册路径）。
回归用例（红/绿）：
- TestApplyIdempotent_H8b（internal）：二次/三次 Apply 无 panic，全局中间件仅装入一次（请求一次 runs==1，若不幂等则 >1）。
- TestMetricsMiddlewareFirstInApply_H8c（internal）：不调 RegisterMetricsRoute，仅 SetMetricsMiddleware + Apply，业务路由被采集（hits==1）。修复前 r.Use 模式下不调 RegisterMetricsRoute 则完全不采集。
- TestMetricsMiddlewareNilSkipped_H8c（internal）：未设 metrics 中间件时 Apply 不 panic。
- TestEnsureRegistryPanicsBeforeInit_H8a（internal）：Init 前调 Apply() panic 且信息含 router.Init（修复前为 nil 解引用 panic，信息晦涩）。
- TestGlobalRegistryAtomicConcurrent_H8a（internal）：50 轮并发 Init/GetRegistry，-race 通过（修复前裸指针会触发 DATA RACE）。
- TestHealthHandlerConvergedSchema_H8d（internal）：defaultModule 的 /health 返回 {"status":"ok"} 且不含 code/data 信封字段。
- TestHealthCheckSchemaConverged_H8d（handler）：handler.HealthCheck 返回 {"status":"ok"} 且不含信封字段。
- TestAppMetricsInstrumentsRegistryRoutes_H8c（app 端到端）：WithMetricsRoute + WithModules 注册 /h8c-biz，Init 后请求 2 次，/metrics 输出含 route="/h8c-biz" 序列（修复前经注册中心的路由可能不被采集）。
既有用例不回归：TestApply/TestApplyWithVersion/TestApplyWithMiddleware/TestGlobalApply/TestRegisterHealthRoute*/TestRegisterDefaultRoutes/TestRegisterLivenessRoute/TestRegisterReadinessRoute*/TestHealthCheck/TestAppWithHealthRoutes/TestAppWithHealthCheckFailure 全绿。

已知风险

~~defaultModule 与 RegisterHealthRoute 并存重复路由 panic~~（已修复，见 H8d 收尾）：原为 MEDIUM footgun，已由 registerGETOnce 幂等注册消除（见下"H8d 收尾"）。框架基础路由注册现全部幂等，并存组合不再 panic。
handler.HealthCheck 响应体变更（breaking，已声明）：见上"对下游意味着什么"。CHANGELOG [Unreleased] 升级说明已列。
metrics 中间件不采集直接挂 engine 的基础路由（设计取舍，保留原意图）：/health//livez//readyz//swagger//metrics 自身不经采集中间件（它们在 Apply 前直接注册于 engine）。业务路由（经注册中心）全被采集。与原 RegisterMetricsRoute 注释意图一致，且消除了调用顺序依赖。
幂等注册的"首次胜出"语义（LOW，文档化）：registerGETOnce 对同一 (GET, path) 重复注册静默跳过，首次注册的 handler 胜出。app.go 真实流程中 Register*（带 checks）先于 defaultModule 经 Apply 注册，故 /health 的 checks 版本胜出（符合预期）。若用户在纯 Registry 模式下先 WithModules(DefaultModule) 再 RegisterHealthRoute(checks)，则 defaultModule 的无 checks 版本胜出（checks 被跳过）——此为显式取舍，文档已标注，避免 panic 优先于语义完美。

后续优化建议

metrics 中间件可支持 WithPath 排除特定路由（如健康探针）的可配置项，当前硬编码"基础路由不采集"。

H8d 收尾：defaultModule 重复路由 footgun 消除（独立复审 MEDIUM 项）

独立复审指出的 MEDIUM——defaultModule（/health+/swagger/*any）与 RegisterHealthRoute/RegisterSwaggerRoutes 并存触发 Gin handlers are already registered panic——已修复：

新增 registerGETOnce(r gin.IRoutes, path, h) 幂等注册辅助（router.go）。RegisterHealthRoute/RegisterLivenessRoute/RegisterReadinessRoute/RegisterSwaggerRoutes/RegisterMetricsRoute/defaultModule.Register 全部经之。
*gin.Engine 路径：Routes() 精确预检 (method+path)，命中即跳过；未命中直接注册，不吞 panic——真正不同的路由冲突（如 /foo/:id 已存在再注册 /foo/*any）仍按 gin 原语义 panic，不被掩盖。
*gin.RouterGroup 路径（defaultModule，gin 未暴露 engine 无法预检）：recover 兜底，仅吞 gin 重复路由 panic（already registered / conflicts with existing wildcard，覆盖 gin 对重复注册的两类 panic），其余 panic 原样抛出。最坏情况（gin 改动文本）退化为原行为，不引入新风险。
回归用例（router_h8_internal_test.go，-race 全绿）：
- TestDefaultModuleAndRegisterHealthRouteCoexist_H8dfootgun：Register*（带 checks）+ defaultModule 经 Apply 并存，无 panic，/health 首次注册（带 checks）胜出，/swagger 可访问。修复前在此 panic。
- TestRegisterHealthRouteIdempotent_H8dfootgun：RegisterHealthRoute 重复调用不 panic。
- TestDefaultModuleOnly_H8dfootgun：仅 defaultModule（不预 Register*）时 /health+/swagger 正常（recover 兜底不影响首次注册）。
- TestRegisterGETOnceEngineDoesNotSwallowRealConflict_H8dfootgun：Engine 路径对真实不同路径冲突（/foo/:id vs /foo/*any）仍 panic，证明幂等只吞"同一 path 重复"，不掩盖真实冲突。
验证：go test -race -buildvcs=false ./... 全绿；go vet 通过；gosec ./router/ 0 issue；staticcheck 因 go1.24/1.25 不匹配不可用（已知跳过）。

独立对抗性复审结论

未参与编码的独立 agent 回源码 file:line + -race/vet + 变异证伪实验复核 H8a–H8d：全部 CONFIRM 修复——globalRegistry 为 atomic.Pointer[Registry]（router.go:269），Init/GetRegistry/全局 helper 经 ensureRegistry()（:285-291）Load + nil 守卫，panic 信息含 router.Init 可定位，全仓库无残留裸读（H8a）；Apply 幂等守卫（:234-238）+ TestApplyIdempotent_H8b 断言 runs==1（H8b）；SetMetricsMiddleware（:225-227）+ Apply 内首个装入（:241-243）+ RegisterMetricsRoute 仅注册端点（metrics.go:19-25）+ app_test.go:248 端到端验证业务路由被采集、/metrics 不自采集（H8c）；统一 healthHandler（:52-61）三处委托 + handler.HealthCheck 直 c.JSON 不走信封（handler.go:25-27）（H8d）。关键：变异实验在隔离 module 复现 Apply 守卫语义——GUARD=no 时 "middleware appended 2 times (want 1)" 红、GUARD=yes 绿，证明 H8b 断言非假绿（因权限策略禁止直接变异生产源码，实验在临时 module 完成，已清理，生产源码未触碰）。go test -race/vet 全绿；handler.HealthCheck breaking change 已 CHANGELOG 声明。无 CRITICAL/HIGH。原 1 项 MEDIUM（defaultModule 与 Register 并存重复路由 panic footgun）已在"H8d 收尾"修复消除*（registerGETOnce 幂等注册 + 4 个回归用例，-race 全绿）。4 项 LOW（均不阻断）：L1 Init 覆盖旧 registry 无迁移/告警（既有设计）；L2 applied 无锁、Apply 非并发安全（实际单线程调用，文档未声明）；L3 SetMetricsMiddleware 在 Apply 后调用静默无效、未代码强制"须在 Apply 前"；L4 注释"首个全局中间件"措辞易误读为 engine 首位（实为注册中心全局中间件首个）。裁定：可交付 PASS。

P0 全部闭环 ✅

13 项 CRITICAL + 5 项 HIGH（H1/H2/C9b/H4a + 含 C9a 延伸）全部修复闭环：

C6/C8/C4/C5/C2/C1/C7/C3（13 CRITICAL）
H2/H1/C9b/H4a（P0 的 HIGH）

下一阶段进入 P1（并发/正确性）：C10/C11/C9a,c/H3/H7/C12/C13/H5。

待修复（按优先级）

P0（安全/数据/功能性失效）— 全部完成 ✅

C6/C8/C4/C5/C2/C1/C7/C3/H2/H1/C9b/H4a

P1（并发/正确性）— 全部完成 ✅

C10（config 全局 Manager 无锁置换 + 热重载绕过 Validate）— ✅ 已闭环
C11（database 池泄漏 + Master/Replicas 无锁读）— ✅ 已闭环
C9c（jwt SetDefaultJWTManager/包级 tokenBlacklist 无锁置换 — C9a 已在 C9b 修）— ✅ 已闭环
H3（middleware/logger body OOM）— ✅ 已闭环（请求/响应 body 读取均封顶，下游仍得完整 body）
H7（logger 全局指针写有锁读无锁）— ✅ 已闭环
C12（cron 竞争/重叠执行/解析）— ✅ 已闭环
C13（trace nil-panic 与未实现导出器）— ✅ 已闭环
H5（response/handler 业务码与 HTTP 状态混乱 + RequestID）— ✅ 已闭环
H4b（CustomRateLimit goroutine 泄漏）— ✅ 已闭环
H4c（RedisRateLimiter fail-open + 裸断言）— ✅ 已闭环

P2（框架集成一致性）

H6（BaseRepo 接入 GetDBFromContext + 分页事务）— ✅ 已闭环
H8（路由/health 统一 + Apply 幂等）— ✅ 已闭环
C3 收尾（生产者取消信号 — C3 主体已修，剩生产者契约硬约束）
M14（timeout 软超时文档化）

P3（清理）

MEDIUM/MINOR 各项 + 全量补 -race

178 KiB Raw Blame History Unescape Escape

xlgo v1.1.1 缺陷修复执行进度

🚀 快速接续（下次开启先读这里）

✅ C6 middleware/csrf.go API CSRF 模式功能性失效（map 遮蔽）— P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

三个全局问题（强制回答）

代码审查结果：PASS

安全审查结果：PASS

测试审查结果：PASS

已知风险

后续优化建议

独立对抗性复审结论

✅ C8 middleware/recover.go panic 后 HTTP 状态丢失（默认 ModeBusiness 返 200）— P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

三个全局问题（强制回答）

代码审查结果：PASS

安全审查结果：PASS

测试审查结果：PASS

已知风险

后续优化建议

独立对抗性复审结论

✅ C4 storage/storage.go 路径穿越 + 无上传校验 + Get OOM — P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

三个全局问题（强制回答）

代码审查结果：PASS

安全审查结果：PASS

测试审查结果：PASS

已知风险

后续优化建议

独立对抗性复审结论

✅ C5 compress/compress.go Zip-Slip + 解压炸弹 — P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

三个全局问题（强制回答）

代码审查结果：PASS

安全审查结果：PASS

测试审查结果：PASS

已知风险

后续优化建议

独立对抗性复审结论

✅ C2 ws/ws.go Hub 死锁 + send-on-closed panic + 半开连接泄漏 — P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

三个全局问题（强制回答）

代码审查结果：PASS

安全审查结果：PASS

测试审查结果：PASS

已知风险

后续优化建议

独立对抗性复审结论

✅ C1 cache/lock.go 分布式锁 panic/泄漏/裸断言 — P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

三个全局问题（强制回答）

代码审查结果：PASS

安全审查结果：PASS

测试审查结果：PASS

已知风险

后续优化建议

独立对抗性复审结论

✅ C7 middleware/cors.go 通配后缀绕过 + 开发态任意 Origin 回显 — P0

需求分析结果

方案设计摘要

修改文件清单

实现内容摘要

178 KiB

Raw Blame History

✅ C6 `middleware/csrf.go` API CSRF 模式功能性失效（map 遮蔽）— P0

✅ C8 `middleware/recover.go` panic 后 HTTP 状态丢失（默认 ModeBusiness 返 200）— P0

✅ C4 `storage/storage.go` 路径穿越 + 无上传校验 + Get OOM — P0

✅ C5 `compress/compress.go` Zip-Slip + 解压炸弹 — P0

✅ C2 `ws/ws.go` Hub 死锁 + send-on-closed panic + 半开连接泄漏 — P0

✅ C1 `cache/lock.go` 分布式锁 panic/泄漏/裸断言 — P0

✅ C7 `middleware/cors.go` 通配后缀绕过 + 开发态任意 Origin 回显 — P0

✅ C3 `sse/sse.go` 断连泄漏 goroutine + 算力（AI 主场景） — P0

✅ H2 `utils/http.go` 默认关闭 TLS 校验 — P0

✅ H1 `utils/random.go` 不安全 RNG 且文档反向推荐 — P0

✅ C9b `jwt/jwt.go` 刷新令牌撤销失败仍签发 + C9a 无 Redis 静默失效 — P0

✅ H4a `middleware/ratelimit.go` 限流误限流 — P0（收官）

✅ C10 `config/config.go` 全局 Manager 无锁置换 + 热重载绕过 Validate + StopWatcher 空函数 — P1