1、调整凭证

2、调整运单
2026-09-08 17:50:34 +08:00
parent a7315b4491
commit cba2ad3b3b
43 changed files with 5730 additions and 1119 deletions
@@ -0,0 +1,300 @@
+# 凭证管理审核功能增强说明
+
+## 功能概述
+
+本次更新对凭证管理模块进行了审核流程增强，主要包括：
+
+1. **承运商信息自动记录**：上传时自动识别并记录承运商信息
+2. **权限控制**：外部组织用户只能查看自己上传的凭证数据
+3. **审核流程**：处理完成后自动进入待审核状态，支持审核通过和审核驳回
+4. **界面优化**：承运商用户隐藏不相关的字段和操作
+
+## 一、数据库变更
+
+### 1.1 新增字段
+
+文件：`/doc/sql/transport/blade_voucher_manage_audit_20260908.sql`
+
+```sql
+-- 添加承运商ID字段
+ALTER TABLE `blade_voucher_manage`
+ADD COLUMN `carrier_id` bigint DEFAULT NULL COMMENT '承运商ID（组织ID）' AFTER `carrier_name`;
+
+-- 添加索引
+ALTER TABLE `blade_voucher_manage`
+ADD KEY `idx_voucher_manage_carrier_id` (`carrier_id`),
+ADD KEY `idx_voucher_manage_audit_status` (`audit_status`);
+```
+
+### 1.2 新增菜单权限
+
+```sql
+INSERT INTO `blade_menu` 
+(2090000000000000905, 2090000000000000900, 'voucher_manage_audit_pass', '审核通过', ...),
+(2090000000000000906, 2090000000000000900, 'voucher_manage_audit_reject', '审核驳回', ...);
+```
+
+## 二、后端变更
+
+### 2.1 实体类 (VoucherManage.java)
+
+新增字段：
+- `Long carrierId` - 承运商ID（组织ID）
+
+### 2.2 Controller (VoucherManageController.java)
+
+新增接口：
+- `POST /audit-pass` - 审核通过
+- `POST /audit-reject` - 审核驳回（支持驳回原因）
+
+### 2.3 Service接口 (IVoucherManageService.java)
+
+新增方法：
+```java
+void auditPass(Long id);
+void auditReject(Long id, String rejectReason);
+```
+
+### 2.4 Service实现 (VoucherManageServiceImpl.java)
+
+#### 2.4.1 submit方法增强
+
+- 自动判断用户组织类型
+- 如果顶级组织是"外部组织"，自动设置：
+  - `uploadSource = "承运商"`
+  - `carrierId = 当前用户组织ID`
+  - `carrierName = 当前用户组织名称`
+- 否则设置为"内部"上传
+
+#### 2.4.2 buildQuery方法增强
+
+- 添加权限控制逻辑
+- 外部组织用户只能查询自己上传的凭证（`createUser = 当前用户ID`）
+
+#### 2.4.3 processUploadedVoucher方法增强
+
+- 处理完成后自动设置 `auditStatus = "待审核"`
+
+#### 2.4.4 新增审核方法
+
+```java
+// 审核通过
+public void auditPass(Long id) {
+    // 验证状态：必须是"处理完成"且"待审核"
+    // 设置 auditStatus = "审核通过"
+}
+
+// 审核驳回
+public void auditReject(Long id, String rejectReason) {
+    // 验证状态：必须是"处理完成"且"待审核"
+    // 设置 auditStatus = "审核驳回"
+}
+```
+
+#### 2.4.5 新增辅助方法
+
+```java
+// 判断是否为外部组织（递归查询顶级组织）
+private boolean isExternalOrganization(Long deptId);
+
+// 获取组织名称
+private String getOrganizationName(Long deptId);
+```
+
+### 2.5 Mapper (VoucherManageMapper.java)
+
+新增查询方法：
+```java
+// 查询组织的顶级父组织ID（使用递归CTE）
+Long selectTopDeptId(@Param("deptId") Long deptId);
+
+// 查询组织名称
+String selectDeptName(@Param("deptId") Long deptId);
+```
+
+## 三、前端变更
+
+### 3.1 API接口 (voucher-manage.js)
+
+新增方法：
+```javascript
+export const auditPass = id => request({ url: `${baseUrl}/audit-pass`, method: 'post', params: { id } });
+export const auditReject = (id, rejectReason) => request({ url: `${baseUrl}/audit-reject`, method: 'post', params: { id, rejectReason } });
+```
+
+### 3.2 页面组件 (voucher-manage.vue)
+
+#### 3.2.1 用户类型判断
+
+```javascript
+// 判断当前用户是否为承运商
+const isCarrier = ref(false);
+const checkIfCarrier = () => {
+  const userInfo = store.getters.userInfo || {};
+  const topDeptName = userInfo.top_dept_name || userInfo.topDeptName || '';
+  isCarrier.value = topDeptName === '外部组织';
+};
+```
+
+#### 3.2.2 搜索表单优化
+
+- 承运商用户隐藏"上传来源"和"承运商"搜索条件（`v-if="!isCarrier"`）
+
+#### 3.2.3 表格列优化
+
+- 承运商用户隐藏以下列：
+  - 上传来源
+  - 承运商名称
+
+#### 3.2.4 操作按钮优化
+
+表格操作列宽度调整为 `200px`，新增审核按钮：
+
+| 按钮 | 显示条件 | 用户限制 |
+|------|---------|---------|
+| 审核通过 | 处理完成 + 待审核 | 仅内部用户 |
+| 审核驳回 | 处理完成 + 待审核 | 仅内部用户 |
+| 查看 | 处理完成 | 全部用户 |
+| 下载 | 处理完成 | 全部用户 |
+| 更换运单批次 | 未完成或待审核 | 全部用户 |
+| 删除 | 上传中或审核驳回 | 全部用户 |
+
+#### 3.2.5 新增审核方法
+
+```javascript
+// 审核通过
+const handleAuditPass = row => {
+  ElMessageBox.confirm(`确认审核通过凭证批次"${row.voucherBatchNo}"吗？`, '提示', {
+    type: 'warning',
+  }).then(async () => {
+    await api.auditPass(row.id);
+    ElMessage.success('审核通过');
+    load();
+  });
+};
+
+// 审核驳回（支持输入驳回原因）
+const handleAuditReject = row => {
+  ElMessageBox.prompt('请输入驳回原因（可选）', '审核驳回', {
+    confirmButtonText: '确认',
+    cancelButtonText: '取消',
+    inputPattern: /.*/,
+  }).then(async ({ value }) => {
+    await api.auditReject(row.id, value || '');
+    ElMessage.success('审核驳回');
+    load();
+  });
+};
+```
+
+## 四、业务流程
+
+### 4.1 承运商上传流程
+
+1. 承运商用户登录（顶级组织为"外部组织"）
+2. 上传凭证时，系统自动记录：
+   - 上传来源：承运商
+   - 承运商ID：用户组织ID
+   - 承运商名称：用户组织名称
+3. 上传完成后，凭证进入"处理中"状态
+4. 处理完成后，自动变为"待审核"状态
+5. 承运商用户只能看到自己上传的凭证
+
+### 4.2 内部用户审核流程
+
+1. 内部用户可以看到所有凭证（包括内部和承运商上传的）
+2. 处理完成且待审核的凭证，显示"审核通过"和"审核驳回"按钮
+3. 点击"审核通过"：凭证状态变为"审核通过"
+4. 点击"审核驳回"：可输入驳回原因，凭证状态变为"审核驳回"
+5. 审核驳回的凭证可以被删除
+
+### 4.3 状态流转
+
+```
+上传中 → 处理中 → 处理完成（自动变为"待审核"）
+                     ↓
+            待审核 → 审核通过
+                  ↘ 审核驳回 → 可删除
+```
+
+## 五、权限控制说明
+
+### 5.1 数据权限
+
+| 用户类型 | 可见范围 |
+|---------|---------|
+| 内部用户 | 全部凭证 |
+| 承运商用户 | 仅自己上传的凭证 |
+
+### 5.2 功能权限
+
+| 功能 | 内部用户 | 承运商用户 |
+|-----|---------|-----------|
+| 批量导入凭证 | ✓ | ✓ |
+| 查看凭证 | ✓ | ✓（仅自己的） |
+| 下载凭证 | ✓ | ✓（仅自己的） |
+| 更换运单批次 | ✓ | ✓（仅自己的） |
+| 删除凭证 | ✓ | ✓（仅自己的） |
+| 审核通过 | ✓ | ✗ |
+| 审核驳回 | ✓ | ✗ |
+| 查看上传来源字段 | ✓ | ✗ |
+| 查看承运商字段 | ✓ | ✗ |
+
+## 六、部署步骤
+
+### 6.1 数据库部署
+
+执行SQL脚本：
+```bash
+mysql -u用户名 -p数据库名 < blade_voucher_manage_audit_20260908.sql
+```
+
+### 6.2 后端部署
+
+1. 编译后端代码
+2. 重启 `blade-transport` 服务
+
+### 6.3 前端部署
+
+1. 构建前端代码：`pnpm run build:prod`
+2. 部署到Web服务器
+
+## 七、注意事项
+
+1. **数据兼容性**：现有凭证的 `carrier_id` 字段为 `NULL`，不影响现有功能
+2. **权限配置**：需要为相关角色分配"审核通过"和"审核驳回"权限
+3. **组织判断**：依赖 `blade_dept` 表的 `dept_name` 字段，顶级组织必须命名为"外部组织"
+4. **审核状态**：只有"处理完成"且"待审核"的凭证才能审核
+5. **用户信息**：前端需要确保 `store.getters.userInfo` 中包含 `top_dept_name` 或 `topDeptName` 字段
+
+## 八、测试建议
+
+### 8.1 功能测试
+
+- [ ] 内部用户上传凭证，验证上传来源为"内部"
+- [ ] 承运商用户上传凭证，验证上传来源为"承运商"，承运商信息自动记录
+- [ ] 承运商用户只能看到自己上传的凭证
+- [ ] 内部用户可以看到所有凭证
+- [ ] 凭证处理完成后自动变为"待审核"状态
+- [ ] 内部用户可以审核通过凭证
+- [ ] 内部用户可以审核驳回凭证
+- [ ] 承运商用户看不到审核按钮
+- [ ] 承运商用户看不到"上传来源"和"承运商名称"列
+
+### 8.2 权限测试
+
+- [ ] 承运商用户无法访问 `/audit-pass` 接口
+- [ ] 承运商用户无法访问 `/audit-reject` 接口
+- [ ] 承运商用户无法看到其他承运商的凭证
+
+### 8.3 异常测试
+
+- [ ] 审核非"待审核"状态的凭证，验证错误提示
+- [ ] 审核非"处理完成"状态的凭证，验证错误提示
+- [ ] 组织信息缺失时，系统正常运行
+
+---
+
+**修改日期**：2026-09-08  
+**修改人**：Claude  
+**版本**：v1.0