feat(交易管理): 新增多文件上传及邮件发送事务支持

- 新增多文件上传接口及发票附件存储
- 邮件发送流程增加事务保障及完整日志记录
- 用户管理备注支持分维度更新并记录操作日志
- 覆盖单元测试与集成测试用例

.trae/documents/估值审核联动与估值次数扣减实现方案.md

@@ -0,0 +1,131 @@
+## 目标概述
+
+* 加强“交易管理-发票附件与发送邮箱”能力，完善数据记录与事务保障。
+
+* 改进“开票弹窗附件上传”支持多文件上传（后端存储结构）。
+
+* 优化“用户管理备注与操作记录”，区分备注维度并完善日志。
+
+* 覆盖单元/集成测试、数据库迁移、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. 更新接口文档与部署回归验证。
+