@ohos-cpf/3rdloop 0.0.3 → 0.0.5

package/vendor/Server/Skills/arkts-code-use/references/ARKTS_RULES.md

@@ -0,0 +1,240 @@
+# ArkTS 规范与约束速查
+
+> ArkTS 是 TypeScript 的扩展集，在 TS 基础上施加了更严格的静态类型约束（强制静态类型、禁止运行时改变对象布局），以获得更好的运行性能。本文档汇总编码时必须遵守的约束，**违反即编译报错**。
+
+---
+
+## 一、禁止项清单（编译必查）
+
+以下是 ArkTS 严格模式下最常见的编译阻断项，生成代码必须全部规避：
+
+| # | 禁止项 | 错误码/规则 | 正确替代方式 |
+|---|--------|------------|------------|
+| 1 | `any` / `unknown` 类型 | `arkts-no-any-unknown` | 使用具体类型或泛型 `T` |
+| 2 | `ESObject` / `Object` 通用类型 | `arkts-no-esobj` | 使用 `interface` 或具体类型 |
+| 3 | 动态属性访问 `obj['key']` | `arkts-no-dynamic-property` | `obj.key` 类型安全访问 |
+| 4 | 未类型化对象字面量 `let o = {}` | `arkts-no-untyped-obj-literals` | 先声明 class/interface 再赋值 |
+| 5 | 内联匿名对象类型参数 | `arkts-no-obj-literals-as-types` | 定义命名 `interface` |
+| 6 | `prototype` 扩展 | `arkts-no-prototype-assignment` | 类继承或组合 |
+| 7 | `delete` 操作符 | `arkts-no-delete` | 将属性设为 `undefined` 或重构数据结构 |
+| 8 | `arguments` 对象 | `arkts-no-arguments` | 使用展开参数 `...args: T[]` |
+| 9 | 双重类型转换 `as unknown as T` | `arkts-no-unsafe-cast` | 定义正确的类型，单次合法转型 |
+| 10 | `for...in` 遍历 | `arkts-no-for-in` | `Object.keys()` + `for...of` / `forEach` |
+| 11 | `eval()` / `new Function()` | `arkts-no-eval` | 禁止使用，无合法替代 |
+| 12 | catch 块直接 `throw e` | `arkts-limited-throw` | `throw e instanceof Error ? e : new Error(String(e))` |
+| 13 | 结构型类型（鸭子类型）匹配 | `arkts-no-structural-typing` | 显式 `extends` / `implements` |
+| 14 | 函数类型不一致赋值 | `arkts-strict-function-types` | 参数/返回值类型完全一致 |
+| 15 | 泛型函数非箭头定义 | `arkts-no-functional-constructors` | 使用 `function` 声明或箭头函数 |
+| 16 | `Object.assign` 修改对象布局 | `arkts-no-object-assign` | 逐属性赋值（类型已声明） |
+| 17 | 运行时修改 class 布局 | `arkts-no-runtime-change-layout` | 类型声明保持静态 |
+| 18 | `Symbol()` API | `arkts-no-symbol` | 不使用 Symbol |
+| 19 | `as any` / 类型断言到 any | `arkts-no-any` | 明确的目标类型断言 |
+| 20 | `void` 返回值以外使用 `undefined` 检查歧义 | — | 显式 `T \| undefined` |
+
+> 完整规则见官方文档 [从 TypeScript 到 ArkTS 的适配规则](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/typescript-to-arkts-migration-guide)。
+
+---
+
+## 二、高频错误正误对照
+
+### 2.1 类型安全（规则 1/2/4/5）
+
+```typescript
+// ❌ 错误：any + 未类型化字面量
+function parse(json: string): any {
+  return JSON.parse(json);
+}
+let config = { timeout: 5000, retries: 3 };
+
+// ✅ 正确：显式类型
+interface Config {
+  timeout: number;
+  retries: number;
+}
+function parseConfig(json: string): Config {
+  return JSON.parse(json) as Config;  // 单次断言到具体类型是允许的
+}
+const config: Config = { timeout: 5000, retries: 3 };
+```
+
+### 2.2 catch 重抛（规则 12，最高频报错之一）
+
+```typescript
+// ❌ 错误：e 为 unknown，直接 throw 违反 arkts-limited-throw
+try {
+  await doWork();
+} catch (e) {
+  throw e;
+}
+
+// ✅ 正确：确保抛出 Error 实例
+try {
+  await doWork();
+} catch (e) {
+  throw e instanceof Error ? e : new Error(String(e));
+}
+```
+
+### 2.3 对象字面量必须对应显式类型（规则 4/5）
+
+```typescript
+// ❌ 错误：内联匿名类型 + 裸字面量
+function fetchData(url: string, cb: (resp: { code: number }) => void): void {}
+let resp = { code: 200 };
+
+// ✅ 正确：命名 interface
+interface Response {
+  code: number;
+}
+function fetchData(url: string, cb: (resp: Response) => void): void {}
+const resp: Response = { code: 200 };
+```
+
+### 2.4 结构型类型禁用（规则 13）
+
+```typescript
+// ❌ 错误：鸭子类型赋值（字段相同也不能赋值）
+interface A { x: number }
+class B { x: number = 1 }
+const a: A = new B();  // 编译报错 arkts-no-structural-typing
+
+// ✅ 正确：显式实现
+class C implements A { x: number = 1 }
+const a2: A = new C();
+```
+
+### 2.5 遍历（规则 10）
+
+```typescript
+// ❌ 错误
+for (const key in obj) { console.log(key); }
+
+// ✅ 正确
+const keys: string[] = Object.keys(obj);
+for (const key of keys) {
+  console.log(key);
+}
+```
+
+---
+
+## 三、类型系统约束
+
+| 约束 | 说明 |
+|------|------|
+| 显式类型标注 | 所有变量、参数、返回值建议显式标注；字面量初始化可省略 |
+| 联合类型 | `string \| null` 合法；禁止用 `any` 模拟联合 |
+| 泛型 | 完整支持；优先泛型而非 any/Object 传参 |
+| 字面量联合 | `mode: 'sync' \| 'async'` 合法，简单场景优先于枚举 |
+| 可选属性 | `timeout?: number` 合法；访问时用 `?.` 或显式判空 |
+| Record 类型 | `Record<string, string>` 用于键值对场景 |
+| 函数类型 | 箭头函数与 function 声明均可；回调参数类型必须显式 |
+
+---
+
+## 四、命名与格式规范（华为 ArkTS 编程规范）
+
+### 4.1 命名约定
+
+| 元素 | 风格 | 示例 |
+|------|------|------|
+| 类 / 接口 / 枚举 / struct / 装饰器类 | PascalCase | `HttpClient`、`RetryPolicy`、`LoadState` |
+| 方法 / 变量 / 参数 | camelCase | `sendRequest`、`maxRetries` |
+| 常量 | UPPER_SNAKE_CASE | `const MAX_SIZE: number = 1024` |
+| 枚举成员 | UPPER_SNAKE_CASE 或 PascalCase（全工程统一） | `enum Status { IDLE, RUNNING }` |
+| 布尔变量/方法 | is/has/can 前缀 | `isValid`、`hasData` |
+| 私有成员 | `private` 修饰符（不加 `_` 前缀） | `private count: number` |
+| 文件名 | PascalCase.ets | `HttpClient.ets`、`Index.ets` |
+
+### 4.2 代码格式
+
+- 缩进 **2 空格**，禁止 Tab
+- 语句行尾**分号**（`.ets` 源文件中必写）
+- 单行长度建议 ≤ 120 字符
+- 单文件 ≤ 400 行，超出按职责拆分
+- import 顺序：`@ohos.*` / `@kit.*` → 第三方库 → 相对路径模块
+
+### 4.3 注释规范
+
+- 公共接口必须有 JSDoc：功能、`@param`、`@returns`
+- 复杂逻辑块行内注释说明"为什么"而非"是什么"
+- 禁止提交注释掉的死代码
+
+```typescript
+/**
+ * 重试策略配置
+ */
+export interface RetryPolicy {
+  /** 最大重试次数，默认 3 */
+  maxRetries: number;
+  /** 重试间隔基数（毫秒），按指数退避递增 */
+  baseIntervalMs: number;
+}
+
+/**
+ * 按指数退避执行重试
+ * @param fn - 要执行的异步操作
+ * @param policy - 重试策略
+ * @returns 操作结果
+ */
+async function withRetry<T>(fn: () => Promise<T>, policy: RetryPolicy): Promise<T> {
+  // ...实现
+}
+```
+
+---
+
+## 五、日志规范
+
+### 5.1 初始化
+
+```typescript
+import hilog from '@ohos.hilog';
+
+// 域值 0x0000~0xFFFF，按模块分配
+const DOMAIN: number = 0x0001;
+// 标签 ≤ 31 字符，格式：模块名_功能名
+const TAG: string = 'MyApp_HttpClient';
+```
+
+### 5.2 级别使用
+
+| 级别 | 场景 |
+|------|------|
+| `debug` | 方法进出、中间状态（禁止用于高频循环） |
+| `info` | 关键流程节点、状态变更、操作成功 |
+| `warn` | 可恢复异常、参数降级处理 |
+| `error` | 操作失败、异常捕获 |
+
+### 5.3 隐私保护（强制）
+
+```typescript
+// ✅ 敏感数据使用 %{private}s
+hilog.info(DOMAIN, TAG, 'login, account: %{private}s', account);
+
+// ❌ 禁止密码/Token/手机号使用 %{public}s
+```
+
+---
+
+## 六、ArkUI 声明式 UI 约束
+
+| 约束 | 说明 |
+|------|------|
+| 状态变量必须加装饰器 | `@State` / `@Prop` / `@Link` / `@Provide` / `@Consume` 等 |
+| 组件内状态修改触发刷新 | 只能通过状态变量驱动 UI，禁止命令式操作 |
+| build() 内禁止修改状态 | 只做声明；状态修改放事件回调和生命周期 |
+| 尺寸单位 | 布局用 `vp`、字体用 `fp`，禁止硬编码 px 假设 |
+| 资源引用 | `$r('app.string.xxx')`；string 避免硬编码 |
+| 条件渲染 | `if/else` 分支中组件结构须完整闭合 |
+| 列表性能 | 大数据量列表用 `LazyForEach` + `IDataSource` |
+
+---
+
+## 七、依赖与导入约束
+
+- `@ohos.*` 模块导入：`import http from '@ohos.net.http';`
+- Kit 聚合导入（优先）：`import { http } from '@kit.NetworkKit';`
+- 相对导入必须带文件名（无扩展名）：`import { Config } from './Config';`
+- import 路径大小写敏感（macOS 不敏感、构建机 Linux 敏感，必须按实际文件名大小写书写）
+- 三方依赖通过 `oh-package.json5` 声明，`ohpm install` 安装，禁止直接引用未声明依赖

