@ohos-cpf/3rdloop 0.0.3 → 0.0.5

package/vendor/Server/Skills/arkts-code-use/assets/TEMPLATES.md

@@ -0,0 +1,367 @@
+# ArkTS 代码模板
+
+> 按代码类型选择模板起步，替换占位内容后按需扩展。所有模板均符合 ArkTS 严格模式与华为编码规范，可通过 `devecocli build` 编译验证。
+
+---
+
+## 一、工具类模板（codeType: util）
+
+无状态、可复用的纯逻辑封装。文件：`utils/StringValidator.ets`
+
+```typescript
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0x0001;
+const TAG: string = 'MyApp_StringValidator';
+
+/**
+ * 字符串校验工具类（纯静态方法，禁止实例化）
+ */
+export class StringValidator {
+  private constructor() {
+    // 工具类禁止实例化
+  }
+
+  /**
+   * 校验字符串非空且长度不超上限
+   * @param value - 待校验字符串
+   * @param maxLen - 最大长度，默认 256
+   * @returns 是否合法
+   */
+  static isValidText(value: string | null | undefined, maxLen: number = 256): boolean {
+    if (value === null || value === undefined) {
+      return false;
+    }
+    return value.length > 0 && value.length <= maxLen;
+  }
+
+  /**
+   * 校验字符串是否匹配正则
+   * @param value - 待校验字符串
+   * @param pattern - 正则表达式
+   * @returns 是否匹配
+   */
+  static matches(value: string, pattern: RegExp): boolean {
+    const matched: boolean = pattern.test(value);
+    hilog.debug(DOMAIN, TAG, 'matches result=%{public}s', String(matched));
+    return matched;
+  }
+}
+```
+
+---
+
+## 二、业务服务类模板（codeType: service）
+
+有状态、含异步操作与资源生命周期管理。文件：`service/ConfigService.ets`
+
+```typescript
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0x0001;
+const TAG: string = 'MyApp_ConfigService';
+
+/** 服务配置 */
+export interface ConfigServiceOptions {
+  /** 请求超时（毫秒） */
+  timeoutMs: number;
+  /** 最大重试次数 */
+  maxRetries: number;
+}
+
+/** 默认配置 */
+const DEFAULT_OPTIONS: ConfigServiceOptions = {
+  timeoutMs: 5000,
+  maxRetries: 3,
+};
+
+/** 服务状态 */
+export const enum ServiceState {
+  IDLE = 0,
+  RUNNING = 1,
+  FINISHED = 2,
+  FAILED = 3,
+}
+
+/**
+ * 配置加载服务：管理状态机、异步操作与日志
+ */
+export class ConfigService {
+  private readonly options: ConfigServiceOptions;
+  private state: ServiceState = ServiceState.IDLE;
+
+  constructor(options: ConfigServiceOptions = DEFAULT_OPTIONS) {
+    this.options = options;
+  }
+
+  /** 获取当前状态 */
+  getState(): ServiceState {
+    return this.state;
+  }
+
+  /**
+   * 执行业务操作（示例骨架，替换为实际逻辑）
+   * @param input - 输入参数
+   * @returns 处理结果
+   */
+  async execute(input: string): Promise<string> {
+    hilog.info(DOMAIN, TAG, 'execute start, input length=%{public}d', input.length);
+    this.state = ServiceState.RUNNING;
+    try {
+      // TODO: 替换为实际业务逻辑（系统 API 须经文档查证，见 API_VERIFICATION.md）
+      const result: string = input.trim();
+      this.state = ServiceState.FINISHED;
+      hilog.info(DOMAIN, TAG, 'execute success');
+      return result;
+    } catch (e) {
+      this.state = ServiceState.FAILED;
+      const err: Error = e instanceof Error ? e : new Error(String(e));
+      hilog.error(DOMAIN, TAG, 'execute failed: %{public}s', err.message);
+      throw err;
+    }
+  }
+}
+```
+
+---
+
+## 三、页面模板（codeType: page）
+
+文件：`pages/ExamplePage.ets`（须注册到 `resources/base/profile/main_pages.json`）
+
+```typescript
+import hilog from '@ohos.hilog';
+import { ConfigService } from '../service/ConfigService';
+
+const DOMAIN: number = 0x0001;
+const TAG: string = 'MyApp_ExamplePage';
+
+/**
+ * 示例页面：演示状态驱动 UI 与资源清理
+ */
+@Entry
+@Component
+struct ExamplePage {
+  @State message: string = 'ready';
+  @State isLoading: boolean = false;
+  private service: ConfigService = new ConfigService();
+  private timerId: number = -1;
+
+  aboutToAppear(): void {
+    hilog.info(DOMAIN, TAG, 'page appear');
+  }
+
+  aboutToDisappear(): void {
+    // 清理页面持有的 Timer / 订阅等资源
+    if (this.timerId >= 0) {
+      clearInterval(this.timerId);
+      this.timerId = -1;
+    }
+    hilog.info(DOMAIN, TAG, 'page disappear');
+  }
+
+  private async onRunClicked(): Promise<void> {
+    this.isLoading = true;
+    try {
+      const result: string = await this.service.execute('  demo input  ');
+      this.message = `result: ${result}`;
+    } catch (e) {
+      this.message = `failed: ${(e as Error).message}`;
+    } finally {
+      this.isLoading = false;
+    }
+  }
+
+  build() {
+    Column({ space: 12 }) {
+      Text(this.message)
+        .fontSize(16)
+        .width('90%')
+        .textAlign(TextAlign.Center)
+
+      if (this.isLoading) {
+        LoadingProgress()
+          .width(36)
+          .height(36)
+      } else {
+        Button('run')
+          .width('60%')
+          .onClick(() => {
+            this.onRunClicked();
+          })
+      }
+    }
+    .width('100%')
+    .height('100%')
+    .justifyContent(FlexAlign.Center)
+  }
+}
+```
+
+---
+
+## 四、自定义组件模板（codeType: component）
+
+文件：`components/StatusCard.ets`
+
+```typescript
+/**
+ * 状态卡片组件：父组件传 @Prop 单向数据，@Link 双向同步计数
+ */
+@Component
+export struct StatusCard {
+  @Prop title: string = '';
+  @Link count: number;
+  private onCountChanged: ((count: number) => void) | null = null;
+
+  build() {
+    Column({ space: 8 }) {
+      Text(this.title)
+        .fontSize(16)
+        .fontWeight(FontWeight.Medium)
+
+      Text(`count: ${this.count}`)
+        .fontSize(20)
+
+      Row({ space: 12 }) {
+        Button('+')
+          .width(44)
+          .height(44)
+          .onClick(() => {
+            this.count += 1;
+            if (this.onCountChanged !== null) {
+              this.onCountChanged(this.count);
+            }
+          })
+        Button('-')
+          .width(44)
+          .height(44)
+          .onClick(() => {
+            this.count -= 1;
+            if (this.onCountChanged !== null) {
+              this.onCountChanged(this.count);
+            }
+          })
+      }
+    }
+    .padding(12)
+    .borderRadius(12)
+    .backgroundColor('#F1F3F5')
+    .width('90%')
+  }
+}
+```
+
+> 组件内回调属性（如 `onCountChanged`）须显式声明类型；父组件使用：`StatusCard({ title: 'demo', count: $count, onCountChanged: (c: number) => {} })`
+
+---
+
+## 五、HTTP 服务类模板（网络场景常用）
+
+文件：`service/HttpService.ets`。须在 `module.json5` 声明 `ohos.permission.INTERNET`。
+
+```typescript
+import { http } from '@kit.NetworkKit';
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0x0001;
+const TAG: string = 'MyApp_HttpService';
+
+/** 请求配置 */
+export interface HttpServiceOptions {
+  connectTimeoutMs: number;
+  readTimeoutMs: number;
+}
+
+/** 响应封装 */
+export interface ApiResponse {
+  statusCode: number;
+  body: string;
+}
+
+const MAX_RESPONSE_BYTES: number = 5 * 1024 * 1024;
+
+/**
+ * HTTP 服务：每次请求独立 HttpRequest，try/finally 释放
+ */
+export class HttpService {
+  private readonly options: HttpServiceOptions;
+
+  constructor(options: HttpServiceOptions) {
+    this.options = options;
+  }
+
+  /**
+   * 发起 GET 请求
+   * @param url - 目标地址（https 优先）
+   * @returns 状态码与响应体
+   */
+  async get(url: string): Promise<ApiResponse> {
+    const httpRequest: http.HttpRequest = http.createHttp();
+    try {
+      const response: http.HttpResponse = await httpRequest.request(url, {
+        method: http.RequestMethod.GET,
+        connectTimeout: this.options.connectTimeoutMs,
+        readTimeout: this.options.readTimeoutMs,
+      });
+      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} bytes`);
+      }
+      hilog.info(DOMAIN, TAG, 'GET %{public}s -> %{public}d', url, response.responseCode);
+      return { statusCode: response.responseCode, body: response.result };
+    } finally {
+      httpRequest.destroy();
+    }
+  }
+}
+```
+
+---
+
+## 六、模块导出模板（index.ets）
+
+```typescript
+// library/src/main/ets/index.ets 或模块入口
+export { StringValidator } from './utils/StringValidator';
+export { ConfigService } from './service/ConfigService';
+export type { ConfigServiceOptions } from './service/ConfigService';
+export { ServiceState } from './service/ConfigService';
+export { HttpService } from './service/HttpService';
+export type { HttpServiceOptions, ApiResponse } from './service/HttpService';
+```
+
+> 仅 `export` 的符号对外可见；`interface`/`type` 导出用 `export type`。
+
+---
+
+## 七、main_pages.json 注册模板
+
+`entry/src/main/resources/base/profile/main_pages.json`：
+
+```json
+{
+  "src": [
+    "pages/Index",
+    "pages/ExamplePage"
+  ]
+}
+```
+
+## 八、module.json5 权限声明模板
+
+`entry/src/main/module.json5`（module 节点内）：
+
+```json
+{
+  "module": {
+    "requestPermissions": [
+      { "name": "ohos.permission.INTERNET" }
+    ]
+  }
+}
+```
+
+> user_grant 级权限（如 LOCATION）声明后还须运行时申请，参见 [代码模式 §五](../references/CODE_PATTERNS.md)。

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

@@ -0,0 +1,144 @@
+# API 查证指南
+
+> 编写 ArkTS 代码前，所有系统 API 的 import 路径、方法签名、权限、API Level 必须通过官方文档查证。本文档说明查证工具的使用方法与领域关键词速查。
+
+---
+
+## 一、查证工具
+
+### 1.1 首选：MCP Gateway `script_deveco_docs`
+
+MCP Gateway 运行时，`script_deveco_docs` 工具封装了 `devecocli docs`，可直接检索与精读 HarmonyOS 官方 API 文档。
+
+**按关键词检索（action=search）**：
+
+```json
+{
+  "action": "search",
+  "keywords": "http createHttp request",
+  "catalog": "harmonyos-references",
+  "limit": 5
+}
+```
+
+| 参数 | 说明 |
+|------|------|
+| `action` | `search`（检索）或 `read`（读全文） |
+| `keywords` | 空格分隔的关键词，建议 2-4 个（API 名 + 模块名 + 功能词） |
+| `catalog` | 默认 `harmonyos-references`（API 参考）；指南类用 `harmonyos-guides` |
+| `limit` | 返回条数，默认 10 |
+
+返回字段：`title`（文档标题）、`documentId`（用于 read）、`sectionTitle`（命中小节）、`snippet`（摘要）。
+
+**按 documentId 精读（action=read）**：
+
+```json
+{
+  "action": "read",
+  "documentId": "API参考/网络/Network_Kit_网络服务/ArkTS_API/ohos_net_http_数据请求_/js-apis-http",
+  "section": "HttpRequest"
+}
+```
+
+`section` 可选，指定后只返回该小节（推荐，节省 token）。文档正文包含：方法签名、参数表、返回值、`权限`、`系统能力`（SystemCapability）、`起始版本`（since）、`废弃`（deprecated）标注、错误码。
+
+### 1.2 备选：`devecocli docs`（终端）
+
+MCP 不可用时直接使用 CLI：
+
+```bash
+# 检索（匹配任一关键词）
+devecocli docs search "http createHttp" --limit 5
+
+# 按文档 ID 精读
+devecocli docs read "API参考/网络/Network_Kit_网络服务/ArkTS_API/ohos_net_http_数据请求_/js-apis-http"
+
+# 查看可用文档目录
+devecocli docs catalog
+```
+
+### 1.3 补充：知识库（最佳实践/平台陷阱）
+
+MCP Gateway 的 `kb_search`（内置）或 `kb-server_search_knowledge`（下游）可检索鸿蒙知识库中的最佳实践与实战经验（如平台陷阱、性能优化），适合在方案设计阶段补充查询，不适合替代官方 API 参考。
+
+---
+
+## 二、三步查询法
+
+对每个涉及的系统 API 依次执行：
+
+```
+Step 1 宽泛定位：用功能关键词检索，确认可用的模块/类
+        例：keywords = "video player"
+Step 2 精确签名：read 文档定位到具体类/方法小节，记录完整签名
+        例：documentId = "...js-apis-media", section = "createAVPlayer"
+Step 3 权限与版本：确认该 API 的「权限」「起始版本」「废弃」标注
+        - 权限 → 记入 module.json5 声明清单
+        - since > 目标 API Level → 加 canIUse()/sdkApiVersion 守卫或换旧接口
+        - deprecated → 检索替代接口（keywords 加 "alternative" 或直接搜新接口名）
+```
+
+---
+
+## 三、领域关键词速查
+
+| 领域 | 功能 | 检索关键词 |
+|------|------|-----------|
+| 网络 | HTTP 请求 | `http createHttp request` |
+| 网络 | WebSocket | `webSocket connect` |
+| 网络 | 网络状态 | `network connection` |
+| 存储 | KV 偏好 | `preferences data` |
+| 存储 | 关系型数据库 | `relationalStore` |
+| 存储 | 文件读写 | `file fs openSync readSync` |
+| 存储 | 用户文件选择 | `file picker` |
+| UI | 页面路由 | `Navigation NavDestination router` |
+| UI | 列表懒加载 | `LazyForEach IDataSource` |
+| UI | 动画 | `animateTo animation` |
+| UI | 弹窗 | `CustomDialog AlertDialog` |
+| 多媒体 | 视频播放 | `AVPlayer media` |
+| 多媒体 | 音频播放/录制 | `AudioRenderer AudioCapturer` |
+| 多媒体 | 图片处理 | `ImageSource PixelMap` |
+| 设备 | 定位 | `geoLocationManager` |
+| 设备 | 蓝牙 BLE | `bluetooth ble` |
+| 设备 | 传感器 | `sensor accelerometer` |
+| 设备 | 振动 | `vibrator` |
+| 安全 | 对称加密 | `cryptoFramework AES Cipher` |
+| 安全 | 摘要/HMAC | `cryptoFramework hash hmac` |
+| 安全 | 密钥管理 | `huks` |
+| 并发 | 任务池 | `taskpool execute Concurrent` |
+| 并发 | Worker | `worker ThreadWorker` |
+| 事件 | 事件总线 | `emitter on emit off` |
+| 权限 | 运行时申请 | `requestPermissionsFromUser abilityAccessCtrl` |
+| 应用 | 应用上下文 | `common UIAbilityContext` |
+| 应用 | 弹框申请 | `requestPermissionsFromUser` |
+
+---
+
+## 四、API Level 对照
+
+| API Level | 系统版本 | 说明 |
+|-----------|---------|------|
+| 9 | HarmonyOS 3.2 | 基础 API |
+| 10 | HarmonyOS 4.0 | — |
+| 11 | HarmonyOS 4.1 | Stage 模型完善 |
+| 12 | HarmonyOS 5.0 (NEXT) | NEXT 正式版本 |
+| 13+ | 5.x 后续 | 持续演进 |
+
+**规则**：
+- 工程模式：目标 API Level 以目标工程 `build-profile.json5` 的 `compatibleSdkVersion` 为准（先读取再写代码）
+- 独立模式：默认按 API 12+ 编写；`since` > 12 的接口必须加版本守卫
+- 优先使用非废弃接口；文档明确标注 `废弃` 的禁止使用
+
+---
+
+## 五、查证结论记录格式
+
+每个功能点查证后立即记录，作为 Phase 3 编码依据：
+
+| 功能点 | import 路径 | 关键 API 与签名 | 权限 | since | 结论 |
+|--------|------------|----------------|------|-------|------|
+| 发起 GET 请求 | `@kit.NetworkKit` (`http`) | `http.createHttp(): HttpRequest`、`request(url, options): Promise<HttpResponse>` | `ohos.permission.INTERNET` | 8 | ✅ |
+| 后台计算校验和 | `@ohos.taskpool` | `@Concurrent` 函数 + `taskpool.execute(task)` | 无 | 9 | ✅ |
+| 蓝牙扫描 | `@ohos.bluetooth.ble` | `startScan(filters)` | `ohos.permission.ACCESS_BLUETOOTH` | 10 | ⚠️ 需 canIUse 守卫 |
+
+> 未出现在该表中的系统 API 不允许出现在最终代码里。