邹方成
cc352d3184
refactor: 优化API路由和响应模型 feat(admin): 添加App用户管理接口 feat(sms): 实现阿里云短信服务集成 feat(email): 添加SMTP邮件发送功能 feat(upload): 支持文件上传接口 feat(rate-limiter): 实现手机号限流器 fix: 修复计算步骤入库问题 docs: 更新API文档和测试计划 chore: 更新依赖和配置
59 lines
3.9 KiB
Markdown
59 lines
3.9 KiB
Markdown
## 输出目标
|
||
- 以 `admin`（后台）与 `app`（用户端）两大类重组全部现有 `v1` API。
|
||
- 统一每个接口的文档格式：路径、方法、版本、功能说明、公开/认证、（admin）权限要求、请求参数与格式、响应结构、错误代码。
|
||
- 版本标注统一为 `v1`（前缀 `"/api/v1"`）。
|
||
|
||
## 分类规则
|
||
- `admin`：在 `app/api/v1/__init__.py:33-38,45-51` 通过 `dependencies=[DependAuth, DependPermission]` 绑定的模块及其接口：`user/role/menu/api/dept/auditlog/valuations/invoice/transactions/third_party_api`，以及 `base`（后台登录与个人信息）。
|
||
- `app`：面向终端用户的模块：`app-user`、`app-valuations`、`sms`（登录与验证码相关）、`upload`。
|
||
- 管理功能但当前公开（未绑定后台依赖）：`industry/index/policy/esg`，归入 `admin（公开）`，在文档中明确“公开接口”。
|
||
|
||
## 文档结构
|
||
- 顶层两章：
|
||
- `app（用户端）`：模块分组（用户认证与账户、用户资料与仪表盘、用户端估值、短信验证码、上传）
|
||
- `admin（后台）`：模块分组（用户管理、角色管理、菜单管理、API 权限管理、部门管理、审计日志、估值评估、发票管理、交易管理、第三方内置接口、内容管理：行业/指数/政策/ESG、基础登录/个人信息）
|
||
- 接口条目统一字段：
|
||
- 路径：`/api/v1/<module>/<subpath>`
|
||
- 方法：`GET/POST/PUT/DELETE`
|
||
- 版本：`v1`
|
||
- 功能说明：一句话摘要
|
||
- 公开/认证：`公开` 或 `需认证`（`admin` 另标注“需权限校验”）
|
||
- 权限要求（admin）：是否受 `DependPermission` 控制（匹配 `(method, path)`）
|
||
- 请求参数：Query/Path/Body（Body 引用 `pydantic` 模型名）
|
||
- 响应结构：统一 `{code,msg,data}` 或分页 `{code,msg,data,total,page,page_size}`（引用响应模型）
|
||
- 错误代码：200/400/401/403/404/422/500（依据全局异常与业务抛出）
|
||
|
||
## 信息来源与标注依据
|
||
- 路由与版本：`app/api/v1/__init__.py:28-52`（前缀与模块挂载）。
|
||
- 认证与权限：
|
||
- `admin` 统一：`DependAuth`、`DependPermission`（`app/api/v1/__init__.py:33-38,45-51`；依赖定义于 `app/core/dependency.py`）。
|
||
- `app` 认证：`Depends(get_current_app_user)`/`Depends(get_current_app_user_id)`（`app/utils/app_user_jwt.py:51,71-72`）。
|
||
- 单接口特例：`sms` 的 `/send-report` 需后台认证（`app/api/v1/sms/sms.py:68`）。
|
||
- 请求/响应模型：端点签名与 `response_model`（来源 `app/schemas/*`）。
|
||
- 错误码与统一响应：`app/core/init_app.py:56-59`（注册），`app/core/exceptions.py:15,23,31`（处理器）。
|
||
|
||
## 示例格式（两条）
|
||
- `app｜POST /api/v1/sms/send-code`（v1）
|
||
- 功能：发送登录验证码到手机号
|
||
- 公开/认证：公开
|
||
- 请求参数（Body）：`SendCodeRequest`
|
||
- 响应结构：`SendResponse`（`{code,msg,data}`）
|
||
- 错误码：`400/422/500`
|
||
- 代码参照：`app/api/v1/sms/sms.py:68`
|
||
- `admin｜GET /api/v1/user/list`（v1）
|
||
- 功能：分页查询后台用户
|
||
- 公开/认证：需认证；需权限校验
|
||
- 请求参数（Query）：分页与过滤
|
||
- 响应结构：`SuccessExtra`（`{code,msg,data,total,page,page_size}`）
|
||
- 错误码：`401/403/422/500`
|
||
- 代码参照：`app/api/v1/__init__.py:33`
|
||
|
||
## 交付内容
|
||
- 生成统一的 Markdown 文档（建议 `docs/api-v1.md`），按 `app` 与 `admin` 两章、功能模块分组列出全部接口，逐条填充统一字段。
|
||
- 附“错误码说明”与“认证/权限机制”章节，提供关键代码路径引用，便于后续维护与审计。
|
||
|
||
## 验证与维护
|
||
- 通过聚合路由与端点扫描确认无遗漏；如有新接口，按相同格式追加。
|
||
- 校验每条接口的认证与权限标注是否与代码一致；抽样比对响应结构、错误码与异常处理一致性。
|
||
|
||
请确认上述按 `admin` 与 `app` 分类的计划；确认后我将开始生成完整文档并交付。 |