julian
c8a5f4cd68
ROADMAP plus granular task files per phase. Phase 1 (12 tasks + 1.13 device authority) covers Codec 8/8E/16 telemetry ingestion; Phase 2 (6 tasks) covers Codec 12/14 outbound commands; Phase 3 enumerates deferred items.
55 lines
3.3 KiB
Markdown
55 lines
3.3 KiB
Markdown
# Phase 3 — Future / optional
|
||
|
||
Items that are designed-for but not committed. Each could become its own phase if the platform's needs grow that direction. None of these block Phase 1 or Phase 2 — they are clean additions thanks to the layout rules in `docs/wiki/concepts/protocol-adapter.md`.
|
||
|
||
## Candidates
|
||
|
||
### 3.A — Additional vendor adapters
|
||
|
||
**Trigger:** Customer onboards Queclink, Concox, or other GPS hardware.
|
||
|
||
Each new vendor is a new sibling under `src/adapters/`. The shell stays unchanged. Phase 1's [[protocol-adapter]] discipline is the load-bearing property here — `core/` does not import from any specific adapter, so a new one slots in without touching existing code.
|
||
|
||
Estimated scope per vendor: roughly Phase 1 tasks 1.4–1.9 again (framing + codec parsers + fixture suite + tests), but smaller because the shell already exists.
|
||
|
||
### 3.B — UDP transport for Teltonika
|
||
|
||
**Trigger:** Devices configured for UDP, or operational reasons to prefer UDP (lower keepalive cost on cellular).
|
||
|
||
Adds a parallel `udp-server.ts` in `src/core/` that handles the Teltonika UDP envelope (`Length 2B + Packet ID 2B + Not Usable Byte 1B + AVL Packet Header + AVL Data Array`). The codec parsers themselves are unchanged — UDP only changes the framing/transport. ACK format differs (5-byte UDP ack vs. 4-byte TCP record count).
|
||
|
||
Reference: `docs/wiki/concepts/avl-data-format.md` § "UDP envelope".
|
||
|
||
Risk: UDP loses TCP's natural per-session stickiness, so a future Phase 2 over UDP would need a different routing model than the connection registry.
|
||
|
||
### 3.C — Codec 15 (`0x0F`)
|
||
|
||
**Trigger:** FMX6 professional fleet onboards.
|
||
|
||
Codec 15 is one-way device→server with both timestamp and IMEI in every frame, used only on FMX6 devices in RS232 modes. Out of scope for the deployed FMB/FMC/FMM/FMU fleet.
|
||
|
||
Implementation is a new handler in `src/adapters/teltonika/codec/data/codec15.ts` plus a registration in `index.ts`. The handshake skips IMEI exchange because it's in every frame.
|
||
|
||
### 3.D — SMS protocols (Codec 4 + binary SMS)
|
||
|
||
**Trigger:** SMS fallback connectivity becomes a requirement (e.g. devices in cellular-fringe areas).
|
||
|
||
Codec 4 carries 24 GPS positions in one SMS (bit-field compressed); separate binary-SMS protocol carries an AVL data array + IMEI. Both require an SMS gateway integration outside this service.
|
||
|
||
This is large enough to warrant its own service rather than living in `tcp-ingestion/`. Open question for that point: should the SMS gateway publish to the same `telemetry:teltonika` Redis Stream, or a separate one? Probably the same — the [[position-record]] contract is transport-agnostic.
|
||
|
||
### 3.E — Multi-region / NATS or Kafka migration
|
||
|
||
**Trigger:** Multi-region deployment, or single-Redis throughput becomes a real bottleneck.
|
||
|
||
Replace `ioredis` with `@nats-io/nats` or `kafkajs`. The publish interface in `src/core/publish.ts` should be small enough that this is a swap, not a rewrite — design Phase 1's publisher with this in mind.
|
||
|
||
## How items move from here to a real phase
|
||
|
||
When one of these triggers fires:
|
||
|
||
1. Create a new `phase-N-<name>/` folder under `.planning/`.
|
||
2. Promote the relevant section above into a full phase plan with the same task structure as Phase 1/2.
|
||
3. Update the ROADMAP with the new phase row.
|
||
4. Remove the section from this README (or mark it as promoted).
|