tekru-labs/elfatoora-middleware

# Elfatoora API 一个用于 TEIF（突尼斯电子发票格式）电子发票的中间件 API。该服务提供 JSON 验证、TEIF XML 生成、通过 ngsign 的数字签名、TTN（税务机构）提交、状态轮询、签名验证以及第三方 invoicing 系统的 Webhook 集成。 ## 概述 Elfatoora API 作为第三方 invoicing 系统与突尼斯电子发票基础设施之间的桥梁。它处理电子发票的完整生命周期，从验证到提交和跟踪。 ### 主要特性 - **JSON Schema 验证**：根据预定义模式验证发票文档 - **TEIF XML 生成**：将验证后的 JSON 发票转换为 TEIF XML 格式 - **数字签名**：与 ngsign 集成，对文档进行加密签名 - **TTN 提交**：通过 Web 服务或 SFTP 将签名后的发票提交给突尼斯税务机构（TTN） - **SFTP 支持**：用于发票上传和下载的安全文件传输 - **状态轮询**：用于跟踪发票处理状态的后台任务 - **签名验证**：验证已提交文档的数字签名 - **Webhook 支持**：通知第三方系统发票处理结果 ## 技术栈 - **运行时**：Node.js 24+ - **语言**：TypeScript - **包管理器**：pnpm 10.28.0 - **框架**：Express.js 5.2.1 - **数据库**：PostgreSQL 与 Kysely ORM - **验证**：Zod - **调度**：node-cron - **XML 处理**：fast-xml-parser ## 项目结构 ``` src/ ├── index.ts # Entry point ├── business-logic/ # Core business logic │ ├── auth/ # Authentication & token management │ ├── document/ # Document calculations and processing │ ├── ngsign/ # Digital signing integration │ ├── teif/ # TEIF XML generation and type definitions │ └── ttn/ # TTN integration │ ├── ws/ # Web service submission │ ├── sftp/ # SFTP file transfer for TTN │ └── ...workers # Background workers ├── controllers/ # Request handlers ├── cron/ # Scheduled jobs ├── db/ # Database client, migrations, and schema ├── routes/ # API route definitions ├── schemas/ # Zod validation schemas └── utils/ # Utility functions tests/ # Test files (co-located with source) docs/ # Documentation and WSDL files ``` ## 先决条件 - Node.js 24.0.0 或更高版本 - pnpm 10.28.0 或更高版本 - PostgreSQL 数据库 - 可访问 TTN Web 服务（生产环境） - 用于文档签名的 ngsign 凭据 ## 安装 ### 1. 克隆并设置 ``` git clone git@gitlab.tekru.net:tekru/elfatoora-api.git cd elfatoora-api pnpm install ``` ### 2. 环境配置 在根目录中创建 `.env` 文件并包含以下变量： ``` # 服务器 PORT=3000 NODE_ENV=development # 数据库 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/e_fatoura # 公共 URL PUBLIC_BASE_URL=http://localhost:3000 # 用于 /v1/clients 管理端点的全局 API 密钥 GLOBAL_API_KEY=replace-with-a-strong-secret ``` ### 3. 数据库设置 运行迁移以设置数据库模式： ``` pnpm run db:migrate ``` ## 用法 ### 开发 使用热重载启动开发服务器： ``` pnpm run dev ``` 服务器将在 http://localhost:3000 启动 ### 生产构建 ``` pnpm run build pnpm run start ``` ### 运行测试 ``` # 运行所有测试 pnpm test # 以监视模式运行测试 pnpm test:watch ``` ### 代码质量 ``` # 代码检查 pnpm run lint # 修复检查问题 pnpm run lint:fix ``` ## API 端点 ### 文档控制器 - `POST /v1/documents` - 提交新的发票文档以进行签名 - `POST /v1/documents/callback/:status` - ngSign 的回调端点（成功/失败） 请参阅 [docs/API.md](docs/API.md) 获取详细的端点规范。 ### 客户端管理控制器 - `POST /v1/clients` - 创建客户端并生成新的 API 令牌 - `PATCH /v1/clients/:taxId` - 更新客户端模式/ngsign/TTN 设置 - `DELETE /v1/clients/:taxId` - 移除客户端 这些端点使用 `GLOBAL_API_KEY` 通过 `x-api-key` 进行保护。 ### TTN 集成 该应用程序支持多种 TTN 提交方法： - **Web 服务**：向 TTN 服务器提交基于 SOAP 的请求 - **SFTP**：用于发票上传和下载的安全文件传输 请参阅 [src/business-logic/ttn/sftp/README.md](src/business-logic/ttn/sftp/README.md) 获取 SFTP 配置和使用说明。 ## 数据库迁移 迁移文件位于 `src/db/migrations/` 目录中： 1. `001_init_invoice_middleware.ts` - 初始模式设置 2. `002_add_ttn_reference.ts` - 添加 TTN 引用跟踪 3. `003_add_qr_code_base64.ts` - 添加二维码支持 4. `004_webhooks.ts` - Webhook 端点和投递（发件箱模式） ## 定时任务 应用程序包含以下定时任务： - **TTN 提交**：每 5 分钟提交待处理文档到 TTN - **TTN 文档咨询**：每 10 分钟轮询 TTN 获取文档状态更新 - **Webhook 工作器**：每分钟处理待处理的 Webhook 投递 在 [src/cron/index.ts](src/cron/index.ts) 中配置定时计划。 ## 开发流程 ### 添加新功能 1. 在适当的 `src/business-logic/` 子目录中创建业务逻辑 2. 在 `src/schemas/` 中添加验证模式 3. 在 `src/controllers/` 中实现控制器 4. 在 `src/routes/` 中定义路由 5. 附带实现编写全面测试 6. 更新文档 ### 测试 测试与源文件共同存放，使用 `__tests__/` 目录模式： ``` src/ ├── business-logic/ │ ├── document/ │ │ ├── calculations.ts │ │ └── __tests__/ │ │ └── calculations.test.ts ``` ## 配置 ### 环境变量 所有配置均通过环境变量管理。关键变量包括： - `NODE_ENV`：应用程序环境（development/production） - `PORT`：服务器端口（默认：3000） - `DB_*`：数据库连接参数 - `GLOBAL_API_KEY`：用于 `/v1/clients` 管理端点的共享密钥 ## 性能 - 数据库查询使用 Kysely 进行类型安全的 SQL 生成 - XML 处理使用 fast-xml-parser 以提高效率 - 后台任务使用 node-cron 进行调度操作 - Webhook 重试采用指数退避策略 ## 安全 - 使用环境变量存储敏感凭据 - 使用 Zod 模式验证所有输入 - 使用数字签名验证文档真实性 - 使用 HTTPS/TLS 进行外部服务通信 ## 故障排除 ### 数据库连接问题 ``` # 检查数据库连接 pnpm run db:migrate ``` ### TTN 服务错误 请查阅 `docs/ttn/ttn-ws-docs.md` 获取特定服务的文档和错误代码。 ### 构建问题 ``` # 清理构建产物 pnpm run clean # 重建 pnpm run build ``` ## 贡献 欢迎贡献！请遵循以下指南： 1. 为新功能编写测试 2. 确保所有测试通过：`pnpm test` 3. 运行代码检查：`pnpm run lint` 4. 遵循 TypeScript 最佳实践 5. 对重大更改更新 README ## 作者 - **Tekru** - 核心开发和架构 - **NGSign** - 数字签名集成和加密服务 ## 许可证 本项目采用 Apache License Version 2.0 开源许可。详细信息请参阅 LICENSE 文件。 ## 支持 如有疑问或问题，请联系开发团队。 **最后更新**：21/01/2026

标签：CVE, Express.js, fast-xml-parser, GNU通用公共许可证, JSON 校验, Kysely ORM, MITM代理, ngsign, node-cron, Node.js, PostgreSQL, SEO 关键词, TEIF, TTN 提交, TypeScript, Webhook, XML 生成, Zod, 中间件 API, 力导向图, 发票生命周期, 发票系统, 后台任务, 安全插件, 数字签名, 测试用例, 状态轮询, 电子 invoicing, 电子发票, 税务申报, 突尼斯电子发票, 第三方对接, 签名验证, 自动化攻击, 集成