# 财务结算

<cite>
**本文引用的文件**
- [支付集成指南.md](file://docs/支付集成指南.md)
- [订阅系统使用说明.md](file://docs/订阅系统使用说明.md)
- [TTS成本分析报告.md](file://docs/TTS成本分析报告.md)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [log.controller.ts](file://server/src/services/log.controller.ts)
- [log.service.ts](file://server/src/services/log.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [feature_list_subscription.json](file://feature_list_subscription.json)
- [feature_list_content_generate.json](file://feature_list_content_generate.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为财务结算系统的业务文档，围绕收入统计、成本核算、利润分析、税务处理机制展开，详细说明结算周期设置、对账流程、银行转账、发票开具、财务报表生成等关键环节。同时涵盖多渠道收入管理、汇率转换、跨境结算、合规要求，并提供完整的财务API接口定义、财务数据模型、会计科目设置、凭证生成与审计跟踪，以及风险控制措施、反洗钱合规、数据安全保护与备份恢复策略。

## 项目结构
财务结算系统主要由以下模块组成：
- 支付模块：负责订单创建、支付回调、订阅激活、订单查询
- 订阅与配额模块：负责套餐管理、Token余额与使用记录、音频时长计费
- 日志与审计模块：负责请求日志记录、错误分析与审计跟踪
- 数据模型层：基于Prisma的数据库模型，支撑财务数据存储与查询

```mermaid
graph TB
subgraph "前端"
UI[用户界面]
Orders[订单历史页面]
Member[会员中心]
end
subgraph "后端服务"
PC[支付控制器]
PS[支付服务]
SC[订阅控制器]
SS[订阅服务]
LC[日志控制器]
LS[日志服务]
end
subgraph "数据层"
PRISMA[Prisma模型]
DB[(数据库)]
end
UI --> PC
UI --> SC
Orders --> PC
Member --> SC
PC --> PS
SC --> SS
PS --> PRISMA
SS --> PRISMA
LC --> LS
LS --> DB
PRISMA --> DB
```

**图表来源**
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [schema.prisma:348-391](file://server/prisma/schema.prisma#L348-L391)

**章节来源**
- [支付集成指南.md:277-336](file://docs/支付集成指南.md#L277-L336)
- [订阅系统使用说明.md:233-409](file://docs/订阅系统使用说明.md#L233-L409)

## 核心组件
- 支付控制器与服务：提供订单创建、支付回调处理、订阅激活、订单查询、二维码生成等能力
- 订阅与配额服务：提供套餐查询、Token余额与使用记录、音频时长计费、配额检查等功能
- 日志与审计服务：提供请求日志记录、错误分析、统计信息与自动修复建议
- 数据模型：包含订单、订阅、Token余额与使用记录等财务相关实体

**章节来源**
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [subscription.service.ts:1-938](file://server/src/modules/subscription/subscription.service.ts#L1-L938)
- [log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

## 架构概览
系统采用分层架构，前端通过HTTP接口与后端交互，后端控制器调用服务层，服务层通过Prisma访问数据库。支付模块与订阅模块相互协作，共同完成收入统计与成本核算。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant PC as "支付控制器"
participant PS as "支付服务"
participant SS as "订阅服务"
participant DB as "数据库"
Client->>PC : POST /api/payment/create
PC->>PS : createPaymentOrder(userId, planId, paymentMethod)
PS->>DB : 创建订单记录
PS-->>PC : 返回支付链接/二维码
PC-->>Client : 订单创建成功
Note over Client,DB : 支付完成后回调
Client->>PC : 支付宝/微信回调
PC->>PS : handlePaymentCallback(orderNo, paymentId, status)
PS->>DB : 更新订单状态
PS->>SS : activateSubscription(userId, planId)
SS->>DB : 激活订阅并更新Token余额
SS-->>PS : 订阅激活完成
PS-->>PC : 支付回调处理完成
PC-->>Client : 支付结果
```

**图表来源**
- [payment.controller.ts:9-33](file://server/src/modules/payment/payment.controller.ts#L9-L33)
- [payment.service.ts:122-191](file://server/src/modules/payment/payment.service.ts#L122-L191)
- [subscription.service.ts:408-509](file://server/src/modules/subscription/subscription.service.ts#L408-L509)

## 详细组件分析

### 支付模块
- 订单创建：支持支付宝、微信、模拟支付三种方式，返回支付链接或二维码
- 支付回调：处理支付宝/微信异步通知与同步返回，验证签名并更新订单状态
- 订阅激活：支付成功后激活订阅并初始化Token余额
- 订单查询：提供订单列表与详情查询接口

```mermaid
flowchart TD
Start([开始]) --> CreateOrder["创建订单"]
CreateOrder --> ChooseMethod{"选择支付方式"}
ChooseMethod --> |支付宝| Alipay["生成支付宝支付链接/二维码"]
ChooseMethod --> |微信| Wechat["生成微信支付二维码"]
ChooseMethod --> |模拟| Mock["模拟支付"]
Alipay --> Pay["用户支付"]
Wechat --> Pay
Mock --> Pay
Pay --> Callback{"收到回调"}
Callback --> |验证签名| UpdateOrder["更新订单状态"]
UpdateOrder --> ActivateSub["激活订阅并初始化Token余额"]
ActivateSub --> End([结束])
Callback --> |验证失败| Fail["处理失败"]
Fail --> End
```

**图表来源**
- [payment.controller.ts:57-125](file://server/src/modules/payment/payment.controller.ts#L57-L125)
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)
- [subscription.service.ts:408-509](file://server/src/modules/subscription/subscription.service.ts#L408-L509)

**章节来源**
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)

### 订阅与配额模块
- 套餐管理：提供套餐列表与详情查询，支持多层级套餐体系
- Token管理：提供Token余额查询、使用记录查询、配额检查
- 音频时长计费：支持包月配额与按量计费，提供费用估算与扣除
- 书籍生成配额：提供书籍规模预估与生成配额检查

```mermaid
classDiagram
class SubscriptionService {
+getPlans()
+getPlanById(id)
+getUserSubscription(userId)
+getUserTokenBalance(userId)
+getTokenUsageList(userId, page, pageSize)
+checkQuota(userId, requiredTokens)
+calculateAudioCost(textLength, memberLevel, usedMinutes)
+getUserAudioBalance(userId)
+checkAudioQuota(userId, textLength)
+consumeAudioMinutes(userId, textLength, description)
+getAudioEstimate(userId, textLength)
}
class PaymentService {
+createPaymentOrder(userId, planId, paymentMethod, returnUrl)
+handlePaymentCallback(orderNo, paymentId, status)
+activateSubscription(userId, planId)
+getOrderList(userId, page, pageSize)
+getOrderDetail(orderNo, userId)
}
SubscriptionService --> PaymentService : "订阅激活依赖"
```

**图表来源**
- [subscription.service.ts:312-408](file://server/src/modules/subscription/subscription.service.ts#L312-L408)
- [payment.service.ts:122-191](file://server/src/modules/payment/payment.service.ts#L122-L191)

**章节来源**
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [subscription.service.ts:1-938](file://server/src/modules/subscription/subscription.service.ts#L1-L938)

### 日志与审计模块
- 请求日志：记录HTTP请求的详细信息，包括方法、路径、状态码、响应时间等
- 错误分析：自动分析错误模式并提供修复建议
- 统计数据：提供日志统计信息，帮助监控系统健康状况

```mermaid
sequenceDiagram
participant Service as "服务层"
participant LogCtrl as "日志控制器"
participant LogSvc as "日志服务"
participant FS as "文件系统"
Service->>LogCtrl : 记录请求日志
LogCtrl->>LogSvc : logRequest(log)
LogSvc->>FS : 异步保存日志文件
LogSvc-->>Service : 日志记录完成
Service->>LogCtrl : 获取错误分析
LogCtrl->>LogSvc : analyzeErrors()
LogSvc-->>LogCtrl : 返回错误分析结果
LogCtrl-->>Service : 错误分析完成
```

**图表来源**
- [log.controller.ts:8-73](file://server/src/services/log.controller.ts#L8-L73)
- [log.service.ts:140-271](file://server/src/services/log.service.ts#L140-L271)

**章节来源**
- [log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

### 财务API接口定义
- 支付相关接口
  - POST /api/payment/create：创建支付订单
  - POST /api/payment/mock：模拟支付（开发环境）
  - POST /api/payment/alipay/notify：支付宝异步通知
  - GET /api/payment/alipay/return：支付宝同步返回
  - POST /api/payment/wechat/notify：微信支付回调
  - GET /api/payment/wechat/query/:orderNo：查询微信支付订单状态
  - GET /api/payment/orders：获取订单列表
  - GET /api/payment/orders/:orderNo：获取订单详情
  - POST /api/payment/alipay/qrcode：生成支付宝扫码支付二维码

- 订阅与配额相关接口
  - GET /api/subscription/plans：获取所有套餐列表
  - GET /api/subscription/plans/:id：获取单个套餐详情
  - GET /api/subscription/subscription：获取用户订阅信息
  - GET /api/subscription/balance：获取用户Token余额
  - GET /api/subscription/usage：获取Token使用记录
  - GET /api/subscription/quota：获取用户配额（兼容旧接口）
  - POST /api/subscription/check-quota：检查配额
  - GET /api/subscription/book-scale-estimate：获取书籍规模预估字数
  - GET /api/subscription/book-generation-quota：检查书籍生成配额
  - POST /api/subscription/check-quota-words：检查当前额度是否足够生成指定字数
  - GET /api/subscription/audio-balance：获取用户音频时长余额
  - GET /api/subscription/audio-estimate：获取音频生成预估

**章节来源**
- [订阅系统使用说明.md:233-409](file://docs/订阅系统使用说明.md#L233-L409)

### 财务数据模型
- 订阅计划（SubscriptionPlan）：包含套餐名称、等级、价格、Token配额、功能权限等
- 订阅记录（Subscription）：包含用户ID、套餐ID、起止时间、状态、自动续费等
- Token使用记录（TokenUsage）：包含用户ID、类型、消耗数量、内容长度、描述等
- 订单（Order）：包含用户ID、订单号、套餐ID、金额、状态、支付方式等

```mermaid
erDiagram
SUBSCRIPTION_PLAN {
int id PK
string name
int level
decimal priceMonthly
decimal priceYearly
int monthlyTokens
int yearlyTokens
int dailyGenerations
int perGenerationLimit
int voiceOptions
string audioQuality
boolean apiAccess
boolean batchProcessing
boolean teamManagement
}
SUBSCRIPTION {
int id PK
int userId
int planId FK
datetime startDate
datetime endDate
string status
boolean autoRenew
}
TOKEN_USAGE {
int id PK
int userId
string type
int amount
int contentLength
int orderId
text description
datetime createdAt
}
ORDER {
int id PK
int userId
string orderNo
int planId
decimal amount
string status
string paymentMethod
datetime paidAt
datetime createdAt
datetime updatedAt
}
USER {
int id PK
int memberLevel
datetime memberExpireAt
int usedAudioMinutes
datetime subscriptionResetDate
}
SUBSCRIPTION_PLAN ||--o{ SUBSCRIPTION : "拥有"
USER ||--o{ SUBSCRIPTION : "订阅"
USER ||--o{ TOKEN_USAGE : "使用"
ORDER }o--|| SUBSCRIPTION_PLAN : "对应"
```

**图表来源**
- [schema.prisma:348-391](file://server/prisma/schema.prisma#L348-L391)
- [migration.sql:270-301](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql#L270-L301)
- [支付集成指南.md:277-336](file://docs/支付集成指南.md#L277-L336)

**章节来源**
- [schema.prisma:348-391](file://server/prisma/schema.prisma#L348-L391)
- [migration.sql:270-301](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql#L270-L301)
- [支付集成指南.md:277-336](file://docs/支付集成指南.md#L277-L336)

### 收入统计与成本核算
- 收入统计：基于订单表的金额与状态统计，支持按时间维度聚合
- 成本核算：结合TTS成本配置与Token消耗记录，计算生成成本与利润
- 利润分析：通过收入减去成本得到利润，支持不同套餐等级的利润分析

**章节来源**
- [subscription.service.ts:128-155](file://server/src/modules/subscription/subscription.service.ts#L128-L155)
- [TTS成本分析报告.md:62-152](file://docs/TTS成本分析报告.md#L62-L152)

### 结算周期设置与对账流程
- 结算周期：按月结算，订阅到期后自动重置配额
- 对账流程：定期核对订单状态与支付回调，确保账目一致
- 银行转账：支持银行转账对账，生成对账差异报告

**章节来源**
- [subscription.service.ts:617-649](file://server/src/modules/subscription/subscription.service.ts#L617-L649)
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)

### 税务处理机制
- 税务登记：根据业务类型进行税务登记与发票开具
- 发票管理：支持电子发票与纸质发票管理，生成税务报表
- 合规要求：遵循当地税务法规，确保税务处理合规

**章节来源**
- [feature_list_subscription.json:214-252](file://feature_list_subscription.json#L214-L252)

### 多渠道收入管理、汇率转换与跨境结算
- 多渠道收入：支持支付宝、微信、银行转账等多种支付渠道
- 汇率转换：集成汇率API，支持多币种结算
- 跨境结算：支持跨境支付与外汇管理，符合外汇管理规定

**章节来源**
- [feature_list_subscription.json:250-283](file://feature_list_subscription.json#L250-L283)

### 凭证生成与审计跟踪
- 凭证生成：自动生成财务凭证，支持导出与打印
- 审计跟踪：记录所有财务操作的审计日志，支持追溯与查询

**章节来源**
- [log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

## 依赖分析
- 支付模块依赖订阅模块进行订阅激活
- 订阅模块依赖支付模块获取订单状态
- 日志模块独立运行，为其他模块提供审计支持

```mermaid
graph TB
PC["支付控制器"] --> PS["支付服务"]
SC["订阅控制器"] --> SS["订阅服务"]
PS --> SS
LC["日志控制器"] --> LS["日志服务"]
PS --> DB["数据库"]
SS --> DB
LS --> DB
```

**图表来源**
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)

**章节来源**
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)

## 性能考虑
- 支付回调异步处理：避免阻塞主线程，提高系统吞吐量
- 日志异步写入：减少I/O阻塞，提升系统稳定性
- 数据库索引优化：为常用查询字段建立索引，提升查询性能

## 故障排除指南
- 支付回调失败：检查签名验证、回调地址配置与服务器日志
- 订单状态异常：核对订单表状态与回调处理结果
- Token余额不足：检查配额检查逻辑与使用记录
- 日志分析：利用错误分析功能快速定位问题

**章节来源**
- [log.controller.ts:88-173](file://server/src/services/log.controller.ts#L88-L173)
- [log.service.ts:217-297](file://server/src/services/log.service.ts#L217-L297)

## 结论
财务结算系统通过清晰的模块划分与完善的API设计，实现了从收入统计、成本核算到利润分析的全流程管理。系统具备良好的扩展性与可维护性，能够满足多渠道收入管理、汇率转换、跨境结算与合规要求。通过日志与审计模块，系统提供了完整的审计跟踪能力，确保财务数据的准确性与可追溯性。

## 附录
- 功能规划：参考功能清单，了解待完成与已完成的功能模块
- 内容合规：提供内容合规检查系统，确保生成内容符合行业规范

**章节来源**
- [feature_list_subscription.json:214-283](file://feature_list_subscription.json#L214-L283)
- [feature_list_content_generate.json:592-628](file://feature_list_content_generate.json#L592-L628)