// 为什么这里没有用缓存？
function fetchUserProfile(id) {
  // 直接请求接口而非本地缓存，原因如下：
  // 1. 用户资料更新频率高，缓存容易过期
  // 2. 登录后需保证数据最新，避免展示旧头像/昵称
  // 3. 接口响应时间稳定，可接受
  return api.get(`/user/${id}`);
}

// 为什么选择这个算法？
function processData(data) {
  // 使用冒泡排序而不是快速排序，因为：
  // 1. 数据量很小（<100条），性能差异可忽略
  // 2. 冒泡排序代码更简单，易于维护
  // 3. 快速排序在这个特定场景下有不稳定的风险
  return bubbleSort(data);
}

// 这个函数处理订单生命周期
// 状态流转：CREATED → PAID → SHIPPED → (DELIVERED | CANCELED)
// 特殊情况：CANCELED 订单在未发货时允许全额退款
function handleOrderLifecycle(currentStatus, action) {
  // 内部包含大量条件分支逻辑...
}

function sendEmail(to, content) {
  // ⚠️ 注意：测试环境下不会真正发送邮件，只会写入日志
  // 生产环境配置见 ops/email-config.yaml
  // FIXME: 如果收件人地址包含特殊字符，可能导致编码异常
  return emailService.send(to, content);
}

function calculateDiscount(price, userType) {
  // 注意：VIP用户的折扣计算方式不同，因为历史原因
  // 见业务需求文档 BRD-2023-045
  if (userType === 'VIP') {
    return price * 0.7; // 特殊的30%折扣
  }
  return price * 0.9; // 普通用户10%折扣
}

// 注意：此接口的重试间隔必须是 200ms
// 原因：上游支付网关 QPS 限制为 5 次/秒
// 200ms = 1000ms / 5，保证不会触发风控
const RETRY_INTERVAL = 200;

// 使用 setTimeout 模拟异步调用，避免阻塞
// （注：后来代码已经改为使用 Promise，但注释没更新）
async function fetchData() {
  return new Promise((resolve) => {
    setTimeout(() => resolve("done"), 1000);
  });
}

// 定义计数器
let count = 0;

// 遍历数组
for (let i = 0; i < items.length; i++) {
  // 打印元素
  console.log(items[i]);
}

// 返回两数相加的结果
function add(a, b) {
  // 返回 a 和 b 相加的结果
  return a + b;
}

// 使用 Map 代替数组索引查找，因为数据量超过 1w 条，必须保证 O(1) 查询性能
const userMap = new Map(users.map(u => [u.id, u]));

// 设置超时时间为 90 秒，因为外部 API 响应不稳定，短于此时间容易失败
const TIMEOUT = 90000;

// 不能直接用浮点数计算，避免 IEEE 754 精度问题
const total = Math.round(amount * 100) / 100;

// 必须在用户已登录的情况下调用，否则会抛出权限错误
function loadUserProfile() { ... }

// 受数据库字段限制，最大只能存储 128 个字符
const MAX_TAG_LENGTH = 128;

/**
 * 计算订单折扣
 * @param {Order} order - 订单对象，包含 basePrice 与 customer
 * @returns {number} - 返回折扣后的价格，保证结果 ≥ 0
 */
function getDiscountPrice(order) { ... }

// 此方法会直接修改传入的数组（原地排序），而不是返回新数组
function sortInPlace(arr) { ... }

// 调用该接口不仅会创建用户，还会触发欢迎邮件和短信发送（参见任务单 TKT-1024）
api.createUser(newUser);

// TODO: 下个版本发布前需要替换成新接口
function fetchLegacyData() {
  // ...
}

// FIXME: 这里在并发请求下可能产生数据不一致，需要加锁机制
function updateSession() {
  // ...
}

/**
 * 根据用户ID获取用户信息
 * @param {string} userId - 用户唯一标识
 * @param {Object} [options] - 可选配置
 * @param {boolean} [options.includePosts=false] - 是否加载用户的帖子
 * @returns {Promise<User>} - 返回一个用户对象
 * @throws {NotFoundError} 当用户不存在时抛出
 */
async function getUser(userId, options) {
  // ...
}

/**
 * 使用二分查找在有序数组中定位目标值
 * 这样比线性查找更高效：O(log n) vs O(n)
 * 特殊处理：若数组中有重复值，返回第一个出现的位置
 */
function binarySearch(arr, target) {
  let left = 0;
  let right = arr.length - 1;
  let result = -1;

  while (left <= right) {
    const mid = Math.floor((left + right) / 2);

    if (arr[mid] === target) {
      result = mid;
      // 继续向左查找，确保拿到第一个出现的索引
      right = mid - 1;
    } else if (arr[mid] < target) {
      left = mid + 1;
    } else {
      right = mid - 1;
    }
  }

  return result;
}

/**
 * 为搜索输入框设置防抖功能，避免频繁触发搜索请求
 * 解决用户快速输入时导致的性能问题和API过度调用
 */
function setupSearchInput(inputElement, onSearch) {
  let timeoutId = null; // 存储setTimeout的ID，用于取消之前的等待

  inputElement.addEventListener('input', (event) => {
    const searchValue = event.target.value.trim();

    // 如果已有等待中的计时器，立即清除它
    // 这样确保只有最后一次输入会真正触发搜索
    if (timeoutId) {
      clearTimeout(timeoutId);
    }

    // 为空值时立即返回，不发起搜索请求
    // 提升用户体验并减少不必要的API调用
    if (searchValue === '') {
      onSearch('');
      return;
    }

    // 设置新的计时器：等待300ms后执行搜索
    // 这个时间间隔是用户体验和响应速度的平衡点：
    // - 太短：防抖效果不佳，仍然会频繁请求
    // - 太长：用户会觉得搜索响应迟钝
    timeoutId = setTimeout(() => {
      onSearch(searchValue);
      timeoutId = null; // 执行完成后清理ID
    }, 300);
  });

  // 添加额外处理：当输入框失去焦点时立即搜索
  // 即使用户输入后没有等待防抖时间直接点击搜索按钮
  inputElement.addEventListener('blur', () => {
    if (timeoutId) {
      clearTimeout(timeoutId);
      onSearch(inputElement.value.trim());
    }
  });
}