csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
e1ec02490453ad4f651ce498d5fa6e23ec239639
junhong_cmp_fiber/.planning/codebase/CONCERNS.md

14 KiB
Raw Blame History

Codebase Concerns

Analysis Date: 2026-03-27

Tech Debt

配置与凭据管理（严重级别：Critical）:

  • Issue: 仓库内存在已提交的生产/测试环境敏感配置与直连外部基础设施的写法，配置边界没有被代码、脚本和部署文件统一约束。
  • Files: docker-compose.prod.yml, Makefile, pkg/config/defaults/config.yaml, scripts/verify_migration/main.go, scripts/verify_indexes/main.go, docs/deployment/deployment-guide.md
  • Impact: 凭据轮换成本高；泄漏后影响数据库、Redis、对象存储、短信网关、Gateway 与部署链路；开发、测试、生产边界容易串用。
  • Supporting evidence:
    • docker-compose.prod.yml 直接写入数据库、Redis、JWT、对象存储、Gateway、短信服务配置。
    • Makefile 的 DB_URL 内嵌远程数据库连接串。
    • pkg/config/defaults/config.yaml 为 gateway.app_id、gateway.app_secret 提供非空默认值，服务在未显式覆盖时仍会初始化 Gateway 客户端，见 cmd/api/main.go:366-383。
    • scripts/verify_migration/main.go 与 scripts/verify_indexes/main.go 直接写死远程 PostgreSQL DSN。
    • docs/deployment/deployment-guide.md 把 Registry 凭据与数据库连接示例直接写进文档。
  • Fix approach: 把所有密钥迁移到部署平台 Secret/环境注入；默认配置只保留空值；脚本统一改为读取环境变量；把示例文档改成占位符而不是真实值。
  • Suggested follow-up investigation topics:
    • 盘点 openspec/, docs/, scripts/ 中所有历史凭据残留。
    • 审查 Gitea Secrets、Docker Registry、数据库、Redis、对象存储、短信网关、Gateway 的轮换计划。
    • 检查 .env、.env.local 是否已在团队机器与 Runner 上扩散。

支付与微信配置迁移未闭环（严重级别：High）:

  • Issue: 设计已经切到 tb_wechat_config + payment_config_id，但代码与文档仍保留环境变量和单例支付实现，处于半迁移状态。
  • Files: docs/wechat-config-management/功能总结.md, internal/service/order/service.go, internal/service/recharge/service.go, internal/handler/callback/payment.go, docs/environment-variables.md, scripts/verify-wechat.sh, docker-compose.prod.yml
  • Impact: 多支付配置切换、旧订单验签、客户端支付发起、OAuth 配置一致性存在行为不一致风险；运维很难判断哪些配置源仍然生效。
  • Supporting evidence:
    • docs/wechat-config-management/功能总结.md:232-238 明确写着客户端支付发起仍是留桩，OAuth 仍从环境变量读取，且旧 JUNHONG_WECHAT_PAYMENT_* “可清理”。
    • internal/service/order/service.go:2107,2163,2356,2362 与 internal/service/recharge/service.go:271、internal/handler/callback/payment.go:66,143 仍保留 TODO/留桩。
    • docs/environment-variables.md:36-69 与 scripts/verify-wechat.sh 仍把微信支付环境变量当成必填启动前置条件。
    • docker-compose.prod.yml 注释称“微信配置已迁移至数据库”，但部署文件仍维持部分旧式环境变量与其他支付相关外部配置模式。
  • Fix approach: 明确单一配置源；把“已迁移”“留桩”“仍依赖环境变量”的边界写入运维文档；在代码层补齐动态加载或删除旧入口。
  • Suggested follow-up investigation topics:
    • 核实当前线上 OAuth 与支付分别读哪一套配置。
    • 核查 payment_config_id 相关回调链路是否覆盖订单、资产充值、代理充值三条路径。
    • 为未实现的客户端支付入口建立显式禁用清单。

核心服务体量过大（严重级别：High）:

  • Issue: 部分核心服务文件已经远超团队规范中的函数/文件规模要求，维护成本和回归风险高。
  • Files: internal/service/order/service.go, AGENTS.md
  • Impact: 改动难以局部验证；支付、幂等、库存/余额、回调逻辑耦合；新需求更容易引入回归。
  • Supporting evidence:
    • AGENTS.md:371-375 要求函数长度 ≤ 100 行，核心逻辑建议 ≤ 50 行。
    • internal/service/order/service.go 的 TODO 已出现在 2107、2163、2356、2362 行，说明文件至少超过 2362 行。
  • Fix approach: 按支付发起、支付回调、订单状态流转、幂等与锁、钱包扣款等职责拆分子服务/辅助组件。
  • Suggested follow-up investigation topics:
    • 统计 internal/service/ 中超长文件与超长函数。
    • 识别最常改动的热点段落与共享依赖。

Known Bugs

