guzhi/.trae/documents/估值二期 API 设计方案.md

目标与范围

• 针对“估值二期”需求（用户端、管理端）设计完整 API，去除 Webhook 回调。
• 对齐现有约定：认证 POST /api/v1/base/access_token（app/api/v1/base/base.py:19-38）、token 请求头（web/src/utils/http/interceptors.js:11-14）；响应 Success/SuccessExtra/Fail（app/schemas/base.py），成功码 code===200（web/src/utils/http/interceptors.js:23-33）；估值域已有 /api/v1/valuations（app/api/v1/valuations/valuations.py:21-191）。

核心流程

• 用户端：登录→评估提交→个人中心（汇款凭证、抬头选择、类型选择、发票列表/详情）→估值记录（下载证书/报告、分享、历史结果、剩余次数）。
• 管理端：交易管理（查看/核验/邮件/开票/状态）→用户管理（信息/操作/修改/审核/投诉/短信文案/证书与报告）→审核列表（上传证书/下载/重传）。

实体与关系

• AppUser ⇄ Valuation(1..n)、Invoice(1..n)、InvoiceHeader(n)
• Valuation ⇄ ValuationCalculationStep(1..n) ⇄ Certificate/Report
• Invoice ⇄ InvoiceHeader/PaymentReceipt/Transaction
• Complaint、SMSMessage 与用户/估值/发票按需关联

端点设计（与前端映射保持一致）

• 认证与用户
  • POST /api/v1/base/access_token 登录（app/api/v1/base/base.py:19-38）
  • GET /api/v1/base/userinfo 用户信息（app/api/v1/base/base.py:40-46）
  • GET /api/v1/app-user/profile 当前用户画像与剩余估值次数
  • GET /api/v1/app-user/list、GET /api/v1/app-user/get、POST /api/v1/app-user/register|update、DELETE /api/v1/app-user/delete（对齐 web/src/api/index.js:433-503）
• 估值评估（沿用并扩展）
  • POST /api/v1/valuations/、GET /api/v1/valuations/、GET /api/v1/valuations/{id}（已存在）
  • GET /api/v1/valuations/{id}/steps（已存在，用于过程展示）
  • GET /api/v1/valuations/{id}/certificate（新增：证书下载）
  • GET /api/v1/valuations/{id}/report（新增：报告下载）
  • POST /api/v1/valuations/{id}/share（新增：生成分享链接/小程序码，异步）
  • POST /api/v1/valuations/batch/delete（已存在）
• 发票与交易（保留现有路径）
  • GET /api/v1/invoice/list、GET /api/v1/invoice/detail、POST /api/v1/invoice/create|update|send|remind|refund、DELETE /api/v1/invoice/delete、POST /api/v1/invoice/update-status（对齐 web/src/api/index.js:504-725）
  • POST /api/v1/invoice/{id}/receipt（新增：上传付款凭证）
  • GET /api/v1/invoice/headers、GET /api/v1/invoice/headers/{id}、POST /api/v1/invoice/headers（新增：抬头管理）
  • POST /api/v1/invoice/{id}/issue（新增：开票，异步 Job）
• 审核与证书
  • GET /api/v1/review/valuations 审核列表（新增）
  • POST /api/v1/review/valuations/{id}/approve|reject（复用估值审核，app/api/v1/valuations/valuations.py:167-183）
  • POST /api/v1/review/valuations/{id}/certificate 上传证书（新增）
  • PUT /api/v1/review/valuations/{id}/report 重传报告（新增）
• 投诉与短信
  • GET /api/v1/complaints、GET /api/v1/complaints/{id}、PUT /api/v1/complaints/{id}（新增）
  • GET /api/v1/sms/templates、POST /api/v1/sms/templates、POST /api/v1/sms/send（新增）

请求/响应格式与认证

• 统一 JSON；请求头 token 必填（除登录与公共资源）。
• 成功：{code:200,data:...,msg:"success"}；失败：{code:4xx/5xx,msg:"错误"}。

字段与校验（示例）

• ValuationCreate：asset_name(1-64), institution(1-128), industry(1-64), heritage_level?, inputs(object), attachments?[url[]]
• InvoiceCreate：ticket_type(electronic|paper), invoice_type(special|normal), phone, email, company_name, tax_number, register_address, register_phone, bank_name, bank_account
• PaymentReceipt：url, uploaded_at, verified
• ShareRequest：channel(miniprogram|link), expire(<=604800)
• 规则：邮箱/手机号/税号格式；枚举校验；附件数量与大小限制。

错误码

• 200 成功；400 参数错误；401 未认证（前端自动登出，web/src/utils/http/interceptors.js:45-53）；403 无权限；404 不存在；409 冲突；422 校验失败；429 频率限制；500 内部错误。

批量与异步（无 Webhook）

• 批量：发票批量开具、邮件批量发送（POST /api/v1/invoice/batch/issue|send）。
• 异步 Job：开票/报告/分享生成返回 job_id；查询 GET /api/v1/jobs/{id}（status: pending|running|success|failed）。客户端采用轮询或前端提示重试。

性能目标

• 登录/用户信息 P95 ≤ 100ms；列表分页 P95 ≤ 200ms（单页 ≤ 100 条）。
• 异步任务完成 ≤ 5s；QPS（单实例）：读 200+/s、写 50+/s。

实施建议

1. 在 app/api/v1/ 新增 invoices/reviews/complaints/sms 路由文件。
2. 在 controllers/ 实现控制器，复用 ValuationController 的计算步骤记录（app/controllers/valuation.py:24-53）。
3. 在 schemas/ 新增/扩展 Pydantic 模型，严格校验。
4. 增加 Job 状态查询端点，统一返回结构；无 Webhook 的情况下采用客户端轮询。
5. 前端按 web/src/api/index.js 对齐接入，复用错误处理与 401 登出。

——请确认该无 Webhook 版本的 API 方案，确认后我将开始后端路由/控制器/模型实现并提供前端对接示例。