# smart-reconciliation

**Repository Path**: zeus-maker/smart-reconciliation

## Basic Information

- **Project Name**: smart-reconciliation
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: lm/feat-mini
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智账：民生银行流水智能汇总

这是一个面向移动端的银行流水解析与汇总应用。后端使用 FastAPI 提供 PDF
解析、报告查询和删除接口；提供 **H5（React）** 与 **微信小程序** 两套客户端，
展示收支汇总、趋势、分类和交易明细。

> 当前 V1 仅支持民生银行个人流水 PDF，其他银行或无法识别的 PDF 会返回提示。

## 环境准备

- Python 3.11+
- Node.js 20+

首次运行后端时安装依赖：

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

首次运行前端时安装依赖：

```bash
cd frontend
npm install
```

## 启动项目

推荐使用仓库根目录的一键脚本（会自动创建 venv / 安装依赖，若尚未准备）：

```bash
./dev.sh start      # 启动前后端
./dev.sh stop       # 停止
./dev.sh restart    # 重启
./dev.sh status     # 查看状态
./dev.sh logs       # 跟踪日志
```

- 前端：`http://127.0.0.1:5173`
- 后端：`http://127.0.0.1:8000`（API 文档 `/docs`）
- 日志与 PID：`.run/`

也可手动分别启动：

```bash
# 后端
cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

# 另开终端启动前端
cd frontend
npm run dev
```

## Docker 一键部署

需已安装并启动 Docker。

```bash
./docker.sh up        # 构建并启动
./docker.sh status    # 查看状态
./docker.sh logs      # 跟踪日志
./docker.sh restart   # 重启
./docker.sh rebuild   # 强制重建镜像并启动
./docker.sh down      # 停止（保留数据）
./docker.sh clean     # 停止并清空数据卷
```

默认访问：`http://127.0.0.1:8080`（可用 `APP_PORT=3000 ./docker.sh up` 改端口）

前端由 Nginx 托管静态资源，并将 `/api` 反代到后端容器；SQLite 与上传目录使用 Docker 数据卷持久化。

## 阿里云镜像仓库（测试服部署）

前后端镜像推送到成都个人版 ACR `marion-namespace/marion-repo`，测试服务器拉取部署。

详细步骤见：**[docs/deploy/阿里云镜像仓库部署指南.md](docs/deploy/阿里云镜像仓库部署指南.md)**

```bash
# 本地构建并推送
./acr.sh login
./acr.sh push 1.0.0

# 测试服务器拉取并启动
./acr.sh login
./acr.sh deploy 1.0.0
```

默认页面：`http://<服务器IP>:8080`

## 微信小程序

目录：`miniprogram/`（原生小程序，对接同一套后端 API）。

1. 先启动后端：`./dev.sh start`（或 Docker）
2. 修改 `miniprogram/utils/config.js` 中的 `API_BASE_URL`：
   - 模拟器可先用 `http://127.0.0.1:8000`
   - 真机请改为电脑局域网 IP，例如 `http://192.168.1.8:8000`
3. 用[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)导入 `miniprogram/` 目录
4. 详情 → 本地设置：勾选「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」
5. 将 `project.config.json` 里的 `appid` 换成你的小程序 AppID（可先用测试号）

功能对齐 H5 V1：上传 PDF、历史上传、支持银行说明、账单汇总（卡片/趋势条/分类/明细分页）、下拉刷新。

## 运行测试

```bash
cd backend
PYTHONPATH=. pytest -v
```

## 端到端手测清单

- [ ] Health 接口返回 200
- [ ] 上传非 PDF 文件时，前端拦截或后端返回 400
- [ ] 上传损坏或其他银行 PDF 时，返回 422 且文案包含“民生银行”
- [ ] 上传真实民生银行 PDF（需自备样本），汇总结果与 skill CLI 同量级一致
- [ ] 验证报告列表、详情、删除与页面刷新
- [ ] 验证 375px 宽度下无横向滚动且布局正常

## UI 参考

原始参考 UI 位于 `ui/` 目录；当前前端视觉已按项目规格单独实现。