# 安卓端调试成功全过程问题总结与修复指南

> **文档类型**：经验沉淀文档（非简单周报）  
> **维护人**：黄镇堡  
> **最后更新**：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_