# 因公付款服务系统 - 架构设计计划

## 一、系统概述

### 1.1 项目定位

基于支付宝企业码能力，构建企业级因公付款服务系统。系统核心目标是帮助企业实现员工因公消费的额度管控、费用控制和账单管理，区别于原文档的旅行社场景，本系统面向各类企业客户提供通用的因公付款解决方案。

### 1.2 核心业务流程

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

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

***

## 二、系统架构设计

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                         前端应用层                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  Web管理后台 │  │  企业Portal │  │ 支付宝小程序 │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         接口服务层                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 企业管理API  │  │ 员工管理API  │  │ 费控管理API  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 额度管理API  │  │ 账单查询API  │  │ 支付跳转API  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        业务服务层                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 企业签约服务  │  │ 员工管理服务  │  │ 费控规则服务  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 额度发放服务  │  │ 账单处理服务  │  │ 消息通知服务  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      支付宝集成层                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Alipay SDK                               ││
│  │   企业码API │ 费控API │ 账单API │ 消息订阅(websocket/http)  ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         数据存储层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ PostgreSQL  │  │  Redis      │  │ 文件存储     │             │
│  │ 企业/员工/制度│  │ 额度/会话缓存 │  │ 账单凭证    │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 技术栈选型

| 层级     | 技术选型                  | 说明              |
| ------ | --------------------- | --------------- |
| 后端框架   | Spring Boot / FastAPI | 根据团队技术栈选择       |
| 数据库    | PostgreSQL 14+            | 存储企业、员工、费控等核心数据 |
| 缓存     | Redis                 | 额度缓存、会话管理、幂等控制  |
| 消息订阅   | WebSocket / HTTP      | 接收支付宝账单变动通知     |
| 支付宝SDK | Alipay SDK            | 调用支付宝企业码相关接口    |
| API文档  | Swagger/OpenAPI       | 接口文档化           |

***

## 三、核心模块设计

### 3.1 企业管理模块

**功能职责**：完成企业码服务的开通和入驻

**核心接口**：

| 接口名                                                 | 功能       | 优先级 |
| --------------------------------------------------- | -------- | --- |
| alipay.commerce.ec.enterprise.registerinvite.create | 邀请企业注册   | P0  |
| alipay.commerce.ec.enterprise.change.notify         | 企业状态变更通知 | P0  |
| alipay.commerce.ec.enterprise.info.query            | 查询企业详情   | P1  |
| alipay.commerce.ec.enterprise.info.modify           | 修改企业信息   | P1  |
| alipay.commerce.ec.enterprise.unsign                | 企业解约     | P2  |
| alipay.commerce.ec.enterprise.delete                | 企业注销     | P2  |

**数据结构**：

```
Enterprise {
    enterprise_id: string      # 企业码企业ID
    account_id: string         # 支付宝账号ID
    name: string               # 企业名称
    status: enum               # 注册/签约/解约/注销
    created_at: datetime
    updated_at: datetime
}
```

### 3.2 员工管理模块

**功能职责**：管理企业内部可使用因公付款的员工账号

**核心接口**：

| 接口名                                       | 功能       | 优先级 |
| ----------------------------------------- | -------- | --- |
| alipay.commerce.ec.employee.add           | 添加企业员工   | P0  |
| alipay.commerce.ec.employee.delete        | 删除企业员工   | P0  |
| alipay.commerce.ec.employee.change.notify | 员工变更通知   | P0  |
| alipay.commerce.ec.employee.invite.query  | 获取员工邀请链接 | P1  |
| alipay.commerce.ec.employee.info.modify   | 修改员工信息   | P1  |
| alipay.commerce.ec.employee.info.query    | 查询员工详情   | P1  |
| alipay.commerce.ec.employee.idlist.query  | 查询员工ID列表 | P1  |

**数据结构**：

