nayota-show-sdk 1.3.77 → 1.3.78

package/AI_EXECUTABLE_TASKS.md

@@ -0,0 +1,558 @@
+# nayota-show-sdk 迁移到 nayota-impossible-pro 的 AI 可执行开发任务单
+
+## 1. 任务目标
+
+把 `nayota-show-sdk` 从“默认面向 `nayota-impossible-pro-orgin` 单后端”的实现，改造成“可同时接入 `nayota-impossible-pro` 正式接口和兼容接口”的 SDK。
+
+本任务的目标不是重写后端，也不是恢复所有旧接口，而是在**不破坏新后端正式运行边界**的前提下，完成 SDK 兼容层建设。
+
+## 2. 总体约束
+
+开发时必须遵守以下约束：
+
+- 不修改 `nayota-impossible-pro` 的正式运行边界
+- 不要求把旧展示模块重新挂回 `nayota-impossible-pro/server/routes/index.route.js`
+- 不把新后端退回到 Mongo/Mongoose 风格主链
+- `nayota-show-sdk` 对外 API 名称保持不变
+- SDK 对调用方继续兼容 `_id`
+- 新增代码尽量集中在 `config/`、`utils/`、`api/` 内
+- 先做 SDK 层适配，不做后端侵入式改造
+
+## 3. 已确认的模块分层
+
+### 3.1 Formal 模块
+
+这些模块优先走 `nayota-impossible-pro` 正式 `/api`：
+
+- `systeminfo`
+- `router`
+- `bmsRole`
+- `bmsRouter`
+- `tag`
+- `svglib`
+- `relationPlatform`
+- `components`
+- `application`
+- `upload`
+- `appRouter`
+- `userDevice`
+- `line`
+- `inspectionPoints`
+- `patrolPoints`
+- `inspectionTask`
+- `inspectionTaskSub`
+- `product`
+- `reservation`
+- `sensor`
+- `scadaProject`
+- `maintenancePlan`
+- `maintenanceRecord`
+- `sensorStatusConfig`
+
+### 3.2 Compat/Fallback 模块
+
+这些模块不能假定正式后端一定有，需要走兼容接口或 fallback：
+
+- `alarmProgress`
+- `alarmRecord`
+- `area`
+- `areaClass`
+- `datavDatas`
+- `datavForms`
+- `departs`
+- `deviceClass`
+- `devices`
+- `video`
+- `view`
+
+### 3.3 暂不开发模块
+
+这些模块本轮不做正式迁移，只保留明确错误提示能力：
+
+- `attendanceRecord`
+- `workSchedule`
+- `energyCalculation`
+- `energyConsumption`
+
+## 4. 交付物
+
+本轮开发完成后，应至少交付：
+
+- 可同时支持 `formalServer` 与 `compatServer` 的 SDK 配置
+- 统一的 `_id/id` 兼容工具
+- formal 请求客户端
+- compat 请求客户端
+- missing-endpoint fallback 工具
+- 至少 5 个核心模块完成接入改造
+- 对暂不开发模块给出清晰错误
+- 文档更新
+
+## 5. 执行顺序
+
+必须按以下顺序执行，不要跳步。
+
+### 阶段 1：基础设施
+
+先完成配置层与工具层，禁止在没有工具层的情况下分散修改 API 文件。
+
+### 阶段 2：核心正式模块
+
+优先迁移：
+
+- `reservation`
+- `maintenancePlan`
+- `maintenanceRecord`
+- `userDevice`
+- `router`
+
+### 阶段 3：fallback 模块样板
+
+优先迁移：
+
+- `departs`
+- `devices`
+
+### 阶段 4：冻结模块处理
+
+给以下模块增加明确错误或占位说明：
+
+- `attendanceRecord`
+- `workSchedule`
+- `energyCalculation`
+- `energyConsumption`
+
+### 阶段 5：README 补充
+
+补充新的配置方式与模块接入说明。
+
+## 6. 具体任务
+
+## Task 1: 改造 SDK 配置
+
+### 目标
+
+让 SDK 支持双服务地址。
+
+### 修改文件
+
+- `config/urlcfg.js`
+
+### 要求
+
+- 保留现有 `showServer`
+- 新增 `formalServer`
+- 新增 `compatServer`
+- 新增 `getFormalUrl()`
+- 新增 `getCompatUrl()`
+- 保持旧调用方式可用
+
+### 兼容规则
+
+- 若只传 `showServer`，则 `formalServer = showServer`
+- 若未传 `compatServer`，compat 模块调用时不能静默失败，必须给出清晰错误
+
+### 验收标准
+
+- 原有 `NayotaSdk.config({ showServer })` 仍可执行
+- 新增 `formalServer` 与 `compatServer` 后能被请求层读取
+
+## Task 2: 新增 ID 兼容工具
+
+### 目标
+
+统一处理 `id/_id`、引用对象和引用数组。
+
+### 新增文件
+
+- `utils/id-compat.js`
+
+### 需要实现的函数
+
+- `attachLegacyId(value)`
+- `normalizeOutgoingIds(value)`
+- `normalizeRef(value)`
+- `normalizeRefArray(value)`
+
+### 规则
+
+#### `attachLegacyId`
+
+- 如果对象有 `id` 但没有 `_id`，补 `_id = id`
+- 递归处理数组和对象
+
+#### `normalizeOutgoingIds`
+
+- 如果对象有 `_id`，出参请求前转成 `id`
+- 不要覆盖已经存在的 `id`
+
+#### `normalizeRef`
+
+- 输入为字符串，原样返回
+- 输入为 `{ _id }` 或 `{ id }`，返回对应 id
+- 其他情况原样返回或返回 `null`
+
+#### `normalizeRefArray`
+
+- 把 `Array<object|string>` 统一转为 `Array<string>`
+- 自动过滤空值
+
+### 验收标准
+
+- 更新类接口能接受 `data._id`
+- 嵌套对象里出现的 `id/_id` 能递归处理
+- 设备/角色/children 这类引用数组能归一化
+
+## Task 3: 改造 formal 请求客户端
+
+### 目标
+
+把当前主请求层升级为可自动处理 `id/_id`。
+
+### 修改文件
+
+- `utils/http-config.js`
+- `utils/http-config-form.js`
+
+### 要求
+
+- 请求前调用 `normalizeOutgoingIds`
+- 响应后调用 `attachLegacyId`
+- 保留 token 处理逻辑
+- `baseURL` 改为读取 `getFormalUrl()`
+
+### 验收标准
+
+- formal 接口返回 `id` 时，SDK 使用方能拿到 `_id`
+- 旧模块传 `_id` 更新不会丢 id
+
+## Task 4: 新增 compat 请求客户端
+
+### 目标
+
+提供独立的兼容请求通道。
+
+### 新增文件
+
+- `utils/http-config-compat.js`
+- `utils/http-config-compat-form.js`
+
+### 要求
+
+- 结构尽量与 formal 客户端一致
+- `baseURL` 来自 `getCompatUrl()`
+- 若未配置 compat 地址，则抛清晰错误
+- 同样支持 token、`normalizeOutgoingIds`、`attachLegacyId`
+
+### 错误文案要求
+
+错误里要明确指出：
+
+- 当前模块需要 `compatServer`
+- 当前未配置 compat 服务地址
+
+### 验收标准
+
+- compat 请求链可以独立工作
+- 未配置 compat 地址时错误清晰
+
+## Task 5: 新增 fallback 工具
+
+### 目标
+
+让模块可以先尝试 formal，缺接口时回退到 compat。
+
+### 新增文件
+
+- `utils/request-fallback.js`
+
+### 需要实现的函数
+
+- `isMissingEndpoint(error)`
+- `requestWithMissingEndpointFallback(primaryRequest, fallbackRequest)`
+
+### 规则
+
+- `404` 和 `501` 视为缺接口
+- 只有缺接口才触发 fallback
+- 鉴权错误、参数错误、500 不允许 fallback 掩盖
+
+### 验收标准
+
+- formal 404 时会改走 compat
+- formal 401/500 时不会偷偷 fallback
+
+## Task 6: 建立模块路由策略表
+
+### 目标
+
+不要把“哪个模块走 formal / compat / fallback / disabled”写死在每个 API 文件里。
+
+### 新增文件
+
+- `utils/module-route-policy.js`
+
+### 至少导出
+
+- `FORMAL_MODULES`
+- `FALLBACK_MODULES`
+- `DISABLED_MODULES`
+
+### 验收标准
+
+- 后续 API 文件能基于该策略统一接入
+- 文档和代码中的模块分类一致
+
+## Task 7: 改造 reservation 模块
+
+### 目标
+
+把 `reservation` 接到正式接口，并完成 `_id/id` 兼容。
+
+### 修改文件
+
+- `api/reservation.js`
+
+### 关键要求
+
+- `updateOne(data)` 不能只用 `data._id`
+- 必须兼容 `data._id || data.id`
+- 保留 `getReservationsByDepart`
+- 默认走 formal
+
+### 验收标准
+
+- `list/create/getOne/updateOne/deleteOne/deleteMany/getReservationsByDepart` 均可用
+- 更新接口接受 `_id`
+- 返回对象含 `_id`
+
+## Task 8: 改造 maintenancePlan 模块
+
+### 目标
+
+把设备和传感器引用数组归一化后再请求正式后端。
+
+### 修改文件
+
+- `api/maintenancePlan.js`
+
+### 关键要求
+
+- `devices` 支持 `['id']` 或 `[{_id:'id'}]`
+- `sensors` 支持 `['id']` 或 `[{_id:'id'}]`
+- `updateOne` 支持 `_id || id`
+
+### 验收标准
+
+- create/update 时引用数组被正确转成 id 数组
+- 返回数据继续兼容 `_id`
+
+## Task 9: 改造 maintenanceRecord 模块
+
+### 目标
+
+对正式模块完成基础 `id/_id` 兼容。
+
+### 修改文件
+
+- `api/maintenanceRecord.js`
+
+### 要求
+
+- `updateOne` 支持 `_id || id`
+- 保留现有自定义接口
+
+### 验收标准
+
+- 增删改查正常
+- 批量接口不因 `id/_id` 差异出错
+
+## Task 10: 改造 userDevice 模块
+
+### 目标
+
+处理数组字段与文本/JSON 字段的兼容。
+
+### 修改文件
+
+- `api/userDevice.js`
+
+### 关键字段
+
+- `devices`
+- `apps`
+- `areas`
+- `departs`
+- `showFields`
+- `detailParams`
+- `airConditionerEnergyData`
+
+### 要求
+
+- 引用数组统一转为字符串数组
+- `updateOne` 支持 `_id || id`
+- 不在 SDK 里强行改变返回结构类型，只做最小兼容
+
+### 验收标准
+
+- create/update 不因对象数组而失败
+- 返回对象带 `_id`
+
+## Task 11: 改造 router 模块
+
+### 目标
+
+适配树结构模块的 children/roles 引用数组。
+
+### 修改文件
+
+- `api/router.js`
+
+### 要求
+
+- `children` 可传字符串数组或对象数组
+- `roles` 可传字符串数组或对象数组
+- `updateOne` 支持 `_id || id`
+
+### 验收标准
+
+- 结构更新时 children/roles 被正确归一
+- 查询返回继续兼容 `_id`
+
+## Task 12: 改造 departs 模块为 fallback 模板
+
+### 目标
+
+为未正式接入模块建立标准 fallback 模式。
+
+### 修改文件
+
+- `api/departs.js`
+
+### 要求
+
+- 先走 formal
+- 缺接口时走 compat
+- 不再把 fallback 逻辑散落到模块内部实现细节中
+
+### 验收标准
+
+- formal 有接口时优先走 formal
+- formal 缺接口时自动走 compat
+
+## Task 13: 改造 devices 模块为 fallback 模板
+
+### 目标
+
+建立第二个 fallback 参考实现。
+
+### 修改文件
+
+- `api/devices.js`
+
+### 要求
+
+- `getOne/updateOne/deleteOne/deleteMany` 支持 fallback
+- 批量接口若 formal 缺失，可拆成 compat 多次请求
+- `updateOne` 支持 `_id || id`
+
+### 验收标准
+
+- formal 缺接口时兼容链路能工作
+- 批量兼容逻辑可用
+
+## Task 14: 给冻结模块增加明确错误
+
+### 目标
+
+避免 AI 或调用方误以为这些模块已经正式可用。
+
+### 修改文件
+
+- `api/attendanceRecord.js`
+- `api/workSchedule.js`
+- `api/energyCalculation.js`
+- `api/energyConsumption.js`
+
+### 要求
+
+- 保持模块导出存在
+- 调用时抛出清晰错误
+- 错误中说明该模块当前不在正式迁移范围内
+
+### 示例
+
+```js
+throw new Error('[nayota-show-sdk] workSchedule is not available on nayota-impossible-pro formal runtime.')
+```
+
+### 验收标准
+
+- 不会静默返回假数据
+- 错误文案清晰、可定位
+
+## Task 15: 更新 README
+
+### 目标
+
+让使用方知道新配置方式和模块边界。
+
+### 修改文件
+
+- `README.md`
+
+### 需要补充
+
+- `formalServer`
+- `compatServer`
+- fallback 机制
+- 哪些模块走正式链路
+- 哪些模块依赖 compat
+- 哪些模块暂不支持
+
+### 验收标准
+
+- 新使用方式有示例
+- 老配置兼容规则有说明
+
+## 7. 每个任务完成后必须自检
+
+每完成一个任务，至少检查：
+
+- 是否破坏了现有导出名称
+- 是否保留了旧 `_id` 兼容
+- 是否把请求路由来源写对
+- 是否把 fallback 触发条件控制在 404/501
+- 是否引入了新的破坏性默认行为
+
+## 8. 推荐实现策略
+
+AI 实施时推荐采用“小步提交”方式：
+
+1. 先完成 `Task 1-6`
+2. 再完成 `Task 7-11`
+3. 再完成 `Task 12-13`
+4. 最后完成 `Task 14-15`
+
+不要一口气同时改完全部 API 文件。
+
+## 9. 本任务单对应的上游分析文档
+
+执行时应同时参考：
+
+- [SDK_MIGRATION_PLAN.md](./SDK_MIGRATION_PLAN.md)
+
+如果任务单和分析文档冲突，以任务单中的模块边界和开发顺序为准；如果发现边界本身错误，应先修正文档，再继续开发。
+
+## 10. 建议给 AI 的执行提示词
+
+可直接把下面这段发给 AI：
+
+```text
+你现在在 nayota-sdk/nayota-show-sdk 仓库中工作。
+目标是按照 AI_EXECUTABLE_TASKS.md 执行 SDK 迁移。
+严格按任务顺序执行，先做 Task 1-6，再做 Task 7-11。
+不要修改 nayota-impossible-pro 的正式运行边界，不要恢复旧模块到正式主链。
+保留 nayota-show-sdk 对外 API 名称不变，统一兼容 _id/id。
+每完成一个任务都做最小自检，并汇报改动文件与验收结果。
+```
+