test(api): 更新API客户端契约测试以符合YAML规范

- 更新登录响应模拟数据以匹配真实的AppLoginVo结构
- 添加认证客户端租户和授权字段验证
- 增加操作码枚举验证测试用例
- 移除对旧token别名的兼容性测试
- 修复测试用例中的短信验证码长度一致性问题
- 更新区域接口路径为PC专用路径
- 调整分片上传接口参数以符合新契约定义

refactor(api): 重构API客户端实现以严格遵循YAML契约

- 添加认证操作码和短信操作码枚举验证
- 实现严格的token响应解析只接受access_token字段
- 使用pickDefined函数过滤请求体中未定义的字段
- 重构认证接口参数映射以符合契约定义
- 更新区域接口路径为PC专用路径/genealogy/pc/region/*
- 优化分片上传接口参数结构与契约保持一致
- 添加操作码枚举验证函数toRequiredOperationCode
- 实现请求体字段选择性提取功能

feat(auth): 优化认证页面的验证码处理流程

- 添加takeCaptchaToken函数用于一次性获取验证码票据
- 更新短信验证码长度验证从4-6位改为精确4位
- 在登录和密码重置流程中集成验证码票据处理
- 修复验证码发送后票据清理逻辑
- 更新HTML模板中的验证码输入字段属性

chore(config): 提取常量配置并扩展配置对象结构

- 将客户端ID、租户ID和令牌键提取为常量
- 扩展配置对象返回客户端配置信息
- 更新配置测试用例以验证新增配置项

docs(planning): 更新PC接口对接规划文档

- 更新契约源说明以反映YAML冻结契约
- 添加YAML与在线Apifox复核对比内容
- 更新阻断项状态表格
- 修订登录响应token字段处理规范
- 更新文件上传和行政区划接口规范说明

style(profile): 优化相册管理页面的文件上传交互

- 将封面和照片OSS ID输入改为隐藏字段
- 添加文件选择标签以改善用户体验
- 移除手动输入OSS ID的选项保持界面简洁

public/js/upload-pages.js

@@ -14,6 +14,8 @@
   'use strict';
 
   var documentRef = root.document;
+  var DEFAULT_CHUNK_SIZE = 4 * 1024 * 1024;
+  var activeUploads = {};
 
   function normalizeUploadResult(data) {
     var source = data || {};
@@ -28,7 +30,7 @@
   }
 
   function buildUploadStatus(fileName, ossId) {
-    return (fileName || '文件') + ' 上传完成，OSS ID：' + ossId;
+    return (fileName || '文件') + (ossId ? ' 上传完成' : ' 上传失败');
   }
 
   function getUploadMode() {
@@ -71,27 +73,159 @@
     if (root.alert) root.alert(message);
   }
 
-  function uploadFileForPage(api, file) {
-    // 当前初始化响应未展开 uploadId、instant 与 OSS 字段，不能猜测分片闭环。
-    if (!api || !file) return Promise.reject(new Error('请选择文件'));
-    return Promise.reject(new Error('当前 PC 文件上传响应未定义头像回填字段，暂不能上传头像'));
+  function createUploadId() {
+    if (root.crypto && typeof root.crypto.randomUUID === 'function') {
+      return 'pc-' + root.crypto.randomUUID();
+    }
+    return 'pc-' + Date.now() + '-' + Math.random().toString(16).slice(2);
+  }
+
+  function arrayBufferToBinary(buffer) {
+    var bytes = new Uint8Array(buffer);
+    var parts = [];
+    var offset;
+
+    for (offset = 0; offset < bytes.length; offset += 8192) {
+      parts.push(String.fromCharCode.apply(null, bytes.subarray(offset, offset + 8192)));
+    }
+    return parts.join('');
+  }
+
+  async function hashBlob(blob) {
+    var buffer;
+
+    if (!blob || typeof blob.arrayBuffer !== 'function') throw new Error('当前浏览器无法读取文件');
+    if (typeof root.hex_md5 !== 'function') throw new Error('缺少文件 MD5 组件');
+    buffer = await blob.arrayBuffer();
+    return root.hex_md5(arrayBufferToBinary(buffer));
+  }
+
+  async function retry(operation, maxRetries) {
+    var attempt = 0;
+
+    while (true) {
+      try {
+        return await operation();
+      } catch (error) {
+        if (attempt >= maxRetries) throw error;
+        attempt += 1;
+      }
+    }
+  }
+
+  async function performResumableUpload(api, file, options) {
+    var settings = options || {};
+    var chunkSize = settings.chunkSize || DEFAULT_CHUNK_SIZE;
+    var totalChunks = Math.ceil(file.size / chunkSize);
+    var calculateHash = settings.hashBlob || hashBlob;
+    var fileMd5 = await calculateHash(file);
+    var initBody = {
+      uploadId: settings.uploadId || createUploadId(),
+      fileName: file.name,
+      fileMd5: fileMd5,
+      totalSize: file.size,
+      totalChunks: totalChunks,
+      chunkSize: chunkSize,
+      contentType: file.type || 'application/octet-stream'
+    };
+    var initResult = await api.initResumableUpload(initBody);
+    var uploadedChunks = Array.isArray(initResult && initResult.uploadedChunks)
+      ? initResult.uploadedChunks.slice()
+      : [];
+    var uploadedLookup = {};
+    var serverUploadId;
+    var chunkIndex;
+
+    if (initResult && initResult.instant) return normalizeUploadResult(initResult);
+    serverUploadId = initResult && initResult.uploadId || initBody.uploadId;
+    uploadedChunks.forEach(function (index) {
+      uploadedLookup[Number(index)] = true;
+    });
+    if (settings.onProgress) {
+      settings.onProgress({ uploadedChunks: uploadedChunks.length, totalChunks: totalChunks });
+    }
+
+    for (chunkIndex = 0; chunkIndex < totalChunks; chunkIndex += 1) {
+      if (uploadedLookup[chunkIndex]) continue;
+
+      await (async function (index) {
+        var start = index * chunkSize;
+        var chunk = file.slice(start, Math.min(start + chunkSize, file.size));
+        var chunkMd5 = await calculateHash(chunk);
+
+        await retry(function () {
+          return api.uploadResumableChunk({
+            uploadId: serverUploadId,
+            chunkIndex: index,
+            chunkMd5: chunkMd5,
+            file: chunk
+          });
+        }, settings.maxRetries === undefined ? 2 : settings.maxRetries);
+        uploadedChunks.push(index);
+        if (settings.onProgress) {
+          settings.onProgress({ uploadedChunks: uploadedChunks.length, totalChunks: totalChunks });
+        }
+      })(chunkIndex);
+    }
+
+    return normalizeUploadResult(await api.completeResumableUpload({
+      uploadId: serverUploadId,
+      fileName: file.name,
+      fileMd5: fileMd5,
+      totalSize: file.size,
+      totalChunks: totalChunks
+    }));
+  }
+
+  function uploadFileForPage(api, file, options) {
+    var key;
+    var promise;
+
+    if (!api || !file || !file.name || !Number(file.size)) return Promise.reject(new Error('请选择文件'));
+    key = [file.name, file.size, file.lastModified || 0].join(':');
+    if (activeUploads[key]) return activeUploads[key];
+
+    promise = performResumableUpload(api, file, options).finally(function () {
+      delete activeUploads[key];
+    });
+    activeUploads[key] = promise;
+    return promise;
+  }
+
+  function mergeUploadTargetValue(currentValue, ossId, multiple) {
+    var current = String(currentValue || '').trim();
+    var next = String(ossId || '').trim();
+
+    if (!multiple || !current) return next;
+    return current.split(',').concat(next).filter(Boolean).join(',');
   }
 
   async function uploadFromInput(input) {
     var api = getApi();
-    var file = input.files && input.files[0];
+    var files = Array.prototype.slice.call(input.files || []);
     var target = query(input.getAttribute('data-upload-target'));
     var status = query(input.getAttribute('data-upload-status'));
+    var multiple = input.getAttribute('data-upload-multiple') === 'true';
     var result;
+    var index;
 
-    if (!file || !target || redirectUnauthorized(api)) return;
+    if (!files.length || !target || redirectUnauthorized(api)) return;
     input.disabled = true;
 
     try {
-      result = normalizeUploadResult(await uploadFileForPage(api, file));
-      if (!result.ossId) throw new Error('上传响应缺少 ossId');
-      target.value = result.ossId;
-      if (status) status.textContent = buildUploadStatus(result.fileName || file.name, result.ossId);
+      for (index = 0; index < files.length; index += 1) {
+        if (status) status.textContent = files[index].name + ' 正在上传...';
+        result = normalizeUploadResult(await uploadFileForPage(api, files[index], {
+          onProgress: function (progress) {
+            if (status) {
+              status.textContent = '正在上传 ' + progress.uploadedChunks + '/' + progress.totalChunks + ' 分片';
+            }
+          }
+        }));
+        if (!result.ossId) throw new Error('上传响应缺少 ossId');
+        target.value = mergeUploadTargetValue(target.value, result.ossId, multiple);
+        if (status) status.textContent = buildUploadStatus(result.fileName || files[index].name, result.ossId);
+      }
     } catch (error) {
       if (redirectUnauthorized(api, error)) return;
       if (status) status.textContent = error.message || '上传失败';
@@ -121,7 +255,9 @@
     normalizeUploadResult: normalizeUploadResult,
     buildUploadStatus: buildUploadStatus,
     getUploadMode: getUploadMode,
+    hashBlob: hashBlob,
     uploadFileForPage: uploadFileForPage,
+    mergeUploadTargetValue: mergeUploadTargetValue,
     shouldRedirectToLogin: shouldRedirectToLogin,
     init: init
   };