一个从 GitHub 仓库读取并浏览壁纸的 SwiftUI iOS App，App 显示名称为 Oura。
- 架构说明：页面、服务、缓存、SwiftData、并发边界和扩展约定；
- Manifest 与缩略图发布规范：源仓库目录、Schema、生成器参数、发布和回滚；
- 开发与验证指南：环境、构建、开发约定、QA 清单和 Git workflow；
- 故障排查：数据源、缓存、图片、相册、SwiftData、Xcode 和离线问题。
- 优先读取静态 manifest，旧仓库自动回退到 GitHub Tree API；
- 首页、搜索页共享同一份图片目录；
- 网格优先使用预生成缩略图，详情页使用原图；
- Kingfisher 下采样、内存缓存与磁盘缓存；
- 使用 manifest 中的真实宽高比，并使用自适应 Masonry Grid 排列；
- 支持按壁纸名称、分类和作者搜索；
- 支持下拉刷新、加载中、空列表和网络错误状态；
- 支持请求相册权限并将图片保存到系统相册；
- 支持 SwiftData 收藏夹和独立的 Favorites 页面。
最近一次成功的壁纸索引会保存到 Application Support，启动时可以先显示旧数据再后台刷新。图片本体是否能离线显示取决于 Kingfisher 磁盘缓存是否仍然存在。
- SwiftUI
- Swift Concurrency
- Kingfisher 8.8.0
- GitHub REST API
| 配置 | 当前值 |
|---|---|
| App 显示名称 | Oura |
| 最低系统版本 | iOS 18.6 |
| GitHub owner/repository | TheRealMilesLee / The-Wallpaper-Collection |
| branch | master |
| manifest URL | https://raw.githubusercontent.com/TheRealMilesLee/The-Wallpaper-Collection/master/manifest.json |
| 首页默认路径 | 2026 Wallpaper |
| 缩略图目录 | thumbnails |
| Kingfisher 内存缓存 | 100 MB |
| Kingfisher 磁盘缓存 | 1 GB，7 天过期 |
git clone https://github.com/MilesCorporate/iOS-WallpaperCollections.git
cd iOS-WallpaperCollections
open WallpaperCollections.xcodeproj项目通过 Swift Package Manager 获取 Kingfisher。壁纸数据源当前配置在
WallpaperCollections/Controller/Service.swift 中。
manifest 生成器位于 scripts/generate_wallpaper_manifest.py。它应该在壁纸源仓库的本地 checkout 上运行，并把生成的
manifest.json 和 thumbnails/ 一起提交到源仓库：
python3 -m pip install pillow
python3 scripts/generate_wallpaper_manifest.py \
--source /path/to/The-Wallpaper-Collection \
--base-url https://raw.githubusercontent.com/TheRealMilesLee/The-Wallpaper-Collection/masterApp 会从以下地址读取 manifest；如果文件不存在，会自动回退到 Tree API：
https://raw.githubusercontent.com/TheRealMilesLee/The-Wallpaper-Collection/master/manifest.json
manifest 中的 thumbnailUrl、width 和 height 让列表页避免下载原图，并消除首次布局时的比例跳动。
完整的目录约定、字段说明、发布验证和回滚流程见 docs/MANIFEST.md。
- 将 manifest 生成器接入壁纸源仓库 CI，自动发布 manifest 和缩略图；
- 为 Tree API fallback 增加 ETag 和更细粒度的重试策略；
- 增加收藏删除、批量管理和缓存清理入口；
- 增加 Service、搜索和 ViewModel 测试；
- 完成可访问性、字符串本地化和真正的收藏离线存储。
Miles (Hengyi Li)