健康检查接口对故障返回 200 成功包裹（严重级别：High）:

  • Symptoms: PostgreSQL 或 Redis 故障时，/health 仍通过 response.Success 返回成功包裹，只在 data.status 中标记 degraded。
  • Files: internal/handler/health.go, docker-compose.prod.yml, Dockerfile.api, debug-deployment.sh
  • Trigger: 数据库或 Redis Ping 失败。
  • Workaround: 监控端必须解析响应体里的 data.status 与 services.*.status，不能只看 HTTP 状态码。
  • Supporting evidence:
    • internal/handler/health.go:101-111 注释与实现都明确“端点本身能响应即视为成功”。
    • docker-compose.prod.yml 与 Dockerfile.api 的健康检查只执行 wget --spider http://127.0.0.1:3000/health，不会校验 JSON 内容。
  • Suggested follow-up investigation topics:
    • 确认当前容器健康检查、反向代理、告警系统是否只看 200。
    • 评估是否需要新增 readyz/livez 区分活性与依赖可用性。

API 路径文档与实际路由不一致（严重级别：Medium）:

  • Symptoms: 文档仍混用 /api/v1、/api/auth、/api/c/v1，读者很难判断当前真实入口。
  • Files: README.md, internal/routes/routes.go, scripts/check-comment-paths.sh
  • Trigger: 新人按 README 试运行、按旧注释实现客户端、或依据文档回归接口。
  • Workaround: 以 internal/routes/routes.go 为准核对真实挂载路径。
  • Supporting evidence:
    • internal/routes/routes.go:21-39 当前真实路由为 /api/auth、/api/admin、/api/c/v1、/api/callback。
    • README.md:577-583 仍展示 v1 := app.Group("/api/v1") 的旧限流示例；README.md:588-624 仍以 /api/v1/users 讲解请求流。
    • scripts/check-comment-paths.sh 只检查 internal/handler/ 中残留 /api/v1，并不覆盖 README.md、docs/、openspec/。
  • Suggested follow-up investigation topics:
    • 扫描所有 docs/, README.md, openspec/, specs/ 中的旧路径。
    • 明确哪些旧路径仍需要兼容，哪些应统一下线。

Security Considerations

部署流水线绕过 TLS 校验（严重级别：High）:

  • Risk: 工作流检出步骤通过 GIT_SSL_NO_VERIFY=1 跳过证书校验，供应链完整性依赖内网信任而不是证书验证。
  • Files: .gitea/workflows/deploy.yaml
  • Current mitigation: 注释说明是“内网自签名证书”。
  • Recommendations: 为 Gitea/Registry 配置受信 CA；移除跳过校验；至少把跳过范围限制在明确的单一主机与受控 Runner。
  • Supporting evidence:
    • .gitea/workflows/deploy.yaml:23-27 设置 GIT_SSL_NO_VERIFY=1 后执行 git clone。

对外/回调错误信息泄漏底层细节（严重级别：Medium）:

  • Risk: 健康检查与富友回调把底层错误或内部状态直接返回给调用方，不符合统一错误暴露规范。
  • Files: internal/handler/health.go, internal/handler/callback/payment.go, AGENTS.md
  • Current mitigation: 有统一错误处理规范，但没有覆盖这两个特殊出口。
  • Recommendations: 对外返回统一错误码/固定消息，把底层错误仅写日志。
  • Supporting evidence:
    • AGENTS.md:124-129 明确禁止直接暴露底层错误。
    • internal/handler/health.go:50-60,82-85 直接返回 err.Error()。
    • internal/handler/callback/payment.go:178-191 直接把 err.Error() 拼入富友回调失败响应。

Performance Bottlenecks

默认限流仍使用内存存储且默认关闭（严重级别：Medium）:

  • Problem: 默认配置既不开启限流，也默认使用 memory 存储；多实例部署时无法形成统一配额。
  • Files: pkg/config/defaults/config.yaml, cmd/api/main.go, README.md
  • Cause: 配置更偏向本地开发便利，缺少生产默认值与环境级约束。
  • Improvement path: 明确生产必须启用 Redis 存储限流；在部署文档里给出环境变量模板；增加启动日志或自检提示当前限流模式。
  • Supporting evidence:
    • pkg/config/defaults/config.yaml:87-93 默认 enable_rate_limiter: false、storage: memory。
    • cmd/api/main.go:236-278 只有显式开启时才挂载限流，并根据配置选择 Redis 或内存存储。

Fragile Areas

OpenAPI 文档生成依赖手工双点维护（严重级别：Medium）:

  • Files: AGENTS.md, docs/api-documentation-guide.md, cmd/api/docs.go, cmd/gendocs/main.go
  • Why fragile: 新增 Handler 必须同时更新两个文件；流程靠人工记忆，历史上已经出现清单不一致并专门做过修复。
  • Safe modification: 每次新增 Handler 时同时检查 cmd/api/docs.go、cmd/gendocs/main.go 与生成产物 docs/admin-openapi.yaml/logs/openapi.yaml。
  • Test coverage: 未发现自动化校验这两份清单一致性的 CI 步骤。
  • Supporting evidence:
    • AGENTS.md:53-65 明确要求手工更新两个文件。
    • docs/api-documentation-guide.md 多处把“忘记在两个文件中添加新 Handler”列为最常见问题。
    • .gitea/workflows/deploy.yaml 中未见 go run cmd/gendocs/main.go、diff 校验或文档一致性检查。

