## 概览
- 后端以 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 文档与实际路由对齐，前后端调用一目了然。