# ReadCard 程序流程文档

## 启动流程

```
main()
  │
  ├─ OpenPort(port, baudrate)          打开串口
  ├─ SetDevice(device)                 设置设备名
  ├─ StorePasswd(password)             存储扇区密码表
  │
  ├─ InitSequence()                    初始化序列（同步阻塞）
  │   ├─ StopCard()                    → 等待应答 (3s超时)
  │   ├─ SetPasswd(1)                  → 等待应答
  │   ├─ SetPasswd(2)                  → 等待应答
  │   ├─ SetPasswd(3)                  → 等待应答
  │   ├─ SetPasswd(4)                  → 等待应答
  │   ├─ SetPasswd(5)                  → 等待应答
  │   ├─ SetPasswd(10)                 → 等待应答
  │   └─ FindCard()                    发出首次寻卡, AutoFind=true
  │      (任一步失败 → 程序退出)
  │
  ├─ 启动 sub_thread                   DDS命令接收线程
  └─ 启动 pub_thread                   设备响应发布线程
```

## 运行时两个线程

```
sub_thread (DDS命令接收)                pub_thread (设备响应发布, 100ms周期)
  │                                      │
  │  收到 ReadCardReq                    │  HandleDeviceMsg()
  │  → HandleDdsMsg()                    │  → RecvDeviceMsg() 读串口
  │                                      │  → ParseDeviceMsg() 解析响应
  │                                      │  → 有数据则 writer_->write() 发布DDS
  │                                      │
  │                                      │  AutoFindTick()
  │                                      │  → AutoFind开启时按间隔发FindCard
```

## DDS 对外接口

### 订阅 Topic: `ReadCardReq`

| 命令 | 参数 | 行为 |
|------|------|------|
| `"find"` | 无 | 清空重复卡记录，启动自动寻卡 |
| `"read"` | `{扇区号}` | 暂停自动寻卡，读指定扇区 |
| `"write"` | `{扇区号, 数据...}` | 暂停自动寻卡，写指定扇区 |
| `"stop"` | 无 | 停止自动寻卡 |
| `"beep"` | `{时长}` 或空 | 暂停自动寻卡，蜂鸣(默认0x0F) |
| `"reset"` | 无 | 暂停自动寻卡，清空串口缓冲区 |

### 发布 Topic: `ReadCardRsp`

| 响应 | 内容 | 说明 |
|------|------|------|
| `"find"` | 成功:`{卡号4字节}` 失败:`{错误码}` | 寻卡结果 |
| `"read"` | 成功:`{数据17字节}` 失败:`{错误码}` | 读卡结果 |
| `"write"` | `{状态码}` | 写卡结果 |
| `"stop"` | `{状态码}` | 停止结果 |
| `"beep"` | `{状态码}` | 蜂鸣结果 |

## 自动寻卡状态机

```
                    ┌──────────────────────────┐
                    │     AutoFind = true       │
                    │   (自动寻卡运行中)         │
                    │                          │
                    │  AutoFindTick按间隔       │
                    │  发送FindCard             │
                    └──┬────────┬───────────┬──┘
                       │        │           │
              寻卡失败  │  寻卡成功(新卡)│    寻卡成功(重复卡)
           interval=500ms│  AutoFind=false│    interval=5000ms
              继续重试   │  发布卡号      │    不发布,继续寻卡
                       │        │           │
                       │        ▼           │
                       │   ┌────────────┐   │
                       │   │AutoFind=false│   │
                       │   │(等待业务处理)│   │
                       │   └──┬─────┬───┘   │
                       │      │     │       │
                       │  DDS下发   DDS下发   │
                       │  read     write    │
                       │      │     │       │
                       │      ▼     ▼       │
                       │   设备响应返回       │
                       │   AutoFind=true     │
                       │   interval=500ms    │
                       │      │              │
                       └──────┘──────────────┘
                    (回到自动寻卡状态)

  特殊命令:
    "stop"  → AutoFind=false, 完全停止寻卡
    "find"  → AutoFind=true, 清空PreCard, 重新开始寻卡
    "beep"/"reset" → AutoFind=false, 暂停寻卡(需DDS重发find恢复)
```

## 定时间隔策略

| 时机 | 间隔 | 说明 |
|------|------|------|
| 发送FindCard后 | 5000ms | 超时保护，无应答则重发 |
| 寻卡失败 | 500ms | 快速重试 |
| 重复刷卡 | 5000ms | 同一张卡不重复处理 |
| 读写完成恢复 | 500ms | 业务结束后快速恢复寻卡 |

## 启动参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--domain` | 0 | DDS域ID |
| `--interface` | serial | 接口类型 |
| `--port` | ttyS1 | 串口端口 |
| `--baudrate` | 9600 | 波特率 |
| `--device` | RC522 | 设备名称 |
| `--version` | - | 显示版本号 |
| `--help` | - | 显示帮助信息 |