From 2bfd69c96b3d3159d86ebbe62f036a013db9d06c Mon Sep 17 00:00:00 2001
From: stu2not <stu2not@stu2notdeMac-mini.local>
Date: Sun, 20 Sep 2026 11:31:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E8=AE=BE=E5=A4=87?=
 =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96=E5=9B=9E=E6=89=A7=E4=B8=AD=E7=9A=84?=
 =?UTF-8?q?ICCID?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/architecture/02-device-bootstrap.md | 33 ++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/docs/architecture/02-device-bootstrap.md b/docs/architecture/02-device-bootstrap.md
index 759185c..a32b003 100644
--- a/docs/architecture/02-device-bootstrap.md
+++ b/docs/architecture/02-device-bootstrap.md
@@ -3,7 +3,8 @@
 ## Purpose
 
 Device bootstrap maps a factory IMEI to Banban's internal `device_id` and
-`serial_number`. Devices do not need to know those IDs before first bootstrap.
+`serial_number`, and returns the associated ICCID for downstream SIM/traffic
+binding. Devices do not need to know those IDs before first bootstrap.
 
 ## Flow
 
@@ -37,11 +38,39 @@ sequenceDiagram
       Handler-->>MQTT: device/{imei}/event_resp status=failed
     end
     Init->>Mapping: UPDATE status=activated, activated_at=now
-    Handler-->>MQTT: device/{imei}/event_resp with device_id and device_sn
+    Handler-->>MQTT: device/{imei}/event_resp with device_id, device_sn, and iccid
     MQTT-->>Device: Receive assigned identity
   end
 ```
 
+## Successful Response
+
+When the IMEI mapping and its authoritative ICCID association are available,
+the handler returns the assigned identity and ICCID in the `msg_id=012`
+response:
+
+```json
+{
+  "msg_id": "012",
+  "params": {
+    "device_id": "TalkingQ_ZHWK00002110",
+    "device_sn": "TQ_ZHWK000000002110",
+    "iccid": "898604E91123D1334901"
+  }
+}
+```
+
+The `iccid` value is the canonical, full ICCID used by the downstream SIM and
+traffic service. It must come from an authoritative IMEI-to-ICCID provisioning
+record or a validated device report; it must not be derived from the IMEI.
+Successful bootstrap requires a non-empty, valid ICCID. If the ICCID cannot
+be resolved or fails consistency validation, the handler must return the
+existing `msg_id=012` failure response instead of returning a partial success.
+
+Adding `params.iccid` is an additive response-field change. Devices that ignore
+unknown JSON fields remain compatible, while strict firmware parsers need a
+protocol/version capability check before this response is enabled for them.
+
 ## Data Model
 
 ```mermaid