/**
 * 优化方案文档
 * 创建时间: 2026-04-09
 * 更新时间: 2026-04-09
 * 名称: 优化方案
 * 作用: 整合审计文档中的问题和解决方案，提供清晰的优化步骤
 * 上次更新内容: 删除已完成的任务，仅保留未解决的问题
 */

# 优化方案与执行步骤

更新日期: 2026-04-09

## 概述

本文档整合了 `api_mapping_report.md`、`development_tasks.md`、`project_issues_and_plan.md` 和 `CACHE_STRATEGY.md` 中的问题和解决方案，提供清晰的优化步骤和可执行计划。
- 已完成的任务已移除，仅保留未解决的问题。

---

## 优先级 3（规划内）🎯

### 1. UI 风格统一（iOS/Cupertino 优先）

**问题描述**
- 项目要求优先 iOS/Cupertino 风格（见 AGENTS.md）
- 存在多处风格差异
- 颜色、圆角、按钮显示不统一

**影响文件**
- 全仓库 UI 相关文件

**解决方案**

#### 统一风格
- 建立主题变量（颜色、圆角、字体、间距）
- 创建 Cupertino 优先的组件库
- 重构常用组件统一样式
- 运行样式审查

**执行步骤**
1. 创建 `lib/src/theme/` 目录
2. 定义主题变量（颜色、圆角、字体、间距）
3. 创建 Cupertino 风格组件库
4. 按页面分批重构
5. 运行样式审查

**预计工时**：3-5 人日（按页面分批推进）

---

### 2. 增加集成/端到端验证脚本

**问题描述**
- 缺少 API 验证脚本
- 缺少前端关键路径的集成/端到端测试

**影响文件**
- `docs/audit/responses/`（已有样例）

**解决方案**

#### 验证脚本
- 补充 API 验证脚本（基于已保存样例）
- 在 CI/本地提供运行步骤
- 补充前端关键路径测试

**执行步骤**
1. 创建 API 验证脚本目录
2. 基于已有样例编写验证脚本
3. 添加到 CI 流程
4. 补充前端集成测试

**预计工时**：1-2 人日

---

### 3. API 相关问题

**问题描述**
- `api_preference.php` 的 `get` 返回结构需运行时确认样例
- `api_what_to_eat.php` 在 `detail`/`random` 的返回 key 变化在部分页面上存在解析差异
- `api_action.php` 需改造为 POST 并在前端处理 429 优雅降级
- 偏好格式（后端对象 vs 前端 ID）需要团队决策

**影响文件**
- `lib/src/repositories/action_repository.dart`
- `lib/src/repositories/preference_repository.dart`
- `lib/src/repositories/what_to_eat_repository.dart`

**解决方案**
1. 召开快速决策会确认偏好数据方案与写接口迁移计划
2. 实现对 `ActionRepository` 的 429 友好处理与前端 `user_id` 持久化
3. 运行端到端请求验证 API 返回结构

**执行步骤**
1. 召开 30 分钟的快速决策会
2. 基于决策实现前端改造或后端补丁
3. 实现 `ActionRepository` 的 429 退避处理
4. 运行 API 验证脚本验证返回结构

**预计工时**：1-2 人日

---

### 4. 缓存策略待实现功能

**问题描述**
- 实现 `X-Invalidate` 响应头支持
- 实现缓存统计和监控
- 实现缓存清理功能
- 实现缓存预热功能

**影响文件**
- `lib/src/services/api/api_service.dart`
- `lib/src/models/api/api_response.dart`

**解决方案**
1. 实现 `X-Invalidate` 响应头支持
2. 添加缓存统计和监控功能
3. 实现缓存清理功能
4. 实现缓存预热功能

**执行步骤**
1. 修改 `api_service.dart` 添加 `X-Invalidate` 响应头支持
2. 实现缓存统计和监控功能
3. 实现缓存清理功能
4. 实现缓存预热功能

**预计工时**：2-3 人日