# 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 与至少一组安全失败路径必须全绿

推荐的 umbrella 仓库最小回归入口：

```bash
./scripts/validate-v1.sh
```

该脚本会顺序执行：
- `Yonexus.Protocol`: `npm run test`
- `Yonexus.Server`: `npm run check && npm run test`
- `Yonexus.Client`: `npm run check && npm run test`

---

## 8. 当前对应关系

与 `TASKLIST.md` 对应关系：

- YNX-1101：协议单元测试
- YNX-1102：Server 单元测试
- YNX-1103：Client 单元测试
- YNX-1104：Server-Client 集成测试
- YNX-1105：失败路径测试矩阵
- YNX-1205：协议测试与验收清单（本文件）