trail-mate/docs/team/team_chat_protocol.md

# Team Chat 协议方案（方案 C，v0.1）

本文件描述“队伍聊天”协议的最小可实施方案，用于承载结构化消息： Text / Location / Command，并与 Team 安全域绑定，支持地图与态势联动。

---

1. 目标与范围

• 目标：让队伍聊天成为“可解析、可执行”的结构化消息流。
• 覆盖媒体类型：
  • Text：普通文本。
  • Location：位置分享，可在 Chat/GPS 地图渲染。
  • Command：指令类消息，可触发队伍行动提示与地图标注。
• 安全：仅队伍成员可解密，不依赖 Meshtastic 普通聊天频道。

前置条件（v0.2 调整）：

• 建队/入队不再通过 LoRa 或 NFC。
• 组队只在 5 米内的近距离场景发生，使用 ESP‑NOW 完成建队与密钥分发。
• LoRa 仅用于队内日常通信（Team Chat/Position/Track），不参与组队流程。

非目标：

• 不替换现有的普通聊天/广播消息。
• 不实现复杂可靠传输（v0.1 先做 best-effort）。

---

2. 端口与加密

• 新增端口：
  • TEAM_CHAT_APP = 303（在 modules/core_team/include/team/protocol/team_portnum.h 中定义）
• 加密方式：
  • 复用 TeamEncrypted envelope（team_wire.h）。
  • 从 team_psk 派生 team_chat key。
  • 建议在 TeamService::setKeysFromPsk() 中新增：
    • deriveKey(psk, "team_chat", keys.chat_key)

这样可实现“队伍聊天协议层隔离”，非队伍成员无法解密。

---

3. Payload 结构（v0.1）

3.1 通用头部

使用简洁 TLV 或固定头 + 变长 payload。建议固定头：

struct TeamChatHeader {
  uint8_t  version;    // =1
  uint8_t  type;       // 1=Text 2=Location 3=Command
  uint16_t flags;      // 预留
  uint32_t msg_id;     // 本地生成，防重放/去重
  uint32_t ts;         // 发送时间（unix）
  uint32_t from;       // 发送者 node_id
};

3.2 Text

struct TeamChatText {
  // UTF-8 text bytes
  bytes text;
};

3.3 Location

struct TeamChatLocation {
  int32_t lat_e7;
  int32_t lon_e7;
  int16_t alt_m;       // optional, 0=unknown
  uint16_t acc_m;      // optional, 0=unknown
  uint32_t ts;         // optional, 0=use header.ts
  uint8_t  source;     // 位置语义图标，见下方映射
  bytes    label;      // optional short label
};

source 映射（与当前固件实现一致）：

• 0：None / 普通位置（无语义图标）
• 1：AreaCleared
• 2：BaseCamp
• 3：GoodFind
• 4：Rally
• 5：Sos

3.4 Command

v0.1 仅做最小指令集，不做撤销/过期语义。

enum TeamCommandType : uint8_t {
  RallyTo = 1,   // 集结到目标点
  MoveTo  = 2,   // 前往目标点
  Hold    = 3    // 原地待命
};

struct TeamChatCommand {
  uint8_t  cmd_type;
  int32_t  lat_e7;      // 可选：用于 Rally/Move
  int32_t  lon_e7;
  uint16_t radius_m;    // 可选：集合半径
  uint8_t  priority;    // 0=normal 1=high
  bytes    note;        // 可选：简短备注
};

---

4. 发送与接收流程

4.1 发送

• UI 产生 Text/Location/Command。
• 编码为 TeamChatHeader + payload。
• 通过 TeamService::sendTeamChat()：
  • 使用 keys.chat_key 加密封装为 TeamEncrypted。
  • 通过 TEAM_CHAT_APP 发送（mesh_.sendAppData(...)）。

4.2 接收

