52 lines
4.2 KiB
Markdown
52 lines
4.2 KiB
Markdown
# 肉垫计划
|
||
|
||
核心功能：多宠物档案、日常照顾任务、多宠物遛狗与主动位置分享、约遛。后端用 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 会要求重新登录。时长按业务约束固定两小时，旧环境变量不会把期限拉长。
|