邹方成
cc352d3184
refactor: 优化API路由和响应模型 feat(admin): 添加App用户管理接口 feat(sms): 实现阿里云短信服务集成 feat(email): 添加SMTP邮件发送功能 feat(upload): 支持文件上传接口 feat(rate-limiter): 实现手机号限流器 fix: 修复计算步骤入库问题 docs: 更新API文档和测试计划 chore: 更新依赖和配置
185 lines
7.9 KiB
Markdown
185 lines
7.9 KiB
Markdown
## 现状速览
|
||
|
||
* 后端框架：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`。
|
||
|
||
<br />
|
||
|
||
## 发送逻辑实现要点
|
||
|
||
* 设置：在 `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`
|
||
|
||
——请确认方案后，我将按上述步骤开始落地实现、编写迁移与测试。
|