yvan
/
kra-new
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
kra-new/docs/code-review-issues.md

11 KiB
Raw Blame History

代码审查问题清单（internal + pkg）

  • 审查日期：2026-08-27 ~ 2026-08-28，共五轮全量审查。第五轮（2026-08-28）：核查第四至七轮全部处置声称（W/S/P/F/C/L/D 系列已修复与评估保留项）+ 全新视角回归审查；go build ./... 编译验证通过
  • 文档结构：只保留待修复问题，按类型归类（不按轮次）；每条标注发现轮次；已修复并经复查确认的、以及经评估决定保留的直接删除
  • gva/ 目录是遗留参考库（独立 module 不参与 kra 编译），不在审查范围
  • 依赖方向合规确认：pkg 无 import internal；integration 不 import data/service；data 不 import integration/payment；无循环依赖
  • 第五轮总评：核心业务路径（支付/调度/数据权限/上传）逻辑严谨、分层契约执行到位；历轮修复全部属实；当前债务已收敛为敏感数据落地防护不对称、文档漂移、中转微文件三类

一、安全与正确性缺陷（第五轮新发现，最优先）

# 问题 位置 说明
V-1 已清空 configs/config.yaml 中的 MySQL DSN、数据库密码和 JWT signing key；模板仅保留 KRA_* 环境变量覆盖说明。泄漏值仍存在于历史提交，需在部署侧轮换数据库密码与 JWT 密钥。 configs/config.yaml:9,13,91 已完成（2026-08-28）
V-2 已让操作审计 Response 复用 redactJSON，与访问日志保持同一脱敏和长度上限策略，避免 token/密钥字段明文入库。 server/middleware/audit.go；capture.go 已完成（2026-08-28；针对性测试通过）
V-3 已补齐 key、public_cert、signing_key、secret_key 等敏感键，并将 integration payment test 路由标记为 BodyPolicyPaymentConfig，请求体统一使用摘要策略。 server/middleware/redact.go；routecatalog/catalog.go 已完成（2026-08-28；针对性测试通过）
V-4 已在 config watcher 与 data reload 入口补充运行时契约说明：watch 只发布不可变快照，reloadSystem 才重建数据库/缓存/存储/集成客户端；保留双路径以维护回滚与连接退休安全。 internal/config/runtime.go；internal/data/config_store.go 已完成（2026-08-28）
V-5 已修正 ApplySync 失败文案为「同步失败」。 server/handler/api.go:195 已完成（2026-08-28）
V-6 已移除 audit handler 八处 err.Error() 拼接；客户端只收到稳定分类提示，内部错误仍由审计/日志链路保留。 server/handler/audit.go 已完成（2026-08-28）
V-7 已补齐秒传复制的 Size、MD5、Mime、UserID 字段，保持与完整上传记录一致。 biz/system/media_upload.go 已完成（2026-08-28）
V-8 CompleteUploadSession 失败时现在回退会话状态并返回错误，避免 media 已创建而 session 长期停留 merging；非关键分片清理仍保持 best-effort。 biz/system/media_upload.go 已完成（2026-08-28）
V-9 已逐项确认：用户重名检查排除软删记录是有意的重新注册语义；export 关系替换使用软删以保留审计历史；对软删记录更新匹配 0 行符合不可恢复约束；关联查询显式 deleted_at IS NULL 与 Model scope 叠加属于迁移期防御，并新增参数软删除更新回归测试。 data/system/* 评估完成，保留（2026-08-28）
V-10 已删除外部退款分支中 !accepted 的不可达兜底，统一返回已确认的 providerErr。 biz/payment/payment.go 已完成（2026-08-28）

二、死代码残留（第五轮新扫描）

死代码 位置 证据
PaymentOrderSourceRegistry.Len 已删除：全仓（含测试）零调用。 biz/payment/payment_order.go
PaymentFulfillmentRegistry.Len 已删除：全仓（含测试）零调用。 biz/payment/payment.go
NewConfiguredPaymentUsecase 恒 nil 错误透传壳 已删除并通过 Wire 重新生成，ProviderSet 直接绑定 NewPaymentUsecase。 biz/payment/provider.go；cmd/wire_gen.go
biz/integration mergeIntegrationDefaults 一行转发壳 已删除，调用点统一使用 MergeIntegrationDefaults。 biz/integration/integration_config.go
P-15 残留 已修正 handler/http.go 注释与 source.go 旧路径标记，并同步移除过时测试样本。 server/handler/http.go；internal/logging/source.go
convertAuthority 的 DeletedAt 值传递被 json:"-" 丢弃 已删除无效赋值，避免向已隐藏字段传递无效数据。 service/system/user_conversion.go

三、重复实现残留（历轮收敛后的漏网项）

# 问题 位置 轮次
D-2 遗漏 1-3 已统一 qq、wechat v3 与 payment data 的支付方式归一化到 paymentkit.NormalizePaymentMethod，消除点号/短横线/空格处理漂移。 integration/payment/qq.go；wechat_v3.go；data/payment/payment.go 已完成（2026-08-28；针对性测试通过）
D-31 已复用 paymentOrderFingerprint 完成 BeforeCreate 前后不可变校验，保留同等字段覆盖范围并删除 10 个 canonical 局部变量。 biz/payment/payment.go 已完成（2026-08-28；针对性测试通过）
D-32 已新增 BodyPolicyUpload 并让 AccessLog 按 routecatalog 决定上传请求体限额，删除硬编码 URL 后缀判断。 routecatalog/catalog.go；server/middleware/access_log.go 已完成（2026-08-28；针对性测试通过）

四、文档漂移（第五轮新发现，低成本高收益）

# 问题 位置
F-21 已将 CLAUDE.md 正文同步为 Gin+手写 DTO+make generate 的现行仓库约定，移除 proto/AIP/fieldmask 时代描述。 CLAUDE.md
F-22 已修正 pkg/README.md，移除不存在的 logging/httpx/paymentkit 公共包描述。 pkg/README.md
F-23 已修正 internal/README.md 与 internal/server/README.md 的 httpx 路径。 internal/README.md；internal/server/README.md
F-24 已将 integration README 的 paymentkit 路径改为 internal/paymentkit。 internal/integration/README.md
F-25 已修正 service README，根包仅聚合 Wire ProviderSet，不再声称 re-export 门面。 internal/service/README.md
F-26 已在 AGENTS.md 项目结构中补充 docs/。 AGENTS.md

五、过分拆分残留（微文件清单，行数实测）

文件 行数 说明
internal/modules/surface/surface.go 19 评估保留：隔离 routecatalog 到 pkg/module 的适配依赖。
internal/data/provider/provider.go 8 评估保留：Database seam 被多个 data 子包独立依赖。
internal/data/data_scope_record.go 9 评估保留：隔离 data 回调写模型与 system 查询模型。
internal/biz/task/task_registry.go 11 评估保留：biz 只暴露窄注册接口，避免 worker/pkg/task 类型穿透。
internal/service/dto/{email,authentication,permission,system_init}.go 7/8/12/13 评估保留：按 transport 契约分文件，合并只减少文件数。
internal/server/handler/{session,navigation,set,http}.go 25/26/26/31 评估保留：单方法 handler 与响应词汇表由 Wire/路由注入约束形成。
internal/server/router 8 个单域注册微文件 12-19 评估保留：领域路由注册边界清晰，统一合并会扩大单文件变更面。

注：Wire ProviderSet 微文件（约 10 个 ≤9 行）属 Wire 惯例不计债务；biz/system 微文件群、SystemConfigService、provider/providers 双文件等已在历轮合并完成。

审查后认为合理、不建议改动的部分（历轮评估保留决策汇总）

  • biz 注入面：RegisterBusinessModule/PaymentBusinessModule 是 docs/PAYMENT.md:121-129 明文声明的业务接入契约（模板无生产实现属预期）；PayInternal/RefundInternal/AuthorizeRefund 被 biz 调用链消费
  • F-2/F-4/F-6/F-7/F-9/F-10/F-11：result.go 自有协议语义非纯转发；handler/http.go 别名层；task 双 usecase 生命周期不同；initialize 三层是启动编排倒置链；system usecase 壳是 Wire 契约边界；security_session 剩余 6 方法跨三层消费；biz 接口嵌入是组合窄能力
  • S-5/S-6/S-7/S-8/S-9：payment 大文件承载跨供应商编排；dto 跨域文件移动放大契约变化；data 转换命名差异需全域迁移；media 四文件职责边界清晰；单方法 handler 由 Wire 注入约束
  • D-4/D-6/D-9/D-10/D-11/D-19：handler 样板各域差异明显；mq helper 属排除范围；config/runtimeconfig 分离已补决策注释；三处清理入口不同各自独立触发；树算法输入模型不同；金额守恒四处输入形态互异（完整结构体/配置化 JSON/XML 值映射/SDK 结构体）
  • L-5/L-10/L-12：错误审计白名单被测试锁定；Kratos errors 仅跨层/stdlib 管内部的双体系分层；binding 覆盖结构必填、手工覆盖上下文（覆盖不均但新代码倾向 binding，未恶化）
  • P-3/P-5/P-6/P-7/P-8/P-9/P-10/P-11/P-13：pkg 各包定位经复核成立；mq/websocket 属既定排除
  • X-1~X-4/X-6~X-8/X-10/X-11：路由双声明/集成配置双通道/热重载分工（watchLoop 发布快照 vs reloadConfig 重建基础设施，合并需重做锁与退休策略）等均完成影响分析保留
  • C-2/C-4/C-6/C-8：loadUser/loadUsers 查询策略不同；*Data nil 防御覆盖测试替身边界；媒体三重限制各守一层；PaymentLogger 是审计替换 seam
  • L-7 复核：data 层 Table() 已全 PO 化（仅 2 处导出动态表名合理保留）；saveRelations 只做 DO→PO 转换
  • 质量标杆（第五轮正面确认）：payment 幂等指纹+回调强制平台查单、退款 lease 语义、task_scheduler 锁序、task_executor SSRF 拨号防护+orphan 跟踪、auth singleflight（context.WithoutCancel 隔离取消传染）、data_scope 回调注入、email CRLF 清洗、ListTasks(0,0) 全量语义、新增缝（PaymentAdapterFactory/MergeRuntimeConfig/deletePrefixViaList/AST 缓存/systeminfo）均内聚无越界

处置建议（按优先级）

  1. 立即处理 V-1（泄漏的数据库密码）→ V-2/V-3（审计敏感数据落地防护对称化）
  2. V-4/V-9（热重载漂移文档化、软删语义逐项确认+补测试）
  3. V-5/V-6/V-7/V-8/V-10 + 二节死代码（小而具体的清理批次）
  4. 三节 D-2 三处遗漏 + D-31/D-32
  5. 四节文档漂移群（一次 README/CLAUDE.md 同步批）
  6. 五节微文件合并（最后）