🧾 发票管理设计
本章详述即时配送小程序的发票管理功能，包括：发票申请流程、发票类型、开票规则、数据表结构、管理端开票审核，以及发票开具和寄送流程。
电子发票
纸质发票
专票/普票
发票说明：用户可在订单完成后申请开票，开票金额为实际支付金额（不含优惠券、红包等）；发票由平台统一开具，也可对接第三方开票服务商（如百望、金蝶）。
一、发票申请流程
1.1 用户申请发票时序图
sequenceDiagram
participant U as 用户
participant APP as 小程序
participant API as 后端服务
participant INV as 发票系统
participant ADMIN as 管理端
participant TAX as 税务局
U->>APP: 进入发票申请页面
APP->>API: 获取可开票订单
API-->>APP: 订单列表(已支付订单)
U->>APP: 选择订单+填写发票信息
APP->>API: 提交发票申请
API->>INV: 创建发票申请记录
INV->>ADMIN: 推送待开票任务
ADMIN->>API: 审核通过
API->>INV: 开具发票
INV->>TAX: 发票上传税务局验真
TAX-->>INV: 验真通过
alt 电子发票
INV-->>API: 返回发票PDF/OFDE
API-->>APP: 通知用户下载
APP-->>U: 展示发票
else 纸质发票
INV-->>API: 返回发票号
API-->>LOG[物流]: 发起快递
LOG-->>U: 发票寄送
end
1.2 发票开具规则
| 规则项 | 说明 |
|---|
| 开票主体 | 平台公司（总公司或地方分公司） |
| 开票内容 | 快递服务费、配送费 |
| 开票金额 | 订单实际支付金额（不含优惠券、红包、积分抵扣） |
| 开票时限 | 订单完成后即可申请，有效期30天 |
| 合并开票 | 同一用户多笔订单可合并开票，单次最多10笔 |
| 增票资质 | 企业用户可申请增值税专用发票，需审核三证合一 |
二、发票类型说明
2.1 发票类型对比
| 类型 | 税率 | 开票时间 | 寄送 | 资质要求 |
|---|
| 电子普票 | 6% | 实时 | 无需 | 个人/企业 |
| 纸质普票 | 6% | 1-3工作日 | 快递到付 | 个人/企业 |
| 增值税专用发票 | 13% | 3-5工作日 | 快递到付 | 企业（需增票资质） |
2.2 发票状态机
stateDiagram-v2
[*] --> 待申请: 用户发起
待申请 --> 待审核: 提交申请
待审核 --> 开具中: 审核通过
待审核 --> 已拒绝: 审核不通过
已拒绝 --> [*]: 通知用户
开具中 --> 已开具: 开具成功
开具中 --> 开具失败: 开具失败
开具失败 --> 待审核: 重新申请
已开具 --> 已寄送: 纸质发票寄出
已开具 --> 已下载: 电子发票已查看
已寄送 --> [*]: 通知用户
已下载 --> [*]: 通知用户
三、发票数据表
3.1 发票申请表 ot_invoice
| 字段 | 类型 | 说明 |
|---|
| id | bigint | 主键 |
| invoice_no | varchar(32) | 发票号 |
| user_id | bigint | 用户ID |
| invoice_type | tinyint | 发票类型(1电子普票/2纸质普票/3专票) |
| invoice_title | varchar(100) | 发票抬头 |
| tax_no | varchar(50) | 税号(企业必填) |
| address | varchar(200) | 地址(专票必填) |
| phone | varchar(20) | 电话(专票必填) |
| bank_name | varchar(50) | 开户行(专票必填) |
| bank_account | varchar(30) | 银行账号(专票必填) |
| amount | decimal(12,2) | 开票金额 |
| tax_amount | decimal(10,2) | 税额 |
| status | tinyint | 状态(0待审核/1开具中/2已开具/3已拒绝/4已寄送) |
| email | varchar(100) | 接收邮箱(电子票) |
| express_no | varchar(50) | 快递单号 |
| receive_addr | varchar(200) | 收货地址 |
| remark | varchar(200) | 备注 |
| request_at | datetime | 申请时间 |
| audit_at | datetime | 审核时间 |
| issue_at | datetime | 开具时间 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
3.2 发票与订单关联表 ot_invoice_order
| 字段 | 类型 | 说明 |
|---|
| id | bigint | 主键 |
| invoice_id | bigint | 发票ID |
| order_id | bigint | 订单ID |
| order_no | varchar(32) | 订单编号 |
| pay_amount | decimal(10,2) | 订单实付金额 |
| created_at | datetime | 创建时间 |
3.3 发票配置表 ot_invoice_config
| 字段 | 类型 | 说明 |
|---|
| id | bigint | 主键 |
| company_name | varchar(100) | 开票公司名称 |
| tax_no | varchar(50) | 税号 |
| address | varchar(200) | 地址 |
| phone | varchar(20) | 电话 |
| bank_name | varchar(50) | 开户行 |
| bank_account | varchar(30) | 账号 |
| invoice_tax_rate | decimal(5,4) | 税率(0.06/0.13) |
| service_phone | varchar(20) | 客服电话 |
| status | tinyint | 状态 |
四、发票核心API
| 接口 | 说明 | 关键参数 |
|---|
GET /app/ot/invoice/can-invoice-orders | 获取可开票订单 | - |
POST /app/ot/invoice/apply | 申请开票 | order_ids, invoice_type, title, tax_no... |
GET /app/ot/invoice/list | 发票列表 | page, size, status |
GET /app/ot/invoice/detail | 发票详情 | invoice_id |
GET /app/ot/invoice/download | 下载发票 | invoice_id |
POST /admin/ot/invoice/page | 管理端发票列表 | page, size, status, date |
POST /admin/ot/invoice/audit | 审核发票 | invoice_id, agree, remark |
POST /admin/ot/invoice/issue | 开具发票 | invoice_id |
POST /admin/ot/invoice/reject | 拒绝发票 | invoice_id, reason |
POST /admin/ot/invoice/express | 填写快递信息 | invoice_id, express_no |
文档同步：requirements_v2.md 发票模块 | 维护：项目团队