diff --git a/docs/android_debug_full_fix_guide.md b/docs/android_debug_full_fix_guide.md
new file mode 100644
index 00000000..e385b0be
--- /dev/null
+++ b/docs/android_debug_full_fix_guide.md
@@ -0,0 +1,2980 @@
+# 安卓端调试成功全过程问题总结与修复指南
+
+> **文档类型**：经验沉淀文档（非简单周报）  
+> **维护人**：黄镇堡  
+> **最后更新**：2026-04-20  
+> **项目**：智慧医养 mall（uni-app x）  
+> **分支**：`huangzhenbao-admin`  
+> **AppID**：`__UNI__81482FF`
+
+---
+
+## 目录
+
+1. [文档说明](#1-文档说明)
+2. [时间范围与排查范围](#2-时间范围与排查范围)
+3. [总体结论](#3-总体结论)
+4. [生成本地打包APP资源阶段——UTS 语法问题](#4-生成本地打包app资源阶段uts-语法问题)
+5. [Run 到 Android 端时的报错与修复全过程](#5-run-到-android-端时的报错与修复全过程)
+6. [JS / UTS / Kotlin 语义差异总结](#6-js--uts--kotlin-语义差异总结)
+7. [Android 适配与页面运行问题总结](#7-android-适配与页面运行问题总结)
+8. [额外发现的重要隐藏问题](#8-额外发现的重要隐藏问题)
+9. [面向后续开发的编码规范清单](#9-面向后续开发的编码规范清单)
+10. [面向后续排查的标准流程清单](#10-面向后续排查的标准流程清单)
+11. [关键文件与关键改动索引](#11-关键文件与关键改动索引)
+12. [结语](#12-结语)
+
+---
+
+## 1. 文档说明
+
+### 1.1 目的
+
+本文档记录了将 uni-app x 商家端项目从"能在小程序/H5运行"推进到"能在 Android 真机正常调试运行"的完整过程。
+
+内容覆盖三个层次：
+
+- **编译层**：HBuilderX 的 UTS → Kotlin 编译阶段报错
+- **构建层**：Android Studio `assembleDebug` 阶段 Kotlin 符号缺失报错
+- **运行层**：APK 安装后页面布局异常、逻辑错误、跳转失败
+
+### 1.2 阅读建议
+
+| 角色                           | 建议阅读章节 |
+| ------------------------------ | ------------ |
+| 新接手本项目的开发者           | 全部         |
+| 遇到 UTS 编译报错              | §4 + §6      |
+| 遇到 Android Studio 构建失败   | §5           |
+| 遇到 Android 页面布局/显示问题 | §7           |
+| 快速查规范                     | §9 + §10     |
+
+### 1.3 项目技术栈
+
+| 层次             | 技术                                     |
+| ---------------- | ---------------------------------------- |
+| 前端框架         | uni-app x（HBuilderX 5.07）              |
+| 前端语言         | UTS（TypeScript 子集，编译为 Kotlin）    |
+| 后端             | Supabase（PostgreSQL + Edge Functions）  |
+| Android 构建     | Android Studio Ladybug + `assembleDebug` |
+| Android 最低版本 | API 21（Android 5.0）                    |
+
+---
+
+## 2. 时间范围与排查范围
+
+### 2.1 时间范围
+
+- **开始**：2026-04-13（开始尝试 Android 本地打包）
+- **完成**：2026-04-20（merchant 端能够在 Android 上正常运行）
+
+### 2.2 关键提交节点
+
+| 提交 Hash               | 提交信息                       | 意义                                            |
+| ----------------------- | ------------------------------ | ----------------------------------------------- |
+| `5ab4789d`              | 保存能够打包成功的版本         | **基线**：首次编译通过，但 Android 运行仍有问题 |
+| `8765e948`              | 小程序条件编译                 | 分离小程序/Android 条件编译                     |
+| `5473f0fc` / `3c256812` | 修复页面展示bug                | 布局适配修复                                    |
+| `f99bd5a7`              | merchant能够在安卓上面进行运行 | **终点**：Android 端完整可用                    |
+
+### 2.3 排查范围
+
+- **页面**：所有 `pages/mall/merchant/**`（共约 30 个页面）+ `pages/user/login`
+- **公共组件**：`components/merchant-tabbar/`、`utils/eventHelpers.uts`（新增）
+- **配置文件**：`pages.json`、`manifest.json`、`fix_kt_files.ps1`
+- **Android 项目**：`D:\Android\Project\mall\app\src\main\java\`
+
+### 2.4 主要错误文件索引
+
+| 文件                                   | 内容                                                |
+| -------------------------------------- | --------------------------------------------------- |
+| `errors_round1_clean.txt`              | A阶段第一轮 UTS 编译错误（清洗版）                  |
+| `errors_round2.txt`                    | A阶段第二轮 UTS 编译错误                            |
+| `D:\Android\Project\mall\报错信息.txt` | B阶段 Android Studio Kotlin 符号缺失错误            |
+| `kotlinc_errors_real.txt`              | 独立 kotlinc 编译尝试的过滤结果（已确认无参考价值） |
+| `build_output_r1_android.txt`          | Android Studio assembleDebug 完整输出               |
+
+---
+
+## 3. 总体结论
+
+### 3.1 根本性结论
+
+**uni-app x 的 UTS 并不是 JavaScript，是一门独立的强类型语言，编译到 Kotlin 后遵循 Kotlin 的严格类型规则。**
+
+大量问题来源于以 JS 习惯写 UTS：
+
+- JS 中合法的表达式（`if (str)`、`a === b`、`obj.field`）在 UTS/Kotlin 中要么报编译错误，要么产生意料之外的运行时行为。
+- CSS 在 Web 浏览器中自动降级处理，在 Android 原生渲染器中不行，无效属性直接被忽略或崩溃。
+
+### 3.2 三阶段问题分布
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│  阶段A：HBuilderX "生成本地打包APP资源"                                  │
+│  工具：HBuilderX 5.07 UTS编译器                                         │
+│  产物：.kt 文件到 unpackage/dist/build/app-android/                     │
+│  问题：UTS 语法错误（13类），编译直接失败                                  │
+├────────────────────────────────────────────────────────────────────────┤
+│  阶段B：Android Studio assembleDebug                                    │
+│  工具：Gradle + Kotlin 编译器                                            │
+│  产物：app-debug.apk                                                    │
+│  问题：Kotlin 符号 unresolved（uni SDK AAR缺失）、=== 运行时语义错误      │
+├────────────────────────────────────────────────────────────────────────┤
+│  阶段C：APK 安装到真机/模拟器运行                                          │
+│  工具：Android 真机                                                      │
+│  问题：布局截断、顶部遮挡、双层TabBar、跳转白屏、无法滚动                   │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.3 问题数量统计
+
+| 阶段             | 问题分类数 | 已解决   | 备注                                                     |
+| ---------------- | ---------- | -------- | -------------------------------------------------------- |
+| A（UTS编译）     | 13类       | 13类     |                                                          |
+| B（Android构建） | 11类       | 9类      | AAR依赖需要补充；getPushClientId待重写                   |
+| C（运行适配）    | 14类       | 14类     | 含flex-direction、scroll-into-view ID、safe-area双重兜底 |
+| 隐藏问题         | 6类        | 6类      | 含AkReq链路模式、sessionUser访问模式                     |
+| **合计**         | **44类**   | **42类** |                                                          |
+
+---
+
+## 4. 生成本地打包APP资源阶段——UTS 语法问题
+
+> **触发场景**：在 HBuilderX 中点击"发行 → 本地打包 → 生成本地打包App资源"，UTS 编译器报错，`.kt` 文件无法生成。
+>
+> **错误来源文件**：`errors_round1_clean.txt`、`errors_round2.txt`
+
+---
+
+### 4.1 非严格布尔条件（最常见）
+
+**错误信息**
+
+```
+condition type mismatch: String but Boolean expected
+condition type mismatch: Int? but Boolean expected
+```
+
+**根因**  
+JavaScript 有 truthy/falsy 机制（空字符串、0、null 均为 falsy），UTS/Kotlin 的 `if` 条件**必须是 Boolean 类型**，不接受其他类型隐式转换。
+
+**错误写法 → 修复写法**
+
+```typescript
+// ❌ JS习惯写法（UTS报错）
+if (this.merchantId) { ... }
+v-if="notice.tag"
+if (item.url) { ... }
+
+// ✅ 修复后
+if (this.merchantId !== '') { ... }
+v-if="notice.tag !== ''"
+if (item.url.length > 0) { ... }
+
+// ❌ 可空类型
+if (result.data) { ... }  // result.data: string | null
+
+// ✅ 修复后
+if (result.data != null && result.data !== '') { ... }
+```
+
+**影响文件**：`profile.uvue`、`index.uvue`、`messages.uvue`、`finance.uvue` 等大量文件。
+
+---
+
+### 4.2 onLoad 参数字段访问
+
+**错误信息**
+
+```
+unresolved reference 'type'
+unresolved reference 'orderId'
+```
+
+**根因**  
+`onLoad(options: any)` 中的 `options` 在 Android UTS 运行时是 `UTSJSONObject`，不能用点访问（`.field`）读取属性；`as any` 掩盖了类型问题，运行时返回 null。
+
+```typescript
+// ❌ 错误写法
+onLoad(options: any) {
+  const type = options.type  // unresolved reference
+  const id = options?.orderId as string
+}
+
+// ✅ 修复写法
+onLoad(options: UTSJSONObject | null) {
+  if (options != null) {
+    const type = options.getString('type') ?? ''
+    const id = options.getString('orderId') ?? ''
+  }
+}
+```
+
+---
+
+### 4.3 `any[]` 泛型不兼容
+
+**错误信息**
+
+```
+type mismatch: inferred type is Array<Any?> but Array<UTSJSONObject> was expected
+```
+
+**根因**  
+UTS 不支持 `any[]`，Android 端数组必须有明确的元素类型。
+
+```typescript
+// ❌ 错误写法
+const rawData = response.data as any[];
+const item = rawData[0] as UTSJSONObject;
+
+// ✅ 修复写法
+const rawData = response.data as Array<UTSJSONObject>;
+const item = rawData[0]; // 已知类型，不需要二次 as
+```
+
+---
+
+### 4.4 UTSJSONObject 点访问
+
+**错误信息**
+
+```
+unresolved reference 'name'
+unresolved reference 'total_sales'
+```
+
+**根因**  
+`UTSJSONObject` 不是普通对象，字段不能用点访问，必须用方法访问。
+
+```typescript
+// ❌ 错误写法
+const name = shopInfo.name;
+const count = shopInfo.total;
+
+// ✅ 修复写法（按值类型选方法）
+const name = shopInfo.getString("name") ?? "";
+const count = shopInfo.getNumber("total") ?? 0;
+const flag = shopInfo.getBoolean("is_active") ?? false;
+const sub = shopInfo.getJSON("address"); // 嵌套对象
+const list = shopInfo.getArray("items"); // 嵌套数组
+```
+
+---
+
+### 4.5 request/uploadFile 回调类型不匹配
+
+**错误信息**
+
+```
+argument type mismatch: AkRequestSuccessResult is not assignable to RequestSuccess<T>
+return type mismatch: AkUploadFileSuccessResult vs UniUploadFileSuccess
+```
+
+**根因**  
+自定义请求封装 `AkReq` 的回调类型（`AkRequestSuccessResult`）与 uni-app x 的标准类型（`RequestSuccess<T>`）不兼容，UTS 强类型检查不允许隐式兼容。
+
+**修复**：对所有使用 `AkReq` 回调的地方，显式声明回调参数类型为项目自定义类型，或用中间变量转换。
+
+---
+
+### 4.6 内联箭头函数事件处理器
+
+**错误信息**
+
+```
+only expressions are allowed here
+```
+
+**根因**  
+UTS 模板中的 `@click` 不支持内联多行逻辑，只能调用命名方法。
+
+```html
+<!-- ❌ 错误写法 -->
+<view @click="() => { doA(); doB() }">
+  <!-- ✅ 修复写法 -->
+  <view @click="handleClick"></view
+></view>
+```
+
+```typescript
+// script 中
+handleClick() {
+  this.doA()
+  this.doB()
+}
+```
+
+---
+
+### 4.7 picker 事件类型错误
+
+**错误信息**
+
+```
+UniPickerChangeEvent does not exist
+argument type mismatch: UniInputEvent vs expected
+```
+
+**根因**  
+`<picker>` 的 `@change` 事件在 uni-app x Android 端使用 `UniInputEvent`（或通用事件接口），`UniPickerChangeEvent` 不存在。
+
+**修复**：提取 `utils/eventHelpers.uts` 工具函数统一处理：
+
+```typescript
+// utils/eventHelpers.uts
+export function getPickerIdx(e: UniInputEvent): number {
+  return parseInt(e.detail.value as string) ?? 0;
+}
+
+export function getInputVal(e: UniInputEvent): string {
+  return (e.detail.value as string) ?? "";
+}
+```
+
+模板使用：
+
+```html
+<picker @change="(e) => { selectedIdx = getPickerIdx(e) }"></picker>
+```
+
+---
+
+### 4.8 对象字面量未声明命名类型
+
+**错误信息**
+
+```
+smart cast to 'String' is impossible
+unresolved reference 'link'
+```
+
+**根因**  
+UTS 的对象字面量需要有已声明的 `type` 类型定义，否则编译器无法推断字段名，smart cast 失败。
+
+```typescript
+// ❌ 错误写法
+const item = { link: '/page', title: '标题' }
+if (item.link) { ... }  // unresolved reference 'link'
+
+// ✅ 修复写法
+type NavItem = { link: string; title: string }
+const item: NavItem = { link: '/page', title: '标题' }
+if (item.link !== '') { ... }
+```
+
+---
+
+### 4.9 `String?` 赋值给 `String`
+
+**错误信息**
+
+```
+assignment type mismatch: String? cannot be assigned to String
+```
+
+**根因**  
+`UTSJSONObject.getString()` 返回 `String?`（可空），不能直接赋给非空 `String` 变量。
+
+```typescript
+// ❌ 错误写法
+const name: string = obj.getString("name"); // String? → String 报错
+
+// ✅ 修复写法
+const name: string = obj.getString("name") ?? "";
+```
+
+---
+
+### 4.10 `Record<string, T>` 类型使用
+
+**错误信息**
+
+```
+unresolved reference 'Record'
+type argument is not within its bounds
+```
+
+**根因**  
+UTS Android 端不支持 `Record<string, T>` 泛型，Kotlin 没有对应的直接映射。
+
+```typescript
+// ❌ 错误写法
+const map: Record<string, number> = {};
+map["key"] = 1;
+
+// ✅ 修复写法（用 if-else 替代或用 UTSJSONObject）
+const map = {} as UTSJSONObject;
+// 或者直接用具体 type 替代 Record
+```
+
+---
+
+### 4.11 函数参数变量名不一致
+
+**错误信息**
+
+```
+unresolved reference 'link'
+unresolved reference 'item'
+```
+
+**根因**  
+事件处理函数的形参名与函数体内使用的变量名不一致（如声明时叫 `item`，调用时传的是 `tip.link`）。
+
+**修复**：参见 §7 问题9——将事件处理器改为只接收基础类型参数，在模板层完成字段提取：
+
+```html
+<!-- 模板：在调用处提取字段 -->
+<view @click="viewDetail(tip.link)">
+  <!-- script：接收 string 类型 -->
+  viewDetail(link: string) { if (link.length > 0) { uni.navigateTo({ url: link
+  }) } }</view
+>
+```
+
+---
+
+### 4.12 可空接收者运算符调用
+
+**错误信息**
+
+```
+operator call is prohibited on nullable receiver: String?
+```
+
+**根因**  
+`String?` 类型不能直接进行字符串运算，需要先用 `?? ''` 确保非空。
+
+```typescript
+// ❌ 错误写法
+const total = price * count; // price: number | null
+
+// ✅ 修复写法
+const total = (price ?? 0) * count;
+```
+
+---
+
+### 4.13 多级可选链类型推断失败
+
+**错误信息**
+
+```
+Cannot infer type for this parameter. Please specify it explicitly.
+Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver
+```
+
+**根因**  
+UTS/Kotlin 不支持像 JS 那样无限级联的可选链（`a?.b?.c?.d`），多级嵌套时编译器无法推断中间类型。
+
+```typescript
+// ❌ 错误写法
+const val = response?.data?.items?.[0]?.name;
+
+// ✅ 修复写法（分步判空）
+if (response != null && response.data != null) {
+  const items = response.data as Array<UTSJSONObject>;
+  if (items.length > 0) {
+    const name = items[0].getString("name") ?? "";
+  }
+}
+```
+
+---
+
+### 4.14 UTS 编译阶段问题汇总表
+
+| #   | 错误类型             | 典型报错                                   | 核心修复                     |
+| --- | -------------------- | ------------------------------------------ | ---------------------------- |
+| 1   | 非布尔条件           | `condition type mismatch: String`          | `!== ''` / `!= null`         |
+| 2   | onLoad参数点访问     | `unresolved reference 'type'`              | `UTSJSONObject.getString()`  |
+| 3   | `any[]` 泛型         | `Array<Any?> vs Array<UTSJSONObject>`      | 明确泛型类型                 |
+| 4   | UTSJSONObject点访问  | `unresolved reference 'name'`              | `.getString()` 等方法        |
+| 5   | 回调类型不匹配       | `AkRequestSuccessResult vs RequestSuccess` | 显式类型声明                 |
+| 6   | 内联箭头函数         | `only expressions are allowed`             | 抽取命名方法                 |
+| 7   | picker事件类型       | `UniPickerChangeEvent does not exist`      | `eventHelpers.uts`           |
+| 8   | 未声明类型对象       | `smart cast impossible`                    | 声明 `type` + `as TypeName`  |
+| 9   | `String?` → `String` | `assignment type mismatch`                 | `?? ''` 兜底                 |
+| 10  | `Record<string,T>`   | `unresolved reference 'Record'`            | 改用具体类型或 UTSJSONObject |
+| 11  | 参数名不一致         | `unresolved reference 'link'`              | 模板层提取基础类型参数       |
+| 12  | 可空运算符           | `prohibited on nullable receiver`          | `?? 0` 后运算                |
+| 13  | 多级可选链           | `Cannot infer type`                        | 分步判空                     |
+
+---
+
+## 5. Run 到 Android 端时的报错与修复全过程
+
+> **触发场景**：UTS 编译通过，生成 `.kt` 文件后，复制到 Android Studio 项目执行 `assembleDebug`，出现 Kotlin 编译错误；或 APK 安装后逻辑行为异常。
+>
+> **错误来源文件**：`D:\Android\Project\mall\报错信息.txt`、`build_output_r1_android.txt`
+
+---
+
+### 5.1 问题链路概览
+
+```
+HBuilderX UTS编译 → .kt文件生成
+        ↓
+复制到 D:\Android\Project\mall\app\src\main\java\
+        ↓
+运行 fix_kt_files.ps1（必须！）
+        ↓
+Android Studio assembleDebug
+        ↓
+adb install / Run
+```
+
+---
+
+### 5.2 问题1：`main.uts` / `App.uvue` 语法错误导致整个编译中止
+
+**现象**：HBuilderX 在处理入口文件时报错，后续所有 `.kt` 文件无法生成。
+
+**根因**：`main.uts` 中有 UTS 不支持的写法，或 `App.uvue` 的 `<script setup>` 函数签名有误。
+
+**修复**：清理 `main.uts` 顶层副作用代码（如 `import` 语句外的立即执行逻辑），确保 `App.uvue` 生命周期函数签名简洁无歧义：
+
+```typescript
+// App.uvue
+onLaunch(opts: OnLaunchOptions | null) {
+  // 不要在此处写复杂初始化逻辑
+}
+```
+
+---
+
+### 5.3 问题2：`@dcloudio/uni-components` 找不到
+
+**现象**
+
+```
+error: cannot find module '@dcloudio/uni-components'
+```
+
+**根因**：HBuilderX 的 `uni_modules` 依赖未正确安装，或版本不兼容。
+
+**修复**：在 HBuilderX 中：菜单 → 工具 → 重新安装依赖（不是 npm install，是 HBuilderX 自身的依赖管理）。若仍失败，重启 HBuilderX 并重新导入项目。
+
+---
+
+### 5.4 问题3：`===` / `!==` 在 Kotlin 中变成引用比较（最关键、影响最大）
+
+**现象**：Android 端登录逻辑判断失效（`loginType.value === 1` 始终返回 false）；角色判断失效（`role === 'merchant'` 永远不匹配）。
+
+**根因**  
+HBuilderX 将 UTS 中的 `===` 直接输出为 Kotlin 的 `===`，但 Kotlin 的 `===` 是**引用相等**（`referenceEquals`），而 JS 的 `===` 是**值相等**（对基础类型）。
+
+| 语言          | `===` 语义                                         |
+| ------------- | -------------------------------------------------- |
+| JavaScript    | 严格值相等（对基础类型与 `==` 等价）               |
+| Kotlin        | 引用相等（`referenceEquals`），等价于 Java 的 `==` |
+| Kotlin 值相等 | 使用 `==`（调用 `equals()`）                       |
+
+```kotlin
+// 生成的 Kotlin 代码（错误）
+if (loginType.value === 1) { ... }   // Kotlin: 引用比较，Number(1) !== 1
+
+// fix_kt_files.ps1 修复后
+if (loginType.value == 1) { ... }    // Kotlin: 值比较，正确
+```
+
+**修复**：`fix_kt_files.ps1` 全局替换：
+
+```powershell
+$c = $c -replace ' === ', ' == '
+$c = $c -replace ' !== ', ' != '
+```
+
+> ⚠️ **这是整个 Android 调试过程中最隐蔽的 bug**。它不产生编译错误，只产生逻辑错误，且很难通过代码审查发现。每次 HBuilderX 重新生成 `.kt` 文件后都必须重新运行此脚本。
+
+---
+
+### 5.5 问题4：登录后跳转到不存在的路由（白屏）
+
+**现象**：商家账号登录成功，Android 页面停在白屏，不跳转。
+
+**根因**：`login.uvue` 中 3 处跳转硬编码到 `admin/homePage/index`，该路由在精简后的 Android `pages.json` 中不存在：
+
+```typescript
+// 错误写法（3处）
+uni.reLaunch({ url: "/pages/mall/admin/homePage/index" });
+```
+
+**修复**：统一改为 Android 端实际存在的路由：
+
+```typescript
+uni.reLaunch({ url: "/pages/mall/merchant/index" });
+```
+
+---
+
+### 5.6 问题5：`onLoad` 参数 Android 端取不到值
+
+**现象**：登录页收不到 URL 中的 `redirect` 参数，登录后无法跳回原页面。
+
+**根因**：旧写法通过 `getCurrentPages()` 读取 options，在 Android 上 `options` 是 `UTSJSONObject`，点访问语法无效：
+
+```typescript
+// 错误写法
+const pages = getCurrentPages() as any[];
+const currentPage = pages[pages.length - 1];
+const opts = currentPage?.options as any;
+const redirect = opts?.redirect as string | null; // Android: 始终 null
+```
+
+**修复**：改用 `onLoad` 钩子 + `UTSJSONObject.getString()`：
+
+```typescript
+import { onLoad } from "@dcloudio/uni-app";
+
+const redirectPath = ref<string>("");
+
+onLoad((opts) => {
+  if (opts != null) {
+    const optsObj = opts as UTSJSONObject;
+    redirectPath.value = optsObj.getString("redirect") ?? "";
+  }
+});
+```
+
+---
+
+### 5.7 问题6：Android Studio Kotlin 符号 unresolved（uni SDK AAR 缺失）
+
+**现象**（来自 `报错信息.txt`）：
+
+```
+error: unresolved reference: uni_showModal
+error: unresolved reference: uni_showLoading
+error: unresolved reference: ShowModalOptions
+error: unresolved reference: UniShowModalResult
+error: unresolved reference: uni_chooseImage
+error: unresolved reference: ChooseImageOptions
+error: unresolved reference: uni_setClipboardData
+```
+
+**根因**：`D:\Android\Project\mall\app\libs\` 中缺少 uni-app SDK 的 AAR 文件，这些 AAR 包含 `uni_showModal` 等原生弹窗 API 的 Kotlin 绑定。
+
+**修复方向**：从 HBuilderX 的本地打包资源包中提取标准 AAR 文件，添加到 `app/libs/` 并在 `build.gradle` 中声明：
+
+```gradle
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
+}
+```
+
+> ⚠️ **注意**：此问题目前尚未完全解决（临时绕过方案：在涉及这些 API 的页面上暂时注释掉相关调用）。这是当前 Android 调试的最后一个未闭合的问题。
+
+---
+
+### 5.8 问题7：BOM（Byte Order Mark）字符污染 Kotlin 文件
+
+**现象**：某些 `.kt` 文件第一行出现 `锘?` 乱码前缀，Kotlin 编译器报错：
+
+```
+error: expecting a top level declaration
+```
+
+**根因**：Windows 环境下，某些编辑器或脚本保存文件时使用 UTF-8 with BOM，BOM 字节（`\xEF\xBB\xBF`）被直接写入文件头，导致 Kotlin 编译器无法识别文件开头。
+
+**修复**：  
+在 `fix_kt_files.ps1` 或单独脚本中，用 `[System.IO.File]::ReadAllText` + `[System.IO.File]::WriteAllText` 重写文件（.NET 默认用无 BOM UTF-8）。或在文件保存时改用 UTF-8 无 BOM 编码。
+
+---
+
+### 5.9 问题8：`fix_kt_files.ps1` 必须在每次 HBuilderX 生成后运行
+
+**现象**：修复过的 `.kt` 文件被重新生成，之前的修复失效，Android Studio 再次报错。
+
+**根因**：每次在 HBuilderX 点"生成本地打包App资源"，都会覆盖 `unpackage/` 目录下的所有 `.kt` 文件，修复脚本的结果被清空。
+
+**当前流程（必须遵守）**：
+
+```
+1. HBuilderX → 发行 → 本地打包 → 生成本地打包App资源
+2. 等待编译完成
+3. 手动将 .kt 文件从 unpackage/ 复制到 Android Studio 项目
+4. 运行：powershell -File D:\Android\Project\mall\fix_kt_files.ps1
+5. Android Studio → Build → assembleDebug
+```
+
+**规范建议**：将步骤 3+4 整合为一个脚本自动执行。
+
+---
+
+### 5.10 fix_kt_files.ps1 完整修复内容
+
+```powershell
+# 修复内容一览：
+# 1. 全局替换 ' === ' → ' == '  （引用比较 → 值比较）
+# 2. 全局替换 ' !== ' → ' != '  （引用不等 → 值不等）
+# 3. 替换跳转路径 /pages/mall/admin/homePage/index → /pages/mall/merchant/index
+# 4. 清除 MerchantTabBar import 和注册引用
+```
+
+---
+
+### 5.11 问题9：login.uvue 深层业务逻辑重构（多问题叠加案例）
+
+**背景**：`login.uvue` 是整个 merchant 流程的入口，其中的 `parseRoleData` 函数是 UTS 改造最复杂的单一案例——它在一个函数内叠加了 4 类 UTS 语法问题。
+
+**问题叠加清单**
+
+| #   | JS 写法                                         | UTS 错误类型                         | 修复                                              |
+| --- | ----------------------------------------------- | ------------------------------------ | ------------------------------------------------- |
+| 1   | 参数类型 `any \| null`                          | 编译器无法推断数组操作               | 定义 `ParseRoleInput` 联合类型                    |
+| 2   | `dataArray.length > 0` 在 `any` 上              | unresolved reference                 | 先 `Array.isArray()` 再 `as Array<UTSJSONObject>` |
+| 3   | `obj.getString('role')` 结果直接参与 `===` 比较 | `String?` 与字面量引用比较永远 false | `?? ''` 兜底 + 改用 `==`                          |
+| 4   | `id != null` 空字符串漏判                       | `getString` 返回 `""` 而非 null      | 改为 `id !== ''`                                  |
+
+**修复前后对比**
+
+```typescript
+// ❌ 修复前（4类问题叠加）
+const parseRoleData = (dataArray: any | null): UTSJSONObject | null => {
+  if (Array.isArray(dataArray) && dataArray.length > 0) {
+    const obj = dataArray[0] as UTSJSONObject;
+    const role = obj.getString("role"); // 返回 String?，未处理 null
+    const id = obj.getString("id"); // 返回 String?，未处理 null
+    if ((role === "merchant" || role === "admin") && id != null) {
+      // role === 'merchant'：引用比较，永远 false
+      // id != null：空字符串 '' 也会通过
+      return { id, role } as UTSJSONObject;
+    }
+  }
+  return null;
+};
+
+// ✅ 修复后（每一步类型明确）
+type ParseRoleInput = UTSJSONObject | Array<UTSJSONObject> | string | null;
+
+const parseRoleData = (dataArray: ParseRoleInput): UTSJSONObject | null => {
+  if (Array.isArray(dataArray)) {
+    const arr = dataArray as Array<UTSJSONObject>; // 明确类型后才能调 .length
+    if (arr.length > 0) {
+      const obj = arr[0];
+      const role = obj.getString("role") ?? ""; // String? → String
+      const id = obj.getString("id") ?? ""; // String? → String
+      if ((role == "merchant" || role == "admin") && id !== "") {
+        // == 值比较；id !== '' 杜绝空字符串通过
+        return { id, role } as UTSJSONObject;
+      }
+    }
+  }
+  return null;
+};
+```
+
+**同一文件中的其它修复点**（一并记录，避免遗漏）
+
+```typescript
+// 1. sessionUser 可空链接：不能用 ?. 调用 UTSJSONObject 方法
+// ❌
+let sessionUid = sessionUser?.getString('id') ?? ''
+// ✅
+let sessionUid: string = sessionUser != null ? (sessionUser.getString('id') ?? '') : ''
+
+// 2. accessData.getString 返回 String?，需要兜底
+// ❌
+const currRole = accessData.getString('role')
+// ✅
+const currRole = accessData.getString('role') ?? ''
+
+// 3. loginType 比较
+// ❌
+if (loginType.value === 1) { ... }
+// ✅（fix 脚本也会处理，但源码级改掉更好）
+if (loginType.value == 1) { ... }
+
+// 4. redirect 解码结果是 String?，需要兜底
+// ❌
+uni.redirectTo({ url: decodeURIComponent(redirect) })
+// ✅
+uni.redirectTo({ url: decodeURIComponent(redirect) ?? '' })
+```
+
+---
+
+### 5.12 问题10：getPushClientId 回调因多重 UTS 限制被整段删除
+
+**现象**：`login.uvue` 中注册推送 CID 的整段代码被删除，推送功能暂时失效。
+
+**被删除的原始代码**：
+
+```typescript
+// ❌ 以下代码在 UTS 中无法编译，已删除
+uni.getPushClientId({
+  success: async (res: any) => {
+    const cid =
+      res && (res.clientid || res.cid)
+        ? res.clientid || res.cid
+        : typeof res === "string"
+          ? res
+          : null; // typeof 在 UTS/Kotlin 中不可用
+    if (cid != null && cid !== "") {
+      uni.setStorageSync("uni_push2_cid", cid);
+    }
+  },
+});
+```
+
+**无法编译的原因（4层）**：
+
+| 问题                      | 说明                                                |
+| ------------------------- | --------------------------------------------------- |
+| `res.clientid`、`res.cid` | `res` 为 UTSJSONObject，不支持点访问属性            |
+| `typeof res === 'string'` | `typeof` 是 JS 运行时操作符，UTS/Kotlin 不支持      |
+| `res && (...)`            | `&&` 要求左侧是 Boolean，UTSJSONObject 不是 Boolean |
+| 回调 `async (res: any)`   | UTS 对异步回调有严格签名要求，不允许 `any` 参数     |
+
+**后续正确实现方式（待开发）**：
+
+```typescript
+// ✅ UTS 兼容写法（待补充到 login.uvue）
+uni.getPushClientId({
+  success(res: GetPushClientIdResult) {
+    const cid = res.cid ?? "";
+    if (cid !== "") {
+      uni.setStorageSync("uni_push2_cid", cid);
+    }
+  },
+  fail(_err: UniError) {
+    /* 静默失败，不影响登录 */
+  },
+});
+```
+
+> ⚠️ **当前状态**：推送 CID 注册功能在 Android 端暂时缺失，登录流程其它功能不受影响。
+
+---
+
+## 6. JS / UTS / Kotlin 语义差异总结
+
+> 此节总结三种语言在相同代码模式下的**行为差异**，是避免 bug 的核心参考材料。
+
+---
+
+### 6.1 比较运算符语义差异（最重要）
+
+| 运算符 | JavaScript           | UTS（编译到Kotlin）     | Kotlin 实际执行                   |
+| ------ | -------------------- | ----------------------- | --------------------------------- |
+| `==`   | 宽松相等（类型转换） | 值相等                  | 值相等（调用 `equals()`）✅       |
+| `===`  | 严格值相等           | **输出为 Kotlin `===`** | **引用相等**（referenceEquals）❌ |
+| `!=`   | 宽松不等             | 值不等                  | 值不等 ✅                         |
+| `!==`  | 严格不等             | **输出为 Kotlin `!==`** | **引用不等** ❌                   |
+
+**结论：UTS 中禁止使用 `===` 和 `!==`，统一使用 `==` 和 `!=`。**
+
+---
+
+### 6.2 条件判断 truthy/falsy 不支持
+
+| 场景              | JavaScript        | UTS/Kotlin  |
+| ----------------- | ----------------- | ----------- |
+| `if (str)`        | 非空字符串为 true | ❌ 类型错误 |
+| `if (num)`        | 非零为 true       | ❌ 类型错误 |
+| `if (obj)`        | 非 null 为 true   | ❌ 类型错误 |
+| `if (arr.length)` | 非零为 true       | ❌ 类型错误 |
+
+**正确写法对照**
+
+| JS 写法            | UTS 正确写法                         |
+| ------------------ | ------------------------------------ |
+| `if (str)`         | `if (str !== '')`                    |
+| `if (num)`         | `if (num != 0)`                      |
+| `if (obj)`         | `if (obj != null)`                   |
+| `if (arr.length)`  | `if (arr.length > 0)`                |
+| `if (str?.length)` | `if (str != null && str.length > 0)` |
+
+---
+
+### 6.3 空值兜底运算符
+
+| 语言       | 空字符串兜底         | null 兜底          | 注意                        |
+| ---------- | -------------------- | ------------------ | --------------------------- |
+| JavaScript | `str \|\| 'default'` | `val ?? 'default'` | `\|\|` 对假值兜底           |
+| UTS/Kotlin | `str ?? 'default'`   | `val ?? 'default'` | `\|\|` 要求两侧都是 Boolean |
+
+```typescript
+// ❌ UTS 中 || 不能用于字符串兜底
+const name = obj.getString("name") || "匿名"; // 编译错误
+
+// ✅ 使用 ??
+const name = obj.getString("name") ?? "匿名";
+```
+
+---
+
+### 6.4 短路运算符 `&&` 的限制
+
+```typescript
+// ❌ 左侧不是 Boolean，报错
+const result = someString && doSomething();
+
+// ✅ 方案1：显式判断
+if (someString !== "") {
+  doSomething();
+}
+
+// ✅ 方案2：确保左侧是 Boolean
+const result = someString !== "" && doSomething();
+```
+
+---
+
+### 6.5 JSON / 对象数据访问模式
+
+| 操作         | JavaScript          | UTS                                |
+| ------------ | ------------------- | ---------------------------------- |
+| 读字符串字段 | `obj.name`          | `obj.getString('name') ?? ''`      |
+| 读数字字段   | `obj.count`         | `obj.getNumber('count') ?? 0`      |
+| 读布尔字段   | `obj.flag`          | `obj.getBoolean('flag') ?? false`  |
+| 读嵌套对象   | `obj.address`       | `obj.getJSON('address')`           |
+| 读数组字段   | `obj.items`         | `obj.getArray('items')`            |
+| 动态键访问   | `obj[key]`          | `obj.getString(key) ?? ''`         |
+| 类型转换     | `(arr as any[])[0]` | `(arr as Array<UTSJSONObject>)[0]` |
+
+---
+
+### 6.6 类型推导差异
+
+```typescript
+// ❌ UTS lambda 必须标注参数类型
+const process = (item) => item.name; // Cannot infer type
+
+// ✅
+const process = (item: UTSJSONObject) => item.getString("name") ?? "";
+
+// ❌ 泛型推断
+const arr: any[] = []; // UTS 不支持
+
+// ✅
+const arr: Array<UTSJSONObject> = [];
+```
+
+---
+
+### 6.7 可选链差异
+
+| 场景   | JavaScript            | UTS                       |
+| ------ | --------------------- | ------------------------- |
+| 单级   | `obj?.field`          | 支持 ✅                   |
+| 多级   | `a?.b?.c?.d`          | ❌ 编译器无法推断中间类型 |
+| 带方法 | `obj?.getString('x')` | 不推荐，改用判空后调用    |
+
+```typescript
+// ❌ 多级可选链
+const val = response?.data?.items?.[0]?.name;
+
+// ✅ 分步判空
+if (response != null) {
+  const data = response.data;
+  if (data != null) {
+    const items = data as Array<UTSJSONObject>;
+    if (items.length > 0) {
+      const name = items[0].getString("name") ?? "";
+    }
+  }
+}
+```
+
+---
+
+### 6.8 跨平台行为差异矩阵
+
+| 代码模式                          | H5       | 微信小程序 | Android uni-app x       |
+| --------------------------------- | -------- | ---------- | ----------------------- |
+| `if (str)`                        | ✅       | ✅         | ❌ 编译错误             |
+| `===` 值比较                      | ✅       | ✅         | ❌ 变为引用比较         |
+| `obj.field`                       | ✅       | ✅         | ❌ unresolved reference |
+| `any[]` 类型                      | ✅       | ✅         | ❌ 类型不匹配           |
+| `box-shadow` CSS                  | ✅       | 部分支持   | ❌ 不支持               |
+| `min-height: 100%` 撑高           | ✅       | 部分支持   | ❌ 子元素高度为0        |
+| `#ifdef MP-WEIXIN` 安全区         | 忽略     | ✅         | ❌ Android被排除        |
+| `getCurrentPages().options.field` | ✅       | ✅         | ❌ 始终返回null         |
+| `statusBarHeight` 可能为null      | ✅(有值) | ✅(有值)   | ⚠️ 可能null             |
+
+---
+
+### 6.9 综合速查表
+
+| JS 写法（可能出错）            | UTS/Android 正确写法            |
+| ------------------------------ | ------------------------------- |
+| `if (str)`                     | `if (str !== '')`               |
+| `if (num)`                     | `if (num != 0)`                 |
+| `if (obj)`                     | `if (obj != null)`              |
+| `a === b`（字符串/数字）       | `a == b`                        |
+| `a !== b`                      | `a != b`                        |
+| `val \|\| default`             | `val ?? default`                |
+| `obj.field`                    | `obj.getString('field') ?? ''`  |
+| `data as any[]`                | `data as Array<UTSJSONObject>`  |
+| `arr[0] as UTSJSONObject`      | `arr[0]`（类型已知）            |
+| `a?.b?.c`                      | 分步 if 判空                    |
+| `options.type` in onLoad       | `opts.getString('type') ?? ''`  |
+| `const fn = (x) =>`            | `const fn = (x: Type) =>`       |
+| `(e) => { a(); b() }` 模板内联 | 抽取命名方法                    |
+| `sysInfo.statusBarHeight`      | `sysInfo.statusBarHeight ?? 20` |
+| `Promise.all([...])`           | 逐个 await（UTS不完全支持）     |
+
+---
+
+### 6.10 `typeof` 操作符在 UTS 中不可用
+
+**背景**：`login.uvue` 中因为使用了 `typeof res === 'string'` 导致整段推送 CID 代码无法编译（见 §5.12）。
+
+| 平台                | 运行时类型判断                                            |
+| ------------------- | --------------------------------------------------------- |
+| JavaScript          | `typeof x === 'string'`、`x instanceof Array`             |
+| UTS（编译到Kotlin） | `x is String`（Kotlin `is` 运算符）或通过类型系统静态保证 |
+
+```typescript
+// ❌ UTS 不支持 typeof
+if (typeof res === 'string') { ... }
+
+// ✅ 替代写法1：已知类型范围时用 Kotlin is 运算符
+if (res is String) { ... }
+
+// ✅ 替代写法2：对 UTSJSONObject 字段，用访问方法的返回值是否为 null 来判断类型
+if (obj.getString('key') != null) { ... }     // 字段是字符串类型
+if (obj.getJSON('key') != null) { ... }       // 字段是嵌套对象
+if (obj.getArray('key') != null) { ... }      // 字段是数组
+```
+
+**规范**：**UTS 代码中禁止使用 `typeof`；类型判断依赖编译期类型或 Kotlin `is` 运算符。**
+
+---
+
+### 6.11 数值转换函数差异
+
+| 操作                 | JavaScript                    | UTS 可用性                                      |
+| -------------------- | ----------------------------- | ----------------------------------------------- |
+| `parseInt('5')`      | 返回 `number`，失败返回 `NaN` | ✅ 返回 `number`，失败返回 `null`               |
+| `parseFloat('3.14')` | 返回 `number`                 | ✅ 支持                                         |
+| `Number(x)`          | 通用强制转换                  | ⚠️ 支持有限，优先用 `parseInt()`/`parseFloat()` |
+| `+str`（一元加）     | 隐式转数字                    | ❌ 不支持                                       |
+| `str as number`      | —（JS无此语法）               | ⚠️ 仅当类型系统能推断时有效                     |
+
+**真实项目案例**（来自 `utils/eventHelpers.uts`）：
+
+```typescript
+// picker change 事件：取选中索引
+// ❌ 不推荐（Number() 支持有限）
+const idx = Number(e.detail.value);
+
+// ✅ 项目实际采用的写法
+const idx: number = parseInt(e.detail.value as string) ?? 0;
+//                                                       ↑ parseInt 返回 number | null，需要 ?? 兜底
+```
+
+**规范**：`parseInt()` / `parseFloat()` 的返回值必须用 `?? 默认值` 处理，避免 `null` 传播。
+
+---
+
+## 7. Android 适配与页面运行问题总结
+
+> **触发场景**：APK 成功安装后，打开页面发现布局异常、内容截断、导航遮挡、跳转失败等视觉和交互问题。
+>
+> **主要涉及文件**：`pages/mall/merchant/*.uvue`
+
+---
+
+### 7.1 scroll-view 无法滚动 / 内容截断
+
+**页面**：`index.uvue`、`growth.uvue`、`messages.uvue`、`finance.uvue`、`orders.uvue`  
+**现象**：列表只显示一小部分，无法向下滚动，底部内容不可达。
+
+**根因**
+
+```css
+/* 旧写法 */
+.merchant-container {
+  min-height: 100%;
+} /* ← 问题根源 */
+.main-scroll {
+  height: 100%;
+} /* ← 无有效父高度，=0 */
+```
+
+`min-height: 100%` 在 Web 中靠内容撑高，子元素 `height: 100%` 继承的是内容高度而非视口高度。在 Android 原生渲染中，布局计算一次性完成，`min-height` 不给子元素提供明确高度，`scroll-view` 拿到的可滚动高度为 0。
+
+**修复**
+
+```css
+/* 修复后 */
+.merchant-container {
+  display: flex;
+  flex-direction: column;
+  height: 100%; /* 明确等于页面可用视口高度 */
+}
+.main-scroll {
+  flex: 1;
+} /* 占满剩余空间 */
+```
+
+**为什么有效**：`height: 100%` 给容器明确的像素高度；`flex: 1` 让 scroll-view 在确定高度内伸展，原生引擎能计算真实 scrollable 区域。
+
+**规范**：**页面根容器必须使用 `height: 100%` + `flex-column`，scroll-view 使用 `flex: 1`，禁止用 `min-height: 100%`。**
+
+---
+
+### 7.2 顶部内容被状态栏遮挡
+
+**页面**：所有 29 个 `navigationStyle: custom` 的 merchant 页面  
+**现象**：顶部导航条贴着屏幕顶端，内容被系统状态栏（时间、电量区域）遮住约 20–40px。
+
+**根因**：顶部安全区代码用条件编译包裹，Android 编译时被排除：
+
+```html
+<!-- 旧写法：Android 编译时整个块消失 -->
+<!-- #ifdef MP-WEIXIN -->
+<view class="mp-tab-navbar">...</view>
+<!-- #endif -->
+```
+
+**修复**：移除 `<!-- #ifdef MP-WEIXIN -->` 和 `<!-- #endif -->` 包裹，让顶部安全区对所有平台生效：
+
+```html
+<!-- 修复后：所有平台都渲染 -->
+<view class="mp-tab-navbar">...</view>
+```
+
+```css
+.mp-tab-navbar {
+  height: calc(88rpx + var(--status-bar-height));
+  padding-top: var(--status-bar-height); /* Android自动注入正确值 */
+}
+```
+
+**规范**：**`--status-bar-height` 对小程序和 Android 均有效，状态栏 padding 不能放在 `#ifdef MP-WEIXIN` 里。**
+
+---
+
+### 7.3 双层 TabBar 叠加
+
+**页面**：`index.uvue`、`orders.uvue`、`messages.uvue`、`growth.uvue`、`profile.uvue`  
+**现象**：底部出现两个导航栏叠加。
+
+**根因**：`pages.json` 配置了系统 TabBar，同时页面内还保留了 `<merchant-tab-bar>` 自定义组件：
+
+```html
+<!-- 页面内还有这个 ← 与系统TabBar并存 -->
+<merchant-tab-bar :current="0"></merchant-tab-bar>
+```
+
+**修复**：从 5 个主 Tab 页删除自定义 TabBar 相关代码：
+
+```html
+<!-- 删除 template 中 -->
+<merchant-tab-bar :current="0"></merchant-tab-bar>
+```
+
+```typescript
+// 删除 script 中
+import MerchantTabBar from '@/components/merchant-tabbar/MerchantTabBar.uvue'
+components: { MerchantTabBar },
+```
+
+**规范**：**自定义 TabBar 组件只用于小程序。Android 使用 `pages.json` 原生 TabBar。二者不能并存。**
+
+---
+
+### 7.4 底部空白过大（safe-bottom 冗余）
+
+**页面**：`index.uvue`、`growth.uvue`  
+**现象**：移除自定义 TabBar 后，底部仍有约 160rpx 空白。
+
+**根因**：`.safe-bottom { height: 160rpx }` 是为自定义 TabBar 留空的，TabBar 移除后空间成为多余空白。
+
+**修复**：
+
+```css
+/* 旧 */
+.safe-bottom {
+  height: 160rpx;
+}
+/* 新 */
+.safe-bottom {
+  height: 20rpx;
+}
+```
+
+并新增"到底提示"作为视觉终止符：
+
+```html
+<view class="bottom-tip">
+  <text class="bottom-tip-text">—— 已经到底了 ——</text>
+</view>
+```
+
+---
+
+### 7.5 登录后跳转到不存在的路由（白屏）
+
+详见 §5.5。
+
+---
+
+### 7.6 `onLoad` 参数取不到 query 字段
+
+详见 §5.6。
+
+---
+
+### 7.7 大量 Web-only 页面被编译进 Android 包
+
+**现象**：HBuilderX UTS 编译时报大量 unresolved reference，来自约 100+ 个 Web-only 页面（admin 后台、消费者端、分销等）。
+
+**根因**：`pages.json` 是全平台统一的，包含约 150+ 个路由，Android 编译处理所有路由对应的文件。
+
+**修复**：大幅精简 `pages.json`，只保留 Android 商家端所需的 ~30 个页面，移除：
+
+- `pages/mall/admin/**`（Web 管理后台，40+ 子包页面）
+- `pages/main/**`（消费者端 5 个 Tab 页）
+- `doc_mall/` 子包（分销、直播、积分等）
+- `test/` 子包（API 调试工具）
+- `analytics/` 子包（数据分析报表）
+
+**规范**：**建议维护 `pages.full.json`（全功能）和一个 Android 精简版，通过脚本在打包前切换。**
+
+---
+
+### 7.8 `statusBarHeight` 可能为 null
+
+**页面**：`chat.uvue`  
+**现象**：头部导航高度偶尔计算为 0。
+
+**修复**：
+
+```typescript
+// 旧
+const statusBarH = sysInfo.statusBarHeight; // 可能 null
+
+// 新
+const statusBarH = sysInfo.statusBarHeight ?? 20;
+```
+
+---
+
+### 7.9 事件处理器接收联合类型导致 smart cast 失败
+
+**页面**：`growth.uvue`  
+**现象**：点击列表项无响应。
+
+**根因**：事件处理函数接收 `TipType | GuideType | CourseType` 联合类型，Android UTS 无法 smart cast，字段访问失败。
+
+**修复**：模板层提取字段，函数接收基础类型：
+
+```html
+<!-- 旧 -->
+@click="viewDetail(tip)"
+
+<!-- 新 -->
+@click="viewDetail(tip.link)"
+```
+
+```typescript
+// 函数只接收 string
+viewDetail(link: string) {
+  if (link.length > 0) { uni.navigateTo({ url: link }) }
+}
+```
+
+---
+
+### 7.10 Android 不支持的 CSS 属性
+
+**现象**：卡片无阴影，渐变色显示异常。
+
+**根因**：`box-shadow` 和多停止点 `linear-gradient` 在 Android 原生渲染层不支持。
+
+**修复**：
+
+```css
+/* 移除 box-shadow */
+
+/* 渐变去掉百分比停止点 */
+/* 旧 */
+background: linear-gradient(135deg, #ff6b35 0%, #ff8c5a 100%);
+/* 新 */
+background: linear-gradient(135deg, #ff6b35, #ff8c5a);
+```
+
+**规范**：**禁用 `box-shadow`；渐变只用两端无停止点写法。**
+
+---
+
+### 7.11 字符串空值判断不兼容
+
+**页面**：`profile.uvue`  
+**现象**：`merchantId` 未赋值时仍发起了数据请求。
+
+```typescript
+// 旧（UTS报错或行为异常）
+if (this.merchantId) { ... }
+
+// 新
+if (this.merchantId !== '') { ... }
+```
+
+---
+
+### 7.12 flex-direction 默认值在 Android 与 Web 相反
+
+**现象**：某些页面在 H5/小程序上是水平排列，在 Android 上变成垂直排列，或按钮堆叠成一列。
+
+**根因**：
+
+| 平台                        | `display: flex` 的默认 `flex-direction` |
+| --------------------------- | --------------------------------------- |
+| Web 浏览器                  | `row`（水平排列）                       |
+| uni-app x（Android 渲染器） | `column`（垂直排列）— **与 Web 相反**   |
+
+如果 CSS 没有显式声明 `flex-direction`，Android 实际是 `column`，而 Web/小程序 是 `row`。
+
+**修复**：需要水平排列的容器，必须**显式声明** `flex-direction: row`：
+
+```css
+/* ❌ 省略 flex-direction（在Android上默认 column，变成垂直堆叠） */
+.nav-bar {
+  display: flex;
+  align-items: center;
+}
+
+/* ✅ 明确声明，行为确定 */
+.nav-bar {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+}
+```
+
+**规范**：**所有 `display: flex` 容器必须显式声明 `flex-direction: row` 或 `column`，不能依赖平台默认值。**
+
+---
+
+### 7.13 scroll-into-view 目标 ID 必须是合法标识符
+
+**页面**：`chat.uvue`（消息列表自动滚动到最新消息）  
+**现象**：`scroll-view` 的 `:scroll-into-view` 绑定后，Android 上滚动不生效。
+
+**根因**：`scroll-into-view` 要求目标元素的 `id` 只能包含字母、数字、下划线、连字符，且必须以字母开头。消息 ID 通常包含 `:` 或空格等非法字符（如 UUID 或时间戳字符串）。
+
+**修复**：设置 ID 前对特殊字符做过滤：
+
+```typescript
+// chat.uvue 中的实际处理
+const getSafeId = (rawId: string): string => {
+  return "msg_" + rawId.replace(/[^a-zA-Z0-9]/g, "_");
+};
+
+// 模板中
+// <view :id="getSafeId(msg.id)">
+// :scroll-into-view="getSafeId(latestMsgId)"
+```
+
+**规范**：**所有动态生成的元素 ID（用于 scroll-into-view 等），必须先做字符过滤，只保留字母、数字、下划线，并添加固定字母前缀。**
+
+---
+
+### 7.14 chat 页面键盘弹出与底部安全区双重兜底
+
+**页面**：`chat.uvue`  
+**现象**：在某些 Android 设备上，页面底部紧贴屏幕边缘，没有间距；在另一些设备上底部空白过多。
+
+**根因**：Android 设备底部安全区高度不一——有实体 Home 键的设备为 0，全面屏设备为 20–40px。单纯使用 `env(safe-area-inset-bottom)` 时，无 Home 键模拟器会返回 0，导致紧贴底部。
+
+**实际处理方式**（`chat.uvue` 中的做法）：
+
+```html
+<!-- 底部安全区：env() 优先，min-height 作为最低保障 -->
+<view style="height: env(safe-area-inset-bottom); min-height: 40rpx;"></view>
+```
+
+- `env(safe-area-inset-bottom)`：在真实全面屏设备上提供正确的物理安全区高度
+- `min-height: 40rpx`：在模拟器或有 Home 键的旧设备上（env 返回 0）保留基本间距
+
+**规范**：**底部安全区同时提供 `env(safe-area-inset-bottom)` 和 `min-height` 双重兜底，二者取较大值自动生效。**
+
+---
+
+## 8. 额外发现的重要隐藏问题
+
+> 这些问题在排查过程中发现，但不属于最初明确提出的类别，需要特别记录。
+
+---
+
+### 8.1 `kotlinc_errors_current.txt`（50MB）全是噪音，无参考价值
+
+**发现过程**：尝试用独立 `kotlinc` 命令行编译 `.kt` 文件，产生了 34,261 行 "error" 日志，误以为找到了大量真实错误。
+
+**真相**：第一条错误即 `cannot access built-in declaration 'kotlin.String'`，说明 `kotlinc` 调用时未传入 SDK classpath（缺少 `android.jar`、uni-app SDK AAR 等），所有报错都是"缺少编译环境"的假错误，与真实代码 bug 无关。
+
+**教训**：**直接 `kotlinc` 编译 uni-app x 生成的 `.kt` 文件没有意义**，必须通过 Android Studio/Gradle 的完整构建体系（带正确 classpath）才能得到真实错误。
+
+---
+
+### 8.2 push 订阅回调签名必须完整声明
+
+**发现**：`merchant/index.uvue` 中推送订阅的回调省略了参数，UTS 要求回调签名必须与接口完全匹配：
+
+```typescript
+// 旧（报 argument type mismatch）
+.subscribe()
+
+// 新（即使不用也要声明）
+.subscribe((_status: string, _err: UniError | null) => {})
+```
+
+**规范**：**UTS 回调参数即使不用也必须在签名中声明，用 `_` 前缀标记为"有意忽略"。**
+
+---
+
+### 8.3 BOM 字节导致首行乱码
+
+**发现**：部分页面生成的 `.kt` 文件首行出现 `锘?` 前缀（BOM 字节 `\xEF\xBB\xBF`），Kotlin 编译器无法识别。
+
+**规范**：**保存文件统一使用 UTF-8 无 BOM 编码。用 .NET `File.WriteAllText()` 写文件默认无 BOM，是安全的。**
+
+---
+
+### 8.4 `any` 类型掩盖了大量潜在的 Android 运行时错误
+
+**发现**：项目中大量 `as any`、`as any[]` 在 HBuilderX 的宽松模式下通过编译，但在 Android 严格模式下全部需要改成具体类型。`any` 是 Android 适配的最大技术债。
+
+**规范**：**新代码禁止使用 `any`；旧代码中的 `any` 是 Android 适配的优先改造目标。**
+
+---
+
+### 8.5 AkReq 数据处理链路：从 request 到 UTSJSONObject 的完整类型模式
+
+**背景**：本项目使用 `AkReq`（封装自 `uni_modules/ak-req/index.uts`）发起请求，但无论用 `AkReq` 还是 `uni.request`，Android 端的响应数据处理链路必须遵循严格的类型模式，否则会在编译或运行时报类型错误。
+
+**完整数据流模式**
+
+```typescript
+// Step 1: 发起请求（AkReq 返回 AkRequestSuccessResult）
+const result = await AkReq.post("/api/merchant/goods/list", { page: 1 });
+
+// Step 2: 错误状态检查
+if (result.error != null) {
+  console.error("请求失败", result.error);
+  return;
+}
+
+// Step 3: 断言响应体类型
+// ❌ 错误写法：as any[] 在严格类型检查下不够安全
+const rawList = result.data as any[];
+
+// ✅ 正确写法：明确为 Array<UTSJSONObject>
+const rawList = result.data as Array<UTSJSONObject>;
+
+// Step 4: 遍历并用方法访问字段（不能点访问）
+for (const item of rawList) {
+  const name = item.getString("name") ?? ""; // string
+  const price = item.getNumber("price") ?? 0; // number
+  const isOnSale = item.getBoolean("on_sale") ?? false; // boolean
+  const images = item.getArray("images"); // Array<any> | null
+  const detail = item.getJSON("detail"); // UTSJSONObject | null
+}
+```
+
+**常见错误模式速查**
+
+| 错误写法                                      | 报错信息                               | 正确写法                                               |
+| --------------------------------------------- | -------------------------------------- | ------------------------------------------------------ |
+| `result.data as any[]` + `arr[0].name`        | `unresolved reference 'name'`          | `as Array<UTSJSONObject>` + `arr[0].getString('name')` |
+| `const x = item.getString('x')` 赋给 `string` | `String? cannot be assigned to String` | 加 `?? ''`                                             |
+| `result.raw?.getString('msg')`                | UTS 中 `?.` 在 `any?` 类型上失效       | 先 `!= null` 判断，再调用方法                          |
+| `result.data.length`（未断言类型）            | `unresolved reference 'length'`        | 先 `as Array<UTSJSONObject>`                           |
+
+**为什么 H5 / 小程序 没有这个问题**：JS 运行时允许在任何对象上点访问任意属性（返回 `undefined` 而非报错）；Android UTS 编译到 Kotlin 后，类型系统要求每一步访问都有明确的编译期类型支撑。
+
+---
+
+### 8.6 sessionUser 可空对象的安全访问模式
+
+**发现**：`login.uvue` 中 `sessionUser` 来自 `uni.getStorageSync()`，类型在运行时可能是 `null`；在 UTS 中对可空 UTSJSONObject 调用可选链 `?.` + 方法调用会编译失败。
+
+```typescript
+// ❌ 旧写法（两个问题：?. 用在 any 类型上 + getString 在可空链上）
+let sessionUid = sessionUser?.getString("id") ?? "";
+
+// ✅ 修复写法（先判 null，再调用）
+let sessionUid: string =
+  sessionUser != null ? (sessionUser.getString("id") ?? "") : "";
+```
+
+**模式推广**：所有从 `uni.getStorageSync()` 读出的 `UTSJSONObject` 类型数据，必须先做 `!= null` 判断，再用方法访问字段，不能用可选链 `?.` 直接调用 UTSJSONObject 的访问方法。
+
+```typescript
+// 通用模式
+const stored = uni.getStorageSync("key") as UTSJSONObject | null;
+const value: string = stored != null ? (stored.getString("field") ?? "") : "";
+```
+
+---
+
+## 9. 面向后续开发的编码规范清单
+
+### 9.1 类型安全规范
+
+- [ ] 禁止使用 `as any` 和 `any[]`；改用 `UTSJSONObject`、`Array<UTSJSONObject>` 或具体 type 定义
+- [ ] 禁止 `if (str)` / `if (num)` / `if (obj)` 非布尔条件；改用 `!== ''` / `!= 0` / `!= null`
+- [ ] 禁止 `===` 和 `!==`；统一使用 `==` 和 `!=`
+- [ ] 字符串兜底使用 `??` 而非 `||`
+- [ ] `UTSJSONObject` 字段访问必须用 `.getString()` / `.getNumber()` / `.getBoolean()` / `.getJSON()` / `.getArray()` 等方法
+- [ ] `onLoad` 参数声明为 `UTSJSONObject | null`，用 `.getString()` 取值
+- [ ] 所有来自 `getSystemInfoSync()` 的数值属性（如 `statusBarHeight`）必须加 `?? defaultValue`
+- [ ] Lambda / 回调函数参数必须显式标注类型，不能依赖推断
+- [ ] 禁止使用 `typeof`；类型判断依赖编译期类型或 Kotlin `is` 运算符
+- [ ] 数值转换统一使用 `parseInt()` / `parseFloat()`，结果必须加 `?? 默认值` 兜底
+- [ ] 从 `uni.getStorageSync()` 读出的 UTSJSONObject 必须先判 `!= null` 再调方法，不能用 `?.`
+
+### 9.2 布局规范（Android 端）
+
+- [ ] 页面根容器使用 `height: 100%` + `display: flex` + `flex-direction: column`
+- [ ] 滚动容器使用 `flex: 1`，不使用 `height: 100%` 或 `min-height`
+- [ ] 禁止使用 `box-shadow`；可用 `elevation` 或浅灰 `border` 替代
+- [ ] `linear-gradient` 只使用两端颜色无停止点写法
+- [ ] 状态栏 padding 使用 `var(--status-bar-height)`，不包裹在 `#ifdef MP-WEIXIN` 里
+- [ ] `navigationStyle: custom` 的页面顶部必须有 `padding-top: var(--status-bar-height)`
+- [ ] 系统 TabBar 和自定义 TabBar 组件不能并存，二选一
+- [ ] 所有 `display: flex` 容器必须显式声明 `flex-direction: row` 或 `column`，不能依赖默认值（Android 默认 `column`，Web 默认 `row`）
+- [ ] 底部安全区同时写 `height: env(safe-area-inset-bottom)` 和 `min-height` 兜底
+- [ ] `scroll-into-view` 绑定的目标 ID 只能含字母、数字、下划线，且必须以字母开头
+
+### 9.3 组件与事件规范
+
+- [ ] 事件处理器函数接收基础类型（`string`、`number`、`boolean`），不接收联合类型
+- [ ] 复杂对象在模板层解构取字段值，传给事件函数
+- [ ] `@click` 内联逻辑必须抽成命名方法，不允许内联箭头函数
+- [ ] picker/input 事件统一使用 `utils/eventHelpers.uts` 中的工具函数
+- [ ] 回调函数签名必须完整声明所有参数，不用的参数用 `_` 前缀命名
+
+### 9.4 多端兼容规范
+
+- [ ] 新建页面时在文件头注释"目标平台"（Android / H5 / 小程序 / 全平台）
+- [ ] Web-only 页面不纳入 Android 的 `pages.json`
+- [ ] 新增页面同时检查：① `pages.json` 路由 ② 页面内是否有平台特定代码
+- [ ] 使用 `#ifdef APP-ANDROID` 而非 `#ifdef MP-WEIXIN` 来隔离 Android 特定代码
+- [ ] 登录跳转的目标路由必须在当前 `pages.json` 中存在
+
+### 9.5 构建流程规范
+
+- [ ] 每次 HBuilderX"生成本地打包App资源"后，必须运行 `fix_kt_files.ps1`
+- [ ] 不要用独立 `kotlinc` 编译 `.kt` 文件排查错误，必须用 Android Studio Gradle
+- [ ] 保存文件统一使用 UTF-8 无 BOM 编码
+
+---
+
+## 10. 面向后续排查的标准流程清单
+
+### 10.1 遇到 HBuilderX UTS 编译错误
+
+```
+1. 查看错误信息中的错误代码（UTS110xxxxx）
+2. 对照 §4 的 13 类问题速查表定位问题类型
+3. 重点检查：
+   - 条件表达式是否非 Boolean？ → 加 !== '' / != null
+   - 是否使用了 obj.field？ → 改 obj.getString('field')
+   - 是否使用了 any[] ？ → 改 Array<UTSJSONObject>
+   - 是否有内联箭头函数？ → 抽取命名方法
+4. 修复后重新"生成本地打包App资源"
+```
+
+### 10.2 遇到 Android Studio Kotlin 编译错误
+
+```
+1. 检查是否运行了 fix_kt_files.ps1
+2. 检查报错中的符号是否属于 uni-app SDK（uni_showModal 等）
+   → 是：检查 app/libs/ 中的 AAR 文件
+   → 否：检查 .kt 文件中是否有 BOM 字节（锘? 开头）
+3. 检查是否有 === 出现（未被 fix 脚本替换）
+4. 全量搜索错误的符号名，确认来自哪个 .uvue/.uts 源文件
+5. 在源文件中修复，重新走完整流程
+```
+
+### 10.3 遇到 Android 运行时逻辑错误（看起来代码是对的但行为不对）
+
+```
+1. 优先怀疑 === / !== 比较（§5.4）：
+   → 在 fix_kt_files.ps1 运行结果中确认替换了多少处
+2. 检查条件分支是否进入了错误分支
+   → 打印关键值到 console.log 观察
+3. 检查 UTSJSONObject 字段是否返回了 null
+   → 改用 getString() 并加 ?? '' 兜底
+4. 检查跳转路由是否存在于 pages.json
+```
+
+### 10.4 遇到 Android 页面布局问题
+
+```
+1. 内容截断/无法滚动：
+   → 检查根容器是否使用了 min-height: 100%
+   → 确认 scroll-view 的父元素有明确的 height
+   → 改用 flex: 1 模型
+
+2. 顶部内容被遮挡：
+   → 检查页面是否 navigationStyle: custom
+   → 检查顶部 padding 是否在 #ifdef MP-WEIXIN 里
+   → 确认使用了 var(--status-bar-height)
+
+3. 双层 TabBar：
+   → 检查页面内是否还有 <merchant-tab-bar> 组件
+   → 检查 pages.json 是否配置了 tabBar
+
+4. CSS 样式异常：
+   → 检查是否使用了 box-shadow
+   → 检查 linear-gradient 是否有多个停止点
+   → 参考 uni-app x 官方 CSS 支持列表
+```
+
+### 10.5 完整构建流程参考
+
+```
+[准备阶段]
+1. 确认当前分支：git branch（应在 huangzhenbao-admin）
+2. 确认 pages.json 是 Android 精简版
+
+[HBuilderX 编译阶段]
+3. HBuilderX → 发行 → 本地打包 → 生成本地打包App资源
+4. 等待编译完成（底部显示"成功"）
+5. 检查是否有错误提示，参照 §4 和 §10.1 处理
+
+[Android Studio 阶段]
+6. 复制 .kt 文件到 D:\Android\Project\mall\app\src\main\java\
+7. 运行：powershell -File D:\Android\Project\mall\fix_kt_files.ps1
+8. Android Studio → Build → Clean Project
+9. Android Studio → Build → assembleDebug
+10. 检查 Build Output，参照 §5 和 §10.2 处理
+
+[设备运行阶段]
+11. adb install 或直接 Run
+12. 按照 §10.3 和 §10.4 的清单检查运行时问题
+```
+
+---
+
+## 11. 关键文件与关键改动索引
+
+### 11.1 源代码关键改动（`5ab4789d` → `f99bd5a7`）
+
+| 文件                                | 主要改动                                                                          | 所属问题          |
+| ----------------------------------- | --------------------------------------------------------------------------------- | ----------------- |
+| `pages/user/login.uvue`             | 3处跳转改为 `merchant/index`；onLoad参数改用 UTSJSONObject                        | §5.5, §5.6        |
+| `pages/mall/merchant/index.uvue`    | 删除 `<merchant-tab-bar>`；删除 `#ifdef MP-WEIXIN` 包裹；容器 `min-height→flex:1` | §7.1, §7.2, §7.3  |
+| `pages/mall/merchant/growth.uvue`   | 同上布局修复；`viewDetail` 改接 string；`safe-bottom` 减小                        | §7.1, §7.9, §7.4  |
+| `pages/mall/merchant/profile.uvue`  | 删 MerchantTabBar；`merchantId` 判空改为 `!== ''`；`any[]→Array<UTSJSONObject>`   | §7.3, §7.11, §4.3 |
+| `pages/mall/merchant/chat.uvue`     | `statusBarHeight ?? 20`                                                           | §7.8              |
+| `pages/mall/merchant/orders.uvue`   | 删 MerchantTabBar；布局 flex 化                                                   | §7.1, §7.3        |
+| `pages/mall/merchant/messages.uvue` | 删 `#ifdef MP-WEIXIN` 包裹；删 MerchantTabBar                                     | §7.2, §7.3        |
+| `pages/mall/merchant/finance.uvue`  | 布局 flex 化（`.page { flex-column }`，`.scroll { flex:1 }`）                     | §7.1              |
+| `pages.json`                        | 移除约 120 个 Web-only 页面路由                                                   | §7.7              |
+| `utils/eventHelpers.uts`（新增）    | `getPickerIdx()`、`getInputVal()` 等工具函数                                      | §4.7              |
+
+### 11.2 Android 项目关键文件
+
+| 文件                                       | 作用                                                                     |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| `D:\Android\Project\mall\fix_kt_files.ps1` | **每次必须运行**：替换 `===→==`、`!==→!=`、修复路径、清除 MerchantTabBar |
+| `D:\Android\Project\mall\app\libs\`        | uni-app SDK AAR 文件（需补充）                                           |
+| `D:\Android\Project\mall\app\build.gradle` | `fileTree(dir: 'libs', include: ['*.aar'])`                              |
+| `D:\Android\Project\mall\报错信息.txt`     | B阶段 Kotlin 符号缺失的原始错误日志                                      |
+
+### 11.3 参考文档
+
+| 文件                                             | 内容                 |
+| ------------------------------------------------ | -------------------- |
+| `docs/Android打包自检清单.md`                    | 打包前的逐项自查清单 |
+| `docs/project_spec/UNI_APP_X_PAGE_FIX_GUIDE.md`  | 页面级修复指南       |
+| `docs/fix_guide/android_debug_full_fix_guide.md` | **本文档**           |
+
+### 11.4 关键提交 diff 查看命令
+
+```powershell
+# 查看基线到最终的所有源码改动
+git diff 5ab4789d f99bd5a7 -- "*.uvue" "*.uts" "*.json" "*.ps1"
+
+# 查看某个文件的改动
+git diff 5ab4789d f99bd5a7 -- pages/user/login.uvue
+
+# 查看 pages.json 被移除的页面
+git diff 5ab4789d f99bd5a7 -- pages.json | Select-String "^-" | Where-Object { $_ -match '"path"' }
+```
+
+---
+
+## 12. 结语
+
+### 12.1 核心教训
+
+这次 Android 调试的问题几乎都源于**一个根本误解**：以为 UTS 是 JavaScript 的方言，实际上它是一门独立的强类型语言，编译到 Kotlin 后遵循完全不同的规则。
+
+> **UTS 不是 JavaScript，不能用 JS 直觉写 UTS。**
+
+三个最重要的认知：
+
+1. **类型是真实的**：`string` 不能当 `boolean` 用，`null` 不会隐式转换，`any` 是技术债
+2. **`===` 是陷阱**：它不产生编译错误，但在 Android 上产生隐蔽的逻辑错误
+3. **布局需要明确高度**：Android 原生渲染不支持从内容反向推算父元素高度
+
+### 12.2 最值得团队反复看的 10 条规则
+
+1. **`===` 和 `!==` 在 Android 是引用比较，一律改用 `==` 和 `!=`**
+2. **`if` 条件只接受 Boolean，`if (str)` 在 UTS 中是编译错误**
+3. **`UTSJSONObject` 的字段必须用 `.getString()` 等方法访问，不能点访问**
+4. **`any[]` 必须改为 `Array<UTSJSONObject>`，`as any` 是所有 Android 问题的根源**
+5. **页面根容器用 `height: 100% + flex-column`，scroll-view 用 `flex: 1`，不用 `min-height`**
+6. **状态栏 padding 用 `var(--status-bar-height)`，不要包在 `#ifdef MP-WEIXIN` 里**
+7. **系统 TabBar 和自定义 TabBar 不能并存，Android 端用系统 TabBar**
+8. **每次 HBuilderX 生成 `.kt` 文件后必须运行 `fix_kt_files.ps1`**
+9. **`onLoad` 参数取字段用 `UTSJSONObject.getString()`，不用 `currentPage.options.field`**
+10. **Web-only 页面必须从 Android 的 `pages.json` 中移除，减少无效编译**
+
+---
+
+_文档完_  
+_最后修订：2026-04-20_  
+_下次更新触发条件：解决 AAR 依赖问题后（问题 §5.7）_
+
+---
+
+---
+
+# 第二轮安卓端调试修复记录（2026-04-21）
+
+> **本轮时间**：2026-04-21  
+> **调试阶段**：APK 已能运行，本轮专注页面交互逻辑与视觉 Bug  
+> **背景**：第一轮（§1-§12）解决了编译和基础运行问题；本轮基于已可运行的 APK，逐页排查交互逻辑、布局、路由、状态管理问题。
+
+---
+
+## 第二轮问题总览
+
+| 序号  | 问题名称                                        | 页面/模块                              | 问题类型          | 是否已解决 | 备注                                         |
+| ----- | ----------------------------------------------- | -------------------------------------- | ----------------- | ---------- | -------------------------------------------- |
+| R2-01 | products.uvue 列表数据累加（3+3=6）             | 商品管理                               | 状态管理          | ✅ 已解决  | onShow 未重置分页                            |
+| R2-02 | 7 个页面 scroll-y 无效，无法滚动                | 商品/评价/会员/库存/促销/聊天/专属折扣 | 安卓布局          | ✅ 已解决  | scroll-y 属性不被识别                        |
+| R2-03 | live.uvue 底部白屏                              | 直播                                   | 安卓布局          | ✅ 已解决  | min-height 导致高度计算错误                  |
+| R2-04 | product-edit.uvue 底部被遮挡                    | 发布/编辑商品                          | 安卓布局          | ✅ 已解决  | position:fixed 在非根视图中失效              |
+| R2-05 | shop-edit.uvue 底部被遮挡                       | 店铺设置                               | 安卓布局          | ✅ 已解决  | 同上                                         |
+| R2-06 | product-detail.uvue 底部被遮挡                  | 商品详情                               | 安卓布局          | ✅ 已解决  | 同上                                         |
+| R2-07 | exclusive-discounts.uvue 无法滚动               | 专属折扣                               | 安卓布局          | ✅ 已解决  | 根容器高度链断裂                             |
+| R2-08 | product-edit 标题显示"商品编辑"                 | 发布商品入口                           | 页面配置          | ✅ 已解决  | 标题硬编码                                   |
+| R2-09 | shop-edit 标题显示"店铺资料"                    | 店铺设置入口                           | 页面配置          | ✅ 已解决  | 标题与入口按钮不一致                         |
+| R2-10 | members.uvue "添加等级"无效                     | 会员管理                               | 业务逻辑          | ✅ 已解决  | 按钮绑定了死变量                             |
+| R2-11 | members.uvue "删除等级"无效                     | 会员管理                               | 异步回调          | ✅ 已解决  | uni.showModal 回调在 Kotlin 中不可靠         |
+| R2-12 | members.uvue 页面无法滚动                       | 会员管理                               | 安卓布局          | ✅ 已解决  | overflow:hidden 缺失                         |
+| R2-13 | settings.uvue 退出商家端无效                    | 设置                                   | 路由+异步回调     | ✅ 已解决  | 同 R2-11，回调链不可靠                       |
+| R2-14 | App.uvue 退出后仍把用户拉回商家端               | 全局启动逻辑                           | 路由守卫/状态恢复 | ✅ 已解决  | storage 未清干净 + store 内存态未重置        |
+| R2-15 | members.uvue 编译失败（import 缺失）            | 会员管理                               | 编译问题          | ✅ 已解决  | 缺 import supa 和 type MemberLevel           |
+| R2-16 | members.uvue 模板结构损坏（`</template>` 缺失） | 会员管理                               | 编译问题          | ✅ 已解决  | 上一轮修复时误注入 script 内容到 template 区 |
+
+---
+
+## R2-01：商品管理列表数据累加（"3+3=6" 问题）
+
+### 现象
+
+进入"商品管理"页，浏览后退出，再次进入页面，列表数据变成两倍（原来 3 条，变成 6 条）；多次进出后持续累加。
+
+### 出现位置
+
+`pages/mall/merchant/products.uvue`，`onShow` 生命周期 + `loadProducts()` 方法
+
+### 问题类型
+
+状态管理 / 异步加载
+
+### 根因分析
+
+`onShow` 直接调用 `loadProducts()`，但没有先重置 `page=1`、`products=[]`、`hasMore=true`。  
+用户在页面内上拉加载了第2页后，`page` 已变为 2；退出再进来时，`onShow` 再次调 `loadProducts()`，此时 `page=2`，服务器返回第2页数据，追加到已有列表，视觉上看到 3+3=6。
+
+### 为什么会这样
+
+uni-app 的 `onShow` 每次页面显示都会触发（不只是第一次加载），而 `onLoad` 只触发一次。把列表数据请求放在 `onShow` 而没有重置分页状态，就会导致"每次回到页面都在原有列表上继续追加"。
+
+### 修复方式
+
+在 `onShow` 中调用 `loadProducts()` 之前先重置分页状态：
+
+```typescript
+onShow() {
+  // 每次页面显示都要重置，防止"3+3=6"数据累加
+  this.page = 1
+  this.hasMore = true
+  this.products = []
+  this.loadProducts()
+},
+```
+
+同步修复 `_doDeleteProduct()` 删除商品后的刷新逻辑（同样需要重置再刷）：
+
+```typescript
+async _doDeleteProduct(id: string) {
+  // ... 删除逻辑 ...
+  this.page = 1
+  this.hasMore = true
+  this.products = []
+  this.loadProducts()
+}
+```
+
+### 涉及文件
+
+`d:\骅锋\mall\pages\mall\merchant\products.uvue`
+
+### 经验总结
+
+> **规律**：凡是有"上拉加载更多"功能的页面，在 `onShow` 中刷新列表前必须先重置分页三件套：`page=1`、`hasMore=true`、`list=[]`。删除/更新后的刷新也要重置，而不是继续从当前页追加。
+
+---
+
+## R2-02：多个页面 scroll-view 无法滚动（scroll-y 属性失效）
+
+### 现象
+
+安卓端页面列表区域无法下滑，内容被截断，只能看到屏幕内的部分。
+
+### 出现位置
+
+以下 7 个页面同时存在：
+
+- `products.uvue`（商品管理）
+- `reviews.uvue`（评价管理）
+- `members.uvue`（会员管理）
+- `inventory.uvue`（库存管理）
+- `promotions.uvue`（促销管理）
+- `chat.uvue`（聊天）
+- `exclusive-discounts.uvue`（专属折扣）
+
+### 问题类型
+
+安卓端布局 / 滚动容器
+
+### 根因分析
+
+模板中使用了 HTML/Web 风格的 `scroll-y` 布尔属性：
+
+```html
+<!-- ❌ Web 写法，Android 端不识别 -->
+<scroll-view scroll-y class="list-container"></scroll-view>
+```
+
+在 uni-app x 安卓端，`scroll-view` 的滚动方向必须通过 `direction` 属性指定，而不是 `scroll-y` / `scroll-x` 布尔属性。
+
+### 为什么会这样
+
+`scroll-y` 是 uni-app（老版本）和微信小程序的写法，继承自 Web 规范。uni-app **x** 的 Android 原生渲染器重新设计了滚动 API，改用 `direction="vertical"` / `direction="horizontal"`，旧属性在安卓端被完全忽略（不报错，只是不生效）。
+
+### 修复方式
+
+批量将 `scroll-y` 替换为 `direction="vertical"`：
+
+```html
+<!-- ✅ Android 端正确写法 -->
+<scroll-view direction="vertical" class="list-container"></scroll-view>
+```
+
+同时确保父容器有 `overflow: hidden`，scroll-view 本身有 `flex: 1`：
+
+```css
+.list-container {
+  flex: 1;
+  overflow: hidden; /* 必须，否则高度无法约束 */
+}
+```
+
+### 涉及文件
+
+上述 7 个页面均已修改。
+
+### 经验总结
+
+> **规律**：uni-app x Android 端，`scroll-view` 必须用 `direction="vertical"` 指定滚动方向，禁止使用 `scroll-y` 属性。同时父容器必须有 `overflow: hidden`，否则 scroll-view 会展开为内容全高，表现为"可以看到全部内容但没有滚动效果"。
+
+---
+
+## R2-03/R2-04/R2-05/R2-06/R2-07：底部白屏 / 内容被遮挡（position:fixed 失效 + 高度链断裂）
+
+### 现象
+
+- `live.uvue`：页面底部有大块白屏
+- `product-edit.uvue`：底部提交栏遮挡内容，或底部留有大段空白
+- `shop-edit.uvue`：同上
+- `product-detail.uvue`：底部操作按钮区遮挡商品信息
+- `exclusive-discounts.uvue`：列表无法滚动，底部截断
+
+### 出现位置
+
+见各页面文件。
+
+### 问题类型
+
+安卓端布局 / 滚动容器 / position:fixed
+
+### 根因分析
+
+**问题一：`position: fixed` 在安卓端非根视图中不可靠**
+
+```css
+/* ❌ 旧写法：submit-bar 用 fixed 定位 */
+.submit-bar {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+}
+```
+
+在 Web 浏览器中，`position: fixed` 相对于视口固定。在 Android uni-app x 中，如果页面根视图不是全屏（有 scroll-view 父容器等），`fixed` 定位的参照系会计算错误，导致按钮出现在错误位置或遮挡内容。
+
+**问题二：根容器使用 `min-height: 100%` 导致高度链断裂**
+
+```css
+/* ❌ 旧写法 */
+.page {
+  min-height: 100%;
+}
+```
+
+`min-height: 100%` 给元素设置了"至少等于视口高度"的约束，但没有给子元素提供可继承的明确高度。Android 原生布局计算时，子 scroll-view 的 `flex: 1` 无法找到参照高度，实际高度为 0，内容溢出到视口之外造成白屏。
+
+### 修复方式
+
+**统一修复模式（所有含提交栏 / 操作栏的页面）**：
+
+```css
+/* ✅ 正确的 flex 列布局 */
+.page {
+  height: 100%; /* 明确高度，不用 min-height */
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.form-scroll {
+  flex: 1; /* 占满剩余空间，可滚动 */
+  overflow: hidden;
+}
+
+.submit-bar {
+  flex-shrink: 0; /* 不缩小，始终在底部 */
+  /* 不再使用 position: fixed */
+  padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+**live.uvue 的修复**（无提交栏，只有高度链问题）：
+
+```css
+.page {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.scroll {
+  flex: 1; /* 不再用 min-height */
+}
+```
+
+### 涉及文件
+
+- `d:\骅锋\mall\pages\mall\merchant\live.uvue`
+- `d:\骅锋\mall\pages\mall\merchant\product-edit.uvue`
+- `d:\骅锋\mall\pages\mall\merchant\shop-edit.uvue`
+- `d:\骅锋\mall\pages\mall\merchant\product-detail.uvue`
+- `d:\骅锋\mall\pages\mall\merchant\exclusive-discounts.uvue`
+
+### 经验总结
+
+> **规律**：含底部固定栏（提交按钮/操作按钮）的页面，统一用 flex 列布局：根容器 `height:100% + flex-column + overflow:hidden` → 内容区 `flex:1 + overflow:hidden` → 底部栏 `flex-shrink:0`。彻底放弃 `position:fixed`，彻底放弃 `min-height:100%`。
+
+---
+
+## R2-08/R2-09：页面入口标题与页面内标题不一致
+
+### 现象
+
+- 点击"发布商品"入口进入后，页面标题显示"商品编辑"（而非"发布商品"）
+- 点击"店铺设置"入口进入后，页面标题显示"店铺资料"（而非"店铺设置"）
+
+### 出现位置
+
+- `pages/mall/merchant/product-edit.uvue`
+- `pages/mall/merchant/shop-edit.uvue`
+
+### 问题类型
+
+页面配置 / 标题硬编码
+
+### 根因分析
+
+**product-edit.uvue**：`<MerchantNavBar title="商品编辑" />` 硬编码，无论是"发布新商品"还是"编辑已有商品"，标题始终是"商品编辑"。页面实际有 `isEdit` 状态字段区分两种场景，但未绑定到标题。
+
+**shop-edit.uvue**：`<MerchantNavBar title="店铺资料" />`，而首页入口按钮文字是"店铺设置"，两者不一致，让用户感觉进错了页面。
+
+### 修复方式
+
+**product-edit.uvue**：改为动态标题：
+
+```html
+<MerchantNavBar :title="isEdit ? '商品编辑' : '发布商品'" />
+```
+
+**shop-edit.uvue**：统一改为"店铺设置"：
+
+```html
+<MerchantNavBar title="店铺设置" />
+```
+
+### 涉及文件
+
+- `d:\骅锋\mall\pages\mall\merchant\product-edit.uvue`
+- `d:\骅锋\mall\pages\mall\merchant\shop-edit.uvue`
+
+### 经验总结
+
+> **规律**：页面标题不能在开发期随意硬编码，必须与调用方（首页/列表页的入口按钮文字、路由注释）保持一致。有多种进入场景（新建/编辑）的页面，必须用响应式绑定 `:title="..."` 而不是静态字符串。
+
+---
+
+## R2-10/R2-11/R2-12：会员管理页三连 Bug
+
+### 问题背景
+
+`members.uvue` 同时存在三个独立 Bug，用户体验表现为：无法添加等级、删除等级无效、页面无法滑动。
+
+---
+
+### R2-10：添加等级按钮无效（死变量）
+
+**现象**：点击"＋ 添加等级"，弹窗不出现，没有任何响应。
+
+**根因**：  
+按钮绑定了 `showAddLevel = true`，但弹窗用的是 `v-if="showEditModal"`——两个完全不同的变量。`showAddLevel` 是死变量，没有任何地方读它。
+
+```html
+<!-- ❌ 旧写法：设置了死变量 -->
+<text @click="showAddLevel = true">＋ 添加等级</text>
+
+<!-- ✅ 修复后：调用方法 -->
+<text @click="openAddLevel">＋ 添加等级</text>
+```
+
+**修复**：新增 `openAddLevel()` 方法，重置 `currentLevel` 为空状态后设置 `showEditModal = true`：
+
+```typescript
+openAddLevel() {
+  this.currentLevel = {
+    id: '',
+    name: '',
+    discount_rate: 0.85,
+    level_rank: this.levels.length + 1
+  } as MemberLevel
+  this.showEditModal = true
+},
+```
+
+同时删除 `data()` 中的死字段 `showAddLevel: false`，替换为 `showDeleteModal: false` 和 `pendingDeleteId: ''`。
+
+---
+
+### R2-11：删除等级无效（uni.showModal 回调在 Kotlin 中不执行）
+
+**现象**：点击"删除"，确认弹窗出现（`uni.showModal`），点击"确认"，什么都没发生，等级没有被删除。
+
+**根因**：
+
+```typescript
+// ❌ 旧写法
+deleteLevel(id: string) {
+  uni.showModal({
+    success: (res: UniShowModalResult): void => {
+      if (res.confirm === true) {
+        void this._doDeleteLevel(id)  // ← 这里有两个问题
+      }
+    }
+  })
+}
+```
+
+**两个叠加问题**：
+
+1. **`this` 捕获失败**：`uni.showModal` 的 `success` 回调是一个 `void lambda`，UTS 编译为 Kotlin 时会变成跨线程的异步回调（Kotlin 协程中的 `suspend` 上下文切换），`this` 引用在回调执行时可能已失效。
+
+2. **`void this._doDeleteLevel(id)` 不可靠**：在非 `suspend` 的 `void lambda` 中调用 `async` 方法（编译后是 Kotlin suspend fun），UTS 不保证 `.then()`/`void` 的执行。实际表现是：回调被丢弃，`_doDeleteLevel` 从未执行。
+
+**修复**：用响应式状态弹窗完全替代 `uni.showModal` 回调模式：
+
+```typescript
+// ✅ 修复后：响应式模态框
+deleteLevel(id: string) {
+  this.pendingDeleteId = id
+  this.showDeleteModal = true
+},
+async confirmDelete() {
+  this.showDeleteModal = false
+  await this._doDeleteLevel(this.pendingDeleteId)
+  this.pendingDeleteId = ''
+},
+```
+
+模板中新增删除确认弹窗：
+
+```html
+<view class="modal" v-if="showDeleteModal">
+  <view class="modal-content">
+    <view class="modal-title">确认删除</view>
+    <text class="modal-desc"
+      >删除后该等级下所有用户等级将同步清空，是否继续？</text
+    >
+    <view class="modal-btns">
+      <text class="btn cancel" @click="showDeleteModal = false">取消</text>
+      <text class="btn danger" @click="confirmDelete">删除</text>
+    </view>
+  </view>
+</view>
+```
+
+---
+
+### R2-12：会员管理页面无法滑动
+
+**现象**：等级列表和客户列表不能下滑查看。
+
+**根因**：
+
+```css
+/* ❌ 旧写法：缺少 overflow: hidden */
+.list-container {
+  padding: 20rpx;
+  flex: 1;
+}
+```
+
+`flex: 1` 让容器占据剩余高度，但没有 `overflow: hidden`，Android 原生渲染器不约束 scroll-view 的高度，scroll-view 展开为内容全高，所有内容都"可见"了，但也就不需要滚动，表现为无法滑动。
+
+**修复**：
+
+```css
+.list-container {
+  padding: 20rpx;
+  flex: 1;
+  overflow: hidden;
+}
+```
+
+---
+
+### 涉及文件
+
+`d:\骅锋\mall\pages\mall\merchant\members.uvue`
+
+---
+
+## R2-13/R2-14：退出商家端无效（settings.uvue + App.uvue 双重问题）
+
+### 现象
+
+点击"设置 → 退出商家端"，确认后：
+
+- 有时什么都没发生
+- 有时跳到登录页，但重新打开 App 又直接进入商家端
+- 始终无法彻底退出
+
+### 出现位置
+
+- `pages/mall/merchant/settings.uvue`（退出入口）
+- `App.uvue`（启动恢复逻辑）
+
+### 问题类型
+
+路由问题 + 异步回调 + 状态管理
+
+---
+
+### R2-13：settings.uvue 退出逻辑使用 Promise.then 回调链，在 Kotlin void lambda 中不执行
+
+**根因**（与 R2-11 完全相同的根本原因）：
+
+```typescript
+// ❌ 旧写法
+confirmLogout() {
+  uni.showModal({
+    success: (res: UniShowModalResult): void => {
+      if (res.confirm === true) {
+        supa.signOut().then(() => {         // ← 问题核心
+          uni.removeStorageSync('user_id')
+          // ... 更多清理 ...
+          uni.reLaunch({ url: '/pages/user/login' })
+        }).catch(() => {
+          // ...
+        })
+      }
+    }
+  })
+}
+```
+
+`supa.signOut()` 返回 `Promise`，在 `uni.showModal` 的 `void lambda` 中调用 `.then()/.catch()` 链，UTS 编译到 Kotlin 后，这个 Promise 链在非 suspend 上下文中**不保证执行**。实际结果是：`.then()` 里的所有清理代码一行都不执行。
+
+**修复**：完全弃用 `uni.showModal` 回调，改为响应式模态框 + `async doLogout()` 方法：
+
+```typescript
+data() {
+  return { showLogoutModal: false }
+},
+methods: {
+  confirmLogout() {
+    this.showLogoutModal = true
+  },
+  async doLogout() {
+    this.showLogoutModal = false
+    uni.showLoading({ title: '退出中...' })
+    try {
+      await supa.signOut()       // await 保证执行顺序
+    } catch (_) {}
+    // 清理所有登录态 / 商家态 storage key
+    uni.removeStorageSync('akreq_access_token')
+    uni.removeStorageSync('akreq_refresh_token')
+    uni.removeStorageSync('akreq_expires_at')
+    uni.removeStorageSync('user_id')
+    uni.removeStorageSync('userInfo')
+    uni.removeStorageSync('merchant_id')
+    uni.removeStorageSync('merchant_idx_cache')
+    uni.removeStorageSync('merchant_orders_pending_tab')
+    uni.removeStorageSync('uni_push2_cid')
+    // 清除 store 内存态，防止 App.uvue 恢复逻辑误判
+    setIsLoggedIn(false)
+    setUserProfile({ username: '', email: '' })
+    uni.hideLoading()
+    uni.reLaunch({ url: '/pages/user/login' })
+  }
+}
+```
+
+---
+
+### R2-14：App.uvue checkExistingSession 会把用户重新拉回商家端
+
+**根因**：即使 `settings.uvue` 的退出成功跳到了登录页，下次 App 冷启动时，`App.uvue` 的 `checkExistingSession()` 还是会把用户送回商家端。
+
+`checkExistingSession()` 的逻辑（简化）：
+
+```typescript
+checkExistingSession() {
+  // 路径一：内存 session 存在
+  const session = supa.getSession()
+  if (session.user != null) {
+    uni.reLaunch({ url: '/pages/mall/merchant/index' })  // ← 拉回
+    return
+  }
+  // 路径二：storage 中有 user_id
+  const savedUserId = uni.getStorageSync('user_id')
+  if (savedUserId != null && savedUserId != '') {
+    getCurrentUser().then((profile) => {
+      if (profile != null) {
+        uni.reLaunch({ url: '/pages/mall/merchant/index' })  // ← 拉回
+      }
+    })
+  }
+}
+```
+
+**为什么旧的退出后仍被拉回**：
+
+| 检查项                        | 旧退出逻辑的问题                                        | 修复后的状态                             |
+| ----------------------------- | ------------------------------------------------------- | ---------------------------------------- |
+| `supa.session` 内存对象       | `supa.signOut()` 未执行（.then 不执行），session 仍存在 | `await supa.signOut()` 确保 session=null |
+| `akreq_access_token` storage  | `.then()` 未执行，未清除                                | `removeStorageSync` 在 async 方法中执行  |
+| `user_id` storage             | 同上                                                    | 同上清除                                 |
+| store.uts `isLoggedIn` 内存态 | 从未清除                                                | 新增 `setIsLoggedIn(false)`              |
+
+修复后，`checkExistingSession` 的两条路径均失效：
+
+- `supa.getSession().user` = null（session 已清除）
+- `uni.getStorageSync('user_id')` = null（storage 已清除）
+- 用户停留在登录页，不再被拉回
+
+### 涉及文件
+
+- `d:\骅锋\mall\pages\mall\merchant\settings.uvue`（主要修改）
+- `d:\骅锋\mall\App.uvue`（无需改动，确认其逻辑本身正确，只要 storage 清干净就不会触发）
+
+### 退出后清理的完整 storage key 清单
+
+| Key                           | 说明                                    |
+| ----------------------------- | --------------------------------------- |
+| `akreq_access_token`          | JWT 访问令牌（AkReq 内存+storage 双写） |
+| `akreq_refresh_token`         | 刷新令牌                                |
+| `akreq_expires_at`            | 令牌过期时间戳                          |
+| `user_id`                     | 用户业务 ID（App.uvue 恢复的判断依据）  |
+| `userInfo`                    | 用户信息缓存                            |
+| `merchant_id`                 | 商家 ID                                 |
+| `merchant_idx_cache`          | 商家首页骨架屏缓存                      |
+| `merchant_orders_pending_tab` | 订单页 tab 状态                         |
+| `uni_push2_cid`               | 推送客户端 ID                           |
+
+### 经验总结
+
+> **规律**：在 UTS 中，凡是需要在用户交互后执行异步操作（清缓存、signOut、网络请求）的场景，必须使用 `async method` + `await`，**不能依赖 `uni.showModal` / `uni.showActionSheet` 等系统弹窗的 `success` 回调中的 Promise 链**。系统弹窗回调是 `void lambda`，在 Kotlin 非 suspend 上下文中，Promise/.then/.catch 的执行不被保证。
+>
+> **退出登录的完整清理清单**：token（access+refresh+expires）+ 用户信息 + 商家 ID + 首页缓存 + 角色缓存 + store 内存态，缺一不可。
+
+---
+
+## R2-15：members.uvue 编译失败（缺少 import supa 和 type MemberLevel）
+
+### 现象
+
+HBuilderX 报编译错误，Android Studio Kotlin 编译报大量 `Unresolved reference: supa`、`Unresolved reference: MemberLevel`、`Unresolved reference: id/name/discount_rate` 等。
+
+### 根因
+
+在一次多文件修复操作中，向 `members.uvue` 的 `<script>` 区域注入了新代码，但同时不小心把原有的 `import supa` 和 `type MemberLevel` 定义移除了（或从未加入）。
+
+Kotlin 编译器对每一个符号引用都要求有对应的定义，`supa` 是全局数据库实例（80+ 处引用），`MemberLevel` 是数据类型（70+ 处引用），全部 unresolved。
+
+### 修复方式
+
+在 `<script lang="uts">` 开头补回：
+
+```typescript
+<script lang="uts">
+  import supa from '@/components/supadb/aksupainstance.uts'
+
+  type MemberLevel = {
+    id: string
+    name: string
+    discount_rate: number
+    level_rank: number
+  }
+
+  type UserInfo = {
+    // ...
+  }
+```
+
+### 涉及文件
+
+`d:\骅锋\mall\pages\mall\merchant\members.uvue`
+
+### 经验总结
+
+> **规律**：每次对 `.uvue` 文件进行多处批量替换后，必须检查：① `import` 语句是否完整 ② 自定义 `type` 定义是否存在 ③ `<template>` / `<script>` / `<style>` 三段式结构是否完整（可用 `Select-String` 快速验证）。
+
+---
+
+## R2-16：members.uvue 模板结构损坏（`</template>` 缺失）
+
+### 现象
+
+HBuilderX 编译报错：
+
+```
+[uni:app-uvue] Invalid end tag.
+file: members.uvue:492:1
+```
+
+第 492 行是 `</script>`，错误表明编译器在读到 `</script>` 时还没有找到对应的 `</template>` 关闭标签。
+
+### 根因
+
+在添加"删除等级确认弹窗"时，多文件替换操作的 `oldString` 匹配了包含 `</view>\n\t</view>\n</template>` 的区块，但生成的 `newString` 重新排布后，模板的 `</view></template>` 结构被混入了 `<script>` 的 `type UserInfo = {` 定义，导致 `<template>` 提前在错误位置"关闭"，而真正的 `</template>` 标签丢失。
+
+实际损坏状态：
+
+```html
+<!-- 模板区域内容 -->
+    </view>
+  }   ← 这里本应是 </view></template>，变成了 script 内容
+
+  type UserInfo = {   ← script 内容出现在 template 区域
+```
+
+### 修复方式
+
+手工在模板末尾（`</view></view>` 和 `<script>` 之间）补回缺失的 `</view>\n</template>` 结构，并清除误混入的 `}` 字符，使 `<template>` 正常闭合。
+
+### 涉及文件
+
+`d:\骅锋\mall\pages\mall\merchant\members.uvue`
+
+### 经验总结
+
+> **规律**：对包含 `</template>`、`</script>`、`</style>` 这类文档级边界标签的替换操作，**oldString 不应包含这些边界标签**；应该只替换边界内部的内容，让边界标签保持原位不动。批量替换后，必须用 `Select-String -Pattern "template|/template|script|/script"` 验证三段式结构完整性。
+
+---
+
+## 第二轮通用修复规律总结
+
+### 规律一：`uni.showModal` / `uni.showActionSheet` 回调中不能用 Promise 链
+
+| ❌ 旧模式                                    | ✅ 新模式                                 |
+| -------------------------------------------- | ----------------------------------------- |
+| `success: (res) => { asyncFn().then(...) }`  | 响应式状态弹窗 + `async method` + `await` |
+| `void this._doSomething()` 在 void lambda 中 | 在组件的 `async method` 中直接 `await`    |
+
+**影响页面**：settings.uvue（退出）、members.uvue（删除等级）、任何需要在系统弹窗确认后执行异步操作的页面。
+
+### 规律二：安卓端三大滚动/布局模式
+
+| 场景             | 正确模式                                                                            |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| 纯列表页         | 根 `height:100% flex-column overflow:hidden` + scroll-view `flex:1 overflow:hidden` |
+| 含底部操作栏     | 同上 + 操作栏 `flex-shrink:0`（不用 position:fixed）                                |
+| scroll-view 方向 | `direction="vertical"` 不是 `scroll-y`                                              |
+
+### 规律三：退出登录必须三清
+
+1. **清 Supabase 内存 session**：`await supa.signOut()`
+2. **清所有 storage key**：token × 3 + user_id + 商家相关 key × 4
+3. **清 store 内存态**：`setIsLoggedIn(false)` + `setUserProfile({...})`
+
+缺任何一步，App 启动时的恢复逻辑都可能把用户重新送回商家端。
+
+### 规律四：onShow 中刷新列表必须先重置分页
+
+```typescript
+onShow() {
+  this.page = 1       // 必须
+  this.hasMore = true // 必须
+  this.list = []      // 必须
+  this.loadData()
+}
+```
+
+### 规律五：多处批量替换后的必检项
+
+```powershell
+# 检查三段式结构完整性
+Select-String -Path "xxx.uvue" -Pattern "^<template>|^</template>|^<script|^</script>|^<style|^</style>"
+
+# 检查关键 import 是否存在
+Select-String -Path "xxx.uvue" -Pattern "import supa|type MemberLevel"
+```
+
+---
+
+## 第二轮未解决问题（需后续跟进）
+
+| 序号 | 问题                                                                 | 当前状态                                             | 建议                                               |
+| ---- | -------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------- |
+| P-01 | 消息中心/聊天功能结构未完善                                          | 页面存在但功能简陋，未实现会话列表/未读标记/订单关联 | 参考正规电商商家端重新设计消息架构                 |
+| P-02 | 扫码功能未实现                                                       | `scan.uvue` 页面存在但功能为占位符                   | 接入 `uni.scanCode` API                            |
+| P-03 | 会员客户列表加载时出现"暂无客户"再显示数据（loading/empty 状态混淆） | 已知但未在本轮修复                                   | 添加 `isLoading` 状态，loading 中不显示 empty 状态 |
+| P-04 | uni-app SDK AAR 依赖缺失（延续自第一轮 §5.7）                        | 涉及 `uni_showModal` 等 API 的 Kotlin 符号缺失       | 从 HBuilderX 本地资源包补充 AAR 到 app/libs/       |
+| P-05 | getPushClientId 推送 CID 注册未实现（延续自第一轮 §5.12）            | 待用正确的 UTS 签名重新实现                          | 参考 §5.12 中的修复模板                            |
+
+---
+
+_第二轮记录更新：2026-04-21_
+
+---
+
+# 第三轮消费者端安卓适配补充记录（2026-05-13）
+
+> **本轮时间**：2026-05-13  
+> **调试阶段**：消费者端主路径页面安卓真机适配补充  
+> **背景**：前两轮主要覆盖商家端编译、构建与运行问题；本轮补充处理消费者端首页主链路中的列表滚动与视觉不一致问题，重点是 `购物车`、`我的`、`我的订单` 三个页面。
+
+---
+
+## 第三轮问题总览
+
+| 序号  | 问题名称                           | 页面/模块       | 问题类型 | 是否已解决 | 备注                                                      |
+| ----- | ---------------------------------- | --------------- | -------- | ---------- | --------------------------------------------------------- |
+| R3-01 | 购物车页面无法上下滑动             | consumer/cart   | 安卓布局 | ✅ 已解决  | `100vh + overflow:hidden + scroll-view height:0` 组合失效 |
+| R3-02 | 我的页面无法上下滑动               | consumer/my     | 安卓布局 | ✅ 已解决  | 与购物车同源，scroll-view 未拿到明确高度                  |
+| R3-03 | 我的订单页面无法上下滑动           | consumer/orders | 安卓布局 | ✅ 已解决  | 已计算 viewportHeight，但未绑定到滚动容器                 |
+| R3-04 | 我的页面安卓配色与小程序结果不一致 | consumer/my     | 安卓视觉 | ✅ 已解决  | 渐变与叠层卡片在 Android 原生渲染器中回退异常             |
+
+---
+
+## R3-01/R3-02/R3-03：消费者端主列表页面无法上下滑动（根容器高度链断裂）
+
+### 现象
+
+- `pages/main/cart.uvue`：购物车商品列表和推荐商品区域在安卓端无法下滑
+- `pages/main/profile.uvue`：我的页面钱包、订单、猜你喜欢区域无法下滑
+- `pages/mall/consumer/orders.uvue`：我的订单列表只能显示首屏内容，后续订单无法通过手势下滑查看
+
+### 出现位置
+
+- `d:\骅锋\mall\pages\main\cart.uvue`
+- `d:\骅锋\mall\pages\main\profile.uvue`
+- `d:\骅锋\mall\pages\mall\consumer\orders.uvue`
+
+### 问题类型
+
+安卓端布局 / scroll-view 高度计算
+
+### 根因分析
+
+三个页面的结构本质一致：
+
+```css
+/* ❌ 旧写法的共同模式 */
+.page {
+  height: 100vh;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.content-scroll {
+  flex: 1;
+  height: 0;
+}
+```
+
+在小程序 / H5 中，这类写法通常仍能滚动，因为浏览器会把 `flex: 1` 和 `height: 0` 结合成可收缩的滚动区域；但在 uni-app x 的 Android 原生渲染链路中，`scroll-view` 必须拿到**明确的像素高度**。一旦父容器只给出 `100vh`、内部再靠 `height: 0` 收缩，原生布局引擎就可能把滚动区计算成非 scrollable 容器，最终表现为：
+
+- 页面内容正常渲染
+- 可见区域能显示首屏内容
+- 手指上下滑动无响应
+
+`orders.uvue` 的情况更隐蔽：源码里已经计算了 `viewportHeight`，但该值仅用于虚拟列表可视区估算，没有实际绑定到 `scroll-view` 容器，所以安卓端仍然拿不到真实可滚动高度。
+
+### 修复方式
+
+修复原则统一为：**继续保留原有布局结构，但只在 Android 端为页面根容器和 scroll-view 注入明确像素高度**，避免影响小程序现有表现。
+
+#### 购物车 / 我的页面修复模式
+
+```typescript
+const pageWindowHeight =
+  systemInfo.windowHeight ?? systemInfo.screenHeight ?? 0;
+
+// #ifdef APP-ANDROID
+isAndroidApp.value = true;
+// #endif
+
+const pageStyle = computed((): string => {
+  if (!isAndroidApp.value) return "";
+  if (pageWindowHeight.value <= 0) return "";
+  return (
+    "height:" +
+    pageWindowHeight.value +
+    "px;min-height:" +
+    pageWindowHeight.value +
+    "px;"
+  );
+});
+
+const contentStyle = computed((): string => {
+  if (!isAndroidApp.value) return "";
+  const contentHeight = pageWindowHeight.value - fixedHeaderHeight;
+  return "height:" + contentHeight + "px;min-height:" + contentHeight + "px;";
+});
+```
+
+模板中把样式显式绑定到页面容器和 `scroll-view`：
+
+```html
+<view class="page" :style="pageStyle">
+  <scroll-view
+    class="content-scroll"
+    :style="contentStyle"
+    :scroll-y="true"
+  ></scroll-view>
+</view>
+```
+
+#### 我的订单页面修复模式
+
+`orders.uvue` 已有 `viewportHeight`，所以只需让这个值真正进入滚动容器：
+
+```typescript
+pageWindowHeight.value =
+  systemInfo.windowHeight ?? systemInfo.screenHeight ?? 0;
+const windowHeight = pageWindowHeight.value;
+const calculatedViewport = windowHeight - statusBarHeight.value - 44 - 48;
+viewportHeight.value =
+  calculatedViewport > 0 ? calculatedViewport : windowHeight;
+
+// #ifdef APP-ANDROID
+isAndroidApp.value = true;
+// #endif
+```
+
+```typescript
+const ordersContentStyle = computed((): string => {
+  if (!isAndroidApp.value) return "";
+  if (viewportHeight.value <= 0) return "";
+  return (
+    "height:" +
+    viewportHeight.value +
+    "px;min-height:" +
+    viewportHeight.value +
+    "px;"
+  );
+});
+```
+
+### 涉及文件
+
+- `d:\骅锋\mall\pages\main\cart.uvue`
+- `d:\骅锋\mall\pages\main\profile.uvue`
+- `d:\骅锋\mall\pages\mall\consumer\orders.uvue`
+
+### 经验总结
+
+> **规律**：消费者端主列表页在 Android 上如果出现“首屏能显示、但完全不能滚动”，优先检查是否存在 `height: 100vh + overflow: hidden + scroll-view height: 0/flex:1` 组合。对 uni-app x Android 来说，scroll-view 最稳妥的做法不是依赖 Web 风格的收缩布局，而是给出明确的像素高度。
+>
+> **规范**：有固定头部、筛选条、底部结算栏的页面，Android 端要么使用完整的 `height: 100%` 高度链，要么直接通过 `windowHeight - 固定区域高度` 计算 scroll-view 像素高度；不要只把高度算在 JS 里而不绑定到模板。
+
+---
+
+## R3-04：我的页面安卓端配色与小程序不一致（渐变与叠层卡片回退异常）
+
+### 现象
+
+`pages/main/profile.uvue` 在微信小程序中顶部是明显的红色渐变，会员条是深棕金色；但在安卓真机中，顶部和钱包会员区出现发白、发灰、层次减弱的问题，视觉结果与小程序明显不一致。
+
+### 出现位置
+
+`d:\骅锋\mall\pages\main\profile.uvue`
+
+### 问题类型
+
+安卓端视觉兼容 / CSS 渐变回退
+
+### 根因分析
+
+问题不在数据，而在样式实现方式：页面头部和会员条使用了复杂叠层视觉，核心依赖如下写法：
+
+```css
+/* ❌ 旧写法 */
+.jd-profile-top {
+  background: linear-gradient(180deg, #ff3b30 0%, #ff5a36 60%, #f5f5f5 100%);
+}
+
+.wallet-plus-ribbon {
+  background: linear-gradient(90deg, #5a3a21 0%, #75542f 52%, #a68049 100%);
+}
+```
+
+在小程序端，这类渐变简写可以正常渲染；但在 Android 原生渲染器中，复杂渐变、卡片叠层和浅色蒙版叠加后，容易出现：
+
+- 渐变层未按预期渲染
+- 背景色回退到默认浅色
+- 文本和图标看起来像“发白”“褪色”
+
+这类问题不会报编译错误，属于纯渲染兼容差异。
+
+### 修复方式
+
+处理原则是：**保留小程序端原视觉，同时为 Android 增加稳定的配色回退类**。
+
+#### 步骤一：把单一 `background` 拆成 `background-color + background-image`
+
+```css
+.jd-profile-top {
+  background-color: #ff5a36;
+  background-image: linear-gradient(
+    180deg,
+    #ff3b30 0%,
+    #ff5a36 60%,
+    #f5f5f5 100%
+  );
+}
+
+.wallet-plus-ribbon {
+  background-color: #8a6638;
+  background-image: linear-gradient(
+    90deg,
+    #5a3a21 0%,
+    #75542f 52%,
+    #a68049 100%
+  );
+}
+```
+
+#### 步骤二：只在 Android 端切换到稳定回退样式
+
+```html
+<view
+  class="jd-profile-top"
+  :class="{ 'jd-profile-top-android': isAndroidApp }"
+></view>
+<view
+  class="wallet-plus-ribbon"
+  :class="{ 'wallet-plus-ribbon-android': isAndroidApp }"
+></view>
+```
+
+```css
+.jd-profile-top-android {
+  background-image: none;
+  background-color: #ff5a36;
+}
+
+.wallet-plus-ribbon-android {
+  background-image: none;
+  background-color: #8a6638;
+}
+```
+
+这样做的结果是：
+
+- 小程序端继续保留原来的渐变视觉
+- Android 端使用稳定纯色回退，不再出现大面积发白发灰
+- 端间通过条件类隔离，不互相影响
+
+### 涉及文件
+
+`d:\骅锋\mall\pages\main\profile.uvue`
+
+### 经验总结
+
+> **规律**：uni-app x Android 对复杂 `linear-gradient`、多层卡片叠色和透明蒙版的支持不如小程序稳定。遇到“同一份代码，小程序颜色正常、Android 发灰发白”的情况，应优先怀疑渐变和叠层渲染回退，而不是业务数据或主题变量。
+>
+> **规范**：复杂视觉区域采用“两层策略”最稳妥：默认样式保留渐变，小程序/H5 使用完整视觉；Android 端通过 `#ifdef APP-ANDROID` 或运行时 `isAndroidApp` 类名切换到纯色回退，保证颜色稳定。
+
+---
+
+## 第三轮通用修复规律总结
+
+### 规律一：消费者端主链路页面的 scroll-view 不要依赖浏览器式自适应高度
+
+| 场景                          | 更稳妥的 Android 写法                                              |
+| ----------------------------- | ------------------------------------------------------------------ |
+| 页面只有一个滚动主体          | 根容器显式高度 + scroll-view 显式高度                              |
+| 页面有固定头部 / Tab / 筛选条 | `windowHeight - 固定区域高度` 计算出内容区像素高度                 |
+| 页面内部有虚拟列表            | 虚拟列表 `viewportHeight` 既用于计算，也必须真正绑定到 scroll-view |
+
+### 规律二：端差异优先做“条件运行”而不是直接改公共样式
+
+```typescript
+// #ifdef APP-ANDROID
+isAndroidApp.value = true;
+// #endif
+```
+
+通过端标记切换模板类名或样式字符串，可以保证：
+
+1. Android 端拿到稳定布局/配色
+2. 小程序端保持原有视觉和交互
+3. 后续排查时能快速判断某个问题是不是 Android 专用回退逻辑触发
+
+### 规律三：视觉兼容优先降级到“可控纯色”，不要硬扛复杂渐变
+
+当页面关键区域承担品牌色表达时，Android 端出现颜色失真，优先级应是：
+
+1. 先保证颜色正确
+2. 再保证层次接近
+3. 最后才追求和小程序完全一致的渐变细节
+
+原因很简单：用户首先感知的是“颜色对不对”，其次才是“渐变够不够精致”。
+
+---
+
+_第三轮记录更新：2026-05-13_
+
+
+---
+
+## 13. Delivery 端地址空白问题（PostgreSQL 函数层面）
+
+> **记录时间**：2026-05-28
+> **涉及表**：`ec_care_tasks`、`hss_service_orders`
+> **涉及函数**：`public.delivery_build_order_json(...)`
+> **影响端**：医疗-delivery（配送端订单详情页、路线页）
+
+---
+
+### 13.1 问题现象
+
+Consumer 端下单后，订单详情页地址显示正常。但 Delivery 端的订单详情页（`detail.uvue`）和路线页（`route.uvue`）中，`order.address`、`order.addressDetail` 等地址字段始终为空白。
+
+同时：
+- `elderGender`（性别）和 `elderAge`（年龄）显示正常
+- 只有地址相关字段（`address`、`addressSummary`、`addressDetail`、`fullAddress`、`latitude`、`longitude`）为空
+
+---
+
+### 13.2 数据层背景
+
+本项目存在**双订单存储**：
+
+| 表 | 说明 | 地址字段 |
+|----|------|----------|
+| `ec_care_tasks` | Care 路径（新） | `address_snapshot`（JSONB）、`address_snapshot_json`（JSONB） |
+| `hss_service_orders` | Legacy 路径（旧） | `address_snapshot_json`（JSONB，NOT NULL DEFAULT `'{}'::jsonb`） |
+
+Consumer 端创建订单时，根据 `useAddressSnapshot` 参数决定写入 `address_snapshot` 还是 `address_snapshot_json`。`ec_care_tasks` 表两列同时存在，`hss_service_orders` 表只有 `address_snapshot_json` 列。
+
+Delivery 端通过 RPC 调用 `rpc_delivery_order_list` / `rpc_delivery_dashboard` / `rpc_delivery_order_detail` 获取订单，这些 RPC 内部统一调用 `delivery_build_order_json` 函数来构建返回的 JSON 结构。
+
+---
+
+### 13.3 排查过程
+
+#### 第一轮：怀疑空对象阻断 fallback
+
+最初怀疑 `address_snapshot_json` 列存储了空对象 `'{}'::jsonb`，导致 `COALESCE` 将其视为有效值而跳过 fallback 到 `address_snapshot`。
+
+尝试修复：执行 `20260528_fix_address_fallback.sql`，在 `v_address` 的 `COALESCE` 中加入 `NULLIF` 排除空对象：
+
+```sql
+v_address JSONB := COALESCE(
+    NULLIF(p_raw -> 'address_snapshot_json', '{}'::jsonb),
+    NULLIF(p_raw -> 'address_snapshot_json', 'null'::jsonb),
+    NULLIF(p_raw -> 'address_snapshot', '{}'::jsonb),
+    NULLIF(p_raw -> 'address_snapshot', 'null'::jsonb),
+    '{}'::jsonb
+);
+```
+
+**结果**：执行后 Delivery 端地址仍然空白，修复未生效。
+
+#### 第二轮：诊断脚本定位
+
+创建并执行诊断脚本 `20260528_debug_address.sql`，三个诊断查询：
+
+**诊断1：确认函数版本**
+```sql
+SELECT proname,
+    CASE WHEN prosrc LIKE '%NULLIF(p_raw -> ''address_snapshot_json'', ''{}''::jsonb)%' THEN 'FIXED' ... END AS address_fallback_status,
+    CASE WHEN prosrc LIKE '%|| jsonb_build_object%' THEN 'SPLIT' ELSE 'SINGLE_BLOCK' END AS function_structure
+FROM pg_proc WHERE proname = 'delivery_build_order_json';
+```
+
+结果：`FIXED (含 NULLIF 排除空对象)` + `SPLIT (小块拼接)`。说明函数版本已经是最新修复版。
+
+**诊断2：查看订单地址数据状态**
+```sql
+SELECT id, task_no,
+    COALESCE(address_snapshot_json::TEXT, 'NULL') AS addr_json_raw,
+    COALESCE(address_snapshot::TEXT, 'NULL') AS addr_snap_raw
+FROM public.ec_care_tasks ORDER BY created_at DESC LIMIT 5;
+```
+
+结果：`address_snapshot_json` 全部是 `NULL`，`address_snapshot` **有完整数据**（包含 `fullAddress`、`detailAddress`、`latitude`、`longitude` 等字段）。
+
+**诊断3：直接测试函数输出**
+```sql
+SELECT delivery_build_order_json(to_jsonb(t), '[]'::jsonb, '[]'::jsonb, '[]'::jsonb, NULL, 'care') ->> 'address' AS test_address
+FROM public.ec_care_tasks t ORDER BY created_at DESC LIMIT 1;
+```
+
+结果：`test_address` = **空**，但 `test_gender` = "女"、`test_age` = 78（正常）。
+
+#### 第三轮：逐步拆解 COALESCE
+
+为了确认 `COALESCE` + `NULLIF` 的行为，执行逐步测试：
+
+```sql
+WITH test_data AS (SELECT to_jsonb(t) AS p_raw FROM public.ec_care_tasks t ORDER BY created_at DESC LIMIT 1)
+SELECT 
+    p_raw -> 'address_snapshot_json' AS step1_raw_json_col,        -- NULL
+    NULLIF(p_raw -> 'address_snapshot_json', '{}'::jsonb) AS step2,  -- NULL
+    NULLIF(p_raw -> 'address_snapshot_json', 'null'::jsonb) AS step3, -- NULL
+    p_raw -> 'address_snapshot' AS step4_raw_snap_col,              -- 有完整数据
+    NULLIF(p_raw -> 'address_snapshot', '{}'::jsonb) AS step5,       -- 有完整数据
+    COALESCE(
+        NULLIF(p_raw -> 'address_snapshot_json', '{}'::jsonb),
+        NULLIF(p_raw -> 'address_snapshot_json', 'null'::jsonb),
+        NULLIF(p_raw -> 'address_snapshot', '{}'::jsonb),
+        NULLIF(p_raw -> 'address_snapshot', 'null'::jsonb),
+        '{}'::jsonb
+    ) AS final_v_address                                            -- NULL ❌
+FROM test_data;
+```
+
+**关键发现**：
+- `step5`（单独计算的 `NULLIF`）= **有完整数据的 JSONB 对象**
+- `final_v_address`（同样的表达式嵌套在 `COALESCE` 中）= **NULL**
+
+这说明 **`COALESCE(NULLIF(...))` 的组合在 PostgreSQL 中对 JSONB 类型存在不可预期的行为**。虽然每个子表达式单独执行都正确，但嵌套在 `COALESCE` 内部时，`v_address` 最终变成了 `NULL`。
+
+#### 第四轮：确认 `to_jsonb` 直接访问正常
+
+为了排除 `to_jsonb(t)` 本身的问题，直接测试：
+
+```sql
+SELECT 
+    to_jsonb(t) -> 'address_snapshot' ->> 'fullAddress' AS test_fullAddress,
+    to_jsonb(t) -> 'address_snapshot' ->> 'detailAddress' AS test_detail
+FROM public.ec_care_tasks t ORDER BY created_at DESC LIMIT 1;
+```
+
+结果：`test_fullAddress` = "广东省梅州市梅县区扶大镇新城科技园景逸花园 骅锋科技"，`test_detail` = "骅锋科技"。
+
+**结论：数据完全正常，问题只在函数内部的 `v_address` 赋值逻辑。**
+
+---
+
+### 13.4 根因分析
+
+PostgreSQL 的 `COALESCE` + `NULLIF` 组合在处理 JSONB 类型时存在**隐式类型推断陷阱**：
+
+1. `p_raw -> 'address_snapshot_json'` 返回 SQL `NULL`
+2. `NULLIF(NULL, '{}'::jsonb)` 返回 SQL `NULL`
+3. `NULLIF(NULL, 'null'::jsonb)` 返回 SQL `NULL`
+4. `p_raw -> 'address_snapshot'` 返回有数据的 JSONB 对象
+5. `NULLIF(对象, '{}'::jsonb)` 应该返回该对象
+
+但当这些表达式嵌套在 `COALESCE` 中时，`COALESCE` 的类型统一推断机制与 `NULLIF` 的返回值类型产生了冲突，导致整个表达式最终返回 `NULL` 而非预期的 JSONB 对象。
+
+> 注：此行为在 PostgreSQL 文档中无明确定义，属于 JSONB 类型与 `COALESCE`/`NULLIF` 交互的边界情况。同样的逻辑对 `TEXT`、`INTEGER` 等基础类型工作正常。
+
+---
+
+### 13.5 修复方案
+
+**核心改动**：将 `v_address` 的赋值从 `COALESCE(NULLIF(...))` 改为 `CASE WHEN jsonb_typeof(...) = 'object'`，完全绕过 `COALESCE` + `NULLIF` 的陷阱。
+
+```sql
+-- 旧写法（有bug）
+v_address JSONB := COALESCE(
+    NULLIF(p_raw -> 'address_snapshot_json', '{}'::jsonb),
+    NULLIF(p_raw -> 'address_snapshot_json', 'null'::jsonb),
+    NULLIF(p_raw -> 'address_snapshot', '{}'::jsonb),
+    NULLIF(p_raw -> 'address_snapshot', 'null'::jsonb),
+    '{}'::jsonb
+);
+
+-- 新写法（可靠）
+v_address JSONB := CASE
+    WHEN jsonb_typeof(p_raw -> 'address_snapshot_json') = 'object'
+         AND p_raw -> 'address_snapshot_json' != '{}'::jsonb
+         AND p_raw -> 'address_snapshot_json' != 'null'::jsonb
+    THEN p_raw -> 'address_snapshot_json'
+    WHEN jsonb_typeof(p_raw -> 'address_snapshot') = 'object'
+         AND p_raw -> 'address_snapshot' != '{}'::jsonb
+         AND p_raw -> 'address_snapshot' != 'null'::jsonb
+    THEN p_raw -> 'address_snapshot'
+    ELSE '{}'::jsonb
+END;
+```
+
+**修复文件**：`mall_sql/migrations/20260528_fix_address_v2.sql`
+
+**验证**：
+```sql
+SELECT delivery_build_order_json(to_jsonb(t), '[]'::jsonb, '[]'::jsonb, '[]'::jsonb, NULL, 'care') ->> 'address' AS test_address
+FROM public.ec_care_tasks t ORDER BY created_at DESC LIMIT 1;
+-- 结果："广东省梅州市梅县区扶大镇新城科技园景逸花园 骅锋科技" ✅
+```
+
+---
+
+### 13.6 经验教训
+
+| # | 教训 |
+|---|------|
+| 1 | **不要用 `COALESCE(NULLIF(...))` 处理 JSONB 类型**。PostgreSQL 中 JSONB 与 `COALESCE`/`NULLIF` 的组合行为不稳定，应改用 `CASE WHEN` + `jsonb_typeof()` |
+| 2 | **数据层诊断优先于前端排查**。当 Delivery 端显示空白而 Consumer 端正常时，首先应检查 RPC 函数对同一条数据的实际输出，而不是怀疑前端渲染逻辑 |
+| 3 | **逐步拆解复杂表达式**。`step5` 单独执行正确但 `final_v_address` 为 NULL，说明问题出在表达式嵌套层面，而非数据本身 |
+| 4 | **保留诊断脚本归档**。`20260528_debug_address.sql` 可作为后续类似问题的排查模板 |
+
+---
+
+_第四轮记录更新：2026-05-28_
diff --git a/mall_sql/migrations/20260528_debug_address.sql b/mall_sql/migrations/20260528_debug_address.sql
new file mode 100644
index 00000000..0263e5fa
--- /dev/null
+++ b/mall_sql/migrations/20260528_debug_address.sql
@@ -0,0 +1,66 @@
+-- ============================================
+-- 诊断脚本：定位 delivery 端地址空白问题
+-- 请复制全部内容执行，把结果截图发给我
+-- ============================================
+
+-- 诊断1：确认 delivery_build_order_json 当前版本
+SELECT 
+    proname,
+    CASE 
+        WHEN prosrc LIKE '%NULLIF(p_raw -> ''address_snapshot_json'', ''{}''::jsonb)%' THEN 'FIXED (含 NULLIF 排除空对象)'
+        WHEN prosrc LIKE '%p_raw -> ''address_snapshot''%' THEN 'HAS_FALLBACK 但缺少 NULLIF'
+        ELSE 'NO_FALLBACK (只有 address_snapshot_json)'
+    END AS address_fallback_status,
+    CASE 
+        WHEN prosrc LIKE '%|| jsonb_build_object%' THEN 'SPLIT (小块拼接)'
+        ELSE 'SINGLE_BLOCK (单个大块)'
+    END AS function_structure
+FROM pg_proc 
+WHERE proname = 'delivery_build_order_json';
+
+
+-- 诊断2：查看 ec_care_tasks 最近5条订单的地址数据状态
+SELECT 
+    id,
+    task_no,
+    elder_name,
+    assigned_to,
+    COALESCE(address_snapshot_json::TEXT, 'NULL') AS addr_json_raw,
+    COALESCE(address_snapshot::TEXT, 'NULL') AS addr_snap_raw,
+    CASE 
+        WHEN address_snapshot_json IS NULL THEN 'json_null'
+        WHEN address_snapshot_json = '{}'::jsonb THEN 'json_empty'
+        WHEN address_snapshot_json = 'null'::jsonb THEN 'json_literal_null'
+        ELSE 'json_has_data'
+    END AS json_status,
+    CASE 
+        WHEN address_snapshot IS NULL THEN 'snap_null'
+        WHEN address_snapshot = '{}'::jsonb THEN 'snap_empty'
+        WHEN address_snapshot = 'null'::jsonb THEN 'snap_literal_null'
+        ELSE 'snap_has_data'
+    END AS snap_status
+FROM public.ec_care_tasks
+ORDER BY created_at DESC
+LIMIT 5;
+
+
+-- 诊断3：直接测试 delivery_build_order_json 对最近一条 care 订单的输出
+-- 如果返回的 address 为空字符串，说明函数内部有问题
+SELECT 
+    t.id,
+    t.task_no,
+    delivery_build_order_json(
+        to_jsonb(t),
+        '[]'::jsonb, '[]'::jsonb, '[]'::jsonb, NULL, 'care'
+    ) ->> 'address' AS test_address,
+    delivery_build_order_json(
+        to_jsonb(t),
+        '[]'::jsonb, '[]'::jsonb, '[]'::jsonb, NULL, 'care'
+    ) ->> 'elderGender' AS test_gender,
+    delivery_build_order_json(
+        to_jsonb(t),
+        '[]'::jsonb, '[]'::jsonb, '[]'::jsonb, NULL, 'care'
+    ) ->> 'elderAge' AS test_age
+FROM public.ec_care_tasks t
+ORDER BY t.created_at DESC
+LIMIT 1;
diff --git a/mall_sql/migrations/20260528_diagnose_address.sql b/mall_sql/migrations/20260528_diagnose_address.sql
new file mode 100644
index 00000000..38d10858
--- /dev/null
+++ b/mall_sql/migrations/20260528_diagnose_address.sql
@@ -0,0 +1,30 @@
+-- ============================================
+-- 诊断：查看订单的地址数据
+-- ============================================
+
+-- 查看 ec_care_tasks 中这个订单的地址字段（用订单ID替换 'xxx'）
+SELECT 
+    id,
+    task_no,
+    COALESCE(address_snapshot_json::TEXT, 'NULL') AS address_snapshot_json_raw,
+    COALESCE(address_snapshot::TEXT, 'NULL') AS address_snapshot_raw,
+    CASE 
+        WHEN address_snapshot_json IS NULL THEN 'null'
+        WHEN address_snapshot_json = '{}'::jsonb THEN 'empty_object'
+        ELSE 'has_data'
+    END AS json_status,
+    CASE 
+        WHEN address_snapshot IS NULL THEN 'null'
+        WHEN address_snapshot = '{}'::jsonb THEN 'empty_object'
+        ELSE 'has_data'
+    END AS snapshot_status
+FROM public.ec_care_tasks
+WHERE task_no LIKE '%20260528%'  -- 根据订单号调整
+ORDER BY created_at DESC
+LIMIT 5;
+
+-- 直接测试 delivery_build_order_json 对这条数据的输出
+-- SELECT delivery_build_order_json(
+--     (SELECT to_jsonb(t) FROM public.ec_care_tasks t WHERE t.id = '订单UUID'::uuid),
+--     '[]'::jsonb, '[]'::jsonb, '[]'::jsonb, NULL, 'care'
+-- ) ->> 'address' AS test_address;
diff --git a/mall_sql/migrations/20260528_fix_address_fallback.sql b/mall_sql/migrations/20260528_fix_address_fallback.sql
new file mode 100644
index 00000000..1ff8732c
--- /dev/null
+++ b/mall_sql/migrations/20260528_fix_address_fallback.sql
@@ -0,0 +1,222 @@
+-- ============================================
+-- 修复 delivery 端地址读取问题
+-- 增强 address_snapshot / address_snapshot_json 的兼容性
+-- ============================================
+
+CREATE OR REPLACE FUNCTION public.delivery_build_order_json(
+    p_raw JSONB,
+    p_logs JSONB DEFAULT '[]'::jsonb,
+    p_records JSONB DEFAULT '[]'::jsonb,
+    p_evidence JSONB DEFAULT '[]'::jsonb,
+    p_exception JSONB DEFAULT NULL,
+    p_source TEXT DEFAULT 'legacy'
+)
+RETURNS JSONB
+LANGUAGE plpgsql
+IMMUTABLE
+AS $$
+DECLARE
+    v_service JSONB := COALESCE(p_raw -> 'service_snapshot_json', jsonb_build_object('category', COALESCE(p_raw ->> 'service_category', ''), 'price', COALESCE((p_raw ->> 'service_price')::NUMERIC, 0)));
+    v_address JSONB := COALESCE(
+        NULLIF(p_raw -> 'address_snapshot_json', '{}'::jsonb),
+        NULLIF(p_raw -> 'address_snapshot_json', 'null'::jsonb),
+        NULLIF(p_raw -> 'address_snapshot', '{}'::jsonb),
+        NULLIF(p_raw -> 'address_snapshot', 'null'::jsonb),
+        '{}'::jsonb
+    );
+    v_raw_status TEXT := COALESCE(p_raw ->> 'status', 'assigned');
+    v_normalized_status TEXT;
+    v_front_status TEXT;
+    v_checkin_record JSONB;
+    v_service_record JSONB;
+    v_service_items JSONB;
+    v_record_json JSONB;
+    v_timeline JSONB;
+    v_status_logs JSONB;
+    v_evidence_list JSONB;
+BEGIN
+    IF p_source = 'care' THEN
+        IF COALESCE(p_raw ->> 'accepted_by_family_at', '') <> '' THEN
+            v_normalized_status := 'completed';
+        ELSIF COALESCE(p_raw ->> 'acceptance_pending_at', '') <> '' THEN
+            v_normalized_status := 'pending_acceptance';
+        ELSIF COALESCE(p_raw ->> 'service_started_at', '') <> '' THEN
+            v_normalized_status := 'in_service';
+        ELSIF COALESCE(p_raw ->> 'checked_in_at', '') <> '' THEN
+            v_normalized_status := 'arrived';
+        ELSIF COALESCE(p_raw ->> 'departed_at', '') <> '' THEN
+            v_normalized_status := 'departed';
+        ELSIF COALESCE(p_raw ->> 'accepted_at', '') <> '' THEN
+            v_normalized_status := 'accepted';
+        ELSE
+            v_normalized_status := CASE v_raw_status
+                WHEN 'ORDER_ACCEPTED' THEN 'accepted'
+                WHEN 'ORDER_CHECKED_IN' THEN 'arrived'
+                WHEN 'ORDER_IN_SERVICE' THEN 'in_service'
+                WHEN 'ACCEPTANCE_PENDING' THEN 'pending_acceptance'
+                WHEN 'ORDER_EXCEPTION' THEN 'exception'
+                WHEN 'ORDER_REJECTED' THEN 'rejected'
+                WHEN 'ORDER_CANCELLED' THEN 'cancelled'
+                WHEN 'ORDER_COMPLETED' THEN 'completed'
+                ELSE 'assigned'
+            END;
+        END IF;
+    ELSE
+        v_normalized_status := lower(v_raw_status);
+    END IF;
+
+    v_front_status := public.delivery_front_status(v_normalized_status, p_raw);
+    v_timeline := public.delivery_build_timeline(p_logs);
+    v_status_logs := public.delivery_build_status_logs(p_logs, COALESCE(p_raw ->> 'id', ''));
+    v_evidence_list := public.delivery_build_evidence(p_evidence, COALESCE(p_raw ->> 'id', ''));
+
+    SELECT item INTO v_checkin_record
+    FROM jsonb_array_elements(COALESCE(p_records, '[]'::jsonb)) item
+    WHERE COALESCE(item ->> 'record_type', item ->> 'care_record_type', '') = 'checkin'
+    ORDER BY COALESCE(item ->> 'created_at', '') DESC
+    LIMIT 1;
+
+    SELECT item INTO v_service_record
+    FROM jsonb_array_elements(COALESCE(p_records, '[]'::jsonb)) item
+    WHERE COALESCE(item ->> 'record_type', item ->> 'care_record_type', '') <> 'checkin'
+      AND COALESCE(item ->> 'record_type', item ->> 'care_record_type', '') <> 'review'
+    ORDER BY COALESCE(item ->> 'created_at', '') DESC
+    LIMIT 1;
+
+    IF v_service_record IS NULL THEN
+        v_service_record := v_checkin_record;
+    END IF;
+
+    v_service_items := COALESCE(v_service_record -> 'service_items_json', public.delivery_default_service_items(COALESCE(p_raw ->> 'id', ''), COALESCE(p_raw ->> 'service_name', '')));
+
+    IF v_service_record IS NULL THEN
+        v_record_json := NULL;
+    ELSE
+        v_record_json := jsonb_build_object(
+            'id', COALESCE(v_service_record ->> 'id', ''),
+            'orderId', COALESCE(p_raw ->> 'id', ''),
+            'startTime', COALESCE(v_service_record ->> 'started_at', v_service_record ->> 'service_started_at', ''),
+            'endTime', COALESCE(v_service_record ->> 'finished_at', v_service_record ->> 'service_finished_at', ''),
+            'actualDurationMinutes', COALESCE((v_service_record ->> 'duration_minutes')::INTEGER, (v_service_record ->> 'actual_duration_minutes')::INTEGER, 0),
+            'serviceItems', COALESCE(v_service_items, '[]'::jsonb),
+            'serviceContent', COALESCE(
+                (
+                    SELECT jsonb_agg(elem ->> 'name')
+                    FROM jsonb_array_elements(COALESCE(v_service_items, '[]'::jsonb)) elem
+                    WHERE COALESCE((elem ->> 'completed')::BOOLEAN, false)
+                ),
+                '[]'::jsonb
+            ),
+            'processNote', COALESCE(v_service_record ->> 'summary', v_service_record ->> 'content', ''),
+            'elderStatus', '',
+            'healthMetrics', jsonb_build_object('bloodPressure', '', 'heartRate', '', 'bloodSugar', '', 'bloodOxygen', ''),
+            'materialsUsed', '',
+            'abnormalNote', '',
+            'photos', COALESCE(
+                (
+                    SELECT jsonb_agg(item ->> 'file_url')
+                    FROM jsonb_array_elements(COALESCE(p_evidence, '[]'::jsonb)) item
+                    WHERE COALESCE(item ->> 'phase', '') = 'service'
+                ),
+                '[]'::jsonb
+            ),
+            'staffRemark', COALESCE(v_service_record ->> 'remark', ''),
+            'familyConfirmation', jsonb_build_object('method', 'none', 'code', '', 'signatureName', '', 'signatureUrl', '', 'confirmedAt', ''),
+            'createdAt', COALESCE(v_service_record ->> 'created_at', ''),
+            'updatedAt', COALESCE(v_service_record ->> 'updated_at', '')
+        );
+    END IF;
+
+    RETURN jsonb_build_object(
+        'id', COALESCE(p_raw ->> 'id', ''),
+        'orderNo', COALESCE(NULLIF(p_raw ->> 'task_no', ''), p_raw ->> 'order_no', ''),
+        'serviceType', COALESCE(NULLIF(v_service ->> 'category', ''), '居家服务'),
+        'serviceName', COALESCE(p_raw ->> 'service_name', ''),
+        'serviceCategory', COALESCE(v_service ->> 'category', ''),
+        'serviceItems', COALESCE(v_service_items, '[]'::jsonb),
+        'elderId', COALESCE(p_raw ->> 'elder_id', p_raw ->> 'user_id', ''),
+        'elderName', COALESCE(NULLIF(p_raw ->> 'recipient_name', ''), p_raw ->> 'elder_name', ''),
+        'elderNameMasked', COALESCE(NULLIF(p_raw ->> 'recipient_name', ''), p_raw ->> 'elder_name', ''),
+        'elderGender', COALESCE(NULLIF(p_raw ->> 'elder_gender', ''), p_raw ->> 'recipient_gender', ''),
+        'elderAge', COALESCE((p_raw ->> 'elder_age')::INTEGER, (p_raw ->> 'recipient_age')::INTEGER, 0),
+        'elderPhone', COALESCE(NULLIF(p_raw ->> 'recipient_phone', ''), p_raw ->> 'elder_phone', ''),
+        'elderPhoneMasked', COALESCE(NULLIF(p_raw ->> 'recipient_phone', ''), p_raw ->> 'elder_phone', ''),
+        'fullElderName', COALESCE(NULLIF(p_raw ->> 'recipient_name', ''), p_raw ->> 'elder_name', ''),
+        'fullPhone', COALESCE(NULLIF(p_raw ->> 'recipient_phone', ''), p_raw ->> 'elder_phone', ''),
+        'contactRelation', '家属',
+        'addressSummary', COALESCE(NULLIF(v_address ->> 'fullAddress', ''), NULLIF(v_address ->> 'full_address', ''), NULLIF(v_address ->> 'address', ''), ''),
+        'address', COALESCE(NULLIF(v_address ->> 'fullAddress', ''), NULLIF(v_address ->> 'full_address', ''), NULLIF(v_address ->> 'address', ''), ''),
+        'addressDetail', COALESCE(NULLIF(v_address ->> 'detailAddress', ''), NULLIF(v_address ->> 'detail_address', ''), ''),
+        'fullAddress', COALESCE(NULLIF(v_address ->> 'fullAddress', ''), NULLIF(v_address ->> 'full_address', ''), NULLIF(v_address ->> 'address', ''), ''),
+        'latitude', COALESCE((v_address ->> 'latitude')::NUMERIC, 0),
+        'longitude', COALESCE((v_address ->> 'longitude')::NUMERIC, 0)
+    ) || jsonb_build_object(
+        'appointmentTime', COALESCE(NULLIF(p_raw ->> 'appointment_time', ''), p_raw ->> 'scheduled_at', ''),
+        'appointmentStartTime', COALESCE(NULLIF(p_raw ->> 'appointment_time', ''), p_raw ->> 'scheduled_at', ''),
+        'appointmentEndTime', COALESCE(NULLIF(p_raw ->> 'appointment_time', ''), p_raw ->> 'scheduled_at', ''),
+        'duration', COALESCE((p_raw ->> 'duration_minutes')::INTEGER, 90),
+        'estimatedDuration', COALESCE((p_raw ->> 'duration_minutes')::INTEGER, 90),
+        'price', COALESCE((v_service ->> 'price')::NUMERIC, 0),
+        'staffIncome', COALESCE((v_service ->> 'price')::NUMERIC, 0),
+        'distance', '',
+        'actualStartTime', COALESCE(p_raw ->> 'service_started_at', ''),
+        'actualEndTime', COALESCE(NULLIF(p_raw ->> 'completed_at', ''), p_raw ->> 'service_completed_at', ''),
+        'status', v_front_status,
+        'statusText', public.delivery_status_text(v_front_status),
+        'statusTone', public.delivery_status_tone(v_front_status),
+        'riskTags', '[]'::jsonb,
+        'healthTags', '[]'::jsonb,
+        'careLevel', COALESCE(v_service ->> 'category', ''),
+        'needFamilyPresent', false,
+        'needMaterials', false,
+        'remark', COALESCE(p_raw ->> 'remark', ''),
+        'merchantId', COALESCE(p_raw ->> 'merchant_id', ''),
+        'merchantName', COALESCE(p_raw ->> 'merchant_name', ''),
+        'deliveryStaffId', COALESCE(NULLIF(p_raw ->> 'current_staff_id', ''), p_raw ->> 'assigned_to', ''),
+        'deliveryStaffName', COALESCE(p_raw ->> 'delivery_staff_name', '')
+    ) || jsonb_build_object(
+        'acceptTime', COALESCE(p_raw ->> 'accepted_at', ''),
+        'departTime', COALESCE(p_raw ->> 'departed_at', ''),
+        'arriveTime', COALESCE(NULLIF(p_raw ->> 'arrived_at', ''), p_raw ->> 'checked_in_at', ''),
+        'checkinTime', COALESCE(NULLIF(p_raw ->> 'checked_in_at', ''), p_raw ->> 'arrived_at', ''),
+        'startServiceTime', COALESCE(p_raw ->> 'service_started_at', ''),
+        'finishTime', COALESCE(NULLIF(p_raw ->> 'completed_at', ''), p_raw ->> 'service_completed_at', ''),
+        'cancelReason', COALESCE(p_raw ->> 'cancel_reason', ''),
+        'exceptionType', COALESCE(p_exception ->> 'exception_type', ''),
+        'exceptionDesc', COALESCE(p_exception ->> 'description', p_exception ->> 'remark', ''),
+        'evidenceList', COALESCE(v_evidence_list, '[]'::jsonb),
+        'signatureUrl', '',
+        'signatureName', '',
+        'satisfactionStatus', CASE WHEN v_front_status = 'pending_acceptance' THEN '待验收' WHEN v_front_status = 'completed' THEN '已验收' ELSE '待评价' END,
+        'settlementStatus', CASE WHEN v_front_status = 'completed' THEN '待结算' ELSE '待确认' END,
+        'archiveStatus', '未归档',
+        'createdAt', COALESCE(p_raw ->> 'created_at', ''),
+        'updatedAt', COALESCE(p_raw ->> 'updated_at', ''),
+        'contactName', COALESCE(p_raw ->> 'contact_name', ''),
+        'contactPhone', COALESCE(p_raw ->> 'contact_phone', ''),
+        'notices', '[]'::jsonb,
+        'timeline', COALESCE(v_timeline, '[]'::jsonb),
+        'statusLog', COALESCE(v_status_logs, '[]'::jsonb)
+    ) || jsonb_build_object(
+        'serviceSummary', COALESCE(v_service_record ->> 'summary', v_service_record ->> 'content', ''),
+        'progressNote', COALESCE(v_service_record ->> 'remark', ''),
+        'distanceKm', '',
+        'allowCheckinRadiusMeters', 100,
+        'lastLocation', CASE
+            WHEN v_checkin_record IS NULL THEN NULL
+            ELSE jsonb_build_object(
+                'latitude', COALESCE((v_checkin_record ->> 'latitude')::NUMERIC, (v_checkin_record ->> 'checkin_latitude')::NUMERIC, 0),
+                'longitude', COALESCE((v_checkin_record ->> 'longitude')::NUMERIC, (v_checkin_record ->> 'checkin_longitude')::NUMERIC, 0),
+                'address', COALESCE(v_checkin_record ->> 'location_text', v_checkin_record ->> 'checkin_address', ''),
+                'time', COALESCE(v_checkin_record ->> 'checked_in_at', v_checkin_record ->> 'checkin_time', '')
+            )
+        END,
+        'trackPoints', COALESCE(v_service_record -> 'track_points_json', '[]'::jsonb),
+        'serviceRecord', v_record_json,
+        'abnormalReport', public.delivery_build_abnormal(p_exception, COALESCE(p_raw ->> 'id', ''))
+    );
+END;
+$$;
+
+-- 刷新 PostgREST schema cache
+NOTIFY pgrst, 'reload schema';
diff --git a/mall_sql/migrations/20260528_fix_address_v2.sql b/mall_sql/migrations/20260528_fix_address_v2.sql
new file mode 100644
index 00000000..26be80d7
--- /dev/null
+++ b/mall_sql/migrations/20260528_fix_address_v2.sql
@@ -0,0 +1,227 @@
+-- ============================================
+-- 修复 delivery 端地址读取问题（v2）
+-- 根因：COALESCE + NULLIF 对 JSONB 类型处理不可靠
+-- 改用 CASE WHEN jsonb_typeof() 明确判断有效对象
+-- ============================================
+
+CREATE OR REPLACE FUNCTION public.delivery_build_order_json(
+    p_raw JSONB,
+    p_logs JSONB DEFAULT '[]'::jsonb,
+    p_records JSONB DEFAULT '[]'::jsonb,
+    p_evidence JSONB DEFAULT '[]'::jsonb,
+    p_exception JSONB DEFAULT NULL,
+    p_source TEXT DEFAULT 'legacy'
+)
+RETURNS JSONB
+LANGUAGE plpgsql
+IMMUTABLE
+AS $$
+DECLARE
+    v_service JSONB := COALESCE(p_raw -> 'service_snapshot_json', jsonb_build_object('category', COALESCE(p_raw ->> 'service_category', ''), 'price', COALESCE((p_raw ->> 'service_price')::NUMERIC, 0)));
+    v_address JSONB := CASE
+        WHEN jsonb_typeof(p_raw -> 'address_snapshot_json') = 'object'
+             AND p_raw -> 'address_snapshot_json' != '{}'::jsonb
+             AND p_raw -> 'address_snapshot_json' != 'null'::jsonb
+        THEN p_raw -> 'address_snapshot_json'
+        WHEN jsonb_typeof(p_raw -> 'address_snapshot') = 'object'
+             AND p_raw -> 'address_snapshot' != '{}'::jsonb
+             AND p_raw -> 'address_snapshot' != 'null'::jsonb
+        THEN p_raw -> 'address_snapshot'
+        ELSE '{}'::jsonb
+    END;
+    v_raw_status TEXT := COALESCE(p_raw ->> 'status', 'assigned');
+    v_normalized_status TEXT;
+    v_front_status TEXT;
+    v_checkin_record JSONB;
+    v_service_record JSONB;
+    v_service_items JSONB;
+    v_record_json JSONB;
+    v_timeline JSONB;
+    v_status_logs JSONB;
+    v_evidence_list JSONB;
+BEGIN
+    IF p_source = 'care' THEN
+        IF COALESCE(p_raw ->> 'accepted_by_family_at', '') <> '' THEN
+            v_normalized_status := 'completed';
+        ELSIF COALESCE(p_raw ->> 'acceptance_pending_at', '') <> '' THEN
+            v_normalized_status := 'pending_acceptance';
+        ELSIF COALESCE(p_raw ->> 'service_started_at', '') <> '' THEN
+            v_normalized_status := 'in_service';
+        ELSIF COALESCE(p_raw ->> 'checked_in_at', '') <> '' THEN
+            v_normalized_status := 'arrived';
+        ELSIF COALESCE(p_raw ->> 'departed_at', '') <> '' THEN
+            v_normalized_status := 'departed';
+        ELSIF COALESCE(p_raw ->> 'accepted_at', '') <> '' THEN
+            v_normalized_status := 'accepted';
+        ELSE
+            v_normalized_status := CASE v_raw_status
+                WHEN 'ORDER_ACCEPTED' THEN 'accepted'
+                WHEN 'ORDER_CHECKED_IN' THEN 'arrived'
+                WHEN 'ORDER_IN_SERVICE' THEN 'in_service'
+                WHEN 'ACCEPTANCE_PENDING' THEN 'pending_acceptance'
+                WHEN 'ORDER_EXCEPTION' THEN 'exception'
+                WHEN 'ORDER_REJECTED' THEN 'rejected'
+                WHEN 'ORDER_CANCELLED' THEN 'cancelled'
+                WHEN 'ORDER_COMPLETED' THEN 'completed'
+                ELSE 'assigned'
+            END;
+        END IF;
+    ELSE
+        v_normalized_status := lower(v_raw_status);
+    END IF;
+
+    v_front_status := public.delivery_front_status(v_normalized_status, p_raw);
+    v_timeline := public.delivery_build_timeline(p_logs);
+    v_status_logs := public.delivery_build_status_logs(p_logs, COALESCE(p_raw ->> 'id', ''));
+    v_evidence_list := public.delivery_build_evidence(p_evidence, COALESCE(p_raw ->> 'id', ''));
+
+    SELECT item INTO v_checkin_record
+    FROM jsonb_array_elements(COALESCE(p_records, '[]'::jsonb)) item
+    WHERE COALESCE(item ->> 'record_type', item ->> 'care_record_type', '') = 'checkin'
+    ORDER BY COALESCE(item ->> 'created_at', '') DESC
+    LIMIT 1;
+
+    SELECT item INTO v_service_record
+    FROM jsonb_array_elements(COALESCE(p_records, '[]'::jsonb)) item
+    WHERE COALESCE(item ->> 'record_type', item ->> 'care_record_type', '') <> 'checkin'
+      AND COALESCE(item ->> 'record_type', item ->> 'care_record_type', '') <> 'review'
+    ORDER BY COALESCE(item ->> 'created_at', '') DESC
+    LIMIT 1;
+
+    IF v_service_record IS NULL THEN
+        v_service_record := v_checkin_record;
+    END IF;
+
+    v_service_items := COALESCE(v_service_record -> 'service_items_json', public.delivery_default_service_items(COALESCE(p_raw ->> 'id', ''), COALESCE(p_raw ->> 'service_name', '')));
+
+    IF v_service_record IS NULL THEN
+        v_record_json := NULL;
+    ELSE
+        v_record_json := jsonb_build_object(
+            'id', COALESCE(v_service_record ->> 'id', ''),
+            'orderId', COALESCE(p_raw ->> 'id', ''),
+            'startTime', COALESCE(v_service_record ->> 'started_at', v_service_record ->> 'service_started_at', ''),
+            'endTime', COALESCE(v_service_record ->> 'finished_at', v_service_record ->> 'service_finished_at', ''),
+            'actualDurationMinutes', COALESCE((v_service_record ->> 'duration_minutes')::INTEGER, (v_service_record ->> 'actual_duration_minutes')::INTEGER, 0),
+            'serviceItems', COALESCE(v_service_items, '[]'::jsonb),
+            'serviceContent', COALESCE(
+                (
+                    SELECT jsonb_agg(elem ->> 'name')
+                    FROM jsonb_array_elements(COALESCE(v_service_items, '[]'::jsonb)) elem
+                    WHERE COALESCE((elem ->> 'completed')::BOOLEAN, false)
+                ),
+                '[]'::jsonb
+            ),
+            'processNote', COALESCE(v_service_record ->> 'summary', v_service_record ->> 'content', ''),
+            'elderStatus', '',
+            'healthMetrics', jsonb_build_object('bloodPressure', '', 'heartRate', '', 'bloodSugar', '', 'bloodOxygen', ''),
+            'materialsUsed', '',
+            'abnormalNote', '',
+            'photos', COALESCE(
+                (
+                    SELECT jsonb_agg(item ->> 'file_url')
+                    FROM jsonb_array_elements(COALESCE(p_evidence, '[]'::jsonb)) item
+                    WHERE COALESCE(item ->> 'phase', '') = 'service'
+                ),
+                '[]'::jsonb
+            ),
+            'staffRemark', COALESCE(v_service_record ->> 'remark', ''),
+            'familyConfirmation', jsonb_build_object('method', 'none', 'code', '', 'signatureName', '', 'signatureUrl', '', 'confirmedAt', ''),
+            'createdAt', COALESCE(v_service_record ->> 'created_at', ''),
+            'updatedAt', COALESCE(v_service_record ->> 'updated_at', '')
+        );
+    END IF;
+
+    RETURN jsonb_build_object(
+        'id', COALESCE(p_raw ->> 'id', ''),
+        'orderNo', COALESCE(NULLIF(p_raw ->> 'task_no', ''), p_raw ->> 'order_no', ''),
+        'serviceType', COALESCE(NULLIF(v_service ->> 'category', ''), '居家服务'),
+        'serviceName', COALESCE(p_raw ->> 'service_name', ''),
+        'serviceCategory', COALESCE(v_service ->> 'category', ''),
+        'serviceItems', COALESCE(v_service_items, '[]'::jsonb),
+        'elderId', COALESCE(p_raw ->> 'elder_id', p_raw ->> 'user_id', ''),
+        'elderName', COALESCE(NULLIF(p_raw ->> 'recipient_name', ''), p_raw ->> 'elder_name', ''),
+        'elderNameMasked', COALESCE(NULLIF(p_raw ->> 'recipient_name', ''), p_raw ->> 'elder_name', ''),
+        'elderGender', COALESCE(NULLIF(p_raw ->> 'elder_gender', ''), p_raw ->> 'recipient_gender', ''),
+        'elderAge', COALESCE((p_raw ->> 'elder_age')::INTEGER, (p_raw ->> 'recipient_age')::INTEGER, 0),
+        'elderPhone', COALESCE(NULLIF(p_raw ->> 'recipient_phone', ''), p_raw ->> 'elder_phone', ''),
+        'elderPhoneMasked', COALESCE(NULLIF(p_raw ->> 'recipient_phone', ''), p_raw ->> 'elder_phone', ''),
+        'fullElderName', COALESCE(NULLIF(p_raw ->> 'recipient_name', ''), p_raw ->> 'elder_name', ''),
+        'fullPhone', COALESCE(NULLIF(p_raw ->> 'recipient_phone', ''), p_raw ->> 'elder_phone', ''),
+        'contactRelation', '家属',
+        'addressSummary', COALESCE(NULLIF(v_address ->> 'fullAddress', ''), NULLIF(v_address ->> 'full_address', ''), NULLIF(v_address ->> 'address', ''), ''),
+        'address', COALESCE(NULLIF(v_address ->> 'fullAddress', ''), NULLIF(v_address ->> 'full_address', ''), NULLIF(v_address ->> 'address', ''), ''),
+        'addressDetail', COALESCE(NULLIF(v_address ->> 'detailAddress', ''), NULLIF(v_address ->> 'detail_address', ''), ''),
+        'fullAddress', COALESCE(NULLIF(v_address ->> 'fullAddress', ''), NULLIF(v_address ->> 'full_address', ''), NULLIF(v_address ->> 'address', ''), ''),
+        'latitude', COALESCE((v_address ->> 'latitude')::NUMERIC, 0),
+        'longitude', COALESCE((v_address ->> 'longitude')::NUMERIC, 0)
+    ) || jsonb_build_object(
+        'appointmentTime', COALESCE(NULLIF(p_raw ->> 'appointment_time', ''), p_raw ->> 'scheduled_at', ''),
+        'appointmentStartTime', COALESCE(NULLIF(p_raw ->> 'appointment_time', ''), p_raw ->> 'scheduled_at', ''),
+        'appointmentEndTime', COALESCE(NULLIF(p_raw ->> 'appointment_time', ''), p_raw ->> 'scheduled_at', ''),
+        'duration', COALESCE((p_raw ->> 'duration_minutes')::INTEGER, 90),
+        'estimatedDuration', COALESCE((p_raw ->> 'duration_minutes')::INTEGER, 90),
+        'price', COALESCE((v_service ->> 'price')::NUMERIC, 0),
+        'staffIncome', COALESCE((v_service ->> 'price')::NUMERIC, 0),
+        'distance', '',
+        'actualStartTime', COALESCE(p_raw ->> 'service_started_at', ''),
+        'actualEndTime', COALESCE(NULLIF(p_raw ->> 'completed_at', ''), p_raw ->> 'service_completed_at', ''),
+        'status', v_front_status,
+        'statusText', public.delivery_status_text(v_front_status),
+        'statusTone', public.delivery_status_tone(v_front_status),
+        'riskTags', '[]'::jsonb,
+        'healthTags', '[]'::jsonb,
+        'careLevel', COALESCE(v_service ->> 'category', ''),
+        'needFamilyPresent', false,
+        'needMaterials', false,
+        'remark', COALESCE(p_raw ->> 'remark', ''),
+        'merchantId', COALESCE(p_raw ->> 'merchant_id', ''),
+        'merchantName', COALESCE(p_raw ->> 'merchant_name', ''),
+        'deliveryStaffId', COALESCE(NULLIF(p_raw ->> 'current_staff_id', ''), p_raw ->> 'assigned_to', ''),
+        'deliveryStaffName', COALESCE(p_raw ->> 'delivery_staff_name', '')
+    ) || jsonb_build_object(
+        'acceptTime', COALESCE(p_raw ->> 'accepted_at', ''),
+        'departTime', COALESCE(p_raw ->> 'departed_at', ''),
+        'arriveTime', COALESCE(NULLIF(p_raw ->> 'arrived_at', ''), p_raw ->> 'checked_in_at', ''),
+        'checkinTime', COALESCE(NULLIF(p_raw ->> 'checked_in_at', ''), p_raw ->> 'arrived_at', ''),
+        'startServiceTime', COALESCE(p_raw ->> 'service_started_at', ''),
+        'finishTime', COALESCE(NULLIF(p_raw ->> 'completed_at', ''), p_raw ->> 'service_completed_at', ''),
+        'cancelReason', COALESCE(p_raw ->> 'cancel_reason', ''),
+        'exceptionType', COALESCE(p_exception ->> 'exception_type', ''),
+        'exceptionDesc', COALESCE(p_exception ->> 'description', p_exception ->> 'remark', ''),
+        'evidenceList', COALESCE(v_evidence_list, '[]'::jsonb),
+        'signatureUrl', '',
+        'signatureName', '',
+        'satisfactionStatus', CASE WHEN v_front_status = 'pending_acceptance' THEN '待验收' WHEN v_front_status = 'completed' THEN '已验收' ELSE '待评价' END,
+        'settlementStatus', CASE WHEN v_front_status = 'completed' THEN '待结算' ELSE '待确认' END,
+        'archiveStatus', '未归档',
+        'createdAt', COALESCE(p_raw ->> 'created_at', ''),
+        'updatedAt', COALESCE(p_raw ->> 'updated_at', ''),
+        'contactName', COALESCE(p_raw ->> 'contact_name', ''),
+        'contactPhone', COALESCE(p_raw ->> 'contact_phone', ''),
+        'notices', '[]'::jsonb,
+        'timeline', COALESCE(v_timeline, '[]'::jsonb),
+        'statusLog', COALESCE(v_status_logs, '[]'::jsonb)
+    ) || jsonb_build_object(
+        'serviceSummary', COALESCE(v_service_record ->> 'summary', v_service_record ->> 'content', ''),
+        'progressNote', COALESCE(v_service_record ->> 'remark', ''),
+        'distanceKm', '',
+        'allowCheckinRadiusMeters', 100,
+        'lastLocation', CASE
+            WHEN v_checkin_record IS NULL THEN NULL
+            ELSE jsonb_build_object(
+                'latitude', COALESCE((v_checkin_record ->> 'latitude')::NUMERIC, (v_checkin_record ->> 'checkin_latitude')::NUMERIC, 0),
+                'longitude', COALESCE((v_checkin_record ->> 'longitude')::NUMERIC, (v_checkin_record ->> 'checkin_longitude')::NUMERIC, 0),
+                'address', COALESCE(v_checkin_record ->> 'location_text', v_checkin_record ->> 'checkin_address', ''),
+                'time', COALESCE(v_checkin_record ->> 'checked_in_at', v_checkin_record ->> 'checkin_time', '')
+            )
+        END,
+        'trackPoints', COALESCE(v_service_record -> 'track_points_json', '[]'::jsonb),
+        'serviceRecord', v_record_json,
+        'abnormalReport', public.delivery_build_abnormal(p_exception, COALESCE(p_raw ->> 'id', ''))
+    );
+END;
+$$;
+
+-- 刷新 PostgREST schema cache
+NOTIFY pgrst, 'reload schema';