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/auth-pages.js

@@ -151,6 +151,14 @@
     if (field) field.value = '';
   }
 
+  function takeCaptchaToken(form) {
+    var field = query('input[name="validToken"]', form);
+    var token = field && field.value || '';
+
+    if (field) field.value = '';
+    return token;
+  }
+
   function startSmsCooldown(button) {
     var originalText;
     var remaining = SMS_CODE_COOLDOWN_SECONDS;
@@ -202,7 +210,7 @@
   }
 
   function isSmsCode(value) {
-    return /^\d{4,6}$/.test(value || '');
+    return /^\d{4}$/.test(value || '');
   }
 
   function validatePassword(value, message) {
@@ -315,6 +323,7 @@
     if (!validateBeforeSubmit('login', values)) return;
     if (!await ensureCaptcha(form, getFormCaptchaOperation(form, 'login'), values.phone)) return;
     values = readForm(form);
+    values.validToken = takeCaptchaToken(form);
     setBusy(button, true);
     try {
       await api.login(buildLoginBody(values));
@@ -384,6 +393,7 @@
     if (!await ensureCaptcha(form, operationCode, values.phone)) return;
 
     values = readForm(form);
+    values.validToken = takeCaptchaToken(form);
 
     setBusy(button, true);
     try {
@@ -391,12 +401,10 @@
         phone: values.phone,
         validToken: values.validToken || ''
       });
-      clearCaptchaToken(form);
       showMessage('验证码已发送');
       setBusy(button, false);
       startSmsCooldown(button);
     } catch (error) {
-      clearCaptchaToken(form);
       showMessage(error.message || '验证码发送失败');
       setBusy(button, false);
     }
@@ -476,6 +484,7 @@
     buildRegisterBody: buildRegisterBody,
     buildPasswordResetBody: buildPasswordResetBody,
     clearCaptchaToken: clearCaptchaToken,
+    takeCaptchaToken: takeCaptchaToken,
     startSmsCooldown: startSmsCooldown,
     getCaptchaOperation: getCaptchaOperation,
     getFormCaptchaOperation: getFormCaptchaOperation,

public/js/profile-pages.js

@@ -58,17 +58,28 @@
   function buildProfileUpdateBody(values) {
     // 字段名称严格对应 PC YAML 里的 ProfileUpdateBody。
     var source = values || {};
+    var body = {};
+    var avatar = trimOrUndefined(source.avatar);
 
-    return {
-      nickName: trimOrUndefined(source.nickName),
-      // int64 在浏览器中必须保留字符串，避免 Number 转换丢失精度。
-      avatarOssId: trimOrUndefined(source.avatarOssId),
-      sex: trimOrUndefined(source.sex),
-      birthday: trimOrUndefined(source.birthday),
-      provinceCode: trimOrUndefined(source.provinceCode),
-      cityCode: trimOrUndefined(source.cityCode),
-      districtCode: trimOrUndefined(source.districtCode)
-    };
+    [
+      'nickName',
+      'realName',
+      'sex',
+      'birthday',
+      'email'
+    ].forEach(function (field) {
+      var value = trimOrUndefined(source[field]);
+
+      if (value !== undefined) body[field] = value;
+    });
+
+    if (avatar !== undefined) {
+      if (!/^\d+$/.test(avatar)) throw new Error('头像 OSS ID 必须是整数');
+      // YAML 将 avatar 标成 int64，但其示例已超过 JS 安全整数；浏览器按十进制字符串保留精度。
+      body.avatar = avatar;
+    }
+
+    return body;
   }
 
   function getApi() {

public/js/region-pages.js

@@ -81,22 +81,6 @@
     return source.districtCode || source.cityCode || source.provinceCode || '';
   }
 
-  function trimOrUndefined(value) {
-    var text = String(value === undefined || value === null ? '' : value).trim();
-
-    return text || undefined;
-  }
-
-  function buildProfileRegionBody(values) {
-    var source = values || {};
-
-    return {
-      provinceCode: trimOrUndefined(source.provinceCode),
-      cityCode: trimOrUndefined(source.cityCode),
-      districtCode: trimOrUndefined(source.districtCode)
-    };
-  }
-
   function getApi() {
     return root.GenealogyApi && root.GenealogyApi.defaultClient;
   }
@@ -354,49 +338,6 @@
     }
   }
 
