系统架构¶

系统概览¶

┌──────────────┐     HTTPS      ┌──────────────┐     PostgreSQL     ┌─────────┐
│  portal-web  │ ──────────────▶│   backend    │ ──────────────────▶│   RDS   │
│  (React SPA) │                │  (Go / Chi)  │                    └─────────┘
└──────────────┘                └──────┬───────┘
                                       │ MQTT (X.509 mTLS)
                                       │
                                ┌──────┴───────┐
                                │  AWS IoT Core │
                                └──────┬───────┘
                                       │ MQTT (X.509 mTLS)
                                       │
                                ┌──────┴───────┐
                                │   e-ink      │
                                │   devices    │
                                └──────────────┘

组件¶

后端（Go）¶

采用模块化单体架构，包含三个领域模块：

模块	职责
`auth`	JWT 认证、OAuth（Google/Apple）、会话管理
`billing`	Stripe 订阅、结账、发票
`iot`	MQTT 客户端、设备注册、心跳处理、命令下发、设备绑定

AWS IoT Core¶

设备通过 X.509 证书双向 TLS 连接。后端作为特权 MQTT 客户端（inklet-backend）连接，可以订阅所有设备主题并发布命令。

主题结构¶

主题	方向	用途
`inklet/dev/{thing}/up/heartbeat`	设备 → 后端	定时心跳
`inklet/dev/{thing}/up/state`	设备 → 后端	设备状态上报
`inklet/dev/{thing}/up/request_claim`	设备 → 后端	请求配对码
`inklet/dev/{thing}/down/cmd`	后端 → 设备	命令下发（text、claim_code、bound、unbound）

数据库模型¶

users
├── sessions (JWT 刷新令牌)
├── oauth_accounts (Google, Apple)
├── subscriptions (Stripe)
└── devices (通过 owner_id 绑定)
    └── device_commands (命令下发日志)

主要数据表：

表	主键	备注
`users`	UUID v4	Email + username 唯一
`devices`	UUID v7	`hw_id` 唯一，`thing_name` 唯一
`device_commands`	UUID v7	跟踪命令下发状态

设备生命周期¶

出厂 → NFC 标签写入签名后的 hw_id
       ↓
开机 → Fleet Provisioning（claim 证书 → 设备证书）
       ↓
心跳循环 → 后端在数据库中注册设备
       ↓
用户绑定设备（NFC 或配对码）
       ↓
后端下发命令 → 设备渲染到显示屏