5.2 KiB
5.2 KiB
name, overview, todos
| name | overview | todos | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 完善项目 README 文档 | 为空白的 README.md 撰写一份完整的中文项目文档，涵盖项目简介、功能特性、技术栈、目录结构、快速开始（依赖/配置/数据库/启动）、API 概览、第三方 AI 服务说明、可观测性与部署等。 |
|
用户需求
为 zt-closet-backend 项目（智能衣橱微信小程序后端）补全根目录下当前为空白的 README.md，产出一份与代码实际相符、可直接指导新开发者上手的完整中文项目文档。
文档内容要求
- 项目简介：说明项目定位（智能衣橱/衣柜管理小程序后端服务），概括核心能力：衣物管理、AI 衣物分类与抠图、穿搭与 AI 推荐、运势生成、社区互动（分享/收藏/点赞/通知）、额度体系、商品与微信支付订单。
- 技术栈：如实列出 Go 1.27、Gin、GORM + MySQL、Redis、Viper、JWT、腾讯云 COS、微信小程序登录与 APIv3 支付、OpenTelemetry（Trace/Metric/Log）、slog + lumberjack。
- 目录结构：按已探明的真实结构逐层说明（configs/global/internal/pkg/thirdparty 等），空占位目录（docs、sql、migrations、scripts 子目录）不得虚构内容。
- 快速开始：环境依赖、配置准备（复制 config.example.yaml 并填写）、MySQL/Redis 准备、两个 Python AI 模型服务的安装与启动、后端编译运行、健康检查验证。
- 配置说明：逐一说明配置段落（Server/Log/Mysql/Redis/OTel/JWT/Cos/Upload/MattingModel/ClassificationModel/WechatMini/WechatPay/UserDefaultQuota/Tokenhub）与默认值。
- API 概览：以表格列出 /ping 与 /api/v1 全部路由（公开路由与 JWT 鉴权路由分组），说明统一响应结构 {code, msg, data} 与 Bearer Token 鉴权方式。
- 可观测性与后台任务：OTel 上报、结构化日志（含 trace_id/span_id）、每日运势生成、权益补偿、订单超时过期等定时任务。
- 安全注意事项：JWT 密钥必填且须为强随机值、密钥仅存于配置文件不入库、微信回调验签等。
文档架构设计
README 采用面向开发者的标准结构，中文撰写，章节顺序遵循"是什么 → 能做什么 → 怎么跑起来 → 怎么配 → 有哪些接口 → 怎么运维"的认知路径：
- 项目简介
- 核心功能
- 技术栈
- 目录结构
- 快速开始（依赖 → 配置 → 基础设施 → AI 模型服务 → 运行）
- 配置说明
- API 概览
- 可观测性与后台任务
- 部署提示
- 安全注意事项
写作规范（关键约束）
- 事实准确性优先：所有技术栈版本、路由、配置段、默认值必须与 go.mod、router.go、main.go、config.example.yaml 已探明内容一致；不得凭想象补充不存在的文件或机制。
- 数据库初始化如实描述：全仓未发现 AutoMigrate 调用与建表 SQL（sql/、migrations/ 目录为空），README 中须如实说明表结构需按 internal/mysqlmodel 的模型定义自行准备建表 SQL，不得虚构自动建表能力。
- 配置机制如实描述：当前 pkg/setting 仅从 configs/config.yaml 读取、不支持环境变量覆盖（最近刚完成"配置全面去环境变量化"改造）；Tokenhub 段在 config.example.yaml 中缺失但 main.go 会读取（Model 默认 hy4、APIKey 为空时运势/AI 功能不可用），撰写时需核实 ReadSection 对缺失段的行为后如实说明。
- AI 服务说明：如实描述 Fashion-CLIP 分类服务（15 维度、hf-mirror 镜像、端口 8000 约定）与 BiRefNet 抠图服务（BiRefNet_lite、本地缓存优先、BIREFNET_REPO_ID 可覆盖、端口 8001 约定）的依赖安装、GPU 建议与启动方式。
- 安全提示：JWT SecretKey 为空会导致启动 panic（代码强制校验）、微信支付 APIv3Key 必须 32 字节、密钥不入库、配置不入版本库（.gitignore 检查 config.yaml 是否被忽略）。
推荐使用的扩展
SubAgent
- code-explorer
- 用途：在撰写 README 前，系统性地补充确认剩余关键事实——pkg/tokenhub（fortune.go、outfit_recommend.go、scheduler.go 的职责与触发时机）、internal/service 各业务服务职责清单、pkg/errcode 错误码分组、internal/mysqlmodel 表模型清单、internal/redisdao 缓存用途、thirdparty 两个 Python 服务的路由端点、pkg/setting 的 ReadSection 对缺失配置段的行为。
- 预期结果：形成一份可支撑 README 各章节的事实清单，确保文档内容与代码一一对应、无虚构。