文档补充
This commit is contained in:
parent
e386994f04
commit
2dcf81c155
135
sub-government-affairs-service/doc/API定义规范.md
Normal file
135
sub-government-affairs-service/doc/API定义规范.md
Normal file
@ -0,0 +1,135 @@
|
|||||||
|
|
||||||
|
# 前端 API 定义规范（REST 风格）
|
||||||
|
|
||||||
|
> 版本：v1.0
|
||||||
|
> 日期：2025-07-01
|
||||||
|
> 风格：**RESTful**
|
||||||
|
> 适用范围：Vue3 / React / 模块化 JS 项目
|
||||||
|
> 目标：提升接口命名一致性，增强可维护性与可读性
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌐 RESTful 命名规范
|
||||||
|
|
||||||
|
REST（Representational State Transfer）强调以资源为中心的接口设计，以下为规范核心：
|
||||||
|
|
||||||
|
### ✅ 基本动词与 HTTP 方法对应
|
||||||
|
|
||||||
|
| 动作 | HTTP 方法 | 路径示例 | 命名示例（函数） |
|
||||||
|
|--------------|------------|-------------------------------|---------------------------|
|
||||||
|
| 获取列表 | GET | `/users` | `fetchUserList` |
|
||||||
|
| 获取详情 | GET | `/users/:id` | `getUserById` |
|
||||||
|
| 创建 | POST | `/users` | `createUser` |
|
||||||
|
| 修改 | PUT/PATCH | `/users/:id` | `updateUser` |
|
||||||
|
| 删除 | DELETE | `/users/:id` | `deleteUserById` |
|
||||||
|
| 导出 | GET | `/users/export` | `exportUserExcel` |
|
||||||
|
| 上传 | POST | `/files/upload` | `uploadFile` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 文件组织结构
|
||||||
|
|
||||||
|
```bash
|
||||||
|
src/
|
||||||
|
├── apis/
|
||||||
|
│ ├── landResourceManagement/ # 土地资源管理
|
||||||
|
│ │ ├── plantingPlan/ # 种植规划
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── operationRecord/ # 作业记录
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── landIllegal/ # 土地违法处理
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── landManagement/ # 土地管理
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── landInspection/ # 土地巡查
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── gridManagement/ # 网格管理
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── gridMemberManagement/ # 网格员管理
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── basicInfoMaintenance/ # 基础信息维护
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── cropsManagement/ # 种植作物
|
||||||
|
│ │ │ ├── index.js
|
||||||
|
│ │ ├── index.js # 土地资源管理模块统一入口
|
||||||
|
│ ├── productionEntityManagement/ # 生产经营主体管理
|
||||||
|
│ │ ├── index.js
|
||||||
|
│ ├── inputManagement/ # 投入品管理
|
||||||
|
│ │ ├── index.js
|
||||||
|
│ ├── productTraceability/ # 农产品溯源
|
||||||
|
│ │ ├── index.js
|
||||||
|
│ ├── index.js # 项目统一入口文件
|
||||||
|
├── utils/
|
||||||
|
│ ├── axios.js # 封装的请求工具
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧱 函数命名规范
|
||||||
|
|
||||||
|
接口定义应以 **动词+资源名** 格式命名函数（驼峰式 camelCase）：
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 用户模块 API 示例
|
||||||
|
import request from '@/utils/request';
|
||||||
|
|
||||||
|
export function fetchUserList(params) {
|
||||||
|
return request('/api/users', { method: 'GET', params });
|
||||||
|
}
|
||||||
|
|
||||||
|
export function getUserById(id) {
|
||||||
|
return request(`/api/users/${id}`, { method: 'GET' });
|
||||||
|
}
|
||||||
|
|
||||||
|
export function createUser(data) {
|
||||||
|
return request('/api/users', { method: 'POST', data });
|
||||||
|
}
|
||||||
|
|
||||||
|
export function updateUser(id, data) {
|
||||||
|
return request(`/api/users/${id}`, { method: 'PUT', data });
|
||||||
|
}
|
||||||
|
|
||||||
|
export function deleteUserById(id) {
|
||||||
|
return request(`/api/users/${id}`, { method: 'DELETE' });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧠 组件方法命名建议
|
||||||
|
|
||||||
|
组件内部方法（UI逻辑处理）请统一以 `handle` 前缀区分，避免与 API 冲突：
|
||||||
|
|
||||||
|
```js
|
||||||
|
const handleAddUser = () => { ... };
|
||||||
|
const handleEditUser = (row) => { ... };
|
||||||
|
const handleDeleteUser = (id) => { ... };
|
||||||
|
const handleExportExcel = () => { ... };
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚫 命名反例
|
||||||
|
|
||||||
|
| 错误命名 | 问题说明 | 推荐命名 |
|
||||||
|
|------------------|----------------------------------------|--------------------------|
|
||||||
|
| `listUser` | 动词语义模糊 | `fetchUserList` |
|
||||||
|
| `editUserById` | 与 REST 风格不符 | `updateUser` |
|
||||||
|
| `addOrEditUser` | 接口职责不清晰 | `createUser` 或 `updateUser` |
|
||||||
|
| `removeUser` | 与 HTTP 方法不一致 | `deleteUserById` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧾 附录：接口语义对照表
|
||||||
|
|
||||||
|
| 类型 | HTTP 方法 | REST URI 示例 | 函数命名示例 |
|
||||||
|
|-------------|------------|---------------------------|--------------------------|
|
||||||
|
| 查询列表 | GET | `/entities` | `fetchEntityList` |
|
||||||
|
| 查询详情 | GET | `/entities/:id` | `getEntityById` |
|
||||||
|
| 新增 | POST | `/entities` | `createEntity` |
|
||||||
|
| 修改 | PUT | `/entities/:id` | `updateEntity` |
|
||||||
|
| 删除 | DELETE | `/entities/:id` | `deleteEntityById` |
|
||||||
|
| 导出 | GET | `/entities/export` | `exportEntityExcel` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
257
sub-government-affairs-service/doc/组件文档.md
Normal file
257
sub-government-affairs-service/doc/组件文档.md
Normal file
@ -0,0 +1,257 @@
|
|||||||
|
# 文件上传组件 (FileUploader)
|
||||||
|
|
||||||
|
## 组件说明
|
||||||
|
|
||||||
|
文件上传组件用于实现文件的上传、预览和管理功能。支持图片上传、多文件上传、文件预览等功能。
|
||||||
|
|
||||||
|
## 基本用法
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<template>
|
||||||
|
<file-uploader
|
||||||
|
v-model="fileList"
|
||||||
|
:limit="5"
|
||||||
|
accept="image/*"
|
||||||
|
/>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<script setup>
|
||||||
|
import { ref } from 'vue';
|
||||||
|
const fileList = ref([]);
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Props
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 默认值 | 说明 |
|
||||||
|
| ---------- | ----------------- | ------------------------------------------------- | --------------- |
|
||||||
|
| modelValue | `Array \| String` | `[]` | 绑定值，图片路径数组或单个路径 |
|
||||||
|
| ossUrl | `String` | `'http://gov-cloud.oss-cn-chengdu.aliyuncs.com/'` | 回显时拼接图片完整路径使用 |
|
||||||
|
| limit | `Number` | `5` | 最多上传几张图片 |
|
||||||
|
| accept | `String` | `'image/*'` | 允许上传的文件类型 |
|
||||||
|
| readonly | `Boolean` | `false` | 是否只读模式，不可上传删除 |
|
||||||
|
|
||||||
|
|
||||||
|
## 事件
|
||||||
|
| 事件名 | 参数 | 说明 |
|
||||||
|
|-------|------|------|
|
||||||
|
| update:modelValue | 新的文件列表值（数组或字符串） | 当文件列表发生变化时触发 |
|
||||||
|
|
||||||
|
## 插槽
|
||||||
|
该组件没有提供插槽。
|
||||||
|
|
||||||
|
### 数据适配处理
|
||||||
|
|
||||||
|
- `selectedFiles`：用于统一处理单文件和多文件场景，读时返回数组，写时根据 `limit` 决定是否回传为字符串或数组。
|
||||||
|
- `fileList`：用于 `el-upload` 的回显列表，拼接完整 URL。
|
||||||
|
- `previewList`：用于图片预览的 URL 列表。
|
||||||
|
|
||||||
|
## 样式
|
||||||
|
|
||||||
|
组件使用了Element Plus的el-upload和el-image-viewer组件，并添加了自定义样式以适应不同的布局需求。
|
||||||
|
|
||||||
|
## 依赖项
|
||||||
|
|
||||||
|
- `element-plus`
|
||||||
|
- `@element-plus/icons-vue` 中的 `Plus`
|
||||||
|
- 自定义 API：`CommonUpload`
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# UrlSelect 远程下拉选择组件
|
||||||
|
|
||||||
|
该组件基于 `el-select` 和自定义 axios 请求封装，支持从指定接口拉取选项列表，并支持 label/value 字段自定义。
|
||||||
|
|
||||||
|
## 功能特性
|
||||||
|
|
||||||
|
- 下拉选项从远程接口加载（通过 `url` 和 `params` 指定）
|
||||||
|
- 支持自定义 label/value 字段名（`labelKey` / `valueKey`）
|
||||||
|
- 支持插槽透传（可扩展 options 或添加分组）
|
||||||
|
- 内部使用双向绑定模型 `internalValue` 实现响应式
|
||||||
|
- 默认使用 `res.data.records` 作为解析逻辑，可自定义 `responseParser`
|
||||||
|
|
||||||
|
## 使用示例
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<UrlSelect
|
||||||
|
v-model="form.industry"
|
||||||
|
url="/api/base/industries"
|
||||||
|
:params="{ enabled: true }"
|
||||||
|
label-key="name"
|
||||||
|
value-key="id"
|
||||||
|
placeholder="请选择行业"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Props 参数
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 默认值 | 说明 |
|
||||||
|
| -------------- | --------------------------- | --------------------------- | ------------------------------ |
|
||||||
|
| modelValue | `String \| Number \| Array` | `null` | 绑定的值 |
|
||||||
|
| url | `String` | `null` | 请求数据的接口地址 |
|
||||||
|
| params | `Object` | `{}` | 请求时的参数 |
|
||||||
|
| labelKey | `String` | `'label'` | 数据项中作为 label 显示的字段 |
|
||||||
|
| valueKey | `String` | `'value'` | 数据项中作为 value 的字段 |
|
||||||
|
| responseParser | `Function` | `(res) => res.data.records` | 处理响应数据的函数，需返回数组 |
|
||||||
|
|
||||||
|
## 事件说明
|
||||||
|
|
||||||
|
组件继承并透传了 `el-select` 的常用事件：
|
||||||
|
|
||||||
|
| 事件名 | 说明 |
|
||||||
|
| ------------------- | ---------------------------- |
|
||||||
|
| `update:modelValue` | v-model 绑定更新 |
|
||||||
|
| `change` | 选项变化时触发 |
|
||||||
|
| `blur` | 失焦时触发 |
|
||||||
|
| `focus` | 聚焦时触发 |
|
||||||
|
| `clear` | 点击清空按钮时触发 |
|
||||||
|
| `visible-change` | 下拉框显示/隐藏变化时触发 |
|
||||||
|
| `remove-tag` | 多选时移除 tag 触发 |
|
||||||
|
| `scroll` | 滚动触发（需设置高度才有效） |
|
||||||
|
|
||||||
|
## 核心逻辑说明
|
||||||
|
|
||||||
|
### 1. 内部绑定值
|
||||||
|
|
||||||
|
```JavaScript
|
||||||
|
const internalValue = ref(props.modelValue);
|
||||||
|
watch(() => props.modelValue, (newVal) => internalValue.value = newVal);
|
||||||
|
watch(internalValue, (newVal) => emit('update:modelValue', newVal));
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 拉取远程选项
|
||||||
|
|
||||||
|
```JavaScript
|
||||||
|
async function fetchOptions() {
|
||||||
|
if (!props.url) return;
|
||||||
|
const res = await request.get(props.url, { params: props.params });
|
||||||
|
const records = props.responseParser(res);
|
||||||
|
options.value = Array.isArray(records) ? records : [];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
组件挂载时会立即请求一次远程数据。
|
||||||
|
|
||||||
|
### 3. 插槽支持
|
||||||
|
|
||||||
|
支持透传所有 `$slots`，并提供默认的 `option` 渲染逻辑。也可通过 `option-group` 插槽实现复杂渲染。
|
||||||
|
|
||||||
|
## 依赖项
|
||||||
|
|
||||||
|
- `element-plus` 的 `el-select`、`el-option`
|
||||||
|
- 项目中的 `request` 请求封装（例如基于 axios）
|
||||||
|
|
||||||
|
## 可拓展点
|
||||||
|
|
||||||
|
- 支持分页加载远程选项（下拉滚动触发）
|
||||||
|
- 支持懒加载（点击展开时再加载）
|
||||||
|
- 支持 loading/loading-text 状态
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# AreaSelect.vue 组件文档
|
||||||
|
|
||||||
|
## 组件简介
|
||||||
|
|
||||||
|
`AreaSelect` 是一个基于 Element Plus 的级联选择组件，封装了行政区域选择功能。支持省/市/县三级联动，数据源通过接口自动获取。
|
||||||
|
|
||||||
|
## 使用方式
|
||||||
|
|
||||||
|
### 1. 引入组件
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<AreaSelect v-model="areaCodeList" />
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 配置示例
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<AreaSelect
|
||||||
|
v-model="selectedArea"
|
||||||
|
:label="'所属区域：'"
|
||||||
|
:placeholder="'请选择区域'"
|
||||||
|
:emit-path="true"
|
||||||
|
:width="600"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## Props 参数说明
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 默认值 | 说明 |
|
||||||
|
| ------------- | ----------------- | ---------------- | ------------------------------------------------------------ |
|
||||||
|
| `modelValue` | `Array | String` | `[]` | 双向绑定的值。如果 `emitPath` 为 `true`，则为数组，否则为字符串。 |
|
||||||
|
| `label` | `String` | `所属行政区域：` | 左侧 label 标签内容。 |
|
||||||
|
| `placeholder` | `String` | `请选择行政区域` | 选择框中的占位符提示文字。 |
|
||||||
|
| `width` | `Number | String` | `500` | 整体组件宽度（单位：px）。 |
|
||||||
|
| `emitPath` | `Boolean` | `true` | 是否返回完整路径的值数组。为 `false` 时只返回最后一级节点的值。 |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## Events 说明
|
||||||
|
|
||||||
|
| 事件名 | 说明 |
|
||||||
|
| ------------------- | ------------------------- |
|
||||||
|
| `update:modelValue` | 用于 `v-model` 双向绑定。 |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## 返回值说明
|
||||||
|
|
||||||
|
- 当 `emitPath = true` 时，返回一个数组，例如：
|
||||||
|
|
||||||
|
```json
|
||||||
|
['530000', '530100', '530102']
|
||||||
|
```
|
||||||
|
|
||||||
|
- 当 `emitPath = false` 时，只返回最后一级，例如：
|
||||||
|
|
||||||
|
```json
|
||||||
|
'530102'
|
||||||
|
```
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## 接口说明
|
||||||
|
|
||||||
|
该组件内部自动发起请求：
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /system/area/region?areaCode=530000
|
||||||
|
```
|
||||||
|
|
||||||
|
接口返回行政区域数据，格式如下：
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"areaName": "云南省",
|
||||||
|
"areaCode": "530000",
|
||||||
|
"areaChildVOS": [
|
||||||
|
{
|
||||||
|
"areaName": "昆明市",
|
||||||
|
"areaCode": "530100",
|
||||||
|
"areaChildVOS": [...]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
------
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
- 外部不应主动更新 `modelValue`，避免造成循环依赖。
|
||||||
|
- 默认展示为“云南省”下的行政区域。
|
||||||
|
- 默认字段映射为：
|
||||||
|
- `label`: `areaName`
|
||||||
|
- `value`: `areaCode`
|
||||||
|
- `children`: `areaChildVOS`
|
||||||
Loading…
x
Reference in New Issue
Block a user