## 目标与范围
- 针对“估值二期”需求（用户端、管理端）设计完整 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 方案，确认后我将开始后端路由/控制器/模型实现并提供前端对接示例。