Metadata-Version: 2.4
Name: flova
Version: 0.2.0
Summary: Small, extensible service orchestration for personal automation
Author: enmu
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: ledger
Requires-Dist: beancount==3.2.3; extra == "ledger"
Provides-Extra: download
Requires-Dist: download-flow-enmu==0.1.7; extra == "download"
Provides-Extra: dev
Requires-Dist: ruff>=0.8; extra == "dev"

# Flova

Flova 把 webhook、只读账本查询、财务适配、本机服务启停和远程部署合成一个可安装的项目。配置与业务数据留在服务器，源码留在本地。

```bash
uv tool install 'flova[download]'
flova --config /path/to/flova.toml config check
flova webhook serve
flova finance prepare --offline --date 2026-10-03
flova finance finish --write --decisions-base64 'BASE64_JSON'
flova service start
flova service restore  # 仅恢复资源，不启动任务
flova service stop
flova service check
flova service pack
flova service pack --keep-stopped  # 正式迁移，成功后保持旧机停止
```

仅运行 ledger 时安装 `uv tool install 'flova[ledger]'`，用 `flova ledger serve` 启动，或 `flova ledger query --start YYYY-MM-DD --end YYYY-MM-DD` 查询。

`flova download -p alipay --download-config /path/to/download.json` 使用现有下载库的提供者工厂，并明确读取配置路径，不再改写第三方包源码。

`flova-download download` 提供旧 dflow 命令的参数和 JSON 兼容入口，服务器 dflow 入口指向它。

默认配置 `/root/.flow/config/flova.toml`。支持 `${ENV_NAME}` 占位符，缺失变量直接报错。模板见 `examples/`。`--config` 和 `--root` 是全局参数，放在功能指令前。`FLOVA_CONFIG`、`FLOVA_ROOT` 可设置默认位置。

Webhook 验证 GitHub HMAC SHA256，只响应指定分支的 push；同一仓库同步互斥，保持旧服务的 fetch/reset/clean 镜像同步语义。因此应指向自动部署仓库，不应指向有未提交人工改动的开发目录。同步后的可选 HTTP hook 由配置指定；失败记录类型，不把凭据或请求正文写入日志。

账本接口保持 `GET /health` 和 `POST /query`，字段 `start_date`、`end_date`、`max_transactions`，仍输出 `schema_version=1`、收入/支出/资产负债变动、分录及警告。日期范围最多366天；查询只读。

财务功能只编排 fa、下载提供者和 oub；Fane 负责解析、模板、去重和分类。`prepare --offline` 不下载、解压、写交易、调用AI或推送。`finish` 不带 `--write` 为预览；未配置实际订阅计划时明确失败，不假装成功。

服务指令读取服务器 `config/services.json` 和唯一 `config/compose.yaml`。启动重复执行不会重建正在运行的容器。普通打包短暂停止 webhook、暂停容器以复制一致数据，立即恢复，再导出镜像。正式迁移使用 `--keep-stopped`：先停稳服务再复制数据，成功后旧机保持停止，禁用 webhook 自启与容器自动重启；失败或回退启动恢复原策略。包保留 n8n 配置和所有权，包含秘密，应私有保存。

新服务器使用相同 Python 3.12 和 x86_64，事先安装 Docker/Compose、Git 和 msmtp。uv 随包迁移。解包至 `/root` 后先执行 `/root/.flow/start.sh restore`，按 [迁移手册](docs/MIGRATION.md) 暂停新机 n8n 发布，再启动检查及切换。SSH 私钥、域名 DNS 及 n8n SSH 服务器地址需单独迁移。

开发：`uv sync --all-extras`，`uv run python -m unittest discover -s tests`，`uv run ruff check src tests`。发布：`PYPI_TOKEN_FILE=/private/path/token ./release.sh --yes`。token 不进入项目分发包。

远程盘点、清单备份恢复和 Docker 克隆见 [主机管理](docs/HOSTS.md)，统一入口 `flova host`，无需本机服务器配置。原 Deploior 功能已全部迁入，配置模板为 `examples/hosts.toml`。

完整换 VPS 步骤见 [迁移手册](docs/MIGRATION.md)，部署概览见 [服务器说明](docs/SERVER.md)，完整参数见 [指令参考](docs/COMMANDS.md)，财务流程见 [n8n说明](docs/N8N.md)。发布新版本前先提高 pyproject.toml 版本号，PyPI 已发布版本不能覆盖。
