邹方成
cc352d3184
refactor: 优化API路由和响应模型 feat(admin): 添加App用户管理接口 feat(sms): 实现阿里云短信服务集成 feat(email): 添加SMTP邮件发送功能 feat(upload): 支持文件上传接口 feat(rate-limiter): 实现手机号限流器 fix: 修复计算步骤入库问题 docs: 更新API文档和测试计划 chore: 更新依赖和配置
3.9 KiB
3.9 KiB
输出目标
- 以
admin（后台）与app（用户端）两大类重组全部现有v1API。 - 统一每个接口的文档格式：路径、方法、版本、功能说明、公开/认证、（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 分类的计划；确认后我将开始生成完整文档并交付。