8.7 KiB
宠迹 PawTrace · 服务端
宠物成长记录与生活管理后端项目 配套小程序:
uniapp-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 § 附录。
五、快速开始
1. 环境准备
- JDK 21+
- Maven 3.9+
- MySQL 8.x
- Redis 7.x(可选,登录态需要)
2. 初始化数据库
mysql -u root -p < src/main/resources/sql/pawtrace.sql
3. 修改配置
编辑 application-dev.yml,修改 MySQL/Redis 账号密码及 application.yml 中的微信小程序 appid/secret、OSS 配置。
4. 启动
# 方式一:IDE 直接运行 ServerPawtraceApplication
# 方式二:命令行
mvn spring-boot:run
# 方式三:打包运行
mvn clean package -DskipTests
java -jar target/server-pawtrace-0.0.1.jar
启动成功后:
六、核心约定
1. 统一返回
{
"code": 200,
"message": "操作成功",
"data": { ... },
"timestamp": 1718000000000
}
业务码详见 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(如有)。
十、贡献
- Fork 本仓库
- 在
feature/xxx分支开发 - 提交 PR 前请保证
mvn clean compile通过 - 提交信息请遵循
feat: .../fix: .../docs: ...规范
Made with ❤️ by PawTrace Team