qiyu-cli 0.2.1 → 0.2.3

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 (72) hide show
  1. package/README.md +433 -72
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +70 -0
  4. package/dist/commands/api.js +169 -49
  5. package/dist/commands/auth.js +151 -29
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +165 -127
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +449 -61
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +160 -33
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +321 -0
  17. package/dist/commands/store.js +165 -77
  18. package/dist/commands/sync-notes.js +374 -0
  19. package/dist/commands/sync-run.js +180 -47
  20. package/dist/commands/sync.js +232 -127
  21. package/dist/core/config.js +280 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +175 -54
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +36 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +65 -43
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +215 -29
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +148 -25
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +1551 -64
  56. package/dist/store/object-kinds.js +32 -0
  57. package/dist/store/retry.js +190 -7
  58. package/dist/store/schema.js +32 -4
  59. package/dist/sync/engine.js +439 -77
  60. package/dist/sync/registry.js +6 -0
  61. package/dist/sync/state.js +20 -0
  62. package/dist/sync/tasks/dim.js +23 -14
  63. package/dist/sync/tasks/knowledge.js +50 -8
  64. package/dist/sync/tasks/pace.js +27 -0
  65. package/dist/sync/tasks/pipeline.js +29 -9
  66. package/dist/sync/tasks/reports.js +176 -49
  67. package/dist/sync/tasks/sessions.js +88 -21
  68. package/dist/sync/tasks/tickets.js +59 -8
  69. package/dist/sync/types.js +60 -1
  70. package/dist/sync/windowing.js +0 -22
  71. package/dist/sync/write-contract.js +79 -0
  72. package/package.json +2 -2
@@ -98,6 +98,23 @@ export function reportBody(taskId, w) {
98
98
  * transfer_human 是形状 A、载荷在 data)。识别已知包装键(result/orders),
99
99
  * 其余对象形态视为「一行全局汇总」(overview 69 字段/summary 27 字段/transfer 恒 1 行)。
100
100
  */
