上传照片（服务端）

sequenceDiagram
    autonumber
    title Shotmeld 照片上传与智能处理流程

    participant Client as 客户端<br>(Web / App)
    participant Server as 服务端<br>(主控协调)
    participant OSSUploader as OSS同步模块<br>(异步上传)
    participant EXIFProcessor as EXIF处理模块<br>(坐标+逆地理)
    participant AITagger as AI标签模块<br>(图像识别)
    participant AliyunOSS as 阿里云OSS<br>(原图存储)
    participant GaodeAPI as 高德API<br>(逆地理编码)
    participant ImageAI as 阿里云图像识别API<br>(智能打标)

    Client ->> Server: 1. 上传图片 (multipart/form-data)
    activate Server
    Server ->> Server: 2. 关联相册 + 生成缩略图<br>快速响应准备
    Server -->> Client: 3. 返回“上传成功”
    deactivate Server

    Note over Client,Server: 第3步返回的图片URL指向<strong>服务端本地存储</strong>，<br>由服务端直接提供文件访问，确保用户“秒级预览”

    par OSS 上传流程
        Server ->> OSSUploader: 4. 异步：上传原图至OSS
        activate OSSUploader
        OSSUploader ->> AliyunOSS: 5. 上传原始图片
        AliyunOSS -->> OSSUploader: 6. 返回OSS URL
        OSSUploader ->> Server: 7. 更新数据库：图片URL切换至OSS地址
        deactivate OSSUploader
    and EXIF 解析流程
        Server ->> EXIFProcessor: 8. 异步：解析EXIF元数据
        activate EXIFProcessor
        EXIFProcessor ->> EXIFProcessor: 9. 火星坐标 → WGS84<br>坐标纠偏
        EXIFProcessor ->> GaodeAPI: 10. 请求逆地理编码<br>经纬度 → 省市区街道
        GaodeAPI -->> EXIFProcessor: 11. 返回结构化地址
        EXIFProcessor ->> Server: 12. 更新地理标签与拍摄地点
        deactivate EXIFProcessor
    and AI 标签识别流程
        Server ->> AITagger: 13. 异步：图像内容识别
        activate AITagger
        AITagger ->> ImageAI: 14. 提交图片URL<br>物体/场景/OCR识别
        ImageAI -->> AITagger: 15. 返回标签列表<br>如：“猫, 窗户, 阳光”
        AITagger ->> Server: 16. 保存AI标签至数据库
        deactivate AITagger
    end

    Note over Server,AliyunOSS: 第7步完成后，<strong>所有图片访问切换至阿里云OSS</strong>，<br>服务端释放存储与带宽压力，实现“前端快响应，后端稳迁移”

    Note right of Server: 最终成果：<br>• 图片通过OSS访问<br>• 带地理位置<br>• 带AI智能标签<br>• 支持搜索与推荐

/**
 * 将GPS（WGS84）坐标转换为高德（GCJ-02）坐标系并获取位置名称
 * @param {number} longitude - GPS经度
 * @param {number} latitude - GPS纬度
 * @returns {Promise<{longitude: number, latitude: number, name: string|null}>} - 包含高德坐标和位置名称的对象
 */
async function convertGPSToAMap(originalLongitude, originalLatitude) {
  try {
    // 验证输入坐标的有效性
    if (typeof originalLongitude !== 'number' || typeof originalLatitude !== 'number' ||
        isNaN(originalLongitude) || isNaN(originalLatitude)) {
      throw new Error('无效的坐标值');
    }

    // 确保有API Key
    if (!config.AMAP_KEY) {
      console.warn('未配置高德地图API Key，无法进行坐标转换和逆地理编码');
      return { longitude: originalLongitude, latitude: originalLatitude, name: null };
    }

    let amapLongitude = originalLongitude;
    let amapLatitude = originalLatitude;
    let locationName = null;

    // 1. 坐标转换 (WGS84 to GCJ-02)
    const convertUrl = `https://restapi.amap.com/v3/assistant/coordinate/convert?key=${config.AMAP_KEY}&locations=${originalLongitude},${originalLatitude}&coordsys=gps`;
    try {
      const convertResponse = await axios.get(convertUrl);
      if (convertResponse.data && convertResponse.data.status === '1' && convertResponse.data.locations) {
        const [lon, lat] = convertResponse.data.locations.split(',');
        amapLongitude = parseFloat(lon);
        amapLatitude = parseFloat(lat);
      } else {
        console.error('高德地图坐标转换API返回错误:', convertResponse.data);
      }
    } catch (convertError) {
      console.error('高德地图坐标转换失败:', convertError);
    }
    
    // 2. 逆地理编码获取位置名称 (使用转换后的或原始的高德坐标)
    const locationStringForRegeo = `${amapLongitude},${amapLatitude}`;
    const regeoUrl = `https://restapi.amap.com/v3/geocode/regeo?key=${config.AMAP_KEY}&location=${locationStringForRegeo}&extensions=base`;
    
    try {
        const regeoResponse = await axios.get(regeoUrl);
        if (regeoResponse.data && regeoResponse.data.status === '1' && regeoResponse.data.regeocode) {
          locationName = regeoResponse.data.regeocode.formatted_address;
        } else {
          console.error('高德地图逆地理编码API返回错误:', regeoResponse.data);
        }
    } catch (regeoError) {
        console.error('高德地图逆地理编码失败:', regeoError);
    }

    // 返回转换后的高德经纬度和获取到的位置名称
    return {
      longitude: amapLongitude,
      latitude: amapLatitude,
      name: locationName
    };

  } catch (error) {
    console.error('获取位置名称或坐标转换主流程失败:', error);
    return { longitude: originalLongitude, latitude: originalLatitude, name: null }; 
  }
}