refactor(offline-booking): 优化离线预约缓存刷新逻辑

重构刷新逻辑，明确 force 参数的作用并添加注释说明
过滤已完成状态的记录以提高缓存效率

@@ -149,14 +149,25 @@ export const build_offline_qr_list = (bill) => {
  * 刷新离线预约记录缓存
  * 刷新离线预约记录缓存
  * - 仅在有授权且网络可用时调用
  * - 仅在有授权且网络可用时调用
  * - 成功后将数据存储到本地缓存（key: OFFLINE_BOOKING_DATA）
  * - 成功后将数据存储到本地缓存（key: OFFLINE_BOOKING_DATA）
- * @param {boolean} force - 是否强制刷新，默认为 false
+ * @param {boolean} force - 是否强制刷新，默认为 false. force 参数的核心作用是控制是否忽略 “正在进行的缓存请求”, 管的是 “是否允许重复发起请求”，不管 “请求能不能成功执行缓存”。
  * @returns {Promise<void>}
  * @returns {Promise<void>}
  */
  */
 export const refresh_offline_booking_cache = async ({ force = false } = {}) => {
 export const refresh_offline_booking_cache = async ({ force = false } = {}) => {
+    // 1. 检查是否有正在进行的刷新请求
+    // 2. 如果有，且 force 为 false，则直接返回该 Promise
+    // 3. 如果没有，或 force 为 true，则继续执行刷新逻辑
+    // 4. 刷新完成后，将结果存储到本地缓存（key: OFFLINE_BOOKING_CACHE_KEY）
+    // 5. 返回刷新结果 Promise
+
     if (!hasAuth()) return { code: 0, data: null, msg: '未授权' }
     if (!hasAuth()) return { code: 0, data: null, msg: '未授权' }
 
 
     if (refresh_promise && !force) return refresh_promise
     if (refresh_promise && !force) return refresh_promise
 
 
+    // 核心逻辑：
+    // 1. 立刻触发异步逻辑，同时捕获 Promise 状态
+    // 2. 保证 refresh_promise 始终是 Promise 类型，适配 await
+    // 3. 隔离作用域，避免变量污染
+    // 加 () 是为了 “让异步逻辑立刻跑起来”，并把 “跑的结果（Promise）” 存起来，供后续复用和等待。
     refresh_promise = (async () => {
     refresh_promise = (async () => {
         const network_type = await get_network_type()
         const network_type = await get_network_type()
         if (!is_usable_network(network_type)) {
         if (!is_usable_network(network_type)) {
@@ -165,6 +176,7 @@ export const refresh_offline_booking_cache = async ({ force = false } = {}) => {
 
 
         const { code, data, msg } = await billOfflineAllAPI()
         const { code, data, msg } = await billOfflineAllAPI()
         if (code && Array.isArray(data)) {
         if (code && Array.isArray(data)) {
+            // 过滤出状态为3（已完成）的记录
             const normalized = data.map(normalize_bill_item).filter((item) => item && item.pay_id && item.status == 3)
             const normalized = data.map(normalize_bill_item).filter((item) => item && item.pay_id && item.status == 3)
             if (normalized.length > 0) {
             if (normalized.length > 0) {
                 Taro.setStorageSync(OFFLINE_BOOKING_CACHE_KEY, normalized)
                 Taro.setStorageSync(OFFLINE_BOOKING_CACHE_KEY, normalized)

@@ -57,7 +57,6 @@ const normalize_options = (options) => {
  * @param {Object} options 选项
  * @param {Object} options 选项
  * @param {Boolean} options.force 是否强制刷新
  * @param {Boolean} options.force 是否强制刷新
  */
  */
-
 const run_refresh_once = async (options) => {
 const run_refresh_once = async (options) => {
     if (polling_state.in_flight) return // 核心防重复——如果正在刷新，直接返回
     if (polling_state.in_flight) return // 核心防重复——如果正在刷新，直接返回
     // 标记为“正在刷新”
     // 标记为“正在刷新”