188 lines
8.7 KiB
Markdown
188 lines
8.7 KiB
Markdown
# 宠迹 PawTrace · 服务端
|
|
|
|
> 宠物成长记录与生活管理后端项目
|
|
> 配套小程序: [`uniapp-pawtrace`](../uniapp-pawtrace)
|
|
> 配套管理端: [`admin-pawtrace`](../admin-pawtrace)
|
|
|
|
## 一、项目简介
|
|
|
|
**宠迹(PawTrace)** 是一款面向个人宠物主的本地化、合规化宠物记录工具。服务端不参与任何用户间互动、不存储敏感人脸/位置信息,所有图片/视频处理均在客户端完成,服务端只负责元数据存取与提醒触达。
|
|
|
|
### 设计原则
|
|
|
|
- ✅ **本地优先**:服务端只做"陪伴",核心数据存本地,服务端兜底
|
|
- ✅ **合规底线**:无 UGC 公开、无评论点赞、无支付、无地图 UGC 标注
|
|
- ✅ **云端可选**:基础版可纯本地使用,登录后提供云端同步与多端访问
|
|
|
|
## 二、技术栈
|
|
|
|
| 类别 | 选型 |
|
|
|----------|--------------------------------------------|
|
|
| 基础框架 | Spring Boot 4.0.6 / Java 21 |
|
|
| 持久层 | MyBatis-Plus 3.5.15 + MySQL 8.x |
|
|
| 缓存 | Redis (Lettuce) |
|
|
| 鉴权 | Sa-Token 1.45.x |
|
|
| 工具集 | Hutool 5.8.x / Fastjson2 |
|
|
| 对象映射 | MapStruct 1.6.x |
|
|
| 微信生态 | WxJava 4.8.x (小程序 / 订阅消息) |
|
|
| 对象存储 | 七牛云 / 阿里云 OSS / 腾讯云 COS / MinIO / AWS S3 |
|
|
| 接口文档 | Knife4j 4.6.x (OpenAPI 3) |
|
|
| 构建 | Maven 3.9+ |
|
|
|
|
## 三、目录结构
|
|
|
|
```
|
|
server-pawtrace
|
|
├── pom.xml
|
|
├── README.md
|
|
└── src/main
|
|
├── java/com/pawtrace/server
|
|
│ ├── ServerPawtraceApplication.java # 启动类
|
|
│ ├── common
|
|
│ │ ├── constant/ # 常量 (CommonConstants / ResultCode)
|
|
│ │ ├── enums/ # 枚举 (宠物性别 / 日记类型 / 信息卡分类)
|
|
│ │ ├── exception/ # 全局异常 (BusinessException / GlobalExceptionHandler)
|
|
│ │ ├── page/ # 分页 (PageRequest / PageResult)
|
|
│ │ ├── result/ # 统一返回 Result
|
|
│ │ └── utils/ # 工具类
|
|
│ ├── config # 配置类 (MyBatis Plus / Redis / Sa-Token / 异步 / 跨域 / Knife4j)
|
|
│ ├── entity # 基础实体 (BaseEntity)
|
|
│ └── modules # 业务模块
|
|
│ ├── user # 用户与鉴权
|
|
│ ├── pet # 宠物档案 + 体重历史
|
|
│ ├── diary # 成长日记
|
|
│ ├── health # 健康医疗(疫苗/驱虫/就诊)
|
|
│ ├── inventory # 物资管家
|
|
│ ├── timemachine # 时光机工坊(仅元数据)
|
|
│ ├── lifecard # 宠物生活信息卡
|
|
│ ├── feedback # 意见反馈
|
|
│ ├── reminder # 提醒调度 (Scheduled)
|
|
│ └── file # 文件上传
|
|
└── resources
|
|
├── application.yml # 主配置
|
|
├── application-dev.yml # 开发环境
|
|
├── application-prod.yml # 生产环境
|
|
├── mapper/ # MyBatis XML(可空)
|
|
└── sql/pawtrace.sql # 初始化 SQL
|
|
```
|
|
|
|
## 四、模块与功能映射
|
|
|
|
| 模块 | 路径前缀 | 对应功能设计章节 | 核心接口 |
|
|
|-------------------||-------------|--------------------------------------------------------|
|
|
| 用户/鉴权 | `/auth` | 一、个人中心 | 微信登录 / 登出 |
|
|
| 宠物档案 | `/pet` | 一、宠物档案 | CRUD + 体重历史分页 |
|
|
| 成长日记 | `/diary` | 二、成长日记 | 时间轴分页(按年/月/类型/宠物筛选) |
|
|
| 健康医疗 | `/health` | 三、健康医疗本 | 疫苗 / 驱虫 / 就诊 CRUD + 提醒开关 |
|
|
| 物资管家 | `/inventory` | 四、物资管家 | CRUD + 低库存预警 + 消耗记录 |
|
|
| 时光机工坊 | `/timemachine` | 五、时光机工坊 | 保存作品元数据(实际处理在客户端) |
|
|
| 宠物生活信息卡 | `/life-card` | 六、生活信息卡 | 按分类查询 + 详情 |
|
|
| 意见反馈 | `/feedback` | 一、个人中心 | 提交反馈 |
|
|
| 提醒调度 | (内部 Scheduled) | 三、提醒功能 | 每天 08:00 扫描即将到期的疫苗/驱虫 |
|
|
| 文件上传 | `/file` | (通用) | 单文件上传,本地存储,生产可切换 OSS |
|
|
|
|
> **未实现功能(明确排除)**:用户间互动、私信、评论点赞、UGC 地图标注、电商/支付、AI 医疗诊断 —— 详见 [功能设计.md § 附录](../功能设计.md)。
|
|
|
|
## 五、快速开始
|
|
|
|
### 1. 环境准备
|
|
|
|
- JDK 21+
|
|
- Maven 3.9+
|
|
- MySQL 8.x
|
|
- Redis 7.x(可选,登录态需要)
|
|
|
|
### 2. 初始化数据库
|
|
|
|
```bash
|
|
mysql -u root -p < src/main/resources/sql/pawtrace.sql
|
|
```
|
|
|
|
### 3. 修改配置
|
|
|
|
编辑 `application-dev.yml`,修改 MySQL/Redis 账号密码及 `application.yml` 中的微信小程序 `appid/secret`、OSS 配置。
|
|
|
|
### 4. 启动
|
|
|
|
```bash
|
|
# 方式一:IDE 直接运行 ServerPawtraceApplication
|
|
# 方式二:命令行
|
|
mvn spring-boot:run
|
|
# 方式三:打包运行
|
|
mvn clean package -DskipTests
|
|
java -jar target/server-pawtrace-0.0.1.jar
|
|
```
|
|
|
|
启动成功后:
|
|
|
|
- 接口地址: <http://localhost:8080/api>
|
|
- 接口文档: <http://localhost:8080/api/doc.html>
|
|
|
|
## 六、核心约定
|
|
|
|
### 1. 统一返回
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": { ... },
|
|
"timestamp": 1718000000000
|
|
}
|
|
```
|
|
|
|
业务码详见 [ResultCode.java](src/main/java/com/pawtrace/server/common/constant/ResultCode.java)。
|
|
|
|
### 2. 鉴权
|
|
|
|
使用 Sa-Token,前端在请求头携带 `Authorization: <token>`(由 `/auth/login` 返回)。除以下白名单外,所有接口需要登录:
|
|
|
|
```
|
|
/auth/login /auth/logout /file/**
|
|
/doc.html /swagger-ui.html /v3/api-docs/**
|
|
```
|
|
|
|
### 3. 业务约束
|
|
|
|
- 宠物上限:`MAX_PET_COUNT = 10`
|
|
- 单条日记图片上限:`MAX_DIARY_IMAGES = 9`
|
|
- 时光机视频图片上限:`MAX_TIMEMACHINE_IMAGES = 15`
|
|
- 提醒提前天数:支持 `1` / `3` / `7` 天
|
|
|
|
### 4. 数据隔离
|
|
|
|
所有业务表都带 `user_id` 字段,Service 层强制按当前登录用户过滤,严禁出现跨用户读取。
|
|
|
|
## 七、扩展指引
|
|
|
|
| 想要做的事 | 修改点 |
|
|
|------------------|----------------------------------------------------------------------------|
|
|
| 切换到 OSS | 实现 `OssService` 接口,替换 `FileController` 中的 `file.transferTo(...)` |
|
|
| 新增宠物种类 | 扩展 `Pet.species` 枚举值与 `PetGenderEnum` 等枚举 |
|
|
| 新增日记类型 | 扩展 `DiaryTypeEnum` |
|
|
| 接入实际的微信订阅消息推送 | `ReminderScheduledTask#scanUpcomingReminders` 的 `TODO` 位置,调用 `wx-java` 推送 |
|
|
| 接入管理端 | 现有接口已经支持按 userId 过滤,管理端只需另写一个 `ROLE_ADMIN` 路由 + 后台 `Controller` |
|
|
| 关闭/开启 WebSocket | `pom.xml` 已预留 `spring-boot-starter-websocket`,业务需要时编写 `WebSocket` Handler |
|
|
|
|
## 八、版本规划
|
|
|
|
- **v0.0.1(当前)**:项目骨架 + 基础 CRUD + 鉴权 + 提醒任务占位
|
|
- **v0.1.0**:微信登录接入、订阅消息推送、文件存储切换 OSS
|
|
- **v0.2.0**:管理端接口、统计接口、数据备份/恢复
|
|
- **v1.0.0**:多端同步、家庭共享(可选)
|
|
|
|
## 九、许可证
|
|
|
|
MIT License. 详见 [LICENSE](../LICENSE)(如有)。
|
|
|
|
## 十、贡献
|
|
|
|
1. Fork 本仓库
|
|
2. 在 `feature/xxx` 分支开发
|
|
3. 提交 PR 前请保证 `mvn clean compile` 通过
|
|
4. 提交信息请遵循 `feat: ...` / `fix: ...` / `docs: ...` 规范
|
|
|
|
---
|
|
|
|
> Made with ❤️ by PawTrace Team
|