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,95 @@
1
+ // D-T4:持久化限频闸门 —— 命中限频把「下次可调用时间」写进库,
2
+ // 跨进程快速失败(spec §6.2)。进程内令牌桶仍是 core/ratelimit.ts 的 TokenBucket;
3
+ // 本闸门是其持久化的兜底层:宁可多拦(本地冷却),绝不超发。
4
+ // 写函数只接受 WriteTx(引擎放进同一 transaction 闭包);读函数只接受 Store。
5
+ // SQL 全部为代码内常量(同 query 红线)——本文件常量 SELECT 调用点共 1 处,
6
+ // 不在 duckdb.ts 的 9 处基线计数内。
7
+ import { RATE_LIMITS } from '../core/ratelimit.js';
8
+ /** 冷却行在 sync_state 里的 dataset 前缀(T3 裁定:主键 dataset 单列,靠前缀区分类别)。 */
9
+ const RATELIMIT_PREFIX = '__ratelimit__:';
10
+ /**
11
+ * 单次冷却等待的上限(毫秒,B 低-2):冷却行是持久化数据,坏数据(时钟错乱/手改库)
12
+ * 可能算出天文数字的 retryAfter —— 等待必须封顶,剩下的靠「有界重试预算」终止,
13
+ * 绝不因为一行坏数据把同步挂死(宁可多等几轮,也不无限等)。
14
+ */
15
+ export const MAX_GATE_WAIT_MS = 300_000;
16
+ /** 冷却等待的封顶(供引擎与任务层共用,避免两处各写一个上限)。 */
17
+ export function clampGateWait(ms) {
18
+ return Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_GATE_WAIT_MS) : 0;
19
+ }
20
+ /** 读某 endpoint 的冷却截止(毫秒时间戳);无记录返回 0(随时可调用)。 */
21
+ export async function readCooldown(store, endpointId) {
22
+ // 常量 SQL 调用点 1/1
23
+ const r = await store.query('SELECT next_allowed_at FROM sync_state WHERE dataset = ?', [RATELIMIT_PREFIX + endpointId]);
24
+ const raw = r.rows[0]?.next_allowed_at;
25
+ if (typeof raw !== 'string' || raw === '')
26
+ return 0;
27
+ const ms = Date.parse(raw);
28
+ return Number.isNaN(ms) ? 0 : ms;
29
+ }
30
+ /** 写/覆盖某 endpoint 的冷却截止(毫秒时间戳)。 */
31
+ export async function writeCooldown(tx, endpointId, untilMs, opts = {}) {
32
+ const untilIso = new Date(untilMs).toISOString();
33
+ // last_rate_limited_at 同样取注入时钟(默认 Date.now)—— 纯 clock 注入下可确定性断言。
34
+ const limitedAtIso = new Date(opts.now?.() ?? Date.now()).toISOString();
35
+ // upsert 契约:每行必须完整列集(sync_state 共 11 列 —— T4 的限频两列 + G2 的区间两列)。
36
+ // ⚠️ 修复批 2 的最小跨所有权改动:v9 迁移给 sync_state 加了 resolved_range_start/end,
37
+ // 本行的完整列集随之补 null(冷却行没有覆盖区间)。
38
+ await tx.upsert('sync_state', [{
39
+ dataset: RATELIMIT_PREFIX + endpointId,
40
+ watermark: untilIso,
41
+ range_status: null,
42
+ last_error: null,
43
+ locked_by: null,
44
+ locked_at: null,
45
+ last_synced_at: null,
46
+ next_allowed_at: untilIso,
47
+ last_rate_limited_at: limitedAtIso,
48
+ resolved_range_start: null,
49
+ resolved_range_end: null,
50
+ }]);
51
+ }
52
+ /**
53
+ * 持久化限频闸门。
54
+ * - `acquire`:读库冷却截止,未到点抛 rate_limit_local(retryAfter 精确到毫秒);
55
+ * 到点或无限频接口放行。
56
+ * - `penalize`:命中远端限频后写冷却。**显式登记为无限频**(RATE_LIMITS 里有键
57
+ * 且值为 null)的 endpoint 不写不拦 —— 与审计语义一致(null = 实测没有);
58
+ * 未登记的 endpoint 照写不误 —— 闸门宁可多拦,远端真实返回 429/限频就是证据。
59
+ *
60
+ * ⚠️ **键统一为 endpoint id**(B 中-6):`penalize` 与 `acquire` 必须传同一把键 ——
61
+ * 远端限频的证据是「这个路径被限了」(限频按路径独立,设计稿 §7.4 实测),
62
+ * 而 acquire 也按路径查冷却。此前两处传的是 task id(`reports.overview`),
63
+ * 而 `RATE_LIMITS` 的键是 endpoint id(`statistic.overview`)——null 豁免恒不触发,
64
+ * 且同路径多任务(`tickets.search` 与 `ticket.logs` 同走 `ticket.search`)各自持一份
65
+ * 冷却,同一路径上交替调用照样超发。键不一致时闸门拦不住它本该拦的调用。
66
+ */
67
+ export class RateGate {
68
+ store;
69
+ clock;
70
+ constructor(store, clock = () => Date.now()) {
71
+ this.store = store;
72
+ this.clock = clock;
73
+ }
74
+ /** 到点放行;未到点抛 { kind: 'rate_limit_local', retryAfter } 形态错误。 */
75
+ async acquire(endpointId) {
76
+ const until = await readCooldown(this.store, endpointId);
77
+ const now = this.clock();
78
+ if (until > now) {
79
+ const e = new Error(`本地限频冷却中:${endpointId} 于 ${new Date(until).toISOString()} 前不可调用`);
80
+ e.kind = 'rate_limit_local';
81
+ e.retryAfter = until - now;
82
+ throw e;
83
+ }
84
+ }
85
+ /** 命中远端限频后写冷却:now + seconds 秒内不再调用该 endpoint。 */
86
+ async penalize(endpointId, seconds) {
87
+ // 必须用 hasOwn —— 与 limitFor 同理,防原型链键。显式 null 才免罚;
88
+ // 未登记(hasOwn false)视为未知接口,远端说限频就限频。
89
+ // ⚠️ 实参必须是 endpoint id(见类注释):传 task id 会让这条豁免恒不触发。
90
+ if (Object.hasOwn(RATE_LIMITS, endpointId) && RATE_LIMITS[endpointId] === null)
91
+ return;
92
+ const now = this.clock();
93
+ await this.store.transaction((tx) => writeCooldown(tx, endpointId, now + seconds * 1000, { now: this.clock }));
94
+ }
95
+ }
@@ -0,0 +1,22 @@
1
+ import { DIM_TASKS } from './tasks/dim.js';
2
+ import { REPORT_TASKS } from './tasks/reports.js';
3
+ import { TICKET_TASKS } from './tasks/tickets.js';
4
+ import { SESSIONS_TASKS } from './tasks/sessions.js';
5
+ import { KNOWLEDGE_TASKS } from './tasks/knowledge.js';
6
+ /** 全量同步任务注册表:dim 6 + reports 9 + tickets 2 + sessions 1 + knowledge 3 = 21。 */
7
+ export const SYNC_TASKS = [
8
+ ...DIM_TASKS,
9
+ ...REPORT_TASKS,
10
+ ...TICKET_TASKS,
11
+ ...SESSIONS_TASKS,
12
+ ...KNOWLEDGE_TASKS,
13
+ ];
14
+ /** 按 id 取任务(sync run <id> 的分派入口)。 */
15
+ export function taskById(id) {
16
+ return SYNC_TASKS.find((t) => t.id === id);
17
+ }
18
+ /** 明确不支持同步的数据集及原因(reason 目前只有 realtime:实时快照不可回放)。 */
19
+ export const UNSUPPORTED_DATASETS = [
20
+ { id: 'realtime.session', reason: 'realtime' },
21
+ { id: 'realtime.ipcc', reason: 'realtime' },
22
+ ];
@@ -0,0 +1,114 @@
1
+ /** 读某 dataset 的水位状态行;不存在时全空。 */
2
+ export async function readWatermark(store, dataset) {
3
+ // 常量 SQL 调用点 1/3
4
+ const r = await store.query('SELECT watermark, range_status, last_synced_at, resolved_range_start, resolved_range_end FROM sync_state WHERE dataset = ?', [dataset]);
5
+ const row = r.rows[0];
6
+ if (!row) {
7
+ return { watermark: null, rangeStatus: null, lastSyncedAt: null, resolvedRangeStart: null, resolvedRangeEnd: null };
8
+ }
9
+ return {
10
+ watermark: row.watermark ?? null,
11
+ rangeStatus: row.range_status ?? null,
12
+ lastSyncedAt: row.last_synced_at ?? null,
13
+ resolvedRangeStart: row.resolved_range_start ?? null,
14
+ resolvedRangeEnd: row.resolved_range_end ?? null,
15
+ };
16
+ }
17
+ /** sync_state 行的完整列集(Store.upsert 契约:每行必须完整列集)。 */
18
+ function stateRow(dataset, watermark, rangeStatus, lastError, lockedBy, lockedAt, lastSyncedAt, rangeStart = null, rangeEnd = null) {
19
+ // D-T4 起 sync_state 共 9 列(+G2 两列 = 11 列):next_allowed_at / last_rate_limited_at
20
+ // 属限频闸门(src/sync/rate-gate.ts)专用,水位行恒为 null;
21
+ // resolved_range_start/end 只在 advanceWatermark 有值(G2 义务,spec §八.2)。
22
+ return { dataset, watermark, range_status: rangeStatus, last_error: lastError, locked_by: lockedBy, locked_at: lockedAt, last_synced_at: lastSyncedAt, next_allowed_at: null, last_rate_limited_at: null, resolved_range_start: rangeStart, resolved_range_end: rangeEnd };
23
+ }
24
+ /**
25
+ * 标记该 dataset 待同步(新一轮窗口开始)。
26
+ * ⚠️ 只翻状态、不动水位:`existing` 由调用方先经 readWatermark 读出传入
27
+ *(WriteTx 无 query——防线分层,读改写的「读」在事务外完成),markPending
28
+ * 保留其 watermark —— 清成 null 会让中断后重跑从 0 全量拉(API 成本巨大)。
29
+ * existing 缺省/null 或全空(无既有行)时水位为 null(首跑)。
30
+ *
31
+ * `lock`(E 中-1 引擎侧):本轮写者盖章 —— 与 markPending 同一行同一事务写入,
32
+ * 两者都写 sync_state 同一主键,分开写会互相清掉对方的列(先写锁再置 pending 会
33
+ * 清锁,先置 pending 再写锁会把 pending 覆回旧状态)。
34
+ */
35
+ export async function markPending(tx, dataset, existing, lock) {
36
+ const lockedBy = lock?.by ?? null;
37
+ const lockedAt = lock?.at ?? null;
38
+ const hasRow = existing !== null && existing !== undefined
39
+ && !(existing.watermark === null && existing.rangeStatus === null && existing.lastSyncedAt === null);
40
+ if (!hasRow) {
41
+ await tx.upsert('sync_state', [stateRow(dataset, null, 'pending', null, lockedBy, lockedAt, null)]);
42
+ return;
43
+ }
44
+ await tx.upsert('sync_state', [stateRow(dataset, existing.watermark, 'pending', null, lockedBy, lockedAt, existing.lastSyncedAt, existing.resolvedRangeStart ?? null, existing.resolvedRangeEnd ?? null)]);
45
+ }
46
+ /**
47
+ * 推进水位:写 watermark、range_status=complete、同步时间**与覆盖区间**(G2 义务)。
48
+ * @param range 本次成功推进覆盖的区间(引擎传入本窗 `w` 或快照的 resolvedRange)——
49
+ * 落 sync_state.resolved_range_start/end(epoch 毫秒字符串,`sync status` 的
50
+ * resolved_range 输出即由此格式化而来,spec §八.2/§十一.17)。
51
+ * 水位值由调用方 stringify 后经 watermark 传入。
52
+ * lock(E 中-1):本轮写者盖章原样保留 —— 水位行与锁列同在 sync_state 同一主键行上,
53
+ * 引擎在 markPending 盖的章不能在推进水位时被抹掉(引擎把同一个 lock 对象传两处)。
54
+ */
55
+ export async function advanceWatermark(tx, dataset, watermark, range, syncedAt, lock) {
56
+ await tx.upsert('sync_state', [stateRow(dataset, watermark, 'complete', null, lock?.by ?? null, lock?.at ?? null, syncedAt, String(range.start), String(range.end))]);
57
+ }
58
+ /**
59
+ * 清空该 dataset 的写者锁(E 中-1 引擎侧)。`existing` 由调用方在事务外读出:
60
+ * **锁列之外的列按 existing 回写** —— 清章绝不顺带丢掉水位或区间状态
61
+ *(sync_state 是单行全列 upsert,少写一列就等于把那一列清成 null)。
62
+ * G2:resolved_range_start/end 同属「锁列之外的列」,必须一并保形回写。
63
+ */
64
+ export async function clearLock(tx, dataset, existing) {
65
+ await tx.upsert('sync_state', [stateRow(dataset, existing?.watermark ?? null, existing?.rangeStatus ?? null, null, null, null, existing?.lastSyncedAt ?? null, existing?.resolvedRangeStart ?? null, existing?.resolvedRangeEnd ?? null)]);
66
+ }
67
+ /** 记录/覆盖一条缺口(同 dataset+range_start 靠主键幂等覆盖)。 */
68
+ export async function recordGap(tx, dataset, rangeStart, rangeEnd, reason, detail, opts = {}) {
69
+ // 时钟注入(T5 修复轮 低-4):引擎传 ctx.clock,测试可确定性断言;缺省真实时间。
70
+ const recordedAt = new Date(opts.now?.() ?? Date.now()).toISOString();
71
+ await tx.upsert('sync_gaps', [{ dataset, range_start: rangeStart, range_end: rangeEnd, reason, recorded_at: recordedAt, detail }]);
72
+ }
73
+ /** 清除指定起点的缺口。 */
74
+ export async function clearGap(tx, dataset, rangeStart) {
75
+ await tx.delete('sync_gaps', 'dataset = ? AND range_start = ?', [dataset, rangeStart]);
76
+ }
77
+ /** 列出缺口;传 dataset 则只列该 dataset,按 dataset+range_start 排序。 */
78
+ export async function listGaps(store, dataset) {
79
+ // 常量 SQL 调用点 2-3/4
80
+ const sql = dataset === undefined
81
+ ? 'SELECT dataset, range_start, range_end, reason, recorded_at, detail FROM sync_gaps ORDER BY dataset, range_start'
82
+ : 'SELECT dataset, range_start, range_end, reason, recorded_at, detail FROM sync_gaps WHERE dataset = ? ORDER BY dataset, range_start';
83
+ const r = await store.query(sql, dataset === undefined ? [] : [dataset]);
84
+ return r.rows.map((row) => ({
85
+ dataset: row.dataset,
86
+ rangeStart: row.range_start,
87
+ rangeEnd: row.range_end ?? null,
88
+ reason: row.reason,
89
+ recordedAt: row.recorded_at,
90
+ detail: row.detail ?? null,
91
+ }));
92
+ }
93
+ /**
94
+ * 读全部 sync_state 行,按 dataset 键控(含 `__ratelimit__:` 冷却行——调用方按前缀
95
+ * 自行排除)。status/verify/install 一次查询取代 N 次 readWatermark(21 任务)。
96
+ */
97
+ export async function listWatermarks(store) {
98
+ // 常量 SQL 调用点 4/4
99
+ const r = await store.query('SELECT dataset, watermark, range_status, last_synced_at, locked_by, locked_at, resolved_range_start, resolved_range_end FROM sync_state');
100
+ const out = new Map();
101
+ for (const row of r.rows) {
102
+ out.set(row.dataset, {
103
+ dataset: row.dataset,
104
+ watermark: row.watermark ?? null,
105
+ rangeStatus: row.range_status ?? null,
106
+ lastSyncedAt: row.last_synced_at ?? null,
107
+ lockedBy: row.locked_by ?? null,
108
+ lockedAt: row.locked_at ?? null,
109
+ resolvedRangeStart: row.resolved_range_start ?? null,
110
+ resolvedRangeEnd: row.resolved_range_end ?? null,
111
+ });
112
+ }
113
+ return out;
114
+ }
@@ -0,0 +1,186 @@
1
+ // src/sync/tasks/dim.ts
2
+ // D-T6:维度表快照任务(6 任务;tags 已在 v1 建表且其同步语义与维度表同构,
3
+ // 归属 T12 汇总时一并声明)。全部 kind=snapshot:接口全量无分页(设计稿 §6.2
4
+ // 实测),幂等来自「全删重插」。fetch 内部经 http.call + 信封归一化——sync 不绕过信封层。
5
+ // 落库行按 TABLES 列集显式投影(缺列补 null)——响应多出的键不进库,缺的键不炸 upsert。
6
+ //
7
+ // 全场景审查(修复批 1)在本文件收敛的语义:
8
+ // · B 高-1:**全部**取数走 callPaced(此前 fetchAll/两个内联 fetch 都是裸 call)——
9
+ // 裸 call 让本地令牌桶的拒绝冒泡成 fetch_failed gap,且远端限频的冷却行无人写;
10
+ // 声明 endpoint 后闸门键与注册表路径同源(B 中-6)。
11
+ // · C 中-14:staffIdList 非数组不再静默 `continue` —— 显式跳过并记 gapHint(见下)。
12
+ // · C 低-7:空串主键行拒绝(`''` 会写进 VARCHAR 主键列并反复覆盖同键)。
13
+ import { callPaced, nowIsoOf } from './pace.js';
14
+ /** 信封归一化结果 → 行数组;payload 不是数组视为响应形态漂移,显式失败。 */
15
+ function rowsOf(res, endpointId) {
16
+ if (!Array.isArray(res.payload)) {
17
+ throw new Error(`接口 ${endpointId} 返回的载荷不是数组(响应形态漂移?),拒绝落库`);
18
+ }
19
+ return res.payload;
20
+ }
21
+ /** 空串主键拒绝(C 低-7):`''` 会写进 VARCHAR 主键列,且空串行还能反复覆盖同键。 */
22
+ const isEmptyKey = (v) => v === null || v === undefined || v === '';
23
+ /**
24
+ * 按列集投影:只保留 cols 里的键(缺列补 null),值统一字符串化——
25
+ * 上游 ID/整型在响应里是 number,表列是 VARCHAR(BIGINT 精度红线)。
26
+ * `keyCols`(C 低-7):落库主键列 —— 值为空串的行**显式失败**,绝不因 `''` 写出一行
27
+ * 能被反复覆盖的同键行(空串是合法的 VARCHAR 值,upsert 主键语义会把它们当成同一个键)。
28
+ * 只有 cols 里出现的键列才在这里判定(如 template_id 由行外补齐,由调用方自行守卫)。
29
+ */
30
+ function project(rows, cols, nowIso, perRow, keyCols = []) {
31
+ const out = [];
32
+ for (const raw of rows) {
33
+ const mid = perRow ? perRow(raw) : raw;
34
+ if (mid === null)
35
+ continue;
36
+ const row = {};
37
+ for (const c of cols) {
38
+ const v = mid[c];
39
+ if (isEmptyKey(v) && keyCols.includes(c)) {
40
+ throw new Error(`响应出现空的主键列 ${c}(值为 ${JSON.stringify(v)})——` +
41
+ '空串/缺键会写出一行能被反复覆盖的同键行,拒绝落库');
42
+ }
43
+ row[c] = v === null || v === undefined ? null : typeof v === 'string' ? v : JSON.stringify(v);
44
+ }
45
+ row.synchronized_at = nowIso;
46
+ out.push(row);
47
+ }
48
+ return out;
49
+ }
50
+ /** 维度快照任务的通用 fetch:callPaced 调接口 → 行数组 → 投影直写(写侧引擎全删重插)。
51
+ * ⚠️ 走 callPaced(B 高-1):本地令牌桶拒绝被吸收为等待重试,远端限频写持久化冷却行。 */
52
+ async function fetchAll(endpointId, body, cols, ctx, nowIso, perRow, keyCols = []) {
53
+ const res = await callPaced(endpointId, body, ctx);
54
+ const rows = project(rowsOf(res, endpointId), cols, nowIso, perRow, keyCols);
55
+ return { rows, apiCount: rows.length };
56
+ }
57
+ // 列集常量(与 schema.ts TABLES 对齐;漂移由 schema drift 对拍测试拦)
58
+ const STAFF_COLS = ['id', 'realname', 'nickname', 'username', 'role', 'roleId', 'status',
59
+ 'createtime', 'updateTime', 'email', 'phone', 'workNumber', 'maxServiceCount',
60
+ 'skillScoreChat', 'skillScoreIpcc', 'groupInfo'];
61
+ const STAFF_GROUP_COLS = ['id', 'name'];
62
+ const CATEGORY_COLS = ['id', 'name', 'parentId', 'rank'];
63
+ const TEMPLATE_COLS = ['id', 'name', 'createTime', 'autoFlow', 'autoStatus', 'fileStatus', 'autoGuide'];
64
+ const FIELD_COLS = ['fieldId', 'id', 'name', 'type', 'required', 'customer', 'description', 'prefill'];
65
+ export const DIM_TASKS = [
66
+ {
67
+ id: 'dim.staff', table: 'staff', kind: 'snapshot',
68
+ watermark: { field: 'synchronized_at', initial: null },
69
+ primaryKey: ['id'],
70
+ endpoint: 'staff.list.new',
71
+ write: { kind: 'upsertRows' },
72
+ // role 文档标必填但实测 status/role 都省略时返回全部 330 行(§6.2)——不传,取全量。
73
+ // groupInfo 列表 → JSON 字符串列(project 统一 JSON.stringify,非字符串值均适用)。
74
+ fetch: (w, ctx) => fetchAll('staff.list.new', {}, STAFF_COLS, ctx, nowIsoOf(ctx), undefined, ['id']),
75
+ },
76
+ {
77
+ id: 'dim.staff_groups', table: 'staff_groups', kind: 'snapshot',
78
+ watermark: { field: 'synchronized_at', initial: null },
79
+ primaryKey: ['id'],
80
+ endpoint: 'staff.group.list.new',
81
+ write: { kind: 'upsertRows' },
82
+ // staff:true 取 staffIdList(成员关系单独落 staff_group_members,本表不存)。
83
+ fetch: (w, ctx) => fetchAll('staff.group.list.new', { staff: true }, STAFF_GROUP_COLS, ctx, nowIsoOf(ctx), undefined, ['id']),
84
+ },
85
+ {
86
+ id: 'dim.staff_group_members', table: 'staff_group_members', kind: 'snapshot',
87
+ watermark: { field: 'synchronized_at', initial: null },
88
+ primaryKey: ['group_id', 'staff_id'],
89
+ endpoint: 'staff.group.list.new',
90
+ write: { kind: 'upsertRows' },
91
+ // 权威来源是 staff.group.list?staff=true 的 staffIdList(含组管理员);
92
+ // 不用 staff.group.members 接口(实测 9/33 组缺人)。
93
+ // C 中-14:staffIdList 不是数组时**不再静默 continue**(那一组的成员会无声消失,
94
+ // 而快照是全量重建——消失的成员没有任何痕迹)。改为:跳过该组 + 记 gapHint
95
+ //(引擎落 sync_gaps,reason 自陈),组 id 缺失/空串则显式失败(主键无法归属)。
96
+ fetch: async (w, ctx) => {
97
+ void w;
98
+ const nowIso = nowIsoOf(ctx);
99
+ const res = await callPaced('staff.group.list.new', { staff: true }, ctx);
100
+ const groups = rowsOf(res, 'staff.group.list.new');
101
+ const out = [];
102
+ const malformed = [];
103
+ let skippedMembers = 0;
104
+ for (const g of groups) {
105
+ if (isEmptyKey(g.id)) {
106
+ throw new Error('接口 staff.group.list.new 返回了缺 id 的组——' +
107
+ 'staff_group_members 主键 (group_id, staff_id) 无法归属,拒绝落库');
108
+ }
109
+ const gid = String(g.id);
110
+ const list = g.staffIdList;
111
+ if (!Array.isArray(list)) {
112
+ // 显式跳过并记缺口:`staff:true` 下实测每组都有该键(§6.2)→ 非数组即形态漂移。
113
+ malformed.push(gid);
114
+ continue;
115
+ }
116
+ for (const sid of list) {
117
+ if (isEmptyKey(sid)) {
118
+ skippedMembers++;
119
+ continue;
120
+ } // 空成员 id:无主键可写
121
+ out.push({ group_id: gid, staff_id: String(sid), synchronized_at: nowIso });
122
+ }
123
+ }
124
+ const gapHint = (malformed.length > 0 || skippedMembers > 0)
125
+ ? {
126
+ reason: 'staff_id_list_malformed',
127
+ detail: `staffIdList 形态不符:${malformed.length} 个组(${malformed.slice(0, 5).join(',')})` +
128
+ `的 staffIdList 不是数组、${skippedMembers} 个成员 id 为空——这些成员未落库,` +
129
+ '请核对上游响应形态',
130
+ }
131
+ : undefined;
132
+ return { rows: out, apiCount: out.length, ...(gapHint ? { gapHint } : {}) };
133
+ },
134
+ },
135
+ {
136
+ id: 'dim.ticket_categories', table: 'ticket_categories', kind: 'snapshot',
137
+ watermark: { field: 'synchronized_at', initial: null },
138
+ primaryKey: ['id'],
139
+ endpoint: 'category.list',
140
+ write: { kind: 'upsertRows' },
141
+ // 文档标 type 必填(2=工单分类);响应列名是 parentId,落库保持原名。
142
+ fetch: (w, ctx) => fetchAll('category.list', { type: 2 }, CATEGORY_COLS, ctx, nowIsoOf(ctx), undefined, ['id']),
143
+ },
144
+ {
145
+ id: 'dim.ticket_templates', table: 'ticket_templates', kind: 'snapshot',
146
+ watermark: { field: 'synchronized_at', initial: null },
147
+ primaryKey: ['id'],
148
+ endpoint: 'ticket.template.list',
149
+ write: { kind: 'upsertRows' },
150
+ // 文档标 status 必填(-1=全部状态);响应 status 全为 1、不携带信息 → 不建列。
151
+ fetch: (w, ctx) => fetchAll('ticket.template.list', { status: -1 }, TEMPLATE_COLS, ctx, nowIsoOf(ctx), undefined, ['id']),
152
+ },
153
+ {
154
+ id: 'dim.ticket_template_fields', table: 'ticket_template_fields', kind: 'snapshot',
155
+ watermark: { field: 'synchronized_at', initial: null },
156
+ primaryKey: ['template_id', 'fieldId'],
157
+ endpoint: 'ticket.template.fields',
158
+ write: { kind: 'upsertRows' },
159
+ // 每模板一次调用(接口按 templateId 取字段);行补 template_id 列(主键 template_id+fieldId,fieldId 是响应键)。
160
+ // 闸门键取 ticket.template.fields(该任务的主要调用路径);templates 列表的
161
+ // ticket.template.list 也走 callPaced,同路径任务共享冷却(B 中-6 的路径口径)。
162
+ fetch: async (w, ctx) => {
163
+ void w;
164
+ const nowIso = nowIsoOf(ctx);
165
+ const tres = await callPaced('ticket.template.list', { status: -1 }, ctx);
166
+ const templates = rowsOf(tres, 'ticket.template.list');
167
+ const out = [];
168
+ for (const t of templates) {
169
+ if (isEmptyKey(t.id)) {
170
+ throw new Error('接口 ticket.template.list 返回了缺 id 的模板——' +
171
+ 'ticket_template_fields 的 template_id 无法归属,拒绝落库');
172
+ }
173
+ const fres = await callPaced('ticket.template.fields', { templateId: t.id }, ctx);
174
+ // 主键列 fieldId 的空值在 project 内显式失败(C 低-7)
175
+ const rows = project(rowsOf(fres, 'ticket.template.fields'), FIELD_COLS, nowIso, undefined, ['fieldId']);
176
+ for (const row of rows)
177
+ out.push({ ...row, template_id: String(t.id) });
178
+ }
179
+ return { rows: out, apiCount: out.length };
180
+ },
181
+ },
182
+ ];
183
+ /** 按 id 取维度任务(T12 汇总与测试的取用形态)。 */
184
+ export function taskById(id) {
185
+ return DIM_TASKS.find((t) => t.id === id);
186
+ }