Implement report supplement evidence flow

suixinkan/Features/WildPhotographerReport/举报摄影师接口.md

@@ -9,7 +9,7 @@
 - 网络入口：`NetworkServices.shared.wildPhotographerReportAPI`
 - 后端成功码：`100000`
 - 响应包裹：工程统一 `APIEnvelope<T>`
-- 当前状态：“举报类型”、“提交举报”和“我的举报列表”已接接口；详情、补充证据、风险地图仍使用 Mock 数据闭环。
+- 当前状态：“举报类型”、“提交举报”、“我的举报列表”、“举报详情”和“补充证据提交”已接接口；风险地图仍使用 Mock 数据闭环。
 
 ## 1. 获取举报类型
 
@@ -269,7 +269,7 @@ struct WildReportListResponse: Decodable, Equatable {
 - 切换筛选时重置为第一页，待处理传 `handle_status=0`，处理中传 `handle_status=1`，已处理传 `handle_status=2`。
 - 滚动到底部时，如果仍有更多数据，则请求下一页并追加。
 - 首屏失败显示 toast 和空态；加载更多失败只 toast，并保留已有列表。
-- 列表接口暂不返回媒体数量，`WildReportRecord.imageCount/videoCount` 暂按 0 处理，后续详情接口补齐。
+- 列表接口暂不返回媒体数量，`WildReportRecord.imageCount/videoCount` 暂按 0 处理，进入详情页后由详情接口补齐。
 
 ### 当前调用位置
 
@@ -278,12 +278,100 @@ struct WildReportListResponse: Decodable, Equatable {
 - `WildPhotographerReportListViewModel.loadMoreIfNeeded(api:scenicId:)`
 - `WildPhotographerReportAPI.reportList(_:)`
 
+## 4. 举报详情
+
+### 用途
+
+“举报详情”页面进入时调用。列表页传入 `WildReportRecord.serverID`，详情接口返回完整举报信息、现场证据、支付截图、补充内容和处理时间线。
+
+### 请求
+
+```http
+GET /api/yf-handset-app/photog/report/detail?id=32
+```
+
+### 请求参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | integer | 必填，举报记录数值 ID，来自列表接口返回的 `id` |
+
+### 关键响应字段
+
+- `complaint_no`：页面展示的举报编号。
+- `report_type` / `report_type_text`：举报类型。
+- `desc`：初始举报说明。
+- `evidences`：初始现场证据，详情页“举报人材料”区域展示。
+- `payment_screenshots`：支付截图，详情页单独展示。
+- `supplements` / `report_contents`：补充内容记录，优先使用 `supplements`，为空时从 `report_contents` 过滤 `type=supplement`。
+- `location_name` / `location_address`：详情页位置展示。
+- `handle_status` / `handle_status_text`：处理状态；iOS 支持 0 待处理、1 处理中、2 已处理、3 驳回。
+- `handle_remark`：处理备注，有值时在详情信息卡展示。
+- `timeline`：处理进度时间线；为空时使用本地状态推导兜底。
+
+### iOS 模型
+
+```swift
+struct WildReportDetailData: Decodable, Equatable, Hashable
+struct WildReportDetailEvidence: Decodable, Equatable, Hashable
+struct WildReportDetailContent: Decodable, Equatable, Hashable
+struct WildReportDetailTimelineItem: Decodable, Equatable, Hashable
+```
+
+### UI 行为
+
+- 详情页先展示列表带入的基础记录，再异步请求详情接口刷新完整数据。
+- 如果传入记录没有 `serverID`，说明来自本地提交成功页等临时记录，不请求详情接口。
+- 详情接口失败时保留现有基础信息，并 toast 错误。
+- 图片证据使用 Kingfisher 加载网络图；视频证据展示视频样式缩略块和文件信息。
+
+### 当前调用位置
+
+- `WildPhotographerReportDetailViewController.viewDidLoad()`
+- `WildPhotographerReportDetailViewModel.loadDetailIfNeeded(api:)`
+- `WildPhotographerReportAPI.reportDetail(id:)`
+
+## 5. 补充证据提交
+
+### 请求
+
+```http
+POST /api/yf-handset-app/photog/report/supplement
+```
+
+### 请求体
+
+```json
+{
+  "id": 32,
+  "desc": "补充说明",
+  "evidences": [
+    {
+      "file_url": "https://example.com/supplement.jpg",
+      "file_type": 1,
+      "file_name": "supplement.jpg"
+    }
+  ]
+}
+```
+
+### 字段说明
+
+- `id`：服务端举报 ID，必填，需大于等于 1；本地临时记录没有 `serverID` 时不允许补充提交。
+- `desc`：补充说明，选填，最多 500 字；与 `evidences` 至少填写一项。
+- `evidences`：补充附件，选填，最多 9 项；附件先通过 OSS `photog_report` 模块上传后再提交 URL。
+- `file_type`：沿用举报提交接口约定，1 图片，2 视频。
+
+### 当前调用位置
+
+- `WildReportSupplementEvidenceViewModel.submit(api:uploader:scenicId:)`
+- `WildPhotographerReportAPI.supplementReport(_:)`
+- `WildReportSupplementEvidenceViewController.submitTapped()`
+
 ## Mock 阶段业务
 
 以下业务当前仍由 `WildPhotographerReportMockStore` 和 ViewModel 本地逻辑完成，暂未接真实接口：
 
-- 举报详情
-- 补充证据
 - 附近风险地图
 - 分享、媒体预览、地图导航演示提示