qiyu-cli 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (230) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +467 -2
  3. package/dist/cli.js +248 -0
  4. package/dist/commands/api.js +770 -0
  5. package/dist/commands/auth.js +349 -0
  6. package/dist/commands/credentials-source.js +70 -0
  7. package/dist/commands/db.js +503 -0
  8. package/dist/commands/local-fallback-wiring.js +67 -0
  9. package/dist/commands/local-fallback.js +34 -0
  10. package/dist/commands/query.js +564 -0
  11. package/dist/commands/skill-specs.js +64 -0
  12. package/dist/commands/skill.js +908 -0
  13. package/dist/commands/spec-types.js +145 -0
  14. package/dist/commands/stats.js +299 -0
  15. package/dist/commands/store-flags.js +56 -0
  16. package/dist/commands/store.js +258 -0
  17. package/dist/commands/sync-run.js +479 -0
  18. package/dist/commands/sync.js +757 -0
  19. package/dist/commands/tree.js +27 -0
  20. package/dist/core/config.js +259 -0
  21. package/dist/core/credentials.js +71 -0
  22. package/dist/core/edition.js +28 -0
  23. package/dist/core/envelope.js +201 -0
  24. package/dist/core/errors.js +356 -0
  25. package/dist/core/http.js +348 -0
  26. package/dist/core/ratelimit.js +126 -0
  27. package/dist/core/registry/index.js +212 -0
  28. package/dist/core/registry/params/ai.knowledge.addKnowledge.json +88 -0
  29. package/dist/core/registry/params/ai.knowledge.deleteKnowledges.json +46 -0
  30. package/dist/core/registry/params/ai.knowledge.editChannelAnswer.json +60 -0
  31. package/dist/core/registry/params/ai.knowledge.editKnowledge.json +95 -0
  32. package/dist/core/registry/params/ai.knowledge.editKnowledgeNoSimilars.json +102 -0
  33. package/dist/core/registry/params/ai.knowledge.getCategoryTree.json +39 -0
  34. package/dist/core/registry/params/ai.knowledge.getDetail.json +46 -0
  35. package/dist/core/registry/params/ai.knowledge.search.json +67 -0
  36. package/dist/core/registry/params/ai.statistic.transferHuman.json +60 -0
  37. package/dist/core/registry/params/category.list.json +39 -0
  38. package/dist/core/registry/params/chat.queue.group.query.json +39 -0
  39. package/dist/core/registry/params/crm.modifyOrder.json +48 -0
  40. package/dist/core/registry/params/crm.modifyUser.json +48 -0
  41. package/dist/core/registry/params/crm.syncCrmInfo.json +46 -0
  42. package/dist/core/registry/params/crm.tagChange.json +74 -0
  43. package/dist/core/registry/params/data.overview.ipcc.json +32 -0
  44. package/dist/core/registry/params/data.overview.session.json +53 -0
  45. package/dist/core/registry/params/evaluation.setting.get.json +39 -0
  46. package/dist/core/registry/params/event.applyStaff.json +116 -0
  47. package/dist/core/registry/params/event.evaluate.json +74 -0
  48. package/dist/core/registry/params/event.inviteEvaluate.json +81 -0
  49. package/dist/core/registry/params/event.qcResult.json +166 -0
  50. package/dist/core/registry/params/event.queryQueueStatus.json +39 -0
  51. package/dist/core/registry/params/event.queueEnter.json +40 -0
  52. package/dist/core/registry/params/event.queueLeave.json +46 -0
  53. package/dist/core/registry/params/event.quitQueue.json +39 -0
  54. package/dist/core/registry/params/event.sessionChange.json +95 -0
  55. package/dist/core/registry/params/event.sessionData.json +452 -0
  56. package/dist/core/registry/params/event.sessionEnd.json +117 -0
  57. package/dist/core/registry/params/event.sessionStart.json +109 -0
  58. package/dist/core/registry/params/event.updateUInfo.json +46 -0
  59. package/dist/core/registry/params/export.session.check.json +7 -0
  60. package/dist/core/registry/params/export.session.json +7 -0
  61. package/dist/core/registry/params/export.session.one.json +7 -0
  62. package/dist/core/registry/params/export.session.one.message.json +7 -0
  63. package/dist/core/registry/params/get_call_order.json +50 -0
  64. package/dist/core/registry/params/get_call_user_info.json +36 -0
  65. package/dist/core/registry/params/get_order.json +50 -0
  66. package/dist/core/registry/params/get_token.json +22 -0
  67. package/dist/core/registry/params/get_user_info.json +36 -0
  68. package/dist/core/registry/params/icoutcall.callIntercept.list.json +32 -0
  69. package/dist/core/registry/params/icoutcall.dialogFlow.fuzzySearch.json +53 -0
  70. package/dist/core/registry/params/icoutcall.dialogFlow.getDialogFlowList.json +32 -0
  71. package/dist/core/registry/params/icoutcall.get.customer.json +39 -0
  72. package/dist/core/registry/params/icoutcall.get.jobdetail.json +39 -0
  73. package/dist/core/registry/params/icoutcall.get.jobproperties.json +39 -0
  74. package/dist/core/registry/params/icoutcall.history.seat.json +67 -0
  75. package/dist/core/registry/params/icoutcall.history.team.json +67 -0
  76. package/dist/core/registry/params/icoutcall.job.create.json +53 -0
  77. package/dist/core/registry/params/icoutcall.job.importcustomer.json +46 -0
  78. package/dist/core/registry/params/icoutcall.job.pause.json +39 -0
  79. package/dist/core/registry/params/icoutcall.job.readdcustomer.json +109 -0
  80. package/dist/core/registry/params/icoutcall.job.start.json +39 -0
  81. package/dist/core/registry/params/icoutcall.job.terminate.json +39 -0
  82. package/dist/core/registry/params/icoutcall.phone.getLineList.json +32 -0
  83. package/dist/core/registry/params/ipcc.calltask.add.auto.json +117 -0
  84. package/dist/core/registry/params/ipcc.calltask.add.byCustom.json +96 -0
  85. package/dist/core/registry/params/ipcc.calltask.add.byRelation.json +82 -0
  86. package/dist/core/registry/params/ipcc.calltask.add.toGroup.json +89 -0
  87. package/dist/core/registry/params/ipcc.calltask.add.toStaff.json +89 -0
  88. package/dist/core/registry/params/ipcc.calltask.get.json +47 -0
  89. package/dist/core/registry/params/ipcc.calltaskdetail.add.json +54 -0
  90. package/dist/core/registry/params/ipcc.calltaskdetail.delete.json +40 -0
  91. package/dist/core/registry/params/ipcc.calltaskdetail.get.json +54 -0
  92. package/dist/core/registry/params/ipcc.calltaskdetail.update.json +40 -0
  93. package/dist/core/registry/params/ipcc.customfield.template.get.json +47 -0
  94. package/dist/core/registry/params/ipcc.login.json +47 -0
  95. package/dist/core/registry/params/kefu.add.json +130 -0
  96. package/dist/core/registry/params/kefu.delete.json +39 -0
  97. package/dist/core/registry/params/kefu.update.json +137 -0
  98. package/dist/core/registry/params/kefu.v2.query.json +39 -0
  99. package/dist/core/registry/params/kefuGroup.add.json +39 -0
  100. package/dist/core/registry/params/kefuGroup.delete.json +39 -0
  101. package/dist/core/registry/params/kefuGroup.update.json +46 -0
  102. package/dist/core/registry/params/kefuGroup.updateKefus.json +46 -0
  103. package/dist/core/registry/params/merchant.account.login.json +53 -0
  104. package/dist/core/registry/params/merchant.changePassword.json +46 -0
  105. package/dist/core/registry/params/merchant.create.json +81 -0
  106. package/dist/core/registry/params/merchant.disable.json +39 -0
  107. package/dist/core/registry/params/merchant.enable.json +39 -0
  108. package/dist/core/registry/params/merchant.list.json +46 -0
  109. package/dist/core/registry/params/merchant.query.json +46 -0
  110. package/dist/core/registry/params/merchant.update.json +74 -0
  111. package/dist/core/registry/params/message.send.image.json +53 -0
  112. package/dist/core/registry/params/message.send.json +53 -0
  113. package/dist/core/registry/params/message.send.voice.json +53 -0
  114. package/dist/core/registry/params/message.sendFile.json +39 -0
  115. package/dist/core/registry/params/message.uploadFile.json +39 -0
  116. package/dist/core/registry/params/online.session.category.list.json +39 -0
  117. package/dist/core/registry/params/online.session.customfield.template.json +39 -0
  118. package/dist/core/registry/params/online.session.customfield.update.json +74 -0
  119. package/dist/core/registry/params/order.upload.json +40 -0
  120. package/dist/core/registry/params/push.msg.image.json +74 -0
  121. package/dist/core/registry/params/push.msg.richText.json +74 -0
  122. package/dist/core/registry/params/push.msg.text.json +74 -0
  123. package/dist/core/registry/params/receive.message.json +89 -0
  124. package/dist/core/registry/params/robot.data.getQuestionsByCategoryName.json +67 -0
  125. package/dist/core/registry/params/robot.data.knowledge.json +46 -0
  126. package/dist/core/registry/params/robot.data.kpoint.json +46 -0
  127. package/dist/core/registry/params/robot.data.queryStandardByEffectiveQuestion.json +46 -0
  128. package/dist/core/registry/params/robot.data.queryStandardQuestionList.json +46 -0
  129. package/dist/core/registry/params/robot.evaluation.comment.json +67 -0
  130. package/dist/core/registry/params/robot.evaluation.setting.json +46 -0
  131. package/dist/core/registry/params/robot.session.assist.json +74 -0
  132. package/dist/core/registry/params/robot.session.chat.json +74 -0
  133. package/dist/core/registry/params/robot.session.close.json +53 -0
  134. package/dist/core/registry/params/robot.session.commonQuestions.json +74 -0
  135. package/dist/core/registry/params/robot.session.create.json +81 -0
  136. package/dist/core/registry/params/robot.session.evaluation.json +67 -0
  137. package/dist/core/registry/params/robot.session.msgAssociate.json +46 -0
  138. package/dist/core/registry/params/robot.session.msgEvaluation.json +53 -0
  139. package/dist/core/registry/params/robot.session.msgPredict.json +74 -0
  140. package/dist/core/registry/params/robot.session.transfer.json +36 -0
  141. package/dist/core/registry/params/robot.session.uploadFile.json +32 -0
  142. package/dist/core/registry/params/robot.statistic.summary.json +53 -0
  143. package/dist/core/registry/params/robot.transfer.config.json +15 -0
  144. package/dist/core/registry/params/session.user.profile.json +39 -0
  145. package/dist/core/registry/params/settings.wxTemplates.json +46 -0
  146. package/dist/core/registry/params/smstask.create.json +53 -0
  147. package/dist/core/registry/params/smstask.status.json +39 -0
  148. package/dist/core/registry/params/staff.group.list.new.json +39 -0
  149. package/dist/core/registry/params/staff.group.members.new.json +46 -0
  150. package/dist/core/registry/params/staff.list.new.json +46 -0
  151. package/dist/core/registry/params/staff.login.json +47 -0
  152. package/dist/core/registry/params/statistic.overview.json +61 -0
  153. package/dist/core/registry/params/statistic.performance.json +82 -0
  154. package/dist/core/registry/params/statistic.salaryDetail.json +54 -0
  155. package/dist/core/registry/params/statistic.satisfaction.report.json +68 -0
  156. package/dist/core/registry/params/statistic.staffAttendance.json +75 -0
  157. package/dist/core/registry/params/statistic.staffquality.json +75 -0
  158. package/dist/core/registry/params/statistic.staffworklod.json +68 -0
  159. package/dist/core/registry/params/tag.all.json +32 -0
  160. package/dist/core/registry/params/tag.batchUpdate.json +32 -0
  161. package/dist/core/registry/params/tag.update.json +60 -0
  162. package/dist/core/registry/params/ticket.apply.json +46 -0
  163. package/dist/core/registry/params/ticket.batch.modify.json +53 -0
  164. package/dist/core/registry/params/ticket.create.json +151 -0
  165. package/dist/core/registry/params/ticket.filter.count.json +46 -0
  166. package/dist/core/registry/params/ticket.filter.list.json +46 -0
  167. package/dist/core/registry/params/ticket.finish.json +60 -0
  168. package/dist/core/registry/params/ticket.followers.update.json +60 -0
  169. package/dist/core/registry/params/ticket.list.json +74 -0
  170. package/dist/core/registry/params/ticket.log.json +39 -0
  171. package/dist/core/registry/params/ticket.modify.json +74 -0
  172. package/dist/core/registry/params/ticket.new.detail.json +39 -0
  173. package/dist/core/registry/params/ticket.reminder.json +60 -0
  174. package/dist/core/registry/params/ticket.reopen.json +67 -0
  175. package/dist/core/registry/params/ticket.reply.json +60 -0
  176. package/dist/core/registry/params/ticket.search.json +116 -0
  177. package/dist/core/registry/params/ticket.template.fields.json +39 -0
  178. package/dist/core/registry/params/ticket.template.list.json +39 -0
  179. package/dist/core/registry/params/ticket.transfer.json +74 -0
  180. package/dist/core/registry/params/track.event.set.json +32 -0
  181. package/dist/core/registry/params/wecom.robot.switch.json +43 -0
  182. package/dist/core/registry/params.js +84 -0
  183. package/dist/core/registry/specs.json +2172 -0
  184. package/dist/core/registry/validate.json +11 -0
  185. package/dist/core/registry/validation-overrides.js +98 -0
  186. package/dist/core/sanitize.js +24 -0
  187. package/dist/core/sign.js +21 -0
  188. package/dist/core/time.js +194 -0
  189. package/dist/core/validate.js +140 -0
  190. package/dist/output.js +263 -0
  191. package/dist/postinstall.js +178 -0
  192. package/dist/query/errors.js +395 -0
  193. package/dist/query/mask.js +368 -0
  194. package/dist/query/metric-catalog.js +85 -0
  195. package/dist/query/sandbox.js +544 -0
  196. package/dist/query/table-query.js +297 -0
  197. package/dist/query/time-shape.js +44 -0
  198. package/dist/schedule/install.js +377 -0
  199. package/dist/skill/check.js +429 -0
  200. package/dist/skill/detect.js +371 -0
  201. package/dist/skill/install.js +1202 -0
  202. package/dist/skill/paths.js +343 -0
  203. package/dist/skill/qiyu/SKILL.md +92 -0
  204. package/dist/skill/qiyu/errors.md +55 -0
  205. package/dist/skill/qiyu/forbidden.md +52 -0
  206. package/dist/skill/qiyu/metrics.md +65 -0
  207. package/dist/skill/qiyu/protocols.md +55 -0
  208. package/dist/skill/qiyu/setup.md +50 -0
  209. package/dist/skill/refs.js +379 -0
  210. package/dist/store/config.js +137 -0
  211. package/dist/store/duckdb.js +321 -0
  212. package/dist/store/index.js +18 -0
  213. package/dist/store/retry.js +36 -0
  214. package/dist/store/schema.js +419 -0
  215. package/dist/store/types.js +4 -0
  216. package/dist/sync/day.js +8 -0
  217. package/dist/sync/engine.js +818 -0
  218. package/dist/sync/rate-gate.js +95 -0
  219. package/dist/sync/registry.js +22 -0
  220. package/dist/sync/state.js +114 -0
  221. package/dist/sync/tasks/dim.js +186 -0
  222. package/dist/sync/tasks/knowledge.js +252 -0
  223. package/dist/sync/tasks/pace.js +66 -0
  224. package/dist/sync/tasks/pipeline.js +321 -0
  225. package/dist/sync/tasks/reports.js +448 -0
  226. package/dist/sync/tasks/sessions.js +188 -0
  227. package/dist/sync/tasks/tickets.js +219 -0
  228. package/dist/sync/types.js +1 -0
  229. package/dist/sync/windowing.js +56 -0
  230. package/package.json +52 -4
