# petstore-backend

宠小它 · 智慧宠物门店服务系统后端（Spring Boot 3.2 + JPA + MySQL）。

## 环境准备

### 必备

- JDK 17
- Maven 3.8+
- MySQL 5.7+ / 8.x
- FFmpeg + ffprobe（服务回顾短片生成；可选，未安装时成片功能不可用但不影响主流程）

### 环境变量

| 变量 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `MYSQL_URL` | 否 | `jdbc:mysql://127.0.0.1:3306/petstore?...` | 数据库 JDBC URL |
| `MYSQL_USERNAME` | 否 | `root` | 数据库用户名 |
| `MYSQL_PASSWORD` | **是** | 空 | 数据库密码 |
| `WECHAT_APPID` | 生产必填 | 空 | 微信小程序 AppID |
| `WECHAT_APPSECRET` | 生产必填 | 空 | 微信小程序 AppSecret |
| `WECHAT_REDIRECT_URI` | 否 | `http://localhost:8080/api/wechat/callback` | 微信回调 |
| `PETSTORE_SESSION_SECRET` | **生产必填** | `dev-change-me` | HMAC session token 签名密钥；改密会使所有已签发 token 立即失效 |
| `PETSTORE_SESSION_TTL_SECONDS` | 否 | `604800`（7 天） | session token 有效期 |
| `APP_BASE_URL` | 生产必填 | `http://localhost:8080` | 后端对外可访问 base URL（用于生成媒体绝对 URL） |
| `UPLOAD_PATH` | 否 | `/www/petstore/uploads` | 上传目录绝对路径 |
| `HIGHLIGHT_FFMPEG` | 否 | `ffmpeg` | ffmpeg 可执行路径 |
| `HIGHLIGHT_FFPROBE` | 否 | `ffprobe` | ffprobe 可执行路径 |
| `HIGHLIGHT_MAX_DURATION_SEC` | 否 | `300` | 成片最大总秒数 |
| `HIGHLIGHT_BGM_PATH` | 否 | 空 | 商用授权 BGM 绝对路径；留空不混音 |
| `SMS_UNIVERSAL_CODE` | **生产必须为空** | `123456`（dev）/ 空（production） | 演示万能验证码；production profile 自动关闭 |
| `JPA_DDL_AUTO` | 否 | `update`（dev）/ `validate`（production） | JPA DDL 模式 |
| `JPA_SHOW_SQL` | 否 | `false` | SQL 日志 |
| `LOG_LEVEL_PETSTORE` | 否 | `info` | `com.petstore` 包日志级别 |

> ⚠️ **密钥轮换**：`application.yml` 历史版本曾提交过真实 DB 密码与微信 AppSecret。这些凭据已在仓库历史中暴露，**必须按安全流程轮换**：改 DB 密码、重置微信 AppSecret、更换 `PETSTORE_SESSION_SECRET`。

## 本地开发

```bash
# 1. 准备本地 MySQL，创建数据库
mysql -uroot -p -e "CREATE DATABASE petstore DEFAULT CHARSET utf8mb4"

# 2. 配置环境变量（或复制 application-example.yml 为 application.yml 并填写）
export MYSQL_PASSWORD=your_local_password

# 3. 启动
mvn spring-boot:run

# 4. 验证
curl http://localhost:8080/api/store/list
```

## 数据库迁移

⚠️ **生产库变更必须走 SQL/Flyway/Liquibase 或人工审核 SQL，禁止依赖 `ddl-auto:update` 自动改表**。

### P0 稳定化批次迁移要点

1. **`uk_report_appointment` 唯一约束上线前需清理重复 `appointment_id`**：
   ```sql
   -- 检查是否存在重复
   SELECT appointment_id, COUNT(*) c FROM t_report WHERE deleted = 0 GROUP BY appointment_id HAVING c > 1;
   -- 清理：保留最新一条，其余软删
   -- （具体清理 SQL 由 DBA 按数据情况编写）
   ```
   清理后再启动应用，让 JPA `ddl-auto:update` 创建唯一约束；否则应用启动会失败。

2. **历史图片 URL 修复**（旧版启动期自动执行，现已移除）：
   ```sql
   UPDATE t_report SET before_photo = REPLACE(before_photo, 'http://localhost:8080/2026/', '/api/upload/image/2026/') WHERE before_photo LIKE 'http://localhost:8080/2026/%';
   UPDATE t_report SET after_photo  = REPLACE(after_photo,  'http://localhost:8080/2026/', '/api/upload/image/2026/') WHERE after_photo  LIKE 'http://localhost:8080/2026/%';
   ```
   仅需在生产库执行一次；dev 库若无历史数据可跳过。

3. **`t_report.appointment_id` 列**：P0 口径要求报告必须绑定预约，但历史 DDL 曾将该列改为 `NULL`。新环境由 JPA 实体 `@UniqueConstraint` 创建约束；老环境若该列允许 NULL 且无重复，可直接加唯一约束。

