flova 0.1.0__tar.gz

flova-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,21 @@
+# Architecture
+
+```text
+src/flova/
+  core/            协议、稳定错误；不依赖服务实现或传输
+  application/     部署、财务、查询、生命周期用例
+  infrastructure/  Git、进程、Beancount、下载库、Docker/systemd适配
+  entrypoints/     CLI与HTTP；验证、路由、序列化
+  config.py        小型TOML配置与环境变量展开
+  bootstrap.py     组合根，装配协议的具体实现
+```
+
+应用层依赖 `Repository`、`SyncHook`、`CommandRunner`、`QueryGateway`、`Runtime` 协议。更换部署方式、账本后端或进程管理器时，新增基础设施适配器并在 bootstrap 装配；核心协议和 HTTP/CLI 入口无需知道具体实现。
+
+新增 webhook 目标只增加 `[webhooks.name]` 配置，保持每个目标独立密钥和锁。新增业务用例放 application，参数入口放 entrypoints；避免把业务逻辑塞入命令行解析或配置加载。
+
+Beancount 查询保持既有统计规则，作为账本输出适配器。财务编排复用 Fane 公共 CLI，不复制 Fane 模板、分类和写入实现。Ekoa 是独立消息网关，通过可选同步 hook 或明确发送命令调用；Flova 不在其核心中绑定消息平台。
+
+本项目不携带服务器密钥、真实配置、账本、n8n数据库或服务器备份。部署由已发布包、明确的运行配置和数据组成。
+
+`Runtime` 将恢复资源、启动、停止、检查、状态与打包分开。普通快照恢复源服务，正式迁移模式成功后保持源服务停止；异常通过恢复栈复原容器和单元启用状态。静态配置、业务数据和卷快照均使用保留所有权的复制，镜像按运行清单导出。详见 [迁移手册](docs/MIGRATION.md)。

flova-0.1.0/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.12.23 /uv /usr/local/bin/uv
+ARG FLOVA_VERSION=0.1.0
+RUN uv pip install --system --no-cache "flova[ledger]==${FLOVA_VERSION}"
+ENTRYPOINT ["flova", "--config", "/etc/flova.toml"]
+CMD ["ledger", "serve"]

flova-0.1.0/Dockerfile.ekoa

@@ -0,0 +1,9 @@
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.12.23 /uv /usr/local/bin/uv
+ARG EKOA_VERSION=0.1.0
+RUN uv pip install --system --no-cache "ekoa==${EKOA_VERSION}"
+RUN useradd --system --create-home --uid 10001 ekoa
+WORKDIR /app
+USER ekoa
+ENTRYPOINT ["ekoa"]
+CMD ["--config", "/app/config/ekoa.toml", "serve"]

flova-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md ARCHITECTURE.md
+recursive-include src *.py
+recursive-include examples *.toml
+global-exclude token .env *.sqlite *.bean *.pyc
+recursive-include docs *.md
+include Dockerfile Dockerfile.ekoa start.sh release.sh
+prune .migration

flova-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: flova
+Version: 0.1.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，并安装 uv；解包至 `/root` 后执行 `/root/.flow/start.sh`。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 不进入项目分发包。
+
+完整换 VPS 步骤见 [迁移手册](docs/MIGRATION.md)，部署概览见 [服务器说明](docs/SERVER.md)，完整参数见 [指令参考](docs/COMMANDS.md)，财务流程见 [n8n说明](docs/N8N.md)。发布新版本前先提高 pyproject.toml 版本号，PyPI 已发布版本不能覆盖。

flova-0.1.0/README.md

@@ -0,0 +1,39 @@
+# 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，并安装 uv；解包至 `/root` 后执行 `/root/.flow/start.sh`。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 不进入项目分发包。
+
+完整换 VPS 步骤见 [迁移手册](docs/MIGRATION.md)，部署概览见 [服务器说明](docs/SERVER.md)，完整参数见 [指令参考](docs/COMMANDS.md)，财务流程见 [n8n说明](docs/N8N.md)。发布新版本前先提高 pyproject.toml 版本号，PyPI 已发布版本不能覆盖。

