# 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 为推断值）