Sync ROADMAP statuses with landed work; mark 1.10/1.12/1.13 as paused

Tasks 1.1-1.9 marked done with their landing commit SHAs. Tasks 1.10
(observability), 1.12 (production hardening), and 1.13 (device
authority) marked paused with explicit resume triggers — pilot
deployment on real Teltonika hardware takes priority. Task 1.11
remains as next, in slimmed form for the pilot (no /readyz healthcheck
since the metrics endpoint is part of paused 1.10).
This commit is contained in:
2026-04-30 16:48:55 +02:00
parent c33c7a4f6b
commit 90d6a73a60
13 changed files with 38 additions and 28 deletions
+26 -16
View File
@@ -41,26 +41,36 @@ These rules govern every task. Any deviation must be discussed and documented as
### Phase 1 — Inbound telemetry (Codec 8, 8E, 16) ### Phase 1 — Inbound telemetry (Codec 8, 8E, 16)
**Status:** ⬜ Not started **Status:** 🟨 In progress (core implementation done; observability + hardening + device authority paused for pilot test)
**Outcome:** A production-ready Node.js TCP server ingesting Teltonika telemetry from any FMB/FMC/FMM/FMU device, publishing normalized `Position` records to Redis Streams, with full observability and CI/CD via Gitea. **Outcome:** A production-ready Node.js TCP server ingesting Teltonika telemetry from any FMB/FMC/FMM/FMU device, publishing normalized `Position` records to Redis Streams, with full observability and CI/CD via Gitea.
[**See `phase-1-telemetry/README.md`**](./phase-1-telemetry/README.md) [**See `phase-1-telemetry/README.md`**](./phase-1-telemetry/README.md)
| # | Task | Status | | # | Task | Status | Landed in |
|---|------|--------| |---|------|--------|-----------|
| 1.1 | [Project scaffold](./phase-1-telemetry/01-project-scaffold.md) | | | 1.1 | [Project scaffold](./phase-1-telemetry/01-project-scaffold.md) | 🟩 | `1e9219d` |
| 1.2 | [Core shell & framing types](./phase-1-telemetry/02-core-shell.md) | | | 1.2 | [Core shell & framing types](./phase-1-telemetry/02-core-shell.md) | 🟩 | `1e9219d` |
| 1.3 | [Configuration & logging](./phase-1-telemetry/03-config-and-logging.md) | | | 1.3 | [Configuration & logging](./phase-1-telemetry/03-config-and-logging.md) | 🟩 | `1e9219d` |
| 1.4 | [Teltonika framing layer (envelope, CRC, handshake)](./phase-1-telemetry/04-teltonika-framing.md) | | | 1.4 | [Teltonika framing layer (envelope, CRC, handshake)](./phase-1-telemetry/04-teltonika-framing.md) | 🟩 | `1e9219d` |
| 1.5 | [Codec 8 parser](./phase-1-telemetry/05-codec-8.md) | | | 1.5 | [Codec 8 parser](./phase-1-telemetry/05-codec-8.md) | 🟩 | `381287b` |
| 1.6 | [Codec 8 Extended parser (incl. NX)](./phase-1-telemetry/06-codec-8-extended.md) | | | 1.6 | [Codec 8 Extended parser (incl. NX)](./phase-1-telemetry/06-codec-8-extended.md) | 🟩 | `381287b` |
| 1.7 | [Codec 16 parser (incl. Generation Type)](./phase-1-telemetry/07-codec-16.md) | | | 1.7 | [Codec 16 parser (incl. Generation Type)](./phase-1-telemetry/07-codec-16.md) | 🟩 | `381287b` |
| 1.8 | [Redis Streams publisher & main wiring](./phase-1-telemetry/08-redis-publisher.md) | | | 1.8 | [Redis Streams publisher & main wiring](./phase-1-telemetry/08-redis-publisher.md) | 🟩 | `af06973` |
| 1.9 | [Fixture suite & testing strategy](./phase-1-telemetry/09-fixture-suite.md) | | | 1.9 | [Fixture suite & testing strategy](./phase-1-telemetry/09-fixture-suite.md) | 🟩 | `381287b` |
| 1.10 | [Observability (Prometheus metrics)](./phase-1-telemetry/10-observability.md) | | | 1.10 | [Observability (Prometheus metrics)](./phase-1-telemetry/10-observability.md) | ⏸ | *deferred — see below* |
| 1.11 | [Dockerfile & Gitea workflow](./phase-1-telemetry/11-dockerfile-and-ci.md) | ⬜ | | 1.11 | [Dockerfile & Gitea workflow](./phase-1-telemetry/11-dockerfile-and-ci.md) | ⬜ | *next, in slim form for the pilot* |
| 1.12 | [Production hardening](./phase-1-telemetry/12-production-hardening.md) | | | 1.12 | [Production hardening](./phase-1-telemetry/12-production-hardening.md) | ⏸ | *deferred — see below* |
| 1.13 | [Device authority (Redis allow-list refresher)](./phase-1-telemetry/13-device-authority.md) | | | 1.13 | [Device authority (Redis allow-list refresher)](./phase-1-telemetry/13-device-authority.md) | ⏸ | *deferred — see below* |
#### Deferred (resume after the real-device pilot test)
These three tasks are paused so we can get the service onto real hardware as fast as possible. They are paused, not cancelled — each must be completed before the service is considered production-ready.
- **1.10 Observability (Prometheus metrics).** Tracking via the placeholder `Metrics` interface for now. **Resume trigger:** as soon as the pilot is generating real traffic and we want to measure it, *or* before any second instance is deployed (without metrics, "consumer lag" and "unknown codec" alerts cannot fire).
- **1.12 Production hardening.** Graceful shutdown is a stub today; uncaught-exception handlers are minimal. **Resume trigger:** before the pilot graduates to "always-on" or before any deployment that does rolling restarts. Acceptable for a manual pilot where we can stop/start the process by hand.
- **1.13 Device authority (Redis allow-list refresher).** Default `AllowAllAuthority` accepts every IMEI; observability of `known | unknown` is moot until 1.10 lands. **Resume trigger:** when Directus has a `devices` collection publishing the allow-list to Redis, or when the operational picture demands rejecting unknown IMEIs (`STRICT_DEVICE_AUTH=true`).
When resuming any of these, change the status from ⏸ back to ⬜ or 🟨 here and in the task file's status badge, and clear the deferral note in the task file.
### Phase 2 — Outbound commands (Codec 12, 14) ### Phase 2 — Outbound commands (Codec 12, 14)
@@ -1,7 +1,7 @@
# Task 1.1 — Project scaffold # Task 1.1 — Project scaffold
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `1e9219d`
**Depends on:** None **Depends on:** None
**Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` § Project location and layout **Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` § Project location and layout
+1 -1
View File
@@ -1,7 +1,7 @@
# Task 1.2 — Core shell & framing types # Task 1.2 — Core shell & framing types
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `1e9219d`
**Depends on:** 1.1 **Depends on:** 1.1
**Wiki refs:** `docs/wiki/concepts/protocol-adapter.md`, `docs/wiki/concepts/codec-dispatch.md`, `docs/wiki/concepts/position-record.md` **Wiki refs:** `docs/wiki/concepts/protocol-adapter.md`, `docs/wiki/concepts/codec-dispatch.md`, `docs/wiki/concepts/position-record.md`
@@ -1,7 +1,7 @@
# Task 1.3 — Configuration & logging # Task 1.3 — Configuration & logging
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `1e9219d`
**Depends on:** 1.1 **Depends on:** 1.1
**Wiki refs:** `docs/wiki/sources/gps-tracking-architecture.md` § Deployment topology, § Observability **Wiki refs:** `docs/wiki/sources/gps-tracking-architecture.md` § Deployment topology, § Observability
@@ -1,7 +1,7 @@
# Task 1.4 — Teltonika framing layer # Task 1.4 — Teltonika framing layer
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `1e9219d`
**Depends on:** 1.2 **Depends on:** 1.2
**Wiki refs:** `docs/wiki/concepts/avl-data-format.md` (envelope, IMEI handshake), `docs/wiki/concepts/codec-dispatch.md`, `docs/wiki/sources/teltonika-data-sending-protocols.md` **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` (envelope, IMEI handshake), `docs/wiki/concepts/codec-dispatch.md`, `docs/wiki/sources/teltonika-data-sending-protocols.md`
+1 -1
View File
@@ -1,7 +1,7 @@
# Task 1.5 — Codec 8 parser # Task 1.5 — Codec 8 parser
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `381287b`
**Depends on:** 1.4, 1.9 (fixture infra) **Depends on:** 1.4, 1.9 (fixture infra)
**Wiki refs:** `docs/wiki/concepts/avl-data-format.md` § Codec 8, `docs/wiki/sources/teltonika-data-sending-protocols.md` § Codec 8 **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` § Codec 8, `docs/wiki/sources/teltonika-data-sending-protocols.md` § Codec 8
@@ -1,7 +1,7 @@
# Task 1.6 — Codec 8 Extended parser # Task 1.6 — Codec 8 Extended parser
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `381287b`
**Depends on:** 1.4, 1.5 (shared GPS Element / timestamp helpers), 1.9 **Depends on:** 1.4, 1.5 (shared GPS Element / timestamp helpers), 1.9
**Wiki refs:** `docs/wiki/concepts/avl-data-format.md` § Codec 8 Extended, `docs/wiki/sources/teltonika-data-sending-protocols.md` § Codec 8 Extended **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` § Codec 8 Extended, `docs/wiki/sources/teltonika-data-sending-protocols.md` § Codec 8 Extended
+1 -1
View File
@@ -1,7 +1,7 @@
# Task 1.7 — Codec 16 parser # Task 1.7 — Codec 16 parser
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `381287b`
**Depends on:** 1.4, 1.5 (shared helpers), 1.9 **Depends on:** 1.4, 1.5 (shared helpers), 1.9
**Wiki refs:** `docs/wiki/concepts/avl-data-format.md` § Codec 16, `docs/wiki/sources/teltonika-data-sending-protocols.md` § Codec 16 **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` § Codec 16, `docs/wiki/sources/teltonika-data-sending-protocols.md` § Codec 16
@@ -1,7 +1,7 @@
# Task 1.8 — Redis Streams publisher & main wiring # Task 1.8 — Redis Streams publisher & main wiring
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** 🟩 Done **Status:** 🟩 Done — landed in commit `af06973`
**Depends on:** 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 **Depends on:** 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
**Wiki refs:** `docs/wiki/entities/redis-streams.md`, `docs/wiki/concepts/position-record.md` **Wiki refs:** `docs/wiki/entities/redis-streams.md`, `docs/wiki/concepts/position-record.md`
@@ -1,7 +1,7 @@
# Task 1.9 — Fixture suite & testing strategy # Task 1.9 — Fixture suite & testing strategy
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** 🟩 Done — landed in commit `381287b`
**Depends on:** 1.1 **Depends on:** 1.1
**Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` § 5.6, `docs/wiki/sources/teltonika-data-sending-protocols.md` **Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` § 5.6, `docs/wiki/sources/teltonika-data-sending-protocols.md`
@@ -1,7 +1,7 @@
# Task 1.10 — Observability (Prometheus metrics) # Task 1.10 — Observability (Prometheus metrics)
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** ⏸ Paused — deferred until after the real-device pilot test. See ROADMAP.md "Deferred" section for resume triggers. The placeholder `Metrics` interface in `src/core/types.ts` is what code currently uses; this task replaces it with `prom-client` and adds the `/metrics`, `/healthz`, `/readyz` HTTP endpoints.
**Depends on:** 1.2, 1.3 **Depends on:** 1.2, 1.3
**Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` § 7. Observability, `docs/wiki/sources/gps-tracking-architecture.md` § 7.4 **Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` § 7. Observability, `docs/wiki/sources/gps-tracking-architecture.md` § 7.4
@@ -1,7 +1,7 @@
# Task 1.12 — Production hardening # Task 1.12 — Production hardening
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started **Status:** ⏸ Paused — deferred until after the real-device pilot test. See ROADMAP.md "Deferred" section for resume triggers. `installGracefulShutdown` exists as a stub from task 1.8; this task fully implements signal handling, drain timeouts, unhandled-rejection handlers, and writes OPERATIONS.md. **Resume before any always-on deployment or rolling-restart workflow.**
**Depends on:** 1.8, 1.10, 1.11 **Depends on:** 1.8, 1.10, 1.11
**Wiki refs:** `docs/wiki/concepts/failure-domains.md` **Wiki refs:** `docs/wiki/concepts/failure-domains.md`
@@ -1,7 +1,7 @@
# Task 1.13 — Device authority (Redis allow-list refresher) # Task 1.13 — Device authority (Redis allow-list refresher)
**Phase:** 1 — Inbound telemetry **Phase:** 1 — Inbound telemetry
**Status:** ⬜ Not started (deferrable — can ship after the rest of Phase 1) **Status:** ⏸ Paused deferred until after the real-device pilot test, AND until Directus has a `devices` collection publishing the allow-list to Redis. See ROADMAP.md "Deferred" section. The `DeviceAuthority` seam exists with `AllowAllAuthority` (default, in `src/adapters/teltonika/device-authority.ts`); this task adds `RedisAllowListAuthority`.
**Depends on:** 1.4 (DeviceAuthority seam), 1.10 (metrics) **Depends on:** 1.4 (DeviceAuthority seam), 1.10 (metrics)
**Wiki refs:** `docs/wiki/concepts/plane-separation.md`, `docs/wiki/entities/directus.md`, `docs/wiki/entities/redis-streams.md` **Wiki refs:** `docs/wiki/concepts/plane-separation.md`, `docs/wiki/entities/directus.md`, `docs/wiki/entities/redis-streams.md`