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

Abierto
  • ¿Algo no está bien?
#433 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
csharp, javascript, openapi
Área
api, backend-api-design

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
C#
Estrellas
1
Forks
0
Merge medio
2 h 2 min
PR fusionados (30 d)
98

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de nevridge/TaskFlow

Todos los issues de nevridge/TaskFlow

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.