## 现状速览

* 后端框架：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`

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