```
Employee {
    employee_id: string        # 员工ID
    enterprise_id: string     # 所属企业ID
    alipay_user_id: string     # 支付宝用户ID
    name: string               # 员工姓名
    phone: string              # 手机号
    department_id: string     # 部门ID
    status: enum              # 待激活/已激活/已删除
    bind_time: datetime       # 绑定时间
}

Department {
    department_id: string     # 部门ID
    enterprise_id: string     # 所属企业ID
    name: string              # 部门名称
    parent_id: string         # 上级部门ID
}
```

### 3.3 费控制度模块

**功能职责**：创建和管理企业的费用控制规则

**核心接口**：

| 接口名                                                 | 功能       | 优先级 |
| --------------------------------------------------- | -------- | --- |
| alipay.ebpp.invoice.institution.create              | 创建费控制度   | P0  |
| alipay.ebpp.invoice.institution.modify              | 编辑费控制度   | P0  |
| alipay.ebpp.invoice.institution.scopepageinfo.query | 查询制度适用成员 | P0  |
| alipay.ebpp.invoice.institution.pageinfo.query      | 查询费控制度列表 | P1  |
| alipay.ebpp.invoice.institution.detailinfo.query    | 查询制度详情   | P1  |
| alipay.ebpp.invoice.institution.delete              | 删除费控制度   | P2  |

**数据结构**：

```
ExpenseControl {
    institution_id: string    # 费控制度ID
    enterprise_id: string     # 所属企业ID
    name: string              # 制度名称
    expense_type: string      # 费用类型
    expense_sub_type: string  # 费用类型子类
    status: enum              # 生效/失效
    created_at: datetime
}

ExpenseRule {
    rule_id: string           # 规则ID
    institution_id: string    # 所属制度ID
    name: string              # 规则名称
    max_amount: decimal       # 最大限额
    valid_from: datetime      # 有效期开始
    valid_to: datetime         # 有效期结束
    merchant_pid: string       # 限定商户(可选)
}
```

### 3.4 额度管理模块

**功能职责**：管理员工的因公消费额度

**核心接口**：

| 接口名                                             | 功能       | 优先级 |
| ----------------------------------------------- | -------- | --- |
| alipay.ebpp.invoice.expensecontrol.quota.create | 创建手工发放额度 | P0  |
| alipay.ebpp.invoice.expensecontrol.quota.query  | 查询员工可用额度 | P0  |
| alipay.ebpp.invoice.expensecontrol.quota.modify | 修改手工发放额度 | P0  |
| alipay.ebpp.invoice.expensecontrol.quota.delete | 删除额度     | P2  |

**数据结构**：

```
Quota {
    quota_id: string           # 额度ID
    employee_id: string        # 员工ID
    institution_id: string    # 费控制度ID
    outer_source_id: string   # 外部来源ID(幂等)
    total_amount: decimal      # 总金额
    available_amount: decimal # 可用金额
    valid_from: datetime       # 有效期开始
    valid_to: datetime         # 有效期结束
    status: enum              # 正常/冻结/已用完/已过期
}
```

### 3.5 账单管理模块

**功能职责**：接收和处理消费账单数据

**核心接口**：

| 接口名                                          | 功能       | 优先级 |
| -------------------------------------------- | -------- | --- |
| alipay.commerce.ec.consume.change.notify     | 账单变动通知   | P0  |
| alipay.commerce.ec.consume.detail.query      | 账单详情查询   | P0  |
| alipay.commerce.ec.consume.detail.batchquery | 账单批量分页查询 | P1  |
| alipay.commerce.ec.balance.downloadurl.query | 对账单文件下载  | P2  |
| alipay.commerce.ec.voucher.change.notify     | 凭证变动通知   | P1  |

**数据结构**：

```
Bill {
    bill_id: string            # 账单ID
    trade_no: string           # 支付宝交易号
    enterprise_id: string     # 企业ID
    employee_id: string       # 员工ID
    institution_id: string    # 费控制度ID
    quota_id: string           # 额度ID
    total_amount: decimal     # 账单金额
    enterprise_pay_amount: decimal  # 企业付金额
    personal_pay_amount: decimal    # 个人付金额
    discount_amount: decimal   # 优惠金额
    trade_time: datetime       # 交易时间
    merchant_name: string      # 商户名称
    status: enum              # 已支付/退款/关闭
}

Voucher {
    voucher_id: string         # 凭证ID
    bill_id: string            # 关联账单ID
    content: json              # 凭证内容
}
```

