# Invoice Master - Fortnox Integration Technical Specification **版本**: v1.0 **日期**: 2026-02-01 **作者**: Claude Code **状态**: 设计阶段 --- ## 目录 1. [概述](#概述) 2. [集成模式说明](#集成模式说明) 3. [系统架构](#系统架构) 4. [Fortnox API分析](#fortnox-api分析) 5. [数据映射设计](#数据映射设计) 6. [核心功能模块](#核心功能模块) 7. [用户流程设计](#用户流程设计) 8. [UI设计规范](#ui设计规范) 9. [API设计](#api设计) 10. [数据库设计](#数据库设计) 11. [安全设计](#安全设计) 12. [错误处理](#错误处理) 13. [开发计划](#开发计划) 14. [测试策略](#测试策略) 15. [部署方案](#部署方案) 16. [附录](#附录) --- ## 概述 ### 1.1 项目背景 Invoice Master是一个基于YOLOv11 + PaddleOCR的发票字段自动提取系统，当前准确率达到94.8%。本方案设计将Invoice Master作为Fortnox会计软件的插件/扩展，实现无缝的发票数据导入功能。 ### 1.2 目标 - 为Fortnox用户提供智能发票识别功能 - 实现一键将发票数据导入Fortnox - 自动匹配供应商和会计科目 - 减少90%的手动录入工作 ### 1.3 范围 **包含功能:** - Fortnox OAuth2认证集成 - 发票PDF上传和OCR识别 - 供应商自动匹配/创建 - 会计凭证(Voucher)自动生成 - 发票图像存档 **不包含功能 (Phase 2):** - 多文档类型支持 (收据、对账单) - 自动付款流程 - 审批工作流 ### 1.4 术语定义 | 术语 | 英文 | 说明 | |------|------|------| | 供应商 | Supplier | Leverantör i Fortnox | | 会计凭证 | Voucher | Verifikation i Fortnox | | 发票 | Invoice | Faktura | | 科目 | Account | Konto i kontoplanen | | OCR参考号 | OCR Number | 瑞典特有的付款参考号 | --- ## 集成模式说明 ### 2.1 Fortnox Extension UI模式 Fortnox的集成主要有**两种模式**，Invoice Master采用**模式1: 外部独立应用**。 #### 模式1: 外部独立应用 (External App) - 推荐 **架构示意图:** ``` 用户流程: ┌─────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │ Fortnox │────▶│ Invoice Master │────▶│ Fortnox │ │ (点击集成) │ │ (独立Web应用) │ │ (数据已导入) │ └─────────────────┘ └─────────────────────┘ └─────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ 在Fortnox中 用户在你的网站上 用户回到Fortnox 看到"Invoice Master" 完成发票上传和识别 查看已导入的凭证 点击打开新窗口 ``` **特点:** - ✅ **有自己的完整UI**（独立网站） - ✅ 通过OAuth2连接Fortnox - ✅ 用户在Fortnox点击后跳转到你的网站 - ✅ 数据通过API双向同步 - ✅ 更灵活的功能和用户体验 **Fortnox中的展示:** - 在Fortnox Integrations页面列出 - 用户点击后打开新标签页到你的网站 - 显示连接状态和基本设置 #### 模式2: 嵌入式集成 (Embedded) - 有限支持 **Fortnox目前支持:** - 菜单链接 (Menu Links) - 在Fortnox菜单中添加链接 - 快捷操作 (Quick Actions) - 有限的上下文操作 - 文件导入 (File Import) - 通过Inbox API **Fortnox不提供:** - ❌ iframe嵌入第三方UI - ❌ 自定义页面/标签 - ❌ 深度UI定制 ### 2.2 推荐方案: 混合模式 **架构设计:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ Invoice Master for Fortnox │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 独立Web应用 (你的域名) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ 发票上传 │ │ 识别结果 │ │ 历史记录 │ │ │ │ │ │ 页面 │ │ 确认页面 │ │ 页面 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ 功能: OCR识别、供应商匹配、预览确认、一键导入Fortnox │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ │ HTTPS API │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Fortnox Integration Service │ │ │ │ (Backend API) │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ └──────────────────────────────┼───────────────────────────────────┘ │ │ OAuth2 + REST API │ ┌──────────▼──────────┐ │ Fortnox │ │ (数据存储/展示) │ └─────────────────────┘ ``` ### 2.3 与纯API方案对比 | 特性 | 独立UI方案 (推荐) | 纯API方案 | |------|------------------|-----------| | **用户体验** | ⭐⭐⭐⭐⭐ 完整的可视化界面 | ⭐⭐ 需要用户自己调用API | | **开发复杂度** | ⭐⭐⭐ 需要前端+后端 | ⭐⭐ 只需要后端API | | **功能灵活性** | ⭐⭐⭐⭐⭐ 可以做OCR预览、编辑 | ⭐⭐ 直接导入，无法预览 | | **用户门槛** | ⭐⭐⭐⭐⭐ 低，非技术用户可用 | ⭐ 高，需要开发者 | | **Fortnox审核** | ⭐⭐⭐⭐ 标准流程 | ⭐⭐⭐⭐ 更简单 | ### 2.4 用户完整流程 ``` 1. 发现阶段 用户在Fortnox Integrations页面找到"Invoice Master" 2. 授权阶段 用户点击"连接" → OAuth2授权 → 跳转到Invoice Master 3. 使用阶段 (在Invoice Master网站) 上传PDF → OCR识别 → 确认/编辑 → 导入到Fortnox 4. 查看阶段 (回到Fortnox) 用户在Fortnox中查看已导入的凭证和发票 ``` --- ## 系统架构 ### 3.1 整体架构图 **注意: 这是技术架构图，对应第2章描述的"独立Web应用"模式** ``` ┌─────────────────────────────────────────────────────────────────┐ │ Fortnox Platform │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Fortnox │ │ Fortnox │ │ Fortnox │ │ │ │ UI │ │ API │ │ Database │ │ │ └──────┬───────┘ └──────┬───────┘ └──────────────┘ │ └─────────┼─────────────────┼─────────────────────────────────────┘ │ │ │ OAuth2 │ HTTPS │ │ ┌─────────▼─────────────────▼─────────────────────────────────────┐ │ Invoice Master Integration │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Fortnox Integration Service │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │ Auth │ │ Invoice │ │ Supplier │ │ │ │ │ │ Module │ │ Handler │ │ Matcher │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │ Voucher │ │ File │ │ Webhook │ │ │ │ │ │ Creator │ │ Storage │ │ Handler │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Invoice Master Core Services │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │ OCR │ │ YOLO │ │ Field │ │ │ │ │ │ Engine │ │ Detector │ │Normalizer │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ │ PostgreSQL / Azure Blob │ ┌─────────▼─────────────────────────────────────────────────────┐ │ Data Storage │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Invoice │ │ Fortnox │ │ File │ │ │ │ Data │ │ Tokens │ │ Storage │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 3.2 组件说明 | 组件 | 技术栈 | 职责 | |------|--------|------| | **Integration Service** | FastAPI + Python | Fortnox API交互、业务逻辑 | | **Auth Module** | OAuth2 + JWT | Fortnox认证、Token管理 | | **Invoice Handler** | - | 发票处理流程协调 | | **Supplier Matcher** | Fuzzy Matching | 供应商匹配算法 | | **Voucher Creator** | - | 生成Fortnox会计凭证 | | **File Storage** | Azure Blob / S3 | 发票PDF存储 | | **Webhook Handler** | - | 接收Fortnox事件 | ### 3.3 技术栈 | 层级 | 技术 | 说明 | |------|------|------| | **Backend** | FastAPI + Python 3.11 | API服务 | | **Database** | PostgreSQL 15 | 关系数据 | | **Cache** | Redis | Token缓存、限流 | | **Storage** | Azure Blob Storage | 文件存储 | | **Message Queue** | Redis Queue | 异步任务 | | **Monitoring** | Prometheus + Grafana | 监控告警 | --- ## Fortnox API分析 ### 3.1 认证机制 Fortnox使用OAuth2授权码流程: ``` ┌─────────┐ ┌─────────────┐ │ User │──(1) Authorization Request───────▶│ Fortnox │ │ │◀──(2) Authorization Code─────────│ OAuth2 │ │ │ │ Server │ │ │──(3) Token Request────────────────▶│ │ │ │◀──(4) Access + Refresh Token──────│ │ └─────────┘ └─────────────┘ ``` **关键端点:** ``` Authorization URL: https://apps.fortnox.se/oauth-v1/auth Token URL: https://apps.fortnox.se/oauth-v1/token API Base URL: https://api.fortnox.se/3 ``` **Scopes Required:** ``` supplier - 供应商管理 invoice - 发票管理 (如需要) voucher - 会计凭证 account - 会计科目 companyinformation - 公司信息 ``` ### 3.2 核心API端点 #### 3.2.1 供应商管理 ```http # 获取供应商列表 GET /3/suppliers Response: { "Suppliers": [ { "@url": "https://api.fortnox.se/3/suppliers/123", "Name": "ABC Company", "SupplierNumber": "123", "OrganisationNumber": "556677-8899" } ] } # 创建供应商 POST /3/suppliers Body: { "Supplier": { "Name": "New Supplier", "OrganisationNumber": "112233-4455" } } ``` #### 3.2.2 会计凭证 (Voucher) ```http # 创建会计凭证 POST /3/vouchers Body: { "Voucher": { "VoucherSeries": "A", // 凭证系列 "TransactionDate": "2024-01-15", // 交易日期 "VoucherRows": [ { "Account": 2440, // 应付账款科目 "Debit": 1250.00, "Credit": 0, "Description": "Invoice F2024-001" }, { "Account": 5460, // 费用科目 "Debit": 0, "Credit": 1000.00, "Description": "Office supplies" }, { "Account": 2610, // 增值税科目 "Debit": 0, "Credit": 250.00, "Description": "VAT 25%" } ] } } ``` #### 3.2.3 文件上传 ```http # 上传附件到Fortnox POST /3/inbox Content-Type: multipart/form-data Body: { "file": [PDF file], "name": "Invoice_F2024_001.pdf" } ``` ### 3.3 API限制 | 限制类型 | 值 | 说明 | |---------|-----|------| | 速率限制 | 300请求/分钟 | 超出返回429 | | 并发连接 | 10 | 同时连接数 | | Token有效期 | 3600秒 | 需使用Refresh Token | | 文件大小 | 10MB | 单个文件限制 | --- ## 数据映射设计 ### 4.1 发票字段映射 **Invoice Master提取字段 → Fortnox字段** | Invoice Master | Fortnox | 类型 | 必填 | 转换逻辑 | |---------------|---------|------|------|----------| | `invoice_number` | `ExternalInvoiceNumber` | string | 是 | 直接映射 | | `invoice_date` | `TransactionDate` | date | 是 | ISO 8601格式 | | `due_date` | `DueDate` | date | 否 | 计算或提取 | | `supplier_name` | `SupplierName` | string | 是 | 匹配或创建 | | `supplier_org_number` | `SupplierOrganisationNumber` | string | 否 | 用于匹配 | | `amount_total` | `TotalAmount` | decimal | 是 | 直接映射 | | `amount_vat` | `VatAmount` | decimal | 否 | 计算得出 | | `ocr_number` | `OCRNumber` | string | 否 | 瑞典特有 | | `bankgiro` | `BankgiroNumber` | string | 否 | 付款信息 | | `plusgiro` | `PlusgiroNumber` | string | 否 | 付款信息 | | `currency` | `Currency` | string | 是 | 默认SEK | ### 4.2 会计科目映射 **默认科目映射表 (Kontoplan BAS2024)** | 费用类型 | 科目代码 | 科目名称 | 说明 | |---------|---------|---------|------| | 应付账款 | 2440 | Leverantörsskulder | 默认贷方 | | 办公用品 | 5460 | Kontorsmaterial | 常见费用 | | 咨询服务 | 6210 | Konsultarvoden | 外部服务 | | 运输费 | 5710 | Frakter | 物流费用 | | 增值税进项 | 2610 | Ingående moms | 25% VAT | | 增值税进项12% | 2620 | Ingående moms 12% | 食品等 | | 增值税进项6% | 2630 | Ingående moms 6% | 交通等 | **科目选择逻辑:** ```python def select_account(invoice_data: dict) -> int: """根据发票内容选择会计科目""" # 1. 检查是否有历史映射 if invoice_data['supplier_org_number']: historical = get_historical_account(invoice_data['supplier_org_number']) if historical: return historical # 2. 关键词匹配 description = invoice_data.get('description', '').lower() if any(word in description for word in ['kontor', 'papper', 'penna']): return 5460 # 办公用品 elif any(word in description for word in ['konsult', 'tjänst']): return 6210 # 咨询服务 elif any(word in description for word in ['frakt', 'transport']): return 5710 # 运输费 # 3. 默认科目 return 6100 # 其他外部费用 ``` ### 4.3 供应商匹配算法 **匹配优先级:** ```python class SupplierMatcher: def match_supplier(self, extracted_data: dict) -> MatchResult: """ 供应商匹配算法 返回: (supplier_number, confidence_score, action) """ # 1. 组织号精确匹配 (权重: 100%) if extracted_data.get('supplier_org_number'): exact_match = self.find_by_org_number( extracted_data['supplier_org_number'] ) if exact_match: return MatchResult( supplier_number=exact_match.number, confidence=1.0, action='USE_EXISTING' ) # 2. 名称模糊匹配 (权重: 80%) name_matches = self.fuzzy_match_name( extracted_data['supplier_name'], threshold=0.85 ) if name_matches and name_matches[0].score > 0.9: return MatchResult( supplier_number=name_matches[0].number, confidence=name_matches[0].score, action='USE_EXISTING' ) # 3. 建议创建新供应商 (权重: <80%) return MatchResult( supplier_number=None, confidence=0.0, action='CREATE_NEW', suggested_name=extracted_data['supplier_name'] ) ``` --- ## 核心功能模块 ### 5.1 认证模块 (Auth Module) **职责:** - Fortnox OAuth2流程管理 - Token存储和刷新 - 多租户隔离 **核心类:** ```python class FortnoxAuthManager: """Fortnox认证管理器""" def __init__(self, client_id: str, client_secret: str): self.client_id = client_id self.client_secret = client_secret self.token_store = TokenStore() def get_authorization_url(self, state: str) -> str: """生成Fortnox授权URL""" params = { 'client_id': self.client_id, 'redirect_uri': settings.FORTNOX_REDIRECT_URI, 'scope': 'supplier voucher account companyinformation', 'state': state, 'response_type': 'code' } return f"{FORTNOX_AUTH_URL}?{urlencode(params)}" async def exchange_code_for_token(self, code: str) -> FortnoxToken: """用授权码换取Token""" response = await httpx.post( FORTNOX_TOKEN_URL, auth=(self.client_id, self.client_secret), data={ 'grant_type': 'authorization_code', 'code': code, 'redirect_uri': settings.FORTNOX_REDIRECT_URI } ) token_data = response.json() return FortnoxToken( access_token=token_data['access_token'], refresh_token=token_data['refresh_token'], expires_at=datetime.utcnow() + timedelta(seconds=token_data['expires_in']), scope=token_data['scope'] ) async def get_valid_access_token(self, tenant_id: str) -> str: """获取有效的访问Token（自动刷新）""" token = await self.token_store.get(tenant_id) if token.is_expired(): token = await self.refresh_token(token.refresh_token) await self.token_store.save(tenant_id, token) return token.access_token ``` ### 5.2 发票处理模块 (Invoice Handler) **处理流程:** ```python class InvoiceProcessingService: """发票处理服务""" async def process_invoice( self, tenant_id: str, pdf_file: UploadFile, settings: ProcessingSettings ) -> ProcessingResult: """ 处理发票的主流程 """ # 1. 保存PDF文件 file_path = await self.file_storage.save(pdf_file) # 2. OCR提取 extraction_result = await self.ocr_service.extract(file_path) # 3. 验证提取结果 if not self.validate_extraction(extraction_result): return ProcessingResult( status='FAILED', error='Extraction validation failed' ) # 4. 供应商匹配 supplier_match = await self.supplier_matcher.match( tenant_id, extraction_result ) # 5. 创建或获取供应商 if supplier_match.action == 'CREATE_NEW': supplier_number = await self.create_supplier( tenant_id, extraction_result ) else: supplier_number = supplier_match.supplier_number # 6. 生成会计凭证 voucher = await self.voucher_creator.create( tenant_id, extraction_result, supplier_number, settings ) # 7. 上传附件 if settings.attach_pdf: await self.attach_invoice_pdf(tenant_id, voucher.id, file_path) return ProcessingResult( status='SUCCESS', extraction=extraction_result, supplier_number=supplier_number, voucher_id=voucher.id, confidence=supplier_match.confidence ) ``` ### 5.3 供应商匹配模块 (Supplier Matcher) ```python class FortnoxSupplierMatcher: """Fortnox供应商匹配器""" def __init__(self, fortnox_client: FortnoxClient): self.client = fortnox_client self.cache = SupplierCache() async def match( self, tenant_id: str, extraction: ExtractionResult ) -> SupplierMatchResult: """匹配供应商""" # 获取所有供应商（带缓存） suppliers = await self.cache.get_suppliers(tenant_id) # 1. 组织号精确匹配 if extraction.supplier_org_number: match = self._match_by_org_number( suppliers, extraction.supplier_org_number ) if match: return SupplierMatchResult( supplier_number=match['SupplierNumber'], confidence=1.0, action='USE_EXISTING' ) # 2. 名称模糊匹配 name_match = self._fuzzy_match_name( suppliers, extraction.supplier_name ) if name_match and name_match['score'] > 0.9: return SupplierMatchResult( supplier_number=name_match['supplier']['SupplierNumber'], confidence=name_match['score'], action='USE_EXISTING' ) elif name_match and name_match['score'] > 0.7: return SupplierMatchResult( supplier_number=name_match['supplier']['SupplierNumber'], confidence=name_match['score'], action='SUGGEST_MATCH', suggested_name=extraction.supplier_name ) # 3. 建议创建新供应商 return SupplierMatchResult( supplier_number=None, confidence=0.0, action='CREATE_NEW', suggested_name=extraction.supplier_name, suggested_org_number=extraction.supplier_org_number ) async def create_supplier( self, tenant_id: str, extraction: ExtractionResult ) -> str: """在Fortnox中创建新供应商""" supplier_data = { 'Supplier': { 'Name': extraction.supplier_name, 'OrganisationNumber': extraction.supplier_org_number, 'Address1': extraction.supplier_address, 'Phone': extraction.supplier_phone, 'Email': extraction.supplier_email, 'BankgiroNumber': extraction.bankgiro, 'PlusgiroNumber': extraction.plusgiro } } response = await self.client.post( tenant_id, '/3/suppliers', json=supplier_data ) # 刷新缓存 await self.cache.invalidate(tenant_id) return response['Supplier']['SupplierNumber'] ``` ### 5.4 凭证生成模块 (Voucher Creator) ```python class FortnoxVoucherCreator: """Fortnox会计凭证生成器""" async def create_voucher( self, tenant_id: str, extraction: ExtractionResult, supplier_number: str, settings: VoucherSettings ) -> VoucherResult: """创建会计凭证""" # 确定会计科目 account = await self.select_account(extraction) # 计算VAT vat_amount = self.calculate_vat( extraction.amount_total, extraction.vat_rate or 25 ) amount_excl_vat = extraction.amount_total - vat_amount # 构建凭证行 voucher_rows = [ # 借方: 费用科目 { 'Account': account, 'Debit': amount_excl_vat, 'Credit': 0, 'Description': f"{extraction.supplier_name} - {extraction.invoice_number}", 'Project': settings.project_code }, # 借方: 增值税 { 'Account': self.get_vat_account(extraction.vat_rate), 'Debit': vat_amount, 'Credit': 0, 'Description': f"Moms {extraction.vat_rate}%" }, # 贷方: 应付账款 { 'Account': 2440, # Leverantörsskulder 'Debit': 0, 'Credit': extraction.amount_total, 'Description': f"Faktura {extraction.invoice_number}", 'SupplierNumber': supplier_number, 'OCRNumber': extraction.ocr_number } ] voucher_data = { 'Voucher': { 'VoucherSeries': settings.voucher_series or 'A', 'TransactionDate': extraction.invoice_date.isoformat(), 'VoucherText': f"Inköp {extraction.supplier_name}", 'VoucherRows': voucher_rows } } response = await self.client.post( tenant_id, '/3/vouchers', json=voucher_data ) return VoucherResult( voucher_id=response['Voucher']['VoucherNumber'], series=response['Voucher']['VoucherSeries'], url=response['Voucher']['@url'] ) ``` --- ## 用户流程设计 ### 6.1 集成入口点 (在Fortnox中) **Fortnox Integrations页面展示:** ``` ┌─────────────────────────────────────────────────────────────┐ │ Invoice Master - Smart Invoice OCR │ │ │ │ 📄 自动识别发票信息 │ │ 🤖 AI驱动的OCR技术 │ │ ⚡ 一键导入到Fortnox │ │ │ │ [连接/打开] │ └─────────────────────────────────────────────────────────────┘ ``` **Fortnox内配置页面:** ``` ┌─────────────────────────────────────────────────────────────┐ │ Invoice Master 设置 │ │ │ │ 状态: ✅ 已连接 │ │ 公司: My Company AB │ │ │ │ 默认设置: │ │ - 凭证系列: [A ▼] │ │ - 自动导入: [✓] │ │ - 附件上传: [✓] │ │ │ │ [保存设置] [断开连接] │ └─────────────────────────────────────────────────────────────┘ ``` ### 6.2 首次设置流程 ``` 用户点击"连接Fortnox" │ ▼ ┌───────────────────┐ │ 跳转到Fortnox授权页 │ │ (OAuth2流程) │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 用户登录Fortnox │ │ 并授权访问 │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 返回到Invoice │ │ Master回调页面 │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 获取公司信息 │ │ 验证连接成功 │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 配置默认设置 │ │ - 凭证系列 │ │ - 默认科目 │ │ - 文件存储选项 │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 完成！显示 │ │ 上传发票界面 │ └───────────────────┘ ``` ### 6.2 发票处理流程 ``` 用户上传PDF发票 │ ▼ ┌───────────────────┐ │ 显示处理进度 │ │ - OCR提取中... │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 显示提取结果 │ │ 供用户确认/编辑 │ │ │ │ ┌───────────────┐ │ │ │ 供应商: XXX │ │ │ │ 金额: 1,250 │ │ │ │ 日期: 2024... │ │ │ │ [编辑] [确认] │ │ │ └───────────────┘ │ └─────────┬─────────┘ │ ┌─────┴─────┐ │ │ ▼ ▼ ┌────────┐ ┌────────┐ │ 编辑 │ │ 确认 │ │ 数据 │ │ 导入 │ └───┬────┘ └───┬────┘ │ │ └─────┬─────┘ │ ▼ ┌───────────────────┐ │ 供应商匹配 │ │ - 查找现有 │ │ - 或创建新 │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 生成会计凭证 │ │ 上传到Fortnox │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 显示成功消息 │ │ 提供Fortnox链接 │ │ 查看凭证 │ └───────────────────┘ ``` ### 6.4 独立Web应用UI设计 **重要说明: 以下UI是Invoice Master独立Web应用的界面，用户在Fortnox点击"打开"后跳转到此界面。** #### 主界面 #### 主界面 ``` ┌─────────────────────────────────────────────────────────────┐ │ Invoice Master for Fortnox [⚙️设置] [?] │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 📤 上传发票 │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ 拖放PDF文件到这里 │ │ │ │ 或点击选择文件 │ │ │ │ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ 📋 最近处理的发票 │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ 文件名 │ 供应商 │ 金额 │ 状态 │ │ │ ├───────────────────────────────────────────────────────┤ │ │ │ INV001.pdf │ ABC Company │ 1,250 │ ✅ 已导入 │ │ │ │ INV002.pdf │ XYZ AB │ 3,450 │ ✅ 已导入 │ │ │ │ INV003.pdf │ (未匹配) │ 890 │ ⚠️ 待确认 │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` #### 结果确认界面 **说明: 此界面在Invoice Master独立Web应用中显示，用于用户确认OCR识别结果。 ``` ┌─────────────────────────────────────────────────────────────┐ │ 确认发票信息 [✕] [✓] │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 📄 Invoice_F2024_001.pdf │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ 供应商信息 │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ 名称: ABC Company │ │ │ │ │ │ 组织号: 556677-8899 │ │ │ │ │ │ 状态: ✅ 已匹配现有供应商 │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ 发票信息 │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ 发票号: F2024-001 │ │ │ │ │ │ 日期: 2024-01-15 │ │ │ │ │ │ 到期日: 2024-02-15 │ │ │ │ │ │ 金额: 1,250.00 SEK │ │ │ │ │ │ OCR: 7350012345678 │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ 会计科目 │ │ │ │ 借方: 5460 - Kontorsmaterial 1,000.00 │ │ │ │ 借方: 2610 - Ingående moms 250.00 │ │ │ │ 贷方: 2440 - Leverantörsskulder 1,250.00 │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ [编辑信息] [重新识别] [取消] [确认并导入到Fortnox] │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## UI设计规范 ### 7.1 设计原则 **独立Web应用设计原则:** 1. **品牌一致性**: 保持Invoice Master品牌，同时尊重Fortnox用户习惯 2. **简洁高效**: 发票处理是高频操作，界面必须简洁快速 3. **清晰反馈**: OCR识别结果必须清晰展示，便于用户确认 4. **无缝集成**: 虽然是独立应用，但要让用户感觉与Fortnox是一体的 ### 7.2 响应式设计 **断点定义:** | 断点 | 宽度 | 布局 | |------|------|------| | Mobile | < 768px | 单列，堆叠布局 | | Tablet | 768px - 1024px | 双列布局 | | Desktop | > 1024px | 三列布局 | ### 7.3 组件规范 #### 文件上传区域 ``` ┌─────────────────────────────────────────────────────────────┐ │ 📤 上传发票 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ 📄 拖放PDF文件到这里 │ │ │ │ │ │ │ │ 或点击选择 │ │ │ │ │ │ │ │ 支持格式: PDF, JPG, PNG (最大10MB) │ │ │ │ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **交互状态:** - 默认: 灰色边框，虚线 - 悬停: 蓝色边框，背景变浅蓝 - 拖入: 蓝色边框，背景变深蓝 - 上传中: 显示进度条 #### 发票卡片 ``` ┌─────────────────────────────────────────────────────────────┐ │ 📄 Invoice_F2024_001.pdf [✓] [✏️] [🗑️]│ ├─────────────────────────────────────────────────────────────┤ │ │ │ 供应商: ABC Company (556677-8899) │ │ 金额: 1,250.00 SEK │ │ 日期: 2024-01-15 │ │ │ │ 状态: ✅ 已导入到Fortnox │ │ 凭证: A-1234 [在Fortnox中查看] │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 7.4 颜色规范 **主色调:** | 用途 | 颜色 | Hex | |------|------|-----| | 主色 | 蓝色 | #2563EB | | 成功 | 绿色 | #10B981 | | 警告 | 黄色 | #F59E0B | | 错误 | 红色 | #EF4444 | | 背景 | 浅灰 | #F9FAFB | | 文字 | 深灰 | #1F2937 | **Fortnox品牌协调:** - 使用Fortnox的蓝色作为次要色 (#0057FF) - 在"导入到Fortnox"按钮中使用Fortnox品牌色 ### 7.5 字体规范 | 元素 | 字体 | 大小 | 字重 | |------|------|------|------| | 标题 | Inter | 24px | 600 | | 副标题 | Inter | 18px | 500 | | 正文 | Inter | 14px | 400 | | 小字 | Inter | 12px | 400 | | 数字 | Inter | 16px | 600 (等宽) | --- ## API设计 ### 8.1 REST API端点 #### 认证相关 ```http # 获取Fortnox授权URL GET /api/v1/fortnox/auth/url Response: { "authorization_url": "https://apps.fortnox.se/oauth-v1/auth?...", "state": "random_state_string" } # OAuth回调处理 GET /api/v1/fortnox/auth/callback?code=xxx&state=xxx Response: { "status": "success", "company_name": "My Company AB", "connected_at": "2024-01-15T10:30:00Z" } # 断开连接 DELETE /api/v1/fortnox/auth Response: { "status": "disconnected" } ``` #### 发票处理 ```http # 上传并处理发票 POST /api/v1/fortnox/invoices Content-Type: multipart/form-data Body: { "file": [PDF file], "auto_import": false, // 是否自动导入，false则返回预览 "settings": { "voucher_series": "A", "attach_pdf": true } } Response (预览模式): { "id": "uuid", "status": "preview", "extraction": { "supplier_name": "ABC Company", "supplier_org_number": "556677-8899", "invoice_number": "F2024-001", "invoice_date": "2024-01-15", "amount_total": 1250.00, "ocr_number": "7350012345678" }, "supplier_match": { "action": "USE_EXISTING", "supplier_number": "123", "confidence": 1.0 }, "voucher_preview": { "rows": [...] } } Response (自动导入模式): { "id": "uuid", "status": "imported", "voucher": { "voucher_number": "1234", "series": "A", "url": "https://api.fortnox.se/3/vouchers/A/1234" }, "fortnox_url": "https://apps.fortnox.se/..." } ``` #### 供应商管理 ```http # 获取Fortnox供应商列表 GET /api/v1/fortnox/suppliers Response: { "suppliers": [ { "supplier_number": "123", "name": "ABC Company", "organisation_number": "556677-8899" } ] } # 创建供应商 POST /api/v1/fortnox/suppliers Body: { "name": "New Supplier", "organisation_number": "112233-4455", "address": "..." } ``` ### 8.2 Webhook接收 ```http # Fortnox Webhook接收端点 POST /webhooks/fortnox Headers: { "X-Fortnox-Event": "voucher.created" } Body: { "event": "voucher.created", "data": { "voucher_number": "1234", "series": "A" } } ``` --- ## 数据库设计 ### 9.1 实体关系图 ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ fortnox_tenants │ │ fortnox_invoices │ │ supplier_cache │ ├─────────────────┤ ├──────────────────┤ ├─────────────────┤ │ id (PK) │◄──────┤ id (PK) │ │ id (PK) │ │ organization_id │ │ tenant_id (FK) │ │ tenant_id (FK) │ │ access_token │ │ file_path │ │ supplier_number │ │ refresh_token │ │ extraction_data │ │ name │ │ expires_at │ │ voucher_id │ │ org_number │ │ company_name │ │ status │ │ cached_at │ │ created_at │ │ created_at │ └─────────────────┘ └─────────────────┘ └──────────────────┘ │ │ ┌──────────────────┐ │ │ processing_queue │ │ ├──────────────────┤ └────────►│ id (PK) │ │ invoice_id (FK) │ │ status │ │ retry_count │ └──────────────────┘ ``` ### 9.2 SQL Schema ```sql -- Fortnox租户表 CREATE TABLE fortnox_tenants ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), organization_id UUID NOT NULL REFERENCES organizations(id), -- OAuth Tokens access_token TEXT NOT NULL, refresh_token TEXT NOT NULL, expires_at TIMESTAMP NOT NULL, scope TEXT, -- 公司信息 company_name VARCHAR(255), company_org_number VARCHAR(20), -- 设置 default_voucher_series VARCHAR(10) DEFAULT 'A', default_account_code INTEGER DEFAULT 5460, auto_attach_pdf BOOLEAN DEFAULT true, -- 状态 is_active BOOLEAN DEFAULT true, last_sync_at TIMESTAMP, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW(), UNIQUE(organization_id) ); -- Fortnox发票处理记录 CREATE TABLE fortnox_invoices ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL REFERENCES fortnox_tenants(id), -- 文件信息 original_filename VARCHAR(255), storage_path TEXT, file_size INTEGER, -- OCR提取结果 extraction_data JSONB, extraction_confidence DECIMAL(3,2), -- 供应商匹配 supplier_number VARCHAR(50), supplier_match_confidence DECIMAL(3,2), supplier_match_action VARCHAR(20), -- USE_EXISTING, CREATE_NEW, SUGGEST_MATCH -- Fortnox凭证 voucher_series VARCHAR(10), voucher_number VARCHAR(50), voucher_url TEXT, -- 处理状态 status VARCHAR(20) DEFAULT 'pending', -- pending, processing, preview, imported, failed error_message TEXT, -- 用户操作 reviewed_by UUID, reviewed_at TIMESTAMP, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW() ); -- 供应商缓存 CREATE TABLE supplier_cache ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL REFERENCES fortnox_tenants(id), supplier_number VARCHAR(50) NOT NULL, name VARCHAR(255), organisation_number VARCHAR(20), address TEXT, phone VARCHAR(50), email VARCHAR(255), cached_at TIMESTAMP DEFAULT NOW(), UNIQUE(tenant_id, supplier_number) ); -- 处理队列 CREATE TABLE processing_queue ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), invoice_id UUID NOT NULL REFERENCES fortnox_invoices(id), status VARCHAR(20) DEFAULT 'queued', -- queued, processing, completed, failed priority INTEGER DEFAULT 5, retry_count INTEGER DEFAULT 0, max_retries INTEGER DEFAULT 3, scheduled_at TIMESTAMP DEFAULT NOW(), started_at TIMESTAMP, completed_at TIMESTAMP, error_message TEXT ); -- 索引 CREATE INDEX idx_fortnox_invoices_tenant ON fortnox_invoices(tenant_id); CREATE INDEX idx_fortnox_invoices_status ON fortnox_invoices(status); CREATE INDEX idx_supplier_cache_tenant ON supplier_cache(tenant_id); CREATE INDEX idx_processing_queue_status ON processing_queue(status); ``` --- ## 安全设计 ### 10.1 认证安全 **Token存储:** - Access Token和Refresh Token使用AES-256加密存储 - 加密密钥存储在Azure Key Vault / AWS Secrets Manager - Token定期轮换 **OAuth安全:** - 使用state参数防止CSRF攻击 - 强制HTTPS回调 - 授权码一次性使用 ### 10.2 数据安全 **传输安全:** - 所有API通信强制TLS 1.3 - 证书固定(Certificate Pinning)防止中间人攻击 **存储安全:** - 发票PDF加密存储(AES-256) - 数据库连接使用SSL - 敏感字段加密(组织号、银行信息) ### 10.3 访问控制 ```python # 权限检查装饰器 async def require_fortnox_connection(func): @wraps(func) async def wrapper(request: Request, *args, **kwargs): tenant_id = request.headers.get('X-Tenant-ID') # 检查是否已连接Fortnox connection = await get_fortnox_connection(tenant_id) if not connection or not connection.is_active: raise HTTPException( status_code=401, detail="Fortnox connection required" ) # 检查Token是否有效 if connection.is_token_expired(): await refresh_fortnox_token(connection) return await func(request, *args, **kwargs) return wrapper ``` --- ## 错误处理 ### 11.1 错误分类 | 错误类型 | 示例 | 处理策略 | |---------|------|----------| | **认证错误** | Token过期、无效 | 自动刷新或提示重新授权 | | **API限制** | 429 Too Many Requests | 指数退避重试 | | **数据错误** | 无效的组织号格式 | 返回具体验证错误 | | **网络错误** | 连接超时 | 重试3次后失败 | | **业务错误** | 供应商不存在 | 提供创建选项 | ### 11.2 错误响应格式 ```json { "error": { "code": "FORTNOX_TOKEN_EXPIRED", "message": "Fortnox access token has expired", "details": { "action": "RECONNECT_REQUIRED", "reconnect_url": "/api/v1/fortnox/auth/url" }, "timestamp": "2024-01-15T10:30:00Z", "request_id": "req_123456" } } ``` ### 11.3 重试策略 ```python class FortnoxAPIRetry: """Fortnox API重试策略""" def __init__(self): self.max_retries = 3 self.base_delay = 1 # 秒 async def execute(self, func, *args, **kwargs): for attempt in range(self.max_retries): try: return await func(*args, **kwargs) except FortnoxAPIError as e: if e.status_code == 429: # Rate limit delay = self.base_delay * (2 ** attempt) await asyncio.sleep(delay) elif e.status_code in [500, 502, 503, 504]: if attempt < self.max_retries - 1: delay = self.base_delay * (2 ** attempt) await asyncio.sleep(delay) else: raise else: raise ``` --- ## 开发计划 ### 12.1 里程碑 | 阶段 | 时间 | 目标 | 交付物 | |------|------|------|--------| | **M1** | Week 1-2 | 基础架构 | 认证模块、数据库 | | **M2** | Week 3-4 | 核心功能 | 发票处理、供应商匹配 | | **M3** | Week 5-6 | Fortnox集成 | API集成、凭证创建 | | **M4** | Week 7-8 | UI开发 | 前端界面、用户流程 | | **M5** | Week 9-10 | 测试优化 | 测试、性能优化 | | **M6** | Week 11-12 | 上线准备 | 文档、审核、部署 | ### 12.2 任务分解 **Week 1-2: 基础架构** - [ ] 创建Fortnox开发者账号 - [ ] 设计数据库Schema - [ ] 实现OAuth2认证流程 - [ ] Token管理和刷新机制 - [ ] 基础API客户端 **Week 3-4: 核心功能** - [ ] 集成Invoice Master OCR - [ ] 实现供应商匹配算法 - [ ] 文件上传和存储 - [ ] 异步处理队列 **Week 5-6: Fortnox集成** - [ ] 供应商API集成 - [ ] 凭证创建逻辑 - [ ] 文件附件上传 - [ ] 错误处理和重试 **Week 7-8: UI开发** - [ ] 连接设置页面 - [ ] 发票上传界面 - [ ] 结果预览/编辑页面 - [ ] 历史记录页面 **Week 9-10: 测试优化** - [ ] 单元测试 (目标80%覆盖率) - [ ] 集成测试 - [ ] 性能测试 - [ ] 安全审计 **Week 11-12: 上线准备** - [ ] 用户文档 - [ ] API文档 - [ ] Fortnox审核申请 - [ ] 生产环境部署 --- ## 测试策略 ### 13.1 测试类型 | 测试类型 | 工具 | 覆盖率目标 | 说明 | |---------|------|-----------|------| | **单元测试** | pytest | 80% | 核心逻辑 | | **集成测试** | pytest + httpx | - | Fortnox API交互 | | **E2E测试** | Playwright | 核心流程 | 用户场景 | | **性能测试** | Locust | - | 并发处理 | | **安全测试** | bandit, safety | - | 漏洞扫描 | ### 13.2 测试用例示例 ```python # 供应商匹配测试 class TestSupplierMatcher: async def test_exact_org_number_match(self): """测试组织号精确匹配""" matcher = FortnoxSupplierMatcher(mock_client) result = await matcher.match( tenant_id="test", extraction=ExtractionResult( supplier_org_number="556677-8899" ) ) assert result.action == 'USE_EXISTING' assert result.confidence == 1.0 async def test_fuzzy_name_match(self): """测试名称模糊匹配""" result = await matcher.match( tenant_id="test", extraction=ExtractionResult( supplier_name="ABC Company AB" ) ) assert result.confidence > 0.85 # Fortnox API集成测试 class TestFortnoxIntegration: async def test_create_voucher(self): """测试创建会计凭证""" creator = FortnoxVoucherCreator(client) result = await creator.create_voucher( tenant_id="test", extraction=mock_extraction, supplier_number="123", settings=mock_settings ) assert result.voucher_id is not None ``` --- ## 部署方案 ### 14.1 架构部署图 ``` ┌─────────────────────────────────────────────────────────────┐ │ Azure │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Container │ │ PostgreSQL │ │ Blob │ │ │ │ Apps │ │ Flexible │ │ Storage │ │ │ │ (FastAPI) │ │ Server │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ └─────────────────┼─────────────────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ Redis │ │ │ │ Cache │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 14.2 资源配置 **Container Apps:** - CPU: 1 vCPU - Memory: 2 GiB - Min replicas: 1 - Max replicas: 5 **PostgreSQL:** - SKU: Standard_B1ms - Storage: 32 GB - Backup: 7 days **Blob Storage:** - Tier: Hot - Redundancy: LRS ### 14.3 部署流程 ```bash # 1. 基础设施部署 az group create --name invoice-master-rg --location swedencentral # 2. 数据库部署 az postgres flexible-server create \ --name invoice-master-db \ --resource-group invoice-master-rg \ --sku-name Standard_B1ms # 3. 应用部署 az containerapp create \ --name invoice-master-fortnox \ --resource-group invoice-master-rg \ --image invoicemaster.azurecr.io/fortnox-integration:latest \ --cpu 1 --memory 2Gi \ --min-replicas 1 --max-replicas 5 ``` --- ## 附录 ### A. Fortnox API参考 **常用端点速查:** | 功能 | 方法 | 端点 | |------|------|------| | 获取公司信息 | GET | /3/companyinformation | | 获取供应商列表 | GET | /3/suppliers | | 创建供应商 | POST | /3/suppliers | | 获取会计科目 | GET | /3/accounts | | 创建凭证 | POST | /3/vouchers | | 上传文件 | POST | /3/inbox | ### B. 科目表参考 (BAS2024) **常用费用科目:** | 代码 | 名称 | 说明 | |------|------|------| | 2440 | Leverantörsskulder | 应付账款 | | 2610 | Ingående moms | 进项VAT 25% | | 2620 | Ingående moms | 进项VAT 12% | | 2630 | Ingående moms | 进项VAT 6% | | 5460 | Kontorsmaterial | 办公用品 | | 5710 | Frakter | 运输费 | | 6100 | Övriga externa tjänster | 其他外部服务 | | 6210 | Konsultarvoden | 咨询费 | ### C. 错误代码表 | 代码 | 说明 | HTTP状态 | |------|------|---------| | FORTNOX_TOKEN_EXPIRED | Token过期 | 401 | | FORTNOX_RATE_LIMITED | 请求过于频繁 | 429 | | SUPPLIER_NOT_FOUND | 供应商不存在 | 404 | | INVALID_ORG_NUMBER | 无效的组织号 | 400 | | EXTRACTION_FAILED | OCR提取失败 | 422 | ### D. 相关链接 - [Fortnox Developer Portal](https://developer.fortnox.se/) - [Fortnox API Docs](https://api.fortnox.se/apidocs) - [BAS Kontoplan](https://www.bas.se/) --- **文档版本历史:** | 版本 | 日期 | 作者 | 变更说明 | |------|------|------|---------| | 1.0 | 2026-02-01 | Claude Code | 初始版本，添加Fortnox集成模式说明和UI设计规范 | --- **审批:** - [ ] 技术负责人 - [ ] 产品经理 - [ ] 安全团队