# SnapLedger Phase 1 实施计划

> **日期:** 2026-05-21
> **范围:** 后端 (FastAPI) + Android 端 (Flutter/Dart)
> **目标:** 跑通端到端数据流 — 截图 → 上传 → 存储 → 入库

## 技术决策

| 决策项 | 选择 | 理由 |
|---|---|---|
| Android 框架 | Flutter / Dart | 主仓库 README 已确定 |
| 后端框架 | Python FastAPI | 已确定 |
| 后端部署 | Docker 容器 | 服务器已有 Docker 环境 |
| API 鉴权 | 静态 Token (Header) | Phase 1 个人使用，简单直接 |
| 数据库 | PostgreSQL 18 (已部署) | — |
| 对象存储 | MinIO (已部署) | — |

## 开发与部署环境

| 环境 | 位置 | 用途 | 配置文件 |
|---|---|---|---|
| 开发机 | 当前主机 (Windows) | 编码、调试、本地运行后端 | `docs/connections-remote.yaml` |
| 服务器 | `Remote_MisakaServer:/home/misakafiles/` | 生产部署 | `docs/connections-local.yaml` |

**配置文件说明：**
- `connections-remote.yaml` — 当前主机开发时使用，通过公网域名/cpolar 隧道连接服务器上的 MinIO 和 PostgreSQL
- `connections-local.yaml` — 服务器部署时使用，MinIO 和 PostgreSQL 均为 localhost 连接
- 两个文件均已在 `.gitignore` 中，不提交到仓库

---

## Part A: 后端 (backend/)

### A1. 项目初始化

- 创建 `pyproject.toml` 管理依赖
- 依赖清单：`fastapi`, `uvicorn[standard]`, `boto3` (S3), `psycopg[binary]` (PostgreSQL), `python-multipart`, `pydantic`, `pyyaml`
- 创建 `config.example.yaml` 声明配置模板
- 创建 `.gitignore`

### A2. 项目结构

```
backend/
├── app/
│   ├── __init__.py
│   ├── main.py            # FastAPI app 入口
│   ├── config.py           # Settings (Pydantic, 读 config.yaml)
│   ├── routers/
│   │   │   └── upload.py   # POST /api/upload 路由
│   ├── services/
│   │   ├── minio.py        # MinIO 上传逻辑
│   │   └── database.py     # PostgreSQL 写入逻辑
│   └── models/
│       └── transaction.py  # Pydantic / SQL 模型
├── config.example.yaml     # 配置模板 (无敏感信息)
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
└── .gitignore
```

### A3. 核心功能实现

| 功能 | 说明 |
|---|---|
| `config.py` | 使用 Pydantic 模型读取 `config.yaml`：MinIO 连接、PG 连接、API Token |
| `POST /api/upload` | 接收 multipart/form-data：图片文件 + original_filename + user_note，鉴权 Token 校验 |
| `services/minio.py` | 生成 Object Key (`YYYY/MM/DD/<uuid>.<ext>`)，调用 S3 PutObject 上传到 `snapledger` 桶 |
| `services/database.py` | 写入 `transactions` 表：image_object_key, original_filename, user_note, upload_time, process_status=PENDING |

### A4. 本地开发验证

- 将 `docs/connections-remote.yaml` 复制为 `backend/config.yaml`
- 在当前主机上使用 `.venv` 运行 FastAPI
- `curl -X POST` 模拟上传，确认 MinIO 有文件、PG 有记录

### A5. 服务器部署

1. SSH 到 `Remote_MisakaServer`
2. `cd /home/misakafiles/ && git clone <主仓库地址> && cd SnapLedger && git submodule update --init`
3. 将 `docs/connections-local.yaml` 复制为 `backend/config.yaml`
4. `cd backend && docker compose up -d --build`
5. 验证容器运行正常，从 Android 端实际测试

---

## Part B: Android 端 (android/)

### B1. 项目初始化

- `flutter create` 创建 Flutter 项目
- 添加依赖：`http` (网络请求)、`path_provider` (文件路径)、`shared_preferences` (可选，缓存 Token)
- 配置 AndroidManifest.xml：注册 Share Intent receiver

### B2. 核心功能实现

| 功能 | 说明 |
|---|---|
| **Share Intent 接收** | Android 原生层 (`MethodChannel`) 注册 `ACTION_SEND` intent，接收图片 URI 和原始文件名 |
| **记账弹窗 UI** | Flutter 半屏弹窗：图片缩略图预览 + 备注输入框 + 提交/取消按钮 |
| **网络上传模块** | 构造 multipart POST 请求，附带图片字节流 + original_filename + user_note + Token Header |
| **失败重试** | 上传失败时本地缓存请求，网络恢复后重试 |

### B3. 验证

- 手机截图 → 分享到 SnapLedger → 弹窗 → 提交 → 确认 MinIO 和 PG 有数据

---

## 实施顺序

```
A1 → A2 → A3 → A4(本地验证) → A5(服务器部署) → B1 → B2 → B3
                                               ↑
                                         后端就绪后开始
```

**先完成后端，再实现 Android 端。** 后端完成后可以用 curl 验证，不依赖客户端。

---

## 产出文件清单

| 文件 | 位置 | 说明 |
|---|---|---|
| 后端代码 | `backend/app/` | FastAPI 应用 |
| Dockerfile | `backend/Dockerfile` | 后端容器镜像 |
| docker-compose.yml | `backend/docker-compose.yml` | 后端容器编排 |
| Flutter 项目 | `android/lib/` | Flutter/Dart 源码 |
| AndroidManifest | `android/android/app/src/main/AndroidManifest.xml` | Share Intent 注册 |