-  async function submitProfileRegion(form) {
-    var api = getApi();
-    var values = getFormValues(form);
-    var body = buildProfileRegionBody(values);
-    var status = query('[data-region-profile-status]', form);
-
-    if (redirectUnauthorized(api)) return;
-    if (!body.provinceCode) {
-      showMessage('请选择省份');
-      return;
-    }
-
-    try {
-      setSubmitting(form, true);
-      if (status) status.textContent = '保存中...';
-      await api.updateProfile(body);
-      if (status) status.textContent = '已保存';
-      showMessage('地区资料已保存');
-      if (root.ProfilePages && root.ProfilePages.reloadProfile) await root.ProfilePages.reloadProfile();
-    } catch (error) {
-      if (redirectUnauthorized(api, error)) return;
-      if (status) status.textContent = '保存失败';
-      showMessage(error.message || '地区资料保存失败');
-    } finally {
-      setSubmitting(form, false);
-    }
-  }
-
-  function setSubmitting(form, isSubmitting) {
-    queryAll('button[type="submit"]', form).forEach(function (button) {
-      button.disabled = isSubmitting;
-    });
-  }
-
-  function bindProfileForms() {
-    queryAll('[data-region-profile-form]').forEach(function (form) {
-      form.addEventListener('submit', function (event) {
-        event.preventDefault();
-        submitProfileRegion(form);
-      });
-    });
-  }
-
   function bindSearchForms() {
     queryAll('[data-region-search-form]').forEach(function (form) {
       form.addEventListener('submit', function (event) {
@@ -425,7 +366,6 @@
     queryAll('[data-region-picker]').forEach(function (picker) {
       initPicker(picker).catch(handlePickerError);
     });
-    bindProfileForms();
     bindSearchForms();
   }
 
@@ -438,7 +378,6 @@
     buildPathText: buildPathText,
     buildRegionSelection: buildRegionSelection,
     getFinalRegionCode: getFinalRegionCode,
-    buildProfileRegionBody: buildProfileRegionBody,
     applyRegionSelection: applyRegionSelection,
     applyProfileRegionSelection: applyProfileRegionSelection,
     shouldRedirectToLogin: shouldRedirectToLogin,

public/js/security-pages.js

@@ -69,7 +69,7 @@
   }
 
   function isSmsCode(value) {
-    return /^\d{4,6}$/.test(String(value || '').trim());
+    return /^\d{4}$/.test(String(value || '').trim());
   }
 
   function getApi() {
@@ -161,6 +161,14 @@
     if (field) field.value = '';
   }
 
+  function takeCaptchaToken(form) {
+    var field = query('input[name="validToken"]', form);
+    var token = field && field.value || '';
+
+    if (field) field.value = '';
+    return token;
+  }
+
   function startSmsCooldown(button) {
     var originalText;
     var remaining = SMS_CODE_COOLDOWN_SECONDS;
@@ -308,6 +316,7 @@
     }
     if (!await ensureCaptcha(form, 'phone', values.phone)) return;
     values = getFormValues(form);
+    values.validToken = takeCaptchaToken(form);
     button.disabled = true;
 
     try {
@@ -315,12 +324,10 @@
         phone: values.phone,
         validToken: values.validToken || ''
       });
-      clearCaptchaToken(form);
       showMessage('验证码已发送');
       startSmsCooldown(button);
     } catch (error) {
       if (redirectUnauthorized(api, error)) return;
-      clearCaptchaToken(form);
       showMessage(error.message || '验证码发送失败');
       button.disabled = false;
     }
@@ -338,6 +345,7 @@
     }
     if (!await ensureCaptcha(form, 'deactivate', boundPhone)) return;
     values = getFormValues(form);
+    values.validToken = takeCaptchaToken(form);
     button.disabled = true;
 
     try {
@@ -345,12 +353,10 @@
         phone: boundPhone,
         validToken: values.validToken || ''
       });
-      clearCaptchaToken(form);
       showMessage('验证码已发送');
       startSmsCooldown(button);
     } catch (error) {
       if (redirectUnauthorized(api, error)) return;
-      clearCaptchaToken(form);
       showMessage(error.message || '验证码发送失败');
       button.disabled = false;
     }
@@ -462,6 +468,7 @@
     isDangerConfirmed: isDangerConfirmed,
     isPhone: isPhone,
     isSmsCode: isSmsCode,
+    takeCaptchaToken: takeCaptchaToken,
     shouldRedirectToLogin: shouldRedirectToLogin,
     init: init
   };

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
   };