部署脚本与运行时约定已漂移（严重级别：Medium）:

  • Files: debug-deployment.sh, docker-compose.prod.yml, README.md, docs/deployment/deployment-guide.md
  • Why fragile: 诊断脚本仍假定旧环境变量名与外置配置文件存在，文档与当前嵌入式配置实现不完全一致。
  • Safe modification: 先以 docker-compose.prod.yml、pkg/config/defaults/config.yaml、cmd/api/main.go 为准修正运维脚本，再统一更新部署文档。
  • Test coverage: 未发现对诊断脚本、部署文档、健康检查语义的自动验证。
  • Supporting evidence:
    • debug-deployment.sh:52-57 仍 grep DB_|CONFIG_ENV，并尝试读取 /app/configs/config.yaml；当前配置前缀实际是 JUNHONG_，配置默认嵌入二进制，见 README.md:651-689、pkg/config/defaults/config.yaml。
    • docs/deployment/deployment-guide.md:302-305 仍建议从 /app/.env 拼接迁移命令，但容器实际入口用环境变量构造 DSN，见 docker/entrypoint-api.sh:8-17。

Scaling Limits

CI/CD 质量闸门过窄（严重级别：High）:

  • Current capacity: 当前工作流只做 clone、build、push、main 分支部署。
  • Limit: 文档一致性、脚本检查、编译前规范、迁移安全、健康语义等问题都可能直接进入镜像与部署环境。
  • Scaling path: 在 .gitea/workflows/deploy.yaml 前置独立质量作业，至少执行 bash scripts/check-all.sh、go build ./...、OpenAPI 生成/校验，并在部署前验证 compose 文件与镜像健康策略。
  • Supporting evidence:
    • README.md:941-957 声称脚本检查会在 CI/CD 自动执行。
    • .gitea/workflows/deploy.yaml 未出现 scripts/check-all.sh、go test、go vet、go build ./...、OpenAPI 校验等步骤。

Dependencies at Risk

Go 版本与运行基础不统一（严重级别：Medium）:

  • Risk: 版本声明分散在多个位置，升级与排障时容易出现“本地能过、容器不一致”的问题。
  • Impact: 构建环境复现、依赖升级与 bug 排查成本上升。
  • Migration plan: 约定单一权威版本源（如 go.mod + .tool-versions/.go-version），并让 Dockerfile、README、部署文档同步引用。
  • Supporting evidence:
    • go.mod:3 使用 go 1.25.0。
    • Dockerfile.api:4 与 Dockerfile.worker:4 使用 golang:1.25.6-alpine。
    • README.md:884 写的是 Go 1.25.1。

Missing Critical Features

缺少可执行的自动化质量/回归入口（严重级别：High）:

  • Problem: README、历史设计与测试文档大量提到 go test、IntegrationTestEnv、tests/integration/，但仓库当前未发现对应测试文件或 tests/ 目录。
  • Blocks: 无法快速验证重构、支付回调、权限过滤、部署脚本变更；文档中的测试命令无法直接落地。
  • Supporting evidence:
    • AGENTS.md:324-354 当前规范明确禁止自动化测试，和 README.md:712-756、docs/testing/test-connection-guide.md 的测试要求形成正面冲突。
    • 读取仓库根目录未发现 tests/ 目录；glob 搜索 tests/**/*_test.go 与 internal/**/*_test.go 未返回结果。
    • docs/testing/test-connection-guide.md 仍宣称“204 个测试总耗时 ~10.5 秒”并要求所有新测试遵循该规范。

Test Coverage Gaps

部署、配置迁移、运维脚本与文档一致性未见自动验证（优先级：High）:

  • What's not tested: docker-compose.prod.yml、debug-deployment.sh、scripts/migrate.sh、OpenAPI 文档生成器双清单、README/部署文档与代码的同步性。
  • Files: .gitea/workflows/deploy.yaml, docker-compose.prod.yml, debug-deployment.sh, scripts/migrate.sh, cmd/api/docs.go, cmd/gendocs/main.go, README.md
  • Risk: 配置漂移、凭据泄漏、文档错误、健康检查误报、迁移行为变化都可能在上线后才暴露。
  • Priority: High
  • Suggested follow-up investigation topics:
    • 设计最小化“文档/脚本一致性检查”而不是恢复完整自动化测试体系。
    • 评估是否要为部署文件与文档生成引入静态检查或 smoke check。

Concerns audit: 2026-03-27

Reference in New Issue View Git Blame Copy Permalink