From b69da0d7965a3fe6b532addbeffe0329a2711823 Mon Sep 17 00:00:00 2001
From: chenhj <1263187585@qq.com>
Date: 星期四, 30 四月 2026 13:36:12 +0800
Subject: [PATCH] 文件系统说明

---
 FILE_UPLOAD_README.md |  480 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 480 insertions(+), 0 deletions(-)

diff --git a/FILE_UPLOAD_README.md b/FILE_UPLOAD_README.md
new file mode 100644
index 0000000..ad5b42a
--- /dev/null
+++ b/FILE_UPLOAD_README.md
@@ -0,0 +1,480 @@
+# 鏈湴鏂囦欢涓婁紶 README
+
+鏈枃妗ｅ熀浜庝互涓嬪疄鐜版暣鐞嗭細
+
+- `src/components/AttachmentUpload/file/index.vue`
+- `src/components/AttachmentUpload/image/index.vue`
+- `src/components/AttachmentPreview/image/index.vue`
+- `src/components/Dialog/FileList.vue`
+- `src/api/basicData/common.js`
+- `src/api/publicApi/commonFile.js`
+
+鐩稿叧缁勪欢宸插湪 `src/main.js` 涓敞鍐屼负鍏ㄥ眬缁勪欢锛屽彲鐩存帴鍦ㄩ〉闈腑浣跨敤锛�
+
+- `FileUpload`
+- `ImageUpload`
+- `ImagePreview`
+- `FileListDialog`
+
+## 1. 鍔熻兘姒傝
+
+褰撳墠杩欏涓婁紶鑳藉姏涓昏鍒嗕负 4 閮ㄥ垎锛�
+
+1. `FileUpload`锛氭櫘閫氭枃浠朵笂浼狅紝鏀寔鎷栨嫿銆佹壒閲忎笂浼犮�侀瑙堛�佸垹闄�
+2. `ImageUpload`锛氬浘鐗囦笂浼狅紝鏀寔鍥剧墖澧欏睍绀恒�侀瑙堛�佸垹闄�
+3. `ImagePreview`锛氬浘鐗囧垪琛ㄩ瑙堝睍绀�
+4. `FileListDialog`锛氫笟鍔￠檮浠跺脊绐楋紝鏀寔鏌ヨ銆佷笂浼犮�佸垹闄ゃ�佷笅杞�
+
+涓婁紶搴曞眰缁熶竴璧版帴鍙ｏ細
+
+- `POST /common/upload`
+
+瀵瑰簲鏂规硶鍦� `src/api/basicData/common.js`锛�
+
+```js
+uploadFile(data)
+```
+
+## 2. 涓婁紶鎺ュ彛璇存槑
+
+### 2.1 閫氱敤涓婁紶鎺ュ彛
+
+鏂囦欢涓婁紶缁勪欢鍜屽浘鐗囦笂浼犵粍浠堕兘璋冪敤浜嗭細
+
+```js
+import { uploadFile } from '@/api/basicData/common'
+```
+
+鎺ュ彛鐗瑰緛锛�
+
+- 璇锋眰鏂瑰紡锛歚POST`
+- 鍦板潃锛歚/common/upload`
+- 璇锋眰绫诲瀷锛歚multipart/form-data`
+- 鏀寔 `FormData` 鎵归噺涓婁紶
+- 榛樿瀛楁鍚嶏細`files`
+
+缁勪欢鍐呴儴浼氳繖鏍风粍瑁呭弬鏁帮細
+
+```js
+const formData = new FormData()
+validFiles.forEach((file) => {
+  formData.append(props.uploadFieldName, file.raw)
+})
+```
+
+### 2.2 涓婁紶杩斿洖鍊艰姹�
+
+涓婁紶鎴愬姛鍚庯紝缁勪欢浼氬皾璇曚粠浠ヤ笅缁撴瀯涓彁鍙栨暟缁勶細
+
+- `response`
+- `response.data`
+- `response.data.data`
+- `response.payload`
+- `response.payload.data`
+- `response.rows`
+- `response.result`
+
+鍥犳鍚庣杩斿洖鏁扮粍鏃讹紝涓婇潰浠绘剰涓�绉嶇粨鏋勯兘鍙互琚瘑鍒��
+
+缁勪欢灞曠ず鏃跺父鐢ㄥ埌鐨勫瓧娈垫湁锛�
+
+- 鏂囦欢鍚嶏細`name` / `originalFilename` / `fileName` / `uidFilename`
+- 鏂囦欢鍦板潃锛歚url` / `downloadURL`
+- 鍥剧墖鍦板潃锛歚url` / `previewURL` / `previewUrl`
+- 涓婚敭锛歚id`
+
+寤鸿涓婁紶鎺ュ彛杩斿洖鐨勫崟椤瑰璞″敖閲忓寘鍚細
+
+```js
+{
+  id: 1,
+  originalFilename: 'demo.pdf',
+  downloadURL: 'https://xxx/demo.pdf',
+  previewURL: 'https://xxx/demo.png'
+}
+```
+
+## 3. FileUpload 鏂囦欢涓婁紶缁勪欢
+
+缁勪欢璺緞锛�
+
+`src/components/AttachmentUpload/file/index.vue`
+
+### 3.1 鍩虹鐢ㄦ硶
+
+```vue
+<template>
+  <FileUpload v-model:file-list="fileList" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const fileList = ref([])
+</script>
+```
+
+### 3.2 甯哥敤灞炴��
+
+| 灞炴�� | 璇存槑 | 绫诲瀷 | 榛樿鍊� |
+| --- | --- | --- | --- |
+| `fileList` | 缁戝畾鏂囦欢鍒楄〃 | `Array` | `[]` |
+| `limit` | 鏈�澶т笂浼犳暟閲� | `Number` | `10` |
+| `fileSize` | 鍗曚釜鏂囦欢澶у皬闄愬埗锛屽崟浣� MB | `Number` | `50` |
+| `fileType` | 鍏佽涓婁紶鐨勬枃浠剁被鍨嬶紝濡� `['pdf', 'docx']` | `Array` | `[]` |
+| `buttonText` | 涓婁紶鎻愮ず鏂囨 | `String` | `鍗曞嚮閫夋嫨鏂囦欢` |
+| `disabled` | 鏄惁绂佺敤 | `Boolean` | `false` |
+| `uploadFieldName` | `FormData` 瀛楁鍚� | `String` | `files` |
+| `index` | 琛ㄦ牸/鍒楄〃琛屾ā寮忎笅鐨勫綋鍓嶈绱㈠紩 | `Number` | `-1` |
+| `childrenKey` | 琛屽唴鎸傝浇瀛楁鍚� | `String` | `files` |
+
+### 3.3 浜嬩欢
+
+| 浜嬩欢 | 璇存槑 |
+| --- | --- |
+| `update:fileList` | 鏂囦欢鍒楄〃鍙樺寲鏃惰Е鍙� |
+| `change` | 鏂囦欢鍒楄〃鍙樺寲鏃惰Е鍙戯紝杩斿洖鏈�鏂板垪琛� |
+
+### 3.4 闄愬埗瑙勫垯
+
+缁勪欢鍐呭凡瀹炵幇锛�
+
+- 鏂囦欢鏁伴噺闄愬埗
+- 鏂囦欢澶у皬闄愬埗
+- 鏂囦欢绫诲瀷鏍￠獙
+- 涓婁紶涓姸鎬侀攣瀹�
+- 澶辫触鍚庤嚜鍔ㄦ竻绌哄綋鍓嶉�夋嫨闃熷垪
+
+渚嬪闄愬埗 PDF/Word锛�
+
+```vue
+<FileUpload
+  v-model:file-list="fileList"
+  :limit="5"
+  :file-size="20"
+  :file-type="['pdf', 'doc', 'docx']"
+/>
+```
+
+### 3.5 杩斿洖鏁版嵁鏍煎紡寤鸿
+
+`FileUpload` 鏇撮�傚悎鎺ユ敹杩欐牱鐨勫垪琛細
+
+```js
+[
+  {
+    id: 1,
+    originalFilename: '鍚堝悓.pdf',
+    downloadURL: 'https://xxx/contract.pdf'
+  }
+]
+```
+
+鍥犱负缁勪欢鎵撳紑鏂囦欢鏃朵細浼樺厛璇诲彇锛�
+
+```js
+url || downloadURL || previewURL || previewUrl
+```
+
+### 3.6 琛屽唴宓屽妯″紡
+
+濡傛灉涓婁紶缁勪欢鏀惧湪琛ㄦ牸鏌愪竴琛屼腑锛屽彲閰嶅悎 `index` 鍜� `childrenKey` 浣跨敤锛�
+
+```vue
+<FileUpload
+  v-model:file-list="tableData"
+  :index="scope.$index"
+  children-key="files"
+/>
+```
+
+姝ゆ椂缁勪欢浼氳嚜鍔ㄨ鍐欙細
+
+```js
+tableData[scope.$index].files
+```
+
+## 4. ImageUpload 鍥剧墖涓婁紶缁勪欢
+
+缁勪欢璺緞锛�
+
+`src/components/AttachmentUpload/image/index.vue`
+
+### 4.1 鍩虹鐢ㄦ硶
+
+```vue
+<template>
+  <ImageUpload v-model:file-list="imageList" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const imageList = ref([])
+</script>
+```
+
+### 4.2 榛樿琛屼负
+
+鍥剧墖涓婁紶缁勪欢榛樿锛�
+
+- 鏈�澶氫笂浼� `10` 寮�
+- 鍗曞紶涓嶈秴杩� `10MB`
+- 榛樿鏀寔鏍煎紡锛歚png / jpg / jpeg / webp`
+- 浣跨敤 `picture-card` 椋庢牸灞曠ず
+- 鐐瑰嚮缂╃暐鍥惧彲棰勮澶у浘
+
+### 4.3 甯哥敤绀轰緥
+
+```vue
+<ImageUpload
+  v-model:file-list="imageList"
+  :limit="9"
+  :file-size="5"
+  :file-type="['png', 'jpg', 'jpeg']"
+  button-text="涓婁紶鍥剧墖"
+/>
+```
+
+### 4.4 杩斿洖鏁版嵁鏍煎紡寤鸿
+
+`ImageUpload` 灞曠ず鍥剧墖鏃朵紭鍏堣鍙栵細
+
+```js
+url || previewURL || previewUrl
+```
+
+寤鸿鍚庣杩斿洖锛�
+
+```js
+[
+  {
+    id: 1,
+    originalFilename: '鐜板満鍥剧墖.jpg',
+    previewURL: 'https://xxx/image.jpg'
+  }
+]
+```
+
+### 4.5 琛屽唴宓屽妯″紡
+
+鍥剧墖缁勪欢鍚屾牱鏀寔琛屽唴瀛楁鍐欏洖锛�
+
+```vue
+<ImageUpload
+  v-model:file-list="tableData"
+  :index="scope.$index"
+  children-key="images"
+/>
+```
+
+榛樿鍐欏洖瀛楁涓� `images`銆�
+
+## 5. ImagePreview 鍥剧墖棰勮缁勪欢
+
+缁勪欢璺緞锛�
+
+`src/components/AttachmentPreview/image/index.vue`
+
+### 5.1 鍩虹鐢ㄦ硶
+
+```vue
+<ImagePreview :file-list="imageList" />
+```
+
+### 5.2 鍙厤缃」
+
+| 灞炴�� | 璇存槑 | 绫诲瀷 | 榛樿鍊� |
+| --- | --- | --- | --- |
+| `fileList` | 鍥剧墖鍒楄〃 | `Array` | `[]` |
+| `thumbSize` | 缂╃暐鍥惧ぇ灏� | `Number` | `72` |
+| `gap` | 缂╃暐鍥鹃棿璺� | `Number` | `10` |
+
+### 5.3 鏁版嵁瑕佹眰
+
+缁勪欢浼氳繃婊ゆ病鏈� `previewURL` 鐨勯」锛屽洜姝ゅ鏋滆姝ｅ父鏄剧ず锛屽缓璁嚦灏戝寘鍚細
+
+```js
+[
+  {
+    previewURL: 'https://xxx/image.jpg',
+    originalFilename: '鍥剧墖1.jpg'
+  }
+]
+```
+
+濡傛灉鍒楄〃涓虹┖锛岀粍浠舵樉绀衡�滄殏鏃犲浘鐗団�濄��
+
+## 6. FileListDialog 闄勪欢寮圭獥缁勪欢
+
+缁勪欢璺緞锛�
+
+`src/components/Dialog/FileList.vue`
+
+杩欎釜缁勪欢閫傚悎涓氬姟琛ㄥ崟鎴栬鎯呴〉閲岀殑鈥滈檮浠剁鐞嗏�濆満鏅紝鑳藉姏鍖呮嫭锛�
+
+- 鏍规嵁涓氬姟涓婚敭鏌ヨ闄勪欢鍒楄〃
+- 鎵撳紑寮圭獥鏌ョ湅闄勪欢
+- 鍦ㄥ脊绐椾腑缁х画涓婁紶闄勪欢
+- 鍒犻櫎闄勪欢
+- 涓嬭浇闄勪欢
+
+### 6.1 缁勪欢灞炴��
+
+| 灞炴�� | 璇存槑 | 绫诲瀷 | 榛樿鍊� |
+| --- | --- | --- | --- |
+| `visible` | 鏄惁鏄剧ず寮圭獥 | `Boolean` | 蹇呬紶 |
+| `recordType` | 涓氬姟绫诲瀷 | `String` | `''` |
+| `recordId` | 涓氬姟涓婚敭 | `Number` | `0` |
+| `title` | 寮圭獥鏍囬 | `String` | `闄勪欢` |
+| `width` | 寮圭獥瀹藉害 | `String` | `50%` |
+| `showActions` | 鏄惁鏄剧ず涓嬭浇/鍒犻櫎鎿嶄綔鍒� | `Boolean` | `true` |
+
+### 6.2 鍩虹鐢ㄦ硶
+
+```vue
+<template>
+  <el-button @click="visible = true">鏌ョ湅闄勪欢</el-button>
+
+  <FileListDialog
+    v-model:visible="visible"
+    record-type="salesLedger"
+    :record-id="rowId"
+    title="闄勪欢鍒楄〃"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const visible = ref(false)
+const rowId = ref(1001)
+</script>
+```
+
+### 6.3 缁勪欢鍐呴儴渚濊禆鐨勬帴鍙�
+
+`FileListDialog` 鏈韩涓嶇洿鎺ヨ皟鐢� `commonFile.js`锛岃�屾槸渚濊禆锛�
+
+- `attachmentList`
+- `createAttachment`
+- `deleteAttachment`
+
+澶勭悊閫昏緫涓猴細
+
+1. 鎵撳紑寮圭獥鍚庢牴鎹� `recordType + recordId` 鏌ヨ闄勪欢
+2. 鐐瑰嚮鈥滀笂浼犻檮浠垛�濆悗锛屽唴閮ㄤ娇鐢� `AttachmentUpload/file` 鍏堜笂浼犲埌 `/common/upload`
+3. 涓婁紶鎴愬姛鍚庯紝灏嗚繑鍥炵殑鏂囦欢瀵硅薄鍜屽凡鏈夊垪琛ㄤ竴璧锋彁浜ょ粰 `createAttachment`
+4. 鍒犻櫎鏃惰皟鐢� `deleteAttachment`
+5. 涓嬭浇鏃剁洿鎺� `window.open(downloadURL, '_blank')`
+
+鍥犳杩欓噷瑕佺壒鍒敞鎰忥細
+
+- `recordType` 鍜� `recordId` 蹇呴』鏄湁鏁堜笟鍔℃爣璇�
+- 涓婁紶鎴愬姛杩斿洖鐨勬暟鎹紝闇�瑕佽兘琚� `createAttachment` 鐩存帴鎺ユ敹
+- 鍒楄〃涓殑涓嬭浇鍦板潃瀛楁搴斾负 `downloadURL`
+
+## 7. commonFile.js 璇存槑
+
+鏂囦欢璺緞锛�
+
+`src/api/publicApi/commonFile.js`
+
+褰撳墠鏂囦欢鎻愪緵鐨勬槸鍏叡鏂囦欢鍒犻櫎鎺ュ彛锛�
+
+```js
+delCommonFile(ids)
+delCommonFileInvoiceLedger(ids)
+```
+
+瀵瑰簲鎺ュ彛锛�
+
+- `/commonFile/delCommonFile`
+- `/invoiceLedger/delFile`
+
+杩欎袱涓柟娉曟洿閫傚悎宸茬粡鍜屽叿浣撲笟鍔＄粦瀹氬悗鐨勨�滃垹闄ゅ凡淇濆瓨闄勪欢鈥濆満鏅紝涓嶈礋璐ｄ笂浼犳枃浠舵湰韬��
+
+绀轰緥锛�
+
+```js
+import { delCommonFile } from '@/api/publicApi/commonFile'
+
+await delCommonFile([1, 2, 3])
+```
+
+## 8. 鎺ㄨ崘浣跨敤鏂瑰紡
+
+### 8.1 鏅�氫笟鍔¤〃鍗曚笂浼犻檮浠�
+
+```vue
+<FileUpload v-model:file-list="form.storageBlobDTOs" />
+```
+
+鎻愪氦琛ㄥ崟鏃剁洿鎺ュ甫涓婏細
+
+```js
+{
+  ...form,
+  storageBlobDTOs: form.storageBlobDTOs
+}
+```
+
+### 8.2 鍥剧墖绫讳笟鍔�
+
+```vue
+<ImageUpload v-model:file-list="form.images" />
+<ImagePreview :file-list="form.images" />
+```
+
+### 8.3 宸茶惤搴撻檮浠剁鐞�
+
+```vue
+<FileListDialog
+  v-model:visible="dialogVisible"
+  :record-type="recordType"
+  :record-id="recordId"
+/>
+```
+
+閫傚悎璇︽儏椤点�佸鎵归〉銆佸彴璐﹂〉杩欑被鈥滄煡鐪嬪苟缁存姢褰撳墠涓氬姟闄勪欢鈥濈殑鍦烘櫙銆�
+
+## 9. 娉ㄦ剰浜嬮」
+
+1. `FileUpload` 鍜� `ImageUpload` 鍙槸璐熻矗鎶婃枃浠跺厛浼犲埌 `/common/upload`锛屼笉绛変簬宸茬粡鍜屼笟鍔℃暟鎹粦瀹氥��
+2. 濡傛灉涓氬姟闇�瑕佹寔涔呭寲闄勪欢鍏崇郴锛屼粛闇�瑕佸湪淇濆瓨琛ㄥ崟鏃舵妸杩斿洖鐨勬枃浠跺璞℃彁浜ょ粰涓氬姟鎺ュ彛銆�
+3. `ImagePreview` 褰撳墠鍙瘑鍒� `previewURL`锛屽鏋滃悗绔彧杩斿洖 `url`锛岄瑙堢粍浠跺皢涓嶄細灞曠ず锛屾渶濂界粺涓�琛ラ綈 `previewURL`銆�
+4. `FileListDialog` 渚濊禆 `recordType`銆乣recordId` 鏌ヨ鍜屼繚瀛橀檮浠跺叧绯伙紝鏂板涓氬姟鏃惰鍏堢‘璁ゅ悗绔叧鑱旀帴鍙ｅ彲鐢ㄣ��
+5. 鍒犻櫎鏈湴鍒楄〃椤瑰拰鍒犻櫎宸蹭繚瀛橀檮浠舵槸涓や欢浜嬶細
+   - 涓婁紶缁勪欢閲岀殑鍒犻櫎锛氬彧浼氫粠褰撳墠鍓嶇缁戝畾鏁扮粍涓Щ闄�
+   - `commonFile.js` / `deleteAttachment`锛氭墠鏄湡姝ｈ皟鐢ㄥ悗绔垹闄�
+
+## 10. 涓�濂楁渶甯歌鐨勯〉闈㈠啓娉�
+
+```vue
+<template>
+  <el-form :model="form">
+    <el-form-item label="闄勪欢">
+      <FileUpload v-model:file-list="form.storageBlobDTOs" :limit="5" />
+    </el-form-item>
+
+    <el-form-item label="鐜板満鍥剧墖">
+      <ImageUpload v-model:file-list="form.images" :limit="9" />
+    </el-form-item>
+
+    <el-form-item label="鍥剧墖棰勮">
+      <ImagePreview :file-list="form.images" />
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const form = ref({
+  storageBlobDTOs: [],
+  images: [],
+})
+</script>
+```
+
+濡傛灉浣犵殑鐩爣鏄�滃厛涓婁紶锛屽啀璺熶笟鍔′竴璧蜂繚瀛樷�濓紝杩欏鍐欐硶鍙互鐩存帴浣滀负鍩虹妯℃澘浣跨敤銆�

--
Gitblit v1.9.3