# 宠迹 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