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

## 项目概述

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

> **技术框架**：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                     # 账单服务
```

### 响应模型

```python
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

### 安装依赖

```bash
cd backend
uv sync
```

### 配置

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

### 启动服务

```bash
uv run main.py run --env=dev
```

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

## 数据库迁移

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

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

## 测试

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

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

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

## 相关文档

- [因公付款服务系统架构设计](./docs/因公付款服务系统架构设计.md)
- [Plugin 模块规划](./docs/Plugin模块规划.md)
- [支付宝 SDK 封装方案](./docs/支付宝SDK封装方案.md)
- [技术集成指南](./docs/技术集成指南.md)

## 参考链接

- [支付宝开放平台文档](https://opendocs.alipay.com/)
- [企业码产品文档](https://opendocs.alipay.com/open/01qX5z)
- [FastApiAdmin 官方文档](https://service.fastapiadmin.com)