ACCEPTANCE.md

@@ -0,0 +1,241 @@
+# 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：协议测试与验收清单（本文件）

TASKLIST.md

@@ -1041,13 +1041,29 @@
 ## Phase 12 — 文档与交付
 
 ### YNX-1201 补齐 Server README
+**状态**
+- [x] 已完成（2026-04-08）
+
 **目标**
 - Server 仓库可独立被安装与使用
 
+**已完成内容**
+- 已补齐 `Yonexus.Server/README.md`
+- 已写明当前实现范围、配置字段、启动/连接流程、公开 API、持久化语义与开发方式
+- 已明确当前限制项（真实 Discord DM、测试覆盖、生命周期集成等），避免 README 过度承诺
+
 ### YNX-1202 补齐 Client README
+**状态**
+- [x] 已完成（2026-04-08）
+
 **目标**
 - Client 仓库可独立被安装与使用
 
+**已完成内容**
+- 已补齐 `Yonexus.Client/README.md`
+- 已写明配置模型、启动/配对/认证流程、公开 API、本地 state 结构与开发方式
+- 已明确当前限制项（测试、配对输入 UX、生命周期集成等），方便后续交接和联调
+
 ### YNX-1203 输出部署文档
 **目标**
 - 写清楚单主多从部署方式、配置示例、配对流程
@@ -1057,9 +1073,17 @@
 - 写清楚常见报错、状态含义、恢复步骤
 
 ### YNX-1205 输出协议测试与验收清单
+**状态**
+- [x] 已完成（2026-04-08）
+
 **目标**
 - 让后续改动有统一回归基线
 
+**已完成内容**
+- 已新增 `ACCEPTANCE.md`
+- 已按协议层、Server、Client、联调、失败路径回归矩阵拆分验收项
+- 已把 `YNX-1101`~`YNX-1105` 与具体验收/测试目标建立对应关系，方便后续补自动化测试时直接对照
+
 ---
 
 ## 推荐执行顺序（最小闭环）