Metadata-Version: 2.4
Name: finance-tax
Version: 0.1.1
Summary: 中国企业记账报税技能包 - 支持银行流水导入、发票管理、自动记账、财务报表生成和税务申报
License: MIT
Keywords: accounting,agent,bookkeeping,china,finance,tax
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: urllib3>=2.0
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: uvicorn>=0.29; extra == 'api'
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: ocr
Requires-Dist: httpx>=0.27; extra == 'ocr'
Description-Content-Type: text/markdown

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

[![PyPI version](https://img.shields.io/pypi/v/finance-tax)](https://pypi.org/project/finance-tax/)
[![Python](https://img.shields.io/pypi/pyversions/finance-tax)](https://pypi.org/project/finance-tax/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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

## 功能特性

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

## 快速开始

### 前置要求

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) 包管理器

### 安装

```bash
# 从 PyPI 安装
uv tool install finance-tax

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

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

### 初始化

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

### 基本使用

```bash
# 导入银行流水
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 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
