77 lines
4 KiB
Markdown
77 lines
4 KiB
Markdown
# Handoff — PON Go iOS
|
||
|
||
Context for the next session/developer. Pairs with [`README.md`](README.md) and
|
||
[`MCMS_API.md`](MCMS_API.md).
|
||
|
||
## Status
|
||
|
||
Feature-complete and (per off-device typecheck + the user's Xcode builds)
|
||
compiling. Screens: Login, Settings, Dashboard (counts, total OLT traffic,
|
||
Health with tappable drill-downs, ONU-state breakdown, detailed-stats +
|
||
auto-refresh toggles), ONU list + detail (Overview with status/firmware+update/
|
||
optical-FEC/UNI/traffic, CPE DHCP, Config raw-JSON tree, Alarms, Logs; reset +
|
||
firmware behind hardened confirms), OLT list + detail (status/uptime/traffic/
|
||
environment/uplink/registration buckets, reset).
|
||
|
||
## Architecture
|
||
|
||
- `AppEnvironment` (`@MainActor @Observable`) owns the active `MCMSConnection`,
|
||
persists the non-secret `APIConfiguration` to UserDefaults, keeps credentials in
|
||
the Keychain, and routes `RootView` (Settings → Login → main `TabView`).
|
||
- Networking core: `APIConfiguration` → `SessionStore`/`APIClient` → repositories.
|
||
Mongo documents are kept as a dynamic `JSONValue` (`APIEnvelope.swift`) and read
|
||
via typed accessors on `MongoDocument` structs (`DeviceModels.swift`) — type the
|
||
fields you use, leave the rest raw.
|
||
- View models are `@MainActor @Observable` classes with a `LoadPhase` + `load()`.
|
||
|
||
## API gotchas (handled in code — don't regress)
|
||
|
||
- **Single-encode URLs.** `APIClient.makeRequest` builds the path with
|
||
`URLComponents.path` (encodes once, keeps `:` in MAC ids raw); `MCMSEndpoint`
|
||
keeps ids RAW. `appendingPathComponent` double-encoded MAC colons → MCMS
|
||
"invalid id". (Verified empirically.)
|
||
- **401 bounces to login; 403 does NOT** — `APIError.requiresReauthentication` is
|
||
401-only (403 is permission/CSRF; re-login won't help). The `onAuthExpired` hook
|
||
flows `APIClient → MCMSConnection → AppEnvironment`.
|
||
- **Writes return `{"status":"success"}` with no `data`** — `decodeEnvelope`
|
||
returns the type's empty value instead of throwing (so login + all writes work).
|
||
- **ONU registration is on OLT-STATE buckets** (`OLTRepository.registrationMap`),
|
||
not ONU-STATE. Parent OLT is `OLT.MAC Address`. Friendly names are `ONU.Name` /
|
||
`OLT.Name` (NOT `Netconf.Name`/`NETCONF.Name`, which default to the id), fetched
|
||
via `projection`.
|
||
- **CPE DHCP** = web helper `GET /api/cpe/onu/<id>/` (versionless, bare
|
||
`[code, cpe…]` array — `APIClient.getRaw`).
|
||
- **Firmware** = Procedure 7 (`FirmwareUpgrade.apply`, unit-tested against a real
|
||
config): GET ONU-CFG → write filename/version into the **inactive** bank → full-
|
||
doc PUT. Inactive-bank only; still test on a spare ONU before production.
|
||
- **Timestamps** are UTC `yyyy-MM-dd HH:mm:ss[.SSSSSS]` with a literal space
|
||
(`MongoTimestamp`, not ISO8601). Uptime = state `Time` − `Online Time`.
|
||
- Everything is `/api/v1` except `/v3/tasks/configs/` (unused). Cookies may be
|
||
`__Host-`-prefixed (`SessionStore` matches either). `/api` is auto-appended to
|
||
the base URL in Settings.
|
||
|
||
## Known real-world notes
|
||
|
||
- One lab box (`mcms.lab.svorka.net`) once sent an illegal `Upgrade: h2` header
|
||
over HTTP/2 that iOS rejects (`-1005`). Fix is server-side (Apache `Protocols
|
||
http/1.1`) or an HTTP/1.1 reverse proxy; iOS has no supported "force HTTP/1.1".
|
||
- The base URL must include `/api`; Settings normalises this.
|
||
|
||
## Verify loop
|
||
|
||
`swiftc -typecheck` against the macOS SDK for the core + view models (see README).
|
||
Tricky SwiftUI bits: compile isolated snippets sans iOS-only modifiers. No iOS SDK
|
||
on the dev machine, so full builds are the user's Xcode step.
|
||
|
||
## Repo split
|
||
|
||
Recommended: consolidate the flat sources + `Assets.xcassets` into the Xcode
|
||
project and git-init that as the iOS repo (with `docs/MCMS_API.md` + the PDFs).
|
||
The included `.gitignore` covers Xcode/Swift build artifacts. The Android app is a
|
||
separate repo (`../mcms_android`), self-contained.
|
||
|
||
## Possible next steps
|
||
|
||
OLT bulk firmware (Procedure 8 task); Swift Charts for PM history; live optical on
|
||
the list rows; richer alarm handling; widen test coverage of the firmware PUT
|
||
against more ONU-CFG shapes.
|