صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
kym
/
haha
2
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 485eb6802c
شاخه‌ها تگ‌ها
haha
/
CLAUDE.md

CLAUDE.md 4.4 KB
تاريخچه خام

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 工作目录