update

2026-05-04 22:42:00 +08:00
parent 985002c96d
commit 79f4055959
14 changed files with 1440 additions and 4 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -272,6 +272,9 @@ chrono = "0.4"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

+# 串口传输 — UART/USB-Serial 通信
+serialport = "4"
+
 # FFI 类型支持（C 类型兼容）
 libc = "0.2"

@@ -292,6 +295,7 @@ env_logger = "0.11"
 | `log` / `fern` | 日志抽象层 + 日志前端，方便调试 | 推荐 |
 | `chrono` | 高精度时间戳（微秒/纳秒级） | 推荐 |
 | `serde` / `serde_json` | 配置文件序列化、调试输出 | 推荐 |
+| `serialport` | 串口打开、读写、清空缓冲区，承载设备 UART 协议 | **核心** |
 | `libc` | FFI 类型兼容（`c_char`, `c_int` 等） | **FFI 必需** |
 | `uuid` | 设备唯一标识符生成 | 可选 |

@@ -1417,7 +1421,120 @@ make

 ---

-## 20. 安全性考虑
+## 20. 当前 Rust Core 接口骨架
+
+当前阶段只定义接口和数据边界，具体读写、CRC、解析、线程生命周期后续实现。
+
+### 20.1 模块职责
+
+| 模块 | 文件 | 职责 |
+|------|------|------|
+| 数据类型 | `src/types.rs` | 力向量、模组枚举、合力、分布力、采样帧、模组错误 |
+| 配置 | `src/config.rs` | 设备地址、采样队列容量、超时、丢弃策略、设备信息 |
+| 错误 | `src/error.rs` | SDK 错误枚举和 C ABI 错误码 |
+| 传输层 | `src/transport.rs` | `SerialTransport` trait，屏蔽具体串口实现 |
+| 协议层 | `src/protocol.rs` | 请求/应答帧结构、`ProtocolCodec` trait、CRC 接口 |
+| 寄存器层 | `src/register.rs` | 地址常量、寄存器元信息、原始字节到业务类型的解析接口 |
+| 通道层 | `src/channel.rs` | sample/command/event 三类 channel 和丢弃策略 |
+| 数据流 | `src/stream.rs` | `StreamController` trait，定义轮询/自动回传模式 |
+| 设备层 | `src/device.rs` | `EskinDevice` trait，聚合 transport、codec、channel |
+| FFI 边界 | `src/ffi/mod.rs` | C ABI handle、版本和基础生命周期接口草案 |
+
+### 20.2 核心接口
+
+```rust
+pub trait SerialTransport {
+    fn open(&mut self) -> Result<(), SdkError>;
+    fn close(&mut self) -> Result<(), SdkError>;
+    fn is_open(&self) -> bool;
+    fn write(&mut self, data: &[u8]) -> Result<usize, SdkError>;
+    fn read(&mut self, buf: &mut [u8], timeout: chrono::Duration) -> Result<usize, SdkError>;
+    fn flush_rx(&mut self) -> Result<(), SdkError>;
+}
+
+pub trait ProtocolCodec {
+    fn encode_read_request(&self, request: &ReadRequest) -> Result<Vec<u8>, SdkError>;
+    fn encode_write_request(&self, request: &WriteRequest) -> Result<Vec<u8>, SdkError>;
+    fn decode_read_response(&self, frame: &[u8]) -> Result<ReadResponse, SdkError>;
+    fn decode_write_response(&self, frame: &[u8]) -> Result<WriteResponse, SdkError>;
+    fn decode_stream_frame(&self, frame: &[u8]) -> Result<ProtocolFrame, SdkError>;
+    fn crc8(&self, data: &[u8]) -> u8;
+}
+
+pub trait RegisterMap {
+    fn device_info_registers(&self) -> &'static [RegisterSpec];
+    fn distribution_register(&self, module: SensorModule) -> Result<RegisterSpec, SdkError>;
+    fn parse_device_info(&self, raw: &[u8]) -> Result<DeviceInfo, SdkError>;
+    fn parse_distribution_force(
+        &self,
+        module: SensorModule,
+        raw: &[u8],
+    ) -> Result<DistributionForce, SdkError>;
+}
+
+pub trait EskinDevice {
+    fn open(&mut self) -> Result<(), SdkError>;
+    fn close(&mut self) -> Result<(), SdkError>;
+    fn state(&self) -> DeviceState;
+    fn device_info(&self) -> Result<DeviceInfo, SdkError>;
+    fn apply_config(&mut self, config: DeviceConfig) -> Result<(), SdkError>;
+    fn start_stream(&mut self) -> Result<(), SdkError>;
+    fn stop_stream(&mut self) -> Result<(), SdkError>;
+    fn read_sample(&self, timeout_ms: u32) -> Result<FingerSample, SdkError>;
+    fn read_event(&self, timeout_ms: u32) -> Result<DeviceEvent, SdkError>;
+    fn read_register(&mut self, addr: u32, length: u16) -> Result<Vec<u8>, SdkError>;
+    fn write_register(&mut self, addr: u32, data: &[u8]) -> Result<u16, SdkError>;
+}
+```
+
+### 20.3 数据流流程图
+
+```mermaid
+flowchart TD
+    App[Rust/C/C++ App] --> Device[EskinDevice]
+    Device --> Channel[ChannelManager]
+    Device --> Codec[ProtocolCodec]
+    Device --> Register[RegisterMap]
+    Device --> Transport[SerialTransport]
+    Transport --> Serial[UART / USB-Serial]
+    Serial --> Hardware[Eskin Finger Device]
+
+    App -->|open| Device
+    Device -->|open port| Transport
+    Device -->|read device info registers| Register
+    Register -->|ReadRequest| Codec
+    Codec -->|frame bytes| Transport
+    Transport -->|response bytes| Codec
+    Codec -->|ReadResponse| Register
+    Register -->|DeviceInfo| Device
+
+    App -->|start_stream| Device
+    Device -->|DeviceCommand::StartStream| Channel
+    Device -->|poll or auto receive| Transport
+    Transport -->|raw frame| Codec
+    Codec -->|ProtocolFrame| Register
+    Register -->|FingerSample| Channel
+    Channel -->|sample_rx| App
+    Channel -->|event_rx| App
+```
+
+### 20.4 设备生命周期
+
+```mermaid
+stateDiagram-v2
+    [*] --> Closed
+    Closed --> Open: open()
+    Open --> Streaming: start_stream()
+    Streaming --> Open: stop_stream()
+    Open --> Closed: close()
+    Streaming --> Error: transport/protocol error
+    Open --> Error: transport/protocol error
+    Error --> Closed: close()
+```
+
+---
+
+## 21. 安全性考虑

 1. **空指针检查**：所有 C API 入口检查指针非空
 2. **状态检查**：操作前检查设备状态（是否已连接、是否正在采集等）
@@ -1426,4 +1543,4 @@ make
 5. **线程安全**：使用 `AtomicBool`、`AtomicU64`、`AtomicU32` 管理共享状态
 6. **资源泄漏**：C++ RAII 保证析构时释放；C API 提供 `eskin_close()`
 7. **panic 安全**：Rust FFI 函数不 panic，所有 panic 用 `catch_unwind` 捕获
-8. **超时保护**：所有串口读操作带超时，避免永久阻塞
+8. **超时保护**：所有串口读操作带超时，避免永久阻塞