邹方成
cc352d3184
refactor: 优化API路由和响应模型 feat(admin): 添加App用户管理接口 feat(sms): 实现阿里云短信服务集成 feat(email): 添加SMTP邮件发送功能 feat(upload): 支持文件上传接口 feat(rate-limiter): 实现手机号限流器 fix: 修复计算步骤入库问题 docs: 更新API文档和测试计划 chore: 更新依赖和配置
71 lines
5.3 KiB
Markdown
71 lines
5.3 KiB
Markdown
## 目标与范围
|
||
- 针对“估值二期”需求（用户端、管理端）设计完整 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 方案，确认后我将开始后端路由/控制器/模型实现并提供前端对接示例。 |