distributed/README.md

配套源码，运行方法见同目录 README。返回实验总览。

# Raft 与容错 KV 教学模型

只依赖 Python 3.10+ 标准库。

```sh
cd labs/distributed
python3 -m unittest -v
python3 raft_model.py
```

包含固定成员选举、任期与投票、日志新旧检查、前缀冲突替换、当前任期提交限制、状态机去重，以及分区和重启场景。KV 命令是 `(client_id, request_id, operation, key, value)`；同一请求 ID 必须对应同一命令。示例 reads 也走复制日志。

`submit` 返回 False 表示调用者没有确认成功，不证明命令一定没有执行或永远不会提交。超时重试必须复用请求 ID。

提交的命令与返回结果经过深拷贝，模拟 RPC 序列化后的值边界。调用者不能通过修改原 Python 字典、列表或返回对象，绕过日志直接改某个副本。`add` 用数值，`put/get` 可演示可复制的数据值；请求身份本身应可哈希，且同一身份的命令不得改变。

所有消息由测试驱动同步执行，使用全前缀复制；没有真实网络、随机调度、线程竞争、磁盘 fsync、快照或成员变更。`restart` 仅在 Python 进程内保留所谓持久字段，用来模拟崩溃边界。本模型不能证明真实多线程分布式实现的正确性，也不兼容 MIT 官方自动评分接口。

单节点重启可向仍在运行的 leader 重新获知提交进度。若所有节点都重启，易失的 commitIndex 全部归零；重新选举后需提交本任期条目（例如 `submit(leader, None)`）才能建立提交屏障并回放旧前缀。本模型不自动追加 no-op，也不运行自动选举计时器。

当前有 16 项测试，包括短 AppendEntries 不错误提交额外后缀、全量重启后的 no-op 与去重恢复、结果未知后继续提交、重复读的原结果，以及输入/返回值的隔离。

练习：增加请求/回复消息队列并打乱顺序；实现 nextIndex 回退；把 term/vote/log 原子保存到磁盘；在测试中加入旧回复；设计一个会在无多数派时误回复成功的 bug 并使测试捕获它。不要直接把本教学代码用于真实服务。