KeyBoard_QT/docs/host_com_rebuild.md

# Host COM Rebuild

## Goal

Keep the COM layer small, explicit, and easy to teach.

The COM layer should:

- define packet types and payload structures
- build full wire frames
- parse full wire frames
- parse typed packet payloads

The COM layer should not:

- enumerate devices
- open ports
- own handshake state
- own UI state

## Current file roles

### `Com_PbCodec.h/.cpp`

Owns the protobuf-side wrapper:

- full protobuf frame serialize / parse
- checksum validation
- typed helper entry points like hello request / response

### `keyboard.pb.h/.cc`

Own the generated protocol model:

- outer `CdcFrame`
- business `CdcPacketBody`
- all message definitions

## Completed nodes

### Node 1: protobuf thin wrapper

Files added in this step:

- `KeyBorad/KeyBorad/COM/Com_PbCodec.h`
- `KeyBorad/KeyBorad/COM/Com_PbCodec.cpp`

Design notes:

- stop expanding hand-written typed payload logic
- let protobuf generated code own message encode/decode
- keep only a thin Qt-friendly wrapper

Implemented behavior:

- serialize a full `CdcFrame`
- parse and validate a full `CdcFrame`
- build `HelloReq` using generated protobuf types
- parse `HelloRsp` using generated protobuf types

### Node 2: remove legacy manual codec

Files removed in this step:

- `KeyBorad/KeyBorad/COM/Com_Cdc.h`
- `KeyBorad/KeyBorad/COM/Com_CdcEncode.h`
- `KeyBorad/KeyBorad/COM/Com_CdcEncode.cpp`
- `KeyBorad/KeyBorad/COM/Com_CdcDecode.h`
- `KeyBorad/KeyBorad/COM/Com_CdcDecode.cpp`

Design notes:

- no dual path
- no hand-written payload encode/decode path left behind
- protobuf is now the only packet encode/decode direction

Implemented behavior:

- checksum moved into `Com_PbCodec.cpp`
- old manual packet structs and old codec files removed

## COM done criteria

For the current project stage, COM is considered done when:

1. the protocol source is the `.proto` file
2. generated `.pb.*` files exist
3. `Com_PbCodec` provides thin project-facing helpers
4. no legacy hand-written packet codec remains