@@ -0,0 +1,448 @@
1
+ // src/sync/tasks/reports.ts
2
+ // D-T7:9 报表任务声明(spec §5.2)+ 按天轮转标记。
3
+ // 全部 kind=windowed、deleteRangeInsert(stat_date)、reportDayRotation=true。
4
+ // 日期一律由调用方按窗口填写(响应内 date 逐接口语义不同——统一不信);
5
+ // 窗口上限按实测逐接口注册(§7.4.1:严格形式 span ≤ N 天对两族判定式都安全)。
6
+ // 业务字段收敛进 payload JSON 字符串列(表设计见 schema.ts 报表批次注释)。
7
+ //
8
+ // 全场景审查(修复批 1)在本文件收敛的语义:
9
+ // · B 高-1:**所有**调用走 callPaced(含 penalize 接线)——裸 call 会让本地令牌桶的
10
+ // 拒绝直接冒泡成 fetch_failed gap,且远端限频的证据(冷却行)无人写;空窗假空重试
11
+ // 必然二次调用同路径,是最容易撞上的一条路径;
12
+ // · A 中-2:日期列(stat_date/work_date)按 **Asia/Shanghai 天对齐**,与
13
+ // deleteRangeInsert 的删除边界同口径(rangeAlign='shanghaiDay')——否则 --full
14
+ // 与增量对同一业务日落在互不覆盖的删除范围里,同日写出两行;
15
+ // · G 中-2:transferHuman 的窗口上限 365 → 360(实测恰好 365 天被拒、364 天也会
16
+ // 报 Internal error,设计稿 §13 建议 ≤360);
17
+ // · G 高-1:attendance/performance 声明 windowEndClamp(endTime 不得晚于昨天 0:00);
18
+ // · C 中-5:载荷为 null 不再当合法空窗(形状漂移必须显式失败);
19
+ // · C 中-3:分页短读终检(total 与累计行数核对)+ 页数上限(对齐 knowledge 口径);
20
+ // · C 中-4:staff_attendance 的脏时间戳逐行丢弃,不再抛 RangeError 断整窗;
21
+ // · C 低-7:空串主键行拒绝。
22
+ //
23
+ // 修复批 4(CodeRabbit #1)——**聚合报表按天切片(maxWindowDays=1)**:
24
+ // 这些接口返回的是**窗口聚合值**(overview=一行全局汇总、staffworklod=每客服一行、
25
+ // transferHuman 恒 1 行),响应里的 `date` 字段原文是
26
+ // "this date has no specific meaning, it only indicates the start time of the current query"。
27
+ // 因此多天窗口 = 一条多天聚合被标在某一天:`daily_overview` 会把 31 天汇总写成第 1 天
28
+ // (E 的「每日概览」读到 31 天累计值),且 deleteRangeInsert 按 stat_date 删范围时
29
+ // 下一次不同起点的窗口删不到旧行(陈旧行残留)。水位字段是 query_start ——
30
+ // 按天窗口才能每日推进。按天切片后窗口数 = 天数(--full 从 1970 起会切出上万窗,
31
+ // 见 spec §5.2 与 README 的量级说明)。
32
+ // 唯一例外:staff_attendance 的响应**有逐行可信时间戳**(`date` 按小时对齐)——
33
+ // 保持 31 天窗口(一行一小时 ≈ 1.7 万行/窗),但 stat_date 由该行的 hour_ts 推导。
34
+ //
35
+ // 修复批 5(复审 N1)——**窗口按上海日界对齐(windowAlign: 'shanghaiDay')**:
36
+ // 按天切片(maxWindowDays=1)只保证「窗宽 ≤ 1 天」;窗口**起点**仍来自水位续跑
37
+ // (watermark+1ms)或任意时刻的 --since —— 窗形如 [今天18:23, 明天18:23):只写一行
38
+ // stat_date=dayOf(start)(今天),拉到的却是跨两天的聚合值,而删除范围是
39
+ // [dayOf(start), dayOf(end−1ms)]=两天 → 「明天」日的行被删掉却不重写(该日数据是上次
40
+ // run 的切片聚合)。「每日概览」因此只在日对齐 run(--until 日期 / 日界水位)下才是
41
+ // 精确全天值,常规晚间 run 下语义每天漂移。
42
+ // 声明 windowAlign 后:引擎按上海日界网格切窗(首窗 start 允许被 range.start 钳制、
43
+ // 末窗 end 钳到 range.end),水位续跑的起点也落到日界(水位所在日整体重拉)——
44
+ // 每窗恰是一整个业务日。
45
+ // **声明它 = 「该表的按日行集必须与按日窗口闭环」**(stat_date 行 ↔ 按日窗一一对应,
46
+ // 删除范围与写入行集同源)。
47
+ // ⚠️ 边界:staff_attendance **不声明**——主键是 staff_id+hour_ts(行集本身幂等),
48
+ // stat_date 只是由行内 hour_ts 派生的辅助列;31 天窗里的小时行跨自然日无害
49
+ // (删除范围 [dayOf(w.start), dayOf(w.end−1ms)] 覆盖窗内所有天,与每行的 stat_date 一致)。
50
+ // 它的接口有**逐行可信时间戳**,按天切片反而白白放大 31 倍窗口数。
51
+ import { callPaced, nowIsoOf } from './pace.js';
52
+ import { shanghaiDayIso } from '../day.js';
53
+ import { MAX_SHANGHAI_SAFE_MS } from '../../core/time.js';
54
+ /** 测试注入点收敛至共享 pace.ts(中-1):reports/knowledge/tickets 共用同一 sleep。 */
55
+ export { __setSleep } from './pace.js';
56
+ /** 分页页数上限(C 中-3,与 knowledge.pagedCursor 同口径):声明 total 已知时
57
+ * ceil(total/pageSize)+5 余量,未知时保守 1000 页——「total 恒大于已取行数」的
58
+ * 响应形态漂移在有限次调用后显式失败,绝不无限翻页。 */
59
+ const MAX_PAGES_FALLBACK = 1000;
60
+ const PAGE_SIZE = 1000;
61
+ /** 通用窗口请求体:startTime/endTime 恒为毫秒(传秒会静默降级)。 */
62
+ function timeBody(w) {
63
+ return { startTime: w.start, endTime: w.end };
64
+ }
65
+ /**
66
+ * 各报表的请求体构造(导出供测试对拍——http mock 只见 URL,body 事实在签名里)。
67
+ * 特殊规则:考勤恒含 startTime(防天粒度静默降级);robot_summary/transfer_human
68
+ * 忽略的参数(robotId/type)绝不透传。
69
+ * ⚠️ `stat_date` 的写法不在这里 —— 行内日期列按上海天对齐(见 dayIso),
70
+ * 请求体的时间参数仍是窗口毫秒(服务端按毫秒窗口过滤,天对齐只影响落库键)。
71
+ */
72
+ export function reportBody(taskId, w) {
73
+ switch (taskId) {
74
+ case 'reports.staff_attendance':
75
+ // 显式传 startTime(哪怕请求体其余为空)——省略它服务端不报错但静默切换天粒度
76
+ return { ...timeBody(w), pageSize: 1000 };
77
+ case 'reports.staff_workload':
78
+ case 'reports.staff_quality':
79
+ case 'reports.staff_satisfaction':
80
+ case 'reports.overview':
81
+ return { ...timeBody(w), pageSize: 1000 };
82
+ case 'reports.order_performance':
83
+ // 空结果集 page>1 会 14500(§5.2)——分页循环只在首页拉满且 total 更大时才进下一页
84
+ return { ...timeBody(w), pageSize: 1000 };
85
+ case 'reports.staff_salary_detail':
86
+ // 单 staffId 由 fetch 按 staff 表逐客服注入(见 salaryDetail 任务);此处仅时间
87
+ return { startTime: w.start, endTime: w.end };
88
+ case 'reports.robot_summary':
89
+ case 'reports.transfer_human':
90
+ // 只传时间对:robotId/type 被服务端忽略,透传只会误导调用方(契约诚实性)
91
+ return timeBody(w);
92
+ default:
93
+ throw new Error(`未知报表任务:${taskId}`);
94
+ }
95
+ }
96
+ /**
97
+ * 载荷 → 行数组(逐接口信封实测:C 族载荷是 message 解析物;robot_summary/
98
+ * transfer_human 是形状 A、载荷在 data)。识别已知包装键(result/orders),
99
+ * 其余对象形态视为「一行全局汇总」(overview 69 字段/summary 27 字段/transfer 恒 1 行)。
100
+ */
101
+ function payloadRows(taskId, payload) {
102
+ // C 中-5:载荷为 null/undefined 是**形状漂移**(信封层丢 data 键、或上游改了形态),
103
+ // 绝不能当合法空窗 —— 静默按空处理会把整段数据吞成 complete。与同文件 orders:null
104
+ // 的显式 kind 口径一致(那里是业务语义的显式失败,这里是形态语义的显式失败)。
105
+ if (payload === null || payload === undefined) {
106
+ throw new Error(`接口 ${endpointOf(taskId)} 未返回载荷(null/undefined)——响应形态漂移,拒绝按空窗处理`);
107
+ }
108
+ if (Array.isArray(payload))
109
+ return { rows: payload, sum: null };
110
+ const o = payload;
111
+ // statistic.performance 的全 null 形态(orders:null/sum:null/total:null,code:200)
112
+ // 是筛选失败(staffIdList 含租户不存在的 id),不是空窗口——fetch 层抛带 kind 的
113
+ // 形态错误,引擎记 sync_gaps(reason=filter_matched_no_staff,T5 裁定透传)。
114
+ if (o.orders === null) {
115
+ const e = new Error('statistic.performance 返回 orders:null——筛选条件未匹配到任何客服(非空窗口)');
116
+ e.kind = 'filter_matched_no_staff';
117
+ throw e;
118
+ }
119
+ // staffquality 的 sum 与分页无关、覆盖全集 → 与分页行一起返回,由 fetch 编为全局行
120
+ if (Array.isArray(o.result))
121
+ return { rows: o.result, sum: o.sum ?? null };
122
+ if (Array.isArray(o.orders))
123
+ return { rows: o.orders, sum: o.sum ?? null };
124
+ return { rows: [o], sum: null };
125
+ }
126
+ /** 空串主键拒绝(C 低-7):`''` 会写进 VARCHAR 主键列,且空串行还能反复覆盖同键。 */
127
+ const isEmptyKey = (v) => v === null || v === undefined || v === '';
128
+ /** per-staff 行投影:staff_id 键缺失 → null(丢弃——脏单行不致断流的取舍,见 task-7-report)。 */
129
+ function staffRow(w, r, nowIso) {
130
+ const sid = r.staffId ?? r.staffid ?? r.staff_id;
131
+ if (isEmptyKey(sid))
132
+ return null;
133
+ return { ...baseRow(w, r, nowIso), staff_id: String(sid) };
134
+ }
135
+ /** 分页 + per-staff 投影(staffworklod / staff_satisfaction)。 */
136
+ async function fetchPagedStaff(taskId, w, ctx) {
137
+ const nowIso = nowIsoOf(ctx);
138
+ const { rows } = await pagedRaw(taskId, w, ctx);
139
+ const mapped = rows
140
+ .map((r) => staffRow(w, r, nowIso))
141
+ .filter((r) => r !== null);
142
+ return { rows: mapped, apiCount: mapped.length };
143
+ }
144
+ /**
145
+ * stat_date + payload 的通用行投影(键列由各任务补齐)。
146
+ * ⚠️ 日期列按**上海自然日零点**写(A 中-2):窗口起点是毫秒级(水位+1ms、--since 的
147
+ * 任意时刻),直接写 `isoOf(w.start)` 会让同一业务日在 --full 与增量下得到两个不同的
148
+ * 键值,两行并存。天对齐后同一业务日恒为同一个键,upsert/删除范围都能覆盖它。
149
+ * dayMs(修复批 4,可选):写 stat_date 所依据的**毫秒时刻**,缺省取窗口起点。
150
+ * 仅 staff_attendance 传入(响应自带逐行可信时间戳 hour_ts —— 该任务的 31 天窗口里
151
+ * 行分布在多个自然日,只用窗口起点会把 31 天的考勤全标成第 1 天)。
152
+ */
153
+ function baseRow(w, src, nowIso, dayMs) {
154
+ return { stat_date: shanghaiDayIso(dayMs ?? w.start), payload: JSON.stringify(src), synchronized_at: nowIso };
155
+ }
156
+ /**
157
+ * 分页拉取原始行(result/orders 包装族:staffworklod/satisfaction/staffAttendance/
158
+ * performance)。page 从 1 起、pageSize=1000,total 收敛翻页(total 缺省视为单页)。
159
+ * 终检(C 中-3):循环结束必须满足「已取行数 >= 声明 total」——上游声明 100 却返回 0 行
160
+ * 的短读是最危险的静默失败方向(会被当合法空窗,配对核对也看不出),此处显式失败。
161
+ * 页数上限同 knowledge.pagedCursor:非空页但 total 恒大于累计、或 total 缺失但页页拉满
162
+ * 的漂移,在有限次调用后终止。
163
+ */
164
+ async function pagedRaw(taskId, w, ctx) {
165
+ const out = [];
166
+ let sum = null;
167
+ let declared = null;
168
+ let page = 1;
169
+ for (;;) {
170
+ const maxPages = declared !== null ? Math.ceil(declared / PAGE_SIZE) + 5 : MAX_PAGES_FALLBACK;
171
+ if (page > maxPages) {
172
+ throw new Error(`接口 ${endpointOf(taskId)} 翻页超限(${page - 1} 页 > 上限 ${maxPages},` +
173
+ `声明 total=${String(declared)},已取 ${out.length} 行):total 与已取行数不收敛,拒绝落库`);
174
+ }
175
+ const body = { ...reportBody(taskId, w), page };
176
+ // B 中-6:callPaced 的键就是注册表 endpoint id(闸门按路径拦、冷却按路径共享)。
177
+ const res = await callPaced(endpointOf(taskId), body, ctx);
178
+ const { rows, sum: s } = payloadRows(taskId, res.payload);
179
+ if (s)
180
+ sum = s;
181
+ out.push(...rows);
182
+ const total = res.payload?.total;
183
+ if (typeof total !== 'number') {
184
+ // total 缺省视为单页:拉满一页仍不声明 total 时不再翻(口径与 tickets.search 一致)
185
+ declared = null;
186
+ break;
187
+ }
188
+ if (declared === null)
189
+ declared = total;
190
+ else if (total !== declared) {
191
+ throw new Error(`接口 ${endpointOf(taskId)} 各页声明 total 漂移(${declared} → ${total}):` +
192
+ '遍历期间上游数据变更,拒绝落库(重跑即可)');
193
+ }
194
+ // total 与已取行数收敛即停;短读(rows.length === 0 但 total 未达)留给终检判定
195
+ if (out.length >= total || rows.length === 0)
196
+ break;
197
+ page++;
198
+ }
199
+ if (declared !== null && out.length < declared) {
200
+ throw new Error(`接口 ${endpointOf(taskId)} 分页短读:声明 total=${declared},实取 ${out.length} 行` +
201
+ '(响应形态漂移/遍历期间上游变更),拒绝落库——重跑即可');
202
+ }
203
+ return { rows: out, sum };
204
+ }
205
+ /** 任务 id → 注册表 endpoint id。 */
206
+ function endpointOf(taskId) {
207
+ switch (taskId) {
208
+ case 'reports.overview': return 'statistic.overview';
209
+ case 'reports.staff_workload': return 'statistic.staffworklod';
210
+ case 'reports.staff_quality': return 'statistic.staffquality';
211
+ case 'reports.staff_satisfaction': return 'statistic.satisfaction.report';
212
+ case 'reports.staff_attendance': return 'statistic.staffAttendance';
213
+ case 'reports.order_performance': return 'statistic.performance';
214
+ case 'reports.staff_salary_detail': return 'statistic.salaryDetail';
215
+ case 'reports.robot_summary': return 'robot.statistic.summary';
216
+ case 'reports.transfer_human': return 'ai.statistic.transferHuman';
217
+ default: throw new Error(`未知报表任务:${taskId}`);
218
+ }
219
+ }
220
+ /** 普通报表 fetch(result/全局行形态):stat_date=窗口起点按上海天对齐;staffId 键取不到时用 'sum' 哨兵。 */
221
+ function fetchSimple(taskId, perStaff) {
222
+ return async (w, ctx) => {
223
+ const nowIso = nowIsoOf(ctx);
224
+ // B 高-1:走 callPaced(本地令牌桶拒绝被吸收为等待重试;远端限频写持久化冷却行)。
225
+ // 裸 call 会让两种限频都直接冒泡成 fetch_failed gap,而空窗假空重试必然二次调用
226
+ // 同一路径——这是最容易撞上本地限频的一条路径。
227
+ const res = await callPaced(endpointOf(taskId), reportBody(taskId, w), ctx);
228
+ const { rows, sum } = payloadRows(taskId, res.payload);
229
+ const mapped = [];
230
+ for (const r of rows) {
231
+ // perStaff 表(staff_workload/quality/satisfaction)键是 (stat_date, staff_id);
232
+ // 全局汇总表(overview/robot_summary/transfer_human)键只有 stat_date——
233
+ // 响应没有 staffId,行形状按目标表列集投影。
234
+ const base = baseRow(w, r, nowIso);
235
+ if (perStaff) {
236
+ const sid = r.staffId ?? r.staffid ?? r.staff_id;
237
+ if (isEmptyKey(sid))
238
+ continue; // 键缺失/空串行:计入 fetched 不写库
239
+ mapped.push({ ...base, staff_id: String(sid) });
240
+ }
241
+ else {
242
+ mapped.push(base);
243
+ }
244
+ }
245
+ // staffquality 全局 sum 行(覆盖全集、与分页无关):sum 本就没有 staff_id,
246
+ // 落 perStaff 表时用上游无语义的哨兵 'sum'(约定位置,见 task-7-report)。
247
+ if (sum && perStaff)
248
+ mapped.push({ ...baseRow(w, sum, nowIso), staff_id: 'sum' });
249
+ return { rows: mapped, apiCount: mapped.length };
250
+ };
251
+ }
252
+ /** staff 表客服 id 列表(salaryDetail 的驱动序:每客服一次调用)。 */
253
+ async function staffIds(store) {
254
+ const r = await store.query('SELECT id FROM staff ORDER BY id');
255
+ return r.rows
256
+ .map((x) => (isEmptyKey(x.id) ? '' : String(x.id)))
257
+ .filter((id) => id !== '');
258
+ }
259
+ /** 报表任务的通用写策略(A 中-2:删除边界与行内日期列同口径 = 上海天对齐)。 */
260
+ const RANGE_INSERT = { kind: 'deleteRangeInsert', rangeColumns: ['stat_date'], rangeAlign: 'shanghaiDay' };
261
+ export const REPORT_TASKS = [
262
+ {
263
+ id: 'reports.overview', table: 'daily_overview', kind: 'windowed',
264
+ // 窗口聚合接口(一行全局汇总,响应 date 无语义)→ 按天切片:多天窗口会把
265
+ // N 天汇总标成第 1 天、水位每月才推进一次(修复批 4,CodeRabbit #1)
266
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
267
+ watermark: { field: 'stat_date', initial: null },
268
+ primaryKey: ['stat_date'], reportDayRotation: true,
269
+ endpoint: 'statistic.overview',
270
+ write: RANGE_INSERT,
271
+ fetch: fetchSimple('reports.overview', false),
272
+ },
273
+ {
274
+ id: 'reports.staff_workload', table: 'staff_workload', kind: 'windowed',
275
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
276
+ watermark: { field: 'stat_date', initial: null },
277
+ primaryKey: ['stat_date', 'staff_id'], reportDayRotation: true,
278
+ endpoint: 'statistic.staffworklod',
279
+ write: RANGE_INSERT,
280
+ // 响应 date 恒 0 → stat_date 只能用窗口起点(调用方填写)
281
+ fetch: (w, ctx) => fetchPagedStaff('reports.staff_workload', w, ctx),
282
+ },
283
+ {
284
+ id: 'reports.staff_quality', table: 'staff_quality', kind: 'windowed',
285
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
286
+ watermark: { field: 'stat_date', initial: null },
287
+ primaryKey: ['stat_date', 'staff_id'], reportDayRotation: true,
288
+ endpoint: 'statistic.staffquality',
289
+ write: RANGE_INSERT,
290
+ fetch: fetchSimple('reports.staff_quality', true),
291
+ },
292
+ {
293
+ id: 'reports.staff_satisfaction', table: 'staff_satisfaction', kind: 'windowed',
294
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
295
+ watermark: { field: 'stat_date', initial: null },
296
+ primaryKey: ['stat_date', 'staff_id'], reportDayRotation: true,
297
+ endpoint: 'statistic.satisfaction.report',
298
+ write: RANGE_INSERT,
299
+ fetch: (w, ctx) => fetchPagedStaff('reports.staff_satisfaction', w, ctx),
300
+ },
301
+ {
302
+ id: 'reports.staff_attendance', table: 'staff_attendance', kind: 'windowed',
303
+ // 逐行可信时间戳(`date` 按小时对齐,落 hour_ts)→ 31 天窗口可行(≈1.7 万行/窗);
304
+ // stat_date 由该行的 hour_ts 推导(不是窗口起点)——它跟随该行自己的业务日
305
+ maxWindowDays: 31, overlapDays: 0,
306
+ watermark: { field: 'stat_date', initial: null },
307
+ // hour_ts 是响应内唯一可信日期字段(小时对齐时间戳)
308
+ primaryKey: ['staff_id', 'hour_ts'], reportDayRotation: true,
309
+ endpoint: 'statistic.staffAttendance',
310
+ // G 高-1:endTime 不得晚于今天 0:00(14501 endTime is invalid),
311
+ // 且今天 0:00 这条边界不稳定 → 引擎把窗口 end 钳到昨天 0:00(留整日余量)。
312
+ windowEndClamp: 'shanghaiYesterday',
313
+ write: RANGE_INSERT,
314
+ // ⚠️ 请求体恒含 startTime(reportBody 已保证)——省略会静默降级为天粒度、少抓 ~10 倍。
315
+ // 分页 total 收敛拉满(单页 pageSize=1000,31d 实测 17765 行 → 两页),再抽 hour_ts。
316
+ fetch: async (w, ctx) => {
317
+ const nowIso = nowIsoOf(ctx);
318
+ const { rows } = await pagedRaw('reports.staff_attendance', w, ctx);
319
+ const mapped = [];
320
+ for (const r of rows) {
321
+ const sid = r.staffId ?? r.staffid;
322
+ const ts = r.date; // 该小时按小时对齐的时间戳
323
+ // C 中-4:脏时间戳逐行丢弃(与其他任务的脏单行口径一致),绝不因一行
324
+ // 非数字/空串的 ts 抛 RangeError 断掉整窗。秒级 ts(10 位)静默落 1970 ——
325
+ // 形态不符即丢弃(小时对齐的毫秒戳约 1.7e12,秒级差 1000 倍,判据取 > 1e11)。
326
+ //
327
+ // ⚠️ gap 2 的写路径同款收口:只有下界不够 —— 微秒误写(`1792467000000000000`)
328
+ // 远大于 1e11,能过旧判据,随后 `new Date(n).toISOString()`(本行 hour_ts)与
329
+ // `shanghaiDayIso(n)`(baseRow 的 stat_date)都抛 RangeError,**整窗 fetch 失败**
330
+ //(与读侧「一条脏值炸整条命令」同一失败模式)。上界取 `MAX_SHANGHAI_SAFE_MS`
331
+ // 而不是 `MAX_DATE_MS`:两者都要「能回显成 +08:00 ISO」,差 8h 就会在
332
+ // `shanghaiDayIso` 的偏移后一段重新抛。
333
+ const n = Number(ts);
334
+ if (isEmptyKey(sid) || !Number.isFinite(n) || n <= 1e11 || n > MAX_SHANGHAI_SAFE_MS)
335
+ continue;
336
+ // 修复批 4:stat_date 按**本行的 hour_ts** 推导上海日(不再用窗口起点)——
337
+ // 31 天窗口里行跨多个自然日,用窗口起点会把它们全标成窗口首日。
338
+ // 删除范围仍是 [dayOf(w.start), dayOf(w.end)](writeRows 的天对齐边界),
339
+ // 覆盖窗内所有天 → 与本行的 stat_date 一致。
340
+ mapped.push({ ...baseRow(w, r, nowIso, n), staff_id: String(sid), hour_ts: new Date(n).toISOString() });
341
+ }
342
+ return { rows: mapped, apiCount: mapped.length };
343
+ },
344
+ },
345
+ {
346
+ id: 'reports.order_performance', table: 'order_performance', kind: 'windowed',
347
+ // 365 是接口的**跨度上限**,不是窗口大小:绩效行没有逐单时间字段(响应 date 无语义),
348
+ // 多天窗口同样会把 N 天聚合标成首日 → 与其余聚合报表统一按天切片(修复批 4 扩展①)。
349
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
350
+ watermark: { field: 'stat_date', initial: null },
351
+ primaryKey: ['order_id'], reportDayRotation: true,
352
+ endpoint: 'statistic.performance',
353
+ // G 高-1:与 staff_attendance 同族的 endTime 对齐检查(14501 endTime is invalid)
354
+ windowEndClamp: 'shanghaiYesterday',
355
+ write: RANGE_INSERT,
356
+ // orders:null = 筛选失败、不是空窗口(staffIdList 含租户不存在的 id 时 code:200
357
+ // 全 null)→ 显式 gapHint,引擎落 sync_gaps(T5 裁定:透传原始 reason)。
358
+ // 行映射补主键列 order_id(响应键 orderId);缺 order_id 的订单行丢弃——
359
+ // 计入 fetched 不写库(脏单行不致断流,与 per-staff 表同一取舍);
360
+ // sum 全局行按 controller 裁定落同表哨兵 order_id='sum'(与 staff_quality 一致)。
361
+ fetch: async (w, ctx) => {
362
+ try {
363
+ const nowIso = nowIsoOf(ctx);
364
+ const { rows, sum } = await pagedRaw('reports.order_performance', w, ctx);
365
+ const mapped = [];
366
+ for (const r of rows) {
367
+ const oid = r.orderId ?? r.order_id;
368
+ if (isEmptyKey(oid))
369
+ continue;
370
+ mapped.push({ ...baseRow(w, r, nowIso), order_id: String(oid) });
371
+ }
372
+ if (sum)
373
+ mapped.push({ ...baseRow(w, sum, nowIso), order_id: 'sum' });
374
+ return { rows: mapped, apiCount: mapped.length };
375
+ }
376
+ catch (e) {
377
+ if (e.kind === 'filter_matched_no_staff') {
378
+ return { rows: [], apiCount: 0,
379
+ gapHint: { reason: 'filter_matched_no_staff', detail: e.message } };
380
+ }
381
+ throw e;
382
+ }
383
+ },
384
+ },
385
+ {
386
+ id: 'reports.staff_salary_detail', table: 'staff_salary_detail', kind: 'windowed',
387
+ // 只覆盖窗口起始日 → 窗口切 1 天(每窗 = 一天的「客服 × 起始日」驱动)
388
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
389
+ watermark: { field: 'stat_date', initial: null },
390
+ primaryKey: ['staff_id', 'work_date'], reportDayRotation: true,
391
+ endpoint: 'statistic.salaryDetail',
392
+ // G 高-1:salaryDetail 跟随 startTime 的窗口起始日 —— 只覆盖起始日,不存在
393
+ // 「endTime 越界」的报错形态,故不声明 windowEndClamp(只有 attendance/performance 需要)。
394
+ write: RANGE_INSERT,
395
+ // ⚠️ 必须传单个 staffId(省略 14004、传数组不识别)→ 按 staff 表逐客服驱动;
396
+ // staff 表为空是任务序错误(先跑 dim.staff),显式失败而非静默空跑。
397
+ fetch: async (w, ctx) => {
398
+ void w;
399
+ const ids = await staffIds(ctx.store);
400
+ if (ids.length === 0) {
401
+ throw new Error('staff 表为空:staff_salary_detail 按客服驱动,请先同步 dim.staff 任务');
402
+ }
403
+ const nowIso = nowIsoOf(ctx);
404
+ const day = shanghaiDayIso(w.start);
405
+ const out = [];
406
+ for (const sid of ids) {
407
+ const body = { ...reportBody('reports.staff_salary_detail', w), staffId: Number(sid) };
408
+ const res = await callPaced(endpointOf('reports.staff_salary_detail'), body, ctx);
409
+ const { rows, sum } = payloadRows('reports.staff_salary_detail', res.payload);
410
+ for (const r of rows) {
411
+ out.push({ ...baseRow(w, r, nowIso), staff_id: sid, work_date: day });
412
+ }
413
+ if (sum)
414
+ out.push({ ...baseRow(w, sum, nowIso), staff_id: sid, work_date: day });
415
+ }
416
+ return { rows: out, apiCount: out.length };
417
+ },
418
+ },
419
+ {
420
+ id: 'reports.robot_summary', table: 'robot_summary', kind: 'windowed',
421
+ // 窗口聚合(一行全局汇总、响应 date 无语义)→ 按天切片(修复批 4 #1)
422
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
423
+ watermark: { field: 'stat_date', initial: null },
424
+ primaryKey: ['stat_date'], reportDayRotation: true,
425
+ endpoint: 'robot.statistic.summary',
426
+ write: RANGE_INSERT,
427
+ // 形状 A;robotId 被服务端忽略 → body 不含(reportBody 保证)
428
+ fetch: fetchSimple('reports.robot_summary', false),
429
+ },
430
+ {
431
+ id: 'reports.transfer_human', table: 'transfer_human', kind: 'windowed',
432
+ // G 中-2:实测**恰好 365 天**被拒(14500 起止时间不能超过365天),且 364 天也会
433
+ // 报 Internal error(边界不稳定)→ 360 天曾是接口跨度上限。但响应恒 1 行聚合值、
434
+ // 无逐行时间字段 → 窗口必须按天切片(修复批 4 #1,与其余聚合报表同口径);
435
+ // 按天窗口天然远低于 360 天,接口跨度上限不再是约束。
436
+ maxWindowDays: 1, overlapDays: 0, windowAlign: 'shanghaiDay',
437
+ watermark: { field: 'stat_date', initial: null },
438
+ primaryKey: ['stat_date'], reportDayRotation: true,
439
+ endpoint: 'ai.statistic.transferHuman',
440
+ write: RANGE_INSERT,
441
+ // 形状 A;type/robotId 被服务端忽略 → body 不含(reportBody 保证)
442
+ fetch: fetchSimple('reports.transfer_human', false),
443
+ },
444
+ ];
445
+ /** 按 id 取报表任务(T12 汇总与测试的取用形态)。 */
446
+ export function taskById(id) {
447
+ return REPORT_TASKS.find((t) => t.id === id);
448
+ }
@@ -0,0 +1,188 @@
1
+ // src/sync/tasks/sessions.ts
2
+ // D-T10:会话导出任务声明(spec §5.3)—— 唯一走四步流水线的 windowed 任务。
3
+ // 实测事实(设计稿 §7.5):
4
+ // ① 窗口 ≤6 天(143.5h 通过 / 144.0h 报 14004)→ maxWindowDays=6;
5
+ // ② 相邻窗口必须重叠 1 天(跨窗口长会话会漏,实测 5 会话/16 消息)→ overlapDays=1,
6
+ // 重叠行由按 session.id 的 upsert 幂等吸收(**去重按 session.id,绝不能按导出任务 key**);
7
+ // ③ **导出按 endTime 过滤**(判定式 window.start <= endTime <= window.end)→ 水位字段 endTime;
8
+ // ④ enrich 派生 session_type:staffId **数字判别**(< -1 → robot / == -1 → internal /
9
+ // > 0 → human;不用 sType),staffId 落库是 VARCHAR、比较时转 number(BIGINT 精度红线);
10
+ // ⑤ categoryDetail 归一化:导出是 " / "(带空格),/one 是 "/"(无空格)——落库前归一,
11
+ // 为 E 的 JOIN 铺路;哨兵值「未分类」「无效会话」是中文单段值,归一化不触及。
12
+ // ⑥ 尾部标记行(fixture)是**导出自己的窗口声明**(C-8):完整导出恰好带一行,
13
+ // 与请求窗口核对 —— 不覆盖请求 = 形态漂移(失败 + 水位冻结);缺失 = 记 gap;
14
+ // 宽于请求 = 记 gap(见 fetchSessions 与 assertFixtureGranularity)。
15
+ // 列投影按 TABLES sessions 列集(payload 收敛 + 键列/时间列/PII 敏感列提升)。
16
+ import { runExportPipeline, parseExportFixture } from './pipeline.js';
17
+ import { nowIsoOf } from './pace.js';
18
+ const isoOf = (ms) => new Date(ms).toISOString();
19
+ const strOrNull = (v) => v === null || v === undefined ? null : typeof v === 'string' ? v : JSON.stringify(v);
20
+ /** 空串主键/键列拒绝(C 低-7):`''` 是合法的 VARCHAR 值,会写出一行能被反复覆盖的同键行。 */
21
+ const isEmptyKey = (v) => v === null || v === undefined || v === '';
22
+ /** categoryDetail 归一化:"a / b / c / d" → "a/b/c/d"(导出 " / " 带空格 → /one 无空格)。 */
23
+ export function normalizeCategoryDetail(v) {
24
+ if (v === null || v === undefined || v === '')
25
+ return null;
26
+ const s = String(v);
27
+ return s.split(' / ').join('/');
28
+ }
29
+ /**
30
+ * session_type 判别(设计稿 §7.5:staffId 是唯一精确字段):
31
+ * staffId 数字 < -1 → robot;== -1 → internal;> 0 → human。
32
+ * staffId 落库为 VARCHAR —— 判别必须基于数字比较(字符串比较会判错负数)。
33
+ * ⚠️ C 中-6:`staffId === 0` **不得**静默落成 'human' —— 0 不是任何已知的判别分支
34
+ *(实测样本只有 < -1 / == -1 / > 0 三类,0 从未出现),静默归到 human 会伪造出一个
35
+ * 「人工接待」的事实。按「未知形态」显式落 null,让该行在按 session_type 过滤时可见地缺失。
36
+ */
37
+ export function deriveSessionType(staffId) {
38
+ if (isEmptyKey(staffId))
39
+ return null;
40
+ const n = Number(staffId);
41
+ if (!Number.isFinite(n))
42
+ return null;
43
+ if (n < -1)
44
+ return 'robot';
45
+ if (n === -1)
46
+ return 'internal';
47
+ if (n === 0)
48
+ return null; // 未知形态:不猜(C 中-6)
49
+ return 'human';
50
+ }
51
+ /** 按列集投影:行补 session_id/session_type/categoryDetail/PII 列;缺 id 行丢弃(不计入 fetched)。
52
+ * ⚠️ 本函数是纯投影(红线 1:同输入同输出)—— synchronized_at 从输入行透传
53
+ *(fetch 在进 enrich 前统一盖章,enrich 直测两调用相等);输入无戳则为 null(列可空)。 */
54
+ function sessionRow(src) {
55
+ const id = src.id ?? src.session_id;
56
+ // 键缺失/空串行:丢弃且不计入 fetched(与 apiCount 口径一致;C 低-7)
57
+ if (isEmptyKey(id))
58
+ return null;
59
+ return {
60
+ session_id: String(id),
61
+ payload: JSON.stringify(src),
62
+ staffId: strOrNull(src.staffId),
63
+ startTime: strOrNull(src.startTime),
64
+ endTime: strOrNull(src.endTime),
65
+ session_type: deriveSessionType(src.staffId),
66
+ categoryDetail: normalizeCategoryDetail(src.categoryDetail),
67
+ userPhone: strOrNull(src.userPhone),
68
+ userName: strOrNull(src.userName),
69
+ userEmail: strOrNull(src.userEmail),
70
+ userAddress: strOrNull(src.userAddress),
71
+ fromIp: strOrNull(src.fromIp),
72
+ userIpCity: strOrNull(src.userIpCity),
73
+ userCrmInfo: strOrNull(src.userCrmInfo),
74
+ synchronized_at: src.synchronized_at ?? null,
75
+ };
76
+ }
77
+ async function fetchSessions(w, ctx) {
78
+ const sctx = ctx;
79
+ if (!sctx.fetchZip) {
80
+ throw new Error('sessions.export 需要 fetchZip 注入(下载走 ZIP 二进制通道,与 JSON 信封层不同构)——生产接线归 sync run 编排层');
81
+ }
82
+ const nowIso = nowIsoOf(ctx);
83
+ const { sessions, fixture } = await runExportPipeline(w, {
84
+ credentials: ctx.credentials,
85
+ fetchZip: sctx.fetchZip,
86
+ pollIntervalMs: sctx.pollIntervalMs,
87
+ maxPolls: sctx.maxPolls,
88
+ // B 高-1:gate/clock 传进流水线 —— create/check 的远端限频要落持久化冷却行。
89
+ gate: ctx.gate,
90
+ clock: ctx.clock,
91
+ });
92
+ // synchronized_at 在 fetch 侧按窗统一盖章(单值、确定性于本窗)——enrich 是纯投影
93
+ //(红线 1:同输入行永远同输出),只透传该戳;原始行直出(session.id 键、未投影)。
94
+ const stamped = sessions.map((r) => ({ ...r, synchronized_at: nowIso }));
95
+ const base = { rows: stamped, apiCount: sessions.length };
96
+ // —— C-8:尾部标记行(fixture)= 导出自己的窗口声明,与请求窗口核对 ——
97
+ // 实测形态(private/raw/session.txt,4687 行样本):**完整导出必然带这一行**,恰好一行、
98
+ // 紧随全部 JSON 行之后,声明一个 24h 窗口。因此「带了它」是正常形态,不是异常;
99
+ // 真正可疑的是它的**内容**(声明的窗口与请求不符)与它的**缺失**(流没有声明覆盖到哪)。
100
+ // ⚠️ fixture 非空 ⇒ 必然可解析(parseJsonl 与这里共用 parseExportFixture 判形态,
101
+ // 不会各写一套正则)——所以没有「fixture 解析不出」的分支,那是不可达代码。
102
+ const declared = fixture === undefined ? null : parseExportFixture(fixture);
103
+ if (declared !== null && (declared.start > w.start || declared.end < w.end)) {
104
+ // 声明的窗口不覆盖本窗请求 → 本窗数据可疑(服务端实测会按(企业,窗口)复用已计算的
105
+ // 导出结果,同参数重复创建返回不同 key 相同数据)→ 宁可失败:fetch 抛错由引擎包装成
106
+ // 中文 gap(failDetail)+ 水位冻结(contiguousBroken),绝不把来路不明的行写进库。
107
+ throw new Error(`会话导出格式漂移(${fixture}):导出声明的窗口 ` +
108
+ `[${isoOf(declared.start)}, ${isoOf(declared.end)}] 未覆盖请求窗口 ` +
109
+ `[${isoOf(w.start)}, ${isoOf(w.end)}] —— 本窗数据可疑,拒绝落库`);
110
+ }
111
+ if (fixture === undefined) {
112
+ // 完整导出应带尾部标记(见上);缺失 = 导出流没有声明它覆盖到哪 —— 空窗可能是真空、
113
+ // 也可能是流被截断在行边界(逐行 JSON 解析对截断在行中间的情况已显式失败)。
114
+ // 不判失败(历史样本可能无),但绝不静默:记一条 gap,让两类空窗可区分。
115
+ return {
116
+ ...base,
117
+ gapHint: {
118
+ reason: 'export_fixture_unreported',
119
+ detail: `导出流未上报尾部标记行(完整导出末尾应有一行 startTime=…,endTime=… 声明导出窗口):` +
120
+ `本窗 ${sessions.length} 行数据的窗口覆盖无从核对 —— 空窗可能确实是空,也可能是导出流被截断在行边界。` +
121
+ `请求窗口 [${isoOf(w.start)}, ${isoOf(w.end)}]`,
122
+ },
123
+ };
124
+ }
125
+ if (declared !== null && (declared.start < w.start || declared.end > w.end)) {
126
+ // 覆盖成立但宽于请求:多出来的行由 session_id 幂等 upsert 吸收(与 overlapDays 同机制),
127
+ // 数据不受损 —— 但「服务端改了窗口」这件事必须可见,记 gap 并带上标记行原文。
128
+ return {
129
+ ...base,
130
+ gapHint: {
131
+ reason: 'export_window_mismatch',
132
+ detail: `导出声明的窗口 [${isoOf(declared.start)}, ${isoOf(declared.end)}] 宽于请求窗口 ` +
133
+ `[${isoOf(w.start)}, ${isoOf(w.end)}](重叠行由 session_id 幂等吸收)`,
134
+ fixture,
135
+ },
136
+ };
137
+ }
138
+ return base;
139
+ }
140
+ /**
141
+ * fixture 检测面的粒度断言(C-8 收尾批,模块级调用 = import 侧效应):
142
+ * 尾部标记行的形态、以及「声明窗口 ↔ 请求窗口」核对的可信度,都建立在**同一份实测**上
143
+ *(private/raw/session.txt:4687 行 + 恰好一行尾标记,声明 24h 窗口;窗口上限 143.5h 通过 /
144
+ * 144.0h 报 14004)。`maxWindowDays ≥ 7` 意味着导出语义已越过那份实测(服务端要么接受更宽
145
+ * 的窗口、要么把一次导出拆成多块 —— 后者会让「一行尾标记」的粒度假设失效:多块 = 多个标记,
146
+ * 而本检测只带出一行)。此时必须在**重新实测**尾标记与窗口声明后修订核对逻辑,而不是
147
+ * 沿用旧假设继续放行 —— 所以这里直接失败,把「假设已过期」摆在载入期。
148
+ */
149
+ export function assertFixtureGranularity(task) {
150
+ const days = task.maxWindowDays;
151
+ if (days !== undefined && days <= 6)
152
+ return;
153
+ throw new Error(`sessions.export 的 fixture 检测面已失效:maxWindowDays=${String(days)}(要求 ≤6)—— ` +
154
+ '尾标记形态与窗口核对建立在「窗口 ≤6 天」的实测样本上(143.5h 通过 / 144.0h 报 14004;' +
155
+ '样本 4687 行 + 恰好一行尾标记,声明 24h 窗口)。窗口上限放宽到 ≥7 天说明导出语义已变,' +
156
+ '必须在重新实测尾标记粒度与窗口声明后修订核对逻辑');
157
+ }
158
+ /**
159
+ * enrich:投影 + 确定性派生(红线 1 推论:同输入行永远同输出)。
160
+ * 派生 session_type(staffId 数字判别)+ categoryDetail 归一化;缺 id 行返回 null
161
+ *(丢弃且不计入 fetched——与 apiCount 口径一致)。synchronized_at 从输入行透传
162
+ *(fetch 已统一盖章),无戳直测时为 null —— 本函数不含任何时钟读取。
163
+ */
164
+ function enrichSession(src) {
165
+ return sessionRow(src);
166
+ }
167
+ export const SESSIONS_TASKS = [
168
+ {
169
+ id: 'sessions.export', table: 'sessions', kind: 'windowed',
170
+ maxWindowDays: 6, overlapDays: 1,
171
+ // 水位 endTime:导出按 endTime 过滤(按 startTime 会漏——实测 14/17 行越界)
172
+ watermark: { field: 'endTime', initial: null },
173
+ primaryKey: ['session_id'],
174
+ // 闸门键 = 主驱动路径(create 是限频的那一个:10 秒 6 次);check 显式登记为无限频。
175
+ endpoint: 'export.session',
176
+ write: { kind: 'upsertRows' },
177
+ fetch: fetchSessions,
178
+ enrich: enrichSession,
179
+ },
180
+ ];
181
+ // 模块级断言(import 侧效应):声明的窗口上限与 fixture 检测面共用同一份实测 ——
182
+ // 上限被改到 ≥7 天时**载入本模块即失败**,不靠注释、不靠自觉(见 assertFixtureGranularity)。
183
+ for (const t of SESSIONS_TASKS)
184
+ assertFixtureGranularity(t);
185
+ /** 按 id 取会话任务(T12 汇总与测试的取用形态)。 */
186
+ export function taskById(id) {
187
+ return SESSIONS_TASKS.find((t) => t.id === id);
188
+ }