@steedos-labs/content-compliance 0.6.2 → 0.6.4

package/IMAGE_COMPARISON_FEATURE.md

@@ -0,0 +1,275 @@
+# 图片版本对比功能文档 (Image Comparison Feature Documentation)
+
+## 功能概述 (Feature Overview)
+
+本功能实现了审批流程中前后两次提交的图片内容对比功能。当审批单被驳回修改后重新提交时，系统会自动识别图片素材，并调用AI算法对当前版本和上一版本进行对比分析，标注出差异点。
+
+The feature implements image comparison between different versions in the approval workflow. When an approval is rejected and resubmitted, the system automatically identifies image materials and calls an AI algorithm to compare the current version with the previous version, marking the differences.
+
+## 功能特性 (Features)
+
+### 1. 智能识别修改场景 (Smart Detection of Modified Submissions)
+- 自动识别审批单的"修改后提交"场景（submitter_revisions 步骤）
+- 区分首次提交和驳回后重新提交的场景
+- Automatically detects "modified submission" scenarios (submitter_revisions step)
+- Distinguishes between first-time submissions and resubmissions after rejection
+
+### 2. 图片素材筛选 (Image Material Filtering)
+- 根据扩展名自动筛选图片类型素材
+- 支持的图片格式：JPG, JPEG, PNG, GIF, BMP, TIFF, TIF, SVG, WEBP, ICO, HEIF, HEIC
+- 排除已作废和已跳过的素材
+- Automatically filters image materials by extension
+- Supported formats: JPG, JPEG, PNG, GIF, BMP, TIFF, TIF, SVG, WEBP, ICO, HEIF, HEIC
+- Excludes voided and bypassed materials
+
+### 3. 版本管理 (Version Management)
+- 自动获取素材的当前版本和历史版本
+- 支持从 OneDrive 历史记录中提取版本信息
+- 如无历史记录，则使用原始素材作为对比基准
+- Automatically retrieves current and historical versions of materials
+- Supports extracting version information from OneDrive history
+- Uses original material as baseline if no history exists
+
+### 4. 异步处理机制 (Async Processing)
+- 采用异步任务机制，不阻塞审批主流程
+- 完整的异常捕获和错误处理
+- 详细的日志记录，便于追踪和排查问题
+- Uses async task mechanism to avoid blocking the approval workflow
+- Complete exception handling and error recovery
+- Detailed logging for tracking and troubleshooting
+
+### 5. 前端展示 (Frontend Display)
+- 在素材详情页新增"版本对比" Tab
+- 并排展示当前版本和上一版本
+- 显示标注差异的对比图
+- 展示差异详情列表（类型、描述、置信度）
+- 显示相似度评分
+- New "Version Comparison" tab in material detail page
+- Side-by-side display of current and previous versions
+- Shows diff image with marked differences
+- Displays difference details list (type, description, confidence)
+- Shows similarity score
+
+## 技术架构 (Technical Architecture)
+
+### Backend Components
+
+#### 1. Core Module (`src/methods/image_comparison.ts`)
+主要功能模块：
+- `isModifiedSubmission()`: 判断是否为修改后提交场景
+- `getImageMaterials()`: 获取审批单中的所有图片素材
+- `getMaterialVersions()`: 获取素材的版本信息
+- `prepareImageComparisonData()`: 准备调用AI接口的数据
+- `callImageComparisonAPI()`: 调用AI图片对比接口
+- `storeComparisonResult()`: 存储对比结果到数据库
+- `processImageComparison()`: 处理单个素材的对比
+- `processBulkImageComparison()`: 批量处理审批单中的所有图片素材
+- `triggerImageComparisonAsync()`: 异步触发图片对比任务
+
+#### 2. Workflow Integration (`src/methods/approval_engine.ts`)
+集成点：
+- 在 `advanceApproval()` 函数中，当审批单从 `submitter_revisions` 步骤提交时触发
+- 使用 `triggerImageComparisonAsync()` 异步触发对比任务
+
+#### 3. API Actions (`src/actions/imageComparison.ts`)
+提供的API接口：
+- `POST /api/pepsico-content/image-comparison/trigger/:recordId` - 手动触发图片对比
+- `GET /api/pepsico-content/image-comparison/status/:recordId` - 获取对比状态
+
+### Database Schema
+
+#### pepsico_material 对象新增字段：
+- `image_comparison_status` (select): 对比状态 (pending/completed/skipped/failed)
+- `image_comparison_result` (json): 对比结果数据
+- `image_comparison_at` (datetime): 对比时间
+- `image_comparison_reason` (text): 跳过原因
+- `image_comparison_error` (textarea): 错误信息
+
+#### pepsico_material_approval 对象新增字段：
+- `image_comparison_status` (select): 批量对比状态 (pending/completed/partial/failed)
+- `image_comparison_stats` (json): 对比统计信息
+- `image_comparison_at` (datetime): 对比时间
+
+### Frontend Components
+
+#### Material Detail Page (`main/default/pages/pepsico_material_detail.page.amis.json`)
+新增"版本对比" Tab：
+- 对比状态展示
+- 并排图片对比显示
+- 差异标注图展示
+- 差异详情表格
+- 相似度评分
+
+#### Styles (`public/content-review/amis.css`)
+添加图片对比 Tab 的样式定义
+
+## AI 接口规范 (AI API Specification)
+
+### 请求接口 (Request Endpoint)
+```
+POST {AI_HOST}/api/v1/image-comparison
+```
+
+### 请求头 (Request Headers)
+```
+X-API-Key: {API_KEY}
+Content-Type: application/json
+```
+
+### 请求体 (Request Body)
+```json
+{
+  "material_id": "素材ID",
+  "approval_id": "审批单ID",
+  "name": "素材名称",
+  "current_version": {
+    "file_id": "当前版本文件ID",
+    "url": "当前版本URL"
+  },
+  "previous_version": {
+    "file_id": "上一版本文件ID",
+    "url": "上一版本URL"
+  },
+  "extension_type": "文件扩展名"
+}
+```
+
+### 响应体 (Response Body)
+```json
+{
+  "current_image_url": "当前版本图片URL",
+  "previous_image_url": "上一版本图片URL",
+  "diff_image_url": "差异标注图URL",
+  "similarity_score": 0.95,
+  "differences": [
+    {
+      "type": "颜色变化",
+      "description": "背景色由蓝色变为红色",
+      "confidence": 0.98,
+      "location": {
+        "x": 100,
+        "y": 200,
+        "width": 50,
+        "height": 50
+      }
+    }
+  ]
+}
+```
+
+## 环境变量配置 (Environment Variables)
+
+在 `.env` 文件中配置：
+
+```bash
+# AI 图片对比服务地址
+PEPSICO_AI_COMPARISON_HOST=https://ai-service.example.com
+
+# AI API 密钥
+PEPSICO_AI_COMPARISON_API_KEY=your-api-key-here
+
+# 如果未设置上述变量，将回退使用以下变量
+PEPSICO_AI_HOST=https://ai-service.example.com
+PEPSICO_AI_API_KEY=your-api-key-here
+```
+
+## 使用流程 (Usage Flow)
+
+### 自动触发场景 (Automatic Trigger)
+1. 审批单在审核阶段被驳回
+2. 审批单进入 `submitter_revisions` 状态
+3. 提交人修改素材后重新提交
+4. 系统自动触发图片对比（在 `advanceApproval` 时）
+5. 异步处理图片对比任务
+6. 结果存储到数据库
+7. 用户在素材详情页查看对比结果
+
+### 手动触发场景 (Manual Trigger)
+可以通过API手动触发图片对比：
+
+```bash
+curl -X POST \
+  https://your-domain.com/api/pepsico-content/image-comparison/trigger/{approvalId} \
+  -H 'Authorization: Bearer YOUR_TOKEN'
+```
+
+查询对比状态：
+```bash
+curl -X GET \
+  https://your-domain.com/api/pepsico-content/image-comparison/status/{approvalId} \
+  -H 'Authorization: Bearer YOUR_TOKEN'
+```
+
+## 错误处理 (Error Handling)
+
+### 常见错误场景
+1. **无历史版本**: 素材没有历史版本，状态标记为 `skipped`
+2. **API 调用失败**: 网络错误或AI服务不可用，状态标记为 `failed`，记录错误信息
+3. **超时**: 60秒超时限制，超时后标记为 `failed`
+4. **数据格式错误**: AI返回数据格式不符合预期，记录错误日志
+
+### 日志记录
+- 所有关键操作都有详细日志记录
+- 使用 `ctx.logger` 记录到系统日志
+- 使用 `console.log` 输出到控制台便于开发调试
+
+## 性能优化 (Performance Optimization)
+
+1. **异步处理**: 图片对比采用异步处理，不阻塞审批流程
+2. **批量处理**: 一次处理审批单中所有图片素材
+3. **错误隔离**: 单个素材对比失败不影响其他素材
+4. **状态跟踪**: 详细记录处理统计信息（总数、成功、跳过、失败）
+
+## 测试建议 (Testing Recommendations)
+
+### 单元测试
+- 测试图片素材筛选逻辑
+- 测试版本获取逻辑
+- 测试数据准备函数
+
+### 集成测试
+- 测试与AI服务的接口调用
+- 测试异步任务执行
+- 测试数据库存储
+
+### 端到端测试
+1. 创建审批单并添加图片素材
+2. 提交审批
+3. 驳回审批
+4. 修改图片素材
+5. 重新提交
+6. 验证图片对比自动触发
+7. 在素材详情页验证对比结果展示
+
+## 故障排查 (Troubleshooting)
+
+### 图片对比未触发
+- 检查审批单是否处于 `submitter_revisions` 步骤
+- 检查是否有图片类型的素材
+- 查看系统日志中的触发记录
+
+### 对比失败
+- 检查AI服务地址和API密钥配置
+- 检查网络连接
+- 查看错误日志获取详细错误信息
+- 验证素材版本是否存在
+
+### 前端显示异常
+- 检查 `image_comparison_result` 数据格式
+- 验证图片URL是否可访问
+- 检查浏览器控制台错误信息
+
+## 未来优化方向 (Future Improvements)
+
+1. **重试机制**: 添加自动重试失败的对比任务
+2. **优先级队列**: 根据素材重要性排序处理
+3. **缓存机制**: 缓存对比结果避免重复计算
+4. **增量对比**: 只对修改过的素材进行对比
+5. **多版本对比**: 支持比较更多历史版本
+6. **自定义规则**: 允许配置对比敏感度和关注点
+
+## 相关文档 (Related Documentation)
+
+- [AI-API-INTEGRATIONS.md](../../../AI-API-INTEGRATIONS.md) - API集成文档
+- [AI-ARCHITECTURE.md](../../../AI-ARCHITECTURE.md) - 架构设计文档
+- [AI-PROJECT-OVERVIEW.md](../../../AI-PROJECT-OVERVIEW.md) - 项目概览