4. **预约/报告身份字段拆分**：升级到 2026-08-01 之后的版本前，生产库必须先执行：
   ```bash
   mysql -h <host> -u <user> -p petstore < db/migrations/20260801_split_service_identity.sql
   ```
   脚本新增 `customer_user_id`、`created_by_user_id`、`author_staff_id` 并回填可确定的历史数据。末尾三个验证查询必须留档；`unresolved_assisted_appointments` 非 0 时需人工确认，禁止把旧员工 `user_id` 冒认成客户。

5. **门店客户主档**：身份拆分验证完成后，紧接着执行：
   ```bash
   mysql -h <host> -u <user> -p petstore < db/migrations/20260801_create_store_customer.sql
   ```
   脚本创建 `t_store_customer`，从预约和报告留资回填本店客户关系。末尾 `appointments_without_store_customer`、`leads_without_store_customer`、`store_customers_linked_to_non_customer` 必须全部为 0。

6. **业务事件落库**：客户主档验证完成后执行：
   ```bash
   mysql -h <host> -u <user> -p petstore < db/migrations/20260801_create_business_event.sql
   ```
   脚本创建不可变 `t_business_event` 并回填可确认的历史事实。末尾四个验证计数必须全部为 0；报告打开和服务开始没有可靠历史数据，不做猜测性回填。

### production profile

```bash
java -jar petstore-backend.jar --spring.profiles.active=production
```

production profile 下：
- `ddl-auto=validate`（只校验，不改表）
- `show-sql=false`
- `SMS_UNIVERSAL_CODE` 默认空（关闭万能验证码）

## 测试

```bash
mvn test
```

最小测试基线（P0 稳定化批次）：
- `SessionTokenServiceTest`：签发/校验/篡改/过期
- `ReportServiceTest`：appointmentId 必填、重复报告、doing→done
- `ReportControllerTest`：公开字段裁剪、照片必填业务码、重复报告业务码
- `AppointmentServiceTest`：状态机非法迁移

## RC 发布门禁

发布前必须依次执行并全部通过：

```bash
# 1. FFmpeg 可用
ffmpeg -version
ffprobe -version

# 2. 上传资源可访问（替换 <known-file> 为已上传的测试文件）
curl -I "$APP_BASE_URL/api/upload/image/<known-file>"
# 期望：HTTP/1.1 200

# 3. 后端测试
mvn -f backend/pom.xml test
# 期望：BUILD SUCCESS，且不再输出 "No tests to run"

# 4. 前端构建（见 frontend/README.md）
npm --prefix frontend install
npm --prefix frontend run build:h5
npm --prefix frontend run build:mp-weixin
```

### RC 检查项

- [ ] `APP_BASE_URL` 已配置且后端可生成可访问媒体 URL
- [ ] `PETSTORE_SESSION_SECRET` 已通过环境变量覆盖（非 `dev-change-me`）
- [ ] `MYSQL_PASSWORD` / `WECHAT_APPSECRET` 等敏感项通过环境变量注入，未硬编码
- [ ] `HIGHLIGHT_FFMPEG` / `HIGHLIGHT_FFPROBE` 指向可用二进制
- [ ] `HIGHLIGHT_MAX_DURATION_SEC` / `HIGHLIGHT_BGM_PATH` 按运营配置
- [ ] 上传目录 `UPLOAD_PATH` 存在且进程有读写权限
- [ ] Nginx `client_max_body_size` ≥ 200MB（与 `spring.servlet.multipart.max-file-size` 一致）
- [ ] 启动使用 `--spring.profiles.active=production`
- [ ] `uk_report_appointment` 唯一约束上线前已清理重复数据
- [ ] 历史图片 URL 已执行一次性修复 SQL
- [ ] 已执行 `20260801_split_service_identity.sql`，并留存未解析预约/报告验证结果
- [ ] 已按顺序执行 `20260801_create_store_customer.sql`，三项主档验证计数均为 0
- [ ] 已执行 `20260801_create_business_event.sql`，四项事件回填验证计数均为 0
- [ ] 已暴露凭据（DB 密码、微信 AppSecret）已轮换

## 安全说明

- **最小鉴权上下文**：HMAC session token（`SessionTokenService`）+ `AuthInterceptor`，不引入完整 Spring Security。
- **公开接口白名单**：见 `AuthInterceptor.PUBLIC_PATTERNS`；其余 `/api/**` 要求 `Authorization: Bearer <token>`。
- **跨店/跨用户边界**：所有 protected 接口从 `CurrentUserContext` 派生 `userId/storeId/role`，不信任请求体里的身份字段。
- **公开报告页**：`GET /api/report/get?token=` 不返回 top-level `userId/storeId/reportToken`；日志只记 token SHA-256 前 8 位 hash。
- **回访池脱敏**：`/api/report/leads` 不返回完整 `wechatOpenid/wechatUnionid`，只返回 `wechatBound` + 脱敏 id。
- **上传路径保护**：`FileController` 归一化路径 + 扩展名/MIME 校验，拒绝 `..` 逃逸。

## 参与贡献

1. Fork 本仓库
2. 新建 `feat_xxx` 分支
3. 提交代码（使用 conventional commits：`feat` / `fix` / `chore` / `docs` / `refactor` / `test`）
4. 新建 Pull Request