payment-platform/backend

因公付款服务系统 - 后端工程

项目概述

基于支付宝企业码能力，构建企业级因公付款服务系统。系统核心目标是帮助企业实现员工因公消费的额度管控、费用控制和账单管理。

技术框架：FastApiAdmin 后端，基于 FastAPI + SQLAlchemy 2.0 + Pydantic 2.x

核心业务流程

企业入驻 → 部门管理 → 员工管理 → 费控制度创建 → 额度发放 → 员工消费 → 账单通知 → 对账结算

1. 企业入驻：企业完成支付宝企业码服务签约开通
2. 组织架构：创建企业部门，添加/管理企业员工
3. 员工激活：员工通过二维码/链接完成支付宝协议确认，绑定企业
4. 费控制度：创建通用场景费控制度，设置使用规则和发放规则
5. 额度管理：为员工创建点券/额度，设定有效期和金额
6. 因公消费：员工出示企业码付款或扫码进行因公支付
7. 账单同步：消费记录实时通过账单变动通知同步给企业
8. 对账结算：企业查询账单详情，进行费用核销和对账

技术架构

系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                         前端应用层                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  Web管理后台 │  │  企业Portal │  │ 支付宝小程序 │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         接口服务层                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 企业管理API  │  │ 员工管理API  │  │ 费控管理API  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 额度管理API  │  │ 账单查询API  │  │ 支付跳转API  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      支付宝集成层                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Alipay SDK                               ││
│  │   企业码API │ 费控API │ 账单API │ 消息订阅(websocket/http)  ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

技术栈

层级	技术选型	说明
后端框架	FastAPI 0.115.2	现代 Web 框架
ORM	SQLAlchemy 2.0.45	数据库 ORM
数据库	PostgreSQL / MySQL / SQLite	多数据库支持
缓存	Redis	额度缓存、会话管理
支付宝SDK	alipay-sdk-python >= 3.7.1018	支付宝 API 调用
异步框架	uvicorn + asyncio	高性能异步服务

插件模块结构

基于 FastApiAdmin 的插件化架构，因公付款服务核心功能在 app/plugin/module_payment/ 目录下：

app/plugin/module_payment/                    # 因公付款服务一级模块
├── plugin.toml                              # 模块元数据
│
├── enterprise/                             # 企业管理子模块
│   ├── model.py                            # 企业实体定义
│   ├── schema.py                          # Pydantic 请求/响应模型
│   ├── crud.py                            # 数据库 CRUD 操作
│   ├── service.py                          # 业务逻辑层
│   └── controller.py                       # API 路由控制器
│
├── department/                             # 部门管理子模块
├── employee/                               # 员工管理子模块
├── expense_institution/                    # 费控制度子模块
├── expense_rule/                           # 使用规则子模块
├── quota/                                  # 额度管理子模块
├── bill/                                   # 账单管理子模块
├── voucher/                                # 凭证管理子模块
├── payment/                                # 支付跳转子模块
└── notification/                           # 消息通知子模块

核心模块

模块职责

子模块	职责	对应支付宝 API
enterprise	企业入驻、签约、解约、注销	alipay.commerce.ec.enterprise.*
department	部门创建、修改、删除、查询	(本地管理)
employee	员工添加、删除、激活、邀请链接	alipay.commerce.ec.employee.*
expense_institution	费控制度 CRUD、成员管理	alipay.ebpp.invoice.institution.*
expense_rule	使用规则创建、编辑、删除	alipay.ebpp.invoice.institution.expenserule.*
quota	额度创建、发放、查询、修改	alipay.ebpp.invoice.expensecontrol.quota.*
bill	账单接收、查询、对账	alipay.commerce.ec.consume.*
voucher	凭证存储、查询	alipay.commerce.ec.voucher.*
payment	扫一扫/付款码跳转链接生成	(本地生成)
notification	支付宝消息接收、处理、分发	(Webhook 回调)

API 路由

POST   /api/payment/enterprise/invite           # 创建企业邀请
GET    /api/payment/enterprise/{id}            # 查询企业详情
POST   /api/payment/employee                    # 添加员工
DELETE /api/payment/employee/{id}              # 删除员工
POST   /api/payment/institution                 # 创建费控制度
POST   /api/payment/quota                       # 创建额度
GET    /api/payment/bill/{id}                  # 查询账单详情
POST   /api/payment/pay/scan-url               # 生成扫一扫跳转链接
POST   /api/payment/pay/code-url               # 生成付款码跳转链接
WS     /ws/payment/notification                # WebSocket 长连接

支付宝 SDK 封装

目录结构

app/core/alipay/                              # 支付宝 SDK 封装
├── __init__.py
├── config.py                                # SDK 配置类
├── client.py                                # 统一客户端
├── schema.py                                # 响应模型定义
├── exceptions.py                            # 异常定义
└── services/                                # 服务层
    ├── base.py                             # 基础服务类
    ├── enterprise_service.py                # 企业服务
    ├── employee_service.py                  # 员工服务
    ├── expense_service.py                   # 费控服务
    ├── quota_service.py                     # 额度服务
    └── bill_service.py                     # 账单服务

响应模型

class AlipayResponse(BaseModel):
    """支付宝响应基础模型"""
    code: str
    msg: str
    sub_code: Optional[str] = None
    sub_msg: Optional[str] = None

    @property
    def success(self) -> bool:
        return self.code == "10000"


class AlipayResponseCodeEnum(Enum):
    """支付宝响应码枚举"""
    SUCCESS = AlipayResponseCode("10000", "接口调用成功")
    SERVICE_UNAVAILABLE = AlipayResponseCode("20000", "服务不可用")
    # ...

快速开始

环境要求

• Python >= 3.10
• PostgreSQL 14+ / MySQL 8.0+ / SQLite 3.x
• Redis

安装依赖

cd backend
uv sync

配置

复制 env/.env.dev.example → env/.env.dev，填写支付宝等配置信息。

启动服务

uv run main.py run --env=dev

接口文档：http://127.0.0.1:8001/docs

数据库迁移

# 生成迁移文件
uv run main.py revision --env=dev

# 应用迁移
uv run main.py upgrade --env=dev

测试

# 运行所有测试
uv run pytest tests/

# 运行单个测试文件
uv run pytest tests/test_alipay.py -v

# 查看 print 输出
uv run pytest tests/test_alipay.py -v -s

相关文档

• 因公付款服务系统架构设计
• Plugin 模块规划
• 支付宝 SDK 封装方案
• 技术集成指南

参考链接

• 支付宝开放平台文档
• 企业码产品文档
• FastApiAdmin 官方文档