# CLAUDE.md — 哈哈智能零售系统

## 项目概览

基于 Spring Boot 的 AI 智能视觉售卖机系统，包含用户端小程序、管理后台、硬件通信等模块。

### 技术栈
- **后端**: Java 21, Spring Boot 4.0.3, MyBatis-Plus 3.5.16
- **前端**: Vue 3 + Element Plus (admin-web), uni-app (mp)
- **数据库**: MySQL, Redis
- **服务端口**: miniapp 7077, admin 7070
- **支付**: 微信支付 JSAPI + 支付分 (Pay Score)

### 模块结构
```
haha-parent
├── haha-common    — 公共工具、枚举、VO
├── haha-entity    — 实体类、DTO
├── haha-mapper    — MyBatis Mapper
├── haha-service   — 核心业务逻辑（回调处理、支付、订单、库存等）
├── haha-miniapp   — 用户端小程序后端 (port 7077)
├── haha-admin     — 管理后台后端 (port 7070)
├── haha-sdk       — 哈哈平台 SDK (API调用、Token管理)
├── qdb-sdk        — 千岛板 SDK
├── haha-mp        — 用户端小程序前端 (uni-app)
├── haha-admin-web — 管理后台前端 (Vue 3)
└── haha-admin-mp  — 管理端小程序
```

## 哈哈平台回调流程

### 两类回调
| 回调 | 路径 | 作用 |
|------|------|------|
| ORC_RESULT | `/api/callback/haha/message` (notify_type=ORC_RESULT) | AI 识别结果，触发订单创建 |
| ORDER | `/api/callback/haha/order` | 设备端报价，写入金额 |

### 订单创建时序
```
1. 用户开门 → preCreatePayScoreOrder (微信支付分预授权) → 存 Redis (TTL 10min)
2. AI识别完成 → ORC_RESULT 回调 → 创建订单 + 关联支付分 → 清理Redis
3. 设备报价 → ORDER 回调 → validateSign → 写入 totalAmount/paidAmount
4. 消息推送 → 用户确认付款
```

### 签名验证 (重要!)
- 哈哈平台使用 **MD5(signStr + ticket)** 签名
- 签名原文: 参数按 key 排序，值 URL 编码后 `key=value&...` 拼接，末尾直接拼接 ticket
- ⚠️ **不能使用 Spring `@RequestParam` 解析后的参数重建签名!** Spring 会 URL-decode，Java `URLEncoder` 重新 encode 的结果与 PHP 原始 `urlencode` 不一致
- **必须从原始 request body 构建签名** → `buildSignContentFromRawBody()`
- 见 `HahaCallbackServiceImpl.java:620` 的 `validateSign(params, rawBody)` 方法

### 支付分关键限制
- 同一实名用户 **进行中订单 ≤ 3 笔** (微信硬限制)
- 超过 3 笔 → 用户无法扫码开门 (错误: "同一实名身份下进行中订单过多")
- 分级清理策略 (见 `PayScoreServiceImpl.cancelStalePayScoreOrdersAndCount`):
  1. 自动补扣: 有金额的待支付订单 (>1min)
  2. 取消 CREATED: 用户从未确认
  3. 清理超时孤儿: DOING/USER_PAYING + 无金额 + >30min
  4. Redis 追踪清理

### 支付分完结金额校验
- 微信要求 `total_amount == sum(post_payments[].amount)` 严格相等
- DB 中单价保留 2 位小数，乘数量后求和可能产生 **1 分钱差额**
- 解决方案: `buildPostPayments(orderId, totalAmount)` 自动平账到末项

### 日志路径
- miniapp: `./logs/haha-miniapp/haha-miniapp.log`
- admin: `./logs/haha-admin/haha-admin.log`
- JVM 工作目录 `/home/kym/application` (服务器)
- prod 环境: logback-spring.xml 同时输出 CONSOLE + FILE

## 关键文件索引
| 文件 | 功能 |
|------|------|
| `HahaCallbackServiceImpl.java` | 回调处理: 签名验证、订单创建、支付分完结 |
| `PayScoreServiceImpl.java` | 支付分: 预授权、创建、完结、取消、限额清理 |
| `OrderServiceImpl.java` | 订单: CRUD、支付分集成、库存扣减 |
| `CallbackController.java` | 回调入口 (miniapp 7077) |
| `OrderController.java` | 管理后台订单接口 (admin 7070) |
| `RequestParseUtil.java` | 请求解析 (JSON/XML/Form) |
| `HahaClient.java` | 哈哈平台 SDK (Token/Ticket管理) |

## 常见故障排查
| 现象 | 原因 | 解决方案 |
|------|------|---------|
| 订单有商品无金额 | ORDER 回调签名失败 | 检查签名日志，修复后用 SQL 补齐 |
| 支付分补扣失败 PARAM_ERROR | post_payments 总额 ≠ total_amount | 已修复自动平账 |
| 支付分补扣失败 REVOKED | 新支付分订单创建导致旧单被撤销 | 新流程自动清理+前端拦截 |
| 用户无法开门 | 进行中订单 ≥ 3 笔 | `cancelStalePayScoreOrdersAndCount` 自动清理 |
| 日志文件找不到 | 路径配错或权限问题 | 检查 `logging.file.path` 和 JVM 工作目录 |