101
+ /**
102
+ * 载荷 → 行数组(逐接口信封实测:C 族载荷是 message 解析物;robot_summary/
103
+ * transfer_human 是形状 A、载荷在 data)。识别已知包装键(result/orders),
104
+ * 其余对象形态视为「一行全局汇总」(overview 69 字段/summary 27 字段/transfer 恒 1 行)。
105
+ *
106
+ * ⚠️ **结构为空的载荷(`{}` / `[]`)一律拒绝**(HANDOFF 报表层 #6,2026-11-04 真实上游采样):
107
+ * 九个报表接口的**空窗**形状全部实测过,没有一个是空容器 ——
108
+ * · `overview` → 带 69 字段的**全零行**(`sessions:0` … 比例字段 `-1`);
109
+ * · `robot.summary` → 带字段的汇总行;`transferHuman` → **一行**数组
110
+ * `[{count:0, sessionRatio:-1, type:0}]`;`salaryDetail` → 带 account/date/id 的**一行**对象;
111
+ * · `staffworklod` / `satisfaction` / `staffAttendance` → `{result:[], total:0}`;
112
+ * `staffquality` → `{result:[], sum:{…34 字段}, total:0}`;
113
+ * `performance` → `{orders:[], sum:{…20 字段}, total:0}`。
114
+ * 所以 `{}` 落进下面的「一行全局汇总」兜底会把**一次形态漂移**写成一行全空行(覆盖真实
115
+ * 汇总的同键行),而 `[]` 会被当合法空窗 → `complete` 且零 gap:两种都是「静默吃掉一整窗」。
116
+ * 与 `api` 层 `not_found`(解包后 `{}`/`[]`)同一判据,这里只是把它变成**拒绝落库**。
117
+ */
101
118
  function payloadRows(taskId, payload) {
102
119
  // C 中-5:载荷为 null/undefined 是**形状漂移**(信封层丢 data 键、或上游改了形态),
103
120
  // 绝不能当合法空窗 —— 静默按空处理会把整段数据吞成 complete。与同文件 orders:null
@@ -105,9 +122,22 @@ function payloadRows(taskId, payload) {
105
122
  if (payload === null || payload === undefined) {
106
123
  throw new Error(`接口 ${endpointOf(taskId)} 未返回载荷(null/undefined)——响应形态漂移,拒绝按空窗处理`);
107
124
  }
108
- if (Array.isArray(payload))
125
+ if (Array.isArray(payload)) {
126
+ // 空数组:实测空窗从不是 `[]`(transferHuman 空窗是一行数组)→ 形态漂移。
127
+ if (payload.length === 0) {
128
+ throw new Error(`接口 ${endpointOf(taskId)} 返回空数组 [] —— 实测空窗形态是 `
129
+ + '{result:[],total:0}(result 族)或一行数组(transferHuman),空数组属响应形态漂移,拒绝按空窗处理');
130
+ }
109
131
  return { rows: payload, sum: null };
132
+ }
110
133
  const o = payload;
134
+ // 空对象:实测空窗从不是 `{}`(全局汇总表返回的是带字段的全零行;salaryDetail 返回带字段的一行)
135
+ // → 落进下面的「一行全局汇总」兜底会写出全空行,覆盖真实汇总。
136
+ if (Object.keys(o).length === 0) {
137
+ throw new Error(`接口 ${endpointOf(taskId)} 返回空对象 {} —— 实测空窗形态是带字段的全零行`
138
+ + '(overview/summary/salaryDetail)或 {result:[],total:0},空对象属响应形态漂移,'
139
+ + '拒绝当作「一行全局汇总」落库');
140
+ }
111
141
  // statistic.performance 的全 null 形态(orders:null/sum:null/total:null,code:200)
112
142
  // 是筛选失败(staffIdList 含租户不存在的 id),不是空窗口——fetch 层抛带 kind 的
113
143
  // 形态错误,引擎记 sync_gaps(reason=filter_matched_no_staff,T5 裁定透传)。
@@ -132,14 +162,69 @@ function staffRow(w, r, nowIso) {
132
162
  return null;
133
163
  return { ...baseRow(w, r, nowIso), staff_id: String(sid) };
134
164
  }
135
- /** 分页 + per-staff 投影(staffworklod / staff_satisfaction)。 */
136
- async function fetchPagedStaff(taskId, w, ctx) {
165
+ /**
166
+ * 分页 + per-staff 投影(staffworklod / staff_satisfaction;staffquality 传 withSum)。
167
+ * ⚠️ `withSum`(2026-11-03 实测修):staffquality 此前走 `fetchSimple` —— **不分页**,
168
+ * 上游 `total=1500` 只取回首页 1000 行仍 `complete`(C 中-3 的短读终检只存在于 `pagedRaw`,
169
+ * 实测只发了 1 个请求)。实测事实(设计稿 §6.2):`staffquality` **分页**(pageSize=5 时
170
+ * `result` 只有 5 行)且 `sum` 与分页无关、始终覆盖全集 → 分页拉满后照写 sum 全局行
171
+ * (staff_id='sum' 哨兵,主键含 stat_date,按天各自一行)。
172
+ */
173
+ async function fetchPagedStaff(taskId, w, ctx, withSum = false) {
137
174
  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 };
175
+ const { rows, sum } = await pagedRaw(taskId, w, ctx);
176
+ const mapped = [];
177
+ let dropped = 0;
178
+ for (const r of rows) {
179
+ const row = staffRow(w, r, nowIso);
180
+ if (row === null) {
181
+ dropped++;
182
+ continue;
183
+ } // 缺 staff_id 键的行:丢弃并计数(见下 gapHint)
184
+ mapped.push(row);
185
+ }
186
+ if (withSum && sum)
187
+ mapped.push({ ...baseRow(w, sum, nowIso), staff_id: 'sum' });
188
+ return { rows: mapped, apiCount: mapped.length, ...droppedHint(taskId, dropped, `缺 staffId(主键列,缺键或空串)`) };
189
+ }
190
+ /**
191
+ * 行被丢弃时的 task gapHint(`row_missing_key`)。
192
+ *
193
+ * ⚠️ 为什么必须记(审查 #5,2026-11-03):`apiCount` 取的是**过滤后**的行数,
194
+ * 配对核对(写库行数 vs apiCount)恒等,缺键行于是**静默消失** —— 窗口照样
195
+ * `status: complete`、`fetched == written`,Agent 无从知道上游有一批行没进库。
196
+ * 这类行是真的没落库(`TASK_GAP_LOSSY_REASONS` 档),必须留痕。
197
+ *
198
+ * `what` 是**丢弃成因的完整描述**(不是列名)—— 成因必须点名真正给坏值的那个东西
199
+ * (CodeRabbit #61:把「date 不是合法时间戳」写成「缺主键列」会把运维引向错的条件)。
200
+ */
201
+ function droppedHint(taskId, dropped, what) {
202
+ if (dropped === 0)
203
+ return {};
204
+ return {
205
+ gapHint: {
206
+ reason: 'row_missing_key',
207
+ detail: `${taskId}: ${dropped} 行${what}被丢弃、未落库`
208
+ + ' —— 上游响应形态漂移,请核对接口返回;本次按已落库的行覆盖窗口',
209
+ },
210
+ };
211
+ }
212
+ /**
213
+ * 一行被丢弃时的 gapHint:`dropped` 是按成因分好的几档(每档一个规模 + 一句说明)。
214
+ * 多个成因时合成一条(引擎每窗只有一个 gapHint),但**逐档点名**、不合并成一个数。
215
+ */
216
+ function droppedHintParts(taskId, parts) {
217
+ const nonZero = parts.filter(([n]) => n > 0);
218
+ if (nonZero.length === 0)
219
+ return {};
220
+ const detail = nonZero.map(([n, what]) => `${n} 行${what}`).join(';');
221
+ return {
222
+ gapHint: {
223
+ reason: 'row_missing_key',
224
+ detail: `${taskId}: ${detail}被丢弃、未落库`
225
+ + ' —— 上游响应形态漂移,请核对接口返回;本次按已落库的行覆盖窗口',
226
+ },
227
+ };
143
228
  }
144
229
  /**
145
230
  * stat_date + payload 的通用行投影(键列由各任务补齐)。
@@ -181,7 +266,14 @@ async function pagedRaw(taskId, w, ctx) {
181
266
  out.push(...rows);
182
267
  const total = res.payload?.total;
183
268
  if (typeof total !== 'number') {
184
- // total 缺省视为单页:拉满一页仍不声明 total 时不再翻(口径与 tickets.search 一致)
269
+ // ⚠️ 只有在**第一页**就缺 total 时才按「单页」处理(口径与 tickets.search 一致)。
270
+ // 已声明过 total 之后某页缺它 = 响应形态漂移,**不能**再把 declared 清空并 break ——
271
+ // 那会让下面的短读终检永远不执行,静默返回少于声明 total 的行且不留任何 gap
272
+ //(2026-11-07 审查实测:page1 total=5 + 2 行、page2 1 行无 total → 返回 3 行、不报错)。
273
+ if (declared !== null) {
274
+ throw new Error(`接口 ${endpointOf(taskId)} 第 ${page} 页缺少 total(首页声明 total=${declared}):` +
275
+ '响应形态漂移,拒绝落库——重跑即可');
276
+ }
185
277
  declared = null;
186
278
  break;
187
279
  }
@@ -217,35 +309,29 @@ function endpointOf(taskId) {
217
309
  default: throw new Error(`未知报表任务:${taskId}`);
218
310
  }
219
311
  }
220
- /** 普通报表 fetch(result/全局行形态):stat_date=窗口起点按上海天对齐;staffId 键取不到时用 'sum' 哨兵。 */
221
- function fetchSimple(taskId, perStaff) {
312
+ /**
313
+ * 全局汇总报表 fetch(overview / robot_summary / transfer_human):响应是**一行全局汇总**,
314
+ * 无 staffId,行形状按目标表列集投影(stat_date + payload)。
315
+ *
316
+ * ⚠️ 这里**没有** per-staff 分支(审查 #5,2026-11-03):早前本函数带 `perStaff` 参数,
317
+ * 但三个调用点全是全局表,`perStaff=true` 的分支连同它「缺 staffId 就 `continue` 丢弃」
318
+ * 的逻辑是**死代码**——声明了却永不执行的一支,正是契约诚实性要消灭的形态;per-staff 表
319
+ * (staffworklod / satisfaction / quality)早已改走 `fetchPagedStaff`(那里的丢弃有
320
+ * `row_missing_key` 缺口留痕)。因此本函数不做投影过滤,不存在静默丢行。
321
+ */
322
+ function fetchSimple(taskId) {
222
323
  return async (w, ctx) => {
223
324
  const nowIso = nowIsoOf(ctx);
224
325
  // B 高-1:走 callPaced(本地令牌桶拒绝被吸收为等待重试;远端限频写持久化冷却行)。
225
326
  // 裸 call 会让两种限频都直接冒泡成 fetch_failed gap,而空窗假空重试必然二次调用
226
327
  // 同一路径——这是最容易撞上本地限频的一条路径。
227
328
  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' });
329
+ const { rows } = payloadRows(taskId, res.payload);
330
+ // ⚠️ 刻意**不写** sum 行:这三张全局表的主键只有 stat_date,而同窗口的 sum 行不带
331
+ // 任何区分列 —— 写进去会与那一行全局汇总同键互覆(`payloadRows` 对全局表本来也
332
+ // 返回 sum=null;这里显式不取,避免以后有人以为「漏了」而补上)。per-staff 表的
333
+ // sum 由 `fetchPagedStaff` 按 `staff_id='sum'` 哨兵处理(那里主键含 stat_date)。
334
+ const mapped = rows.map((r) => baseRow(w, r, nowIso));
249
335
  return { rows: mapped, apiCount: mapped.length };
250
336
  };
251
337
  }
@@ -256,8 +342,14 @@ async function staffIds(store) {
256
342
  .map((x) => (isEmptyKey(x.id) ? '' : String(x.id)))
257
343
  .filter((id) => id !== '');
258
344
  }
259
- /** 报表任务的通用写策略(A 中-2:删除边界与行内日期列同口径 = 上海天对齐)。 */
345
+ /**
346
+ * 报表任务的通用写策略(A 中-2:删除边界与行内日期列同口径 = 上海天对齐)。
347
+ * ⚠️ 只在「窗起止都落在日界」时精确 —— 声明者必须同时 `windowAlign: 'shanghaiDay'`
348
+ *(注册表加载期由 `write-contract.ts` 校验,见 `tests/sync/delete-boundary-contract.test.ts`)。
349
+ */
260
350
  const RANGE_INSERT = { kind: 'deleteRangeInsert', rangeColumns: ['stat_date'], rangeAlign: 'shanghaiDay' };
351
+ /** 行内自带逐小时时间戳 → 按窗精确删(`[start, end)`),不碰相邻窗的边界日。 */
352
+ const HOUR_INSERT = { kind: 'deleteRangeInsert', instantColumn: 'hour_ts' };
261
353
  export const REPORT_TASKS = [
262
354
  {
263
355
  id: 'reports.overview', table: 'daily_overview', kind: 'windowed',
@@ -268,7 +360,7 @@ export const REPORT_TASKS = [
268
360
  primaryKey: ['stat_date'], reportDayRotation: true,
269
361
  endpoint: 'statistic.overview',
270
362
  write: RANGE_INSERT,
271
- fetch: fetchSimple('reports.overview', false),
363
+ fetch: fetchSimple('reports.overview'),
272
364
  },
273
365
  {
274
366
  id: 'reports.staff_workload', table: 'staff_workload', kind: 'windowed',
@@ -287,7 +379,9 @@ export const REPORT_TASKS = [
287
379
  primaryKey: ['stat_date', 'staff_id'], reportDayRotation: true,
288
380
  endpoint: 'statistic.staffquality',
289
381
  write: RANGE_INSERT,
290
- fetch: fetchSimple('reports.staff_quality', true),
382
+ // ⚠️ 必须分页(2026-11-03 实测修):此前 fetchSimple 单次调用不读 total —— 租户
383
+ // 客服 > 1000 时被静默截断且仍 complete。sum 全局行经 withSum 保留。
384
+ fetch: (w, ctx) => fetchPagedStaff('reports.staff_quality', w, ctx, true),
291
385
  },
292
386
  {
293
387
  id: 'reports.staff_satisfaction', table: 'staff_satisfaction', kind: 'windowed',
@@ -303,6 +397,11 @@ export const REPORT_TASKS = [
303
397
  // 逐行可信时间戳(`date` 按小时对齐,落 hour_ts)→ 31 天窗口可行(≈1.7 万行/窗);
304
398
  // stat_date 由该行的 hour_ts 推导(不是窗口起点)——它跟随该行自己的业务日
305
399
  maxWindowDays: 31, overlapDays: 0,
400
+ // ⚠️ **刻意不声明 windowAlign**(2026-11-03 复核):31 天步长的日对齐网格 + 残段窗
401
+ // 跳过规则会让「水位+1ms 落在日中间」的首窗被整段跳过、再跳到 +31 天,中间 30 天直接
402
+ // 不抓(日对齐只在 maxWindowDays=1 的任务上安全)。窗不对齐日界就不能按 stat_date 的
403
+ // 自然日删 —— 改用 `instantColumn: 'hour_ts'`:删除范围跟随窗本身,窗内消失的小时
404
+ // 精确删、窗外相邻窗写好的小时一行不碰。
306
405
  watermark: { field: 'stat_date', initial: null },
307
406
  // hour_ts 是响应内唯一可信日期字段(小时对齐时间戳)
308
407
  primaryKey: ['staff_id', 'hour_ts'], reportDayRotation: true,
@@ -310,13 +409,16 @@ export const REPORT_TASKS = [
310
409
  // G 高-1:endTime 不得晚于今天 0:00(14501 endTime is invalid),
311
410
  // 且今天 0:00 这条边界不稳定 → 引擎把窗口 end 钳到昨天 0:00(留整日余量)。
312
411
  windowEndClamp: 'shanghaiYesterday',
313
- write: RANGE_INSERT,
412
+ // 逐行 hour_ts → 删除按 [start, end) 精确(31 天窗起止不在日界,见 types.ts instantColumn)
413
+ write: HOUR_INSERT,
314
414
  // ⚠️ 请求体恒含 startTime(reportBody 已保证)——省略会静默降级为天粒度、少抓 ~10 倍。
315
415
  // 分页 total 收敛拉满(单页 pageSize=1000,31d 实测 17765 行 → 两页),再抽 hour_ts。
316
416
  fetch: async (w, ctx) => {
317
417
  const nowIso = nowIsoOf(ctx);
318
418
  const { rows } = await pagedRaw('reports.staff_attendance', w, ctx);
319
419
  const mapped = [];
420
+ let badKey = 0;
421
+ let badTs = 0;
320
422
  for (const r of rows) {
321
423
  const sid = r.staffId ?? r.staffid;
322
424
  const ts = r.date; // 该小时按小时对齐的时间戳
@@ -330,16 +432,29 @@ export const REPORT_TASKS = [
330
432
  //(与读侧「一条脏值炸整条命令」同一失败模式)。上界取 `MAX_SHANGHAI_SAFE_MS`
331
433
  // 而不是 `MAX_DATE_MS`:两者都要「能回显成 +08:00 ISO」,差 8h 就会在
332
434
  // `shanghaiDayIso` 的偏移后一段重新抛。
435
+ // 丢弃的两类分开计数(CodeRabbit #61):缺 staff_id 是「缺主键列」,
436
+ // date 非数字/秒级/越界是「脏时间戳」—— 两者的动作不同,不能混成一句。
333
437
  const n = Number(ts);
334
- if (isEmptyKey(sid) || !Number.isFinite(n) || n <= 1e11 || n > MAX_SHANGHAI_SAFE_MS)
438
+ if (isEmptyKey(sid)) {
439
+ badKey++;
440
+ continue;
441
+ }
442
+ if (!Number.isFinite(n) || n <= 1e11 || n > MAX_SHANGHAI_SAFE_MS) {
443
+ badTs++;
335
444
  continue;
445
+ }
336
446
  // 修复批 4:stat_date 按**本行的 hour_ts** 推导上海日(不再用窗口起点)——
337
447
  // 31 天窗口里行跨多个自然日,用窗口起点会把它们全标成窗口首日。
338
- // 删除范围仍是 [dayOf(w.start), dayOf(w.end)](writeRows 的天对齐边界),
339
- // 覆盖窗内所有天 → 与本行的 stat_date 一致。
448
+ // 删除范围按 hour_ts ∈ [w.start, w.end)(write 的 instantColumn),与写入逐行同口径。
340
449
  mapped.push({ ...baseRow(w, r, nowIso, n), staff_id: String(sid), hour_ts: new Date(n).toISOString() });
341
450
  }
342
- return { rows: mapped, apiCount: mapped.length };
451
+ return {
452
+ rows: mapped, apiCount: mapped.length,
453
+ ...droppedHintParts('reports.staff_attendance', [
454
+ [badKey, '缺 staffId(主键列,缺键或空串)'],
455
+ [badTs, '的 date 不是合法毫秒时间戳(非数字/秒级/越界,无法作为 hour_ts)'],
456
+ ]),
457
+ };
343
458
  },
344
459
  },
345
460
  {
@@ -350,28 +465,40 @@ export const REPORT_TASKS = [
350
465
  watermark: { field: 'stat_date', initial: null },
351
466
  primaryKey: ['order_id'], reportDayRotation: true,
352
467
  endpoint: 'statistic.performance',
353
- // G 高-1:与 staff_attendance 同族的 endTime 对齐检查(14501 endTime is invalid)
468
+ // G 高-1:与 staff_attendance 同族的 endTime 上界检查(14501 endTime is invalid)
354
469
  windowEndClamp: 'shanghaiYesterday',
355
470
  write: RANGE_INSERT,
356
471
  // orders:null = 筛选失败、不是空窗口(staffIdList 含租户不存在的 id 时 code:200
357
472
  // 全 null)→ 显式 gapHint,引擎落 sync_gaps(T5 裁定:透传原始 reason)。
358
- // 行映射补主键列 order_id(响应键 orderId);缺 order_id 的订单行丢弃——
359
- // 计入 fetched 不写库(脏单行不致断流,与 per-staff 表同一取舍);
360
- // sum 全局行按 controller 裁定落同表哨兵 order_id='sum'(与 staff_quality 一致)。
473
+ // 行映射补主键列 order_id(响应键 orderId);缺 order_id 的订单行**丢弃且不计入
474
+ // fetched**(`continue` 在 push 之前 —— 此前注释写「计入 fetched」,与代码相反;
475
+ // 「丢了几行」目前对 Agent 不可见,见 HANDOFF 的 report_row_dropped 待办)。
476
+ // ⚠️ sum 行必须**按天**唯一(2026-11-03 实测修):本表主键只有 `order_id`,而
477
+ // staff_quality 的哨兵 `staff_id='sum'` 之所以按天各一行,是它的主键含 stat_date。
478
+ // 沿用裸 `'sum'` 时,回补前一天会 upsert 覆盖后一天的 sum(实测:先 day1 再 day0,
479
+ // day1 的汇总整体消失)—— 故哨兵随窗口日:`sum:<上海日>`。
361
480
  fetch: async (w, ctx) => {
362
481
  try {
363
482
  const nowIso = nowIsoOf(ctx);
364
483
  const { rows, sum } = await pagedRaw('reports.order_performance', w, ctx);
365
484
  const mapped = [];
485
+ let dropped = 0;
366
486
  for (const r of rows) {
367
487
  const oid = r.orderId ?? r.order_id;
368
- if (isEmptyKey(oid))
488
+ // 缺 order_id 的订单行:丢弃并计数(审查 #5,见 droppedHint);此前只丢弃、
489
+ // 不留痕,Agent 从 complete 的窗口上看不出上游有一批行没进库。
490
+ if (isEmptyKey(oid)) {
491
+ dropped++;
369
492
  continue;
493
+ }
370
494
  mapped.push({ ...baseRow(w, r, nowIso), order_id: String(oid) });
371
495
  }
372
496
  if (sum)
373
- mapped.push({ ...baseRow(w, sum, nowIso), order_id: 'sum' });
374
- return { rows: mapped, apiCount: mapped.length };
497
+ mapped.push({ ...baseRow(w, sum, nowIso), order_id: `sum:${shanghaiDayIso(w.start)}` });
498
+ return {
499
+ rows: mapped, apiCount: mapped.length,
500
+ ...droppedHint('reports.order_performance', dropped, '缺 orderId(主键列,缺键或空串)'),
501
+ };
375
502
  }
376
503
  catch (e) {
377
504
  if (e.kind === 'filter_matched_no_staff') {
@@ -425,7 +552,7 @@ export const REPORT_TASKS = [
425
552
  endpoint: 'robot.statistic.summary',
426
553
  write: RANGE_INSERT,
427
554
  // 形状 A;robotId 被服务端忽略 → body 不含(reportBody 保证)
428
- fetch: fetchSimple('reports.robot_summary', false),
555
+ fetch: fetchSimple('reports.robot_summary'),
429
556
  },
430
557
  {
431
558
  id: 'reports.transfer_human', table: 'transfer_human', kind: 'windowed',
@@ -439,7 +566,7 @@ export const REPORT_TASKS = [
439
566
  endpoint: 'ai.statistic.transferHuman',
440
567
  write: RANGE_INSERT,
441
568
  // 形状 A;type/robotId 被服务端忽略 → body 不含(reportBody 保证)
442
- fetch: fetchSimple('reports.transfer_human', false),
569
+ fetch: fetchSimple('reports.transfer_human'),
443
570
  },
444
571
  ];
445
572
  /** 按 id 取报表任务(T12 汇总与测试的取用形态)。 */
@@ -1,7 +1,8 @@
1
1
  // src/sync/tasks/sessions.ts
2
2
  // D-T10:会话导出任务声明(spec §5.3)—— 唯一走四步流水线的 windowed 任务。
3
3
  // 实测事实(设计稿 §7.5):
4
- // ① 窗口 ≤6 天(143.5h 通过 / 144.0h 报 14004)→ maxWindowDays=6;
4
+ // ① 窗口跨度必须 **<** 6 天(恰 144.0h 报 14004,143.9999h 通过)→ maxWindowDays=6,
5
+ // 且 fetch 把请求收成 end−1(跨度 6 天 − 1ms,见 fetchSessions 内注释);
5
6
  // ② 相邻窗口必须重叠 1 天(跨窗口长会话会漏,实测 5 会话/16 消息)→ overlapDays=1,
6
7
  // 重叠行由按 session.id 的 upsert 幂等吸收(**去重按 session.id,绝不能按导出任务 key**);
7
8
  // ③ **导出按 endTime 过滤**(判定式 window.start <= endTime <= window.end)→ 水位字段 endTime;
@@ -19,6 +20,20 @@ const isoOf = (ms) => new Date(ms).toISOString();
19
20
  const strOrNull = (v) => v === null || v === undefined ? null : typeof v === 'string' ? v : JSON.stringify(v);
20
21
  /** 空串主键/键列拒绝(C 低-7):`''` 是合法的 VARCHAR 值,会写出一行能被反复覆盖的同键行。 */
21
22
  const isEmptyKey = (v) => v === null || v === undefined || v === '';
23
+ /**
24
+ * 会话行的主键取值:导出原生字段是 `id`,已投影行是 `session_id`。
25
+ * ⚠️ 规则**只在这里定义一份**:fetch 侧的丢弃判据与 `sessionRow` 的投影必须同源 ——
26
+ * 两处各写一份 `a ?? b` 时,写反了次序(fetch 用 `session_id ?? id`、投影用
27
+ * `id ?? session_id`)会让 `{id:'', session_id:'x'}` 在 fetch 被判「有键」、在 enrich
28
+ * 被判「缺键」,又回到「written < expected → 整窗 count_mismatch 回滚」的老路。
29
+ * 语义:取**第一个非空**候选 —— 空串不是键,但别名里有值就说明这行有键可用。
30
+ */
31
+ function sessionKeyOf(src) {
32
+ for (const v of [src.id, src.session_id])
33
+ if (!isEmptyKey(v))
34
+ return v;
35
+ return undefined;
36
+ }
22
37
  /** categoryDetail 归一化:"a / b / c / d" → "a/b/c/d"(导出 " / " 带空格 → /one 无空格)。 */
23
38
  export function normalizeCategoryDetail(v) {
24
39
  if (v === null || v === undefined || v === '')
@@ -52,7 +67,7 @@ export function deriveSessionType(staffId) {
52
67
  * ⚠️ 本函数是纯投影(红线 1:同输入同输出)—— synchronized_at 从输入行透传
53
68
  *(fetch 在进 enrich 前统一盖章,enrich 直测两调用相等);输入无戳则为 null(列可空)。 */
54
69
  function sessionRow(src) {
55
- const id = src.id ?? src.session_id;
70
+ const id = sessionKeyOf(src);
56
71
  // 键缺失/空串行:丢弃且不计入 fetched(与 apiCount 口径一致;C 低-7)
57
72
  if (isEmptyKey(id))
58
73
  return null;
@@ -80,7 +95,18 @@ async function fetchSessions(w, ctx) {
80
95
  throw new Error('sessions.export 需要 fetchZip 注入(下载走 ZIP 二进制通道,与 JSON 信封层不同构)——生产接线归 sync run 编排层');
81
96
  }
82
97
  const nowIso = nowIsoOf(ctx);
83
- const { sessions, fixture } = await runExportPipeline(w, {
98
+ // ⚠️ 引擎的 Range 是**半开**区间 [start, end),导出接口的判定式却是**闭**区间
99
+ // `window.start <= endTime <= window.end`(本文件第 ③ 条实测)。把 `w.end` 原样发出去
100
+ // 有两处错:① 多覆盖 1ms —— endTime == w.end 的行该归下一窗(下一窗起点是
101
+ // end − overlap,重叠幂等会吸收,但请求窗口与实际覆盖对不上);② 窗口跨度**恰好等于**
102
+ // maxWindowDays × 86400000 —— 实测服务端严格拒绝这个边界:跨度 518400000ms(144.0h)
103
+ // → `14004 Timestamp interval limit`,518399999ms(143.9999h)通过。2026-11-08 用真实
104
+ // 凭证复现:`sync run sessions.export` 每个 6 天窗都 fetch_failed(底层 Timestamp
105
+ // interval limit),水位冻结、一行不落。半开 → 闭区间的正确映射就是 `end − 1`,它同时
106
+ // 把跨度降到上限之内;1ms 窗保持原样(`end − 1 == start` 会撞 start==end 的 14004)。
107
+ // fixture 核对与 gap 文案一律用 `req`(服务端声明回显的是实际请求值),不用 `w`。
108
+ const req = { start: w.start, end: Math.max(w.start + 1, w.end - 1) };
109
+ const { sessions, fixture } = await runExportPipeline(req, {
84
110
  credentials: ctx.credentials,
85
111
  fetchZip: sctx.fetchZip,
86
112
  pollIntervalMs: sctx.pollIntervalMs,
@@ -89,10 +115,29 @@ async function fetchSessions(w, ctx) {
89
115
  gate: ctx.gate,
90
116
  clock: ctx.clock,
91
117
  });
118
+ // ⚠️ 缺 id 的行必须在 fetch 侧就丢弃并计数(2026-11-04 修)。此前它们留到 enrich
119
+ // 才被 `sessionRow` 丢掉,而 `apiCount` 已经按**丢弃前**的行数取好 —— 引擎的配对
120
+ // 基线于是包含永远不会落库的行:written < expected → 整窗 count_mismatch 回滚,
121
+ // 且 gap 只说「应写 N 行、实际写入 M 行」,不点名真正的原因(缺 id)。
122
+ // 现在与 reports 族同一口径:先过滤、apiCount 取过滤后行数、丢弃记 row_missing_key。
123
+ const withId = [];
124
+ let dropped = 0;
125
+ for (const r of sessions) {
126
+ // ⚠️ 必须走 `sessionKeyOf`,不能就地写 `r.session_id ?? r.id`(CodeRabbit PR #67 抓到):
127
+ // 两处各写一份时次序写反,`{id: 7, session_id: ''}` 会在 fetch 判「缺键」而
128
+ // `sessionRow` 判「有键」—— 合法行被丢弃、水位照常推进,且这条路径绕过 enrich 单测。
129
+ if (isEmptyKey(sessionKeyOf(r)))
130
+ dropped++;
131
+ else
132
+ withId.push(r);
133
+ }
92
134
  // synchronized_at 在 fetch 侧按窗统一盖章(单值、确定性于本窗)——enrich 是纯投影
93
135
  //(红线 1:同输入行永远同输出),只透传该戳;原始行直出(session.id 键、未投影)。
94
- const stamped = sessions.map((r) => ({ ...r, synchronized_at: nowIso }));
95
- const base = { rows: stamped, apiCount: sessions.length };
136
+ const stamped = withId.map((r) => ({ ...r, synchronized_at: nowIso }));
137
+ const base = { rows: stamped, apiCount: withId.length };
138
+ const dropNote = dropped > 0
139
+ ? `${dropped} 行缺 id(主键列,缺键或空串)被丢弃、未落库(已从上文的行数统计中扣除)`
140
+ : '';
96
141
  // —— C-8:尾部标记行(fixture)= 导出自己的窗口声明,与请求窗口核对 ——
97
142
  // 实测形态(private/raw/session.txt,4687 行样本):**完整导出必然带这一行**,恰好一行、
98
143
  // 紧随全部 JSON 行之后,声明一个 24h 窗口。因此「带了它」是正常形态,不是异常;
@@ -100,38 +145,53 @@ async function fetchSessions(w, ctx) {
100
145
  // ⚠️ fixture 非空 ⇒ 必然可解析(parseJsonl 与这里共用 parseExportFixture 判形态,
101
146
  // 不会各写一套正则)——所以没有「fixture 解析不出」的分支,那是不可达代码。
102
147
  const declared = fixture === undefined ? null : parseExportFixture(fixture);
103
- if (declared !== null && (declared.start > w.start || declared.end < w.end)) {
148
+ if (declared !== null && (declared.start > req.start || declared.end < req.end)) {
104
149
  // 声明的窗口不覆盖本窗请求 → 本窗数据可疑(服务端实测会按(企业,窗口)复用已计算的
105
150
  // 导出结果,同参数重复创建返回不同 key 相同数据)→ 宁可失败:fetch 抛错由引擎包装成
106
151
  // 中文 gap(failDetail)+ 水位冻结(contiguousBroken),绝不把来路不明的行写进库。
107
152
  throw new Error(`会话导出格式漂移(${fixture}):导出声明的窗口 ` +
108
153
  `[${isoOf(declared.start)}, ${isoOf(declared.end)}] 未覆盖请求窗口 ` +
109
- `[${isoOf(w.start)}, ${isoOf(w.end)}] —— 本窗数据可疑,拒绝落库`);
154
+ `[${isoOf(req.start)}, ${isoOf(req.end)}] —— 本窗数据可疑,拒绝落库`);
110
155
  }
111
156
  if (fixture === undefined) {
112
157
  // 完整导出应带尾部标记(见上);缺失 = 导出流没有声明它覆盖到哪 —— 空窗可能是真空、
113
158
  // 也可能是流被截断在行边界(逐行 JSON 解析对截断在行中间的情况已显式失败)。
114
159
  // 不判失败(历史样本可能无),但绝不静默:记一条 gap,让两类空窗可区分。
115
- return {
116
- ...base,
117
- gapHint: {
160
+ // ⚠️ 两条提示用**数组**带出(CodeRabbit PR #67):丢弃行(row_missing_key,真的少了)
161
+ // 与缺 fixture(export_fixture_unreported,覆盖无从核对)互不覆盖 —— 压成一条会让
162
+ // 消费方按 reason 分支时永远漏掉另一类信号。引擎逐条落 sync_gaps、逐条可分支。
163
+ const hints = [{
118
164
  reason: 'export_fixture_unreported',
119
165
  detail: `导出流未上报尾部标记行(完整导出末尾应有一行 startTime=…,endTime=… 声明导出窗口):` +
120
- `本窗 ${sessions.length} 行数据的窗口覆盖无从核对 —— 空窗可能确实是空,也可能是导出流被截断在行边界。` +
121
- `请求窗口 [${isoOf(w.start)}, ${isoOf(w.end)}]`,
122
- },
123
- };
166
+ `本窗 ${withId.length} 行数据的窗口覆盖无从核对 —— 空窗可能确实是空,也可能是导出流被截断在行边界。` +
167
+ `请求窗口 [${isoOf(req.start)}, ${isoOf(req.end)}]`,
168
+ }];
169
+ if (dropped > 0) {
170
+ hints.push({ reason: 'row_missing_key', detail: `sessions.export: ${dropNote} —— 上游响应形态漂移(正常导出每行都带 id),请核对接口返回` });
171
+ }
172
+ return { ...base, gapHint: hints };
124
173
  }
125
- if (declared !== null && (declared.start < w.start || declared.end > w.end)) {
174
+ if (declared !== null && (declared.start < req.start || declared.end > req.end)) {
126
175
  // 覆盖成立但宽于请求:多出来的行由 session_id 幂等 upsert 吸收(与 overlapDays 同机制),
127
176
  // 数据不受损 —— 但「服务端改了窗口」这件事必须可见,记 gap 并带上标记行原文。
128
- return {
129
- ...base,
130
- gapHint: {
177
+ const hints = [{
131
178
  reason: 'export_window_mismatch',
132
179
  detail: `导出声明的窗口 [${isoOf(declared.start)}, ${isoOf(declared.end)}] 宽于请求窗口 ` +
133
- `[${isoOf(w.start)}, ${isoOf(w.end)}](重叠行由 session_id 幂等吸收)`,
180
+ `[${isoOf(req.start)}, ${isoOf(req.end)}](重叠行由 session_id 幂等吸收)`,
134
181
  fixture,
182
+ }];
183
+ if (dropped > 0) {
184
+ hints.push({ reason: 'row_missing_key', detail: `sessions.export: ${dropNote} —— 上游响应形态漂移(正常导出每行都带 id),请核对接口返回` });
185
+ }
186
+ return { ...base, gapHint: hints };
187
+ }
188
+ if (dropped > 0) {
189
+ return {
190
+ ...base,
191
+ gapHint: {
192
+ reason: 'row_missing_key',
193
+ detail: `sessions.export: ${dropNote} —— 上游响应形态漂移(正常导出每行都带 id),` +
194
+ '请核对接口返回;本次按已落库的行覆盖窗口',
135
195
  },
136
196
  };
137
197
  }
@@ -157,8 +217,9 @@ export function assertFixtureGranularity(task) {
157
217
  }
158
218
  /**
159
219
  * enrich:投影 + 确定性派生(红线 1 推论:同输入行永远同输出)。
160
- * 派生 session_type(staffId 数字判别)+ categoryDetail 归一化;缺 id 行返回 null
161
- *(丢弃且不计入 fetched——与 apiCount 口径一致)。synchronized_at 从输入行透传
220
+ * 派生 session_type(staffId 数字判别)+ categoryDetail 归一化。缺 id 行在 **fetch 侧**
221
+ * 已丢弃并记 row_missing_key(此前留到这里才丢,与 apiCount 口径不一致会导致整窗
222
+ * count_mismatch 回滚);这里保留 null 兜底,正常输入不会触发。synchronized_at 从输入行透传
162
223
  *(fetch 已统一盖章),无戳直测时为 null —— 本函数不含任何时钟读取。
163
224
  */
164
225
  function enrichSession(src) {
@@ -173,6 +234,12 @@ export const SESSIONS_TASKS = [
173
234
  primaryKey: ['session_id'],
174
235
  // 闸门键 = 主驱动路径(create 是限频的那一个:10 秒 6 次);check 显式登记为无限频。
175
236
  endpoint: 'export.session',
237
+ // ⚠️ 闸门必须覆盖 fetch 实际调用的**每个** endpoint(2026-11-02 实测修):
238
+ // `export.session` 被限流时 penalize 写的是它自己的冷却行,只声明一个键时引擎
239
+ // 恰好读的就是它 —— 但流水线还会调 `export.session.check`(登记为无限频,
240
+ // 理论上不会被 penalize)。把它一并声明是**为了让守卫能双向核对**
241
+ // (tests/sync/gate-keys.test.ts 按 fetch 实际调用的 id 集合比对),不是多余的。
242
+ gateEndpoints: ['export.session', 'export.session.check'],
176
243
  write: { kind: 'upsertRows' },
177
244
  fetch: fetchSessions,
178
245
  enrich: enrichSession,