# qycl

**Repository Path**: yaxy1234/qycl

## Basic Information

- **Project Name**: qycl
- **Description**: AI辅助编程的菜谱APP（Android端）
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 岂柚此梨（Android 个人菜谱 App）

一个完全跑在**手机本地**的个人菜谱管理应用：添加、分类、收藏、搜索、随机推荐自己的菜谱，**不需要联网、不依赖任何后台服务器**，所有数据存在 App 自带的本地数据库里。

> 包名：`com.example.qycm`
> 适用：想随手记菜谱、按分类查找、偶尔「今天吃什么」随机抽一道的人。

---

## 一、功能一览

| 模块 | 说明 |
|---|---|
| 首页 | 全部菜谱列表，支持按分类 / 收藏筛选 |
| 分类 | 分类网格浏览，点分类看该分类下的菜 |
| 分类管理 | 新建 / 重命名 / 删除自建分类（系统自带分类不可删） |
| 菜谱列表 | 进入某个分类后的菜谱清单 |
| 菜谱详情 | 展示食材、步骤、教程链接、收藏状态 |
| 新建 / 编辑菜谱 | 填写名称、简介、分类、标签、难度、时长、食材、步骤、教程链接，可配封面图 |
| 收藏 | 单独一页看所有收藏的菜 |
| 搜索 | 按菜名 / 简介 / 标签 / 食材搜索 |
| 我的 | 统计（菜谱数、收藏数、分类数）、清理缓存、清空数据 |
| 随便吃点 | 按「全部 / 收藏 / 分类」模式随机抽一道菜 |
| 运行日志 | 排障用：查看 / 复制 / 导出运行日志、记录崩溃堆栈（「我的」页连点版本号 7 次进入） |

首次启动会自动写入**种子数据**（9 个系统分类 + 3 道示例菜谱），方便你一打开就有内容看。

---

## 二、技术栈

| 层面 | 技术 |
|---|---|
| 语言 | Kotlin |
| UI | Jetpack Compose + Material 3 |
| 导航 | Navigation Compose |
| 架构 | ViewModel + 单向数据流（UiState） |
| 本地数据库 | Room（SQLite） |
| 异步 | Kotlin Coroutines + Flow |
| 图片 | Coil（选图后自动复制到 App 私有目录） |

**构建链版本（已锁定，勿随意升级）**

- AGP `8.13.2` + Gradle `8.14.3`
- Kotlin `2.2.10` + KSP `2.2.10-2.0.2`
- `compileSdk` / `targetSdk` = `36`，`minSdk` = `24`（Android 7.0 及以上可装）

> ⚠️ **不要升级 AGP 到 9.x**：AGP 9 与当前 KSP 版本硬冲突，会导致整个工程无法编译。

---

## 三、环境要求

- **Android Studio** 最新稳定版（如 Hedgehog / Iguana / Jellyfish 任一较新版）
- JDK 17（Android Studio 自带，无需单独装）
- 一台 Android 7.0+ 的手机或模拟器

---

## 四、如何运行

1. 用 Android Studio 打开本工程根目录（`D:\MyCode\qycm`）。
2. 首次打开会提示 **Sync Project with Gradle Files**，点它等同步完成（约 1 分钟）。
   - 若编辑器里测试文件报「Unresolved reference」之类的红，多半是没同步：**`File → Sync Project with Gradle Files`**，仍不行就 **`File → Invalidate Caches / Restart`**。
3. 连上手机（打开 USB 调试）或启动模拟器。
4. 点工具栏绿色 ▶ **Run 'app'**（或 `Shift+F10`），选设备即可安装运行。

### 打包正式 APK

`Build → Build Bundle(s) / APK(s) → Build APK(s)`，编译完在
`app/build/outputs/apk/debug/`（调试包）或 `release/`（需先配置签名）拿到 `.apk`。

---

## 五、项目结构

```
app/src/main/java/com/example/qycm/
├── data/                 # 数据层：Room 数据库、Entity、DAO、Repository、种子数据、图片存储
│   ├── local/            # AppDatabase / Entity / DAO / SeedInitializer
│   └── RecipeRepository.kt   # ★ 页面只通过它读写数据，不直接碰数据库
├── log/                  # 运行日志：AppLogger（落盘 + 全局崩溃捕获）
├── model/                # 给页面用的数据模型（Recipe / RecipeDetail / Category）
├── ui/
│   ├── theme/            # 配色、字体、圆角（Material 3 主题）
│   ├── components/       # ★ 唯一样式来源：卡片/按钮/标签/顶栏等公共组件
│   ├── home/ category/ categorymanage/ list/ detail/
│   │   edit/ favorite/ search/ mine/ random/   # 各页面（壳 + 纯UI + UiState 三层）
│   └── debug/            # 开发辅助：样式样张页 + 运行日志页（LogViewerScreen）
├── navigation/
│   ├── Routes.kt         # ★ 所有路由字符串的唯一定义处
│   └── AppNavHost.kt     # 页面注册与统一的页面切换动画
└── MainActivity.kt       # 入口，挂载 AppNavHost

app/src/test/             # 单元测试（JVM 上跑真实 Room，无需模拟器）
_backup_step1/            # 14 个「架构自检脚本」（Node.js，共 1600+ 项检查，见第八章）
```

