# 学生考核申请附件功能改造说明

## 改造概述

本次改造将学生考核申请表单中的附件上传功能升级为与宿舍违纪模块相同的现代化附件管理系统，提供更好的用户体验和功能完整性。

## 改造内容

### 1. 界面升级
- **拖拽上传**: 支持拖拽文件到上传区域
- **卡片式展示**: 文件以卡片形式展示，每行5个文件
- **缩略图预览**: 图片文件显示缩略图，其他文件显示文件类型图标
- **文件名显示**: 智能截断长文件名，保留后缀
- **操作按钮**: 每个文件卡片提供下载和删除按钮

### 2. 功能增强
- **多文件上传**: 支持同时上传多个文件，最多15个
- **文件类型限制**: 支持图片、视频、PDF、Word文档等格式
- **文件大小限制**: 单个文件不超过10MB
- **实时预览**: 图片文件可直接预览
- **文件下载**: 支持下载已上传的文件
- **文件删除**: 支持删除不需要的文件

### 3. 技术实现

#### 3.1 上传配置
```typescript
// 上传地址
const uploadAction = computed(() => {
  return import.meta.env.VITE_APP_BASE_API + '/resource/oss/upload';
});

// 上传请求头
const uploadHeaders = computed(() => {
  return {
    'Authorization': `Bearer ${getToken() || ''}`,
    'clientid': import.meta.env.VITE_APP_CLIENT_ID || 'e5cd7e4891bf95d1d19206ce24a7b32e'
  };
});

// 业务类型标识
const uploadData = computed(() => {
  return {
    bizType: 'assessment_bonus_attachment'
  };
});
```

#### 3.2 文件处理函数
- `handleBeforeUpload`: 上传前文件校验
- `handleUploadSuccess`: 上传成功处理
- `handleUploadError`: 上传失败处理
- `handleFileChange`: 文件列表变更处理
- `handleFilePreview`: 文件预览处理
- `handleDownloadAttachment`: 文件下载处理
- `handleRemoveAttachmentConfirm`: 文件删除确认
- `handleRemoveAttachment`: 文件删除处理

#### 3.3 辅助函数
- `isImageFile`: 判断是否为图片文件
- `getFileOssId`: 获取文件OSS ID
- `getFileExt`: 获取文件扩展名
- `getShortFileName`: 获取缩写的文件名

### 4. 数据结构更新

#### 4.1 接口定义
```typescript
interface XskhAssessmentBonusApprovalForm {
  id?: string | number;
  applicationId?: string | number;
  bonusItemName?: string;
  bonusContent?: string;
  bonusScore?: number;
  attachment?: string;        // 存储OSS ID列表，逗号分隔
  approvalStatus?: string;
  approvalScore?: number;
  approvalBy?: string | number;
  approvalTime?: string;
  approvalRemark?: string;
  fileList?: any[];          // 新增：存储文件列表，用于界面展示
}
```

#### 4.2 数据转换
- **保存时**: 将`fileList`中的`ossId`合并为`attachment`字段
- **加载时**: 将`attachment`字段解析为`fileList`用于界面展示

### 5. 样式设计

#### 5.1 容器样式
- 固定高度，支持滚动
- 灰色背景，圆角边框
- 响应式布局

#### 5.2 文件卡片样式
- 180px高度，圆角设计
- 悬停效果，阴影变化
- 缩略图区域110px高度
- 文件名区域32px高度
- 操作按钮区域38px高度

#### 5.3 网格布局
- 使用CSS Grid布局
- 每行5个文件卡片
- 9px间距
- 自适应宽度

## 使用说明

### 1. 新增附加分项目
1. 点击"添加附加分"按钮
2. 填写项目信息
3. 在附件区域拖拽或点击上传文件
4. 文件上传成功后显示在卡片列表中

### 2. 编辑附加分项目
1. 打开编辑弹窗
2. 系统自动加载已有附件
3. 可以添加、删除、下载附件
4. 保存时自动更新附件信息

### 3. 查看考核申请
1. 打开查看弹窗
2. 附件区域为只读状态
3. 可以预览图片和下载文件
4. 不能进行上传和删除操作

## 兼容性说明

### 1. 向后兼容
- 保持原有的`attachment`字段格式
- 支持旧数据的正常加载和显示
- 不影响现有业务逻辑

### 2. 数据迁移
- 无需数据迁移
- 新功能与旧数据格式兼容
- 自动处理数据转换

## 注意事项

### 1. 文件限制
- 支持格式：jpg, jpeg, png, gif, bmp, webp, pdf, doc, docx, txt, mp4, avi, mov
- 文件大小：单个文件不超过10MB
- 文件数量：每个附加分项目最多15个文件

### 2. 权限控制
- 查看模式下禁用上传和删除功能
- 编辑模式下支持所有操作
- 新增模式下支持所有操作

### 3. 错误处理
- 文件格式错误时显示提示
- 文件大小超限时显示提示
- 上传失败时显示错误信息
- 网络异常时提供重试机制

## 技术依赖

### 1. 组件依赖
- `ImagePreview`: 图片预览组件
- `ElUpload`: Element Plus上传组件
- `ElButtonGroup`: 按钮组组件

### 2. 图标依赖
- `UploadFilled`: 上传图标
- `Document`: 文档图标
- `Loading`: 加载图标
- `Download`: 下载图标
- `Delete`: 删除图标

### 3. 工具函数
- `getToken`: 获取认证令牌
- `request`: HTTP请求工具
- `ElMessage`: 消息提示
- `ElMessageBox`: 确认对话框
- `ElLoading`: 加载状态

## 2025-11-29 移动端违纪记录适配

最新一轮改造已经将移动端违纪记录录入页（`mobile/src/pages/xskh/wjjlEntry/disciplineRecordForm.vue`）迁移到与宿舍卫生检查新增页一致的附件上传方案，主要收益如下：

1. **统一的上传能力**：支持 `uni.chooseFile`、相册/相机、备用 action sheet，多端体验保持一致。
2. **多类型文件**：除图片外，可上传 PDF、Word 等文档并在界面上以卡片方式区分展示。
3. **微信优化**：在微信内置浏览器自动初始化 JS-SDK，保留进度条与后端 `/system/wechat/downloadToOss` 的桥接能力。
4. **一致的交互**：图片列表提供预览/下载/删除/重试，文档列表提供下载/删除/重试，同步复用 15 个文件、10MB 大小的限制说明。

后续若有新的移动端页面需要接入文件上传，可直接参考此实现或复用该文档中的“技术实现”章节配置，确保多端体验保持一致。

## 总结

本次改造成功将学生考核申请的附件功能升级为现代化的文件管理系统，提供了：

1. **更好的用户体验**: 拖拽上传、卡片展示、实时预览
2. **完整的功能**: 上传、下载、删除、预览
3. **稳定的技术**: 基于成熟的OSS存储系统
4. **良好的兼容性**: 与现有系统无缝集成

改造后的附件功能与宿舍违纪模块保持一致，提供了统一的用户体验和功能标准。