flova-0.1.0/docs/COMMANDS.md

@@ -0,0 +1,208 @@
+# 指令参考
+
+全局参数必须放在功能名称前：`flova --root /root/.flow --config /root/.flow/config/flova.toml 功能 ...`。默认路径可由 `FLOVA_ROOT`、`FLOVA_CONFIG` 设置；`--version` 显示版本。
+
+| 功能 | 指令 | 行为 |
+| --- | --- | --- |
+| 校验配置 | `flova config check` | 校验 TOML，不输出密钥 |
+| 启动或恢复服务 | `flova service start` | 安装命令入口、恢复迁移包卷/镜像、创建网络和 systemd 单元，启动服务；重复执行保留正在运行的容器 |
+| 仅恢复资源 | `flova service restore` | 恢复镜像、网络、卷与入口，不启动业务 |
+| 停止服务 | `flova service stop` | 先停止原生服务与 n8n，保留数据 |
+| 正式迁移打包 | `flova service pack --keep-stopped --output /private/path/migration.tar.gz` | 成功后旧机保持停止；失败恢复服务及启用状态 |
+| 检查服务 | `flova service check` | 检查容器、webhook、n8n、查询接口、Fane 配置和账本 |
+| 查看状态 | `flova service status` | 展示容器和 systemd 状态 |
+| 打包迁移 | `flova service pack --output /private/path/migration.tar.gz` | 一致性快照及镜像导出，恢复运行，不覆盖已存在的包 |
+| GitHub 账本同步 | `flova webhook serve` | 按配置监听、验签、过滤分支、串行同步仓库 |
+| 查询 HTTP 服务 | `flova ledger serve` | 提供只读 `/health`、`/query`，需要 ledger extra |
+| 查询命令 | `flova ledger query --start YYYY-MM-DD --end YYYY-MM-DD` | 输出 JSON，`--max-transactions` 控制分录条数 |
+| 账单下载 | `flova download -p alipay --download-config /private/path/download.json` | 使用下载提供者；需要 download extra，另支持 wechat |
+| n8n 准备阶段 | `flova finance prepare --date YYYY-MM-DD` | 下载、解压、同步和提取待分类交易；`--offline` 只读预览 |
+| n8n 完成阶段 | `flova finance finish --write --decisions-base64 'BASE64_JSON'` | 应用分类、订阅；不加 `--write` 为预览 |
+
+财务参数：`--flow` 选择 Fane 同步配置，`--date` 选择日期，`--ledger`、`--subscriptions` 指定账本和真实订阅计划，`--fa`、`--dflow`、`--oub` 覆盖命令路径。没有待分类交易时，决策传空字符串。实际运行和业务配置见 [n8n 说明](N8N.md)。
+
+服务器的 `dflow` 指向 `flova-download` 兼容入口，用 `flova-download --help` 查看旧下载命令参数。通用 CLI 用 `flova download`。
+
+以下帮助直接取自本项目 0.1.0 CLI。同一功能组共享参数，具体行为以表格为准。
+
+## config check
+
+```text
+usage: flova config [-h] {check}
+
+positional arguments:
+  {check}
+
+options:
+  -h, --help  show this help message and exit
+```
+
+## service start
+
+```text
+usage: flova service [-h] [--output OUTPUT] [--keep-stopped]
+                     {start,restore,stop,check,status,pack}
+
+positional arguments:
+  {start,restore,stop,check,status,pack}
+
+options:
+  -h, --help            show this help message and exit
+  --output OUTPUT
+  --keep-stopped        leave source stopped after a successful migration pack
+```
+
+## service check
+
+```text
+usage: flova service [-h] [--output OUTPUT] [--keep-stopped]
+                     {start,restore,stop,check,status,pack}
+
+positional arguments:
+  {start,restore,stop,check,status,pack}
+
+options:
+  -h, --help            show this help message and exit
+  --output OUTPUT
+  --keep-stopped        leave source stopped after a successful migration pack
+```
+
+## service status
+
+```text
+usage: flova service [-h] [--output OUTPUT] [--keep-stopped]
+                     {start,restore,stop,check,status,pack}
+
+positional arguments:
+  {start,restore,stop,check,status,pack}
+
+options:
+  -h, --help            show this help message and exit
+  --output OUTPUT
+  --keep-stopped        leave source stopped after a successful migration pack
+```
+
+## service pack
+
+```text
+usage: flova service [-h] [--output OUTPUT] [--keep-stopped]
+                     {start,restore,stop,check,status,pack}
+
+positional arguments:
+  {start,restore,stop,check,status,pack}
+
+options:
+  -h, --help            show this help message and exit
+  --output OUTPUT
+  --keep-stopped        leave source stopped after a successful migration pack
+```
+
+## webhook serve
+
+```text
+usage: flova webhook [-h] {serve}
+
+positional arguments:
+  {serve}
+
+options:
+  -h, --help  show this help message and exit
+```
+
+## ledger serve
+
+```text
+usage: flova ledger [-h] [--start START] [--end END]
+                       [--max-transactions MAX_TRANSACTIONS]
+                       {serve,query}
+
+positional arguments:
+  {serve,query}
+
+options:
+  -h, --help            show this help message and exit
+  --start START
+  --end END
+  --max-transactions MAX_TRANSACTIONS
+```
+
+## ledger query
+
+```text
+usage: flova ledger [-h] [--start START] [--end END]
+                       [--max-transactions MAX_TRANSACTIONS]
+                       {serve,query}
+
+positional arguments:
+  {serve,query}
+
+options:
+  -h, --help            show this help message and exit
+  --start START
+  --end END
+  --max-transactions MAX_TRANSACTIONS
+```
+
+## download
+
+```text
+usage: flova download [-h] [--provider {alipay,wechat}]
+                         [--download-config DOWNLOAD_CONFIG]
+
+options:
+  -h, --help            show this help message and exit
+  --provider {alipay,wechat}, -p {alipay,wechat}
+  --download-config DOWNLOAD_CONFIG
+```
+
+## finance prepare
+
+```text
+usage: flova finance [-h] [--flow FLOW] [--date DATE] [--offline] [--write]
+                        [--decisions-base64 DECISIONS_BASE64]
+                        [--subscriptions SUBSCRIPTIONS] [--ledger LEDGER]
+                        [--fa FA] [--dflow DFLOW] [--oub OUB]
+                        {prepare,finish}
+
+positional arguments:
+  {prepare,finish}
+
+options:
+  -h, --help            show this help message and exit
+  --flow FLOW
+  --date DATE
+  --offline
+  --write
+  --decisions-base64 DECISIONS_BASE64
+  --subscriptions SUBSCRIPTIONS
+  --ledger LEDGER
+  --fa FA
+  --dflow DFLOW
+  --oub OUB
+```
+
+## finance finish
+
+```text
+usage: flova finance [-h] [--flow FLOW] [--date DATE] [--offline] [--write]
+                        [--decisions-base64 DECISIONS_BASE64]
+                        [--subscriptions SUBSCRIPTIONS] [--ledger LEDGER]
+                        [--fa FA] [--dflow DFLOW] [--oub OUB]
+                        {prepare,finish}
+
+positional arguments:
+  {prepare,finish}
+
+options:
+  -h, --help            show this help message and exit
+  --flow FLOW
+  --date DATE
+  --offline
+  --write
+  --decisions-base64 DECISIONS_BASE64
+  --subscriptions SUBSCRIPTIONS
+  --ledger LEDGER
+  --fa FA
+  --dflow DFLOW
+  --oub OUB
+```