package/IMAGE_COMPARISON_README.md

@@ -0,0 +1,250 @@
+# 🎨 Image Comparison Feature - Quick Start Guide
+
+> Automatic image version comparison for approval workflow resubmissions
+
+## 🚀 What Does It Do?
+
+When an approval is **rejected** and the submitter **modifies images** before resubmitting:
+1. ✅ System automatically detects the resubmission
+2. ✅ Identifies all image materials in the approval
+3. ✅ Retrieves current and previous versions
+4. ✅ Calls AI service to compare images
+5. ✅ Stores detailed comparison results
+6. ✅ Displays differences in a beautiful UI tab
+
+## 📦 Quick Facts
+
+- **Supported Formats**: 12+ (JPG, PNG, GIF, BMP, etc.)
+- **Processing**: Async (non-blocking)
+- **Trigger**: Automatic on resubmission
+- **UI Location**: Material detail page → "版本对比" tab
+- **Status Tracking**: Real-time with detailed logs
+
+## 🎯 Key Benefits
+
+| For | Benefit |
+|-----|---------|
+| 👔 **Reviewers** | See exactly what changed; make better decisions |
+| ✍️ **Submitters** | Verify changes were captured correctly |
+| 🏢 **Business** | Audit trail; reduced manual comparison time |
+| 💻 **System** | Automated, scalable, traceable |
+
+## 📁 File Structure
+
+```
+steedos-packages/content-review/
+├── src/
+│   ├── methods/
+│   │   └── image_comparison.ts       ⭐ Core logic (340 lines)
+│   └── actions/
+│       └── imageComparison.ts        🔌 API endpoints
+├── main/default/
+│   ├── objects/
+│   │   ├── pepsico_material/fields/  📊 5 new fields
+│   │   └── pepsico_material_approval/fields/ 📊 3 new fields
+│   └── pages/
+│       └── pepsico_material_detail.page.amis.json  🎨 UI tab
+├── public/content-review/
+│   └── amis.css                      💅 Styles
+├── test_image_comparison.js          🧪 Tests
+├── IMAGE_COMPARISON_FEATURE.md       📖 Full docs
+└── README (this file)                📄 Quick start
+
+Root directory:
+├── IMAGE_COMPARISON_IMPLEMENTATION.md    📋 Summary
+└── IMAGE_COMPARISON_ARCHITECTURE_DIAGRAMS.md  📐 Diagrams
+```
+
+## ⚙️ Setup (3 Steps)
+
+### 1. Configure Environment
+Add to `.env`:
+```bash
+PEPSICO_AI_COMPARISON_HOST=https://your-ai-service.com
+PEPSICO_AI_COMPARISON_API_KEY=your-secret-key
+```
+
+### 2. Build & Deploy
+```bash
+cd steedos-packages/content-review
+npm run build
+# Deploy to your environment
+```
+
+### 3. Test
+```bash
+node test_image_comparison.js
+```
+
+## 🔧 API Endpoints
+
+### Trigger Comparison (Manual)
+```bash
+POST /api/pepsico-content/image-comparison/trigger/:approvalId
+```
+
+### Check Status
+```bash
+GET /api/pepsico-content/image-comparison/status/:approvalId
+```
+
+## 🎓 How to Use
+
+### Automatic Flow
+1. Create approval with images
+2. Submit → gets rejected
+3. Modify images
+4. Resubmit → **comparison auto-triggers** 🎯
+5. View results in "版本对比" tab
+
+### Manual Trigger (for testing)
+```bash
+curl -X POST \
+  http://localhost:5000/api/pepsico-content/image-comparison/trigger/{approvalId}
+```
+
+## 📊 Database Fields
+
+### On `pepsico_material`
+- `image_comparison_status` - Status: pending/completed/skipped/failed
+- `image_comparison_result` - Full comparison data (JSON)
+- `image_comparison_at` - Timestamp
+- `image_comparison_reason` - Why skipped (if applicable)
+- `image_comparison_error` - Error details (if failed)
+
+### On `pepsico_material_approval`
+- `image_comparison_status` - Batch status
+- `image_comparison_stats` - Statistics: {total, processed, skipped, failed}
+- `image_comparison_at` - Timestamp
+
+## 🎨 UI Features
+
+The "版本对比" tab shows:
+- ✅ Status badge (with color coding)
+- ✅ Comparison timestamp
+- ✅ Side-by-side images (previous vs current)
+- ✅ Diff image with marked differences
+- ✅ Detailed difference table
+- ✅ Similarity score percentage
+- ✅ Error/skip reasons (if applicable)
+
+## 🐛 Troubleshooting
+
+### Comparison not triggering?
+- Check: Is approval in `submitter_revisions` step?
+- Check: Are there image materials?
+- Check: View logs for trigger message
+
+### Comparison failed?
+- Check: AI service URL and API key
+- Check: Network connectivity
+- Check: Error field on material record
+- Check: System logs for details
+
+### UI not showing?
+- Check: Is material an image type?
+- Check: Does `image_comparison_status` exist?
+- Refresh page and clear cache
+
+## 📚 Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [IMAGE_COMPARISON_FEATURE.md](./IMAGE_COMPARISON_FEATURE.md) | Complete feature guide |
+| [IMAGE_COMPARISON_IMPLEMENTATION.md](../../IMAGE_COMPARISON_IMPLEMENTATION.md) | Implementation summary |
+| [IMAGE_COMPARISON_ARCHITECTURE_DIAGRAMS.md](../../IMAGE_COMPARISON_ARCHITECTURE_DIAGRAMS.md) | Visual diagrams |
+
+## 🧪 Testing
+
+Run the test suite:
+```bash
+cd steedos-packages/content-review
+node test_image_comparison.js
+```
+
+Expected output:
+```
+✓ Modified submission detection: PASS
+✓ Image material filtering: PASS
+✓ Version retrieval: PASS
+✓ Data preparation: PASS
+All tests passed!
+```
+
+## 🔍 Code Examples
+
+### Import and Use
+```typescript
+import { 
+  getImageMaterials, 
+  processBulkImageComparison,
+  triggerImageComparisonAsync 
+} from './methods/image_comparison';
+
+// Get all image materials in an approval
+const images = await getImageMaterials(ctx, approvalId);
+
+// Process all images (sync)
+const result = await processBulkImageComparison(ctx, approvalId);
+
+// Trigger async (recommended)
+await triggerImageComparisonAsync(ctx, approvalId);
+```
+
+### Check Results
+```typescript
+const material = await ctx.getObject('pepsico_material').findOne(materialId);
+
+if (material.image_comparison_status === 'completed') {
+  const result = material.image_comparison_result;
+  console.log('Similarity:', result.similarity_score);
+  console.log('Differences:', result.differences);
+}
+```
+
+## 🎯 Status Meanings
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Comparison queued or in progress |
+| `completed` | Successfully compared |
+| `skipped` | No previous version to compare |
+| `failed` | Error during comparison |
+| `partial` | Some materials succeeded, some failed (batch only) |
+
+## 🚦 Next Steps
+
+1. ✅ Code is complete and committed
+2. ⏳ Deploy AI comparison service
+3. ⏳ Configure environment variables
+4. ⏳ Test in staging
+5. ⏳ User acceptance testing
+6. ⏳ Production deployment
+7. ⏳ Monitor and optimize
+
+## 💡 Tips
+
+- **Performance**: Async processing means no workflow delay
+- **Scalability**: Can handle many images in one approval
+- **Reliability**: Individual failures don't affect others
+- **Debugging**: Check logs with approval/material IDs
+- **Recovery**: Use manual trigger API if needed
+
+## 🆘 Support
+
+Need help? Check:
+1. System logs with approval/material ID
+2. Material record's error fields
+3. AI service health status
+4. Network connectivity
+5. Documentation files above
+
+## 📝 License
+
+Part of Steedos PepsiCo Content Review System
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-02-05  
+**Status**: ✅ Production Ready (pending AI service)