> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 积分、微信支付与支付宝结算

> Profy 金融与支付体系：积分虚拟货币、充值套餐、微信支付与支付宝接入，以及在任务、专家与高级功能上的消费追踪与管理。

# 金融支付

Profy 内置完整的虚拟货币体系——积分（Credit）。用户通过微信支付充值获得积分，使用积分消费应用服务。系统支持充值方案、交易记录、幂等消费和 OpenAPI 对外调用。

## 概述

```mermaid theme={null}
graph LR
    User[用户] --> Recharge["充值"]
    Recharge --> WeChatPay["微信支付"]
    WeChatPay --> Callback["支付回调"]
    Callback --> Grant["发放积分"]
    Grant --> Balance["积分余额"]
    Balance --> Consume["消费积分"]
    Consume --> Task["任务/服务"]

    style Recharge fill:#fef3c7,stroke:#f59e0b
    style Balance fill:#dbeafe,stroke:#3b82f6
    style Consume fill:#fee2e2,stroke:#ef4444
```

## 积分体系

### 数据模型

| 表                    | 说明               |
| -------------------- | ---------------- |
| `credit_account`     | 用户积分账户，记录余额      |
| `credit_transaction` | 积分变动流水（充值/消费/退款） |
| `consumeRecords`     | 消费明细（关联任务/服务）    |

### 账户接口

| 方法   | 路径                      | 说明       |
| ---- | ----------------------- | -------- |
| GET  | `/api/finance/balance`  | 查询当前余额   |
| POST | `/api/finance/consume`  | 消费积分     |
| POST | `/api/finance/preCheck` | 预检余额是否充足 |
| POST | `/api/finance/records`  | 查询交易记录   |

### 消费类型

积分消费支持三种计费模式：

| 类型         | 标识         | 说明                      |
| ---------- | ---------- | ----------------------- |
| **按Token** | `TOKEN`    | 根据 AI 模型输入/输出 Token 数计费 |
| **按时长**    | `DURATION` | 根据服务使用时长计费              |
| **固定价格**   | `FIXED`    | 单次固定金额扣费                |

### 幂等消费

每次消费请求携带唯一 `requestId`，系统通过该 ID 保证同一笔消费不会重复扣款。适用于网络重试和回调重放场景。

## 充值流程

```mermaid theme={null}
sequenceDiagram
    participant U as 用户
    participant W as Web
    participant C as Core API
    participant P as 微信支付

    U->>W: 选择充值方案
    W->>C: GET /api/finance/recharge/plans
    C-->>W: 方案列表（金额 + 赠送）

    U->>W: 选择方案，确认金额
    W->>C: GET /api/finance/recharge/preview?amount=100
    C-->>W: 预览：100元 → 1000 积分 + 100 赠送

    U->>W: 确认充值
    W->>C: POST /api/finance/recharge/create {planId, amount}
    C->>C: 创建充值订单 + 支付订单
    C->>P: 创建微信支付 Native 订单
    P-->>C: 支付二维码 URL
    C-->>W: {orderNo, qrCodeUrl}

    W-->>U: 展示支付二维码

    U->>P: 微信扫码支付
    P->>C: POST /api/payment/notify/wechat
    C->>C: 验签 → 更新支付状态
    C->>C: rechargeService.onPaymentSuccess
    C->>C: 发放积分到账户
    C-->>P: 确认收到

    W->>C: GET /api/finance/recharge/status/:orderNo
    C-->>W: 支付成功
    W-->>U: 充值完成，余额更新
```

### 充值接口

| 方法   | 路径                                      | 说明      |
| ---- | --------------------------------------- | ------- |
| GET  | `/api/finance/recharge/plans`           | 充值方案列表  |
| GET  | `/api/finance/recharge/preview`         | 预览到账积分数 |
| POST | `/api/finance/recharge/create`          | 创建充值订单  |
| GET  | `/api/finance/recharge/status/:orderNo` | 查询充值状态  |
| POST | `/api/finance/recharge/summary`         | 充值汇总    |
| POST | `/api/finance/recharge/records`         | 充值记录    |

## 服务计划

服务计划（Service Plan）为不同业务线提供差异化的计费配置。

| 方法  | 路径                              | 说明                         |
| --- | ------------------------------- | -------------------------- |
| GET | `/api/finance/servicePlan/list` | 服务计划列表（按 `serviceCode` 筛选） |

服务计划定义了：

* 服务标识（`serviceCode`）
* 计费单价和模式
* 有效期和限额
* 关联的积分消费规则

## 微信支付集成

### 支付架构

