# 发票申请功能联调说明

适用范围：

- 后台：`business-finance`（源码包 `com.jeesharp.business.modules.finance.invoice`）
- 小程序端：订单详情、发票申请、发票结果页

目标：

- 用户可在小程序端对订单发起发票申请
- 后台可查看申请单、同意或驳回
- 同意后后台可上传发票附件
- 小程序端可查看审核结果并下载附件

---

## 一、数据库准备

执行：

- [finance_schema.sql](../../../doc/sql/business-finance/finance_schema.sql)（建表，权威脚本）
- [finance_invoice.sql](../../../doc/sql/business-finance/finance_invoice.sql)（占位说明，执行请以 `finance_schema.sql` 为准）
- [finance_seed.sql](../../../doc/sql/business-finance/finance_seed.sql) 可选模拟数据

会员库增量场景：若历史环境仅在 `member.sql` 中建过表，可继续保留原表；新环境请执行 `finance_schema.sql`。

重点确认表：

- `app_member_invoice_apply`

核心字段：

- `member_id`
- `order_id`
- `order_no`
- `biz_type`
- `invoice_type`
- `invoice_title`
- `invoice_tax_no`
- `email`
- `mobile`
- `amount_label`
- `apply_reason`
- `status`
- `audit_remark`
- `invoice_file_key`
- `invoice_file_name`
- `invoice_file_url`
- `audit_time`
- `audit_by_id`

状态说明：

- `pending`
- `approved`
- `rejected`

---

## 二、菜单权限准备

执行：

- [finance_menu_permission.sql](./finance_menu_permission.sql)

确认权限：

- `member:invoiceApply:list`
- `member:invoiceApply:info`
- `member:invoiceApply:save`
- `member:invoiceApply:delete`
- `member:invoiceApply:audit`

后台页面入口：

- `/business/member/invoiceApply`

---

## 三、后端接口

### 1. 后台管理接口

控制器：

- `com.jeesharp.business.modules.finance.invoice.controller.MemberInvoiceApplyController`

接口（与迁移前一致，`${jeesharp.web.adminPath}` 前缀不变）：

- `GET /member/invoiceApply/v1/info?id={id}`
- `POST /member/invoiceApply/v1/list`
- `POST /member/invoiceApply/v1/save`
- `GET /member/invoiceApply/v1/delete?ids={ids}`
- `POST /member/invoiceApply/v1/audit`

审核入参示例：

```json
{
  "id": "申请单ID",
  "action": "approve",
  "auditRemark": "审核通过",
  "invoiceFileKey": "file-key",
  "invoiceFileName": "invoice.pdf",
  "invoiceFileUrl": "https://..."
}
```

`action` 可选：

- `approve`
- `reject`

### 2. 小程序接口

控制器：

- `InvoiceApplyMobileController`（`business-mobile-gateway`）

接口：

- `POST /mobile/member/invoiceApply/create`
- `GET /mobile/member/invoiceApply/result/{id}`
- `GET /mobile/member/invoiceApply/order/{orderId}`

创建入参示例：

```json
{
  "orderId": "订单ID",
  "orderNo": "订单编号",
  "bizType": "mall",
  "invoiceType": 1,
  "invoiceTitle": "张三",
  "invoiceTaxNo": "",
  "email": "demo@example.com",
  "mobile": "13800138000",
  "amountLabel": "198.00",
  "applyReason": "个人报销"
}
```

说明：

- 当前对 `mall` 订单做了严格订单校验（应用层调用 `business-mall` 模块的 `MallOrderApplicationService`）
- 同一 `memberId + orderId` 不允许重复申请

---

## 四、后台操作流程

### 1. 查看申请

进入：

- `/business/member/invoiceApply`

可按以下条件筛选：

- 订单编号
- 会员ID
- 业务类型
- 状态
- 发票抬头

### 2. 审核

`pending` 状态下可操作：

- 同意
- 驳回

#### 同意时

1. 填审核备注
2. 上传发票附件
3. 提交审核

审核后：

- `status = approved`
- 回填附件信息：
  - `invoice_file_key`
  - `invoice_file_name`
  - `invoice_file_url`

#### 驳回时

1. 填驳回原因
2. 提交审核

审核后：

- `status = rejected`
- `audit_remark` 保存驳回说明

---

## 五、小程序操作流程

### 1. 发起申请

入口：

- `pages/order/detail`

触发条件：

- 当前订单 `status = completed`

操作：

1. 打开订单详情
2. 点击 `申请发票`
3. 填写：
   - 发票抬头
   - 税号（企业可填）
   - 邮箱（选填）
   - 手机号（选填）
   - 申请备注（选填）
4. 提交申请

跳转：

- `pages/invoice/result`

### 2. 查看结果

如果订单已有申请单：

- 订单详情页按钮显示 `查看发票`

结果页展示：

- 订单号
- 状态
- 发票抬头
- 申请时间
- 审核备注（若有）
- 附件下载按钮（若已上传）

### 3. 下载附件

如果后台已上传发票附件：

- 小程序端点击 `下载发票附件`
- 优先：
  - `uni.downloadFile`
  - `uni.openDocument`
- 失败兜底：
  - 复制附件 URL

---

## 六、联调验收步骤

### 步骤 1：准备订单

确认存在一个已完成订单：

- `orderId`
- `orderNo`
- `bizType`
- `totalAmount`

### 步骤 2：小程序提交申请

校验：

- `POST /mobile/member/invoiceApply/create`
- `app_member_invoice_apply` 已新增记录
- 状态为 `pending`

### 步骤 3：后台审核

后台打开：

- `/business/member/invoiceApply`

执行：

- 同意并上传附件
  或
- 驳回并填写原因

校验：

- `status`
- `audit_remark`
- `invoice_file_url`

### 步骤 4：小程序回查

校验：

- `GET /mobile/member/invoiceApply/result/{id}`
- `GET /mobile/member/invoiceApply/order/{orderId}`
- 订单详情页按钮从 `申请发票` 变成 `查看发票`

### 步骤 5：附件下载

若已同意：

- 结果页显示下载按钮
- 能正常下载 / 打开文件

---

## 七、当前边界

当前已完成：

- 发票申请主流程闭环
- 后台审核与附件回填
- 小程序结果查看与附件下载

当前未做：

- 发票申请后台完整分页运营台优化
- 非 `mall` 业务类型的严格订单归属校验
- 发票撤回 / 重新申请
- 电子发票自动生成

---

## 八、建议后续优化

1. 发票申请后台页增加状态标签、附件预览、审核时间显示
2. 对接真实订单中心，按 `bizType` 校验订单归属
3. 支持重新申请 / 重新上传
4. 对接电子发票平台，审核通过后自动生成 PDF
