tuya 概述 {#description}
面向业务代码位于 src/* 的小程序 / 面板宿主工程，介绍如何接入 @ray-js/electrician-timing-sdk：app 入口一次性 init、六类定时（云、循环、随机、点动、倒计时、天文）的接入方式。天文不在本 SDK 中。
信息源
以 @ray-js/electrician-timing-sdk 的 README（含 README-zh_CN.md）与包类型声明为权威；本地实现与之冲突时以 README + 包导出为准。
工程 config 与 SDK 的边界
init/changeConfig的字段名以 SDK README 为准。type: 'ele'时，supportCloud/supportCycle/supportRandom/supportInching取'auto'/'y'/'n'。- 宿主使用的 URL query（
supportCountdown、supportCycle等）属于工程侧契约：先写入工程config，再驱动本地能力判断。supportCountdown特别提示：它不是type: 'ele'的 READMEinit字段；倒计时入口的展示由宿主config决定，SDK 调用本身使用createCountdown(code, ...)。 - 群组场景默认不支持云定时（README），建议同时关闭天文。
适用场景 {#scene}
六类定时 → SDK 写入 API
| 类型 | 归属 | 写入 API（以 README 为准） |
|---|---|---|
| 云定时 | SDK | addCloudTimer、batchAddCloudTimer、updateCloudTimer、updateCloudTimerStatus、removeCloudTimer；监听 onCloudUpdate |
| 循环 | SDK | electri.cycle.add/update/... |
| 随机 | SDK | electri.random.* |
| 点动（延时关） | SDK | electri.inching.* |
| 倒计时 | SDK | createCountdown、cancelCountdown |
| 天文 | 不在 SDK 中 | 使用 @ray-js/ray 的 addAstronomical、getAstronomicalList、updateAstronomical、updateAstronomicalStatus、removeAstronomical，详见 references/astronomical.md。勿使用 electri.astronomical（无此命名空间）或 addDpTimer（无法解析日出日落）。 |
落地目录由 AI 按工程现状判断（典型放在 src/pages/<feature>/，无强制命名）。
何时使用本 skill
当宿主工程需要接入「电工定时」相关能力时使用，典型场景：
- 接入云定时（按周重复、节假日等）。
- 接入循环定时（在时间段内按间隔循环开关）。
- 接入随机定时（在时间段内随机执行）。
- 接入点动定时 / 延时关（开启后延时自动关闭，inching）。
- 接入倒计时（一次性倒计时关闭）。
- 接入天文定时（日出 / 日落，注意：不属于本 SDK，通过
@ray-js/ray实现）。
搭配使用 {#usage}
可复制片段（跨工程通用）
代码片段集中在 references/snippets.md，按锚点访问：
- 入口
init - 最小页面
ConflictPopup - 五类 SDK 内定时的写入示例
- 退出
destroy
生成或迁移代码时：先读对应锚点，再按目标工程补齐类型与 i18n。天文定时不在本 SDK 中，不要从这些片段推断，请使用 references/astronomical.md。
init（必读）
在 src/app.tsx 的 onLaunch —— 或等价首启钩子 —— 早于任何定时 hook / API 调用时执行。若启动时 DP schema 尚未就绪，supportCloud / supportCycle / supportRandom / supportInching 传 'auto'，或从 URL 取明确的 'y' / 'n'。
一般情况下，init 一次即可，不需要 changeConfig。仅当 devId / groupId 运行时切换、需要让 SDK 重建内部状态时，才调用 changeConfig（字段形态与 init 一致，参见 README）。
退出
离开定时模块时调用 destroy()，并把先前注册的 on*（如 onCloudUpdate）与对应 off* 配对。是否绑定页面 onUnload 由业务决定。
冲突弹窗（useDefaultModal）
- 定时 API 传
{ useDefaultModal: true }时，SDK 会在栈顶页面执行selectComponent('#<id>')并调用show(conflictData, validateData)。 init的conflictModallId（常见smart-conflict-popup）必须等于页面组件的id。- 在所有可能触发默认冲突 UI 的页面挂载弹窗组件（落地路径
src/components/conflict/）。不要挂在src/app.tsx上 —— 它不是页面栈容器。
推荐调用顺序（与 README 对齐）
init（早于任何定时 hook / 写入 API）。- 确认能力（云定时支持、群组、倒计时配置）。
- 调
electri.*/addCloudTimer/createCountdown/addDpTimer。 - 统一处理
success/cancel/{ conflict, validateData }。 - 注册
on*监听，退出前off*+destroy()。
延伸阅读
- docs/integration-guide.md：URL query 表、README ↔ 工程映射、页面路径索引、以及 §5 API 注意事项与最佳实践。
- references/astronomical.md：
@ray-js/ray的五个天文 API（add / list / update / updateStatus / remove）、参数语义（loops、offsetType、time偏移、bizType）以及可移植的 TS 辅助函数。用户问到「天文定时 / 日出 / 日落」时阅读。
注意事项 {#tip}
API 注意事项与最佳实践
完整表格见 docs/integration-guide.md §5。
- 铁律：所有定时读写必须在
init成功之后。统一处理返回结构：success/cancel/pass/{ conflict, validateData }。启用路径会跑冲突校验。 electri.*/ 云 / 倒计时：要使用默认冲突 UI，须传useDefaultModal: true，且当前页面挂载了id与conflictModallId匹配的ConflictPopup。- 云定时：群组默认不支持。列表与操作可用
isLANOnline/isLocalOnline驱动在线提示。 - 倒计时：按 README，枚举型总时长需配合
totalRange+cancelValue；错误码参见 README。 - 自定义 DP 定时：使用
addDpTimer。三种标准电工类型仍优先electri.*。 - 监听：
onCloudUpdate等必须与off*成对，防止泄漏。
术语：用户说「点动」或「电动定时」时，按 inching / 延时关（sdk_inching）处理。
自检
-
src/app.tsx是否在任何首屏定时逻辑前调用了init，并且没有在常规启动流程里无谓地调用changeConfig？ - 所有使用
useDefaultModal: true的页面，是否在页面根节点挂载了id === conflictModallId的冲突组件？ - 是否把 SDK 字段与工程 query 字段分开（尤其倒计时）？
- 天文功能是否避开了
electri.*/addDpTimer，并改用 references/astronomical.md 列出的五个@ray-js/ray天文 API？