### 3.6 支付跳转模块

**功能职责**：生成跳转链接，拉起支付宝扫一扫或付款码

**核心接口**：

| 功能     | 说明                     | 优先级 |
| ------ | ---------------------- | --- |
| 跳转扫一扫  | 生成openAlipayApp拉起扫一扫参数 | P0  |
| 跳转付款码  | 生成schema拉起付款码参数        | P0  |
| 跳转发票关联 | 生成发票关联页面跳转链接           | P1  |

***

## 四、消息通知机制

### 4.1 通知类型

| 通知类型   | 接口名                                         | 处理方式    |
| ------ | ------------------------------------------- | ------- |
| 企业状态变更 | alipay.commerce.ec.enterprise.change.notify | 更新企业状态  |
| 员工变更   | alipay.commerce.ec.employee.change.notify   | 更新员工状态  |
| 账单变动   | alipay.commerce.ec.consume.change.notify    | 创建/更新账单 |
| 凭证变动   | alipay.commerce.ec.voucher.change.notify    | 更新凭证信息  |

### 4.2 接入方式

* **WebSocket长连接**：实时推送，延迟低

* **HTTP回调**：简单实现，需要暴露公网接口

***

## 五、数据库表设计

### 5.1 核心表结构

```sql
-- 企业表
CREATE TABLE t_enterprise (
    id BIGSERIAL PRIMARY KEY,
    enterprise_id VARCHAR(64) NOT NULL UNIQUE,
    account_id VARCHAR(64),
    name VARCHAR(128) NOT NULL,
    status VARCHAR(32) DEFAULT 'registered',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 部门表
CREATE TABLE t_department (
    id BIGSERIAL PRIMARY KEY,
    department_id VARCHAR(64) NOT NULL UNIQUE,
    enterprise_id VARCHAR(64) NOT NULL,
    name VARCHAR(128) NOT NULL,
    parent_id VARCHAR(64),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 员工表
CREATE TABLE t_employee (
    id BIGSERIAL PRIMARY KEY,
    employee_id VARCHAR(64) NOT NULL UNIQUE,
    enterprise_id VARCHAR(64) NOT NULL,
    alipay_user_id VARCHAR(64),
    name VARCHAR(64) NOT NULL,
    phone VARCHAR(32),
    email VARCHAR(128),
    department_id VARCHAR(64),
    status VARCHAR(32) DEFAULT 'pending',
    bind_time TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 费控制度表
CREATE TABLE t_expense_institution (
    id BIGSERIAL PRIMARY KEY,
    institution_id VARCHAR(64) NOT NULL UNIQUE,
    enterprise_id VARCHAR(64) NOT NULL,
    name VARCHAR(128) NOT NULL,
    expense_type VARCHAR(32) DEFAULT 'DEFAULT',
    expense_sub_type VARCHAR(32) DEFAULT 'DEFAULT',
    status VARCHAR(32) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 使用规则表
CREATE TABLE t_expense_rule (
    id BIGSERIAL PRIMARY KEY,
    rule_id VARCHAR(64) NOT NULL UNIQUE,
    institution_id VARCHAR(64) NOT NULL,
    name VARCHAR(128),
    max_amount DECIMAL(12,2),
    valid_from TIMESTAMP,
    valid_to TIMESTAMP,
    merchant_pid VARCHAR(64),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 额度表
CREATE TABLE t_quota (
    id BIGSERIAL PRIMARY KEY,
    quota_id VARCHAR(64) NOT NULL UNIQUE,
    employee_id VARCHAR(64) NOT NULL,
    institution_id VARCHAR(64) NOT NULL,
    outer_source_id VARCHAR(64) NOT NULL,
    total_amount DECIMAL(12,2) NOT NULL,
    available_amount DECIMAL(12,2) NOT NULL,
    valid_from TIMESTAMP NOT NULL,
    valid_to TIMESTAMP NOT NULL,
    status VARCHAR(32) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 账单表
CREATE TABLE t_bill (
    id BIGSERIAL PRIMARY KEY,
    bill_id VARCHAR(64) NOT NULL UNIQUE,
    trade_no VARCHAR(64) NOT NULL,
    enterprise_id VARCHAR(64) NOT NULL,
    employee_id VARCHAR(64) NOT NULL,
    institution_id VARCHAR(64),
    quota_id VARCHAR(64),
    total_amount DECIMAL(12,2) NOT NULL,
    enterprise_pay_amount DECIMAL(12,2) DEFAULT 0,
    personal_pay_amount DECIMAL(12,2) DEFAULT 0,
    discount_amount DECIMAL(12,2) DEFAULT 0,
    trade_time TIMESTAMP,
    merchant_name VARCHAR(256),
    status VARCHAR(32) DEFAULT 'paid',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 凭证表
CREATE TABLE t_voucher (
    id BIGSERIAL PRIMARY KEY,
    voucher_id VARCHAR(64) NOT NULL UNIQUE,
    bill_id VARCHAR(64) NOT NULL,
    content JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 操作日志表
CREATE TABLE t_operation_log (
    id BIGSERIAL PRIMARY KEY,
    operation_type VARCHAR(64) NOT NULL,
    enterprise_id VARCHAR(64),
    employee_id VARCHAR(64),
    request_data JSONB,
    response_data JSONB,
    status VARCHAR(32),
    error_message TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 添加更新触发器函数
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = CURRENT_TIMESTAMP;
    RETURN NEW;
END;
$$ language 'plpgsql';

-- 为需要自动更新updated_at的表创建触发器
CREATE TRIGGER update_t_enterprise_updated_at
    BEFORE UPDATE ON t_enterprise
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_t_employee_updated_at
    BEFORE UPDATE ON t_employee
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_t_expense_institution_updated_at
    BEFORE UPDATE ON t_expense_institution
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_t_quota_updated_at
    BEFORE UPDATE ON t_quota
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_t_bill_updated_at
    BEFORE UPDATE ON t_bill
    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
```

