## 背景与现状概要
- 技术栈：后端 Go（Gin 封装于 `internal/pkg/core`）、GORM、Viper、Zap、Swagger；前端 Vue3 + Vite + TypeScript + Pinia + Element Plus。
- 核心入口：`main.go`（服务启动与任务调度）；路由中心：`internal/router/router.go`；拦截与鉴权：`internal/router/interceptor/*`。
- 业务分层：处理器 `internal/api/{admin,activity,app,user,pay,common}`；服务 `internal/service/**`；数据访问 `internal/repository/mysql/{dao,model}`。
- 前端管理后台：`web/admin/src/**`，接口定义集中在 `web/admin/src/api/**`。

## 目标与交付物
- 代码结构梳理报告：目录分层说明 + 模块职责 + 依赖关系图（Mermaid）。
- 无用代码清理：列出候选清理清单、逐项验证、提交可回滚的变更方案。
- API 文档（前后端）：
  - 后端 REST 端点清单（方法、路径、鉴权、处理器、请求/响应示例、错误码、分页约定）。
  - 前端调用约定（基地址、拦截器、Token 注入、模块函数到后端端点的映射）。
- 更新与补充项目根文档：`docs/说明文档.md`（规划、实施方案、进度记录）。

## 实施步骤
### 1. 架构梳理（Align/Architect）
- 枚举代码目录：识别后端、前端、配置、构建、脚本、生成器与产物目录。
- 生成架构图：描绘后端分层（Router → Interceptor → API → Service → Repo）、前端分层（视图 → Store → API）。
- 输出《代码结构总览.md》：说明关键路径与职责、跨模块依赖、构建/部署要点。

### 2. 路由与端点收敛（Atomize）
- 解析 `internal/router/router.go` 的路由注册，枚举所有端点（含分组与中间件）。
- 关联处理器方法（如 `admin.*`、`activity.*` 等），抽取鉴权要求：`AdminTokenAuthVerify`、`AppTokenAuthVerify`、RBAC `RequireAdminAction`。
- 标准化约定：分页键（`page`、`page_size`）、通用响应包（`code`、`message`、`data`、`request_id`）、错误码体系。

### 3. API 文档编制
- 后端文档：生成《API文档-后端.md》
  - 列表：方法、路径、处理器、鉴权、中间件、请求参数、响应示例、错误码、注意事项。
  - 支付/回调、系统健康、上传等特殊端点单独章节。
- 前端文档：生成《API文档-前端.md》
  - 说明 Axios 基础配置（BaseURL、超时、拦截器、Token 注入）。
  - 列出 `web/admin/src/api/**` 模块函数到后端端点映射、入参/出参、调用示例。

### 4. 无用代码清理策略
- 判定规则：
  - 未被任何文件 `import`/调用；
  - 未在路由或启动流程中引用；
  - 构建产物（如 `build/resources/admin/**`）、运行日志（`logs/**`）；
  - 演示/测试脚本（如 `miniapp/pay-test/**`）、一次性生成器产物。
- 候选清单（初版）：
  - `internal/metrics/**`（若未启用 Prometheus）；
  - `internal/repository/mysql/testrepo_sqlite.go`（未检索到引用）；
  - `cmd/**`（工具/生成器，保留或迁移到 dev-only）；
  - `scripts/swagger.*`（构建脚本，非运行时）；
  - `build/resources/admin/**`、`logs/**`（产物与输出）。
- 清理流程：
  - 逐项交叉检索引用关系 → 标注“安全删除”/“需保留”；
  - 对可能未来使用的模块改为禁用配置或注释式保留，避免功能回退风险；
  - 产物与日志转移到忽略或发布流程之外（完善 `.gitignore` 与构建管线）。

### 5. 文档与规范同步
- 更新 `docs/说明文档.md`：规划、实施方案、节点记录（按用户规范）。
- 在 `docs/api/` 目录落地《代码结构总览.md》《API文档-后端.md》《API文档-前端.md》。
- 所有函数在新增代码中补充函数级注释（功能、参数、返回值）。

### 6. 验收与验证（Assess）
- 后端：`go build`、路由完整性检查、Swagger 校验（非生产）、关键端点手测。
- 前端：`vite build`、ESLint/Stylelint、页面 API 调用冒烟测试。
- 部署：非生产环境验证 PProf、CORS、静态资源路由回退；检查 `.env` 与证书安全。

## 输出物清单
- `docs/api/代码结构总览.md`（含架构图）
- `docs/api/API文档-后端.md`（REST 列表与约定）
- `docs/api/API文档-前端.md`（调用契约与示例）
- 可回滚的清理变更（提交前附清单与影响评估）

## 依赖与约束
- 保留生成器/工具目录（`cmd/**`）除非确认迁移；
- 配置与证书不改动业务值，仅完善文档与忽略策略；
- 如需补充 Swagger 注解，遵循现有 `swaggo` 用法并保持最小侵入。

## 下一步
- 确认本计划后：
  1) 输出架构梳理文档；
  2) 生成端点清单并编制前后端 API 文档；
  3) 提交清理候选与验证报告，执行安全清理。
- 如需额外约定（错误码字典、分页/排序统一规范、RBAC 角色映射），我将在文档中补充并与现有实现对齐。