{"id":26573967,"url":"https://github.com/chiupam/invoiceocr","last_synced_at":"2025-09-07T01:33:08.422Z","repository":{"id":283634825,"uuid":"952370931","full_name":"chiupam/invoiceOCR","owner":"chiupam","description":"基于腾讯云OCR API的发票识别与管理系统，支持自动识别发票数据、图像处理、项目分类和数据导出功能。","archived":false,"fork":false,"pushed_at":"2025-04-18T17:09:04.000Z","size":307,"stargazers_count":13,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-25T01:53:37.868Z","etag":null,"topics":["api","chinese-invoice","database","document-management","flask","invoice-ocr","ocr-recognition","python","tax-invoice-management","tencent-cloud","web-app"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chiupam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-21T07:05:49.000Z","updated_at":"2025-07-21T09:12:09.000Z","dependencies_parsed_at":"2025-04-20T12:05:51.795Z","dependency_job_id":null,"html_url":"https://github.com/chiupam/invoiceOCR","commit_stats":null,"previous_names":["chiupam/invoiceocr"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/chiupam/invoiceOCR","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiupam%2FinvoiceOCR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiupam%2FinvoiceOCR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiupam%2FinvoiceOCR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiupam%2FinvoiceOCR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chiupam","download_url":"https://codeload.github.com/chiupam/invoiceOCR/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiupam%2FinvoiceOCR/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273986612,"owners_count":25202704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","chinese-invoice","database","document-management","flask","invoice-ocr","ocr-recognition","python","tax-invoice-management","tencent-cloud","web-app"],"created_at":"2025-03-23T01:32:04.571Z","updated_at":"2025-09-07T01:33:08.373Z","avatar_url":"https://github.com/chiupam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧾 发票OCR管理系统\n\n[![Python Version](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/)\n[![Flask Version](https://img.shields.io/badge/flask-2.0.1-green.svg)](https://flask.palletsprojects.com/)\n[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/docker-available-blue.svg)](https://hub.docker.com/r/chiupam/invoiceocr)\n[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Coverage Status](https://img.shields.io/badge/coverage-80%25-green.svg)](https://github.com/chiupam/invoiceOCR/actions)\n\n\u003c/div\u003e\n\n一个基于Flask框架开发的智能发票管理系统，支持发票图片上传与OCR识别，提供发票信息管理、数据导出及统计分析等功能。系统采用腾讯云OCR API进行发票文字识别，实现发票信息的智能提取与处理。\n\n## ✨ 功能特点\n\n- 📤 发票图片和PDF文件上传与预览\n- ✏️ 支持手动创建发票，无需上传图片\n- 🔍 基于腾讯云OCR API的发票文字识别\n- 📄 支持直接识别PDF发票第一页\n- 💾 发票数据结构化处理与存储\n- 📋 发票列表展示与多维度排序\n- 🔎 发票详情查看与编辑\n- 📁 项目分类管理功能\n- 👁️ 发票图片与PDF预览功能\n- 📊 发票数据导出（CSV、Excel格式）\n- 📈 发票统计分析与图表展示\n- 📱 响应式网页设计，适配多种设备\n- ⏱️ 定时任务自动清理过期文件\n\n## 🔄 最近更新\n\n最新版本 v1.3 (2024.04.04)\n- ✅ 添加手动创建发票功能，无需上传图片即可录入信息\n- 🐛 修复未分类发票统计显示问题\n- 🔧 添加对image_path为None的检查，避免模板渲染错误\n\n查看完整的更新历史请参考 [CHANGELOG.md](CHANGELOG.md)\n\n## 🚀 快速开始\n\n### 🐳 使用 Docker\n\n#### 1️⃣ 准备工作\n\n确保已安装Docker和Docker Compose：\n- [Docker安装指南](https://docs.docker.com/get-docker/)\n- [Docker Compose安装指南](https://docs.docker.com/compose/install/)\n\n#### 2️⃣ 部署步骤\n\n##### (1) 克隆仓库并进入项目目录\n```bash\ngit clone https://github.com/chiupam/invoiceOCR.git\ncd invoiceOCR\n```\n\n##### (2) 创建环境变量文件（可选）\n```bash\ncp .env.example .env\n# 仅需配置基本环境变量，API密钥通过Web界面配置\n```\n\n##### (3) 构建并启动容器\n```bash\ndocker-compose up -d\n```\n\n##### (4) 访问应用\n浏览器访问 http://localhost:5001 即可使用应用。首次访问时，系统会引导您完成腾讯云API密钥设置。\n\n#### 3️⃣ 常用Docker命令\n\n- **查看容器日志**\n```bash\ndocker-compose logs -f\n```\n\n- **停止容器**\n```bash\ndocker-compose down\n```\n\n- **重新构建（更新代码后）**\n```bash\ndocker-compose up -d --build\n```\n\n#### 4️⃣ 使用预构建的Docker镜像\n\n我们提供了多个镜像源以适应不同地区用户的需求：\n\n##### 🔵 Docker Hub (推荐)\n\n```bash\n# 拉取最新版本\ndocker pull chiupam/invoiceocr:latest\n\n# 拉取特定版本\ndocker pull chiupam/invoiceocr:v1.3\n\n# 运行容器\ndocker run -d -p 5001:5001 -v $(pwd)/data:/app/data --name invoice_ocr chiupam/invoiceocr:latest\n```\n\n##### 🔷 GitHub Container Registry\n\n```bash\n# 拉取最新版本\ndocker pull ghcr.io/chiupam/invoiceocr:latest\n\n# 拉取特定版本\ndocker pull ghcr.io/chiupam/invoiceocr:v1.3\n\n# 运行容器\ndocker run -d -p 5001:5001 -v $(pwd)/data:/app/data --name invoice_ocr ghcr.io/chiupam/invoiceocr:latest\n```\n\n##### 💾 数据持久化\n\n上面的命令使用了卷挂载 `-v $(pwd)/data:/app/data` 来保证数据在容器重启后不会丢失。您可以根据需要修改本地路径。\n\n### 💻 本地部署\n\n#### 1️⃣ 克隆项目\n\n```bash\ngit clone https://github.com/chiupam/invoiceOCR.git\ncd invoiceOCR\n```\n\n#### 2️⃣ 创建并激活虚拟环境\n\n```bash\n# 创建虚拟环境\npython3 -m venv .venv\n\n# 激活虚拟环境 (Linux/Mac)\nsource .venv/bin/activate\n\n# 激活虚拟环境 (Windows)\n# .venv\\Scripts\\activate\n```\n\n激活后，命令行前面会出现`(.venv)`前缀，表示当前处于虚拟环境中。后续所有命令都应在此环境中执行。\n\n#### 3️⃣ 安装依赖\n\n```bash\n# 确保在虚拟环境中执行\n(.venv) pip3 install -r requirements.txt\n```\n\n#### 4️⃣ 基本环境配置\n\n创建 `.env` 文件（可以复制 `.env.example` 并根据需要修改）：\n\n```bash\n# 复制示例配置\n(.venv) cp .env.example .env\n```\n\n注意：与旧版本不同，API密钥现在不需要在环境变量中配置，而是在Web界面中设置。\n\n#### 5️⃣ 运行应用\n\n```bash\n(.venv) python3 run.py\n```\n\n应用将在 http://127.0.0.1:5001/ 运行。首次运行时，系统会自动初始化数据库并引导您完成必要的设置。\n\n#### 6️⃣ 首次访问配置\n\n首次访问系统时，会自动跳转到设置页面，需要配置以下信息：\n\n1. 腾讯云OCR API密钥（SecretId和SecretKey）\n   - 可在[腾讯云控制台](https://console.cloud.tencent.com/cam/capi)获取\n   - 需要开通腾讯云OCR服务（增值税发票识别）\n\n配置完成后，即可开始使用系统的所有功能。\n\n#### 7️⃣ 退出虚拟环境（完成使用后）\n\n```bash\n(.venv) deactivate\n```\n\n#### ❓ 常见问题解决\n\n- **依赖安装失败**：尝试更新pip后再安装 `python3 -m pip install --upgrade pip`\n- **数据库初始化错误**：确认是否有足够权限创建文件，或检查data目录是否存在\n- **OCR识别失败**：检查`.env`文件中的腾讯云API密钥是否正确\n\n## 📂 项目结构\n\n```\nInvoiceOCR/\n├── app/                          # Web应用主目录\n│   ├── static/                   # 静态资源\n│   │   ├── css/                  # CSS样式\n│   │   │   └── style.css         # 全局样式表\n│   │   ├── js/                   # JavaScript文件\n│   │   │   ├── edit_invoice.js   # 发票编辑页面脚本\n│   │   │   ├── index.js          # 首页脚本\n│   │   │   ├── main.js           # 主要公共脚本\n│   │   │   └── upload.js         # 上传页面脚本\n│   │   └── uploads/              # 上传的发票图片存储目录\n│   ├── templates/                # HTML模板\n│   │   ├── errors/               # 错误页面模板\n│   │   │   ├── 404.html          # 404错误页面\n│   │   │   └── 500.html          # 500错误页面\n│   │   ├── base.html             # 基础布局模板\n│   │   ├── index.html            # 首页模板\n│   │   ├── invoice_create.html   # 发票创建页面\n│   │   ├── invoice_detail.html   # 发票详情页面\n│   │   ├── invoice_edit.html     # 发票编辑页面\n│   │   ├── project_detail.html   # 项目详情页面\n│   │   ├── project_form.html     # 项目编辑表单\n│   │   ├── project_list.html     # 项目列表页面\n│   │   ├── settings.html         # 设置页面\n│   │   └── upload.html           # 上传页面\n│   ├── __init__.py               # 应用初始化\n│   ├── config.py                 # 应用配置\n│   ├── models.py                 # 数据模型\n│   ├── routes.py                 # 路由定义\n│   └── utils.py                  # 辅助函数\n├── core/                         # 核心功能模块\n│   ├── __init__.py               # 模块初始化\n│   ├── invoice_export.py         # 发票数据导出功能\n│   ├── invoice_formatter.py      # 发票数据格式化\n│   ├── ocr_api.py                # OCR API调用功能\n│   ├── ocr_process.py            # OCR结果处理\n│   └── README.md                 # 核心模块说明文档\n├── data/                         # 数据存储目录\n│   ├── invoices.db               # SQLite数据库文件\n│   ├── output/                   # 导出文件存储目录\n│   └── README.md                 # 数据目录说明文档\n├── tools/                        # 工具脚本目录\n│   ├── clean_temp_files.py       # 临时文件清理工具\n│   ├── db_backup.py              # 数据库备份工具\n│   ├── db_init.py                # 数据库初始化脚本\n│   ├── db_query.py               # 数据库查询工具\n│   ├── generate_test_data.py     # 测试数据生成工具\n│   └── README.md                 # 工具脚本说明文档\n├── test/                         # 测试目录\n│   ├── fixtures/                 # 测试数据目录\n│   │   └── invoices/             # 测试发票图片\n│   └── README.md                 # 测试说明文档\n├── .env.example                  # 环境变量示例文件\n├── .gitignore                    # Git忽略文件\n├── docker-compose.yml            # Docker Compose配置\n├── Dockerfile                    # Docker构建文件\n├── LICENSE                       # 许可证文件\n├── README.md                     # 项目说明文档\n├── requirements.txt              # 项目依赖\n└── run.py                        # 应用启动脚本\n```\n\n## 🔧 配置说明\n\n### 上传发票\n\n1. 点击左侧导航栏中的\"上传发票\"\n2. 选择一个项目分类（可选）\n3. 拖拽发票图片或PDF文件到上传区域，或点击选择文件\n4. 系统会自动识别并处理发票内容（对于PDF文件，会识别第一页）\n5. 上传后自动跳转到发票详情页进行查看和编辑\n\n### 项目管理\n\n1. 点击左侧导航栏中的\"项目管理\"\n2. 可以创建、编辑、删除项目\n3. 点击项目卡片查看该项目下的所有发票\n4. 未分类发票会显示在\"未分类\"区域\n\n### 查看发票列表\n\n- 在首页可以看到所有上传的发票列表\n- 可以通过点击表头排序发票\n- 控制台上方显示统计数据和图表\n- 可以根据项目筛选发票列表\n\n### 发票详情与编辑\n\n- 点击发票列表中的发票行即可查看详情\n- 点击发票图片可以在弹窗中查看大图，支持放大缩小功能\n- 对于PDF文件，会显示PDF阅读器方便查看\n- 点击\"编辑\"按钮修改发票信息，所有金额字段会自动处理货币符号\n- 点击\"删除\"按钮删除发票\n\n### 导出功能\n\n在发票详情页，可以选择导出格式（CSV或Excel）导出发票数据。\n在项目详情页，可以导出整个项目的发票数据为Excel。\n\n### 清理导出文件\n\n首页提供\"清理导出文件\"按钮，可以手动清理已导出的临时文件。\n系统还会自动定期（每天凌晨3点）清理过期的导出文件。\n\n## 🛠️ 开发者指南\n\n### GitHub Actions 配置\n\n本项目使用GitHub Actions自动构建和发布Docker镜像。如果您fork了本项目并希望启用自动构建，需要配置以下GitHub Secrets:\n\n#### 1. 访问GitHub仓库设置\n\n- 前往您的GitHub仓库\n- 点击顶部的\"Settings\"选项卡\n- 在左侧菜单中找到\"Security\"部分下的\"Secrets and variables\"\n- 选择\"Actions\"\n\n#### 2. 添加必要的Secrets\n\n需要添加以下Secret以启用Docker Hub发布:\n\n| Secret名称 | 说明 | 获取方式 |\n|----------|------|---------|\n| `DOCKERHUB_USERNAME` | Docker Hub用户名 | 您的Docker Hub账号用户名 |\n| `DOCKERHUB_TOKEN` | Docker Hub访问令牌 | 在Docker Hub → Account Settings → Security中创建 |\n\n#### 3. 获取Docker Hub访问令牌\n\n1. 登录[Docker Hub](https://hub.docker.com/)\n2. 点击右上角头像 → Account Settings → Security\n3. 点击\"New Access Token\"按钮\n4. 输入描述（如\"GitHub Actions\"）\n5. 选择适当的权限（至少需要\"Read \u0026 Write\"权限）\n6. 点击\"Generate\"生成令牌\n7. **重要**: 立即复制生成的令牌，它只会显示一次\n\n#### 4. 验证配置\n\n配置完成后，每次发布新Release或手动触发工作流时，将自动构建并推送Docker镜像到您的Docker Hub账号。\n\n## 📝 许可证\n\nMIT License \n\n## 👤 作者\n\n- [chiupam](https://github.com/chiupam)\n\n## 🙏 致谢\n\n感谢您的使用和反馈！如果您有任何问题或建议，请随时联系我们。 ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchiupam%2Finvoiceocr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchiupam%2Finvoiceocr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchiupam%2Finvoiceocr/lists"}