242 lines
5.7 KiB
Markdown
242 lines
5.7 KiB
Markdown
# Yonexus v1 验收与回归清单
|
||
|
||
本清单服务于 `TASKLIST.md` 中的 YNX-1205。
|
||
|
||
目标：给后续开发、联调、回归提供一份统一基线，避免只凭“能跑起来了”判断完成度。
|
||
|
||
---
|
||
|
||
## 1. 范围
|
||
|
||
覆盖对象：
|
||
|
||
- `Yonexus.Protocol`
|
||
- `Yonexus.Server`
|
||
- `Yonexus.Client`
|
||
- Server ↔ Client 联调主流程
|
||
- pairing / auth / heartbeat / rule dispatch 关键失败路径
|
||
|
||
不覆盖：
|
||
|
||
- 多服务器拓扑
|
||
- 离线消息队列
|
||
- 管理 UI
|
||
- 复杂规则匹配
|
||
|
||
---
|
||
|
||
## 2. 协议层验收
|
||
|
||
### 2.1 builtin 编解码
|
||
|
||
必须验证：
|
||
|
||
- `builtin::{json}` 能正确编码
|
||
- `builtin::{json}` 能正确解码
|
||
- malformed builtin 消息会返回标准错误
|
||
- 未支持 builtin type 可被明确拒绝
|
||
|
||
### 2.2 rule message 解析
|
||
|
||
必须验证：
|
||
|
||
- `${rule}::${content}` 可被正确解析
|
||
- `${rule}::${sender}::${content}` 可被正确解析
|
||
- `content` 中包含 `::` 时不会被错误拆分
|
||
- `builtin` 不能作为普通 rule 注册
|
||
|
||
### 2.3 共享认证约束
|
||
|
||
必须验证：
|
||
|
||
- nonce 长度固定为 24
|
||
- timestamp 新鲜度窗口符合协议
|
||
- 签名输入序列化规则固定且可复用
|
||
|
||
---
|
||
|
||
## 3. Server 单体验收
|
||
|
||
### 3.1 启动与配置
|
||
|
||
必须验证：
|
||
|
||
- 缺失 `followerIdentifiers` 会 fail fast
|
||
- 缺失 `notifyBotToken` / `adminUserId` / `listenPort` 会 fail fast
|
||
- 非法 `listenPort` 会 fail fast
|
||
- 启动时会加载持久化记录并补齐 allowlist 初始记录
|
||
|
||
### 3.2 pairing
|
||
|
||
必须验证：
|
||
|
||
- 未配对 allowlisted client 进入 `pair_required`
|
||
- server 创建 pending pairing 记录
|
||
- pairing code 不通过 Yonexus WebSocket 下发
|
||
- pairing 通知失败时返回 `admin_notification_failed`
|
||
- 正确 pairing code 返回 `pair_success`
|
||
- 错误 pairing code 返回 `invalid_code`
|
||
- 过期 pairing code 返回 `expired`
|
||
|
||
### 3.3 auth
|
||
|
||
必须验证：
|
||
|
||
- paired client 可通过合法签名拿到 `auth_success`
|
||
- 非 allowlisted identifier 被拒绝
|
||
- 未配对 identifier 不可通过 auth
|
||
- public key 不匹配会失败
|
||
- stale/future timestamp 会失败
|
||
- nonce collision 会触发 `re_pair_required`
|
||
- 超过 `>10 attempts / 10s` 会触发 `re_pair_required`
|
||
|
||
### 3.4 liveness
|
||
|
||
必须验证：
|
||
|
||
- heartbeat 后更新 `lastHeartbeatAt`
|
||
- 7 分钟无心跳转为 `unstable`
|
||
- 11 分钟无心跳转为 `offline`
|
||
- `offline` 时发送 `disconnect_notice` 并断开连接
|
||
|
||
### 3.5 messaging
|
||
|
||
必须验证：
|
||
|
||
- 未认证 client 发送 rule message 会被拒绝
|
||
- 已认证 client 的消息会被重写为 `${rule}::${sender}::${content}`
|
||
- duplicate rule 注册默认失败
|
||
- `sendMessageToClient()` 对离线 client 返回失败
|
||
|
||
---
|
||
|
||
## 4. Client 单体验收
|
||
|
||
### 4.1 启动与本地状态
|
||
|
||
必须验证：
|
||
|
||
- 缺失 state 文件时可初始化最小状态
|
||
- 首次启动会自动生成 Ed25519 keypair
|
||
- 重启后不会重复生成 keypair
|
||
- 已有 secret 时可进入 auth 流程
|
||
|
||
### 4.2 连接与重连
|
||
|
||
必须验证：
|
||
|
||
- 可连接到可用的 server
|
||
- server 不可用时会按退避策略重连
|
||
- 手动断开不会误触发自动重连
|
||
- 成功重连后退避计数会重置
|
||
|
||
### 4.3 pairing / auth
|
||
|
||
必须验证：
|
||
|
||
- 收到 `pair_request` 后进入待确认状态
|
||
- 可提交 pairing code
|
||
- 收到 `pair_success` 后保存 secret
|
||
- 收到 `hello_ack(auth_required)` 后自动发 `auth_request`
|
||
- 收到 `auth_success` 后进入 authenticated
|
||
- 收到 `re_pair_required` 后清理本地 secret 并回退到 `pair_required`
|
||
|
||
### 4.4 heartbeat / dispatch
|
||
|
||
必须验证：
|
||
|
||
- authenticated 后启动 heartbeat loop
|
||
- 断线或未认证时停止 heartbeat loop
|
||
- `registerRule()` 拒绝 `builtin`
|
||
- `sendMessageToServer()` 拒绝 `builtin::` 和非法格式
|
||
|
||
---
|
||
|
||
## 5. 联调验收
|
||
|
||
### 5.1 首次配对闭环
|
||
|
||
必须通过：
|
||
|
||
1. Client 连接 Server
|
||
2. Client 发送 `hello`
|
||
3. Server 返回 `hello_ack(pair_required)`
|
||
4. Server 创建 pairing request 并发出管理员通知
|
||
5. Client 提交正确 pairing code
|
||
6. Server 返回 `pair_success`
|
||
7. Client 保存 secret
|
||
8. Client 发送 `auth_request`
|
||
9. Server 返回 `auth_success`
|
||
10. Client 进入 authenticated 并开始 heartbeat
|
||
|
||
### 5.2 正常重连闭环
|
||
|
||
必须通过：
|
||
|
||
1. 已配对 Client 重连
|
||
2. `hello_ack(auth_required)`
|
||
3. Client 发送合法 `auth_request`
|
||
4. Server 返回 `auth_success`
|
||
5. 心跳恢复正常
|
||
|
||
### 5.3 规则消息闭环
|
||
|
||
必须通过：
|
||
|
||
1. Client 认证成功
|
||
2. Client 调用 `sendRuleMessage()`
|
||
3. Server 收到并完成 sender rewrite
|
||
4. Server 规则处理器命中 exact match
|
||
5. Server 调用 `sendRuleMessageToClient()` 回发消息
|
||
6. Client 本地规则处理器收到消息
|
||
|
||
---
|
||
|
||
## 6. 失败路径回归矩阵
|
||
|
||
每次关键改动后，至少回归以下场景：
|
||
|
||
- pairing code 错误
|
||
- pairing 过期
|
||
- pairing 通知失败
|
||
- unsupported protocol version
|
||
- malformed builtin frame
|
||
- unknown identifier
|
||
- invalid signature
|
||
- stale timestamp
|
||
- future timestamp
|
||
- nonce collision
|
||
- handshake rate limit
|
||
- duplicate active connection 竞争
|
||
- 未认证连接发送 rule message
|
||
|
||
---
|
||
|
||
## 7. 自动化建议
|
||
|
||
建议的最小自动化分层：
|
||
|
||
- `Yonexus.Protocol`: 单元测试，锁定 codec / types / auth helpers
|
||
- `Yonexus.Server`: 单元测试，覆盖 runtime + pairing/auth/liveness 核心逻辑
|
||
- `Yonexus.Client`: 单元测试，覆盖 state/transport/runtime 主状态机
|
||
- Server + Client: 集成测试，覆盖 happy path 与关键失败路径
|
||
|
||
建议把通过条件固化为：
|
||
|
||
- `Yonexus.Protocol` 测试必须全绿
|
||
- Server / Client 类型检查必须全绿
|
||
- 新增联调测试后，happy path 与至少一组安全失败路径必须全绿
|
||
|
||
---
|
||
|
||
## 8. 当前对应关系
|
||
|
||
与 `TASKLIST.md` 对应关系：
|
||
|
||
- YNX-1101：协议单元测试
|
||
- YNX-1102：Server 单元测试
|
||
- YNX-1103：Client 单元测试
|
||
- YNX-1104：Server-Client 集成测试
|
||
- YNX-1105：失败路径测试矩阵
|
||
- YNX-1205：协议测试与验收清单（本文件）
|