***

## 六、接口设计

### 6.1 企业管理接口

| 接口                                         | 方法     | 说明     |
| ------------------------------------------ | ------ | ------ |
| POST /api/enterprise/invite                | 创建企业邀请 | 获取注册链接 |
| GET /api/enterprise/{enterpriseId}         | 查询企业详情 | <br /> |
| PUT /api/enterprise/{enterpriseId}         | 修改企业信息 | <br /> |
| POST /api/enterprise/{enterpriseId}/unsign | 企业解约   | <br /> |
| POST /api/enterprise/{enterpriseId}/delete | 企业注销   | <br /> |

### 6.2 员工管理接口

| 接口                                        | 方法     | 说明     |
| ----------------------------------------- | ------ | ------ |
| POST /api/employee                        | 添加员工   | <br /> |
| DELETE /api/employee/{employeeId}         | 删除员工   | <br /> |
| GET /api/employee/{employeeId}            | 查询员工详情 | <br /> |
| PUT /api/employee/{employeeId}            | 修改员工信息 | <br /> |
| GET /api/employee/list                    | 查询员工列表 | <br /> |
| GET /api/employee/{employeeId}/invite-url | 获取邀请链接 | <br /> |

### 6.3 费控管理接口

| 接口                                            | 方法     | 说明     |
| --------------------------------------------- | ------ | ------ |
| POST /api/institution                         | 创建费控制度 | <br /> |
| PUT /api/institution/{institutionId}          | 编辑费控制度 | <br /> |
| GET /api/institution/{institutionId}          | 查询制度详情 | <br /> |
| GET /api/institution/list                     | 查询制度列表 | <br /> |
| DELETE /api/institution/{institutionId}       | 删除费控制度 | <br /> |
| POST /api/institution/{institutionId}/members | 编辑制度成员 | <br /> |

