## 目标概述

* 加强“交易管理-发票附件与发送邮箱”能力，完善数据记录与事务保障。

* 改进“开票弹窗附件上传”支持多文件上传（后端存储结构）。

* 优化“用户管理备注与操作记录”，区分备注维度并完善日志。

* 覆盖单元/集成测试、数据库迁移、API文档与审计日志。

## 数据库与模型变更

* EmailSendLog

  * 新增：`extra: JSONField(null=True)` 完整记录发送邮箱的请求数据（收件人、主题、正文、附件列表、重试信息等）。

* Invoice（或与开票弹窗相关的业务模型）

  * 新增：`attachments: JSONField(null=True)` 支持多个附件URL（与弹窗上传对应）。

* <br />

* 迁移脚本：创建/修改上述字段；保留历史数据不丢失。

## 事务与原子性

* 发送邮箱流程（交易管理）

  * 封装在 `tortoise.transactions.in_transaction()` 中：邮件发送、EmailSendLog写入（含attachments/extra）原子提交；失败回滚。

  * extra写入内容：完整`SendEmailRequest`（收件人、主题、正文、附件URL/文件名、重试次数、客户端UA等）。

* 多文件上传至发票附件（开票弹窗）

  * 更新发票的 `attachments` 字段在同一事务内写入；如任一URL校验失败则回滚。

## 后端接口改造

* 上传组件（后端）

  * 新增：`POST /api/v1/upload/files` 接收 `files: List[UploadFile]`，统一返回 `urls: string[]`；保留现有单文件接口向后兼容。

* 交易管理（管理员）

  * `POST /api/v1/transactions/send-email` 扩展：

    * 入参支持 `file_urls: string[]`（与/或单文件），服务端聚合附件；

    * 在事务中记录 EmailSendLog（含attachments与extra），返回log\_id与状态；

    * 回显接口（详情/列表）新增 `extra` 字段完整展示发送记录。

* 开票弹窗附件（管理员/或对应端）

  * 新增/改造：`PUT /api/v1/invoice/{id}/attachments` 入参 `urls: string[]`，更新发票 `attachments`。

  * 列表/详情回显 `attachments: string[]`。

* 用户管理备注优化（管理员端）

  * 新接口：`PUT /api/v1/app-user-admin/{user_id}/notes`

    * 入参：`system_notes?: string`、`user_notes?: string`（可选择性更新）

    * 逻辑：仅更新提供的字段；不影响其他字段。

  * 修复：`POST /api/v1/app-user-admin/quota` 仅调整次数，不再自动写入 `user.notes`。

  * 操作日志：在调整配额、更新备注、停用启用等操作时写入 `AppUserOperationLog`。

## 前端改造（要点）

* 多文件上传组件

  * 改为多选/拖拽支持；对每个文件显示上传进度与失败重试；

  * 成功后收集URL数组写入发票 `attachments` 或作为邮件附件来源；

  * 兼容旧接口：若后端仅返回单URL，前端仍正常显示（降级为单文件模式）。

* 开票弹窗

  * 支持附件列表预览与移除；提交时调用 `PUT /invoice/{id}/attachments`；

* 邮件发送弹窗

  * 选择附件来源（已上传的附件/本地文件再上传）；提交后在详情页面完整回显 `extra`（含附件清单与正文等）。

## 审计与日志

* 关键操作：邮件发送、发票附件更新、用户备注更新、配额调整

  * 统一调用审计记录（路由中间件已存在，补充结构化日志：`logger.info()` + DB审计表/操作日志表写入）。

## 测试方案

* 单元测试

  * Email发送控制器：事务成功/失败回滚（模拟抛错）

  * 多文件上传：文件类型校验、URL数组返回、尾随空白处理

  * 备注更新：选择性字段更新、不影响其他字段

* 集成测试（FastAPI + httpx.AsyncClient）

  * 发送邮箱：请求→持久化校验（attachments/extra）→回显接口校验

  * 附件上传：批量上传、更新发票、列表/详情回显

  * 用户备注：接口调用→DB值校验→操作日志存在

## 迁移与兼容

* 使用现有迁移工具（如Aerich）生成并应用迁移：新增JSON/Text字段；

* 前端保留旧接口兼容：若上传仍走单文件，后端返回数组长度1；

* API文档（OpenAPI）

  * 补充/更新以上端点的schema说明、示例请求/响应、错误码约定；

## 实施步骤与交付

1. 数据模型与迁移脚本编写与应用（EmailSendLog、Invoice、AppUser/OperationLog）。
2. 后端接口改造与事务封装（邮件发送、多文件上传、发票附件更新、备注接口）。
3. 前端组件与弹窗改造（多文件上传、进度与错误处理、回显extra）。
4. 审计日志与结构化日志补充。
5. 单元与集成测试编写，覆盖核心路径。
6. 更新接口文档与部署回归验证。