SnapLedger/docs/implementation-plan.md

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 注册