shop-java/yoshop-java

yoshop-java：萤火商城 2.0 Java 重写版

对齐目标：F:\shop\shop（ThinkPHP 6.1.5，约 4.45 万行）。核心原则：不改任何前端代码即可切换后端。

对齐基线

• ../API清单.md / ../API清单.csv：全部 253 个接口（store 151 / api 74 / admin 24 / timer 4），由 ../tools/extract_api.py 自动扫描生成。

必须遵守的接口契约

约定	内容
响应体	{"status":200,"message":"success","data":{...}}，业务成败看 status，HTTP 恒为 200
状态码	200 成功 / 401 未登录 / 403 无权限 / 500 错误（对齐 config/status.php）
分页	data.list = {total, per_page, current_page, last_page, data:[...]}，snake_case；页码越界时 current_page 夹到 last_page
认证	请求头 Access-Token；登录态存 ThinkPHP File 缓存（runtime/cache），格式见下文「认证」
时间	yyyy-MM-dd HH:mm:ss，东八区
软删除	is_delete（10=正常 / 30=删除，以模型为准逐表核对）
枚举	状态值用 10/20/30 数字（如订单 status、支付 trade_status），禁止自创枚举值

包结构（对齐 PHP 模块）

cn.yoshop
├── common      ← app/common（实体、业务 service、library）
├── admin       ← app/admin（平台后台，24 个接口）
├── store       ← app/store（商家后台，151 个接口，重头）
├── client      ← app/api（H5+小程序，74 个接口）
├── timer       ← app/timer（定时任务，用 @Scheduled 替代）
└── config

实施顺序建议（由简到难）

1. 基础层：R / Status / 异常 / 分页 / 认证拦截器（本骨架已含前四项）
2. 只读接口：store 端商品、订单列表查询（不写库，风险最低）
3. 后台 CRUD：商品/分类/规格管理
4. 订单链路：下单 → 库存锁定 → 支付回调（验签+幂等，重点测试）→ 发货
5. 小程序端 api（依赖登录态与微信 SDK，WxJava）
6. 定时任务 + 队列（@Scheduled / RabbitMQ），最后切流量

认证（已实现）

请求头 Access-Token
  → md5(token) → {runtime}/cache/{前2位}/{后30位}.php
  → 文件头 32 字节（"<?php
//" + 12位过期时间戳 + "
 exit();?>
"）+ PHP serialize 数据

StoreAuthInterceptor 校验登录态，白名单 passport/login、passport/logout、map/transfer， 失败返回 {"status":401,"message":"请先登录后再访问","data":{"isPrompt":true}}。

配置 yoshop.auth.mode："off" 开发/双跑放行；"file" 真实校验（需与 PHP 同机或目录可见）。 注意必须带引号，裸 off 会被 YAML 解析成布尔 false。

列表 / 详情出参分离

详情多出的 skuList/video/videoCover/categoryIds/serviceIds/isSpecLocked/specList/content 用 @JsonView(Views.Detail.class) 标注，列表接口用 @JsonView(Views.List.class)。 需 spring.jackson.mapper.default-view-inclusion: true，否则未标注字段会被全部排除。

双跑对比验证

PHP 与 Java 同时在线（Nginx 按比例分流），用脚本对同一请求双发、diff 响应 JSON；API清单.csv 可直接生成冒烟用例清单。

待核对项（骨架中已标注 TODO 语义）

• 数据库名与连接串（application.yml 已填内网 shop 库）
• is_delete 各表实际取值
• checkPrivilege（API 级权限）尚未实现：PHP 按角色查 store_api 表，Java 端只校验登录态，上线前需补齐
• 多级控制器 URL 的点号写法是否与前端调用一致（API清单.md 中 URL 为推断值）