guzhi/交易管理与用户备注功能增强实施计划.md at d4b2c801f4f2f04d02982522505ac4d39e5b4205

zfc/guzhi

邹方成 552c02516a feat(发票): 支持多附件上传和邮件发送功能

refactor(用户管理): 优化用户列表查询和备注字段处理

feat(估值): 评估报告和证书URL改为数组类型并添加下载地址

docs: 添加交易管理与用户备注功能增强实施计划

fix(邮件): 修复邮件发送接口的多附件支持问题

style: 清理注释代码和格式化文件

2025-11-25 20:09:50 +08:00

目标概述

EmailSendLog
- 新增：extra: JSONField(null=True) 完整记录发送邮箱的请求数据（收件人、主题、正文、附件列表、重试信息等）。
Invoice（或与开票弹窗相关的业务模型）
- 新增：attachments: JSONField(null=True) 支持多个附件URL（与弹窗上传对应）。
迁移脚本：创建/修改上述字段；保留历史数据不丢失。

发送邮箱流程（交易管理）
- 封装在 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值校验→操作日志存在