多租户自动化开票平台
MULTI-TENANT INVOICE PLATFORM
面向中小企业的电子发票 SaaS 平台 —— 一套系统服务多个租户，
API 对接即开即用，异步队列保证高可靠，全流程状态可追溯。
7
数据表
租户 / 密钥 / 发票 / 红冲 / 审计
8
API 端点
开票 / 红冲 / 查询 / 管理
3
异步 Worker
开票 / 红冲 / 超时恢复
2
服务商对接
fpapi + 诺诺（Provider 抽象层）
Architecture
架构设计
🏢 多租户隔离
共享数据库 + tenant_id 列实现租户数据隔离。每个请求通过中间件自动注入租户上下文，业务代码无需关心隔离逻辑。
🔐 双通道鉴权
外部系统使用 API Key（Bearer fk_live_xxx）调用开票接口；管理后台使用 JWT 认证。API Key 支持吊销，吊销后立即拒绝访问。
⚡ 异步队列
BullMQ + Redis 实现异步开票。API 接收后立即返回，Worker 后台处理。失败自动重试 3 次，超时 Cron 兜底恢复。
🔌 服务商抽象
Provider 接口抽象层，已实现 fpapi（射手科技）和诺诺（Nuonuo）两个服务商。工厂模式按租户配置自动路由，新增服务商只需实现接口。
Workflow
开票流程
📥
API 接收
外部系统通过 API Key 提交开票请求
→🔒
幂等校验
同一 requestId 不重复入库
→📋
入库排队
写入数据库 + 推入 BullMQ 队列
→⚙️
Worker 处理
异步调用税控服务商 SDK 开票
→✅
状态回写
更新发票状态 + 触发 Webhook 通知
→🔄
异常恢复
超时/失败自动重试，Cron 兜底
Screenshots
系统界面
仪表盘
管理员首页：发票总数、已开具、失败数、开票总额一目了然，右侧租户排行展示各租户开票量和金额。
租户管理
多租户管理界面：公司名称、税号、服务商类型、状态一览。支持新增租户、管理 API Key、暂停服务。
发票台账
全量发票记录：租户、购方、类型（普票/红票）、金额、发票号、状态（issued/timeout/failed），支持按状态筛选和手动重试。
开票测试
开票表单：选择租户和 API Key，填写发票类型、购方信息、商品明细（支持多行），实时计算含税合计，一键提交开票请求。
审计日志
完整操作审计：每次登录、API Key 创建/吊销、租户变更、开票操作都有记录，支持按操作类型筛选。
API Endpoints
接口一览
Data Model
数据模型
tenants
租户信息 + 服务商配置
api_keys
API Key 认证 + 吊销管理
invoices
发票主表（含状态机）
invoice_items
发票明细行
reversals
红冲/作废记录
webhook_events
回调事件日志
audit_logs
操作审计
Tech Stack
技术栈
Fastify 5
后端框架
TypeScript
类型安全
PostgreSQL 16
数据库
Drizzle ORM
数据访问层
BullMQ
异步队列
Redis 7
队列 & 缓存
Zod
请求验证
Docker
容器化部署