audio_codebuddy/.qoder/repowiki/zh/content/核心模块/订阅付费系统/财务结算.md

财务结算

本文引用的文件

• 支付集成指南.md
• 订阅系统使用说明.md
• TTS成本分析报告.md
• payment.controller.ts
• payment.service.ts
• subscription.controller.ts
• subscription.service.ts
• tts.service.ts
• log.controller.ts
• log.service.ts
• schema.prisma
• migration.sql
• feature_list_subscription.json
• feature_list_content_generate.json

目录

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

简介

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

项目结构

财务结算系统主要由以下模块组成：

• 支付模块：负责订单创建、支付回调、订阅激活、订单查询
• 订阅与配额模块：负责套餐管理、Token余额与使用记录、音频时长计费
• 日志与审计模块：负责请求日志记录、错误分析与审计跟踪

• 数据模型层：基于Prisma的数据库模型，支撑财务数据存储与查询

  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
• subscription.controller.ts:1-191
• log.controller.ts:1-233
• schema.prisma:348-391

章节来源

• 支付集成指南.md:277-336
• 订阅系统使用说明.md:233-409

核心组件

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

章节来源

• payment.controller.ts:1-258
• payment.service.ts:1-578
• subscription.controller.ts:1-191
• subscription.service.ts:1-938
• log.controller.ts:1-233
• log.service.ts:1-354

架构概览

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

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
• payment.service.ts:122-191
• subscription.service.ts:408-509

详细组件分析

支付模块

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

• 订单查询：提供订单列表与详情查询接口

  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
• payment.service.ts:358-406
• subscription.service.ts:408-509

章节来源

• payment.controller.ts:1-258
• payment.service.ts:1-578

订阅与配额模块

• 套餐管理：提供套餐列表与详情查询，支持多层级套餐体系
• Token管理：提供Token余额查询、使用记录查询、配额检查
• 音频时长计费：支持包月配额与按量计费，提供费用估算与扣除

• 书籍生成配额：提供书籍规模预估与生成配额检查

  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
• payment.service.ts:122-191

章节来源

• subscription.controller.ts:1-191
• subscription.service.ts:1-938

日志与审计模块

• 请求日志：记录HTTP请求的详细信息，包括方法、路径、状态码、响应时间等
• 错误分析：自动分析错误模式并提供修复建议

• 统计数据：提供日志统计信息，帮助监控系统健康状况

  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
• log.service.ts:140-271

章节来源

• log.controller.ts:1-233
• log.service.ts:1-354

财务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

财务数据模型

• 订阅计划（SubscriptionPlan）：包含套餐名称、等级、价格、Token配额、功能权限等
• 订阅记录（Subscription）：包含用户ID、套餐ID、起止时间、状态、自动续费等
• Token使用记录（TokenUsage）：包含用户ID、类型、消耗数量、内容长度、描述等

• 订单（Order）：包含用户ID、订单号、套餐ID、金额、状态、支付方式等

  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
• migration.sql:270-301
• 支付集成指南.md:277-336

章节来源

• schema.prisma:348-391
• migration.sql:270-301
• 支付集成指南.md:277-336

收入统计与成本核算

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

章节来源

• subscription.service.ts:128-155
• TTS成本分析报告.md:62-152

结算周期设置与对账流程

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

章节来源

• subscription.service.ts:617-649
• payment.service.ts:358-406

税务处理机制

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

章节来源

• feature_list_subscription.json:214-252

多渠道收入管理、汇率转换与跨境结算

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

章节来源

• feature_list_subscription.json:250-283

凭证生成与审计跟踪

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

章节来源

• log.controller.ts:1-233
• log.service.ts:1-354

依赖分析

• 支付模块依赖订阅模块进行订阅激活
• 订阅模块依赖支付模块获取订单状态

• 日志模块独立运行，为其他模块提供审计支持

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

图表来源

• payment.controller.ts:1-258
• subscription.controller.ts:1-191
• log.controller.ts:1-233

章节来源

• payment.controller.ts:1-258
• subscription.controller.ts:1-191
• log.controller.ts:1-233

性能考虑

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

故障排除指南

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

章节来源

• log.controller.ts:88-173
• log.service.ts:217-297

结论

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

附录

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

章节来源

• feature_list_subscription.json:214-283
• feature_list_content_generate.json:592-628