xjz-payment-platform

<div align="center">
     <h1>xjz-payment-platform </h1>
     <h3>企业级因公付款服务平台</h3>
     <p>基于支付宝企业码的企业因公消费额度管控解决方案</p>
</div>

## 📘 项目介绍

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

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

### 核心业务流程

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

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

---

## 🎯 核心优势

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

---

## 📦 工程结构

```sh
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             # 本文档
```

---

## 🏗️ 系统架构

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

### 后端启动

```bash
cd backend

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

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

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

### 前端启动

```bash
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             # 响应模型定义
```

核心模型：

```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 == AlipayResponseCodeEnum.SUCCESS.value.code


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

---

## 📖 相关文档

| 文档 | 说明 |
|------|------|
| [后端 README](backend/README.md) | 后端开发指南、API 路由、测试 |
| [系统架构设计](backend/docs/因公付款服务系统架构设计.md) | 系统设计文档 |
| [Plugin 模块规划](backend/docs/Plugin模块规划.md) | 插件化架构说明 |
| [支付宝 SDK 封装方案](backend/docs/支付宝SDK封装方案.md) | SDK 使用指南 |
| [技术集成指南](backend/docs/技术集成指南.md) | 支付宝接口集成说明 |

---

## 🔗 参考链接

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