🧾 finance-tax — 中国企业记账报税技能包

面向中国中小微企业的智能记账报税工具，为 AI Agent 提供完整的财务管理能力。

功能特性

• 银行流水导入 — 支持主流银行 Excel 格式，智能列名识别与去重
• 发票管理 — 参数化录入，对接阿里云发票查验 API，支持科目建议与审核入账
• 自动记账 — 智能科目匹配，自动生成复式记账凭证
• 附件管理 — 发票照片、电子发票、银行回单等电子凭证的上传与关联
• 财务报表 — 资产负债表、利润表、现金流量表、科目余额表
• 税务计算 — 增值税、企业所得税、印花税、附加税自动计算
• 迁移导入 — 从其他系统导入期初余额，自动验证借贷平衡
• 中国税务合规 — 支持小规模/一般纳税人，兼容两套会计准则
• Web 数据看板 — 内置 Web UI，数据概览、查询与图表分析
• 自动版本检测 — CLI 启动时检测 PyPI 新版本并提示更新

快速开始

前置要求

• Python 3.11+
• uv 包管理器

安装

# 从 PyPI 安装
uv tool install finance-tax

# 或添加为项目依赖
uv add finance-tax

# 安装可选依赖（Web 看板 / 发票 OCR）
uv tool install "finance-tax[api]"

初始化

ft init --name "我的公司" --year 2026

基本使用

# 导入银行流水
ft bank import 银行流水.xlsx --bank-name 招商银行

# 录入发票
ft invoice add --invoice-number 12345678 --invoice-date 2026-03-01 \
  --direction input --amount 10000 --tax-amount 600 --seller-name "供应商"

# 查验发票真伪
ft invoice verify --invoice-id 1

# 审核流水并生成凭证（Agent 工作流）
ft bank list --unprocessed --json-output
ft voucher suggest 1
ft voucher assign 1 --debit "银行存款" --credit "主营业务收入" --post

# 月末计提工资（手工凭证）
ft voucher create --date 2026-03-31 \
  --debit "管理费用/工资" --credit "应付职工薪酬/工资" \
  --amount 15000 --description "计提3月工资" --post

# 迁移记账（从其他系统导入期初余额）
ft migrate import-balance --period 2026-03 --json-data '[...]'
ft migrate verify --period 2026-03

# 生成报表
ft report balance-sheet --period 2026-03
ft report income --period 2026-03 --start 2026-01

# 计算税费
ft tax vat --period-start 2026-01 --period-end 2026-03
ft tax income --year 2026 --quarter 1

# 启动 Web 数据看板
ft web --port 8000

项目结构

finance-tax/
├── SKILL.md                  # 技能清单（模块索引）
├── README.md                 # 说明文档
├── pyproject.toml            # Python 项目配置
├── references/               # 各模块详细文档
│   ├── setup.md              # 初始化配置
│   ├── bank-import.md        # 银行流水导入
│   ├── invoice-manage.md     # 发票管理
│   ├── voucher-generate.md   # 凭证生成
│   ├── report-generate.md    # 报表生成
│   ├── tax-calculate.md      # 税务计算
│   ├── account-period.md     # 科目/期间管理
│   ├── migrate.md            # 迁移记账
│   └── attachment-manage.md  # 附件管理
├── data/                     # 基础数据
│   ├── chart_of_accounts_small_enterprise.json
│   ├── chart_of_accounts_enterprise.json
│   └── tax_rules.json
└── src/finance_tax/          # 源代码
    ├── cli.py                # CLI 入口
    ├── config.py             # 配置管理
    ├── database.py           # 数据库 & 迁移管理
    ├── version_check.py      # PyPI 版本检测
    ├── models/               # 数据模型
    ├── import_engine/        # 导入引擎（银行/发票/附件/查验）
    ├── accounting/           # 会计引擎
    ├── reporting/            # 报表引擎
    ├── taxation/             # 税务引擎
    └── web/                  # Web 看板
        ├── app.py            # FastAPI 后端
        └── static/           # 前端静态文件
            ├── index.html    # SPA 骨架
            ├── css/app.css   # 全局样式
            └── js/           # 模块化 JS
                ├── app.js    # Vue 主入口
                ├── api.js    # API 封装
                ├── utils.js  # 工具函数
                └── views/    # 各视图状态逻辑

技术栈

• 语言: Python 3.11+
• CLI: Click + Rich
• ORM: SQLAlchemy 2.0
• 数据库: SQLite（本地）
• Excel: openpyxl + pandas
• 配置: Pydantic Settings
• Web: FastAPI + Vue 3 + TailwindCSS + ECharts（CDN，无需构建）

许可证

MIT