docs: add implementation plan for reimburse apply attachments
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed
1 parent
4b012923bf
commit
112ad31428
1 file changed
+500
@@ -0,0 +1,500 @@
|
||||
# 报销申请「申请附件」Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 在 Web 报销申请与 bx-mobile 申请页增加可选「申请附件」上传/绑定/查看，与发票夹分离，复用现有 `reimburse_apply` 附件能力。
|
||||
|
||||
**Architecture:** 不改表结构。上传走已有 `attachmentApi`（`biz_type=reimburse_apply`）；新建先 `bizId=0` 再 `bindBiz`；编辑回填 `listByBiz`。Web 用 `BxAttachmentUpload`；H5 对齐备用金 `useAttachment` + `van-uploader`。详情文案「历史附件」统一为「申请附件」。
|
||||
|
||||
**Tech Stack:** Vue 3、Element Plus、`BxAttachmentUpload`、bx-mobile Vant、`useAttachment`、既有 BX attachment API
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-09-05-reimburse-apply-attachments-design.md`
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
| 操作 | 文件 | 职责 |
|
||||
|------|------|------|
|
||||
| Modify | `web-admin/src/views/bx/reimburse/apply/index.vue` | 申请弹窗上传区；保存后 bind；编辑回填；详情文案 |
|
||||
| Modify | `web-admin/src/views/bx/reimburse/approve/index.vue` | 「历史附件」→「申请附件」 |
|
||||
| Modify | `web-admin/src/views/bx/view/todo/index.vue` | 同上 |
|
||||
| Modify | `web-admin/src/views/bx/view/all/index.vue` | 同上 |
|
||||
| Modify | `web-admin/src/views/bx/view/mine/index.vue` | 同上 |
|
||||
| Modify | `bx-mobile/src/views/reimburse/ReimburseApplyPage.vue` | 申请附件上传区 + bind/load |
|
||||
|
||||
**不变：** 后端 schema、发票夹、`miniprogram`、付款发放/冲抵附件逻辑。
|
||||
|
||||
**参考：**
|
||||
|
||||
- Web 组件：`web-admin/src/components/bx/base/BxAttachmentUpload.vue`（`hasUploading` / `getFileIds`）
|
||||
- Web 用法：`web-admin/src/views/bx/payment/index.vue` 发放附件
|
||||
- H5：`bx-mobile/src/views/advance/AdvanceApplyPage.vue` + `bx-mobile/src/hooks/useAttachment.ts`
|
||||
- API：`attachmentApi` 已在 `web-admin/src/api/bx/index.ts` 与 `bx-mobile/src/api/index.ts`
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Web 申请弹窗 — 上传 UI 与状态
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/views/bx/reimburse/apply/index.vue`
|
||||
|
||||
- [ ] **Step 1: 增加 import 与状态**
|
||||
|
||||
在 script 中补充：
|
||||
|
||||
```ts
|
||||
import { attachmentApi, reimburseApi, invoiceWalletApi } from '@/api/bx'
|
||||
import BxAttachmentUpload from '@/components/bx/base/BxAttachmentUpload.vue'
|
||||
```
|
||||
|
||||
（若 `reimburseApi` / `invoiceWalletApi` 已从 `@/api/bx` 导入，合并为一条 import，并加上 `attachmentApi`。）
|
||||
|
||||
在现有 `selectedInvoicePicks` 附近增加：
|
||||
|
||||
```ts
|
||||
const applyAttachmentRef = ref<InstanceType<typeof BxAttachmentUpload> | null>(null)
|
||||
const applyAttachments = ref<BxAttachmentItem[]>([])
|
||||
```
|
||||
|
||||
`BxAttachmentItem` 已从 `@/utils/bx/attachment` 导入则复用；否则一并导入。
|
||||
|
||||
- [ ] **Step 2: 在模板插入上传区块**
|
||||
|
||||
在「关联发票（可选）」整块（含 `selectedInvoicePicks` / `BxInvoiceSelectDialog` 触发区）之后、「备注说明」`el-form` 之前插入：
|
||||
|
||||
```vue
|
||||
<div class="form-section">
|
||||
<h4>申请附件（可选）</h4>
|
||||
<BxAttachmentUpload
|
||||
ref="applyAttachmentRef"
|
||||
v-model="applyAttachments"
|
||||
biz-type="reimburse_apply"
|
||||
:biz-id="editingId || 0"
|
||||
hint="补充行程单、说明截图、合同等；与发票夹无关。支持图片、视频、PDF、Office、压缩包等。"
|
||||
/>
|
||||
</div>
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 打开新增 / 重置时清空附件**
|
||||
|
||||
在 `openAddDialog` 与 `resetAddForm` 中增加：
|
||||
|
||||
```ts
|
||||
applyAttachments.value = []
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 打开编辑时回填附件**
|
||||
|
||||
在 `openEditDialog` 成功拿到 `row.id` 并 `dialogs.add = true` 之后，在现有 `Promise.all([...])` 中增加加载，或在其后：
|
||||
|
||||
```ts
|
||||
applyAttachments.value = await loadBxAttachments('reimburse_apply', row.id).catch(() => [])
|
||||
```
|
||||
|
||||
（`loadBxAttachments` 已在本文件导入。）
|
||||
|
||||
- [ ] **Step 5: 本地确认弹窗可打开、上传控件可见**
|
||||
|
||||
Run: `cd web-admin && pnpm dev`（若已在跑则刷新）
|
||||
打开 `#/bx/reimburse/apply` → 新增 → 在发票区与备注之间应看到「申请附件（可选）」。
|
||||
Expected: 上传卡片可见；未保存前可不实际上传。
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/views/bx/reimburse/apply/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(bx): add apply-attachment upload UI on reimburse apply dialog
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Web — 保存/提交时拦截上传中并 bindBiz
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/views/bx/reimburse/apply/index.vue`
|
||||
|
||||
- [ ] **Step 1: 增加 bind 辅助函数**
|
||||
|
||||
放在 `saveAddForm` 附近：
|
||||
|
||||
```ts
|
||||
async function bindApplyAttachments(reimburseId: string) {
|
||||
const ids = (applyAttachmentRef.value?.getFileIds?.() || applyAttachments.value.map((f) => f.id)).filter(
|
||||
(id) => id != null && id !== '' && !String(id).startsWith('upload-')
|
||||
)
|
||||
if (!ids.length) return
|
||||
try {
|
||||
await attachmentApi.bindBiz(ids, 'reimburse_apply', reimburseId)
|
||||
} catch (e: any) {
|
||||
ElMessage.warning(e?.message || '报销单已保存，但申请附件关联失败，请重新编辑后保存')
|
||||
}
|
||||
}
|
||||
|
||||
function assertApplyAttachmentsIdle(): boolean {
|
||||
if (applyAttachmentRef.value?.hasUploading()) {
|
||||
ElMessage.warning('附件上传中，请稍候')
|
||||
return false
|
||||
}
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 改 `submitAdd`**
|
||||
|
||||
在 `buildAddPayload()` 之后、`loadingMap.addSubmit = true` 之前：
|
||||
|
||||
```ts
|
||||
if (!assertApplyAttachmentsIdle()) return
|
||||
```
|
||||
|
||||
在 `const id = await saveAddForm(payload)` 成功且 `id` 有值后、`ElMessage.success` 之前：
|
||||
|
||||
```ts
|
||||
await bindApplyAttachments(id)
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 改 `submitAddAndApprove`**
|
||||
|
||||
同样在 payload 校验后加 `assertApplyAttachmentsIdle()`；在 `saveAddForm` 成功得到 `id` 后、`reimburseApi.submit` 之前调用 `await bindApplyAttachments(id)`。
|
||||
|
||||
- [ ] **Step 4: 手测绑定**
|
||||
|
||||
1. 新增报销：填一条明细 → 上传 1 张图片 → 保存草稿
|
||||
2. 打开详情 →「申请附件」区应能看到文件（若文案仍是「历史附件」，Task 3 再改）
|
||||
3. 编辑该草稿 → 附件应回显；再传一个文件保存 → 详情应有两个
|
||||
|
||||
Expected: 上传中点保存会 toast「附件上传中，请稍候」；无附件可正常保存。
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/views/bx/reimburse/apply/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(bx): bind reimburse apply attachments on save and submit
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Web — 「历史附件」文案统一为「申请附件」
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/views/bx/reimburse/apply/index.vue`
|
||||
- Modify: `web-admin/src/views/bx/reimburse/approve/index.vue`
|
||||
- Modify: `web-admin/src/views/bx/view/todo/index.vue`
|
||||
- Modify: `web-admin/src/views/bx/view/all/index.vue`
|
||||
- Modify: `web-admin/src/views/bx/view/mine/index.vue`
|
||||
|
||||
- [ ] **Step 1: 全局替换标题文案**
|
||||
|
||||
将上述 5 个文件中用户可见的：
|
||||
|
||||
```html
|
||||
<h4 class="dlg-view-section-title">历史附件</h4>
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```html
|
||||
<h4 class="dlg-view-section-title">申请附件</h4>
|
||||
```
|
||||
|
||||
仅改展示文案，不改 `loadBxAttachments('reimburse_apply', …)` 逻辑。
|
||||
|
||||
- [ ] **Step 2: 确认无残留**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
rg '历史附件' web-admin/src/views/bx --glob '*.vue'
|
||||
```
|
||||
|
||||
Expected: 无匹配（或仅注释/无关处；业务标题应为 0）。
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/views/bx/reimburse/apply/index.vue \
|
||||
web-admin/src/views/bx/reimburse/approve/index.vue \
|
||||
web-admin/src/views/bx/view/todo/index.vue \
|
||||
web-admin/src/views/bx/view/all/index.vue \
|
||||
web-admin/src/views/bx/view/mine/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
fix(bx): rename historical attachments label to apply attachments
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: bx-mobile 申请页 — 附件上传 UI 与 accept
|
||||
|
||||
**Files:**
|
||||
- Modify: `bx-mobile/src/views/reimburse/ReimburseApplyPage.vue`
|
||||
|
||||
- [ ] **Step 1: 增加 import 与常量**
|
||||
|
||||
在 script 中增加（路径按页面现有 `@/` 别名）：
|
||||
|
||||
```ts
|
||||
import { useAttachment } from '@/hooks/useAttachment'
|
||||
```
|
||||
|
||||
在其它常量附近：
|
||||
|
||||
```ts
|
||||
const MAX_ATTACHMENTS = 10
|
||||
|
||||
/** 与 Web BxAttachmentUpload 对齐：图片/视频/文档/压缩包 */
|
||||
const attachmentAccept = [
|
||||
'image/*',
|
||||
'video/*',
|
||||
'application/pdf',
|
||||
'application/msword',
|
||||
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
|
||||
'application/vnd.ms-excel',
|
||||
'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
|
||||
'application/vnd.ms-powerpoint',
|
||||
'application/vnd.openxmlformats-officedocument.presentationml.presentation',
|
||||
'text/plain',
|
||||
'text/csv',
|
||||
'application/rtf',
|
||||
'application/zip',
|
||||
'application/x-zip-compressed',
|
||||
'application/x-rar-compressed',
|
||||
'application/x-7z-compressed',
|
||||
'.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
|
||||
'.txt', '.csv', '.rtf', '.wps', '.et', '.dps',
|
||||
'.zip', '.rar', '.7z',
|
||||
'.mp4', '.webm', '.mov', '.avi',
|
||||
].join(',')
|
||||
|
||||
const applyAttachment = useAttachment()
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 模板插入「申请附件」卡片**
|
||||
|
||||
在「关联发票」区块（含 `van-popup` 发票选择器）结束之后、「报销说明」`form-card` 之前插入（结构对齐 `AdvanceApplyPage`）：
|
||||
|
||||
```vue
|
||||
<!-- 申请附件（可选） -->
|
||||
<div class="form-card">
|
||||
<div class="form-header">
|
||||
<h3>申请附件（可选）</h3>
|
||||
</div>
|
||||
<p class="form-tip">补充行程单、说明截图、合同等；与发票夹无关。</p>
|
||||
<div class="uploader-slot-btn advance-attachment-upload">
|
||||
<van-uploader
|
||||
:after-read="onAfterReadApplyAttachment"
|
||||
:before-read="beforeReadApplyAttachment"
|
||||
:disabled="applyAttachment.uploading.value"
|
||||
multiple
|
||||
result-type="file"
|
||||
:accept="attachmentAccept"
|
||||
>
|
||||
<button
|
||||
type="button"
|
||||
class="btn btn-primary btn-sm"
|
||||
:class="{ 'btn-loading': applyAttachment.uploading.value }"
|
||||
:disabled="applyAttachment.uploading.value"
|
||||
>
|
||||
{{ applyAttachment.uploading.value ? '上传中…' : '上传附件' }}
|
||||
</button>
|
||||
</van-uploader>
|
||||
</div>
|
||||
<div v-if="applyAttachment.files.value.length" class="att-grid advance-att-grid">
|
||||
<div
|
||||
v-for="(file, idx) in applyAttachment.files.value"
|
||||
:key="file.id"
|
||||
class="att-img advance-att-tile"
|
||||
:class="{ 'is-uploading': file._pending }"
|
||||
:title="file.fileName"
|
||||
role="button"
|
||||
tabindex="0"
|
||||
@click="applyAttachment.open(file)"
|
||||
@keydown.enter.prevent="applyAttachment.open(file)"
|
||||
>
|
||||
<img
|
||||
v-if="applyAttachment.isImage(file.fileType) && file.previewUrl"
|
||||
:src="file.previewUrl"
|
||||
:alt="file.fileName"
|
||||
/>
|
||||
<div v-else class="att-file-icon att-doc-thumb">
|
||||
<span class="att-doc-thumb__ext">{{ applyAttachment.fileExt(file.fileName) }}</span>
|
||||
<span class="att-doc-thumb__name">{{ file.fileName }}</span>
|
||||
</div>
|
||||
<div v-if="file._pending" class="att-upload-mask" aria-label="上传中">
|
||||
<van-loading size="22px" color="#fff" />
|
||||
<span class="att-upload-mask__text">上传中</span>
|
||||
</div>
|
||||
<button
|
||||
v-if="!file._pending"
|
||||
type="button"
|
||||
class="del"
|
||||
@click.stop="applyAttachment.remove(idx)"
|
||||
>
|
||||
×
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
若页面 style 中尚无 `.advance-attachment-upload` / `.advance-att-grid` / `.advance-att-tile`，从 `AdvanceApplyPage.vue` 底部 scoped 样式原样拷贝对应规则到本文件（或复用本文件已有同名规则，勿重复冲突）。
|
||||
|
||||
- [ ] **Step 3: before/after read 处理函数**
|
||||
|
||||
```ts
|
||||
function beforeReadApplyAttachment(file: File | File[]) {
|
||||
const batch = Array.isArray(file) ? file : [file]
|
||||
const remain = MAX_ATTACHMENTS - applyAttachment.files.value.length
|
||||
if (remain <= 0) {
|
||||
showToast(`最多上传 ${MAX_ATTACHMENTS} 个附件`)
|
||||
return false
|
||||
}
|
||||
if (batch.length > remain) {
|
||||
showToast(`还可上传 ${remain} 个附件，超出部分已忽略`)
|
||||
return Promise.resolve(batch.slice(0, remain))
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
async function onAfterReadApplyAttachment(uploadFile: any) {
|
||||
const files = Array.isArray(uploadFile) ? uploadFile : [uploadFile]
|
||||
for (const f of files) {
|
||||
if (!f?.file) continue
|
||||
await applyAttachment.upload(f.file)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
（`showToast` 本页应已导入。）
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add bx-mobile/src/views/reimburse/ReimburseApplyPage.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(bx-mobile): add optional apply-attachment uploader on reimburse apply
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: bx-mobile — 保存 bind 与编辑 loadList
|
||||
|
||||
**Files:**
|
||||
- Modify: `bx-mobile/src/views/reimburse/ReimburseApplyPage.vue`
|
||||
|
||||
- [ ] **Step 1: 改 `onSubmit`**
|
||||
|
||||
在 `validateReimburseApplyForm()` 通过后、`submitting.value = true` 之前：
|
||||
|
||||
```ts
|
||||
if (applyAttachment.uploading.value) {
|
||||
showToast('附件上传中，请稍候')
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
在 `create` / `update` 成功并得到 `id` 之后、弹出「提交审批」对话框之前：
|
||||
|
||||
```ts
|
||||
try {
|
||||
await applyAttachment.bindNew('reimburse_apply', id)
|
||||
} catch (bindErr: any) {
|
||||
showToast(bindErr?.message || '报销单已保存，但申请附件关联失败，请重新编辑后保存')
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 编辑加载与清空**
|
||||
|
||||
在 `loadEditData` 成功解析单据后（发票 picks 处理前后均可）增加：
|
||||
|
||||
```ts
|
||||
await applyAttachment.loadList('reimburse_apply', editingId.value)
|
||||
```
|
||||
|
||||
在 `loadEditData` 开头无 `id` 分支、以及 `watch(route.query.id)` 清空编辑态时：
|
||||
|
||||
```ts
|
||||
applyAttachment.clear()
|
||||
```
|
||||
|
||||
（与 `selectedInvoicePicks.value = []` 同级。）
|
||||
|
||||
- [ ] **Step 3: 手测 H5**
|
||||
|
||||
1. 新建报销 → 上传附件 → 保存 → 进详情确认「申请附件」可见
|
||||
2. 编辑草稿 → 附件回显 → 删除一个再保存 → 详情同步
|
||||
3. 无附件可保存
|
||||
|
||||
Expected: 与发票选择互不影响；上传中保存被拦截。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add bx-mobile/src/views/reimburse/ReimburseApplyPage.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(bx-mobile): bind and load reimburse apply attachments on save/edit
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: 联调验收（对照 Spec §6）
|
||||
|
||||
**Files:** 无代码（或仅修联调发现的小问题）
|
||||
|
||||
- [ ] **Step 1: 按 Spec 验收清单逐项勾选**
|
||||
|
||||
| # | 检查项 | 结果 |
|
||||
|---|--------|------|
|
||||
| 1 | Web 上传/预览/下载/删除；与发票夹独立 | |
|
||||
| 2 | 无附件可保存、可提交审批 | |
|
||||
| 3 | 详情/审批/付款查看「申请附件」 | |
|
||||
| 4 | bx-mobile 上传与查看 | |
|
||||
| 5 | 仅 draft/rejected 可改 | |
|
||||
| 6 | 类型含图片/视频/文档等 | |
|
||||
| 7 | Web 无「历史附件」业务标题 | |
|
||||
|
||||
- [ ] **Step 2: 若有缺陷，最小修复后追加 commit**（勿扩大范围）
|
||||
|
||||
- [ ] **Step 3: 更新图谱（若改了代码文件）**
|
||||
|
||||
```bash
|
||||
./scripts/update-graph.sh frontend
|
||||
# 若只动了 bx-mobile 且脚本不覆盖，按仓库惯例更新对应 graphify；无脚本则跳过
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spec 覆盖自检
|
||||
|
||||
| Spec 要求 | Task |
|
||||
|-----------|------|
|
||||
| Web 上传区 + 可选 | Task 1 |
|
||||
| 新建 bind / 编辑回填 / 上传中拦截 | Task 2 |
|
||||
| 「历史附件」→「申请附件」 | Task 3 |
|
||||
| bx-mobile 上传 UI + accept 含视频 | Task 4 |
|
||||
| H5 bindNew / loadList / clear | Task 5 |
|
||||
| 验收标准 | Task 6 |
|
||||
| 不做小程序/新表/发票夹改造 | 全计划未引入 |
|
||||
|
||||
---
|
||||
|
||||
## 执行说明
|
||||
|
||||
本仓库前端几乎无组件单测；各 Task 以手测与 `rg` 检查代替 TDD 红绿循环。实现时勿改后端除非 bind/list 联调失败再最小修补。
|
||||
Reference in new issue
Block a user