sundynix-pets/pets-be/README.md

肉垫计划

核心功能：多宠物档案、日常照顾任务、多宠物遛狗与主动位置分享、约遛。后端用 Gin + GORM + PostgreSQL，管理端用 React + Vite + shadcn/ui + Tailwind，构建后通过 go:embed 随服务提供 /。

目录

• cmd/server：服务入口
• internal/config：配置
• internal/model：数据库模型
• internal/database：PostgreSQL 连接和迁移
• internal/storage：MinIO 文件存储
• internal/httpapi：用户与管理端 API
• web/admin：管理端源码
• internal/admin/dist：嵌入的管理端构建产物

本地启动

1. cp configs/config.example.yaml configs/config.yaml，设置 PostgreSQL、MinIO、JWT 和微信参数。
2. cd web/admin && npm ci && npm run build。
3. 若数据库还不存在，在 pets-be 目录执行一次 go run ./cmd/dbinit。
4. 执行 go run ./cmd/server。

默认业务接口 http://localhost:9090/api，管理端 http://localhost:9090/。小程序生产 API 地址是 https://pet.sundynix.cn/api。

配置可用 PETS_ 前缀的环境变量覆盖，例如 PETS_POSTGRES_PASSWORD。生产模式必须设置 PETS_ADMIN_PASSWORD，微信登录需要 App ID 和 App Secret。auth.dev_login 只能在 debug 模式开启。

数据

GORM 使用 sundynix_ 表前缀、单数 snake_case 表名和字段名，例如 sundynix_user。主键均为 PostgreSQL uuid，Go 字段为 string。文件内容存 MinIO；sundynix_file 存 bucket、object_key、md5、url 和元信息。头像与约遛封面只通过 *_file_id 关联文件表。上传会先按 MD5 查重。

现有 MySQL 数据未自动迁移。新的 PostgreSQL 表在服务启动时自动创建。正式切换旧数据前，应单独设计数据迁移映射并备份。

部署

../deploy/docker-compose.yml 使用外部 PostgreSQL 和 MinIO；把 ../deploy/.env.example 复制为 .env 后设置凭据。pet.sundynix.cn 用于业务 API；s3.sundynix.cn 用于文件上传和图片直链。URL 由 MinIO endpoint、bucket 和 object key 拼接，在上传时写入文件表，格式为 https://s3.sundynix.cn/sundynix-pet/<object_key>。res.sundynix.cn/browser/... 是 MinIO 控制台页面，不能作为图片直链。

管理端路由与犬种百科

菜单使用独立路由：/admin/overview、/admin/users、/admin/pets、/admin/breeds、/admin/walks、/admin/meetups、/admin/tasks、/admin/files；登录页 /admin/login。根路径自动进入工作台或登录页；Go 的 SPA 回退支持刷新和直达链接。业务接口仍在 /api，无需额外 API 前缀。

犬种目录自动导入 350 项（CKU 去重 347 项，另补充三种实用分类），按名称拼音 A–Z 排序。选品种使用 breed_id，手动填写保留 breed 名称并清空 breed_id。后台提供新增、编辑、启用、停用、搜索及每页十条分页。停用品种不影响已有宠物档案。

CKU 当前返回完整详情的 88 个犬种已整理基本资料、简短改写介绍和来源链接；另三项补充分类提供原创介绍。资料缺失时显示待补充，后台可以编辑百科字段。图片与长篇犬种标准未转载。

登录刷新

管理端和小程序的访问 token、refresh token 都为 2 小时。请求前发现不足一分钟即刷新；401 也会尝试刷新并仅重试一次。刷新凭证每次轮换，数据库只存 SHA-256 摘要；两个角色的凭证不能混用，停用账号、过期及退出会话都不能继续刷新。后台退出会撤销会话和其访问 token。

刷新成功后，两种凭证重新计时两小时；超过两小时未使用则重新登录。小程序自动重新微信登录，管理端回到登录页并保留原目标路由。并发接口共用刷新请求，支持 Web Locks 的浏览器还会跨标签页串行刷新；网络失败保留凭证以便重试。

接口：POST /api/auth/refresh、POST /api/admin/refresh，请求体为 { "refresh_token": "..." }。登录与刷新响应包含 token、refresh_token、expires_in: 7200、expires_at、refresh_expires_at（Unix 秒）。旧七天 token 会要求重新登录。时长按业务约束固定两小时，旧环境变量不会把期限拉长。