ljwx-health/ljwx-boot/scripts/test-data-factory/DEVICE_BINDING_V2_TEST_GUIDE.md

Device Binding V2 API Testing Guide

Created: 2026-02-07 Purpose: Test Phase 0-3 device binding APIs with signature verification Related: device-binding-phase3-implementation-report.md

📋 Overview

This guide provides instructions for testing the Device Binding V2 APIs implemented in Phase 0-3.

Test Coverage

Phase	Feature	Test Coverage
P0-1	Signature Verification	✅ Automated
P1-1	Status Query	✅ Automated
P1-2	Approve/Reject	✅ Automated
P2-1	Batch Approve	⚠️ Manual
P2-2	User/Admin Unbind	✅ Automated
P3-2	SSE Push	⚠️ Manual
P3-3	Confirm Token	⚠️ Manual

---

🚀 Quick Start

Prerequisites

1. ljwx-boot running on http://localhost:9998
2. Valid SaToken from login
3. Python 3.8+ with requests library

Get SaToken

# Login and get token
curl -X POST http://localhost:9998/auth/user_name \
  -H "Content-Type: application/json" \
  -d '{"userName":"admin","password":"80a3d119ee1501354755dfc3c4638d74c67c801689efbed4f25f06cb4b1cd776"}' \
  -v 2>&1 | grep -i satoken

# Look for: satoken: <your_token_here>

Run Automated Test

cd ljwx-boot/scripts/test-data-factory

# Run full flow test
python test_device_binding_v2.py \
  --base-url http://localhost:9998 \
  --token <your_satoken> \
  --device-sn TEST_DEVICE_001 \
  --device-secret test_secret_001

Expected Output:

============================================================
Starting Device Binding V2 Full Flow Test
============================================================

[Test 1] Request Device Binding
ℹ️  Testing GET /api/v2/device/challenge/TEST_DEVICE_001
✅ Challenge received: a1b2c3d4e5f6g7h8i9j0...
ℹ️  Signature calculated: 9f8e7d6c5b4a3f2e1d0c...
ℹ️  Testing POST /api/v2/device/bind/request for TEST_DEVICE_001
✅ Binding requested: requestId=xxx, approvalId=yyy

[Test 2] Query Approval Status
ℹ️  Testing GET /api/v2/device/bind/status/xxx
✅ Status: PENDING

[Test 3] Approve Binding
ℹ️  Testing POST /api/v2/device/bind/approve/yyy
✅ Binding approved successfully

[Test 4] Verify Status Changed to APPROVED
ℹ️  Testing GET /api/v2/device/bind/status/xxx
✅ Status: APPROVED

[Test 5] User Self-Unbind Device
ℹ️  Testing POST /api/v2/device/bind/unbind for TEST_DEVICE_001
✅ Device unbound successfully

============================================================
✅ Device Binding V2 Full Flow Test PASSED
============================================================

---

📝 Manual Test Cases

Test Case 1: Signature Verification

Objective: Verify HMAC-SHA256 signature validation

# Step 1: Get challenge
curl -X GET http://localhost:9998/api/v2/device/challenge/TEST_DEVICE_001

# Response:
# {
#   "code": 200,
#   "data": {
#     "challenge": "a1b2c3d4e5f6g7h8",
#     "expiresIn": 300
#   }
# }

# Step 2: Calculate signature (Python)
import hmac, hashlib
device_secret = "test_secret_001"
challenge = "a1b2c3d4e5f6g7h8"
device_sn = "TEST_DEVICE_001"
message = challenge + device_sn
signature = hmac.new(device_secret.encode(), message.encode(), hashlib.sha256).hexdigest()
print(signature)

# Step 3: Request binding
curl -X POST http://localhost:9998/api/v2/device/bind/request \
  -H "Content-Type: application/json" \
  -H "satoken: <your_token>" \
  -d '{
    "deviceSn": "TEST_DEVICE_001",
    "challenge": "a1b2c3d4e5f6g7h8",
    "signature": "<calculated_signature>"
  }'

Expected: code: 200, status: PENDING

---

Test Case 2: Batch Approve with Confirm Token

Objective: Test P3-3 two-step batch approval

# Assume you have 3 pending approvals: approval_id_1, approval_id_2, approval_id_3

# Step 1: Generate confirm token
curl -X POST http://localhost:9998/api/v2/device/bind/batch-approve/generate-token \
  -H "Content-Type: application/json" \
  -H "satoken: <your_token>" \
  -d '{
    "approvalIds": ["approval_id_1", "approval_id_2", "approval_id_3"]
  }'