---

## 六、关键架构约定（给维护者的速记）

这套约定是为了「将来好改、好迁」。改代码前先看一眼：

1. **页面不许直接访问数据库**。所有读写走 `RecipeRepository`，页面只拿到 `model/` 下的模型对象。
2. **展示用的文字/格式在 Model 或 UiState 里算好**，页面只负责画，不在界面里拼字符串。
3. **`ui/components/` 是唯一的样式来源**。卡片、按钮、标签、顶栏都复用这里的组件，页面不要自己重写一套。
4. **每个页面三层结构**：
   - 壳（接 ViewModel + 回调，不含界面代码）
   - 纯 UI（只吃 UiState，`@Preview` 指向这一层）
   - UiState（data class，所有字段有默认值）
5. **路由字符串只在 `Routes.kt` 出现一次**，其它地方用 `Routes.recipeDetail(id)` 这类构造器。
6. **列表自动刷新靠 Flow**：数据库一变，页面自动重组，页面里不要手写「重新拉取列表」。
7. **页面切换动画统一在 `AppNavHost` 的 `qycmComposable` 里定义**（单一来源）：
   - 底部 tab（首页 / 分类 / 我的）之间：**方向性左右滑动**，方向按 tab 的相对位置决定；
   - 其它所有跳转（含详情页、返回）：**新页侧边滑入 + 淡入，旧页原地快速淡出（不位移）**，缓动用减速曲线。
   > ⚠️ 曾给详情页做过「封面共享元素飞入」，因详情页是异步加载、源与目标无法同帧出现而效果不稳，**已移除**，不要往回加。
8. **日志统一走 `log/AppLogger`**（不要直接用 `android.util.Log`）：
   - `android.util.Log` 只写进 Logcat —— 手机**不连电脑就什么都看不到**，用户报 bug 时无从查起；
   - `AppLogger` 同时打 Logcat **和**落盘到 `filesDir/logs/`（按天切文件、上限 5 个自动删旧），
     用户能在 App 内导出；崩溃由全局处理器自动记录（含机型 / 系统版本 / 完整堆栈）；
   - 页面跳转不用自己写日志 —— `AppNavHost` 统一记一条「进入页面: xxx」，一处覆盖全部路由。

---

## 七、如何运行测试

单元测试用 **Robolectric** 在 JVM 上跑真实 Room（不用开模拟器），覆盖分类删除、收藏、搜索、详情、编辑、随机推荐等数据层行为。

在 Android Studio 里：右键 `app/src/test/` → **Run 'All Tests'**；
或用命令行：

```bash
./gradlew :app:testDebugUnitTest
```

全部通过会显示 `BUILD SUCCESSFUL`。

---

## 八、架构自检脚本（可选）

`_backup_step1/` 下有 14 个 Node.js 脚本（`_check_step1.js` … `_check_step15.js`），共 **1600+ 项**自动检查（构建配置、分层、组件复用、路由、ViewModel 写法、统计口径等）。它们**不参与 APK 打包**，只是开发期帮你守住架构约定。

运行（需本机有 Node.js）：

```bash
node _backup_step1/_check_step9.js
```

---

## 九、常见问题

- **测试文件标红但能编译？** → 没同步 Gradle，见第四章第 2 步。
- **改完代码真机没变化？** → 单测和编辑器改动都不生成 APK，必须重新 `Run 'app'` / `Build APK` 重装。
- **删了自建分类，里面的菜没了？** → 不会。分类删除时，里面的菜会自动移到「其他」分类；系统分类（如 热门、其他）不可删。
- **想重置成初始状态？** → 「我的 → 清空数据」会恢复成种子数据。
- **App 出 bug 了，日志怎么拿到？** → 「我的」页底部**连点版本号 7 次**进入「运行日志」页：
  点**复制全部**直接粘贴发出去，或点**分享文件**发原始日志文件。日志里有时间、级别、标签；
  如果是闪退，还会带上完整堆栈和机型 / 系统版本。想让日志重新开始，点「清空日志」即可
  （清空前建议先导出）。

---

## 十、License

个人项目，仅供学习与交流使用。