shop-java/接口实现进度-第2批.md

Java 后端接口实现进度（第 2 批）

对照基准：线上 PHP 站点 https://shop.qinys.cn（同一套库、同一份数据） 校验方式：逐个接口抓 PHP 黄金样本 → Java 同参数请求 → 递归逐字段 diff（tools/compare_batch.py） 最近一次运行：28 个接口全部 PASS，0 差异

一、本次修复：/store/store/info 报 500

根因：该路由此前没有实现。Spring 找不到处理器时抛 NoResourceFoundException，被全局异常兜底成 {"status":500,"message":"服务器内部错误"}，前端只看到 500，无法判断是"没实现"还是"真报错"。

修复：

1. 新增 StoreController（/store/store/info、/store/store/update），出参与 PHP Store::info 一致： {"storeInfo":{...,"logoImage":null}}。
2. GlobalExceptionHandler 增加 NoResourceFoundException 专门处理，未实现的路由现在返回 {"status":500,"message":"接口未实现：/store/xxx/yyy"}，一眼能定位。

注意路由规则：PHP 的 URL 是「模块 + 控制器 + 方法」，所以前端 api/store/store/info 对应 Java 的 /store/store/info（第一个 store 是模块，第二个是控制器 Store.php）； 多级控制器写成点号，如 /store/goods.service/list、/store/store.menu/list。

二、本次新实现并通过 0 差异校验的接口

接口	说明
GET /store/store/info	商城信息（含 logoImage）
POST /store/store/update	更新商城信息
GET /store/store.menu/list	后台菜单树（含 menuApi / apiIds，过滤空操作菜单）
GET /store/store.role/list	角色树（含 roleMenu / menuIds）
GET /store/store.user/list	管理员列表（含 role / roleIds）
GET /store/category/list	商品分类树（含 image / children）
POST /store/category/add\|edit\|delete	分类增删改（含"上级不能设为自己子级""被商品引用不能删"校验）
GET /store/goods.service/list\|all	商品服务（保障服务）
POST /store/goods.service/add\|edit\|delete	商品服务增删改（软删除）
GET /store/files/list	文件库列表（类型/分组/来源/回收站筛选，15 条分页）
GET /store/files.group/list	文件分组树
POST /store/files.group/add\|edit\|delete	分组增删改（删组时文件归还"未分组"）
POST /store/files/edit\|delete\|moveGroup	文件改名/批量删除（≤15）/移动分组
GET /store/region/all	全部地区（约 240KB，key 为地区 ID）
GET /store/region/tree	地区树（省→city→region）
GET /store/user/list	会员列表（昵称/手机号/性别/等级/注册时间筛选）
GET /store/user.grade/all\|list	会员等级（upgrade / equity 由 JSON 串转对象）
GET /store/order/list?dataType=	订单列表（paginate(10)，7 种 dataType，6 种关键词检索）
GET /store/order/detail	订单详情（goods / user / address / trade）
GET /store/setting/detail	设置项（无该项时 values: []）
POST /store/setting/update	更新设置项
GET /store/setting.cache/items	缓存清理项
GET /store/setting.delivery/all\|list	配送模板
GET /store/setting.express/all\|list	物流公司
GET /store/setting.printer/all\|list	打印机
GET /store/store.address/all\|list	商城地址（cascader / region / full_address）
GET /store/page/list	页面列表（不含 page_data 长文本）
GET /store/content.article/list	文章列表（不含 content，含 image / category）
GET /store/content.article.category/list	文章分类
GET /store/content.help/list	帮助列表
GET /store/market.coupon/list	优惠券列表
GET /store/market.points/log	积分明细（含会员）
GET /store/market.recharge.plan/list	充值套餐
GET /store/user.balance/log	余额明细（含会员）

三、本批踩到的"出参差异坑"（已在代码里注释）

现象	处理
PHP 关联字段名是 camelCase（logoImage、menuApi、roleMenu、menuIds、roleIds、apiIds）	Jackson 全局 SNAKE_CASE 会把它们变成 logo_image，逐个加 @JsonProperty("xxxYyy")
菜单无 api 绑定时 PHP 输出 "apiIds": []、"menuApi": []	关联设为空 List，不用 null
订单 update_price 是对象 {symbol,value}	用 getUpdatePriceVo() 组对象
订单 pay_time/delivery_time/receipt_time 为 0 时输出 ""	TimeUtil.formatOrBlank()（对齐 PHP format_time()）
订单 order_source_data 库内是 json 串，出参是数组	出参时 JSON 解析，空串返回 []
订单/流水里的 user 只 with 了 avatar，没有 grade 键	UserLiteSerializer 序列化后剔除 grade
订单商品 content 列表不返回	查询排除 + @JsonInclude(NON_NULL)
yoshop_store_setting 主键是字符串 key	@TableId(value="key", IdType.INPUT)，更新走条件更新

四、尚未实现的接口（下一批）

按页面优先级排序：

1. 商品新增/编辑：goods/add、goods/edit、goods/delete、goods/state、goods/basic、goods/list_by_ids
2. 订单操作：order.event/*（确认取消、改价、改地址、备注、打印）、order.refund/*、order.delivery/*
3. 文件上传：upload/image、upload/video（需要落盘 + 写 yoshop_upload_file）
4. 设置-支付：setting.payment/options、setting.payment.template/*
5. 统计：statistics.data/survey、statistics.data/initialize
6. CRUD 补齐：文章/帮助/优惠券/充值套餐/页面/配送模板/物流公司/打印机/角色/管理员的 add|edit|delete
7. API 级权限：PHP 的 checkPrivilege()（按角色校验 store_api），当前只校验登录态

五、怎么跑

# 后端
cd F:\shop\java-rewrite\yoshop-java
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=18080 --yoshop.auth.mode=file --yoshop.auth.runtime-cache-path=F:/shop/java-rewrite/runtime/cache"

# 前端
cd F:\shop\yoshop2.0-store
NODE_OPTIONS=--openssl-legacy-provider ./node_modules/.bin/vue-cli-service serve   # 8120

# 回归对比（需本地 Java 服务 + golden 样本）
cd F:\shop\java-rewrite\tools
python compare_batch.py

本机有系统代理（HTTP_PROXY=127.0.0.1:xxx），会让 127.0.0.1 也走代理并返回 502， 联调脚本里已用 trust_env = False；手工 curl 记得加 --noproxy '*'。