23588b584f
- infrastructure-setup.md: MinIO bucket, access key, PostgreSQL database/user/table deployment guide - implementation-plan.md: backend (FastAPI) and Android (Flutter) implementation roadmap - .gitignore: exclude credential YAML files (connections-remote.yaml, connections-local.yaml) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
132 lines
4.9 KiB
Markdown
132 lines
4.9 KiB
Markdown
# 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 注册 |
|