zfc/guzhi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
guzhi/.trae/documents/交易管理_用户管理_估值模块增量改造方案.md
邹方成 cc352d3184 feat: 重构后端服务并添加新功能 
refactor: 优化API路由和响应模型
feat(admin): 添加App用户管理接口
feat(sms): 实现阿里云短信服务集成
feat(email): 添加SMTP邮件发送功能
feat(upload): 支持文件上传接口
feat(rate-limiter): 实现手机号限流器
fix: 修复计算步骤入库问题
docs: 更新API文档和测试计划
chore: 更新依赖和配置
2025-11-19 19:36:03 +08:00

7.9 KiB
Raw Blame History

现状速览

  • 后端框架：FastAPI；ORM：Tortoise；权限：DependAuth + DependPermission 挂载在 admin 路由（app/api/v1/__init__.py:33-37）。

  • 用户端估值评估路由：/api/v1/app-valuations（app/api/v1/app_valuations/app_valuations.py），控制器分层清晰（app/controllers/user_valuation.py、app/controllers/valuation.py）。

  • 上传目前仅支持图片（app/controllers/upload.py:12-52，app/api/v1/upload/upload.py:7-14）。

  • 发票与抬头能力完善（app/api/v1/invoice/invoice.py、app/controllers/invoice.py）。

  • Web 管理端用户列表当前使用 Mock 数据展示“剩余体验次数”（web/src/views/user-management/user-list/index.vue:115-122 与 web/src/api/index.js:279-352）。

目标改造概览

  • 交易管理新增“邮件发送”接口，支持正文与附件，完备校验与日志。

  • 用户管理新增“剩余估值次数”字段与管理员调额能力，提供操作日志（前/后值、类型、备注）。

  • 估值表新增“报告/证书”URL 字段与多格式上传能力，生成可下载链接。

  • 估值表新增“统一社会信用代码/身份证号”与“业务/传承介绍”，前后端同步与校验。

  • 全量权限控制、API 文档补充、数据库变更记录与单元测试覆盖。

数据库与模型变更

  • ValuationAssessment（app/models/valuation.py）新增：

    • report_url: CharField(512)、certificate_url: CharField(512) 用于管理员上传的报告/证书下载地址。

    • credit_code_or_id: CharField(64) 用于统一社会信用代码或身份证号。

    • biz_intro: TextField 业务/传承介绍。

  • 用户配额与日志：

    • AppUser（app/models/user.py）新增 remaining_quota: IntField(default=0)。

    • 新增操作日志模型（建议放入 app/models/invoice.py 同模块管理，或新建 app/models/transaction.py）：AppUserQuotaLog 字段：app_user_id、operator_id、operator_name、before_count、after_count、op_type（如：付费估值）、remark、created_at。

    • 邮件发送日志模型：EmailSendLog 字段：email、subject、body 摘要（前 N 字符）、file_name/file_url、status（OK/FAIL）、error（可空）、sent_at。

  • 迁移：使用 Aerich 生成并升级（保持兼容，所有新增字段均可空或有安全默认值）。

接口设计与权限控制

  • 交易管理新增：POST /api/v1/transactions/send-email

    • Body（multipart 或 JSON）：

      • email（必填，邮箱校验）

      • subject（可选，默认“估值服务通知”）

      • body（必填，文案内容，长度与危险字符校验）

      • file（可选，UploadFile，或 file_url 字符串二选一）

    • 行为：使用标准库 smtplib + email 组合发送；支持 TLS/SSL；发送后落库 EmailSendLog；返回发送状态与日志 ID。

    • 权限：挂载于 transactions_router（已带 DependAuth、DependPermission，app/api/v1/__init__.py:52）。

  • 用户管理新增：

    • GET /api/v1/user/list 返回结构新增 remaining_quota 字段。

    • POST /api/v1/user/quota（管理员）调整用户剩余估值次数：

      • Body：user_id、target_count 或 delta、op_type、remark

      • 行为：读取当前值，计算前后值，更新 AppUser.remaining_quota，记录 AppUserQuotaLog。

    • GET /api/v1/user/{id}/quota-logs 返回日志列表（分页、类型筛选）。

  • 发票抬头查看：

    • 复用现有接口 GET /api/v1/invoice/headers?app_user_id=...（app/api/v1/invoice/invoice.py:118-124）。

  • 估值评估新增字段对外：

    • 管理端与用户端输出 Schema 同步包含 report_url、certificate_url、credit_code_or_id、biz_intro。

