payment-platform/README.md

xjz-payment-platform

企业级因公付款服务平台

基于支付宝企业码的企业因公消费额度管控解决方案

📘 项目介绍

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

设计初心：以插件化、松耦合为核心，基于支付宝企业码 API 实现企业因公付款的完整业务流程。

核心业务流程

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

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

---

🎯 核心优势

优势	描述
🔥 支付宝企业码集成	深度集成支付宝企业码 API，支持因公付款全流程
⚡ 额度精准管控	基于费控制度和点券机制，实现员工消费额度精确控制
🔐 安全可靠	JWT + OAuth2 认证机制，RBAC 权限控制模型
🧱 插件化架构	基于 FastApiAdmin 插件化设计，便于扩展和维护
📊 实时账单	消费记录实时同步，支持企业对账和费用分析
🚀 快速部署	Docker 一键部署，支持生产环境快速上线
📖 完善文档	详细的开发文档和集成指南

---

📦 工程结构

xjz-payment-platform/
├─ backend/               # 后端工程 (FastAPI + Python)
│   ├─ app/
│   │   ├─ core/alipay/  # 支付宝 SDK 封装
│   │   ├─ plugin/module_payment/  # 因公付款服务模块
│   │   └─ ...
│   ├─ docs/             # 设计文档
│   └─ tests/            # 测试用例
├─ frontend/             # Web前端工程 (Vue3 + Element Plus)
├─ devops/              # 部署配置
├─ docker-compose.yaml   # Docker编排文件
└─ README.md             # 本文档

---

🏗️ 系统架构

flowchart LR
  subgraph client[前端应用]
    U[企业管理员]
    E[员工]
  end
  subgraph fe[Web管理后台]
    V[Vue3 + Vite]
  end
  subgraph be[后端服务]
    A[FastAPI / Uvicorn]
    P[因公付款模块]
    Al[支付宝SDK]
  end
  subgraph alipay[支付宝]
    API[开放平台API]
    MSG[消息订阅]
  end
  subgraph data[数据层]
    DB[(数据库)]
    R[(Redis)]
  end
  U --> V
  E --> V
  V --> A
  A --> P
  P --> Al
  Al --> API
  Al --> MSG
  P --> DB
  P --> R

技术栈

类型	技术选型	描述
后端框架	FastAPI / Uvicorn / Pydantic 2.0	现代、高性能异步框架
ORM	SQLAlchemy 2.0	强大的 ORM 库
支付宝SDK	alipay-sdk-python >= 3.7.1018	支付宝 API 调用
前端框架	Vue3 / Vite5 / Pinia / TypeScript	快速开发 Vue3 应用
Web UI	ElementPlus	企业级 UI 组件库
数据库	MySQL / PostgreSQL / Sqlite	多数据库支持
缓存	Redis	高性能缓存数据库
部署	Docker / Nginx / Docker Compose	容器化部署方案

---

📁 插件模块结构

因公付款服务核心功能在 backend/app/plugin/module_payment/ 目录下：

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.*
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.*
payment	扫一扫/付款码跳转链接生成	(本地生成)
notification	支付宝消息接收、处理、分发	(Webhook 回调)

---

🚀 快速开始

环境要求

类型	技术栈	版本
后端	Python	≥ 3.10
前端	Node.js	≥ 20.0
数据库	MySQL / PostgreSQL / SQLite	见配置
缓存	Redis	建议 6.x / 7.x

后端启动

cd backend

# 安装依赖（推荐 uv）
uv sync

# 配置环境变量
cp env/.env.dev.example env/.env.dev
# 编辑 env/.env.dev，填写支付宝配置等

# 启动服务（首次启动自动初始化数据库）
uv run main.py run --env=dev

前端启动

cd frontend
pnpm install
pnpm run dev

访问地址

服务	地址
前端 Web	http://127.0.0.1:5180
后端 API	http://127.0.0.1:8001
Swagger 文档	http://127.0.0.1:8001/docs

---

🛠️ 支付宝 SDK 封装

目录结构 backend/app/core/alipay/：

app/core/alipay/
├── __init__.py          # 导出接口
├── config.py            # SDK 配置类
├── client.py            # 统一客户端
└── schema.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 == AlipayResponseCodeEnum.SUCCESS.value.code


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

---

📖 相关文档

文档	说明
后端 README	后端开发指南、API 路由、测试
系统架构设计	系统设计文档
Plugin 模块规划	插件化架构说明
支付宝 SDK 封装方案	SDK 使用指南
技术集成指南	支付宝接口集成说明

---

🔗 参考链接

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