【缺陷】数据导出(CSV/XLSX)日期时间列硬编码按 UTC 渲染,与界面时区不一致(@objectstack/rest export-format.ts formatDate)

[baozhoutao]

版本与环境

• @objectstack/* 17.0.0-rc.6(rest / console / core / spec)
• 复现环境:全新空库 SQLite dev 实例,OS_LOCALIZATION_TIMEZONE=Asia/Shanghai,容器 TZ=Asia/Shanghai
• 触发入口:Console 列表工具栏原生「导出」按钮(CSV 与 XLSX 均复现)

现象

界面按业务时区(东八区)正确显示日期时间,但导出文件中同一字段按 UTC 输出,相差 8 小时;跨日记录在导出文件中会退到前一天(月初记录退到上个月,月度对账直接对不上)。

字段(datetime)	界面显示(东八区)	导出文件值	差值
扫码时间	2026/8/1 上午6:00	2026-07-31 22:00:00	−8h,跨月退到 7 月
下工时间	2026/8/13 下午5:00	2026-08-13 09:00:00	−8h
created_at(系统字段)	当地 16:59:35	2026-08-13 08:59:35	−8h

CSV 与 XLSX 输出完全相同的 UTC 字符串(XLSX 中为文本单元格,非带时区的日期型)。已在 3 个不同对象上复现;formatCellValue() 按字段类型分派,与对象无关,波及全部含 date/datetime 列的导出。

复现步骤

1. 全新实例,OS_LOCALIZATION_TIMEZONE=Asia/Shanghai;
2. 任一对象造一条 datetime 值为当地 2026-08-01 06:00(落库 2026-07-31T22:00:00.000Z)的记录;
3. 列表页确认界面显示 2026/8/1 上午6:00;
4. 点工具栏「导出」下载 CSV 或 XLSX;
5. 文件中该列为 2026-07-31 22:00:00(期望:2026-08-01 06:00:00)。

根因(已定位到函数)

调用链:Console exportDownload() → GET /api/v1/data/{object}/export?format=…&fields=…(请求无时区参数)→ @objectstack/rest src/rest-server.ts:6930 导出路由 → CSV rowsToCsv()(:1651-1663)/ XLSX(:7208)→ formatRowCells(row, cols, metaMap)(签名无时区入参)→ src/export-format.ts:174-181:

/** `YYYY-MM-DD` (date) or `YYYY-MM-DD HH:mm:ss` (datetime), in UTC. */
function formatDate(value: unknown, withTime: boolean): unknown {
  const d = toDate(value);
  if (!d) return value;
  const ymd = `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
  if (!withTime) return ymd;
  return `${ymd} ${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}`;
}

getUTC* 写死,由同文件 formatCellValue()(:251-252)对 type: 'date' / type: 'datetime' 无条件调用。getUTC* 与进程 TZ 无关,部署侧无从规避;导出链路亦无时区配置项、无 export 钩子、视图 exportOptions 无格式化项。

三条佐证,倾向这是疏漏而非有意设计:

1. 时区在这条路径上拿得到、只是没接:导出路由第一步 resolveExecCtx(src/rest-server.ts:6935)取到的 ExecutionContext 已带 timezone(resolveLocalizationContext() 级联 平台默认→全局→租户),格式化层未使用;
2. 同平台别处认时区:自动编号日期令牌按 ADR-0053「business timezone」渲染,fallback 才是 UTC(@objectstack/spec RenderAutonumberInput.timezone);导出格式化与该语义不一致;
3. 导出自身两套时钟:同文件 exportContentDisposition()(src/export-format.ts:58-82)生成文件名时间戳用 getFullYear()/getHours() 本地时区取值——文件名东八区、文件内容 UTC,同一次导出内部自相矛盾。

建议修法

把 ExecutionContext.timezone 透传进 formatRowCells / formatCellValue,formatDate 用 Intl.DateTimeFormat(…, { timeZone }) 按业务时区取日历分量;timezone 缺省时维持现状(UTC),保证向后兼容。

来源

下游实施项目验收中发现并完成定位:steedos-labs/os-project-titanwind-ehr#1269(含完整取证:3 对象实测截图、导出原件、逐介入点排查记录)。修复前下游导出文件无法用于月度对账,盼排期。

[hotlong]

Triage: lands in packages/rest (src/export-format.ts formatDate / formatCellValue, plumbed through formatRowCells in src/rest-server.ts) ⇒ domain:cli, pm:queue, type Bug, target:v17. Release-board rationale (binary test, class ①): a published-surface defect a downstream deployment hits today — 17.0.0-rc.6, Console export of every date/datetime column renders UTC while the UI renders the business timezone, cross-day rows fall into the wrong month and monthly reconciliation fails (full forensics in steedos-labs/os-project-titanwind-ehr#1269). Root cause is already located to the function; the fix direction in the body (thread ExecutionContext.timezone — already resolved at the export route — into the formatter, Intl.DateTimeFormat with timeZone, UTC fallback when absent) is consistent with the ADR-0053 business-timezone semantics that autonumber date tokens already follow, and with the file-name-vs-content self-contradiction noted in exportContentDisposition. Not a contract accept/reject change — output formatting pulled back to declared semantics. Dedup: no open twin found (export timezone / formatDate UTC searches). Size/model suggestion: M, opus; consumer-package tests should cover CSV and XLSX both, plus the timezone-absent fallback.

---

Generated by Claude Code

[os-zhuang]

Queued first in this lane — dispatches the moment #7912 lands. (domain:cli seat #6024, session session_01P7vaLs7bhBPi9m3JyzkhDj.) Stays pm:queue, unassigned; ⛔ not a claim.

Maintainer directive, 2026-08-13 (live PM chat): target:v17 and Bug take priority. Under it this card is the top of this lane's queue — it is the only dispatchable v17 card here (the other, #7644, is pm:on-hold awaiting a 17.0.0 release), it is type Bug, and it has a measured downstream deployment blocked on it rather than an internal sweep finding.

Why it is not out already — same-file hard serial, not a grading doubt:

card	region of packages/rest/src/rest-server.ts
#7912 (in flight)	filterAppForUser, ~:2976-3056
#8373 (this card)	the export route ~:6930, rowsToCsv ~:1651-1663, XLSX ~:7208

Regions are ~4000 lines apart, but the rule is the rule: priority is ordering, not exemption — even priority:p0 does not waive same-file serialization. I put the exemption to the maintainer explicitly (region-level declaration + merge main before PR + re-merge after the sibling lands + merge-queue arbitration) and the ruling was do not exempt; wait for #7912 to land. Recording that here so the next reader does not re-litigate it.

⇒ rest-server.ts queue is now #7912 (in flight) → #8373 → #8039. This card displaces #8039, which is comment-only and was previously next.

For whoever takes it — leads to verify, not inherit. The card is unusually well-diagnosed (root cause located to formatDate at export-format.ts:174-181, with the call chain traced), and that is exactly the kind of precision that decays: re-measure the line anchors on origin/main at dispatch time and anchor on symbols. Two things on the card worth carrying:

• The timezone is already resolved on this path and simply not threaded — resolveExecCtx at the export route hands back an ExecutionContext carrying timezone (platform default → global → tenant cascade). The fix is plumbing, not a new resolution mechanism.
• ⭐ The strongest evidence that this is an oversight rather than a design choice: the same file already keeps two clocks. exportContentDisposition() (:58-82) builds the download's filename timestamp with local-time getters while the file's contents use getUTC*. One export, contradicting itself.

Coverage must include CSV and XLSX (both reproduce), plus the timezone-absent fallback staying UTC for backward compatibility. Size/model per triage: M, mode:subagent, model: opus.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 4 (domain:cli seat #6024)
Session: session_01P7vaLs7bhBPi9m3JyzkhDj
Branch: claude/issue-8373-export-business-timezone
Worktree: objectstack-issue-8373
Domain: domain:cli
File surface: packages/rest/src/export-format.ts (formatDate / formatCellValue / formatRowCells) + the export route's call sites in packages/rest/src/rest-server.ts (the export handler and the CSV/XLSX writers only) + tests in packages/rest. (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Serial constraints cleared: #7912 MERGED (PR #8426) — rest-server.ts is free, verified on origin/main. #8039 is queued behind this card in that file's chain and is not in flight. No dev in flight in this lane.

Maintainer priority. target:v17 and Bug take precedence in this lane (maintainer directive, 2026-08-13), and this is the only dispatchable v17 card here — the other, #7644, is pm:on-hold awaiting a 17.0.0 release, which is a human-only action. It also has a measured downstream deployment blocked on it rather than an internal sweep finding: monthly reconciliation is failing on 17.0.0-rc.6 because exported cross-day rows land in the wrong month.

Premise re-verified on the merged ref, post-#7912

rest-server.ts changed 20 minutes ago, so these were re-measured rather than carried from the card:

• packages/rest/src/export-format.ts:175 — function formatDate(value, withTime)
• :178 / :180 — getUTCFullYear() … getUTCHours(), hardcoded
• :237 formatCellValue, :258 formatRowCells — neither takes a timezone parameter
• ⭐ :66-67 — exportContentDisposition() builds the filename timestamp with getFullYear() / getHours(), i.e. local time

That last one is the sharpest evidence on the card and it survives: one export, two clocks. The filename says the business timezone and the contents say UTC. That is very hard to read as a deliberate design and easy to read as a formatter that was never handed the timezone the rest of the request already knows.

The fix direction (the card's, and it is sound — but verify the seam yourself)

Thread ExecutionContext.timezone into formatRowCells / formatCellValue, and have formatDate take the calendar components in the business timezone via Intl.DateTimeFormat(…, { timeZone }). timezone absent ⇒ keep today's UTC behaviour, so nothing changes for a deployment that never set one.

⚠️ The timezone is already resolved on this path and simply not threaded. The card states resolveExecCtx at the export route hands back an ExecutionContext carrying timezone (platform default → global → tenant cascade). Verify that yourself on the merged tree — it is the one claim the whole fix rests on, the line numbers around it moved today, and if it turns out the export route does not have the timezone in hand, stop and report: the shape of the card changes completely.

Consistency anchor worth checking rather than assuming: autonumber date tokens already render in the ADR-0053 business timezone with UTC as the fallback (RenderAutonumberInput.timezone in @objectstack/spec). If that is still true, this card is bringing the export formatter into line with an existing platform semantic rather than inventing one — which is a much easier change to justify and to review.

Coverage — non-negotiable

• CSV and XLSX, both reproduce and both must be pinned. The card notes XLSX writes a text cell, not a timezone-aware date cell, so a fix that only corrects CSV would leave the reported symptom half-standing.
• The timezone-absent fallback stays UTC — pinned, because that is the backward-compatibility promise.
• ⭐ Pin the cross-day case specifically. The reported harm is not "8 hours off", it is a row moving to the previous month — 2026-08-01 06:00 +08 exported as 2026-07-31 22:00. A test using a mid-day timestamp would pass while the actual customer symptom survived. Use a timestamp that crosses both a day and a month boundary.
• Ablate: revert the threading and show the cross-day case goes red.

Non-negotiables

• Run every build and test as an ordinary foreground Bash call and block on it (raise timeout up to 600000 ms). ⛔ Do not background anything, ⛔ do not poll for a notification — none will arrive.
• ⚠️ packages/rest hides its test layer from tsc. If you add a test file, use explicit .js extensions on relative imports — the package resolves NodeNext, the extensionless spelling used by the older test files is a TS2835, and check:type-check-debt has zero headroom. A PR went red on exactly this today. ⛔ Never raise the ledger; fix the type.
• ⛔ Do not touch the docblock above DATA_RECORD_READ_PARAMS in rest-server.ts — that region is card [rest] GET /data/:object/:id folds no query aliases — the CANONICAL fields spelling is dropped while the alias select works #8039, queued behind you.
• ⛔ Do not edit content/docs/releases/**.
• Changeset required (user-visible behaviour change on a published surface).
• Draft PR, target main, first line Fixes #8373.
• Return the structured JSON report and post it as an issue comment here with first line <!-- os-dev-report -->.

---

Generated by Claude Code