64 lines
5.2 KiB
Markdown
64 lines
5.2 KiB
Markdown
---
|
||
name: 完善项目 README 文档
|
||
overview: 为空白的 README.md 撰写一份完整的中文项目文档，涵盖项目简介、功能特性、技术栈、目录结构、快速开始（依赖/配置/数据库/启动）、API 概览、第三方 AI 服务说明、可观测性与部署等。
|
||
todos:
|
||
- id: explore-details
|
||
content: 使用 [subagent:code-explorer] 补充确认 tokenhub/service/errcode/mysqlmodel 表结构/Redis 用途/AI 服务端点等 README 所需事实
|
||
status: completed
|
||
- id: write-readme-core
|
||
content: 撰写 README 主体：项目简介、核心功能、技术栈、目录结构、快速开始（依赖/配置/基础设施/AI 服务/运行）
|
||
status: completed
|
||
dependencies:
|
||
- explore-details
|
||
- id: write-readme-api-ops
|
||
content: 撰写配置说明、API 概览表、可观测性与后台任务、部署提示与安全注意事项，并全文校对与代码事实一致性
|
||
status: completed
|
||
dependencies:
|
||
- write-readme-core
|
||
---
|
||
|
||
## 用户需求
|
||
|
||
为 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 采用面向开发者的标准结构，中文撰写，章节顺序遵循"是什么 → 能做什么 → 怎么跑起来 → 怎么配 → 有哪些接口 → 怎么运维"的认知路径：
|
||
|
||
1. 项目简介
|
||
2. 核心功能
|
||
3. 技术栈
|
||
4. 目录结构
|
||
5. 快速开始（依赖 → 配置 → 基础设施 → AI 模型服务 → 运行）
|
||
6. 配置说明
|
||
7. API 概览
|
||
8. 可观测性与后台任务
|
||
9. 部署提示
|
||
10. 安全注意事项
|
||
|
||
## 写作规范（关键约束）
|
||
|
||
- **事实准确性优先**：所有技术栈版本、路由、配置段、默认值必须与 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 各章节的事实清单，确保文档内容与代码一一对应、无虚构。 |