# Response:
# {
#   "code": 200,
#   "data": {
#     "confirmToken": "uuid-token-here",
#     "expiresIn": 300,
#     "count": 3
#   }
# }

# Step 2: Batch approve with token (within 5 minutes)
curl -X POST http://localhost:9998/api/v2/device/bind/batch-approve-with-confirm \
  -H "Content-Type: application/json" \
  -H "satoken: <your_token>" \
  -d '{
    "approvalIds": ["approval_id_1", "approval_id_2", "approval_id_3"],
    "actionType": "APPROVE",
    "comments": "Batch approved",
    "confirmToken": "uuid-token-here"
  }'

# Expected: successCount: 3, failedCount: 0

---

Test Case 3: SSE Real-time Push

Objective: Test P3-2 Server-Sent Events

Using curl:

# Terminal 1: Open SSE connection
curl -N -H "satoken: <your_token>" \
  http://localhost:9998/api/v2/device/bind-events/stream

# Terminal 2: Request a binding
curl -X POST http://localhost:9998/api/v2/device/bind/request \
  -H "Content-Type: application/json" \
  -H "satoken: <your_token>" \
  -d '{...}'

# Terminal 1 should receive:
# event: binding_status_change
# data: {"requestId":"xxx","status":"PENDING",...}

# Terminal 2: Approve the binding
curl -X POST http://localhost:9998/api/v2/device/bind/approve/yyy \
  -H "satoken: <your_token>" \
  -d '{"comments":"test"}'

# Terminal 1 should receive:
# event: approval_result
# data: {"approvalId":"yyy","result":"APPROVED",...}

Using JavaScript (Browser):

const eventSource = new EventSource('http://localhost:9998/api/v2/device/bind-events/stream', {
  headers: { 'satoken': '<your_token>' }
});

eventSource.addEventListener('binding_status_change', (event) => {
  console.log('Binding status changed:', JSON.parse(event.data));
});

eventSource.addEventListener('approval_result', (event) => {
  console.log('Approval result:', JSON.parse(event.data));
});

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
};

---

🔍 API Reference

Complete API List

API	Method	Path	Auth	Description
Get Challenge	GET	/api/v2/device/challenge/{deviceSn}	No	Get challenge for signature
Request Binding	POST	/api/v2/device/bind/request	Yes	Request binding with signature
Query Status	GET	/api/v2/device/bind/status/{requestId}	Yes	Query approval status
Approve	POST	/api/v2/device/bind/approve/{approvalId}	Yes	Approve binding
Reject	POST	/api/v2/device/bind/reject/{approvalId}	Yes	Reject binding
Batch Approve	POST	/api/v2/device/bind/batch-approve	Yes	Batch approve
Generate Token	POST	/api/v2/device/bind/batch-approve/generate-token	Yes	Generate confirm token
Batch Confirm	POST	/api/v2/device/bind/batch-approve-with-confirm	Yes	Batch approve with token
User Unbind	POST	/api/v2/device/bind/unbind	Yes	User self-unbind
Admin Unbind	POST	/api/v2/device/bind/force-unbind	Yes	Admin force unbind
SSE Stream	GET	/api/v2/device/bind-events/stream	Yes	Real-time event stream

Detailed API Specs

See api-map.yaml section device_binding_v2 for complete request/response schemas.

---

🐛 Troubleshooting

Issue: "Challenge invalid or expired"

Cause: Challenge expired (5-minute TTL) or already used

Solution: Get a new challenge before each request

Issue: "Signature verification failed"

Cause: Incorrect signature calculation

Solution:

1. Verify device secret is correct
2. Ensure message = challenge + deviceSn (no spaces)
3. Use HMAC-SHA256, not plain SHA256

Issue: "Confirm token invalid or expired"

Cause: Token expired (5-minute TTL) or already used (anti-replay)

Solution: Generate new token for each batch operation

Issue: "SSE connection closed"

Cause: 30-minute timeout or network issue

Solution: Implement auto-reconnect with exponential backoff

---

📊 Performance Benchmarks

Operation	P95 Latency	Notes
Get Challenge	< 50ms	Redis read
Request Binding	< 200ms	Signature verification + DB write
Query Status	< 100ms	DB read
Approve	< 150ms	CAS update + event publish
Batch Approve	< 500ms	Depends on batch size
SSE Event Delivery	< 100ms	In-memory push

---

📚 Related Documentation

• Device Binding Flow v2.3
• Phase 3 Implementation Report
• API Map
• Test Recipe

---

Last Updated: 2026-02-07