docs: refresh frontend integration notes
This commit is contained in:
wren
+172
-23
@@ -1,6 +1,6 @@
|
||||
# 入口模块管理 API 完整技术文档
|
||||
|
||||
> **供前端对接使用** | 更新时间：2025-11-28 | 版本：v2.0
|
||||
> **供前端对接使用** | 更新时间：2025-01-29 | 版本：v2.1
|
||||
|
||||
## 📋 目录
|
||||
|
||||
@@ -390,7 +390,9 @@ LIMIT 20 OFFSET 0;
|
||||
**错误响应（500）**
|
||||
```json
|
||||
{
|
||||
"detail": "查询入口模块列表失败: connection to server failed"
|
||||
"code": 500,
|
||||
"msg": "查询入口模块列表失败: connection to server failed",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -470,7 +472,9 @@ WHERE id = 1; -- $1 参数化查询
|
||||
**错误响应（404）**
|
||||
```json
|
||||
{
|
||||
"detail": "入口模块不存在: id=999"
|
||||
"code": 404,
|
||||
"msg": "入口模块不存在: id=999",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -606,7 +610,9 @@ RETURNING id, name, description, path, areas, created_at, updated_at;
|
||||
**错误响应（400）- 名称重复**
|
||||
```json
|
||||
{
|
||||
"detail": "模块名称已存在: name=合同管理"
|
||||
"code": 400,
|
||||
"msg": "模块名称已存在: name=合同管理",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -756,21 +762,27 @@ RETURNING id, name, description, path, areas, created_at, updated_at;
|
||||
**错误响应（404）- 模块不存在**
|
||||
```json
|
||||
{
|
||||
"detail": "入口模块不存在: id=999"
|
||||
"code": 404,
|
||||
"msg": "入口模块不存在: id=999",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（400）- 名称已存在**
|
||||
```json
|
||||
{
|
||||
"detail": "模块名称已存在: name=案卷智能评查"
|
||||
"code": 400,
|
||||
"msg": "模块名称已存在: name=案卷智能评查",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（400）- 没有更新字段**
|
||||
```json
|
||||
{
|
||||
"detail": "没有要更新的字段"
|
||||
"code": 400,
|
||||
"msg": "没有要更新的字段",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -849,7 +861,9 @@ DELETE FROM entry_modules WHERE id = 1;
|
||||
**错误响应（404）**
|
||||
```json
|
||||
{
|
||||
"detail": "入口模块不存在: id=999"
|
||||
"code": 404,
|
||||
"msg": "入口模块不存在: id=999",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -862,6 +876,73 @@ DELETE FROM entry_modules WHERE id = 1;
|
||||
|
||||
### 6. 上传入口模块图标
|
||||
|
||||
> ⚠️ **重要更新 (v2.1)**：图片上传功能已修复JWT拦截问题，静态资源现在可以无需Token访问。
|
||||
|
||||
#### 🔥 前端常见问题及解决方案
|
||||
|
||||
**问题1：上传时报错 "Field required - body.file"**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 3000,
|
||||
"msg": "参数校验错误",
|
||||
"data": [
|
||||
{
|
||||
"type": "missing",
|
||||
"loc": ["body", "file"],
|
||||
"msg": "Field required"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**原因**：字段名错误或没有使用FormData上传
|
||||
|
||||
**正确做法**：
|
||||
```javascript
|
||||
// ✅ 正确
|
||||
const formData = new FormData();
|
||||
formData.append('file', imageFile); // 字段名必须是 "file"
|
||||
|
||||
await fetch(`/api/v3/entry-modules/${moduleId}/image`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
// ✅ 不要设置 Content-Type，让浏览器自动添加boundary
|
||||
},
|
||||
body: formData
|
||||
});
|
||||
|
||||
// ❌ 错误示例
|
||||
formData.append('image', imageFile); // 字段名错误
|
||||
formData.append('picture', imageFile); // 字段名错误
|
||||
body: JSON.stringify({file: base64}); // 不能用JSON
|
||||
headers: {'Content-Type': 'multipart/form-data'} // 不要手动设置
|
||||
```
|
||||
|
||||
**问题2：图片显示401 Unauthorized**
|
||||
|
||||
这是因为旧版本JWT中间件拦截了MinIO静态资源。
|
||||
|
||||
**已修复** ✅：
|
||||
- MinIO路径（`/docauditai/`）已加入JWT白名单
|
||||
- 图片现在可以**无需Token**直接访问
|
||||
- 测试：`curl http://your-server/docauditai/documents/mz/static/img/entry_module_1.png`
|
||||
|
||||
**问题3：错误的图片访问路径**
|
||||
|
||||
```javascript
|
||||
// ❌ 错误 - 硬编码路径
|
||||
const imageUrl = `/docauditai/entryModule/${module.code}`;
|
||||
|
||||
// ✅ 正确 - 使用数据库path字段
|
||||
const imageUrl = `http://172.16.0.81:9000/docauditai/${module.path}`;
|
||||
|
||||
// ✅ 或者使用上传接口返回的url字段（推荐）
|
||||
const result = await uploadImage(moduleId, file);
|
||||
const imageUrl = result.data.url;
|
||||
```
|
||||
|
||||
#### 接口定义
|
||||
|
||||
```http
|
||||
@@ -1067,28 +1148,52 @@ WHERE id = 1;
|
||||
**错误响应（400）- 不支持的格式**
|
||||
```json
|
||||
{
|
||||
"detail": "不支持的图片格式: .pdf，支持的格式: .jpg, .jpeg, .png, .gif, .webp, .svg"
|
||||
"code": 400,
|
||||
"msg": "不支持的图片格式: .pdf，支持的格式: .jpg, .jpeg, .png, .gif, .webp, .svg",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（400）- 文件为空**
|
||||
```json
|
||||
{
|
||||
"detail": "文件内容为空"
|
||||
"code": 400,
|
||||
"msg": "文件内容为空",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（404）- 模块不存在**
|
||||
```json
|
||||
{
|
||||
"detail": "入口模块不存在: id=999"
|
||||
"code": 404,
|
||||
"msg": "入口模块不存在: id=999",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（422）- 缺少file字段** ⚠️ **常见错误**
|
||||
```json
|
||||
{
|
||||
"code": 3000,
|
||||
"msg": "参数校验错误",
|
||||
"data": [
|
||||
{
|
||||
"type": "missing",
|
||||
"loc": ["body", "file"],
|
||||
"msg": "Field required",
|
||||
"input": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（500）- MinIO上传失败**
|
||||
```json
|
||||
{
|
||||
"detail": "上传入口模块图片失败: S3 error: Access Denied"
|
||||
"code": 500,
|
||||
"msg": "上传入口模块图片失败: S3 error: Access Denied",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1465,22 +1570,30 @@ api.interceptors.response.use(
|
||||
(error) => {
|
||||
if (error.response) {
|
||||
const { status, data } = error.response;
|
||||
// ⭐ v2.1更新：错误响应统一格式 {code, msg, data}
|
||||
const errorMsg = data.msg || data.detail || '请求失败';
|
||||
|
||||
switch (status) {
|
||||
case 401:
|
||||
// Token过期，跳转登录
|
||||
console.error('未授权:', errorMsg);
|
||||
window.location.href = '/login';
|
||||
break;
|
||||
case 403:
|
||||
// 无权限
|
||||
console.error('权限不足');
|
||||
console.error('权限不足:', errorMsg);
|
||||
break;
|
||||
case 404:
|
||||
// 资源不存在
|
||||
console.error(data.detail || '资源不存在');
|
||||
console.error('资源不存在:', errorMsg);
|
||||
break;
|
||||
case 422:
|
||||
// 参数校验错误
|
||||
console.error('参数错误:', errorMsg, data.data);
|
||||
break;
|
||||
case 500:
|
||||
// 服务器错误
|
||||
console.error(data.detail || '服务器错误');
|
||||
console.error('服务器错误:', errorMsg);
|
||||
break;
|
||||
}
|
||||
}
|
||||
@@ -1554,20 +1667,20 @@ export const entryModuleApi = {
|
||||
|
||||
/**
|
||||
* 上传图标
|
||||
* ⚠️ 注意：字段名必须是 "file"，不要手动设置Content-Type
|
||||
*/
|
||||
uploadImage: (id: number, file: File) => {
|
||||
const formData = new FormData();
|
||||
formData.append('file', file);
|
||||
formData.append('file', file); // ✅ 字段名必须是 "file"
|
||||
|
||||
return api.post<{
|
||||
code: number;
|
||||
msg: string;
|
||||
data: ImageUploadResponse;
|
||||
}>(`/entry-modules/${id}/image`, formData, {
|
||||
headers: {
|
||||
'Content-Type': 'multipart/form-data'
|
||||
}
|
||||
});
|
||||
}>(`/entry-modules/${id}/image`, formData
|
||||
// ✅ 不要设置Content-Type，axios会自动设置
|
||||
// 如果手动设置会缺少boundary参数导致上传失败
|
||||
);
|
||||
}
|
||||
};
|
||||
```
|
||||
@@ -1776,7 +1889,43 @@ WHERE module = 'entry_module';
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v2.0
|
||||
**最后更新**：2025-11-28
|
||||
## 📝 版本更新记录
|
||||
|
||||
### v2.1 (2025-01-29)
|
||||
|
||||
**重要更新**：
|
||||
1. ✅ 修复JWT拦截MinIO静态资源问题
|
||||
- MinIO路径（`/docauditai/`）已加入JWT白名单
|
||||
- 图片现在可以无需Token访问
|
||||
|
||||
2. ✅ 统一错误响应格式
|
||||
- 旧格式：`{"detail": "错误信息"}`
|
||||
- 新格式：`{"code": xxx, "msg": "错误信息", "data": []}`
|
||||
|
||||
3. ✅ 新增图片上传常见问题解决方案
|
||||
- 详细说明了"Field required - body.file"错误的解决方法
|
||||
- 提供了正确的FormData使用示例
|
||||
- 强调字段名必须是 "file"
|
||||
|
||||
4. ✅ 创建测试工具
|
||||
- 新增HTML测试工具：`scripts/test_entry_module_image_upload.html`
|
||||
- 可视化测试界面，帮助调试图片上传功能
|
||||
|
||||
**前端重要修改**：
|
||||
- ⚠️ 删除手动设置 `Content-Type: multipart/form-data`
|
||||
- ⚠️ 使用 `data.msg` 替代 `data.detail` 获取错误信息
|
||||
- ⚠️ 图片访问不要硬编码路径，使用数据库path字段
|
||||
|
||||
### v2.0 (2025-11-28)
|
||||
|
||||
- 完整的API文档
|
||||
- 数据库设计详解
|
||||
- 前端对接指南
|
||||
- TypeScript类型定义
|
||||
|
||||
---
|
||||
|
||||
**当前版本**：v2.1
|
||||
**最后更新**：2025-01-29
|
||||
**维护者**：Backend Team
|
||||
**反馈渠道**：[提交Issue](http://git.7bm.co:1024/leke/docauditai/-/issues)
|
||||
|
||||
Reference in New Issue
Block a user