spike: review how the client timezone is passed to the API

未关闭
  • 哪里不对？
#433 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
活跃
技术栈
csharp, javascript, openapi
领域
api, backend-api-design

调研方向

Start by reading the seven named request DTOs and their validators, then trace each endpoint’s handling of the offset and its omission behavior. Compare the web files src/api/journal.ts and src/lib/journal-utils.ts with assistant ApiModels.cs, TaskFlowApiClient.cs and Tools/ for sign or staleness issues. Done means posting the endpoint inventory, option comparison, recommendation and cost, and opening follow-up issues if a refactor is recommended.

由索引模型根据 Issue 内容生成。

描述

tech-debt

Found while reviewing the assistant-builder agent for #400 (piece 8). The client's timezone reaches the API as a bare integer, timezoneOffsetMinutes, and the meaning of that integer is written down almost nowhere. This spike looks at whether the representation should change.

What I found

  • Seven request DTOs carry int? TimezoneOffsetMinutes: AddJournalTodoDto, CarryForwardRequestDto, CreateJournalEntryDto, CreateTaskItemDto, JournalDayQueryDto, PatchTaskItemDto and UpdateTaskItemDto. The validators bound it (CarryForwardRequestDtoValidator says -720 to 840, "UTC-12:00 to UTC+14:00").
  • The sign convention (minutes east of UTC, so UTC-7 is -420) is stated in no code comment on the parameter. The assistant's InputParsing.LocalNow and the web's getTimezoneOffsetMinutes() both produce it, and JavaScript's own Date.getTimezoneOffset() uses the opposite sign (minutes west). The assistant agent file carried the rule as prose, which #400 cuts, so a code comment on InputParsing.LocalNow is the interim fix.
  • The same value is hand-copied into three places: the API DTOs, the web (src/api/journal.ts and src/lib/journal-utils.ts) and the assistant (ApiModels.cs, TaskFlowApiClient.cs, Tools/). About 30 assistant tests assert the exact integer.
  • A single offset cannot describe a zone whose offset changes with the date (daylight saving). The offset sent is the one at the moment of the request, so a date in the past or future can be off by an hour.
  • What happens when the offset is omitted is described in different places in different words, for example "UTC when omitted" in JournalEntriesController and the due-date wording in PatchTaskItemDto, while the carry-forward rule in CLAUDE.md says "no UTC fallback". They may all be consistent; this spike checks.

Scope

  1. Inventory every endpoint that accepts the offset and record, for each, what the server does with it and what it does when the offset is missing.
  2. Check each client (web, assistant) for the sign convention and for any place that sends a stale or inverted value.
  3. Compare these options for how the client's timezone reaches the server:
    • Keep the integer, document it. DTO doc comments, an OpenAPI description, and one shared definition in each client.
    • A single request header or middleware (for example X-Timezone-Offset), so DTOs stop carrying it and the rule is written once.
    • An IANA zone id (for example America/Los_Angeles) converted on the server, which handles daylight saving per date.
    • Anything else the inventory suggests.
  4. For the best option, estimate the change: API, web, assistant, tests, and any migration of stored data (none expected).
  5. Recommend one option and say what it costs.

Acceptance criteria

  1. The inventory table is posted on this issue: each endpoint, what it does with the offset, and its behavior when omitted.
  2. Any place that sends a wrong-signed or stale offset is listed as its own bug, or the issue says none exist.
  3. The three options are compared against the inventory, with a recommendation.
  4. If a refactor is recommended, follow-up issues are opened for it; if not, the issue says what documentation to add instead.

Out of scope

  • The carry-forward behavior itself (#415, #409 and #406 cover journal reliability). This issue is only about how the timezone is represented and passed.
  • Changing any behavior in this spike. It produces a decision and issues.
  • The interim code comment on InputParsing.LocalNow. #400's build makes that edit.
主要语言
C#
星标
1
派生
0
平均合并
2 小时 2 分钟
30 天内合并 PR
98

环境准备

  • 提供 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

nevridge/TaskFlow 的其他 Issue

查看 nevridge/TaskFlow 的全部 Issue

相似的 Issue

更多 C# Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。