feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

2026-09-12 14:25:25 +08:00
commit 39af400fc8
472 changed files with 36277 additions and 0 deletions
@@ -0,0 +1,105 @@
+# API接口大全图片方案计划
+
+## 概述
+为API接口大全的桌面端和移动端选择合适的主题封面图片，通过后端数据填充方式实现。
+
+## 当前状态分析
+
+### 后端模型
+- `ApiItem` 已有 `image_url` 字段（URLField），用于存储封面图片URL
+- `seed_api_directory.py` 已有部分 `image_url` 数据，但使用 `https://aka.doubaocdn.com/s/...` 可能不稳定
+
+### 桌面端（ApiDirectoryDesktop.tsx）
+- 已有 `getApiImageUrl()` 函数，支持三级回退：
+  1. 优先使用 `api.image_url`
+  2. 其次使用自定义映射（如百度翻译）
+  3. 最后回退到 `https://picsum.photos/seed/${api.id}/400/300`
+- 使用 Ant Design `<Image>` 组件渲染封面图，已有 `fallback` 属性
+
+### 移动端（ApiDirectoryMobile.tsx）
+- **问题**：使用硬编码本地数据，不调用后端API
+- **问题**：只显示 Ant Design 图标，没有封面图片
+- 需要改为API动态获取数据
+
+## 实施方案
+
+### 步骤1：更新种子数据（后端）
+**文件**: `chunyu_project/apidirectory/management/commands/seed_api_directory.py`
+
+为每个API选择合适的Unsplash主题封面图：
+
+| API名称 | 图片主题 | Unsplash图片URL |
+|---------|---------|----------------|
+| 天气查询 | 天空/云层 | `https://images.unsplash.com/photo-1504608524841-42fe6f032b4b?w=800&h=600&fit=crop` |
+| 空气质量指数 | 清新空气/绿色 | `https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=800&h=600&fit=crop` |
+| IP地址定位 | 地球/网络 | `https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=800&h=600&fit=crop` |
+| 二维码生成 | 科技/数字 | `https://images.unsplash.com/photo-1558591710-4b4a1ae0f04d?w=800&h=600&fit=crop` |
+| 百度翻译 | 语言/交流 | `https://images.unsplash.com/photo-1456513080510-7bf3a84b82f8?w=800&h=600&fit=crop` |
+| 文本比较 | 文档/代码 | `https://images.unsplash.com/photo-1518770660439-4636190af475?w=800&h=600&fit=crop` |
+| 图片压缩 | 图像/照片 | `https://images.unsplash.com/photo-1542038784456-1ea8e935640e?w=800&h=600&fit=crop` |
+| 短链接生成 | 链接/连接 | `https://images.unsplash.com/photo-1557682172-298e090bd0f1?w=800&h=600&fit=crop` |
+
+### 步骤2：优化桌面端图片显示
+**文件**: `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryDesktop.tsx`
+
+改进 `getApiImageUrl()` 函数：
+- 统一使用高质量图片源
+- 添加更完善的错误处理
+- 确保回退链可靠
+
+### 步骤3：移动端改为API动态获取
+**文件**: `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryMobile.tsx`
+
+重构移动端组件：
+1. 移除硬编码本地数据
+2. 添加API数据获取逻辑（调用 `api_request.apidirectory.getItems()`）
+3. 添加加载状态和错误处理
+4. 添加封面图片显示（使用与桌面端一致的图片URL处理逻辑）
+5. 保持移动端特有的UI风格（卡片式布局）
+
+### 步骤4：创建图片URL工具函数
+**文件**: `chunyu_project_react/src/utils/apiImageUtils.ts`
+
+创建统一的图片处理工具：
+- `getApiImageUrl(api: ApiItem): string` - 获取API封面图URL
+- `getFallbackImageUrl(id: number): string` - 获取备用图片URL
+- 统一桌面端和移动端的图片处理逻辑
+
+### 步骤5：更新CSS样式
+**文件**:
+- `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryDesktop.css`
+- `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryMobile.css`
+
+确保图片显示效果：
+- 图片加载中的占位符样式
+- 图片加载失败的默认背景
+- 移动端图片圆角和阴影效果
+
+## 验证步骤
+
+1. **后端验证**：运行 `python manage.py seed_api_directory` 更新数据
+2. **桌面端验证**：访问 `/api` 桌面端，检查每个API卡片是否显示正确的封面图
+3. **移动端验证**：访问 `/api` 移动端，检查：
+   - 数据是否从API动态获取
+   - 封面图片是否正确显示
+   - 加载状态和错误处理是否正常
+4. **图片回退验证**：临时修改某个API的 `image_url` 为无效URL，验证回退机制是否生效
+5. **响应式验证**：在不同屏幕尺寸下测试图片显示效果
+
+## 文件清单
+
+| 文件路径 | 操作 | 说明 |
+|---------|------|------|
+| `chunyu_project/apidirectory/management/commands/seed_api_directory.py` | 修改 | 更新image_url为Unsplash图片 |
+| `chunyu_project_react/src/utils/apiImageUtils.ts` | 新建 | 图片URL工具函数 |
+| `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryDesktop.tsx` | 修改 | 使用统一图片工具函数 |
+| `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryMobile.tsx` | 重构 | 改为API动态获取+图片显示 |
+| `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryDesktop.css` | 修改 | 优化图片样式 |
+| `chunyu_project_react/src/pages/ApiDirectory/ApiDirectoryMobile.css` | 修改 | 添加图片样式 |
+
+## 假设与决策
+
+1. **图片来源**：使用 Unsplash 免费图床，图片URL格式为 `https://images.unsplash.com/photo-{id}?w=800&h=600&fit=crop`
+2. **图片尺寸**：统一使用 800x600 尺寸，适配大多数卡片布局
+3. **回退策略**：图片加载失败时，使用 `picsum.photos` 的 seed 图片（基于API ID确保一致性）
+4. **移动端数据**：完全移除硬编码数据，统一使用后端API