网络请求本地日志设计

1. 目标与状态

• 目标：参照 CusumptionMachine 的网络请求日志方式，让 AIDishRecognition 的 HTTP 请求日志写入本地文件，供现场问题追溯。
• 状态：设计已确认，等待用户审阅书面设计后进入实施计划。
• 执行模式：常规 Codex；本任务是单仓库、聚焦网络拦截器的低风险改动。

2. Compact Use Case

• Use Case ID：UC-OBS-001
• 状态 / DoR：Review / READY
• 角色、触发与目标：运维或开发人员在设备发生网络问题后，通过设备本地日志查看请求 URL、参数、结果、耗时或异常原因。
• In Scope：OkHttp 请求成功和 IOException 失败日志落盘；沿用当前项目日志目录与异步写入机制。
• Out of Scope：日志上传、日志轮转与过期清理、服务端改造、网络库升级、请求重试、请求头记录、扩大请求体采集范围。
• 主流程：请求经过 RequetInterceptor，拦截器组装现有日志内容；响应成功后把完整记录异步追加到当天网络日志文件，再把原响应交给业务层。
• 边界或异常 / 恢复：连接失败、超时、DNS 或其他 IOException 发生时，记录异常类型、异常消息与失败耗时，然后原样重新抛出异常，保持现有业务失败链路不变。
• 业务规则与不应影响逻辑：本地文件写入不得消费响应体、不得改变请求或响应、不得吞掉网络异常，不改变 Retrofit 与 RxJava 回调行为。
• 验收标准：成功请求和网络异常均可在当前项目日志目录的当天网络日志文件中定位；Debug 构建和现有单元测试通过。
• 测试与证据：运行现有单元测试、Debug 构建和差异检查；真机触发成功与失败请求后检查日志文件作为人工验收。
• 性能 / 安全：不新增同步文件 I/O；沿用 LocalFileRecorder 单线程异步写入。日志不新增请求头或新的敏感字段采集。
• 待确认项：无。

3. 参考实现与当前基础

CusumptionMachine 在 RequetInterceptor 中组装请求 URL、POST 参数、响应和耗时，然后调用：

LocalFileRecorder.writeLog(
        ResourcesUtils.getStringRes(R.string.local_recorder_net_work_title),
        builder.toString());

其日志文件名前缀为 网络请求_。

AIDishRecognition 已具备以下基础：

1. CptApplication 已为全局 OkHttp 客户端注册 RequetInterceptor。
2. RequetInterceptor 已记录 URL、Form 参数、Multipart 参数、响应体和耗时。
3. LocalFileRecorder 已使用单线程执行器异步写入 应用外部文件目录/Log/；外部目录不可用时回退到内部文件目录。
4. 扫码支付专用客户端由全局客户端 newBuilder() 创建，会继承相同拦截器。

因此无需新建日志组件，也无需修改网络客户端，只需把拦截器现有记录接入本地写入工具。

4. 设计方案

4.1 文件位置与命名

继续使用当前项目 LocalFileRecorder 的目录规则：

<应用外部文件目录>/Log/网络请求_<日期>.txt

外部文件目录不可用时，保持现有逻辑回退到应用内部文件目录。新增字符串资源：

<string name="local_recorder_net_work_title">网络请求_</string>

文件名前缀通过资源读取，不在拦截器内散落硬编码。

4.2 成功请求

沿用当前日志内容与 peekBody 方式：

请求url: ...
请求方式: POST
请求参数: ...
请求结果: ...
本次请求耗时: ...毫秒

响应读取完成后调用 LocalFileRecorder.writeLog()。文件写入继续在后台单线程执行，不阻塞网络线程。

4.3 网络异常

用 try/catch 包裹 chain.proceed(request) 及响应日志组装。捕获 IOException 后追加：

请求失败: <异常类型>: <异常消息>
本次请求耗时: ...毫秒

写入本地日志后重新抛出同一个异常。该设计只增强可观测性，不改变现有错误类型、回调和界面提示。

4.4 数据边界

• 保持现有 FormBody 与 MultipartBody 参数记录能力。
• Multipart 文件只记录文件名，不读取文件二进制内容。
• 不新增请求头日志，避免把账号、密码、密钥或 Token 写入文件。
• 不扩大 JSON @Body 的采集范围；本次以对齐参考项目的本地落盘能力为目标。
• 响应体继续受当前 peekBody(1 MiB) 上限约束。

5. 影响范围

计划修改业务仓库：

• app/src/main/java/com/cpt/aidishrecognition/network/RequetInterceptor.java
• app/src/main/res/values/strings.xml

明确不修改：

• LocalFileRecorder.java 的目录、线程和文件写入实现；
• Retrofit、OkHttp 客户端创建方式；
• API 定义、请求字段与业务回调；
• 当前工作区中已有的菜品学习相关改动；
• Git 分支、暂存区和提交记录。

6. 验收与验证

6.1 自动验证

./gradlew :app:testDebugUnitTest
./gradlew :app:assembleDebug
git diff --check

6.2 人工验收

1. 在真机发起一个成功的 HTTP 请求。
2. 检查当前项目日志目录生成 网络请求_<日期>.txt。
3. 确认日志包含 URL、已有参数、响应和耗时。
4. 模拟断网、连接失败或超时，再次检查同一日志文件。
5. 确认失败记录包含异常类型、异常消息和耗时，应用仍走原有失败回调。

7. 追踪矩阵

8. 实施边界

本文档只冻结本次实现范围。书面设计经用户复核后，生成详细实施计划，再修改业务代码并补充同 basename 的 Markdown 与 HTML 变更记录。