### 6.4 额度管理接口

| 接口                                   | 方法       | 说明     |
| ------------------------------------ | -------- | ------ |
| POST /api/quota                      | 创建额度     | <br /> |
| GET /api/quota/{quotaId}             | 查询额度详情   | <br /> |
| GET /api/quota/employee/{employeeId} | 查询员工可用额度 | <br /> |
| PUT /api/quota/{quotaId}             | 修改额度     | <br /> |
| DELETE /api/quota/{quotaId}          | 删除额度     | <br /> |

### 6.5 账单管理接口

| 接口                     | 方法     | 说明     |
| ---------------------- | ------ | ------ |
| GET /api/bill/{billId} | 查询账单详情 | <br /> |
| GET /api/bill/list     | 查询账单列表 | <br /> |
| GET /api/bill/download | 下载对账单  | <br /> |

### 6.6 支付跳转接口

| 接口                        | 方法         | 说明     |
| ------------------------- | ---------- | ------ |
| POST /api/pay/scan-url    | 生成扫一扫跳转链接  | <br /> |
| POST /api/pay/code-url    | 生成付款码跳转链接  | <br /> |
| POST /api/pay/invoice-url | 生成发票关联跳转链接 | <br /> |

***

## 七、实施计划

### 阶段一：基础能力建设（2-3周）

1. **环境准备**

   * 完成支付宝开放平台账号注册和认证

   * 创建自研应用（小程序或网页应用）

   * 配置密钥，完成应用上线

2. **框架搭建**

   * 项目工程创建，依赖配置

   * 数据库设计和初始化

   * 支付宝SDK集成和配置

3. **核心功能开发**

   * 企业管理模块（入驻、签约）

   * 员工管理模块（增删改查）

   * 消息订阅机制实现

**交付物**：

* 基础项目框架

* 数据库表结构脚本

* 企业管理、员工管理API

### 阶段二：费控和额度模块（2-3周）

1. **费控制度管理**

   * 费控制度CRUD

   * 使用规则管理

   * 成员范围管理

2. **额度管理**

   * 额度创建和发放

   * 额度查询和修改

   * 有效期管理

**交付物**：

* 费控管理API

* 额度管理API

* 管理后台界面原型

### 阶段三：账单和支付模块（2-3周）

1. **账单管理**

   * 账单通知接收和处理

   * 账单查询和对账

   * 凭证管理

2. **支付跳转**

   * 扫一扫跳转链接生成

   * 付款码跳转链接生成

   * H5/小程序端集成

**交付物**：

* 账单管理API

* 支付跳转功能

* 完整业务流程联调

### 阶段四：测试和上线（1-2周）

1. **测试**

   * 单元测试编写

   * 接口联调测试

   * 场景测试

2. **上线**

   * 生产环境部署

   * 支付宝产品包挂载

   * 消息订阅配置

   * 正式环境联调

**交付物**：

* 测试报告

* 部署文档

* 用户手册

***

## 八、风险点和注意事项

### 8.1 关键风险

| 风险点     | 影响    | 应对措施        |
| ------- | ----- | ----------- |
| 支付宝接口限流 | 业务中断  | 添加限流保护，本地缓存 |
| 消息通知丢失  | 账单不一致 | 定期对账，主动查询补全 |
| 额度超用    | 资金损失  | 额度预冻结机制     |
| 员工删除后消费 | 纠纷    | 删除前检查待生效额度  |

### 8.2 注意事项

1. **幂等性**：所有写操作接口需保证幂等，使用outer\_source\_id控制
2. **安全性**：敏感数据加密存储，接口权限校验
3. **日志**：完整记录所有操作，便于问题排查
4. **监控**：接口调用监控，异常告警

***

## 九、参考文档

* 支付宝开放平台文档：<https://opendocs.alipay.com/>

* 企业码产品文档：<https://opendocs.alipay.com/open/01qX5z>

* 消息订阅接入：<https://opendocs.alipay.com/open/10381/gh4emp>