上传能力扩展

  • 控制器：新增 upload_file(file: UploadFile) 支持 pdf/docx/xlsx/zip 等白名单；存储到 app/static/files；生成可下载链接 settings.BASE_URL + /static/files/{name}。

  • 路由：POST /api/v1/upload/file（保留图片接口不变）。

  • 校验：

    • MIME 白名单与大小限制；文件名清洗与去重；异常返回 4xx/5xx。

Schema 与后端校验

  • 估值 Schema（app/schemas/valuation.py）新增并校验：

    • credit_code_or_id：正则校验（统一社会信用代码/18位身份证格式二选一）。

    • report_url、certificate_url：URL 格式校验。

  • 用户配额：新增 AppUserQuotaUpdateSchema 与 AppUserQuotaLogOutSchema。

  • 邮件发送：SendEmailRequest 支持两种附件输入；返回 SendEmailResponse。


发送逻辑实现要点

  • 设置：在 app/settings/config.py 增加 SMTP 相关配置：SMTP_HOST、SMTP_PORT、SMTP_USERNAME、SMTP_PASSWORD、SMTP_TLS、SMTP_FROM（默认 None，走环境变量注入）。

  • 发送器：app/services/email_client.py（或 app/controllers/transactions.py 内部封装），使用 smtplib.SMTP_SSL/SMTP.starttls()，构造 MIMEText 与 MIMEBase，附件从 UploadFile 或远程 file_url 下载后附加。

  • 错误处理：

    • 参数校验失败返回 422；SMTP 异常记录 EmailSendLog.error 并返回 500；长正文截断日志摘要防止超长存储。

  • 日志：统一 loguru 记录关键事件（如 transactions.email_send_start/ok/fail）。

权限控制与 API 权限表

  • 新增接口在 Api 表登记（路径+方法+标签），使用现有刷新接口 POST /api/v1/api/refresh 扫描路由自动入库。

  • 路由均落于已挂载依赖的 admin 模块，App 端路由继续独立（app/api/v1/__init__.py:28-33）。

API 文档与变更记录

  • 为所有新增接口与控制器方法补充函数级注释（功能、参数、返回值），满足用户规范。

  • 通过 FastAPI 自动生成的 OpenAPI 展示；补充接口示例与错误码说明（Docstring）。

  • 数据库变更记录：在迁移文件中含新增字段/表说明；在说明文档中列出字段语义与默认值（本次提交提供变更概要）。

单元测试计划

  • 邮件发送：

    • 伪造 FakeEmailClient，覆盖成功/失败/附件两种输入；比照 tests/api/v1/test_sms.py 的 monkeypatch 风格。

  • 用户配额：

    • 调额接口：前后值正确、日志记录正确、权限检查（需登录管理员）。

  • 估值字段：

    • 创建/更新时包含新字段；URL 与正则校验失败用例；上传文件生成链接断言。

  • 上传：

    • 非法 MIME 与超限大小拒绝；合法文件成功返回 URL。

兼容性与回滚策略

  • 所有新增字段均为可空或安全默认，旧数据不受影响。

  • 新增接口均为新增路由，不改动原有行为；前端逐步切换数据源，保留 Mock 作为回退。

  • 迁移脚本按标准生成；如需回滚 aerich 支持 downgrade。

实施步骤

  1. 模型与 Schema 更新；生成 Aerich 迁移；本地升级并验证。
  2. 上传控制器扩展与新路由；估值控制器/输出字段同步。
  3. 交易管理发送接口（含 SMTP 封装、日志落库、异常处理）。
  4. 用户配额接口与日志模型/路由；admin 列表与详情改造。
  5. 权限入库与刷新；为接口添加函数级注释。
  6. 单元测试编写与通过；OpenAPI 检视；交付 API/DB 变更说明。

关键代码定位参考

  • 路由注册：app/api/v1/__init__.py:28-52

  • 用户端估值入口：app/api/v1/app_valuations/app_valuations.py:233-318

  • 估值控制器：app/controllers/valuation.py:73-100、app/controllers/user_valuation.py:21-42

  • 上传控制器：app/controllers/upload.py:12-52

  • 发票抬头接口：app/api/v1/invoice/invoice.py:118-144

  • 管理端用户列表（前端）：web/src/views/user-management/user-list/index.vue:69-166

  • Mock 数据与 API：web/src/api/index.js:279-352, 433-479

——请确认方案后，我将按上述步骤开始落地实现、编写迁移与测试。