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

25 KiB
Raw Blame History

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

  • 审查日期：2026-08-27 ~ 2026-08-28，共四轮全量审查。第四轮（2026-08-28）：核查第三至六轮处置声称是否真实落地 + 全量回归审查（重点：重构引入的新问题），go build ./... 编译验证通过
  • 文档结构：只保留待修复问题，按类型归类（不按轮次）；每条标注发现轮次；已修复并经复查确认的直接删除
  • gva/ 目录是遗留参考库（独立 module 不参与 kra 编译），不在审查范围
  • 依赖方向合规确认：pkg 无 import internal；integration 不 import data/service；data 不再 import integration/payment（第四轮重构后复验单向）；无循环依赖

一、正确性缺陷（第四轮回归审查新发现，最高优先级）

# 问题 位置 说明
W-1 payment 空注册表导致应用启动失败。 已修复：模板允许无业务模块启动，调用未配置能力时返回明确错误。 原位置 已完成
W-2 CompleteUpload 吞掉 ListChunks 底层错误。 已修复：底层错误与分片数量不足已拆分处理。 internal/biz/system/media_upload.go 已完成
W-3 MergeRuntimeConfig 嵌套子节合并缺口。 已修复并增加回归测试。 internal/config/clone.go；runtime_test.go 已完成
W-4 退款状态词表语义边角。 已修复并补充测试。 internal/paymentkit/status.go 已完成
W-5 公告/参数/版本列表无 ORDER BY。 已修复：统一按 id desc 排序。 data/system/*.go 已完成
W-6 外部退款分支存在不可达死分支。 已修复。 internal/biz/payment/payment.go 已完成

二、死代码与零消费者机制

2.1 三层死方法残留（第三至五轮处置后仍未删，均经全仓 Grep 反查确认零调用）【二轮发现，四轮复核仍在】

层 死代码 位置
biz 接口+data 实现 RecordDataAccess 写入链已删除；查询侧仍保留。 相关文件
service 包装 security_session.go 中 8 个无消费者透传方法已删除。 相关文件
biz 注入面 经复核保留：RegisterBusinessModule 与 PaymentBusinessModule 是 docs/PAYMENT.md 明确要求的业务接入契约；PayInternal/RefundInternal/AuthorizeRefund 已由 biz 调用链消费，模板无具体业务实现属于预期扩展点，不是死代码。评估完成，保留（2026-08-28）。 biz/payment/payment.go:400-412；payment_order.go:139-152
dto 死字段（已确认项） GetAuthorityButtonsRequest.Selected 已删除；其余字段因仍参与响应或兼容契约暂保留。 dto/permission.go
死分支 经复核保留：service 层接收通用 map[string]any，[]byte 仍是合法 usecase/fake 输入；该分支有针对性测试，不属于可证明死代码。评估完成，保留（2026-08-28）。 service/system/export_excel.go:85-86

2.2 mq / websocket 零消费者基础设施【既定排除范围，历轮明确不处理，现状保持】

  • mq 全链（声明式订阅+legacy API+簿记/dispatcher/reconcile）业务消费者为零；_ mq.Client 幻影参数（cmd/main.go:65）；integration/provider.go:33-38 三重死绑定 + Hub 死绑定
  • websocket：Hub 接口零消费者；integration 层 On* 四注册方法零调用，双层 handler 登记机制两层都为空
  • namedClient/Client() 整型死代码（integration/mq/emqx.go:632-650）

2.3 零散死代码（第四轮新扫描）【四轮】

死代码 位置 证据
config.CloneData 已删除：全仓零调用，且 Clone/MergeRuntimeConfig 已覆盖实际快照复制入口。已完成（2026-08-28）。 internal/config/clone.go
paymentkit.XMLValues/XMLEncode 已删除：仅测试调用；XML 编解码辅助已移入 payment 集成测试文件，生产 XML 继续走 gopay。已完成（2026-08-28）。 internal/paymentkit/xml.go
paymentkit.NestedString 已删除：生产零调用；旧测试已改为覆盖现存 JSONObject/StringAtPath。已完成（2026-08-28）。 internal/paymentkit/json.go
logging.NewZapLogger 已删除：唯一测试调用改用生产构造器 NewReloadableZapLogger，避免维护双入口。 internal/logging/zap.go；data/gorm_logger_test.go
data/payment.contains 已改用 paymentkit.ContainsFold，本地实现已删除。 data/payment/payment.go
paymentkit status.go 的 ConfiguredInt64/ConfiguredValues/Text/FirstText/FirstString 定位漂移 经复核保留：这些函数仍被 payment data/integration 生产路径消费，属于配置解析边界；问题是 README 描述过窄而非死代码。评估完成，保留（2026-08-28）。 internal/paymentkit/status.go:36-90

三、重复实现 / 双份维护

3.1 大块可消除

# 问题 位置 轮次
D-2（部分完成） 支付方式归一化骨架已统一到 paymentkit.NormalizePaymentMethod；各渠道状态词表与退款身份校验因语义不同保留。 integration/payment；internal/paymentkit 部分完成
D-4 经复核样板虽多，但各 handler 的绑定方式、错误文案、响应 envelope 和鉴权上下文差异明显；抽统一门面会隐藏 transport 语义并扩大回归面，暂不改动。 server/handler/* 评估完成，保留（2026-08-28）
D-6 经复核暂不改动：重复 helper 与 MQ/WebSocket 零消费者基础设施同属既定排除范围；上收 internal/utils 会扩大无消费者包的公共表面积。 emqx.go:226-260 vs websocket/server.go:189-240 评估完成，保留（2026-08-28）

3.2 配置/数据不变式双份维护

# 问题 位置 轮次
D-9 config.Store 与 runtimeconfig.Store 的同构 listener/通知/克隆机制经复核不合并：前者负责文件快照与 fsnotify 全量替换，后者负责数据库集成配置按 provider key 通知；已补决策注释固化边界。 config/runtime.go；integration/runtimeconfig/store.go 评估完成，保留分离（2026-08-28）
D-10 经复核保留三处清理：persistConfigValues 覆盖完整运行时保存，persistDatabaseConfig 覆盖初始化页的局部写入，removeIntegrationConfigFromFile 覆盖启动时对旧模板的兼容清理；入口不同且各自可独立触发，合并会削弱不落盘不变式。 internal/data/config_store.go；data.go 评估完成，保留（2026-08-28）

3.3 中小重复

# 问题 位置 轮次
D-11 经复核保留：authority 树与 menu 树输入模型、过滤规则和输出结构不同，共享算法会引入泛型/回调抽象而降低可读性。 biz authority.go vs menu.go 评估完成，保留（2026-08-28）
D-15 defaults 合并逻辑三层三份。 已修复：统一使用 integrationbiz.MergeIntegrationDefaults。 相关文件 已完成
D-17 剩余 values() 与 testRow() 已收敛为共享读取逻辑，并保留启用状态差异。 data/payment/payment.go 已完成
D-19（评估后保留） payment 金额守恒校验四处重复。 经复核保留：四处输入字段与供应商容错语义不同，强行合并会破坏分层；biz 最终守恒校验作为跨边界不变式。 biz/payment 与各供应商适配器 不改动
D-21 支付订单响应映射已统一复用 paymentOrderResponse。 service/payment/payment.go 已完成
D-22 同 2.3，已改用 paymentkit.ContainsFold。 data/payment/payment.go 已完成

四、过度分层：转发门面 / 透传壳 / 回调穿透

# 问题 位置 轮次
F-2 经复核保留：文件除 paymentkit 转发外还承载 callbackFields、firstNonEmpty 与 parseConfiguredAmount 等包内协议语义；高频短别名被 100+ 处渠道代码消费，整体展开只会放大改动而不减少规则源。 integration/payment/result.go 评估完成，保留（2026-08-28）
F-4 经复核保留：handler/http.go 只提供响应类型与函数别名，避免各 handler 重复导入 httpx，不承载业务规则。 server/handler/http.go 评估完成，保留（2026-08-28）
F-6 经复核保留：TaskUsecase 面向 worker 的 repo/校验能力，TaskApplicationUsecase 负责运行时同步与恢复；两者生命周期和依赖不同。 biz/task/task.go 评估完成，保留（2026-08-28）
F-7 经复核保留：InitializationRepo → initialize.Repo → data.Data 是启动编排的接口倒置链，避免 initialize 直接依赖 data 实现。 initialize/initialize.go 评估完成，保留（2026-08-28）
F-8 已删除 newReloadableDB 的匿名变参垫片；审计回调仍只在数据库激活/替换时由 registerDataScopeCallbacks 绑定，职责链闭环。 data/runtime_clients.go；data_scope.go 已完成（2026-08-28）
F-9 经复核保留：system usecase 透传壳是 biz 对外契约与 Wire 注入面的稳定边界，删除会把 service/worker 直接绑定到 repo。 biz/system/* 评估完成，保留（2026-08-28）
F-10 经复核保留剩余活跃方法：security session 负责 token/cache 语义，不能与 service handler 合并；已确认的 8 个无消费者方法按死代码处理。 service/system/security_session.go 评估完成，保留（2026-08-28）
F-11 经复核保留：biz 接口嵌入透传用于组合窄 repo 能力，调用方依赖稳定 usecase 契约，机械拆分会扩大 Wire 与测试替身改动。 biz/system/* 评估完成，保留（2026-08-28）
F-13 已删除 Adapter 类型别名和包级 New 双入口；Factory.New 直接实现 biz 的 PaymentAdapterFactory，工厂表使用 biz 接口类型。 integration/payment/adapter.go；vendor.go 已完成（2026-08-28）

五、过分拆分 / 文件组织

根因模式三条【三轮】：①零逻辑 usecase 壳（wire 强制每域一个构造器放大）；②"每资源 N 文件"机械切分；③为 import 美观引入的中间缝合包/门面。

# 问题 位置 轮次
S-1（第一批） 已合并 actor/data-scope 上下文载荷文件；复核剩余微文件均对应独立职责，不再机械归并。 internal/biz/system/context.go 部分完成（2026-08-28）
S-2 SystemConfigService 已合并为单文件。 internal/service/system/system.go 已完成
S-3（第一批） routes.go 已改为有序注册表；各领域路由文件承担独立注册边界，复核后保留。 internal/server/router/routes.go 部分完成（2026-08-28）
S-4 四个 data 子包的 provider 文件已合并。 internal/data/*/provider.go 已完成
S-5 经复核保留：payment 大文件承载跨供应商编排与契约，微文件分别对应独立边界；dto 合并会重新混装领域，收益不足。 biz/payment、service/dto 评估完成，保留（2026-08-28）
S-6 经复核保留：system.go/settings.go 虽跨域，但移动类型会放大 service DTO 导入与生成契约变化；本批不做机械拆分。 service/dto/system.go、settings.go 评估完成，保留（2026-08-28）
S-7 经复核保留：data 层转换与 PO 命名差异来自不同存储关系和历史兼容，统一命名需全域迁移，当前无安全局部收益。 data/system/* 评估完成，保留（2026-08-28）
S-8 经复核保留：media 四文件分别覆盖资源、元数据、上传会话与上传流程，职责边界清晰，不为减少文件合并。 biz/system/media* 评估完成，保留（2026-08-28）
S-9 经复核保留：单方法 handler 结构体由 Wire/路由注入约束形成，合并会改变构造与注册契约，暂不改动。 server/handler/session.go、navigation.go、set.go 评估完成，保留（2026-08-28）

六、包归属问题

# 问题 位置 轮次
P-3 经复核保留：pkg/module 是跨 internal/modules、routecatalog 和启动编排的基础契约，移动会反向扩大依赖面。 pkg/module 评估完成，保留（2026-08-28）
P-5 按 2.2 既定排除范围保留：MQ/WebSocket 零消费者基础设施暂无迁移收益。 pkg/mq、pkg/websocket 评估完成，保留（2026-08-28）
P-6 按 2.2 既定排除范围保留：重复 helper 只服务于零消费者适配器，上收 utils 会扩大公共 API。 integration/mq、integration/websocket 评估完成，保留（2026-08-28）
P-7 经复核保留：aws-sdk-v2 与 minio-go 分别覆盖 S3 兼容和 MinIO 专属能力，统一 SDK 会损失 provider 行为或引入迁移风险。 integration/storage 评估完成，保留（2026-08-28）
P-8 经复核保留：query/page/trace 解析函数依赖 Gin transport 类型；移入 pkg/utils 会把 HTTP 语义泄漏到通用包，收益不足。 server/handler/query.go 等 评估完成，保留（2026-08-28）
P-9 经复核保留：configuration.go 的 DTO 塑形、JSON 规范化和掩码共享同一初始化事务边界，拆分会增加中间状态与回滚路径。 initialize/configuration.go 评估完成，保留（2026-08-28）
P-10 经复核保留：pagination/gormkit 直接表达当前 GORM 存储契约，继续下沉不会减少依赖。 pkg/database 评估完成，保留（2026-08-28）
P-11 按 2.2 既定排除范围保留：pkg/mq 的 kra 前缀与项目级协议契约一致，暂无独立复用边界。 pkg/mq 评估完成，保留（2026-08-28）
P-13 经复核保留：pkg/module、pkg/task、pkg/database/migration 组成同层基础设施契约组，拆包只增加导入跳转。 pkg/* 评估完成，保留（2026-08-28）
P-14 已将 httpx 收敛为通用 SetCookie，x-token 命名保留在 handler/middleware 业务边界；密码修改冲突码移至 middleware，并由 handler 继续提供兼容常量。 internal/server/httpx/response.go；server/handler/http.go；server/middleware/auth.go 已完成（2026-08-28；针对性测试通过）
P-15 包移动注释与 logging 栈跳过标记已修正。 相关文件 已完成
P-16 已同步 CLAUDE.md 的目录结构与分层说明，移除不存在的 api/、internal/global/ 等描述。 CLAUDE.md 已完成（2026-08-28）

七、分层 / 职责违规

# 问题 位置 轮次
L-3（部分完成） PaymentResult/PaymentTestResult 的死 JSON 标签已移除；PaymentRequest 字段与指纹语义保留，Definition 家族因仍被 service 消费暂不迁移。 biz/payment/payment.go；biz/integration 部分完成
L-4 SystemParameter 的查询字段与时间区间已拆为 SystemParameterFilter；API/Export 过滤字段已分别迁移至独立 APIFilter、ExportTemplateFilter，实体 DO 不再承载列表过滤/排序字段。 biz/service/data system parameter、api、export 已完成（2026-08-28；针对性测试通过）
L-5 经复核保留：错误审计的中文消息白名单、业务路径例外和支付回调摘要已由现有测试固定为安全策略；支付回调/配置正文脱敏依赖 routecatalog body policy，抽成无业务中间件会削弱防泄漏边界。限流配置来自 SecurityService，未发现可安全下沉的独立策略对象。 server/middleware/* 评估完成，保留（2026-08-28）
L-6（部分完成） AuthenticationResult 已在返回 service 前清空密码哈希并补回归测试。 QueryExport 动态行、export DO 的兼容 SQL 字段、UserOptions 选项形状仍保留：前两项涉及公开导入导出契约与存量数据兼容，后者虽命名偏 UI，但实际是稳定的 label/value 投影；当前直接迁移收益不足以覆盖契约风险。 biz/system/* 部分完成（2026-08-28；针对性测试通过）
L-7 已将 system data 的静态表查询改为 PO Model(...)；动态导出表仍按已校验模板访问。复核确认 saveRelations 只做 DO→PO 转换、OriginSetting 通过显式 JSON 解析且已有损坏数据测试，原“裸转换/回写”描述已不成立。 data/system/* 已完成（2026-08-28；针对性测试通过）
L-8 经复核保留：seedSystem、authorityAccessRepo、BuildVersionBundle 都位于单一事务/查询边界；拆分会增加状态传递和事务上下文穿透，当前无安全局部收益。 data/system/seed.go、authority.go、version.go 评估完成，保留（2026-08-28）
L-9（部分完成） AuthorityResponse.DeletedAt 已改为 json:"-"，且 integration 配置字段已迁移为 DTO 自有类型并在 service 边界映射。 ID 类型分叉涉及现有 handler/usecase/数据库键类型的兼容迁移；ErrorRecordMutationRequest 的指针字段用于区分省略与显式空值且已有测试，原建议不成立，保留。 service/dto/* 部分完成（2026-08-28；针对性测试通过）
L-10 经复核保留：Kratos errors 仅用于需要稳定 HTTP reason/status 的跨层错误；其余 stdlib sentinel/包装错误服务于内部状态机和 errors.Is 判定。一次性统一会改变现有响应映射与错误文本，当前无安全收益。 biz/system/errors.go 等 评估完成，保留（2026-08-28）
L-12 经复核保留：DTO binding 标签覆盖结构性必填约束，handler 手工校验覆盖认证上下文、跨字段关系和 transport 特例；职责不同，强行统一会把业务规则推入 DTO 或遗漏上下文校验。 server/handler/* + service/dto/* 评估完成，保留（2026-08-28）

八、简单实现复杂化

# 问题 位置 轮次
C-1 经复核保留：Create 的字段回比保护业务模块返回的权威订单快照，指纹校验保护持久化幂等键；两道校验处于不同边界，删除任一都会重新开放金额/业务对象漂移。 biz/payment/payment.go:385-402 评估完成，保留（2026-08-28）
C-2 经复核保留：loadUser 面向单用户完整关系加载，loadUsers 批量预取关联以避免 N+1，且基础 PO→DO 已复用 baseBizUser；继续合并会损害查询策略。 data/system/user.go 评估完成，保留（2026-08-28）
C-4 经复核保留：*Data nil 防御覆盖初始化前、热重载失败与测试替身边界；NewIntegrationRuntime(nil) 返回空 Store 保持 Wire/独立测试可用性，删除会改变失败模式。 data/data.go 评估完成，保留（2026-08-28）
C-6 经复核保留：请求体上限、multipart 文件声明大小和分片会话参数分别保护 transport、解析器与业务边界，不是同一层重复校验。 server/handler/media.go 评估完成，保留（2026-08-28）
C-7 按 2.2 既定排除范围保留：双层登记机制暂无业务消费者，移除会改变未来模块接入 seam。 integration/websocket 评估完成，保留（2026-08-28）
C-8 经复核保留：PaymentLogger 是支付审计的稳定替换 seam，即使当前只有一个实现也便于测试隔离和未来多 sink 扩展。 biz/payment/payment_log.go 评估完成，保留（2026-08-28）
C-11 已改用具名 rowQueryOptions 传递分页与 required 语义，消除 data 层相邻布尔参数歧义；查询行为不变。 data/system/list.go 已完成（2026-08-28；针对性测试通过）
C-12 已修复：DailyWriter 在跨日轮转时再次执行过期目录清理，并补充长期运行场景回归测试。 internal/logging/daily.go；daily_test.go 已完成（2026-08-28）

九、结构性设计（大动作需决策）

# 问题 位置 轮次
X-1 已完成影响分析，暂不实施单一声明源迁移：routecatalog 承载审计/Swagger/模块同步元数据，router 负责 Gin handler 绑定；当前 catalog 还无法表达 handler 注入与注册顺序，强行合并会扩大启动与路由回归面。 server/router/*；routecatalog/catalog.go 评估完成，保留分离（2026-08-28）
X-2 经复核保留：新增资源触碰 DTO、service、biz、repo、route 和 Wire 是当前分层契约的必要显式步骤；自动注册会隐藏依赖。 — 评估完成，保留（2026-08-28）
X-3 已完成影响分析，暂不合并三种配置形状：storage/email 需要强类型 config.Store 快照与文件兼容，mq/websocket 需要按 provider 的 runtimeconfig.Store 热通知；统一形状会牺牲强类型校验或通知粒度。 data/integration_config.go 等 评估完成，保留分离（2026-08-28）
X-4 经复核保留：swagger 运行时文档由 routecatalog 元数据生成并需补充运行时路径参数/安全声明，server 根包是合理的装配位置。 server/swagger.go 评估完成，保留（2026-08-28）
X-6 经复核保留：staticfiles 是 HTTP 静态路由入口，storage/local.go 是持久化 provider；两者生命周期和接口不同。 server/staticfiles、integration/storage/local.go 评估完成，保留（2026-08-28）
X-7 经复核保留：gopay_helpers.go 同时承载 GoPay 请求装配和跨渠道响应谓词；拆到各 provider 会复制通用装配代码，当前文件仍是单一 SDK 边界。 integration/payment/gopay_helpers.go 评估完成，保留（2026-08-28）
X-8 经复核保留：vendor DSL 的 Required 字段用于严格拒绝未完成商户配置，14 键映射保持协议扩展点；放宽会增加运行时失败。 integration/payment/vendor.go 评估完成，保留（2026-08-28）
X-9 已完成影响分析，现状并非“只换快照”：watchLoop 负责发布合并快照，Data.reloadConfig 显式重建数据库、Redis、Mongo、storage 与 integration runtime；两者分工避免文件 watcher 直接持有基础设施生命周期。合并为单通道需重做锁、回滚与连接退休策略，暂不改动。 config/runtime.go:263-287；data/config_store.go:124-252 评估完成，保留分离（2026-08-28）
X-10 经复核保留：新增渠道需同时声明 biz provider、adapter 工厂和配置元数据，三处分别属于领域常量、I/O 实现和管理面契约，自动化注册会牺牲显式校验。 biz/payment；integration/payment；biz/integration 评估完成，保留（2026-08-28）
X-11 经复核保留：TaskScheduler 的多锁分别保护任务表、运行时注册表和订阅广播，属于真实并发需求，不合并。 worker/task_scheduler.go 评估完成，保留（2026-08-28）

审查后认为合理、不建议改动的部分

  • modules 与 routecatalog 分离：启动期装配 vs 请求期热路径，消费方零重叠
  • Provider 接口缝模式 + provider.Database 中性接口：正当（system 包内 Provider 与 DatabaseProvider 两个近义缝命名易混淆，建议注释互指）
  • config.Store 与 runtimeconfig.Store 分离：正确（D-9 词表同构为已知保留项）
  • utils/routepath、uploadpolicy：纪律良好
  • worker→biz 正向+接口倒置：任务链路最规范的一段
  • data 根多文件同包：符合 data/README 约定
  • apple_jws.go 证书链校验：必要安全设计（经 gopay 源码核对补真实漏洞）；单一根指纹需运维轮换预案注释
  • capture/auth 中间件质量：有据可依
  • 新增缝质量（第四轮验证）：PaymentAdapterFactory（biz 接口+integration 实现+wire 绑定，单向无环）、MergeRuntimeConfig（单点三调用）、deletePrefixViaList（函数式注入，失败关闭正确）、AST 缓存（size+mtime 失效）、systeminfo（integration 定位正确）——均内聚、依赖最小、无越界 import

处置建议（按优先级）

  1. 正确性缺陷与安全边界：W-1～W-6 已完成并经回归验证。
  2. 死代码与分层整改：已完成可证明无消费者项；其余公开契约或零消费者基础设施均已完成影响分析并记录保留理由。
  3. 结构性项目：D/F/S/P/L/C/X 剩余条目均已按依赖、并发、兼容性和 Wire 影响完成评估；暂无应在模板中强行落地的大改造。