# Diary News — Android App

> 私人新闻聚合器的 Android 客户端,读 FastAPI 后端。
>
> **状态**:方案阶段(未开工)。本文档是开工前的最终蓝图,任何代码改动必须先对齐这里的约定。

---

## 0. 一句话总览

- **后端**:`http://207.57.129.228:3000/api/v1`(私有 IP 直连,明文 HTTP)
- **客户端**:Kotlin + Jetpack Compose,单 module
- **认证**:Bearer JWT,access 60min,自动 refresh
- **离线**:列表分页缓存 + 收藏本地库 + Token 加密存储
- **目标**:7 天出第一个能跑通登录 → 列表 → 详情 → 收藏的 APK

---

## 1. 文档索引(按开工顺序读)

| 序 | 文档 | 作用 | 何时读 |
|---|---|---|---|
| 1 | [01-architecture.md](01-architecture.md) | 模块划分 + 数据流 + 依赖选型理由 | 开工前 30min |
| 2 | [02-api-contract.md](02-api-contract.md) | 每个接口的请求/响应 + DTO 字段映射表 | 写 DTO 时对照 |
| 3 | [03-build-run.md](03-build-run.md) | Gradle / SDK / network security / 真机调试 | 第一次 build 前 |
| 4 | [04-milestones.md](04-milestones.md) | 7 天里程碑拆分 + DoD | 每天开工前看当天任务 |

---

## 2. 5 分钟决策摘要(免读细节直接用)

| 维度 | 选择 | 替代方案(及为啥不选)|
|---|---|---|
| 语言 | Kotlin 2.0.21 | — |
| UI | Jetpack Compose (Material3) | ❌ XML View(老)| ❌ RN/Flutter(项目太轻)|
| 网络 | Retrofit 2.11 + OkHttp 4.12 | ❌ Ktor Client(生态薄)|
| 序列化 | kotlinx.serialization 1.7.3 | ❌ Moshi(更重)|
| DI | Hilt 2.52 | ❌ Koin(运行时,启动慢)|
| 分页 | Paging 3.3.4 | ❌ 手写 LazyColumn + offset |
| 图片 | Coil 2.7 | ❌ Glide(Compose 集成弱)|
| 路由 | Navigation Compose 2.8.4 | — |
| 加密 | security-crypto 1.1.0-alpha06(EncryptedSharedPreferences)| — |
| 本地 DB | Room 2.6.1 | — |
| minSdk | 24 (Android 7.0) | ❌ 26(放弃 7.0/7.1 ~3% 用户)|
| targetSdk | 35 (Android 15) | — |
| compileSdk | 35 | — |
| AGP | 8.7.2 | — |
| API base | `http://207.57.129.228:3000/api/v1` | ❌ HTTPS(当前 server 无证书)|

---

## 3. 顶层目录(最终落地的样子)

```
diary-news-android/        # ← 独立 Git 仓库(不要混进 diary-news)
├── settings.gradle.kts├── build.gradle.kts            # root
├── gradle/
│ ├── libs.versions.toml # 集中版本
│ └── wrapper/
├── app/
│ ├── build.gradle.kts│ ├── proguard-rules.pro│ └── src/main/
│ ├── AndroidManifest.xml
│ ├── res/                  # xml + values + mipmap
│ └── java/com/diary/news/
│ ├── DiaryNewsApp.kt       # @HiltAndroidApp
│ ├── MainActivity.kt│ ├── data/                  # api/auth/db/repository
│ ├── domain/                # 业务 model
│ ├── di/                    # Hilt modules
│ └── ui/                    # theme/nav/login/feed/article/bookmarks/sources/common
└── README.md
```

> **仓库策略**:Android app 单独建 Git 仓库 `diary-news-android`,不要和 `diary-news`(后端 + web)混。原因是 release 节奏 / CI / 依赖管理天然不同。

---

## 4. 端到端数据流(登录 → 刷列表 → 打开详情 → 收藏)

