dandri/trail-mate
1
0
Fork 0
mirror of https://github.com/vicliu624/trail-mate.git synced 2026-08-22 10:39:45 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/cardputer-zero
trail-mate/docs/TEAM.md
T
liu weikai 6fbcbce48c feat: team tracker
2026-02-04 11:06:53 +08:00

2875 lines
72 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 你这个 TEAM 业务到底在做什么（我现在能总结到“可写 TeamEvent”的程度）
## 1) Team 的定义（产品级一句话）
**Team = 临时形成、目标驱动、随时解散的户外行动单元。**
它不是“群聊”，也不是“普通位置共享”，而是让一小群人在无网络环境下持续回答三件事：
1. **我们是否还在一起**（队伍是否分散/掉队/走偏）
2. **接下来要做什么**（集合、等待、求助等“行动共识”）
3. **有没有人出问题**（静止、失联、电量低、SOS）
---
## 2) Team 的核心能力（你已经确定的）
### A. 临时组队（Create / Join / Disband）
* Leader 一键建队
* 成员通过短码/QR 拿到 **TeamKey** 加入
* Team 可以随时解散（解散即密钥销毁）
**这一套你已经做成状态机：Create → Active → Rotate → Disband**
---
### B. 强隐私位置共享（你的差异化关键）
你明确在意：
> **位置广播出去后，只有 Team 成员能解析成功；即便 Team channel 配置外传，也看不懂。**
因此你采用两层保护：
* L1：Meshtastic **Channel** 加密（CH-ENC）
* L2：应用层 **E2EE**（TeamKey 派生的 PosKey/WpKey，TeamEncrypted Envelope）
并且你倾向新增自己的 PortNum：
* `TEAM_POSITION_APP`
* `TEAM_WAYPOINT_APP`
* `TEAM_TRACK_APP`
* 管理类 `TEAM_MGMT_APP`
---
### C. Team 内的“行动指令”（Preset / Command）
你提出的差异化：
* 向队友发 **预设指令**（集合、等待、求助…）
* 指令携带必要参数（例如集合地点 waypoint）
* 指令是“事件”，不靠打字聊天
> 注意：你前面没要求我把它做成完整协议，但你已经明确这是 Team 的重要业务能力。
---
### D. Team 生命周期复盘（你现在要做的）
你希望**整个组队过程可复盘**，包括生命周期中所有事件落地。
所以我们引入：
* SD 日志（append-only）
* LogRecord（AEAD + CRC）
* snapshot 加速（可选）
* LogKey（独立于 TeamKey，可配置是否保留）
---
## 3) Team 生命周期里“会发生哪些事件”（这直接决定 TeamEvent）
为了写 `TeamEvent` 的 protobuf，你需要先承认：
**TeamEvent 不等于“所有无线包”**，而是**业务层发生的事情**，能用于复盘与解释行为。
你当前业务可以归纳为 5 类事件：
### 1) 生命周期事件（Lifecycle）
* Team 被创建（Leader 本地）
* 广播可发现（ADVERTISE）
* 有人请求加入（JOIN_REQUEST）
* Leader 接受并下发配置（JOIN_ACCEPT）
* 成员确认入队（JOIN_CONFIRM）
* Team 状态同步（TEAM_STATUS）
* 密钥轮换（KEY_ROTATE）
* 解散/离开（DISBAND / LEAVE）
这些事件用于回答：
* “队伍什么时候开始/结束”
* “谁在队里、什么时候加入/离开”
* “什么时候换过密钥、为什么换”
---
### 2) 位置与轨迹事件（Telemetry）
* 收到某成员位置（POSITION_RX）
* 收到航点/集合点（WAYPOINT_RX）
* 收到轨迹批量点（TRACK_RX）
这些事件用于复盘：
* 人在什么时候到过哪里
* 队伍是否分散、何时重新聚拢
> 位置事件会有降采样策略，否则日志爆炸。
---
### 3) 指令事件（Command）
* 集合指令（含地点 waypoint）
* 等待/暂停
* 求助（SOS，含位置/严重级别）
这些事件用于复盘：
* “谁下达过行动共识”
* “队伍如何响应”
---
### 4) 连接与可见性事件（Presence/Health）
这类你在产品目标里明确需要，但我们之前没有把它细化成协议字段，现在总结出来：
* 某成员“暂时不可见”（超时没收到位置）
* 恢复可见
* 电量低（如果你决定上报）
* 静止过久（如果你决定做本机推断事件）
这些事件用于复盘：
* “为什么当时地图上看不到人”
* “掉队是不是因为设备没电/失联”
> 这类事件可以是“本机推断”，不一定来自无线包。
---
### 5) 安全/异常事件（Security/Diagnostics）
你要做强隐私承诺，就必须能复盘“失败原因”，否则用户只会觉得 bug。
* 解密失败（DECRYPT_FAIL）
* key_id 不匹配（KEY_MISMATCH）
* 重放丢弃（REPLAY_DROP）
* 包格式错误（DECODE_FAIL）
这些事件用于复盘：
* “当时收到了包但没显示”的原因
---
## 4) 我现在对你 TEAM 业务的总结边界（我确定 vs 我不会擅自假设）
### 我已经可以确定的（来自你明确提出并反复确认的）
* Team 是临时行动单元，有 Create/Join/Disband
* Team 内位置共享 + waypoint
* 强隐私：channel 隔离 + 应用层 E2EE
* 需要记录整个生命周期事件并可复盘
* 你愿意新增自定义 PortNum（TEAM_*_APP）
### 我不会擅自补的（你没冻结）
* 指令种类到底有哪些、每种指令带哪些参数（我能提建议，但需要你确认）
* 成员健康字段是否要上报（电量、能力、角色）
* 是否要求“全队一致复盘”（你目前更像本地复盘/Leader复盘）
---
# Team 建队 / 加入 报文交互流程（强隐私版本）
## 参与方
```
L = Leader / 建队者设备
M = Member / 队员设备
O = Others / 旁观设备（非 Team 成员）
```
## 信道
```
CH0 = 默认公共频道（Primary Channel）
CHT = Team 私有频道（新建 / 分配的 channel index）
```
## 安全层
```
CH-ENC = Meshtastic 按 Channel 的链路层加密
E2EE = TeamKey 派生的应用层端到端加密
（Envelope: TeamEncrypted）
```
---
## 总览：时序线图（ASCII）
```
时间 ↓
L (Leader) M (Member) O (Others)
────────────────────────────────────────────────────────────────────────
(0) 本地建队（无报文）
L: 生成 TeamKey
L: TeamId = Trunc(Hash(TeamKey))
L: 选择 / 创建 CHT
L: ChannelPSK = KDF(TeamKey, "channel-psk")
L: MgmtKey = KDF(TeamKey, "mgmt")
L: PosKey = KDF(TeamKey, "pos")
L: WpKey = KDF(TeamKey, "wp")
────────────────────────────────────────────────────────────────────────
(1) Team 可被“发现”（不泄密）
CH0
L ─────── TEAM_ADVERTISE ───────▶ *
{ team_id, join_hint?, channel_index?, nonce/ts }
O: 只能知道“附近有一个 Team”
无法获得任何密钥或位置
────────────────────────────────────────────────────────────────────────
(2) 队员请求加入（无密钥）
CH0
M ───── TEAM_JOIN_REQUEST ─────▶ L
{ team_id, member_pub?, nonce/ts }
────────────────────────────────────────────────────────────────────────
(3) Leader 接受加入并下发 Team 配置
CH0
L ───── TEAM_JOIN_ACCEPT ─────▶ M
{
team_id,
payload = E2EE(MgmtKey, {
channel_index = CHT,
channel_psk = ChannelPSK,
key_id = current_key_id,
team_params? (freq / precision / timeout)
}),
nonce/ts
}
注：
- 此时 M **必须已经通过 UI 获得 TeamKey**
（短码 / QR / 近距离方式）
- 否则无法解密 MgmtKey / payload
────────────────────────────────────────────────────────────────────────
(4) 队员本地切换到 Team
M: 保存 TeamKey
M: 派生 MgmtKey / PosKey / WpKey
M: 保存 CHT + ChannelPSK
M: 切换到 CHT
────────────────────────────────────────────────────────────────────────
(5) 入队确认（推荐）
CHT (CH-ENC)
M ───── TEAM_JOIN_CONFIRM ─────▶ L
{
team_id,
payload = E2EE(MgmtKey, {
ok,
capabilities?,
battery?
}),
nonce/seq
}
────────────────────────────────────────────────────────────────────────
(6) Team 状态同步（可选）
CHT (CH-ENC)
L ─────── TEAM_STATUS ───────▶ Team
{
team_id,
payload = E2EE(MgmtKey, {
member_list_hash,
key_id,
team_params
}),
nonce/seq
}
────────────────────────────────────────────────────────────────────────
(7) Team 内位置共享（核心）
CHT (CH-ENC)
Each Member ── TEAM_POSITION_APP ──▶ Team
payload = TeamEncrypted {
team_id,
key_id,
nonce,
ciphertext = AEAD(
PosKey,
protobuf(meshtastic_Position),
aad = header
)
}
Team 外成员：
- 即便拿到 CHT + ChannelPSK
- 只能解 CH-ENC
- 无 TeamKey / PosKey → 无法解密位置
```
---
## 关键语义说明（非常重要）
### 1️⃣ 为什么 **TEAM_ADVERTISE** 不包含密钥
这是**“发现”而不是“加入”**：
* 让人知道「附近有一个 Team」
* 但不授予任何能力
* 防止被动监听就获得权限
---
### 2️⃣ 为什么 **TeamKey 不通过无线明文传播**
这是你“强隐私承诺”的核心：
* TeamKey **只通过 UI 侧渠道**传播（短码 / QR / 近距）
* 无线中只传播 **TeamKey 派生物**
* 即使频道配置外传，也无法逆推出 TeamKey
---
### 3️⃣ 为什么要分 **ChannelPSK / MgmtKey / PosKey**
这是“可演化设计”：
* ChannelPSK：只管“这包是谁能收到”
* MgmtKey：管成员管理 / 参数
* PosKey / WpKey：管位置 / 航点
👉 未来你可以做到：
* 换位置密钥 ≠ 踢人
* 换管理密钥 ≠ 影响历史数据
---
### 4️⃣ 为什么要 **TEAM_JOIN_CONFIRM**
不是为了安全，是为了**产品可感知性**：
* Leader 知道谁真的成功入队
* UI 能显示“成员已就绪”
* 后续 Team 状态才可信
---
## MVP 与增强项划分（帮你控复杂度）
### MVP 必须（第一版就该有）
* (0) 本地建队 + TeamKey 派生
* (1) TEAM_ADVERTISE
* UI 侧 TeamKey 输入 / 扫码
* (3) TEAM_JOIN_ACCEPT
* (4) 切换到 CHT
* (7) TEAM_POSITION_APP（E2EE）
### 可选增强（后续再加）
* member_pub + 更强密钥交换
* TEAM_JOIN_CONFIRM
* TEAM_STATUS
* key rotation / key_id 更新
* 防重放窗口优化
---
# Team Management Protocol
## Message Definitions (Protobuf-Level)
---
## 公共约定（适用于所有 Team 报文）
### Team Identity
* **TeamKey**
* 高熵随机生成
* 仅通过 UI 侧（短码 / QR / 近距）分发
* **MUST NOT** 通过无线明文传播
* **team_id**
* 定义：`Trunc(Hash(TeamKey))`
* 用途：标识 Team，而不泄露 TeamKey
* **MUST** 在所有 Team 相关报文中出现
---
### 加密层级
* **CH-ENC**：Meshtastic Channel 加密
* **E2EE**：应用层 Team 加密（AEAD）
---
### TeamEncrypted Envelope（通用）
> 用于所有 E2EE payload（位置 / 管理 / 状态）
| 字段 | 类型 | 级别 | 说明 |
| ---------- | ------ | ---- | ------------ |
| version | uint32 | MUST | Envelope 版本 |
| team_id | bytes | MUST | Team 标识 |
| key_id | uint32 | MUST | 当前密钥版本 |
| nonce | bytes | MUST | 每包唯一，用于 AEAD |
| ciphertext | bytes | MUST | AEAD 加密后的数据 |
| aad_flags | uint32 | MAY | AAD 类型标识 |
---
## 1. TEAM_ADVERTISE
**用途**：让 Team 可被“发现”，不授予任何能力
* **信道**：CH0
* **加密**：可明文或 CH0 加密
* **PortNum**：`TEAM_MGMT_APP`
### 字段表
| 字段 | 类型 | 级别 | 说明 |
| ------------- | ------ | ---- | ---------------- |
| team_id | bytes | MUST | Team 标识 |
| join_hint | uint32 | MAY | 加入提示（需确认 / 有效期等） |
| channel_index | uint32 | MAY | Team Channel 索引 |
| expires_at | uint64 | MAY | 广告过期时间 |
| nonce | bytes | MUST | 防重放 |
### 语义规则
* **MUST NOT** 包含任何密钥材料
* **MUST NOT** 泄露位置或成员信息
* **MAY** 周期性广播
---
## 2. TEAM_JOIN_REQUEST
**用途**：队员请求加入 Team（无密钥）
* **信道**：CH0
* **PortNum**：`TEAM_MGMT_APP`
### 字段表
| 字段 | 类型 | 级别 | 说明 |
| ------------ | ------ | ---- | ----------- |
| team_id | bytes | MUST | 目标 Team |
| member_pub | bytes | MAY | 公钥（增强密钥交换用） |
| capabilities | uint32 | MAY | 能力标识 |
| nonce | bytes | MUST | 防重放 |
### 语义规则
* **MUST NOT** 包含 TeamKey
* **MAY** 被 Leader 拒绝（无响应）
---
## 3. TEAM_JOIN_ACCEPT
**用途**：Leader 接受成员并下发 Team 配置
* **信道**：CH0
* **PortNum**：`TEAM_MGMT_APP`
* **加密**：E2EE（MgmtKey）
### Payload（解密后结构）
| 字段 | 类型 | 级别 | 说明 |
| ------------- | ---------- | ---- | ------------ |
| channel_index | uint32 | MUST | Team Channel |
| channel_psk | bytes | MUST | Channel PSK |
| key_id | uint32 | MUST | 当前密钥版本 |
| team_params | TeamParams | MAY | 行为参数 |
### 外层字段表
| 字段 | 类型 | 级别 | 说明 |
| ------- | ------------- | ---- | ------- |
| team_id | bytes | MUST | Team 标识 |
| payload | TeamEncrypted | MUST | E2EE 封装 |
| nonce | bytes | MUST | 防重放 |
### 语义规则
* 接收方 **MUST** 已拥有 TeamKey
* 解密失败 **MUST** 丢弃
* **MUST NOT** 在 TeamKey 未确认前应用配置
---
## 4. TEAM_JOIN_CONFIRM
**用途**：成员确认已成功入队
* **信道**：CHT
* **PortNum**：`TEAM_MGMT_APP`
* **加密**：CH-ENC + E2EE（MgmtKey）
### Payload（解密后）
| 字段 | 类型 | 级别 | 说明 |
| ------------ | ------ | ---- | ----- |
| ok | bool | MUST | 加入成功 |
| capabilities | uint32 | MAY | 能力声明 |
| battery | uint32 | MAY | 电量百分比 |
---
## 5. TEAM_STATUS
**用途**：同步 Team 当前状态
* **信道**：CHT
* **PortNum**：`TEAM_MGMT_APP`
* **加密**：CH-ENC + E2EE（MgmtKey）
### Payload（解密后）
| 字段 | 类型 | 级别 | 说明 |
| ---------------- | ---------- | ---- | ------ |
| member_list_hash | bytes | MUST | 成员列表摘要 |
| key_id | uint32 | MUST | 当前密钥版本 |
| team_params | TeamParams | MAY | 当前参数 |
---
## 6. TEAM_POSITION_APP
**用途**：Team 内位置共享（强隐私）
* **信道**：CHT
* **PortNum**：`TEAM_POSITION_APP`
* **加密**：CH-ENC + E2EE（PosKey）
### Payload（E2EE 明文结构）
| 字段 | 类型 | 级别 | 说明 |
| --------------- | ------------------- | ---- | ---- |
| position | meshtastic_Position | MUST | 位置数据 |
| precision_level | uint32 | MAY | 精度等级 |
| timestamp | uint64 | MUST | 位置时间 |
### 外层（TeamEncrypted）
| 字段 | 类型 | 级别 | 说明 |
| ---------- | ------ | ---- | ------- |
| team_id | bytes | MUST | Team 标识 |
| key_id | uint32 | MUST | 位置密钥版本 |
| nonce | bytes | MUST | 每包唯一 |
| ciphertext | bytes | MUST | AEAD 密文 |
---
## 7. TEAM_WAYPOINT_APP
**用途**：Team 内航点共享
* 与 `TEAM_POSITION_APP` 完全一致
* 使用 `WpKey` 解密
* 明文结构为 `meshtastic_Waypoint`
---
## 8. TEAM_TRACK_APP
**用途**：Team 内轨迹批量点共享（固定间隔）
* 与 `TEAM_POSITION_APP` 完全一致（E2EE PosKey）
* 明文结构为 `TeamTrackMessage`（自定义轻量编码）
* 轨迹点不带单点时间戳，时间由 `start_ts + i * interval_s` 推导
* `valid_mask` 用于标记每个点是否有效（无 fix 时可置 0）
* 单包最多 20 个点
* **发送端建议**：在队伍 keys 就绪后启动 10 分钟采样窗口；每 30 秒采样一次，共 20 点；窗口内若全部点无效则不发包
* **接收端落盘**：`/team/<team_dir>/tracks/<member_id>.gpx`（GPX 1.1，增量追加 `<trkpt>`）
### Payload（E2EE 明文结构）
| 字段 | 类型 | 级别 | 说明 |
| ---------- | -------------------------------- | ---- | ---- |
| version | uint8 | MUST | 版本 |
| start_ts | uint32 | MUST | 起始时间（epoch 秒） |
| interval_s | uint16 | MUST | 采样间隔（秒） |
| count | uint8 | MUST | 点数（<= 20） |
| valid_mask | uint32 | MUST | 点有效性位图（bit i 对应第 i 个点） |
| points | (lat_e7 int32, lon_e7 int32) * N | MUST | 经纬度（E7） |
---
## 9. MUST / SHOULD / MAY 总结（Conformance Checklist）
### MUST
* TeamKey **不得**通过无线明文传播
* 所有 Team 数据 **必须**包含 team_id
* 所有 E2EE payload **必须**使用 AEAD
* nonce **必须** 唯一（防重放）
* 解散 Team 时 **必须** 丢弃所有派生密钥
### SHOULD
* 使用独立的 PosKey / WpKey
* 支持 key_id 轮换
* JOIN_CONFIRM / TEAM_STATUS 用于 UI 同步
### MAY
* 使用 member_pub 做更强密钥交换
* 支持权限分级
* 统一 payload 长度以降低关联风险
---
## 协议一句话定义（可写在文件头）
> **Team 协议定义了一种临时、目标驱动的加密协作单元，其安全边界以 TeamKey 为核心，而非无线信道。**
---
## 目标：你要对用户承诺什么
**隐私承诺（你可以写进 PRD / README）：**
1. **只有 Team 成员能解读 Team 位置与航点**（即便别人拿到频道配置/PSK，也无法解密）
2. **Team 解散后内容不可恢复**（密钥丢弃）
3. **外人无法从包内容推断成员位置**（密文 + 随机化 + 防重放）
---
好，这一步我们把 **Team 的一生**画清楚。
不是“功能流程图”，而是**状态机**——**什么时候处在什么状态、因为什么事件发生跃迁、跃迁时必须做什么**。
下面这张 **ASCII 状态机图**，你可以直接放进协议文档或 PRD。
---
# Team 生命周期状态机（State Machine）
```
┌─────────────────────────┐
│ (Idle) │
│ No Active Team │
└───────────┬─────────────┘
│
Create Team │ (UI action)
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CREATE │
│ │
│ Entry actions (local only): │
│ - Generate TeamKey (high entropy) │
│ - Derive team_id = Trunc(Hash(TeamKey)) │
│ - Allocate / select Team Channel (CHT) │
│ - Derive keys: │
│ ChannelPSK = KDF(TeamKey, "channel-psk") │
│ MgmtKey = KDF(TeamKey, "mgmt") │
│ PosKey = KDF(TeamKey, "pos") │
│ WpKey = KDF(TeamKey, "wp") │
│ │
│ Exit condition: │
│ - Leader confirms creation │
└───────────┬─────────────────────────────────────────────────┘
│
│ TEAM_ADVERTISE (CH0)
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ACTIVE │
│ │
│ Team exists and is operational │
│ │
│ Ongoing behaviors: │
│ - Broadcast TEAM_ADVERTISE (CH0, optional) │
│ - Accept TEAM_JOIN_REQUEST (CH0) │
│ - Send TEAM_JOIN_ACCEPT (CH0, E2EE MgmtKey) │
│ - Operate on Team Channel (CHT): │
│ * TEAM_JOIN_CONFIRM │
│ * TEAM_STATUS │
│ * TEAM_POSITION_APP (E2EE PosKey) │
│ * TEAM_WAYPOINT_APP (E2EE WpKey) │
│ * TEAM_TRACK_APP (E2EE PosKey) │
│ │
│ Valid transitions: │
│ - Rotate keys │
│ - Disband team │
└───────────┬───────────────────────┬─────────────────────────┘
│ │
│ Rotate Team Key │ Disband Team
│ (Leader action) │ (Leader or policy)
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ ROTATE │
│ │
│ Purpose: │
│ - Mitigate key leakage │
│ - Exclude lost / untrusted members │
│ │
│ Entry actions (Leader): │
│ - Increment key_id │
│ - Generate new subkeys: │
│ MgmtKey', PosKey', WpKey' │
│ │
│ Protocol actions: │
│ - Broadcast key update via TEAM_STATUS (E2EE MgmtKey) │
│ - Optionally re-issue TEAM_JOIN_ACCEPT to valid members │
│ │
│ Member behavior: │
│ - Switch to new key_id │
│ - Drop packets with old key_id │
│ │
│ Exit condition: │
│ - All active members synced OR timeout │
└───────────┬─────────────────────────────────────────────────┘
│
│ Rotation complete
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ACTIVE │
│ (with new key_id) │
└─────────────────────────────────────────────────────────────┘
(from ACTIVE or ROTATE)
│
│ Disband Team
│
▼
┌─────────────────────────────────────────────────────────────┐
│ DISBAND │
│ │
│ Entry actions (Leader): │
│ - Broadcast TEAM_END / final TEAM_STATUS (optional) │
│ │
│ Mandatory local actions (ALL members): │
│ - Immediately discard: │
│ * TeamKey │
│ * ChannelPSK │
│ * MgmtKey / PosKey / WpKey │
│ - Stop all Team broadcasts │
│ - Leave Team Channel (CHT) │
│ │
│ Exit condition: │
│ - Return to Idle │
└───────────┬─────────────────────────────────────────────────┘
│
│
▼
┌─────────────────────────┐
│ (Idle) │
│ No Active Team │
└─────────────────────────┘
```
---
## 状态语义说明（这比图本身更重要）
### 1️⃣ Idle
* 设备**不持有任何 TeamKey**
* 不广播 Team 位置
* UI 显示「未建队 / 未加入」
---
### 2️⃣ Create
* **纯本地状态**
* 没有任何无线安全风险
* 所有“信任根”在这一刻生成
> 这是 **Team 安全边界的诞生点**
---
### 3️⃣ Active
* Team 的 **主要生命周期**
* 所有 Team 功能（地图、位置、指令）都只在此状态合法
* **TeamKey 是唯一信任来源**
---
### 4️⃣ Rotate
* **不是异常状态，是主动防御状态**
* 用来兑现你对用户的这句话：
> “即使配置外传，也能立刻止损”
关键点：
* Rotate **不改变 team_id**
* 只改变 `key_id` + 派生密钥
* 旧密钥立即失效
---
### 5️⃣ Disband
* **安全终止态**
* 所有密钥必须被销毁
* 不允许“恢复”“回看”“重连”
> Team 结束 ≠ 暂停
> Team 结束 = **密码学意义上的死亡**
---
## 你可以直接写进协议的 MUST 规则（来自状态机）
* **MUST** 仅在 `ACTIVE` / `ROTATE` 状态发送 Team 数据
* **MUST** 在 `DISBAND` 进入时销毁全部 Team 密钥
* **MUST** 丢弃 key_id 不匹配的数据包
* **MUST NOT** 从 `DISBAND` 回到 `ACTIVE`（必须重新建队）
---
## 为什么这张状态机“站得住”
* **产品层**：每个状态都能映射到一个清晰 UI
* **协议层**：每个跃迁都有明确报文或本地动作
* **安全层**：密钥生命周期与状态生命周期完全一致
---
非常好，这一步其实是**把“用户点了什么”和“协议里发生了什么”一一对齐**。
下面我会**严格按 UI 行为 → 状态变化 → 报文触发**来写，不引入新概念、不模糊。
你可以把这份内容理解为：
> **UI 是状态机的控制面板，协议报文是状态跃迁的副作用。**
---
# UI 行为 ↔ Team 状态机 ↔ 报文触发 精确映射
---
## 一、UI 总览：Team 菜单的三种“用户可感知状态”
从 UI 角度，Team 其实只有三种状态（和协议状态一一对应）：
| UI 显示状态 | 协议状态 | 用户能做什么 |
| -------- | ------- | ------------ |
| 未建队 | Idle | 建队 / 加入 |
| Team 进行中 | Active | 查看 / 分享 / 解散 |
| 正在解散 | Disband | 无（系统动作） |
> Rotate 是 **Active 内的子动作**，通常是 Leader-only，不是普通用户主流程。
---
## 二、UI 行为 1：点击「建队（Create Team）」
### UI 行为
```
菜单 → Team → [Create Team]
```
---
### 对应状态机跃迁
```
Idle ──(Create Team)──▶ Create ──▶ Active
```
---
### 报文与动作映射（逐步）
#### Step 1：用户点击「Create Team」（无报文）
**UI 行为**
* 用户确认“我要建一个 Team”
**本地动作（MUST）**
* 生成 `TeamKey`
* 计算 `team_id = Trunc(Hash(TeamKey))`
* 分配 / 选择 `CHT`
* 派生密钥：
* `ChannelPSK`
* `MgmtKey`
* `PosKey`
* `WpKey`
📌 **此时没有任何无线报文**
📌 **这是 Team 安全边界的起点**
---
#### Step 2：UI 显示「Team 已创建 / 分享码」
**UI 行为**
* 显示 Team Code / QR
* 显示「成员数：1」
**协议动作**
* **进入 Active 状态**
* 开始周期性（或一次性）广播：
```
CH0 → TEAM_ADVERTISE
```
```text
TEAM_ADVERTISE {
team_id,
join_hint?,
channel_index?,
nonce
}
```
📌 这是 **UI 显示“Team 已存在”** 的唯一协议依据
---
#### Step 3：UI 返回 Team 主页面（Active）
**UI 行为**
* 显示：
* Team Active
* Members: 1
* [View Team Map]
* [Share Team]
* [Disband Team]
**协议行为**
* 允许并处理以下报文：
* `TEAM_JOIN_REQUEST`
* `TEAM_JOIN_ACCEPT`
* `TEAM_POSITION_APP`
---
## 三、UI 行为 2：他人加入 Team（Join Team）
### UI 行为（队员）
```
Team → Join Team → 输入短码 / 扫码 → Confirm
```
---
### 报文与状态映射
#### Step 1：队员输入短码 / 扫码（无报文）
**UI 行为**
* 用户确认加入
**本地动作（MUST）**
* 解析 / 获得 `TeamKey`
* 预计算 `team_id`
* 派生 `MgmtKey / PosKey / WpKey`
📌 **没有 TeamKey，后续任何 JOIN 报文都没有意义**
---
#### Step 2：队员请求加入
```
CH0 → TEAM_JOIN_REQUEST
```
```text
TEAM_JOIN_REQUEST {
team_id,
nonce
}
```
---
#### Step 3：Leader UI 出现「加入请求」
**UI 行为（Leader）**
* 显示“新成员请求加入”
* [Accept] / [Ignore]
📌 UI 事件 **直接绑定** 下一条报文是否发送
---
#### Step 4：Leader 点击「Accept」
```
CH0 → TEAM_JOIN_ACCEPT
```
```text
TEAM_JOIN_ACCEPT {
team_id,
payload = E2EE(MgmtKey, {
channel_index,
channel_psk,
key_id,
team_params?
}),
nonce
}
```
---
#### Step 5：队员 UI 切换为「Team Active」
**UI 行为**
* 显示 Team 主页面
* Members ≥ 2
**本地动作**
* 保存 CHT + ChannelPSK
* 切换到 CHT
**协议动作（推荐）**
```
CHT → TEAM_JOIN_CONFIRM
```
---
## 四、UI 行为 3：Team 进行中（无按钮，但有持续行为）
### UI 行为
```
Team Active → View Team Map
```
---
### 协议行为（持续）
* 每个成员周期性发送：
```
CHT → TEAM_POSITION_APP
```
* UI 地图刷新 **只依赖成功解密后的 payload**
* 解密失败的数据包：
* MUST 被丢弃
* MUST NOT 更新 UI
---
## 五、UI 行为 4：点击「解散 Team（Disband Team）」【Leader】
### UI 行为
```
Team Active → [Disband Team] → Confirm
```
---
### 对应状态机跃迁
```
Active ──(Disband)──▶ Disband ──▶ Idle
```
---
### 报文与动作映射
#### Step 1：Leader 点击「Disband」
**UI 行为**
* 显示强确认弹窗
---
#### Step 2：Leader 确认解散
**协议动作（可选但推荐）**
```
CHT → TEAM_STATUS / TEAM_END
```
```text
TEAM_STATUS {
team_id,
payload = E2EE(MgmtKey, {
state = DISBAND
})
}
```
📌 这是 **通知性质**，不是安全关键
📌 即使收不到，也不影响安全性
---
#### Step 3：所有设备进入 Disband
**本地动作（MUST，所有成员）**
* 立即销毁：
* `TeamKey`
* `ChannelPSK`
* `MgmtKey / PosKey / WpKey`
* 停止所有 Team 报文
* 离开 CHT
---
#### Step 4：UI 回到未建队状态
```
Team → You are not in a Team
[Create Team] [Join Team]
```
📌 **UI 是密钥销毁完成的“可视确认”**
---
## 六、UI 行为 5：普通成员「离开 Team（Leave）」【非解散】
> 这是 **UI 行为 ≠ 协议状态变化** 的典型例子
### UI 行为
```
Team Active → [Leave Team]
```
---
### 本地动作（MUST）
* 销毁所有 TeamKey / 派生密钥
* 离开 CHT
### 协议动作（MAY）
```
CHT → TEAM_LEAVE_NOTICE
```
> 仅用于 UI 同步，不影响 Team 存续
📌 **Team 状态仍为 Active（对其他人）**
---
## 七、关键设计原则（可以写进 PRD）
1. **UI 行为永远先于报文**
报文只是“用户意图的副作用”
2. **没有 TeamKey → UI 不允许进入 Active**
安全失败必须表现为“操作不可达”
3. **解散是密钥行为，不是通知行为**
报文失败 ≠ 解散失败
---
## 一句话总结这套映射关系
> **UI 决定状态，
> 状态决定密钥，
> 密钥决定哪些报文“有意义”。**
---
### 下一步（非常自然）
如果你愿意，我可以下一步帮你直接做其中之一：
1. **把这套映射写成“UI × Protocol 对照表”**（方便测试与 PR）
2. **帮你设计 Team 页面在不同状态下的 LVGL 组件树**
3. **把这些 UI 行为转成自动化测试用例描述**
你现在这一步，已经是在做**系统级产品设计**了，而不是“功能拼装”。
好，这一步我们**完全站在“嵌入式 UI 工程”的角度**来做。
目标不是“好看”，而是 **状态清晰、组件稳定、不会演化失控**。
下面我给你的是 **LVGL 组件树（Component Tree）**，不是布局草图；
你可以直接据此拆 `.cpp / .h`，或者对照你现在的 UI 架构来重构。
---
# Team 页面 · LVGL 组件树设计
（按 **状态** 明确分支，而不是条件 if/else 堆在一起）
---
## 总体设计原则（先给你“架构约束”）
### 1️⃣ Team 页面 = 状态容器（不是功能容器）
```text
TeamPage
└── TeamStateContainer // 只负责：Idle / Active / Disband
```
* **永远只挂载一个子树**
* 状态切换 = 删除旧子树 + 创建新子树
* 不在同一树里 hide/show
👉 这是防止 LVGL 页面“变成屎山”的关键
---
### 2️⃣ 页面分三棵互斥的树
```text
TeamState = { IDLE, ACTIVE, DISBAND }
```
* `IdleTree`
* `ActiveTree`
* `DisbandTree`（瞬态，通常很短）
---
## 一、Team 页面根节点（所有状态共用）
```text
TeamPage (lv_obj_t*)
├── TopBar
│ ├── BackButton
│ └── TitleLabel ("Team")
│
└── TeamStateContainer (lv_obj_t*)
└── <StateSpecificTree>
```
说明：
* `TopBar` 永远存在
* `TeamStateContainer` 是**唯一可变区域**
---
## 二、状态 1：未建队（IDLE）
### 用户心智
> “我现在不在任何 Team 里。”
---
### 组件树：IdleTree
```text
IdleTree (lv_obj_t*)
├── CenterContainer
│ ├── StatusIcon // 简单图标：空队伍
│ ├── StatusLabel // "You are not in a Team"
│ └── Spacer
│
├── ActionContainer
│ ├── CreateTeamButton // 主按钮
│ └── JoinTeamButton // 次按钮
```
---
### 组件职责说明
* `CreateTeamButton`
* 点击 → **触发 UI 行为：Create Team**
* 后续状态切换由控制器决定
* `JoinTeamButton`
* 跳转到 Join 流程页（输入码 / 扫码）
* 成功后切换到 `ACTIVE`
📌 **IdleTree 不关心任何协议或密钥**
---
## 三、状态 2：Team 进行中（ACTIVE）
这是 **停留时间最长、最重要的状态**。
### 用户心智
> “我在一个 Team 里，我能看到状态，也能做决定。”
---
### 组件树：ActiveTree（完整）
```text
ActiveTree (lv_obj_t*)
├── SummaryCard
│ ├── TeamStatusLabel // "Team Active"
│ ├── MemberCountLabel // "Members: N"
│ └── PrivacyBadge // "Strong Privacy / E2EE"
│
├── Divider
│
├── ActionList
│ ├── ViewMapItem // → Team Map
│ ├── ShareTeamItem // → 显示 Team Code / QR
│ └── (optional) RotateKeyItem // Leader only
│
├── Divider
│
└── DangerZone
└── DisbandButton / LeaveButton
```
---
### 关键：Leader / Member 的分支（不是不同页面）
#### 普通成员（Member）
```text
DangerZone
└── LeaveTeamButton
```
#### Leader（建队者）
```text
DangerZone
└── DisbandTeamButton
```
> ⚠️ **不要在 UI 层暴露“Leader”概念**
> 只通过按钮存在与否体现
---
### 各组件的“协议触发点”
#### `ViewMapItem`
* 只做一件事：跳转到 Team Map 页面
* Team Map 页面只消费：
* `TEAM_POSITION_APP`
* `TEAM_WAYPOINT_APP`
* `TEAM_TRACK_APP`
#### `ShareTeamItem`
* 进入 **Share Subpage**
* 只读数据：
* Team Code
* QR
* ❌ 不触发任何报文
#### `RotateKeyItem`（Leader-only）
* 点击 → 进入确认页
* 确认后：
* 触发 **Rotate 状态**
* 发送 `TEAM_STATUS (new key_id)`
#### `DisbandTeamButton`
* 点击 → 进入 **DisbandTree**
---
## 四、状态 3：解散中（DISBAND）
这是一个 **瞬态状态**，但非常重要。
### 用户心智
> “这件事是不可逆的。”
---
### 组件树：DisbandTree
```text
DisbandTree (lv_obj_t*)
├── WarningIcon
├── WarningLabel
│ └── "Disbanding Team..."
│
└── ProgressIndicator
```
---
### 行为绑定（关键）
* **进入 DisbandTree 的同时**
* 本地立即销毁：
* TeamKey
* ChannelPSK
* 所有派生密钥
* 停止 Team 报文
* **不等待网络结果**
* UI 停留时间极短（例如 300–500ms）
---
### Disband 完成后
```text
DISBAND → IDLE
```
* 销毁 `DisbandTree`
* 创建 `IdleTree`
---
## 五、状态切换 = 组件树切换（推荐实现模式）
### 推荐控制逻辑（伪代码）
```cpp
void TeamPage::setState(TeamState newState) {
if (currentTree) {
lv_obj_del(currentTree);
currentTree = nullptr;
}
switch (newState) {
case IDLE:
currentTree = buildIdleTree(container);
break;
case ACTIVE:
currentTree = buildActiveTree(container);
break;
case DISBAND:
currentTree = buildDisbandTree(container);
break;
}
}
```
📌 **没有 show/hide**
📌 **没有 if (isLeader) scattered everywhere**
📌 **所有状态边界在一个地方**
---
## 六、这套组件树设计的三个“硬优势”
1. **状态与 UI 完全同构**
状态机 = UI 结构，不是注释
2. **协议失败不会污染 UI**
* 解散不依赖报文成功
* UI 只反映本地密钥状态
3. **未来扩展不会炸**
* 加 Team Settings
* 加 Key Rotation
* 加 Debug Info
都只是在 `ActiveTree` 里加一支
---你这个“拉回”的动作非常对。
我们现在**明确只做一件事**：
> **围绕「建队状态机 + 密钥交换流程」，哪些数据必须持久化？哪些绝不能持久化？哪些是状态性的？**
不谈 UI、不谈地图、不谈未来扩展，只谈**数据与生命周期**。
---
# Team 建队 & 密钥交换阶段
## 数据持久化整理（严格按状态机）
---
## 一、先给结论（总表）
> **不是所有参与建队的东西都应该持久化**
> 持久化的唯一判断标准是：
> 👉 *“设备重启后，是否还能继续处于同一个 Team 状态”*
### 数据分三类：
| 类别 | 是否持久化 | 原因 |
| ---------- | ----- | ------------- |
| Team 身份与密钥 | ✅ 必须 | 否则重启=自动退队 |
| Channel 配置 | ✅ 必须 | 否则无法接收 Team 包 |
| 协议瞬态状态 | ❌ 不应 | 可通过报文重建 |
| UI / 交互状态 | ❌ 不应 | 完全是表现层 |
---
## 二、按状态机逐状态分析
---
## 状态 0：Idle（未建队）
### 持久化数据
**无。**
```text
(no Team-related persistent data)
```
### 原则
* Idle 状态下 **设备上不存在任何 Team 痕迹**
* 这是安全与心理边界的起点
---
## 状态 1：Create（本地建队，尚未 Active）
> 这是一个**非常短暂的状态**
> 只存在于一次 UI 操作中
### 是否需要持久化？
❌ **不需要**
### 原因
* Create 是一次**原子操作**
* 要么成功进入 Active
* 要么失败回到 Idle
👉 **Create 阶段失败 = 不留下任何痕迹**
---
## 状态 2：Active（Team 正在进行）
这是**唯一需要持久化的核心状态**。
---
### 1️⃣ Team 身份类（必须持久化）
```text
TeamIdentity
├── team_id (bytes)
├── team_role (enum: LEADER / MEMBER)
├── key_id (uint32)
```
#### 说明
* `team_id`：所有 Team 数据的索引键
* `team_role`：影响 UI 与允许的动作
* `key_id`：当前密钥版本（用于解密判断）
✅ **MUST persist**
---
### 2️⃣ Team 密钥类（必须持久化，安全存储）
```text
TeamSecrets
├── team_key (bytes) // 根密钥
├── mgmt_key (bytes)
├── pos_key (bytes)
├── wp_key (bytes)
```
#### 说明
* 派生密钥 **可以重算**，但不建议
* 重算依赖 KDF 版本一致，风险高
* 实践中直接存派生结果更稳
✅ **MUST persist**
⚠️ **必须使用安全存储（NVS / encrypted storage）**
---
### 3️⃣ Channel 配置类（必须持久化）
```text
TeamChannelConfig
├── channel_index (uint8 / uint32)
├── channel_psk (bytes)
```
#### 说明
* 重启后必须能重新监听 CHT
* 否则会“逻辑上还在 Team，物理上听不到”
✅ **MUST persist**
---
### 4️⃣ Team 行为参数（建议持久化）
```text
TeamParams
├── position_interval_ms
├── position_precision_level
├── advertise_enabled
├── join_policy
```
#### 说明
* 这些参数**由 Leader 决定**
* 成员端只是执行
🟡 **SHOULD persist**
（不存也能跑，但体验不一致）
---
### 5️⃣ 不应持久化的东西（非常重要）
#### ❌ 协议瞬态状态
```text
DO NOT persist:
- 已发送但未确认的 JOIN_REQUEST
- JOIN_CONFIRM 状态
- 最近一次 TEAM_STATUS 内容
- 成员列表（可通过广播重建）
```
原因：
* 都是 **软状态**
* 断电/重启后自然恢复
---
#### ❌ UI 状态
```text
DO NOT persist:
- 当前是否在 Team 页面
- 是否展开某个子菜单
- 是否刚刚显示过 QR
```
---
## 状态 3：Rotate（密钥轮换中）
> Rotate 是 **Active 的子状态**
### 持久化策略：**两阶段提交**
#### 临时状态（不持久化）
```text
RotateContext (RAM only)
├── new_key_id
├── new_mgmt_key
├── new_pos_key
├── new_wp_key
```
#### 切换成功瞬间（持久化）
```text
TeamSecrets (overwrite)
├── key_id = new_key_id
├── mgmt_key = new_mgmt_key
├── pos_key = new_pos_key
├── wp_key = new_wp_key
```
📌 **不要持久化“正在轮换中”**
📌 **要么成功覆盖，要么保持旧密钥**
这是**避免掉电/异常导致“半轮换”**的关键。
---
## 状态 4：Disband（解散）
### 行为规则（强制）
> **Disband = 数据销毁**
### 必须执行的持久化动作
```text
DELETE persistent:
- TeamIdentity
- TeamSecrets
- TeamChannelConfig
- TeamParams
```
### 不允许的行为
* ❌ 不允许标记“已解散但可恢复”
* ❌ 不允许保留 team_id
* ❌ 不允许缓存旧密钥
📌 **Disband 是密码学意义上的死亡**
---
## 三、Join 流程中的持久化时机（精确）
### 成员设备（Member）
| 时刻 | 是否持久化 | 内容 |
| -------------------- | ----- | -------------------------------- |
| 输入短码 | ❌ | （仅 RAM） |
| 发送 JOIN_REQUEST | ❌ | |
| 收到 JOIN_ACCEPT 并成功解密 | ✅ | TeamIdentity + Secrets + Channel |
| 切换到 CHT 成功 | ✅ | 同上 |
| JOIN_CONFIRM | ❌ | |
---
### 建队者（Leader）
| 时刻 | 是否持久化 | 内容 |
| ----------- | ----- | ---------- |
| Create Team | ✅ | 全量 Team 数据 |
| 接受新成员 | ❌ | |
| Rotate 成功 | ✅ | 覆盖密钥 |
| Disband | ❌（删除） | |
---
## 四、你可以直接写进协议/实现文档的一句话规则
> **只有“定义 Team 身份连续性的数据”才允许持久化；
> 所有报文级、交互级状态都必须是可丢弃的。**
---
## 五、一个非常实用的工程建议（重要）
**把 Team 持久化做成一个“单一对象”**
```text
PersistentTeamState
├── identity
├── secrets
├── channel
├── params
```
* 有这个对象 → Team = Active
* 没有这个对象 → Team = Idle
📌 **不要拆散到多个 KV**
📌 **不要用 flag 表示“在不在 Team”**
---
# 1️⃣ 建队流程（Leader）
## 持久化读写时序图
```
时间 ↓
Leader Device
──────────────────────────────────────────────────────────────
[UI] Click "Create Team"
|
v
📦 RAM: generate TeamKey
📦 RAM: derive team_id, ChannelPSK, MgmtKey, PosKey, WpKey
📦 RAM: select Team Channel (CHT)
|
| (still NOT persistent)
|
v
[UI] Confirm Create
|
v
💾 PERSIST: write PersistentTeamState
├── identity.team_id
├── identity.role = LEADER
├── identity.key_id = 0
├── secrets.team_key
├── secrets.mgmt_key
├── secrets.pos_key
├── secrets.wp_key
├── channel.channel_index = CHT
├── channel.channel_psk
└── params (optional)
|
v
[STATE] Team = ACTIVE
|
v
[PROTO] start TEAM_ADVERTISE (CH0)
[PROTO] accept JOIN_REQUEST
[PROTO] send JOIN_ACCEPT
```
### 关键规则（必须遵守）
* ❌ **在 UI Confirm 之前，绝不写 Flash**
* ✅ **第一次持久化 = Team 正式存在**
* 💡 掉电在 Confirm 之前 → 自动回到 Idle（无残留）
---
# 2️⃣ 加入流程（Member）
## 持久化读写时序图（最容易出 bug 的地方）
```
时间 ↓
Member Device
──────────────────────────────────────────────────────────────
[UI] Click "Join Team"
|
v
[UI] Input Code / Scan QR
|
v
📦 RAM: obtain TeamKey
📦 RAM: derive team_id, MgmtKey, PosKey, WpKey
|
| (still NOT persistent)
|
v
[PROTO] send TEAM_JOIN_REQUEST (CH0)
|
v
[PROTO] receive TEAM_JOIN_ACCEPT (CH0)
|
v
[SEC] try decrypt JOIN_ACCEPT payload
|
|-- decryption FAIL --> ❌ abort (NO write)
|
v
📦 RAM: extract channel_index, channel_psk, key_id
|
| (still NOT persistent)
|
v
[PROTO] switch to Team Channel (CHT)
|
|-- switch FAIL --> ❌ abort (NO write)
|
v
💾 PERSIST: write PersistentTeamState
├── identity.team_id
├── identity.role = MEMBER
├── identity.key_id
├── secrets.team_key
├── secrets.mgmt_key
├── secrets.pos_key
├── secrets.wp_key
├── channel.channel_index
├── channel.channel_psk
└── params (optional)
|
v
[STATE] Team = ACTIVE
|
v
[PROTO] send TEAM_JOIN_CONFIRM (CHT)
[PROTO] start TEAM_POSITION_APP
```
### 关键规则（这是重点）
* ❌ **收到 JOIN_ACCEPT ≠ 可以写 Flash**
* ❌ **解密成功 ≠ 可以写 Flash**
* ✅ **只有在“成功切换到 CHT”之后才允许持久化**
> 这是为了防止：
> **“Flash 里记录着 Team，但无线层根本进不了 Team Channel”**
---
# 3️⃣ 解散流程（Disband）
## 持久化删除时序图（最安全的一条）
### 3A. Leader 解散 Team
```
时间 ↓
Leader Device
──────────────────────────────────────────────────────────────
[UI] Click "Disband Team"
|
v
[UI] Confirm Disband
|
v
❌ DELETE: erase PersistentTeamState
├── identity
├── secrets
├── channel
└── params
|
v
📦 RAM: clear all Team-related state
|
v
[STATE] Team = IDLE
|
v
[PROTO] (optional) send TEAM_STATUS / TEAM_END
```
### 3B. 普通成员离开 Team（Leave）
```
时间 ↓
Member Device
──────────────────────────────────────────────────────────────
[UI] Click "Leave Team"
|
v
❌ DELETE: erase PersistentTeamState
|
v
📦 RAM: clear Team state
|
v
[STATE] Team = IDLE
|
v
[PROTO] (optional) send LEAVE_NOTICE
```
### 关键规则（必须统一）
* ❌ **不要先发报文再删数据**
* ❌ **不要等待网络 ACK**
* ✅ **删除持久化 = Team 立刻不存在**
> 报文是“礼貌”，
> **删除密钥才是“事实”。**
---
# 4️⃣ 旋转密钥（Rotate）补充：持久化原子性
```
Leader Device
──────────────────────────────────────────────────────────────
[UI] Click "Rotate Key"
|
v
📦 RAM: generate new subkeys
📦 RAM: new_key_id
|
v
[PROTO] broadcast TEAM_STATUS(new_key_id)
|
|-- timeout / abort --> ❌ discard RAM only
|
v
💾 PERSIST (ATOMIC overwrite):
├── identity.key_id = new_key_id
├── secrets.mgmt_key = new
├── secrets.pos_key = new
└── secrets.wp_key = new
|
v
[STATE] Team still ACTIVE (new key)
```
### 关键规则
* ❌ **不允许“半写入”**
* ❌ **不持久化 Rotate 进行中状态**
* ✅ **要么全换，要么不换**
---
# 5️⃣ 一条可以写进实现规范的铁律
> **持久化只发生在“状态跃迁完成之后”，
> 删除只发生在“状态跃迁开始之时”。**
---
# 6️⃣ 最终工程检查清单（你可以直接用）
* [ ] Create Confirm 前没有任何 Flash 写入
* [ ] Join 成功切换 CHT 前没有任何 Flash 写入
* [ ] Disband / Leave 第一动作就是删除持久化
* [ ] Rotate 只有一个原子写点
* [ ] PersistentTeamState 是否是“单一对象”
---
# Team 持久化存储设计
## NVS / Flash Layout & Wear Strategy
> 设计目标：
>
> * 掉电安全
> * 原子更新
> * 最小擦写
> * 明确“Team 存在 / 不存在”的判据
---
## 一、总原则（先立铁律）
### 1️⃣ Team 持久化 = **单一对象**
> **Flash 中只有一个“Team 是否存在”的真相源**
```text
PersistentTeamState
```
* 有它 → Team = Active
* 没有它 → Team = Idle
❌ 不使用多个 flag
❌ 不在不同 namespace 里拆散
---
### 2️⃣ 写入次数极少，是“生命周期级别”的
| 操作 | 写 Flash？ |
| ----------- | -------- |
| 建队成功 | ✅ 一次 |
| 成员加入成功 | ✅ 一次 |
| Rotate Key | ✅ 一次 |
| 正常使用（位置/聊天） | ❌ |
| 解散 / 离开 | ✅ 删除 |
> **不是高频写场景**
> 所以重点是 **正确性 > 极限性能**
---
## 二、推荐存储方式（ESP32 实践）
### ✅ 推荐：NVS（Non-Volatile Storage）
原因：
* 自带 wear leveling
* 支持 blob
* 支持 namespace
* 原子语义清晰
> 你现在的需求 **完全不需要自定义 raw flash**
---
## 三、NVS Namespace 设计
```text
NVS Namespace: "team"
```
**只有这一个 namespace 存 Team。**
---
## 四、Key 布局（极简但完整）
### 核心 Key 列表
| Key | 类型 | 说明 |
| ------------ | ---- | ---------------------- |
| `version` | u32 | 结构版本 |
| `team_state` | blob | 整个 PersistentTeamState |
> ❗**不要拆成几十个 key**
> 拆了就很难保证一致性与原子性
---
## 五、PersistentTeamState 结构（Flash 中的唯一真相）
### 逻辑结构（与你之前分析一致）
```text
PersistentTeamState
├── header
│ ├── magic
│ ├── version
│ ├── length
│ └── crc32
│
├── identity
│ ├── team_id
│ ├── role (LEADER / MEMBER)
│ └── key_id
│
├── secrets
│ ├── team_key
│ ├── mgmt_key
│ ├── pos_key
│ └── wp_key
│
├── channel
│ ├── channel_index
│ └── channel_psk
│
└── params (optional)
├── position_interval_ms
├── precision_level
└── flags
```
---
### Header 设计（非常重要）
| 字段 | 作用 |
| --------- | ----------- |
| `magic` | 判断是否存在 Team |
| `version` | 结构版本 |
| `length` | 防截断 |
| `crc32` | 掉电 / 半写检测 |
📌 **header 是你对抗掉电与损坏的最后防线**
---
## 六、写入策略（什么时候写，怎么写）
### 1️⃣ 写入只发生在“成功跃迁后”
你前面定的规则，现在变成存储规则：
| 场景 | 写入内容 |
| --------------- | ----------------------- |
| Create Confirm | 写完整 PersistentTeamState |
| Join 成功切换 CHT | 写完整 PersistentTeamState |
| Rotate 成功 | **整体覆盖写** |
| Disband / Leave | 删除 key |
---
### 2️⃣ 写入方式：整体覆盖（不是增量）
```text
nvs_set_blob("team", "team_state", &state, sizeof(state))
nvs_commit()
```
* 不修改子字段
* 不做 patch
* 不维护“正在 rotate”状态
📌 **整体写 + CRC = 最稳**
---
## 七、擦写 / 删除策略（关键）
### 解散 / 离开 Team
```text
nvs_erase_key("team", "team_state")
nvs_commit()
```
* **删除即事实**
* 不保留“历史 Team”
* 不留可恢复路径
---
### 为什么不用 flag 表示“已解散”
因为：
* flag 本身也是状态
* flag 需要维护一致性
* flag 会引入“幽灵 Team”
**不存在 = 最干净**
---
## 八、掉电与损坏恢复策略
### 启动时的判断逻辑（唯一入口）
```text
if (nvs_has_key("team", "team_state")) {
read blob
if (magic ok && crc ok) {
Team = ACTIVE
} else {
erase key
Team = IDLE
}
} else {
Team = IDLE
}
```
📌 **任何异常 → 删除 → Idle**
---
## 九、Key Rotation 的原子性保证
### 正确做法（你前面已经定了）
1. 新密钥 **只存在 RAM**
2. 广播 Rotate
3. 同步完成
4. **一次性覆盖写 PersistentTeamState**
```text
old_state → new_state
nvs_set_blob(...)
nvs_commit()
```
❌ 不写中间态
❌ 不写 `rotating = true`
---
## 十、Flash 磨损分析（给你信心）
### 最坏情况估算
| 操作 | 次数 |
| ------ | ------- |
| 建队 | 1 |
| Rotate | 假设 20 次 |
| 解散 | 1 |
**< 50 次写入 / Team 生命周期**
NVS 默认 wear leveling 足以支撑 **数十万次**。
👉 **可以放心**
---
## 十一、一个非常重要的安全建议（强烈）
### TeamSecrets 存储
* 如果平台支持：
* 使用 **NVS encrypted partition**
* 或：
* 在写入前，用 device-unique key 再包一层
你不需要军工级，只需要：
> **Flash 被 dump，TeamKey 不可直接读出**
---
## 十二、最终“实现检查清单”（你可以直接用）
* [ ] Team 只占用一个 NVS key
* [ ] PersistentTeamState 有 magic + crc
* [ ] 所有写入都是整体 blob
* [ ] 解散 = erase key
* [ ] 启动异常 = erase key
* [ ] Rotate 只有一个 commit 点
---
## 一句话总结这套设计
> **Flash 里不保存“过程”，
> 只保存“事实”。**
---
## 1) 复盘的三种级别（先定产品边界）
你要“整个生命周期所有事件落地”，但落地可以有不同强度：
### A. 本地复盘（推荐默认）
* **每台设备只记录自己看到/发出的事件**
* 不需要全员上报
* 最少协议改动
* 复盘不一定 100%完整（取决于你当时是否收到包）
### B. 领队完整复盘（可选增强）
* Leader 设备尽量收集全队事件（仍然是“尽量”，无线环境无法保证 100%）
* 更接近“行动记录仪”
### C. 全队一致复盘（最重，不建议一开始做）
* 需要全队 ACK/补齐/对账
* 立刻把系统复杂度拉爆
> 我建议：**先做 A**，再做 B（Leader 模式），C 暂时不碰。
---
## 2) 你要记录什么：事件模型（Event Sourcing 风格）
把 Team 的一生理解为：**事件序列 + 状态重建**。
### 事件必须包含的元信息（所有事件通用）
* `event_id`：唯一（可用 `sender_id + seq`）
* `team_id`
* `ts`：事件发生时间（设备本地时间 + 可选 mesh 时间）
* `sender_id`：节点 ID
* `event_type`
* `payload`：按类型携带字段
* `key_id`：当时使用的密钥版本（很重要，便于复盘解密）
### 事件类型建议（覆盖你当前系统）
**生命周期**
* `TEAM_CREATED`（Leader 本地）
* `TEAM_ADVERTISE_SENT/RECEIVED`
* `TEAM_JOIN_REQUEST_SENT/RECEIVED`
* `TEAM_JOIN_ACCEPT_SENT/RECEIVED`
* `TEAM_JOIN_CONFIRM_SENT/RECEIVED`
* `TEAM_STATUS_SENT/RECEIVED`
* `TEAM_KEY_ROTATED`（含 old/new key_id）
* `TEAM_DISBANDED` / `TEAM_LEFT`
**行动**
* `TEAM_POSITION_RX`（建议只存“采样后的”位置点）
* `TEAM_WAYPOINT_RX`
* `TEAM_COMMAND_RX`（你未来的集合/求助等指令）
**异常**
* `DECRYPT_FAIL`（重要：复盘时能解释“为什么当时没显示”）
* `REPLAY_DROP`
* `MEMBER_LOST` / `MEMBER_RECOVERED`
---
## 3) 日志存储位置：Flash vs SD 的现实选择
### 如果你有 SD 卡（强烈推荐）
* 用 SD 文件做**追加写日志**（Flash 磨损问题直接变小）
* 文件系统好用（导出、查看、同步）
### 只有 Flash（NVS/自定义分区）
* 也能做，但要用**环形日志（ring buffer）**
* 写放大、磨损要精心控制
* 不适合存“高频位置点”
> 结论：**位置轨迹复盘几乎必然要 SD**，否则你必须极度降采样。
---
## 4) 最关键：复盘与“解散销毁密钥”如何兼容？
你之前的安全模型是：Disband 立即销毁 TeamKey → 历史不可读。
而复盘要求：解散后仍能读历史。
所以你要引入一个独立的日志密钥：
### 新增密钥：`LogKey`
* `LogKey = KDF(TeamKey, "log")` **可以**，但如果 Disband 会销毁 TeamKey，那 LogKey 也丢了。
* 更合理：**创建 Team 时生成独立随机 LogKey**，并设置“是否保留”的策略。
### 两种策略（对应产品开关）
1. **默认：Disband 销毁 LogKey**
* 不可复盘
* 最强隐私承诺（默认建议）
2. **开启复盘：Disband 保留 LogKey（仅本机）**
* 日志文件仍然是加密的
* 只有该设备能复盘
* 你仍可承诺：**TeamKey 销毁，网络权限消失；但本机保留行动记录**
这其实很符合户外真实需求：
* **通信权限**随队伍结束而结束
* **行动记录**可由个人/领队保留
---
## 5) 写入策略：怎样既完整又不爆存储？
### 位置点不要“每包都落盘”
位置是最高频数据，必须做降采样：
* 规则一：**按时间采样**（例如每 10s/30s 记录一次）
* 规则二：**按距离采样**（移动超过 20m 才记）
* 规则三：异常优先（SOS/集合时临时升频）
### 事件日志推荐结构：Append-only + Checkpoint
为了复盘速度与稳定性：
* `events.log`：追加写（每条事件一条记录）
* `snapshot.bin`：偶尔写一个“当前 Team 状态快照”（比如每 5 分钟或每 200 条事件）
* 复盘时：从最近快照开始回放事件，速度快
---
## 6) 存储格式建议（别纠结，选一个能跑的）
你已经在 protobuf 体系里，最顺：
* **protobuf event**（一条 event message）
* 外层封一层 `LogRecord`：
* `len`（u16/u32）
* `record_type`（event/snapshot）
* `ciphertext`
* `crc32`（可选）
日志内容建议 **AEAD(LogKey)** 加密，保证：
* 落地文件被拷走也看不懂
* 文件被篡改能检测出来
---
## 7) 复盘的输出是什么样？
### 最小可用复盘（MVP）
* 时间线：加入/离开/集合/求助/掉线/恢复
* 地图回放：按时间推进显示轨迹（不要求动画，先做“按时间跳点”）
### Leader 复盘增强
* 统计：队伍最大拉开距离、成员掉线次数、集合耗时
* 异常：谁长时间静止、谁电量低、何时丢包严重
---
## 8) 最重要的落地决策：你要不要“复盘开关”？
我强烈建议在建队时就决定：
* `Record mode: Off / Local / Leader`
* `Retention: 1 day / 7 days / manual delete`
* `Privacy: Keep logs encrypted (default)`
并且在解散时：
* 如果 record off → 删除日志 + 销毁 LogKey
* 如果 record on → 写入 `TEAM_DISBANDED` 事件 + 关闭记录，但保留 LogKey（本机）
---
## 9) 你问的“整理一下”：需要持久化的新增数据
在你之前 `PersistentTeamState` 基础上，加这几项就够：
**当 Record=ON 时：**
* `log_enabled`（bool）
* `log_mode`（enum: LOCAL / LEADER）
* `log_key`（bytes）✅（独立于 TeamKey）
* `log_file_id` / `log_path`（如果 SD）
* `log_seq`（用于事件递增编号）
* `last_snapshot_offset`（可选）
**当 Record=OFF 时：**
* 不持久化任何 log 相关内容
---
# 1) SD 文件布局
## 1.1 目录结构（按 Team 会话分桶）
建议每次 Team 生命周期（Create→Disband）生成一个 **session_id**（随机 64-bit 或时间戳+随机），作为一个会话目录。
```
/trail-mate/
/team_logs/
/YYYYMMDD/
/T_<session_id>/
meta.json
keys.bin
events.log
snapshot.idx
snapshots.bin
```
### 文件职责
* `meta.json`（明文、可读）
* 仅放非敏感信息：创建时间、设备名、版本号、记录模式等
* `keys.bin`（加密/保护）
* 存 LogKey 的封装（详见 3）
* `events.log`（核心追加写日志）
* 事件流（加密记录）
* `snapshot.idx`（小索引，方便快速定位）
* 每个快照对应 `events.log` 的 offset + `snapshots.bin` 的 offset
* `snapshots.bin`（快照流，追加写）
* 复盘加速的状态快照（加密记录）
> **MUST**：`events.log` 与 `snapshots.bin` 都是 *append-only*（只追加、不改写、不截断）。
> **SHOULD**：每天分目录，方便清理/归档。
---
# 2) LogRecord 二进制格式（通用记录容器）
`events.log` 和 `snapshots.bin` 使用同一种 record 容器：`LogRecord`。
每条记录都是：**固定头 + 变长密文 + 可选 CRC**。
## 2.1 LogRecord 结构（小端序 Little-endian）
```
+-------------------------------+
| magic (4) "TLOG" |
| version (1) = 1 |
| type (1) 1=EVENT 2=SNAP|
| flags (2) |
| header_len (2) bytes |
| body_len (4) bytes |
| session_id (8) |
| seq (8) monotonic |
| ts_ms (8) unix ms |
| key_id (4) |
| nonce (12) |
| aad_crc32 (4) | (optional but recommended)
|--------------------------------
| AAD (header extension...) | (header_len - fixed_header bytes)
|--------------------------------
| ciphertext (body_len bytes) | AEAD output (may include tag)
|--------------------------------
| trailer_crc32 (4) optional |
+-------------------------------+
```
### 固定头字段说明
* `magic`：用于快速扫描与恢复
* `version`：格式版本
* `type`：EVENT / SNAP
* `flags`：位标志（是否有 trailer_crc、是否压缩等）
* `header_len`：头部总长度（方便未来扩展 AAD）
* `body_len`：密文长度
* `session_id`：会话绑定（防止混写）
* `seq`：单调递增序号（掉电恢复、去重、对齐）
* `ts_ms`：记录写入时间（或事件发生时间，看你定义）
* `key_id`：LogKey 轮换版本（可选但强烈推荐）
* `nonce(12)`：AEAD nonce（每条记录唯一）
* `aad_crc32`：对 AAD 计算 CRC（用来快速判断 header 是否被破坏）
> **MUST**：`seq` 单调递增且不重复（同一 session 内）。
> **MUST**：`nonce` 在同一 `key_id` 下不可重复。
> **SHOULD**：`header_len` 允许携带扩展 AAD（比如 sender_id、event_type 等的明文字段）。
---
## 2.2 flags 位定义（建议）
* bit0: `HAS_TRAILER_CRC`（记录末尾带 `trailer_crc32`）
* bit1: `BODY_COMPRESSED`（密文内部的明文在加密前压缩）
* bit2: `TS_IS_EVENT_TIME`（ts_ms 表示事件发生时间，否则表示写入时间）
* bit3: `RESERVED`
> 推荐默认打开 `HAS_TRAILER_CRC`。即使 AEAD 能校验密文完整性，CRC 仍对**快速定位损坏/截断**很有价值。
---
# 3) 加密与密钥存放（LogKey）
## 3.1 LogKey 的定位
* TeamKey 用于 Team 通信（可能在 Disband 时销毁）
* **LogKey 用于日志加密**，是否保留由 “Record Mode/Retention Policy” 决定
> 你想要“可复盘”，就必须 **在 Disband 后仍可获得 LogKey**（至少在本机）。
## 3.2 keys.bin（推荐结构）
`keys.bin` 不要明文放 LogKey。建议用设备唯一密钥封装（例如 ESP32 NVS 加密分区 / eFuse key / 或你自己的 device key）。
`keys.bin` 内容建议也是一个小的 `KeyRecord`：
```
magic "TKEY" (4)
version (1)
flags (1)
reserved(2)
session_id (8)
key_id (4)
nonce (12)
ciphertext (var) = AEAD(DeviceKey, LogKeyMaterial)
crc32 (4)
```
其中 `LogKeyMaterial` 至少包含：
* `log_key` (32 bytes)
* `kdf_info`/algo id（可选）
* `created_ts`（可选）
> **MUST**：设备没有解封 `keys.bin` 的能力时，不允许进入复盘（避免误显示）。
---
# 4) events.log 里明文到底放什么（EVENT 内容）
EVENT 的明文建议用 protobuf（或你自定义 TLV），然后 AEAD 加密。
### 明文建议结构：`TeamEvent`（protobuf）
包含：
* `event_type`
* `sender_id`
* `team_id`
* `payload`（按类型 oneof）
* `mesh_ts`（可选）
* `rx_rssi/snr`（可选）
* `seq_in_mesh`（可选）
> **SHOULD**：把 `event_type` 放到 LogRecord 的 AAD 扩展里（明文），这样你可以不解密就做快速过滤/统计；但会泄露“事件类别”——如果你非常在意隐私，就不要这么做，把一切放密文里。
---
# 5) CRC 策略（掉电与损坏恢复的关键）
你有三层完整性：
1. AEAD tag：保证密文不可篡改（但无法判断“文件截断”位置）
2. `aad_crc32`：快速判断 header 是否损坏
3. `trailer_crc32`：对整个 record（从 magic 到 ciphertext）做 CRC，便于恢复扫描
### trailer_crc32 计算范围（建议）
对 `LogRecord` 从 `magic` 开始到 `ciphertext` 末尾（不含 trailer_crc32 本身）做 CRC32。
> **MUST**：读取时若 CRC 不匹配，该 record 之后的数据可视为不可信，进入恢复扫描模式。
---
# 6) 追加写策略（append-only）
## 6.1 写入流程（每条 record）
1. 组装明文 event
2. 生成 nonce
3. AEAD 加密得到 ciphertext
4. 写入 LogRecord 头 + ciphertext
5. 写入 trailer_crc32（若启用）
6. `fsync/flush`（看你平台：至少在关键事件/周期性 flush）
### Flush 策略（SD 实用建议）
* 普通事件：可每 N 条或每 T 秒 flush 一次（例如 2s）
* 关键事件（TEAM_CREATED / DISBANDED / ROTATED / SOS）：**立即 flush**
> **SHOULD**：实现一个 `LogWriter`，内部有小缓冲；但不要大到掉电损失太多。
---
# 7) 快照策略（snapshot + index）
复盘如果只靠 replay events，会越来越慢。快照就是为了“从某个点开始回放”。
## 7.1 快照内容
快照明文建议存：
* 当前 `key_id`
* 成员表（最近可见成员、最后位置）
* 当前 waypoint/assemble point
* 关键参数（采样策略）
* `last_event_seq`（快照覆盖到的最后事件序号）
然后 AEAD(LogKey) 加密，写入 `snapshots.bin`（同 LogRecord 格式，type=SNAP）。
## 7.2 何时写快照（建议）
* 每 **N 条事件**（例如 200）
* 或每 **T 秒**（例如 60s）
* 或关键事件后（rotate/disband）
> **MUST**：快照写入不应影响实时通信，必须可丢弃（失败不影响主功能）。
## 7.3 snapshot.idx（小索引，明文）
索引是一条条固定长度记录，追加写，便于快速定位最新快照：
```
IdxEntry (fixed 32 bytes):
- magic "SIDX" (4) (optional per file header)
- version (1)
- reserved(3)
- session_id (8)
- snap_seq (8) // snapshot record seq
- events_offset (8) // events.log offset at snapshot time
- snaps_offset (8) // snapshots.bin offset for this snapshot
```
> **SHOULD**：`snapshot.idx` 可明文，因为它只暴露 offset；如果你认为“有无快照/频率”也敏感，可把 idx 也加密，但工程复杂度会上升。
---
# 8) 恢复与复盘读取流程（掉电后可自愈）
## 8.1 打开一个 session 的复盘步骤
1. 读取 `meta.json`（可选）
2. 解封 `keys.bin` 得到 LogKey
3. 读取 `snapshot.idx`，找到最后一个可用快照（校验 snap record CRC/AEAD）
4. 从快照恢复状态
5. 从 `events.log` 的 `events_offset` 开始，顺序读取 record：
* magic 检查
* header/aad_crc32 检查
* trailer_crc32（若启用）
* AEAD 解密
* 解析 event → 回放更新状态
## 8.2 恢复扫描（文件损坏/截断）
当发现 CRC 不匹配或读到半条 record：
* 进入扫描模式：按字节滑动找下一个 `"TLOG"` magic
* 找到后尝试解析 header_len/body_len 是否合理
* CRC 通过则继续
> **MUST**：扫描必须有上限（避免在损坏文件上死循环）。
---
# 9) 文件滚动与保留策略（防止无限增长）
## 9.1 单 session 文件滚动
建议 `events.log` 达到阈值就切分：
* `events_0001.log`
* `events_0002.log`
同理快照。
阈值建议：
* 4MB / 16MB / 64MB 任选一个（看 SD/需求）
* 位置点多的话建议更小，便于导出与修复
## 9.2 Retention（保留期）
* `meta.json` 里记录 retention policy
* 定期清理 `YYYYMMDD` 目录
> **MUST**：用户应能“一键删除某次行动记录”（删除整个 `T_<session_id>` 目录）。
---
# 10) 最小实现版本（你可以先落地这个）
如果你要先快速跑起来，我建议 MVP：
* 只要三个文件：
* `meta.json`
* `keys.bin`
* `events.log`
* `events.log`：LogRecord + AEAD + trailer_crc32
* 不做快照、不做 idx
* 位置事件做强制降采样（例如 10s 一条）
后续再加：
* `snapshots.bin` + `snapshot.idx`
---
Reference in New Issue View Git Blame Copy Permalink