# 订单班图片处理标准化流程和最佳实践 (2025-10-03)

## 核心原则
**图片文件名必须与markdown文档中的alt text（描述文字）完全一致**

例如：
- ✅ 正确：`![营养盐示意图](image/营养盐示意图.jpg)`
- ❌ 错误：`![营养盐示意图](image/营养盐.jpg)`

## 标准处理流程

### 1. 分析阶段
```bash
# 读取markdown文档，提取所有图片引用
cat "文档名.md" | grep "!\["

# 分析图片引用格式
# 格式：![alt text](image/filename.jpg)
# 目标：alt text = filename（不含扩展名）
```

### 2. 检查文件现状
```bash
# 查看图片目录
ls -la image/

# 识别需要重命名的文件类型：
# - Hash名称：如 65351297-3c82-49ea-a8c7-03944a3af294.jpg
# - 通用名称：如 image.jpg, image 1.jpg
# - Whisk系列：如 Whisk_3bc3f132f453ff1a1e3492de3faca12fdr.jpg
# - URL编码：如 %E9%95%BF%E6%B1%9F%E5%9B%BE%E7%89%87.jpg
# - 不完整中文名：如 营养盐.jpg（应为 营养盐示意图.jpg）
```

### 3. 创建映射关系
分析每个图片的alt text，创建重命名映射：
- 从markdown中提取alt text作为目标文件名
- 保持.jpg扩展名统一
- 确保中文名称完整且与alt text一致

### 4. 批量重命名脚本
```bash
#!/bin/bash
cd "$(dirname "$0")/image"

# 示例映射
mv "原文件名.jpg" "目标文件名.jpg"
mv "image.jpg" "中华人民共和国环境保护法截图.jpg"
mv "65351297-3c82-49ea-a8c7-03944a3af294.jpg" "长江采样布点图.jpg"
# ... 更多映射

echo "✓ 图片重命名完成"
```

### 5. 更新markdown引用
```bash
# 使用sed批量替换
sed -i '' \
  -e 's|image/原文件名\.jpg|image/新文件名.jpg|g' \
  -e 's|image/image\.jpg|image/中华人民共和国环境保护法截图.jpg|g' \
  "文档名.md"
```

### 6. 验证步骤
```bash
# 验证markdown中的引用
grep "image/" "文档名.md"

# 验证文件存在
ls -la image/ | grep "特定文件名"

# 检查alt text与文件名一致性
# 确保 ![XXX](image/XXX.jpg) 格式
```

## 常见问题和解决方案

### 问题1：URL编码的中文文件名
- **现象**：`%E9%95%BF%E6%B1%9F%E5%9B%BE%E7%89%87.jpg`
- **解决**：直接在markdown中替换为正常中文，文件系统已经是正确的中文名

### 问题2：文件名与alt text不完全一致
- **现象**：`![营养盐示意图](image/营养盐.jpg)`
- **解决**：重命名文件为完整的alt text：`营养盐.jpg` → `营养盐示意图.jpg`

### 问题3：扩展名不一致（.jpeg vs .jpg）
- **现象**：markdown中是.jpeg但文件是.jpg
- **解决**：统一使用.jpg扩展名

### 问题4：特殊字符处理
- **现象**：alt text中包含下划线、空格等
- **解决**：文件名保持与alt text完全一致，包括特殊字符

## 最佳实践

### 1. 命名规范
- 使用描述性中文名称
- 避免使用通用名称（image.jpg、图片1.jpg）
- 保持alt text与文件名完全一致
- 统一使用.jpg扩展名

### 2. 处理顺序
1. 先分析所有图片的alt text
2. 创建完整的重命名映射表
3. 一次性执行所有重命名
4. 批量更新markdown引用
5. 全面验证结果

### 3. 质量检查
- 确保每个图片都有描述性的alt text
- 验证所有图片文件都存在
- 检查markdown渲染是否正常
- 保存处理记录便于追溯

## 实际案例总结

### 财经商贸订单班（21个图片）
- Hash名称 → 描述性名称：如 `6b00bb23e96aba0d679669cfa2e28c14.jpeg` → `平台电商优势展示图.jpg`
- 重点：电商运营相关的界面设计图、产品展示图

### 环保订单班（26个图片）
- 通用名称 → 法规名称：如 `image.jpg` → `中华人民共和国环境保护法截图.jpg`
- 不完整名称 → 完整名称：如 `营养盐.jpg` → `营养盐示意图.jpg`
- 重点：水质监测相关的技术图表、法规截图

## 工具函数

### 快速检查不一致的文件
```bash
# 提取所有需要检查的图片引用
grep -E "!\[.*\]\(image/.*\)" "文档.md" | \
while read line; do
  alt=$(echo "$line" | sed 's/.*\[\([^]]*\)\].*/\1/')
  file=$(echo "$line" | sed 's/.*image\/\([^)]*\)\).*/\1/' | sed 's/.jpg$//')
  if [ "$alt" != "$file" ]; then
    echo "不一致: [$alt] != [$file]"
  fi
done
```

## 记忆要点
1. **核心原则**：文件名 = alt text
2. **统一格式**：全部使用.jpg
3. **批处理优先**：避免逐个手动修改
4. **完整验证**：确保所有引用正确
5. **记录留存**：保存处理脚本和映射关系

---

**最后更新**：2025-10-03
**适用范围**：所有订单班的notion文稿图片处理