签入版本

2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -23,7 +23,12 @@
 | 查询 | GET | `params`（URL 参数） | 分页/列表/详情 |
 | 新增 | POST | `data`（请求体） | JSON 格式 |
 | 修改 | PUT | `data`（请求体） | JSON 格式，含 id |
-| 删除 | DELETE | URL 参数或 `data` | 单条用 URL，批量用 data |
+| 删除 | DELETE | URL 参数 | 单条（id 在路径中） |
+| 批量删除 | **DELETE** | `data`（请求体 `{ids:[]}`） | 本项目统一 DELETE + body |
+
+:::warning 与常见 REST 风格的差异
+本项目 `batchDelete` 为 **DELETE**（请求体仍传 `ids` 数组——DELETE 方法携带 body）；`resetPwd` 为 **PUT**，`account` 等扩展操作为 POST——以后端 `routes/api.php` 实际路由为准（见 [8.7 API 接口总览](/zh/api-spec/overview.html)）。
+:::

 ## 文件组织

@@ -42,6 +47,9 @@ ui/src/api/
 │   ├── article.ts
 │   ├── category.ts
 │   └── link.ts
+├── data/                   # 数据管理模块（字典/配置/参数/公告/城市）
+├── monitor/                # 监控模块（定时任务）
+├── file/                   # 文件模板
 └── tool/                   # 工具模块
    └── example.ts
 ```
@@ -82,33 +90,40 @@ export function exampleDelete(id) {
  return http.request({ url: '/example/delete/' + id, method: 'DELETE' });
 }

-// 批量删除
+// 批量删除（DELETE + 请求体 { ids: [...] }）
 export function exampleBatchDelete(data: any) {
  return http.request({ url: '/example/batchDelete', method: 'DELETE', data });
 }
 ```

+:::tip 拦截器已解包
+`http.request` 的响应拦截器在 `code === 0` 时直接返回 `data`——函数返回值即业务数据（如分页返回 `{records,total,current,size,pages}`），无需再取 `response.data.data`。
+:::
+
 ## 常见扩展操作

 | 操作 | 函数名示例 | HTTP 方法 |
 |------|-----------|----------|
 | 重置密码 | `userResetPwd(data)` | POST |
-| 导入 | `{module}Import(data: FormData)` | POST（multipart/form-data） |
+| 导入 | `{module}Import(data: FormData)` | POST（multipart/form-data，带 Bearer 头） |
 | 导出 | `{module}Export(params)` | GET |
-| 刷新缓存 | `dictRefreshCache()` | GET |
+| 刷新字典缓存 | `dictRefreshCache()` | GET |
+| 获取用户信息 | `getUser()` | GET |
 | 获取菜单 | `getMenus()` | GET |
-| 获取字典项 | `getDictItemList(code)` | GET |
+| 修改密码 | `updatePassword(data)` | PUT |
+| 获取字典项 | `getDictItemByCode(code)` | GET |
+| 刷新 Token | `postRefresh({ refresh_token })` | POST（公开接口） |

 ## 组件中使用

 ```vue
 <script setup lang="ts">
-import { getExamplePage, exampleDelete } from '@/api/tool/example';
+import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
 import { ElMessage, ElMessageBox } from 'element-plus';

 const tableData = ref([]);

-// 查询
+// 查询（res 即 data：{records, total, current, size, pages}）
 const fetchData = async () => {
  const res = await getExamplePage({ pageNo: 1, pageSize: 20 });
  tableData.value = res.records;
@@ -121,5 +136,22 @@ const handleDelete = async (id) => {
  ElMessage.success('删除成功');
  fetchData();
 };
+
+// 批量删除
+const handleBatchDelete = async (ids) => {
+  await exampleBatchDelete({ ids });
+  ElMessage.success('删除成功');
+  fetchData();
+};
 </script>
 ```
+
+## 编写检查清单
+
+| 检查项 | 说明 |
+|------|------|
+| URL 与后端路由一致 | 逐字符核对 `routes/api.php`（二级路径模块名如 `file/template`） |
+| HTTP 方法正确 | 特别注意 `batchDelete`=DELETE（带 body）、`runOnce/pause/resume`=GET |
+| 认证接口不需要带公开标记 | 拦截器自动加 Bearer 头，公开接口同样可用 |
+| 导入用 FormData | `Content-Type` 交给浏览器自动带 boundary，勿手写 |
+| 导出处理返回值 | 后端返回文件地址（字符串），直接打开下载 |