android2harmony 0.1.0

package/skills/hmos-fix-build-errors/references/rdb-entity-pattern.md

@@ -0,0 +1,131 @@
+# RDB Entity 确定性修复 Pattern
+# 适用于: ArkTS 严格模式 + @kit.ArkData relationalStore
+# 触发场景: 迁移 Android RDB 实体类到 ArkTS 时
+# 经验来源: EinkBro 迁移 (2026-03-26)
+
+---
+
+## Pattern 1: ValuesBucket 正确用法
+
+### 错误写法 (编译报错)
+```typescript
+import { relationalStore, ValuesBucket } from '@kit.ArkData';
+
+toValuesBucket(): ValuesBucket {
+  const bucket = new ValuesBucket();  // ERROR: 'ValuesBucket' only refers to a type
+  bucket.put('key', value);           // ERROR: ValuesBucket has no .put() method
+  return bucket;
+}
+```
+
+### 正确写法
+```typescript
+type EntityValuesBucket = Record<string, number | string | boolean | Uint8Array | null>;
+
+toValuesBucket(): EntityValuesBucket {
+  const bucket: EntityValuesBucket = {};
+  bucket['key'] = value;
+  return bucket;
+}
+```
+
+**原因**: `ValuesBucket` 在 SDK 中是 type alias (`Record<string, ValueType>`)，不是可实例化的类。
+
+---
+
+## Pattern 2: fromResultSet 参数类型 (禁止 any)
+
+### 错误写法 (编译报错)
+```typescript
+// ArkTS 严格模式禁止 any
+static fromResultSet(resultSet: any): EntityName {  // ERROR: arkts-no-any-unknown
+```
+
+### 正确写法
+```typescript
+static fromResultSet(resultSet: Object): EntityName {
+  const rs = resultSet as Record<string, Object>;
+  const colIndex = (name: string): number =>
+    (rs['getColumnIndex'] as Function)(name) as number;
+
+  entity.field = (rs['getLong'] as Function)(colIndex('field_name')) as number;
+  entity.name  = (rs['getString'] as Function)(colIndex('name')) as string;
+  return entity;
+}
+```
+
+**替代方案** (更简洁但运行时开销略高):
+```typescript
+// 使用类型断言避免 any，运行时通过 Record<string, Function> 调用
+static fromResultSet(resultSet: Object): EntityName {
+  const getCol = (name: string): number =>
+    (resultSet as Record<string, Function>)['getColumnIndex'](name) as number;
+  const getLong = (name: string): number =>
+    (resultSet as Record<string, Function>)['getLong'](getCol(name)) as number;
+  const getStr = (name: string): string =>
+    (resultSet as Record<string, Function>)['getString'](getCol(name)) as string;
+
+  const entity = new EntityName();
+  entity.id   = getLong('id');
+  entity.name = getStr('name');
+  return entity;
+}
+```
+
+---
+
+## Pattern 3: // @ts-ignore 不可用
+
+### 错误尝试
+```typescript
+// @ts-ignore  // ERROR: Switching off type checks with in-place comments is not allowed
+static fromResultSet(resultSet: any): EntityName {
+```
+
+### 必须用 Pattern 2 替代
+
+---
+
+## Pattern 4: toValuesBucket() 返回类型注解
+
+```typescript
+type EntityValuesBucket = Record<string, number | string | boolean | Uint8Array | null>;
+
+toValuesBucket(): EntityValuesBucket {
+  const bucket: EntityValuesBucket = {} as EntityValuesBucket;
+  // ...
+  return bucket;
+}
+```
+
+---
+
+## 完整 Entity 模板
+
+```typescript
+type EntityValuesBucket = Record<string, number | string | boolean | Uint8Array | null>;
+
+export class MyEntity {
+  id: number = 0;
+  name: string = '';
+  value: number = 0;
+
+  static fromResultSet(resultSet: Object): MyEntity {
+    const rs = resultSet as Record<string, Object>;
+    const col = (n: string): number => (rs['getColumnIndex'] as Function)(n) as number;
+    const entity = new MyEntity();
+    entity.id   = (rs['getLong']   as Function)(col('id'))   as number;
+    entity.name = (rs['getString'] as Function)(col('name')) as string;
+    entity.value = (rs['getLong']  as Function)(col('value')) as number;
+    return entity;
+  }
+
+  toValuesBucket(): EntityValuesBucket {
+    const bucket: EntityValuesBucket = {} as EntityValuesBucket;
+    if (this.id > 0) { bucket['id'] = this.id; }
+    bucket['name'] = this.name;
+    bucket['value'] = this.value;
+    return bucket;
+  }
+}
+```