feat: rebuild pet app and backend around core care flows
This commit is contained in:
+26
-55
@@ -1,64 +1,35 @@
|
||||
# 毛孩子计划 · 后端 (pets-be)
|
||||
# 肉垫计划
|
||||
|
||||
Gin + GORM + MySQL + MinIO 的宠物小程序后端，内嵌 React(Vite + Tailwind + shadcn/ui) 后台管理。
|
||||
|
||||
## 技术栈与约定
|
||||
- 模块路径 `github.com/sundynix/pets-be`，标准 Go 布局（`cmd/ internal/ pkg/ configs/ deployments/ web/`）
|
||||
- 所有数据库表带前缀 `sundynix_`
|
||||
- 统一响应 `{code, message, data}`（`pkg/response`），列表接口统一分页参数 `page` / `page_size`（`response.PageQuery` + `PageResult`）
|
||||
- MySQL `root/root` 库 `pets`；MinIO `sundynix/sundynix` 桶 `pets`
|
||||
- 服务端口 `:8080`；后台在 `http://localhost:8080/admin`（seed 管理员 `sundynix/sundynix`）
|
||||
|
||||
## 快速开始
|
||||
```bash
|
||||
# 1. 起依赖（MySQL + MinIO）
|
||||
make env-up # 或 cd deployments && docker compose up -d
|
||||
|
||||
# 2. 构建后台前端 + 后端单二进制
|
||||
make build # 产物 bin/pets-be（已 embed 后台）
|
||||
./bin/pets-be
|
||||
|
||||
# 或开发期直接运行（使用现有 internal/admin/dist）
|
||||
make run
|
||||
```
|
||||
|
||||
### 后台前端开发（热更新）
|
||||
```bash
|
||||
make admin-dev # vite dev server :5173，已代理 /api → :8080
|
||||
# 改完执行 make admin-build 让产物落到 internal/admin/dist，再 go build 即 embed
|
||||
```
|
||||
核心功能：多宠物档案、日常照顾任务、多宠物遛狗与主动位置分享、约遛。后端用 Gin + GORM + PostgreSQL，管理端用 React + Vite + shadcn/ui + Tailwind，构建后通过 `go:embed` 随服务提供 `/admin/`。
|
||||
|
||||
## 目录
|
||||
- `cmd/server` 入口：载配置→连库→迁移→seed→建桶→路由→启动
|
||||
- `internal/config` 配置(viper，支持 `PETS_` 环境变量覆盖)
|
||||
- `internal/model` GORM 模型（`sundynix_` 前缀）
|
||||
- `internal/database` 连接/迁移/seed
|
||||
- `internal/storage` MinIO 封装（自动建桶 + 上传）
|
||||
- `internal/service` 业务逻辑；`internal/handler` HTTP 处理器；`internal/router` 路由
|
||||
- `internal/middleware` CORS / 用户鉴权 / 管理员鉴权
|
||||
- `internal/admin` `go:embed` 内嵌后台产物 + SPA fallback
|
||||
- `pkg/response` 统一响应与分页；`pkg/jwt` 令牌；`pkg/errcode` 错误码
|
||||
- `web/admin` 后台前端源码
|
||||
|
||||
## 接口
|
||||
- 小程序 `/api/*`（用户 JWT）：auth / user / pets / onboarding / records / tasks / plan / reminders / report / bill / community / articles / pro / ai / upload
|
||||
- 后台 `/api/admin/*`（管理员 JWT）：login / stats / users / pets / posts / comments / articles / memberships
|
||||
- `cmd/server`：服务入口
|
||||
- `internal/config`：配置
|
||||
- `internal/model`：数据库模型
|
||||
- `internal/database`：PostgreSQL 连接和迁移
|
||||
- `internal/storage`：MinIO 文件存储
|
||||
- `internal/httpapi`：用户与管理端 API
|
||||
- `web/admin`：管理端源码
|
||||
- `internal/admin/dist`：嵌入的管理端构建产物
|
||||
|
||||
## 登录鉴权
|
||||
默认 `auth.dev_login: true`，`POST /api/auth/login {"nickname":"xxx"}` 即发用户 JWT。
|
||||
接真微信：在 `configs/config.yaml` 填 `wechat.app_secret` 并把 `dev_login` 置 false，实现 `/api/auth/wechat`(code2session)。
|
||||
## 本地启动
|
||||
|
||||
### access token + refresh token
|
||||
登录接口返回 `token`(access) 与 `refresh_token` 两个令牌：
|
||||
1. `cp configs/config.example.yaml configs/config.yaml`，设置 PostgreSQL、MinIO、JWT 和微信参数。配置文件不进入 Git。
|
||||
2. `cd web/admin && npm ci && npm run build`。
|
||||
3. 若数据库还不存在，在 `pets-be` 目录执行一次 `go run ./cmd/dbinit`。
|
||||
4. 执行 `go run ./cmd/server`。
|
||||
|
||||
- **access token**：JWT，默认 **2 小时**（`jwt.expire_hours`），放 `Authorization: Bearer`，服务端无状态校验。
|
||||
- **refresh token**：随机串，落库 `sundynix_refresh_tokens`（**只存 sha256**）。小程序 30 天、后台 7 天。
|
||||
- 续期：`POST /api/auth/refresh` / `POST /api/admin/refresh`，入参 `{"refresh_token":"..."}`，返回新的一对令牌。
|
||||
- 退出：`POST /api/auth/logout` / `POST /api/admin/logout` 作废该刷新令牌。
|
||||
默认业务接口 `http://localhost:9090/api`，管理端 `http://localhost:9090/admin/`。小程序生产 API 地址是 `https://pet.sundynix.cn/api`。
|
||||
|
||||
安全约定：
|
||||
- **每次续期都轮换**刷新令牌，旧的立即作废；作废后 60 秒内再到达算并发重试（放行），超过则判定泄露，**吊销该账号全部会话**。
|
||||
- 主动退出、被连坐吊销的令牌不享受宽限期。
|
||||
- 禁用用户时一并吊销其刷新令牌，最多 2 小时后彻底失去访问。
|
||||
配置可用 `PETS_` 前缀的环境变量覆盖，例如 `PETS_POSTGRES_PASSWORD`。生产模式必须设置 `PETS_ADMIN_PASSWORD`，微信登录需要 App ID 和 App Secret。`auth.dev_login` 只能在 debug 模式开启。
|
||||
|
||||
前端两端都做了单飞续期：并发请求同时 401 只会发一次 refresh（否则刷新令牌会被并发轮换掉）。小程序续期失败会回退到 `wx.login` 重新登录。
|
||||
## 数据
|
||||
|
||||
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 控制台页面，不能作为图片直链。
|
||||
|
||||
Reference in New Issue
Block a user