package/vendor/Server/Skills/arkts-code-use/references/CODE_PATTERNS.md

@@ -0,0 +1,431 @@
+# ArkTS 代码模式
+
+> 编写鸿蒙原生 ArkTS 代码时的标准实现模式：异步编程、并发、错误处理、事件、权限、资源生命周期、UI 状态管理。所有模式均已通过 ArkTS 严格模式编译验证。
+
+---
+
+## 一、异步编程模式
+
+### 1.1 Promise + async/await（默认选择）
+
+```typescript
+import fs from '@ohos.file.fs';
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0x0001;
+const TAG: string = 'MyApp_Async';
+
+/** 将回调式 API 封装为 Promise */
+function readTextAsync(filePath: string): Promise<string> {
+  return new Promise<string>((resolve: (value: string) => void,
+    reject: (reason: Error) => void) => {
+    fs.readText(filePath, (err: Error, data: string) => {
+      if (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+      resolve(data);
+    });
+  });
+}
+
+/** 调用方：async/await + try/catch/finally */
+async function processFile(filePath: string): Promise<string> {
+  try {
+    const content: string = await readTextAsync(filePath);
+    hilog.info(DOMAIN, TAG, 'read ok, length=%{public}d', content.length);
+    return content;
+  } catch (e) {
+    hilog.error(DOMAIN, TAG, 'read failed: %{public}s', (e as Error).message);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+```
+
+### 1.2 超时控制（Promise.race）
+
+```typescript
+function withTimeout<T>(task: Promise<T>, timeoutMs: number): Promise<T> {
+  const timer: Promise<never> = new Promise<never>(
+    (_resolve: (value: never) => void, reject: (reason: Error) => void) => {
+      setTimeout(() => {
+        reject(new Error(`timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+  return Promise.race<T>([task, timer]);
+}
+```
+
+---
+
+## 二、并发模式（taskpool / worker）
+
+> 阻塞 IO、大量计算禁止在主线程执行。优先 taskpool（轻量任务池），长生命周期后台线程用 worker。
+
+### 2.1 taskpool 耗时计算
+
+```typescript
+import taskpool from '@ohos.taskpool';
+
+// @Concurrent 函数必须是独立函数，不能捕获外部变量（可序列化参数传入）
+@Concurrent
+function computeChecksum(input: number[]): number {
+  let sum: number = 0;
+  for (const value of input) {
+    sum += value * 31;
+  }
+  return sum;
+}
+
+async function runInBackground(input: number[]): Promise<number> {
+  const task: taskpool.Task = new taskpool.Task(computeChecksum, input);
+  return await taskpool.execute(task) as number;
+}
+```
+
+### 2.2 worker 生命周期（必须 terminate）
+
+```typescript
+import worker from '@ohos.worker';
+
+class WorkerHost {
+  private threadWorker: worker.ThreadWorker | null = null;
+
+  start(): void {
+    // 脚本路径相对模块 src/main/ets
+    this.threadWorker = new worker.ThreadWorker('entry/ets/workers/MyWorker.ets');
+    this.threadWorker.onmessage = (event: MessageEvents): void => {
+      // 处理子线程结果
+    };
+    this.threadWorker.postMessage({ type: 'start' });
+  }
+
+  /** 必须在确定生命周期节点调用，防止线程泄露 */
+  stop(): void {
+    if (this.threadWorker !== null) {
+      this.threadWorker.terminate();
+      this.threadWorker = null;
+    }
+  }
+}
+```
+
+---
+
+## 三、错误处理模式
+
+### 3.1 BusinessError（系统 API 标准错误）
+
+```typescript
+import { BusinessError } from '@ohos.base';
+
+async function callSystemApi(): Promise<void> {
+  try {
+    // await someSystemApi();
+  } catch (error) {
+    // 系统 API 错误统一转型为 BusinessError 读取 code
+    const err: BusinessError = error as BusinessError;
+    hilog.error(0x0001, 'MyApp', 'code=%{public}d, msg=%{public}s', err.code, err.message);
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+}
+```
+
+### 3.2 参数防御性校验
+
+```typescript
+class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+function validateInput(value: string | null | undefined, fieldName: string,
+  maxLen: number = 256): string {
+  if (value === null || value === undefined || value.length === 0) {
+    throw new ValidationError(`${fieldName} must not be empty`);
+  }
+  if (value.length > maxLen) {
+    throw new ValidationError(`${fieldName} exceeds max length ${maxLen}`);
+  }
+  return value;
+}
+```
+
+### 3.3 统一 Result 类型（避免异常控制流蔓延）
+
+```typescript
+export interface Result<T> {
+  success: boolean;
+  value?: T;
+  error?: string;
+}
+
+export class Ok<T> implements Result<T> {
+  success: boolean = true;
+  constructor(public value: T) {}
+}
+
+export class Fail<T> implements Result<T> {
+  success: boolean = false;
+  constructor(public error: string) {}
+}
+```
+
+---
+
+## 四、事件模式（emitter）
+
+```typescript
+import emitter from '@ohos.events.emitter';
+
+// 事件常量集中定义
+export const enum AppEvent {
+  DATA_UPDATED = 1001,
+  SYNC_FAILED = 1002,
+}
+
+class EventBus {
+  private static subscriptionCount: number = 0;
+
+  static subscribe(eventId: number, callback: (data: emitter.EventData) => void): void {
+    emitter.on({ eventId: eventId }, callback);
+    EventBus.subscriptionCount += 1;
+  }
+
+  static emit(eventId: number, data: Record<string, Object>): void {
+    emitter.emit({ eventId: eventId }, { data: data });
+  }
+
+  /** 取消订阅必须与 on 配对 */
+  static unsubscribe(eventId: number): void {
+    emitter.off(eventId);
+  }
+}
+```
+
+---
+
+## 五、权限申请模式
+
+```typescript
+import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
+import { common } from '@kit.AbilityKit';
+
+async function requestPermissions(context: common.UIAbilityContext,
+  permissions: Permissions[]): Promise<boolean> {
+  const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
+  const result: abilityAccessCtrl.PermissionRequestResult =
+    await atManager.requestPermissionsFromUser(context, permissions);
+  return result.authResults.every((status: number) =>
+    status === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED);
+}
+```
+
+> normal 级权限仅声明即生效；user_grant 级权限须声明 + 运行时申请两步缺一不可。
+
+---
+
+## 六、资源生命周期管理（防泄露）
+
+> **规则**：凡是 `create/open/on/connect` 获取的资源，必须存在对称的 `destroy/close/off/disconnect` 释放路径，置于 `try/finally` 或组件销毁回调中。
+
+| 资源 | 获取 | 释放 | 位置 |
+|------|------|------|------|
+| HTTP 连接 | `http.createHttp()` | `httpRequest.destroy()` | `try/finally` |
+| 文件句柄 | `fs.openSync()` | `fs.closeSync(fd)` | `try/finally` |
+| RDB 存储 | `getRdbStore()` | `close()` | 模块卸载 |
+| Worker | `new ThreadWorker()` | `terminate()` | 任务完成/销毁 |
+| Timer | `setInterval()` | `clearInterval(id)` | `aboutToDisappear` |
+| emitter 订阅 | `emitter.on()` | `emitter.off(id)` | `aboutToDisappear` |
+| 传感器 | `sensor.on()` | `sensor.off(type)` | 页面隐藏/销毁 |
+| AVPlayer | `createAVPlayer()` | `release()` | 播放结束/销毁 |
+
+### 6.1 HTTP 请求标准范式（最常见泄露点）
+
+```typescript
+import { http } from '@kit.NetworkKit';
+
+const MAX_RESPONSE_BYTES: number = 5 * 1024 * 1024;
+
+async function httpGet(url: string): Promise<string> {
+  const httpRequest: http.HttpRequest = http.createHttp();
+  try {
+    const response: http.HttpResponse = await httpRequest.request(url, {
+      method: http.RequestMethod.GET,
+      connectTimeout: 10_000,
+      readTimeout: 15_000,
+      expectMaxDuration: 20_000,
+    });
+    if (typeof response.result !== 'string') {
+      throw new Error('unexpected response type');
+    }
+    if (response.result.length > MAX_RESPONSE_BYTES) {
+      throw new Error(`response too large: ${response.result.length}`);
+    }
+    return response.result;
+  } finally {
+    // ✅ 成功失败均释放
+    httpRequest.destroy();
+  }
+}
+```
+
+### 6.2 文件读写标准范式
+
+```typescript
+import fs from '@ohos.file.fs';
+
+function readFileSafely(filePath: string): string {
+  let fd: number = -1;
+  try {
+    const file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
+    fd = file.fd;
+    const stat: fs.Stat = fs.statSync(filePath);
+    const buffer: ArrayBuffer = new ArrayBuffer(stat.size);
+    fs.readSync(fd, buffer);
+    return String.fromCharCode(...new Uint8Array(buffer));
+  } finally {
+    if (fd >= 0) {
+      fs.closeSync(fd);
+    }
+  }
+}
+```
+
+### 6.3 组件内订阅/Timer 清理
+
+```typescript
+@Component
+struct PollingComponent {
+  @State message: string = '';
+  private timerId: number = -1;
+
+  aboutToAppear(): void {
+    this.timerId = setInterval(() => {
+      this.message = `tick ${Date.now()}`;
+    }, 1000);
+  }
+
+  aboutToDisappear(): void {
+    if (this.timerId >= 0) {
+      clearInterval(this.timerId);
+      this.timerId = -1;
+    }
+  }
+
+  build() {
+    Text(this.message)
+  }
+}
+```
+
+---
+
+## 七、UI 状态管理模式
+
+### 7.1 父子组件通信
+
+```typescript
+// 子组件：单向输入 @Prop，双向绑定 @Link
+@Component
+struct CounterCard {
+  @Prop title: string = '';
+  @Link count: number;
+
+  build() {
+    Column({ space: 8 }) {
+      Text(this.title)
+        .fontSize(16)
+      Text(`count: ${this.count}`)
+        .fontSize(20)
+      Button('+1')
+        .onClick(() => {
+          this.count += 1;
+        })
+    }
+    .padding(12)
+  }
+}
+
+@Entry
+@Component
+struct Index {
+  @State count: number = 0;
+
+  build() {
+    Column({ space: 12 }) {
+      CounterCard({ title: 'demo', count: $count })  // @Link 用 $ 传引用
+    }
+  }
+}
+```
+
+### 7.2 @Provide/@Consume 跨层级
+
+```typescript
+// 祖先组件
+@Entry
+@Component
+struct GrandParent {
+  @Provide themeColor: string = '#007DFF';
+
+  build() { /* 包含后代组件 */ }
+}
+
+// 任意后代组件（无需逐层传递）
+@Component
+struct DeepChild {
+  @Consume themeColor: string;
+
+  build() {
+    Text('themed').fontColor(this.themeColor)
+  }
+}
+```
+
+### 7.3 @Builder 复用 + @BuilderParam 插槽
+
+```typescript
+@Builder
+function LoadingView(text: string) {
+  Column({ space: 8 }) {
+    LoadingProgress().width(48).height(48)
+    Text(text).fontSize(14)
+  }
+  .width('100%')
+  .justifyContent(FlexAlign.Center)
+}
+```
+
+---
+
+## 八、兼容性守卫模式
+
+```typescript
+import deviceInfo from '@ohos.deviceInfo';
+
+// 硬件能力检测：调用蓝牙/NFC/摄像头前必须
+function ensureBluetooth(): boolean {
+  return canIUse('SystemCapability.Communication.Bluetooth.Core');
+}
+
+// API Level 守卫：使用 since 高于目标版本的接口前必须
+function getSdkApiLevel(): number {
+  return deviceInfo.sdkApiVersion;
+}
+```
+
+---
+
+## 九、典型平台陷阱速查
+
+| 陷阱 | 正确做法 |
+|------|---------|
+| 沙箱路径 | 用 `context.filesDir` / `context.cacheDir`；禁止硬编码 `/data/local/tmp` |
+| rawfile 资源 | 不可直接路径访问；用 `resourceManager.getRawFileContentSync()` / `getRawFdSync()` |
+| `file://` 前缀 | 拼接为 `file://` + 绝对路径（两斜杠），媒体 URL 不用三斜杠 |
+| fs.writeSync 传 Uint8Array | 必须传 `uint8array.buffer`（ArrayBuffer） |
+| 高频 hilog.debug | 禁止每帧/每秒多次打印，影响性能 |
+| 阻塞主线程 | `Thread.sleep` 类同步等待不存在；用 `await new Promise` + setTimeout 或 taskpool |