```
1. 启动
 DiaryNewsApp.onCreate
 → Hilt 初始化
 → MainActivity 检查 TokenStore:有 access 且未过期 → 直接进 Feed
 → 无 / 过期 → 进 LoginScreen

2. 登录
 LoginScreen → LoginViewModel.login()
 → POST /auth/login { username, password }
 → 拿到 { access_token, refresh_token, expires_in }
 → TokenStore.save()  (EncryptedSharedPreferences)
 → 跳 FeedScreen

3. 列表
 FeedScreen → FeedViewModel
 → Pager + ArticlePagingSource(api::listArticles)
 → ApiService.listArticles(page, page_size, ...)
 → AuthInterceptor 加 Authorization: Bearer <access>
 → 返回 ArticleListResponseDto
 → Paging 流到 LazyColumn
 → 每一项 ArticleCard 渲染

4. 详情
 点 ArticleCard → ArticleScreen(articleId)
 → ArticleViewModel.load(id)
 → ApiService.getArticle(id)
 → 三段 Tab:评论(commentary)/译文(body_zh_formatted)/原文(body_html)

5. 收藏
 详情页点 ☆ 按钮 → ArticleViewModel.toggleBookmark()
 → POST /bookmarks { article_id } 或 DELETE /bookmarks/{id}
 → 乐观更新 UI(立刻变实心★,失败再回滚 + Snackbar)

6. 401 自动 refresh
 任意接口返回 401
 → OkHttp TokenAuthenticator 拦截
 → 拿 refresh_token 调 /auth/refresh
 → 拿到新 access → 重发原请求
 → 用户完全无感
```

---

## 5. 不要做的事(踩坑清单)

| 坑 | 说明 | 正确做法 |
|---|---|---|
| ❌ 把 access_token 存普通 SharedPreferences | root 手机秒读 | `EncryptedSharedPreferences` + Keystore |
| ❌ 在主线程调 Retrofit | ANR | `suspend fun` + ViewModelScope(自动主线程安全)|
| ❌ 在每次请求前同步读 token | 阻塞 UI | TokenStore 缓存到内存,只在 save/load 时动 SP |
| ❌ refresh 接口并发触发 N 次 | 触发限流 / 死锁 | `synchronized(this)` 单飞锁 |
| ❌ 全量缓存所有文章 | DB 撑爆,启动慢 | 只缓存当前可见页 |
| ❌ WebView 开 JS | XSS 风险 | `settings.javaScriptEnabled = false` |
| ❌ 信任 HTTPS 证书所有 CA | 中间人 | 默认 `system` trust anchor,不动 |
| ❌ 让 HTTP 走全网 | 不安全 | `network_security_config.xml` 白名单单一 IP |
| ❌ 在 ViewModel 里持有 Context | 内存泄漏 | 用 `@HiltAndroidApp` / `AndroidEntryPoint`,Context 通过 Hilt 注入 |
| ❌ ProGuard 不留 keep 规则就 release | retrofit 接口全找不到 | 详见 03-build-run.md §5 |

---

## 6. 启动指令(开工第一步)

1. **Android Studio Hedgehog**(2023.1.1)+ → `File → New → New Project → Empty Activity (Compose)`
2. **包名**:`com.diary.news`
3. **Application name**:`Diary News`
4. **Min SDK**:24 / **Target SDK**:35
5. **Kotlin DSL** + **Version Catalog**(`gradle/libs.versions.toml`)
6. 改完 `gradle/libs.versions.toml` 后第一次 Sync —— 视网络,5-15 分钟
7. 跑 `gradlew assembleDebug` 出第一个 debug APK
8. 真机或模拟器装上,网络选 **宿主机的桥接**(模拟器用 `10.0.2.2:3000` 临时绕开,真机直接走 server IP)

完整步骤见 [03-build-run.md](03-build-run.md)。

---

## 7. 与 web 端的关系

| 项 | web (Vue) | Android (Kotlin) |
|---|---|---|
| 主题色 | `#2080f0` | 同 |
| 字体 | 系统字体 + 14px/13px | Material3 Typography scale |
| 卡片布局 | 标题 → 译标 → 摘要 → 评论钩子 | 同(插图在中间)|
| 列表分页 | 12345 页码 (NPagination)| 滚动加载(Paging 3)|
| 详情页布局 | 评论 / 译文 / 原文 三段 | 同(改用 Tab) |
| 鉴权 | localStorage 存 token | EncryptedSharedPreferences |

视觉与交互**保持一致**,不要做出两个产品的分裂感。

---

## 8. 后续可能加的东西(不在 MVP)

- 推送通知(FCM / 极光)
- 离线下载包(整本周报导出 PDF)
- 阅读历史(本地,不上服务端)
- 暗色主题(Material3 Dynamic Color)
- 主屏幕 widget(显示今日头条)
- Wear OS 端(以后再说)

> 原则:**MVP 先能跑,再加料**。每加一项功能,先回到 [01-architecture.md](01-architecture.md) 看会不会破坏现有分层。