邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
77 lines
4.9 KiB
Markdown
77 lines
4.9 KiB
Markdown
## 背景与现状概要
|
||
- 技术栈：后端 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 角色映射），我将在文档中补充并与现有实现对齐。 |