From 2dcf81c155b3dab1efa8b4db92ad98a18814fce7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B2=88=E9=B8=BF?= Date: Wed, 2 Jul 2025 17:10:19 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A1=A5=E5=85=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../doc/API定义规范.md | 135 +++++++++ .../doc/组件文档.md | 257 ++++++++++++++++++ 2 files changed, 392 insertions(+) create mode 100644 sub-government-affairs-service/doc/API定义规范.md create mode 100644 sub-government-affairs-service/doc/组件文档.md diff --git a/sub-government-affairs-service/doc/API定义规范.md b/sub-government-affairs-service/doc/API定义规范.md new file mode 100644 index 0000000..9b29641 --- /dev/null +++ b/sub-government-affairs-service/doc/API定义规范.md @@ -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` | + +--- + diff --git a/sub-government-affairs-service/doc/组件文档.md b/sub-government-affairs-service/doc/组件文档.md new file mode 100644 index 0000000..4056bbf --- /dev/null +++ b/sub-government-affairs-service/doc/组件文档.md @@ -0,0 +1,257 @@ +# 文件上传组件 (FileUploader) + +## 组件说明 + +文件上传组件用于实现文件的上传、预览和管理功能。支持图片上传、多文件上传、文件预览等功能。 + +## 基本用法 + +```vue + + + +``` + +## 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 + +``` + +## 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 + +``` + +### 2. 配置示例 + +```vue + +``` + +------ + +## 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` \ No newline at end of file