zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bindbox-game/.trae/documents/API 与后台管理代码审计与整改计划.md
邹方成 6ee627139c
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 40s
Details
feat: 新增支付测试小程序与微信支付集成 
feat(pay): 添加支付API基础结构
feat(miniapp): 创建支付测试小程序页面与配置
feat(wechatpay): 配置微信支付参数与证书
fix(guild): 修复成员列表查询条件
docs: 更新代码规范文档与需求文档
style: 统一前后端枚举显示与注释格式
refactor(admin): 重构用户奖励发放接口参数处理
test(title): 添加称号效果参数验证测试
2025-11-17 00:42:08 +08:00

5.1 KiB
Raw Blame History

概览

  • 后端以 Go 实现，路由集中在 internal/router/router.go，分5组：管理端非认证(/api/admin登录)、管理端认证(/api/admin全量管理接口)、系统管理(/api模板兼容)、APP公开(/api/app)、APP认证(/api/app)。
  • 管理端处理器分布在 internal/api/admin/*，覆盖活动/期次/奖励/抽奖/用户资产/称号/道具卡/优惠券/工会/系统用户角色菜单等。
  • 前端后台管理位于 web/admin，Axios 基础 baseURL=/api，API 模块在 web/admin/src/api/*。

发现与结论

  • 路由与前端 URL 基本一致；系统管理模块通过 baseURL=/api 访问 /api/user/list|/api/role/list|/api/v3/system/menus/simple，与后端 systemApiRouter 对齐（internal/router/router.go:59-167）。
  • 前端存在绝对 URL 前缀问题：web/admin/src/api/reward-grant.ts:50 使用 url: '/api/admin/...'，与 baseURL=/api 叠加为重复前缀，应改为相对 admin/...。
  • 奖励发放接口在前端有重复实现：reward-grant.ts 与 player-manage.ts 同指向 POST /api/admin/users/{id}/rewards/grant（后端实现见 internal/api/admin/users_reward_admin.go:32-75），建议合并与统一用法。
  • 认证链路清晰：管理端拦截器校验 JWT、登录哈希与状态（internal/router/interceptor/admin_auth.go:18-82）；APP 端简化（internal/router/interceptor/app_auth.go:13-35）。前端 Axios 统一加 Authorization 并防抖登出（web/admin/src/utils/http/index.ts:65-76,84-92）。
  • 分层一致性：多数管理端处理器调用 service 层，但也有直接操作 DAO 的情况（如称号管理 internal/api/admin/titles_admin.go），建议将复杂业务（效果校验、用户称号唯一激活切换）沉入 service 保持一致性与复用。
  • 性能与合理性：
    • 工作台积分统计扫表累加（internal/api/admin/dashboard_admin.go:74-84）可改为 SQL 聚合并按有效期过滤；积分净变动已用流水 SUM（87-107），建议两者一致走 SQL。
    • 新用户概览多表聚合（224-381）逻辑合理但查询密集，后续可评估增加索引与批量 UNION/子查询降往返。
  • API 路由一致性：系统管理接口挂在 /api 与管理端其余接口挂在 /api/admin，存在认知负担；短期保留兼容，补齐文档；中期评估统一路径策略。

整改实施计划

阶段1：快速修复

  • 修复前端绝对 URL 前缀问题：将 web/admin/src/api/reward-grant.ts:50 的 url: '/api/admin/users/${userId}/rewards/grant' 改为 url: 'admin/users/${userId}/rewards/grant'，与其余模块一致。
  • 合并奖励发放 API：删除/重定向 reward-grant.ts 的重复实现，统一在 player-manage.ts 暴露 fetchGrantPlayerReward，或反之，在 reward-grant.ts 统一导出并在 player-manage.ts 复用。

阶段2：分层与可维护性

  • 抽取称号管理核心逻辑到 service：
    • 将 AssignUserTitle 的 upsert 与“仅保留一个激活称号”的切换（internal/api/admin/titles_admin.go:439-490）抽到 internal/service/title，供管理端与未来 APP 端统一调用。
    • 将效果参数校验 validateEffectParams（titles_admin.go:296-377）迁移为可复用的校验器，便于单元测试与前后端一致性。
  • 优化工作台统计：
    • 积分总额改为 SQL SUM(points) 并过滤过期（替换 dashboard_admin.go:74-84 的内存累加），减少 I/O 与CPU。

阶段3：一致性与文档

  • 路由规范化策略评审：维持 /api（系统管理）与 /api/admin 并存，新增开发文档条目明确两者用途与历史原因；中期根据前端路由与菜单加载需求评估是否迁移到 /api/admin/system/*。
  • 更新 Swagger 文档：核对 docs/swagger.yaml/docs/swagger.json 与现状路由一致，补充工作台接口、称号/效果接口、批量发放接口说明。

阶段4：测试与验证

  • 前端：为 Axios 层与关键 API（登录、奖励发放、称号分配）增加最小可运行的集成测试或契约测试；校验 401 防抖与登出行为。
  • 后端：为称号 service 新增单元测试（效果参数校验、scope 命中、唯一激活切换），为工作台统计新增 SQL 聚合测试。

参考定位

  • 路由总表：internal/router/router.go:50-53,56-167,169-188,190-210,213-232
  • 绝对 URL 问题：web/admin/src/api/reward-grant.ts:50
  • Axios baseURL：.env.development:7、web/admin/src/utils/http/index.ts:45-48
  • 奖励发放后端：internal/api/admin/users_reward_admin.go:32-75
  • 工作台积分统计：internal/api/admin/dashboard_admin.go:74-84,87-107
  • 称号分配逻辑：internal/api/admin/titles_admin.go:439-490
  • 认证拦截器：internal/router/interceptor/admin_auth.go:18-82、internal/router/interceptor/app_auth.go:13-35

验收标准

  • 前端所有 API 使用相对路径，无 /api/ 重复前缀；奖励发放仅一处实现且通过。
  • 工作台统计在数据量上升时仍稳定（SQL 聚合后端性能可观）。
  • 称号管理逻辑具备可测试的 service 层，接口行为与前端预期一致。
  • Swagger 文档与实际路由对齐，前后端调用一目了然。