增量质量报告 · codescan/codewiki-hub-api

• 分支：v1.5.0-pre.7
• 对比范围：e0a6558 (base) → 00f6c53 (head)
• 变更主题：新增「Agent 提示词存储 + 管理员 API」；GORM 日志参数化（安全加固）
• 质检增量：修复 5 条 / 新增 15 条（codescan.issues_diff 真实数据）

---

1. 变更概览

本次提交是一次功能新增 + 安全加固，共改动 15 个文件（新增 6 / 修改 9）：

功能链路（分层清晰，符合既有 Template 模块范式）：

• data.AgentPromptRepo（GORM 数据访问）→ biz.AgentPromptService（校验 + SHA256 checksum）→ controller.AgentPromptController（HTTP）→ server.NewHTTPServer 注册 4 条路由。
• 新表 hub_agent_prompt：models.go 新增 AgentPrompt 结构体，同时在 db.go 的 AutoMigrate 与 docs/ddl.sql 双向落地（表前缀 hub_，与 DDL 一致）。
• Wire 注入：initialize.go 的 repo/biz/service ProviderSet 各增一条 + wire_gen.go 同步生成。

接口变更（新增，Backward-compatible），均挂在 admin 命名空间：

GET    /hub/admin/agent-prompts
GET    /hub/admin/agent-prompts/{prompt_key}
PUT    /hub/admin/agent-prompts/{prompt_key}
PUT    /hub/admin/agent-prompts/{prompt_key}/enabled

安全加固：db.go 新增 newParameterizedGormLogger（ParameterizedQueries: true），GORM 日志不再插值 SQL 参数，避免提示词正文进入慢查询/错误日志；并新增回归测试 TestParameterizedGormLoggerDoesNotLogPromptBody 断言日志只出现 ? 占位符。

---

2. 修复的问题（base 有 / head 无）— 5 条

数据来源：codescan.issues_diff。

⚠ 落地判读（重要）：这 5 条并非真实修复，而是行号漂移的同一问题。对照「新增问题」列表可见同一问题在 head 中以下一行的行号重新出现：

• db.go 行过长 :66 → :90（文件头部插入 ~24 行）
• db_logging_test.go 圈复杂度 :14 → :66（前面插入新测试 ~52 行）
• initialize.go 行过长 :117 → :121、未使用参数/高耦合 :128 → :132（ProviderSet 各增 1~2 行，函数整体下移 4 行）

即净修复为 0 条，仅位置变化。不应将其计入"缺陷收敛"。

---

3. 新增的问题（head 有 / base 无）— 15 条

数据来源：codescan.issues_diff。

3.1 真实新增（本变更引入）

真实新增集中在 新增代码自身的重复代码块（错误映射 / 响应封装 / 测试桩），均 Low，无功能或安全风险。唯一 Threshold 级问题是 NewGormDB 高耦合（新增 logger 构造使其从 10 → 11）。

3.2 行号漂移导致"伪新增"（同 §2，实为同一问题换行号）

3.3 疑似误报

汇总：15 条新增中，真实新增 9 条（全部 Low + 1 条 Medium 高耦合），伪新增（行号漂移）5 条，误报 1 条。无 Critical / High，无功能或安全缺陷。

---

4. 代码质量与影响分析

4.1 正确性核查（人工复核，结论：良好）

• checksum 计算：biz.UpdateContent 先 TrimSpace 归一化，再 sha256 + hex，且以归一化后的正文计算，测试已覆盖（首尾空白去除后校验和一致）。
• 长度校验：utf8.RuneCountInString(normalized) > MaxAgentPromptChars(200_000)，按字符而非字节计数，中文安全。
• LIKE 通配符转义：escapeLikePattern 对 \、%、_ 转义，配合 ESCAPE '\'，用户输入按字面量匹配（TestAgentPromptRepoListEscapesWildcard 覆盖）。转义顺序（先转义 \）正确，无二次转义漏洞。
• 唯一性 / 更新语义：UpdateContent/UpdateEnabled 用 Updates(map) 部分更新，并以 RowsAffected == 0 → gorm.ErrRecordNotFound 处理并发删除，biz 层统一 mapAgentPromptError 映射为业务 ErrAgentPromptNotFound。
• 对外输出收敛：列表接口 agentPromptSummary 不含 prompt_content，正文仅详情接口返回（TestAgentPromptControllerListOmitsPromptContent 覆盖），减少正文外泄面。
• 安全日志： 生效并被测试锁死； default 分支仅记录 ，不回显原始错误值，响应体亦不泄露底层错误。

4.2 安全加固评估

• 本次是正向安全修复：GORM 日志改为参数化，提示词正文（可能含业务敏感内容）不再进入慢查询/错误日志。
• 该 Logger 作用于全局 DB 连接（所有查询），符合预期，但需确认下游无依赖"插值 SQL"日志的排障流程。

4.3 观察项 / 潜在风险（非阻断，建议评审确认）

1. admin 路由无路由级鉴权，updated_by 可伪造：4 条新路由未挂鉴权中间件（与既有 /hub/admin/*、模板管理一致，依赖上游 BFF 身份透传）。agentPromptUpdatedBy 直接取客户端可控的 X-User-Domain 头并小写化写入 updated_by。若提示词被视为敏感配置，建议补充权限校验，否则审计字段可被任意调用方伪造。
2. 请求体未限流：Update 使用 json.NewDecoder(ctx.Request().Body) 直接解码，DisallowUnknownFields 已开启，但未 MaxBytesReader；超长 body 会被完整读入内存后才在 biz 层按 200k 字符拒绝。建议在 handler 层限制体积（如 http.MaxBytesReader）。
3. 列表无分页：List 一次返回全表，提示词为配置类小表，当前可接受；若后续量级增长建议补分页。
4. 表初始化一致性：hub_agent_prompt 同时由 AutoMigrate 与 docs/ddl.sql 维护，需保证二者字段/索引长期一致（当前一致：prompt_key 唯一、category/enabled 索引）。
5. 无默认提示词种子：本次仅提供 CRUD，未提供种子数据/消费方，属分部交付，无需在本增量内处理，但需与后续 Agent V2 消费侧对齐。

4.4 工程质量正向信号

• 新增功能测试覆盖充分：biz（校验/哈希/错误映射）、data（SQLite 集成：筛选/排序/转义/更新审计）、controller（身份头、空正文 400、列表脱敏）三层层层有测，且测试即文档化行为契约。
• 分层依赖收敛良好：biz.AgentPromptRepository 接口 + wire.Bind，符合依赖倒置，未把 *gorm.DB 泄漏到 biz 层。

---

5. 结论与建议

总体风险等级：低。 本增量以新增功能为主，附带一项有价值的安全加固；未引入 Critical/High 缺陷，未发现功能性或安全性 bug。质检报告的 5 条"修复"实为行号漂移，净修复为 0；15 条"新增"中仅 9 条真实（多为 Low 重复代码），1 条误报。

建议动作：

1. （可选，低优先）合并 biz/controller 中重复的错误映射与响应封装小工具（对应 6 处重复代码块），消除 Low 噪音；NewGormDB 高耦合可通过抽取 buildGormLogger() 或 autoMigrate(db) 助手降低 fan-out。
2. （评审确认）明确 /hub/admin/agent-prompts/* 的鉴权归属；如提示词属敏感配置，补充权限校验与体积限制。
3. （报告口径）后续增量统计应将"行号漂移"类问题从修复/新增计数中剔除，避免"缺陷收敛"假象。

放行建议：可放行（无阻断项）。