feat: 完成9.7线下收款登记与日清

2026-08-26 09:53:48 +08:00
parent dca4bd5a20
commit 825a0448cc
24 changed files with 2663 additions and 6 deletions
@@ -0,0 +1,53 @@
+# 9.7 线下收款接口调整
+
+本次仅调整以下两个接口，路径保持不变：
+
+- `GET /api/yf-handset-app/photog/offline-pay-collect/statistics`
+- `GET /api/yf-handset-app/photog/offline-pay-collect/details`
+
+## 1. statistics
+
+请求：`scenic_id`
+
+在现有 `pending` 中增加所有未补缴日期，按日期升序：
+
+```json
+"dates": [
+  { "date": "2026-08-23", "unpaid_amount": "230.00", "unpaid_count": 2 }
+]
+```
+
+- 包含今天及历史所有仍有待补缴数据的日期。
+- `date_count`、待补缴总金额和总笔数必须与 `dates` 汇总一致。
+- `today.date` 按 `Asia/Shanghai` 返回当前营业日，客户端以此限制未来日期。
+
+## 2. details
+
+请求改为：`scenic_id + date`，删除 `page/page_size`。
+
+`data` 直接返回单日对象：
+
+```json
+{
+  "date": "2026-08-24",
+  "total_amount": "350.00",
+  "collect_count": 3,
+  "paid_amount": "100.00",
+  "paid_count": 1,
+  "unpaid_amount": "250.00",
+  "unpaid_count": 2,
+  "status": 0,
+  "status_text": "本日未结清",
+  "collects": []
+}
+```
+
+- 无数据日期也返回成功、零值汇总和空 `collects`。
+- 明细按登记时间倒序，再按 `collect_no` 保证稳定顺序。
+
+## 不调整的接口
+
+- `POST /register`：继续只接收 `scenic_id/amount/pay_method`，响应保持现状。
+- `POST /supplement`：继续只接收 `scenic_id/date`，响应保持现状。
+
+客户端不会向这两个接口传入 `request_id`、补缴金额快照或补缴笔数快照，也不依赖新增错误码。