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

オープン
  • 何か問題がありますか？
#433 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
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分
マージ済み PR（30日）
98

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

nevridge/TaskFlow のほかの issue

nevridge/TaskFlow の issue をすべて見る

似ている issue

C# の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。