• TeamService::processIncoming() 新增 TEAM_CHAT_APP 分支：
  • 解密 TeamEncrypted。
  • 解析 TeamChatHeader。
  • 触发 TeamChatEvent（新增 EventBus 类型）。
• UI 接收到 TeamChatEvent：
  • 追加到 team_ui_chatlog（新增类型字段）。
  • 若是 Location/Command，同步更新地图/GPS 页标注。

---

5. 与现有代码的改动点

最小改动清单（v0.1）：

1. 协议与端口

   • modules/core_team/include/team/protocol/team_portnum.h 新增 TEAM_CHAT_APP = 303
   • 新增 team_chat.h/.cpp（编码/解码）

2. 密钥派生

   • TeamKeys 增加 chat_key
   • TeamService::setKeysFromPsk() 中派生 "team_chat"

3. TeamService

   • 新增 sendTeamChat(...)
   • processIncoming() 处理 TEAM_CHAT_APP

4. 事件总线

   • sys/event_bus.h 新增 TeamChatEvent

5. UI / 存储

   • team_ui_chatlog_append() 扩展为结构化消息（type + payload）
   • Contacts/Team 聊天页改用 TeamChat 数据源渲染卡片

---

6. 兼容性与过渡

• 保留现有普通聊天：
  • Primary/Secondary 继续用 TEXT_MESSAGE_APP
• Team Chat 作为独立通道：
  • 不影响普通聊天历史与通知
  • 可以逐步替换 Team 页的会话来源
• Location.source 兼容建议（PC/上位机）：
  • 若收到未知 source（不在 0..5），按普通 Location 渲染，不得丢弃整条消息
  • 继续使用坐标与时间字段，label 存在时可用于展示
  • 建议保留原始 source 值，便于前向兼容

---

7. v0.1 已确定事项

• ACK/送达：不需要（尽力而为）。
• Command 撤销/过期：不支持。
• 地图交互：收到消息只弹系统通知；弹窗由 Chat 会话中选中地图标注后触发，显示该位置瓦片地图的裁剪图。
• 组队模式 GPS：从 posring.log 渲染队员位置。

8. 版本策略

• TeamChatHeader.version = 1
• 后续扩展通过 flags 或新 type 兼容

---

附录 A：ESP‑NOW 建队与入队（v0.2）

目标：减少步骤与不稳定环节，近距离（≤5m）快速建队。

A1. 角色与约束

• 场景：所有人同一房间/范围 ≤5m。
• 介质：ESP‑NOW（2.4GHz），不再使用 LoRa/NFC。
• 结果：成员收到 team_psk + team_id + key_id + epoch，之后用 LoRa 收发 Team 协议。

A2. 简化流程

Leader

1. Create Team → 打开 “Pairing (ESP‑NOW)” 窗口（默认 120s）。
2. 接收成员 Join 请求（可“Auto‑accept”或手动 Accept）。
3. 发送 KeyDist（ESP‑NOW）给新成员。

Member

1. Join Team → Nearby Teams（ESP‑NOW 扫描）选择目标。
2. 发送 Join 请求并等待 KeyDist。
3. 收到 KeyDist 后进入已加入状态。

A3. ESP‑NOW 消息（建议）

PAIR_BEACON { team_id_short, team_id, epoch, key_id, leader_id, expires_at }
PAIR_JOIN   { team_id, member_id, member_pub, nonce }
PAIR_ACCEPT { team_id, member_id, ok, nonce }
PAIR_KEY    { team_id, key_id, epoch, team_psk_encrypted, nonce }

说明：

• team_psk_encrypted 可用临时会话密钥（由 member_pub + leader 私钥派生）加密。
• nonce 用于关联请求与防重放。
• 所有 ESP‑NOW 包都只在 Pairing 窗口内处理。

A4. 与 Team Chat 的关系

• ESP‑NOW 仅负责“建队/入队/密钥分发”。
• 完成后使用 LoRa 的 Team 协议（TEAM_CHAT / TEAM_POS / TEAM_TRACK / …）。