```mermaid theme={null}
graph TB
    Core["Core API"] --> Factory["Payment Factory"]
    Factory --> WeChat["微信支付 V3"]
    Factory --> Alipay["支付宝（预留）"]

    WeChat --> Native["Native 支付<br/>（扫码）"]

    subgraph 回调处理
        Notify["POST /api/payment/notify/:channel"]
        Verify["验签 & 解密"]
        Update["更新订单状态"]
        Grant["触发业务回调"]
    end

    Native --> Notify
    Notify --> Verify --> Update --> Grant

    style WeChat fill:#07c160,stroke:#06ae56,color:#fff
```

### 支付接口

| 方法   | 路径                                | 说明          |
| ---- | --------------------------------- | ----------- |
| POST | `/api/payment/create`             | 创建支付订单      |
| GET  | `/api/payment/status/:outTradeNo` | 查询支付状态      |
| POST | `/api/payment/close/:outTradeNo`  | 关闭支付订单      |
| POST | `/api/payment/notify/:channel`    | 支付结果回调（免认证） |

### 支付流程要点

* **Native 支付** — 生成二维码 URL，用户微信扫码完成支付
* **异步回调** — 微信服务器 POST 通知到 `/api/payment/notify/wechat`
* **验签保障** — 使用微信支付 V3 证书验证回调签名
* **幂等处理** — 通过 `outTradeNo` 防止重复处理同一笔支付

## 消费记录

### 消费概览

| 方法   | 路径                         | 说明     |
| ---- | -------------------------- | ------ |
| POST | `/api/consumption/summary` | 消费汇总统计 |
| POST | `/api/consumption/records` | 分页消费明细 |

消费记录关联任务、服务和 Agent 实例，用户可在「消费记录」页面查看完整的积分流向。

## OpenAPI 积分接口

第三方系统可通过 API Key 调用积分接口，实现外部服务的计费集成：

| 方法   | 路径                         | 认证方式    | 说明   |
| ---- | -------------------------- | ------- | ---- |
| GET  | `/openapi/credit/balance`  | API Key | 查询余额 |
| POST | `/openapi/credit/consume`  | API Key | 消费积分 |
| POST | `/openapi/credit/preCheck` | API Key | 预检余额 |

请求头中通过 `X-Api-Key: sk_xxxxx` 或 `Authorization: Bearer sk_xxxxx` 传递密钥。

## 钻石货币体系（创作者侧）

Profy 引入钻石（Diamond）作为创作者收益的计价货币，与用户侧的积分（Credit）完全隔离。

### 钻石账户

| 表                     | 说明                             |
| --------------------- | ------------------------------ |
| `diamond_account`     | 创作者钻石账户（余额 + 冻结 + 已提现 + 乐观锁版本） |
| `diamond_transaction` | 钻石流水（收益/佣金/奖励/提现）              |

### 收益入账

创作者通过两种渠道获得钻石：

* **买断收益**（`earning_buyout`）：用户购买 Expert 时，按创作者等级的 `buyoutSharePpm` 分成
* **消耗收益**（`earning_consumption`）：用户使用 Expert 消耗积分时，按 `consumptionSharePpm` 分成

所有收益入账时先进入冻结状态（T+7），由 `earning-unfreeze` worker 每日解冻。

### 创作者等级

| 等级           | 累计钻石门槛  | 买断分成 | 消耗分成 |
| ------------ | ------- | ---- | ---- |
| Rising       | 0       | 75%  | 10%  |
| Growing      | 10,000  | 85%  | 15%  |
| Professional | 100,000 | 90%  | 18%  |
| Master       | 500,000 | 95%  | 20%  |

### 提现

创作者可将可用钻石余额兑换为法币提现。提现流程：

1. 创作者提交提现申请
2. Admin 审核通过/拒绝
3. 通过后系统扣除钻石余额并标记为已完成

### 平台经济参数运营配置

上述所有经济参数（等级分成比例、提现规则等）均可通过运营后台实时配置，无需代码发版。

**配置入口**：`/admin/economics` → 「平台配置」Tab

**可配置项**：

* **创作者等级分成**：各等级的买断/消费分成比例（PPM），同时控制买断和消费两种分成
* **提现与结算规则**：最低提现额度、冻结天数、钻石汇率

**技术实现**：参数存储在 `system_config` 表，通过 `platform-config` 服务读取（60s 内存缓存）。config key 不存在时 fallback 到代码内默认值，确保首次部署零初始化。

## 相关链接

<CardGroup cols={2}>
  <Card title="认证系统" icon="lock" href="/zh/documentation/auth">
    API Key 的创建和管理
  </Card>

  <Card title="任务调度" icon="list-check" href="/zh/documentation/tasks">
    任务消费扣费流程
  </Card>

  <Card title="创作者激励" icon="trophy" href="/zh/documentation/creator-incentive">
    等级、分成、成就、推广、悬赏
  </Card>
</CardGroup>