邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
4.9 KiB
4.9 KiB
背景与现状概要
- 技术栈：后端 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、RBACRequireAdminAction。 - 标准化约定：分页键（
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用法并保持最小侵入。
下一步
- 确认本计划后：
- 输出架构梳理文档；
- 生成端点清单并编制前后端 API 文档；
- 提交清理候选与验证报告，执行安全清理。
- 如需额外约定（错误码字典、分页/排序统一规范、RBAC 角色映射），我将在文档中补充并与现有实现对齐。