接口实现进度-第8批.md 8.9 KB
第 8 批接口实现进度：客户端设置、评论、导出、统计与打印（15 个，收官）
时间：2026-10-17 进度：151 个接口已全部实现，剩余 0（
tools/check_progress.py复核：PHP 151 / Java 151 / 待实现 0） 验证：读接口 26/26 零差异、写接口 21/21 断言全通过；订单 10/10、设置 13/13、营销 6/6 回归全 PASS
一、本批 15 个接口
| 分组 | 接口 | 方法 | 说明 |
|---|---|---|---|
| 客户端设置 | /store/client.h5.setting/detail |
GET/POST | resetOptions 合并默认，未知 key 返回 [] |
/store/client.h5.setting/update |
POST | 先 update 后 insert（有则改、无则插） | |
/store/client.wxapp.setting/detail |
GET/POST | 额外返回 domain（去端口） |
|
/store/client.wxapp.setting/update |
POST | 仅落库 4 个白名单字段 | |
| 商品评论 | /store/goods.comment/list |
GET/POST | join 商品/订单子查询，page 15 |
/store/goods.comment/detail |
GET/POST | 含 images / imageIds / imageList | |
/store/goods.comment/edit |
POST | 先删后插 comment_image，同步 is_picture | |
/store/goods.comment/delete |
POST | 软删除 | |
| 订单导出 | /store/order.export/list |
GET/POST | 导出记录分页 |
/store/order.export/exportOrder |
GET/POST | 生成 xlsx + 落导出记录（兼容 export_order） |
|
| 统计 | /store/statistics.data/data |
GET/POST | overview + tradeTrend + goodsRanking + userExpendRanking |
/store/statistics.data/survey |
GET/POST | 6 项指标，支持起止时间 | |
/store/statistics.data/initialize |
GET/POST | 空响应体（void） | |
| 其他 | /store/controller/initialize |
GET/POST | 空响应体（void） |
/store/order.event/printer |
POST | 小票打印（飞鹅 / 365 两种驱动） |
二、新增/改动文件
实体：CommentImage（新增）；Comment 补 user/orderGoods/imageIds/imageList/images；
H5Setting、WxappSetting、OrderExport（新增，主键与保留字列均加反引号映射）。
Mapper：CommentImageMapper、H5SettingMapper、WxappSettingMapper、OrderExportMapper（新增）；
OrderGoodsMapper 新增 goodsRanking()（销量 Top10，@Select 手写 SQL）。
服务：CommentService、ClientSettingService、StatisticsService、OrderExportService、PrinterService（新增）。
控制器：GoodsCommentController、ClientH5SettingController、ClientWxappSettingController、
StatisticsController、StoreBaseController、OrderExportController（新增）；OrderEventController 增 printer。
改造：OrderService 抽出 buildQuery，新增 listAll（导出不分页）与 findAssembled（打印）；
BizException 增 silent 工厂 + GlobalExceptionHandler 对应分支；
WebMvcConfig 加 /downloads/** 静态映射与 yoshop.export-path；pom.xml 加 poi-ooxml 5.4.1。
工具脚本：seed_comment_golden.py（评论种子，支持 --cleanup）、
compare_final_batch.py（26 读用例）、test_final_writes.py（21 写断言，含 Excel 逐格对比）。
三、双跑验证结果
读接口 compare_final_batch.py：26/26 PASS
| 分组 | 用例数 | 覆盖 |
|---|---|---|
| 评论列表 | 11 | 无参 / 分页 / goodsId / orderNo / userId / status / score / 组合 / 空结果 |
| 评论详情 | 4 | 正常 / 含图 / 软删除记录 / 不存在报错 |
| H5 设置 | 2 | 默认合并 / 未知 key |
| 小程序设置 | 2 | 含 domain / 默认值 |
| 导出列表 | 1 | 分页结构 |
| 统计 | 4 | data / survey 无参 / 带区间 / 反向区间 |
| initialize | 2 | 两个接口空响应体 |
写接口 test_final_writes.py：21/21 PASS（PHP 跑 → 采样 → 复位 → Java 跑 → 采样 → 对照）
- 评论编辑：改分数/内容/状态/排序 + 换图（先删后插，comment_image 行 id 递增但内容一致）；
- 评论清空图片：
is_picture由 1 → 0； - 评论软删除：
is_delete=1，列表与详情同步消失； - 缺失记录报错文案：
Call to a member function edit() on null/setDelete() on null； - H5 设置：首次新增 + 二次覆盖，库内 JSON 字节完全一致；
- 小程序设置：4 字段白名单落库一致（多余字段被丢弃）；
- 订单导出：Excel 单元格逐格完全一致（28 列 × N 行，含商品明细多行文本与「元」后缀）；
- 导出 betweenTime：
start_time/end_time落库一致、文件名时间戳归一化后一致； - 打印：打印机不存在、驱动调用失败（真实请求飞鹅接口返回「参数错误 : 该帐号未注册.」）两端一致。
回归（本地 PHP 源）：订单 10/10、设置 13/13、营销 6/6，全部 PASS。
四、七个关键对齐点
renderError与throwError的 data 结构不同：打印失败走renderError，PHP 返回{"status":500,"message":"...","data":[]}；而多数业务异常走throwError，data 是{"isPrompt":true}。 Java 侧新增BizException.silent()（不置 prompt 标志）+ 全局处理器分支返回new Object[0]， 否则前端data.isPrompt判断会走错分支。- 统计口径三处易错：
consumeUsers的 PHP 是group('user_id')->count()——分组行数， 不是count(*)也不是count(user_id)，等价 SQL 是count(distinct user_id)； 计数类走number_format（千分位字符串），金额类走helper::number2（两位小数）， 两者都是字符串出参，不是数字。 - 导出字典即列序：PHP
Export::dictionary()用LinkedHashMap语义， Excel 列顺序必须与字典顺序一致（28 列），不能按实体字段顺序生成。 单元格值一律\t值\t包裹，金额加「元」，商品明细是「1.商品名称：…\n 商品规格：g: v; \n…」的多行模板， - H5/小程序设置落库要复刻 PHP
json_encode字节：PHP 默认转义/与非 ASCII（\uXXXX）。 通用 Jackson 配置产出的 JSON 字节不同，虽然语义一样但会导致「落库不一致」。 已建专用PHP_JSON（ESCAPE_NON_ASCII）+.replace("/", "\\/")，实测字节完全一致。 - 小程序
domain去端口：PHP$request->host(true)第二参为 true 时不带端口； JavagetServerName()也不带端口，但为兼容反向代理场景仍统一replaceAll(":\\d+$", "")。 - 未知 setting key 的两种行为：
detail传未知 key 时 PHP 走resetOptions后返回空数组[]（不报错）； 而update里取describe[$key]会抛Undefined array key。两处分支不能合并。 - 打印驱动的错误透传：PHP 是
$result['msg'] ?: '操作失败'，业务失败也返回 200 之外的 status=500， 但 message 用驱动原文。Java 侧BizException.silent(error != null ? error : "操作失败")复刻。
五、整体交付状态
| 指标 | 数值 |
|---|---|
| PHP 接口总数（store 模块） | 151 |
| Java 已实现 | 151（100%） |
| 控制器 | 43 个 |
| 服务 | 30 个 |
| 读接口双跑对比 | 累计 26 + 60 + 13 + 10 + 7 + 6 ≈ 122 项，0 差异 |
| 写接口断言 | 累计 21 + 118 + 66 + 77 + 42 + 62 + 38 + 24 ≈ 448 项，全通过 |
自动化脚本（tools/）：check_progress.py 盘点进度、compare_*.py 双跑对比、
test_*_writes.py 写接口对照、seed_*_golden.py 造数、backup_*.py 测试前备份。
六、仍未接入的能力（切流前必须补）
checkPrivilege角色权限校验——当前所有 store 接口只校验登录态（token），未按yoshop_store_role_menu做接口级鉴权，这是切流前的第一优先级；- 微信小程序发货信息上报（
OrderDeliveryService内留空）； - 第三方支付（微信/支付宝）退款接口调用；
- 阿里云物流轨迹驱动（当前只落库物流单号，不拉轨迹）；
- 微信支付 V3 平台证书自动下载（现依赖手工放置证书）。
七、测试数据清理与环境还原
- 删除
yoshop_order10099（TESTORDER10099）、yoshop_printer10001、yoshop_comment10001–10004 及yoshop_comment_image3 条、yoshop_order_export3 条； 复核：订单表回到原始 2 条（10001/10002），其余 4 张表归零。 - 删除导出产物：
F:/shop/shop/public/downloads/10001/*.xlsx、yoshop-java/runtime/downloads/10001/*.xlsx。 F:/shop/shop/.env已按原字节还原（备份/tmp/yoshop_env_backup.txt，即 localhost/test）。- 本地 PHP 站点（127.0.0.1:8899，PHP 8.2 便携包）已关闭；PHP 8.2 目录保留在
C:/Users/Administrator/AppData/Local/Temp/php82/，需要再跑双端对比时可直接复用。 - Java 服务（18080）启动命令保持不变：
mvn -q -o -DskipTests spring-boot:run -Dspring-boot.run.arguments="--server.port=18080 --yoshop.auth.mode=file --yoshop.auth.runtime-cache-path=<...>/runtime/cache"。