Skip to content

Latest commit

 

History

History
792 lines (589 loc) · 45.8 KB

system-contract.md

File metadata and controls

792 lines (589 loc) · 45.8 KB

系统契约

状态:当前软件规范。 本文件是 HTTP/API、协议、会话、持久化、配置与运行时行为的唯一规范来源。产品目的和关卡教学意图以产品与关卡意图为准;验证方式和验收证据以验证为准。

本文档规定 Aster Archive 当前已实现关卡及运行能力的软件契约,用于指导实现、测试、部署与验收。

本文档采用“目标规格”立场:实现或测试与本文件不一致时,不得反向修改契约;应先提出明确变更并由维护者决定。

1. 引言

1.1 目的

本文档用于明确 Aster Archive 的软件行为、接口边界、数据约束、运行约束与验收口径,供开发、测试和维护共用。

1.2 适用范围

本规格覆盖以下内容:

  • 站点首页、起始说明页与更新页
  • 第 01 关至第 26 关主线所需的页面、资源与后端接口
  • 健康检查、日志、配置加载与静态资源服务
  • 第 15、17、21 关等协议型能力
  • 第 25、26 关等状态型复杂交互关卡
  • 与上述内容直接相关的测试和验收要求

1.3 文档边界

  • 对纯静态关卡,本文档只保留软件层需要长期维护的高层行为约束,不逐页展开 HTML 细节。
  • 对有后端或协议行为的关卡,本文档提供可实现、可测试、可验收的严格规格。
  • 题面文案、叙事氛围和解法细节不在本文档中逐字冻结;其上位约束由产品与关卡意图负责。

1.4 术语

  • flag:下一关路径标识,格式为 {两位编号}-{十位随机小写字符串}。
  • 主线:从 00-letsstart 到第 26 关的连续游玩链路。
  • 关卡接口:挂载于 /api/{关卡编号} 下的 HTTP 或协议入口。
  • 协议型关卡:依赖 WebSocket、HTTPS Trailer、HTTP/2 等能力的关卡。
  • 状态型关卡:依赖会话、持久化或多步状态修改的关卡。
  • 业务失败:请求格式合法,但因谜题规则、库存、未通关等原因未成功完成操作。
  • 请求错误:请求缺少必要字段、字段类型错误、方法错误、路径错误或坐标不合法。

1.5 参考文档

2. 总体描述

2.1 产品概述

Aster Archive 是一个浏览器访问型 Web 解谜应用。玩家通过阅读页面、查看源码、访问静态资源、发送 HTTP 请求、使用协议能力或操作状态型界面来获得下一关入口。

2.2 用户特征

  • 主要用户具备基础前端 / HTTP 认知,并愿意结合浏览器开发者工具继续探索
  • 次要用户可能以学习 Web 基础知识或研究谜题设计为主要动机
  • 软件行为应优先保证主要用户能够理解公开说明、找到提示入口并完成主线推进

2.3 系统上下文

系统由以下三层构成:

  • 浏览器客户端:访问页面、发起普通 HTTP 请求或协议连接
  • Web 入口层:负责静态内容分发与常规 HTTP 转发
  • 应用服务层:提供页面、普通 API 与范围内关卡所需的协议能力

2.4 当前覆盖范围

本契约当前覆盖首页、起始说明页、更新页、已实现的第 01–26 关,以及直接支撑它们的接口、协议能力、状态持久化、日志、配置和测试。关卡持续、不定期更新,不采用阶段边界;新增关卡或运行能力需要在实现前扩展相应契约。

2.5 设计约束

  • 软件设计应与单机、低成本、可长期维护的部署前提保持一致
  • 当前契约不要求多节点扩容、独立缓存集群、高规格数据库或平台化改造
  • 特殊协议能力不得被简化为只能通过人工伪造响应才能完成
  • 配置必须通过统一配置入口加载并校验
  • 状态型关卡必须保持玩家会话隔离,不得跨玩家共享可变状态

2.6 假设与依赖

  • 部署环境可提供 HTTP、HTTPS 与 HTTP/2 监听能力
  • 对第 15、17、21 关等协议型关卡,外部入口必须允许玩家实际访问所需能力

3. 需求组织与一致性规则

3.1 编号规则

  • 功能需求使用 FR-*
  • 非功能需求使用 NFR-*
  • 验收要求使用 AR-*

3.2 规范优先级

  • 必须:当前契约必须满足
  • 应:默认应满足;若延期,需要显式记录影响
  • 可:增强项,不作为当前硬性验收前提

3.3 响应语义规则

除个别关卡玩法明确要求例外外,系统应遵循以下规则:

  • 请求错误使用 4xx
  • 业务失败可使用 200 返回结构化失败信息
  • 未处理异常使用 500
  • JSON 接口默认返回 application/json; charset=utf-8

3.4 会话与持久化规则

  • 会话型接口必须使用系统签发的会话标识 Cookie 区分玩家
  • 同一玩家重复访问时,应复用其已有状态,除非规则明确要求重置
  • 缺失、非法或失效会话必须返回明确错误,不得静默读取其他玩家状态
  • 状态文件损坏、缺失或过期时,应进入可理解的恢复路径,而不是返回模糊异常

4. 系统特性与功能需求

4.1 站点入口与静态主线

4.1.1 描述

系统必须提供首页、起始页和第 01 至 26 关主线内容。纯静态关卡可以通过 HTML、CSS、注释、静态资源、目录、字体或前端脚本承载线索。

4.1.2 功能需求

  • FR-01 系统必须提供 / 首页,并展示项目定位、当前开放进度和主入口链接。
  • FR-02 系统必须提供 /00-letsstart 起始说明页,并解释 flag 规则、基本游玩方式和必要约定。
  • FR-03 系统必须提供 /updates 更新页,用于展示阶段进展、开放范围和对外可见的主要内容演进。
  • FR-04 第 01 关至第 26 关必须构成连续主线;当前关必须能提供下一关线索。
  • FR-05 纯静态关卡的线索可分布于页面源码、注释、CSS、字体、站点地图、隐藏文件或前端脚本,但线索必须真实存在于可观测系统层面。

4.2 页面提示、引导与叙事一致性

4.2.1 描述

系统必须通过页面结构、提示入口、例外规则说明和统一叙事表达来支撑玩家推进主线,而不是把关键规则只隐藏在代码或接口实现中。

4.2.2 功能需求

  • FR-06 每个关卡页面应提供关卡标题和基本题面说明。
  • FR-07 默认情况下,系统应为关卡提供提示入口;若某关不适合单独提供提示,应在公共说明或题面中明确替代方式。
  • FR-08 当某关存在例外规则、额外操作前提或非默认访问方式时,页面或相关公开说明必须直接说明。
  • FR-09 页面命名、主要文案和限制访问材料等表达应与“神秘档案馆探索”的叙事设定保持一致。
  • FR-10 公开页面与关卡页面之间不得出现明显冲突的世界观口径、命名体系或开放进度表述。

4.3 普通 HTTP 关卡

4.3.1 描述

普通 HTTP 关卡通过查询参数、请求方法、请求头、认证、Cookie、Range 或 JSON 请求体等行为向玩家暴露下一关线索。

4.3.2 功能需求

  • FR-11 后端关卡接口应优先采用 /api/{关卡编号}/... 路径组织。
  • FR-12 普通 HTTP 关卡必须显式区分请求错误和业务失败。
  • FR-13 需要玩家观察响应头、响应体、Cookie 或状态码的关卡,必须在服务端返回稳定、可重复的结果。
  • FR-14 当关卡依赖时间、语言或请求头时,输入条件和可见反馈必须保持一致。

4.4 协议型关卡

4.4.1 描述

第 15、17、21 关依赖 WebSocket、HTTPS Trailer、HTTP/2 与 103 Early Hints 等普通页面之外的协议能力。

4.4.2 功能需求

  • FR-15 系统必须支持第 15 关所需的 WebSocket 升级与消息收发。
  • FR-16 系统必须支持第 17 关所需的 HTTPS Trailer 输出。
  • FR-17 系统必须支持第 21 关所需的独立 HTTP/2 服务与 103 Early Hints。
  • FR-18 当代理层无法稳定转发上述能力时,系统必须允许客户端直连对应应用服务端口。

4.5 状态型复杂关卡

4.5.1 描述

第 25、26 关需要会话、文件持久化和多步状态修改,必须以比普通 HTTP 关卡更严格的规格管理。

4.5.2 功能需求

  • FR-19 第 25 关必须提供登录、状态查询、配置提交、快照模板读取和恢复提交能力。
  • FR-20 第 25 关必须为每个会话保存独立状态,并提供过期状态的机会性清理机制。
  • FR-21 第 26 关必须提供棋盘读取、取 flag、重置、单格放置、单格旋转和单格删除能力。
  • FR-22 第 26 关必须为每个会话保存独立棋盘、库存和通关状态。
  • FR-23 第 26 关写操作后必须重新计算通关状态,并将结果写回持久化状态。
  • FR-24 状态型关卡必须对非法参数返回请求错误,对规则不满足的合法请求返回玩家可理解的业务失败信息。

4.6 运行与维护支撑

4.6.1 功能需求

  • FR-25 系统必须提供 /api/status 健康检查接口。
  • FR-26 系统必须支持统一静态资源托管。
  • FR-27 系统必须在启动时校验必要配置,缺失或非法时直接失败。
  • FR-28 系统必须提供运行日志,并支持按日期轮转。
  • FR-29 系统应支持优雅停机,避免测试和部署阶段出现悬挂连接。

5. 外部接口规格

5.1 公共接口约束

5.1.1 通用请求约束

  • 所有 JSON 写接口默认接受 application/json
  • 表单登录接口可接受 application/x-www-form-urlencoded
  • 未声明鉴权的接口按游客访问设计
  • 除协议型接口外,未声明特殊行为的接口使用 HTTP/1.1 即可访问

5.1.2 通用错误响应

当接口以 JSON 返回错误时,应优先使用以下语义:

场景 HTTP 状态码 最低响应要求
缺少参数、参数类型错误、坐标不合法 400 返回可理解错误消息
认证失败、会话失效或未授权 401 或 403 返回可理解错误消息
路径不存在 404 返回不可达或无效
方法不允许 405 返回方法不允许
未处理异常 500 返回通用错误消息,不泄露内部路径

5.2 健康检查接口

GET /api/status

项目 规格
目的 提供基础可用性探针
请求体 无
成功响应 200,JSON:{ "message": "ok" }
错误响应 500 表示服务异常
会话要求 无
持久化副作用 无

5.3 普通 HTTP 关卡接口

GET /api/04

项目 规格
目的 通过自定义响应头提供下一关线索
输入 无
成功响应 200,JSON 至少包含 message 字段;响应头必须包含 X-Archive-Next
错误响应 500
会话要求 无
副作用 无

GET /api/05

项目 规格
目的 通过错误方法返回拒绝信息,引导玩家切换方法
成功响应 400,JSON:包含拒绝性提示
会话要求 无
副作用 无

POST /api/05

项目 规格
目的 通过正确方法返回下一关线索
请求体 无强制字段
成功响应 200,JSON:包含 message,其中给出第 06 关线索
会话要求 无
副作用 无

GET /api/06

项目 规格
目的 通过查询参数分支返回普通欢迎语或下一关线索
查询参数 level,当值为 manager 时返回线索
成功响应 200,JSON:message
会话要求 无
副作用 无

GET /api/07

项目 规格
目的 根据 location 查询参数返回场景文案
查询参数 location,允许缺失;特定值返回第 08 关线索
成功响应 200,JSON:message
业务规则 缺失位置时返回“请指定”;未知位置返回“当前不开放”
会话要求 无
副作用 无

POST /api/12/login

项目 规格
目的 校验管理员用户名和当日四位密码
请求体 username: string,password: string
字段规则 username 必须存在;password 必须为四位数字,且与服务端基于当日日期生成的口令一致
成功响应 200,JSON:{ "message": "登录成功" }
失败响应 缺少字段时 400;用户名错误或密码错误时 401
会话要求 无
Cookie 副作用 必须写入登录 Cookie;Cookie 应为 HttpOnly,并限制到关卡所需路径
持久化副作用 无文件落盘;可使用短周期运行时缓存保存当日口令

GET /api/12/get_room_info

项目 规格
目的 在正确 room_id 和有效 Cookie 下返回下一关线索
查询参数 room_id: number
成功响应 200,JSON:当 room_id = 13 且 Cookie 有效时,message 返回下一关线索
失败响应 未授权时 401;房间号不匹配时 200 返回无此房间提示
会话要求 必须携带有效登录 Cookie
副作用 无

POST /api/14/login

项目 规格
目的 使用 Basic Auth 校验管理员凭据并返回下一关线索
输入 Authorization: Basic <base64(username:password)>
字段规则 必须按关卡预设凭据规则校验 Basic Auth 信息
成功响应 200,JSON:message 返回第 15 关线索
失败响应 401;响应头必须带出认证提示头
会话要求 无
副作用 无

GET /api/16

项目 规格
目的 根据未来时间点与协议提示返回线索
查询参数 timepoint: number
请求头 可携带 X-Forwarded-Http3 作为提示输入
成功响应 200,JSON:message;响应头必须回写 X-Forwarded-Http3 判定结果
失败响应 400,当 timepoint 缺失或非法
业务规则 timepoint 不大于当前年份时返回过去提示;未来时间点返回下一关线索
会话要求 无
副作用 无

GET /api/18

项目 规格
目的 通过受限 Range 分段读取线索文本
请求头 Range: bytes=start-end
成功响应 无 Range 时可返回普通提示;合法分段请求返回 206,并带 Accept-Ranges、Content-Range
失败响应 416,用于格式错误、贪婪范围、越界范围或单次范围过大
业务规则 不允许 suffix range 和 open-ended range;单次最大范围宽度为关卡约束值
会话要求 无
副作用 无

POST /api/20

项目 规格
目的 对玩家猜测返回完全匹配和部分匹配数量
请求体 guess: string
成功响应 200,JSON:必须包含 message、exact、partial、isCorrect
失败响应 400,当 guess 缺失
业务规则 当猜测完全正确时,isCorrect 为 true,并返回下一关线索
会话要求 无
副作用 无

GET /api/22

项目 规格
目的 根据 Accept-Language 首选语言返回本地化文案
输入 Accept-Language 请求头
成功响应 200,JSON:message
业务规则 首选语言包含 en 时必须返回包含第 23 关线索的英文文案;否则返回默认中文文案
会话要求 无
副作用 无

5.4 协议型关卡接口

WS /api/15/challenge

| 项目 | 规格 | | -------------- | ------------------------------------------------------------------ | ---- | ---- | -------- | | 目的 | 提供迷宫初始化、移动判定和通关反馈 | | 连接前提 | 必须通过 WebSocket Upgrade 建立连接 | | 初始服务端消息 | 建立连接后必须先发送欢迎消息,提示客户端发送 init 动作 | | 客户端消息 | {"action":"init"} 或 {"action":"move","direction":"up | down | left | right"} | | 初始化响应 | 返回迷宫宽高 | | 移动响应 | 返回是否撞墙、是否通关;通关时返回完整迷宫和第 16 关线索 | | 错误响应 | 非法 JSON、非法 action、未初始化移动、非法方向时返回结构化错误消息 | | 连接结束 | 通关后服务端应主动关闭连接 | | 会话要求 | 单连接内状态隔离;不要求跨连接复用 | | 副作用 | 无持久化 |

GET /api/17

项目 规格
目的 通过 HTTPS Trailer 返回下一关线索
协议要求 必须通过 HTTPS 访问
成功响应 200,正文为 JSON 文本;响应头必须声明 Trailer;响应结束时必须附加 Trailer 头,内容包含第 18 关线索
会话要求 无
副作用 无

GET /api/21

项目 规格
目的 通过 HTTP/2 与 103 Early Hints 暴露协议级线索
协议要求 必须通过独立 HTTP/2 服务访问
成功响应 200,JSON:message;在正式响应前必须发送 103 Early Hints,其 link 预加载 analytics.js
失败响应 路径不存在时 404;方法不允许时 405;未处理异常时 500
CORS 应允许来自站点主入口的读取访问
会话要求 无
副作用 无

GET /api/analytics.js

项目 规格
目的 提供第 21 关预加载脚本
协议要求 与 /api/21 同属 HTTP/2 服务
成功响应 200,JavaScript 内容
会话要求 无
副作用 无

5.5 第 25 关接口

状态模型

第 25 关会话状态至少包含以下字段:

字段 类型 说明
field string 当前可修改字段名
current_value string 当前字段值
updated_at string 最后更新时间,使用可序列化时间字符串
last_recovery object 可选 最近一次恢复提交信息

Cookie 约束

项目 规格
格式 32 位十六进制字符串
属性 必须为 HttpOnly,SameSite=Lax
会话失效 Cookie 缺失、格式不合法、对应文件不存在或不可解析时视为失效

存储约束

  • 每个会话必须对应独立 JSON 状态文件
  • 过期状态文件应有机会性清理机制
  • 清理失败不得中断正常请求

POST /api/25/login

项目 规格
目的 建立运维终端会话并生成初始状态
请求体 username: string,password: string
字段规则 必须按本关预设登录规则校验用户名和密码
成功响应 200,JSON:至少包含 message、field、current_value、updated_at
失败响应 401,当用户名或密码错误
Cookie 副作用 必须签发新的会话 Cookie
持久化副作用 必须创建新的会话状态文件

GET /api/25/state

项目 规格
目的 返回当前会话状态
成功响应 200,JSON:当前状态对象
失败响应 401,当会话缺失或失效
会话要求 必须携带有效会话 Cookie
副作用 无

GET /api/25/snapshot-template

项目 规格
目的 返回恢复模板字段和快照标识
成功响应 200,JSON:至少包含 field、snapshot_id
失败响应 401,当会话缺失或失效
会话要求 必须携带有效会话 Cookie
副作用 无

POST /api/25/commit

项目 规格
目的 修改当前配置值
请求体 new_value: string
字段规则 new_value 必须为非空字符串
成功响应 200,JSON:至少包含 message、field、current_value、updated_at
失败响应 会话缺失或失效时 401;缺少 new_value 时 400
会话要求 必须携带有效会话 Cookie
持久化副作用 必须更新现有会话状态文件

POST /api/25/recover

项目 规格
目的 提交离线快照恢复信息并给出下一关线索
请求体 field?: string,old_value: string,new_value: string,modified_at: string,snapshot_id: string
字段规则 old_value、new_value、modified_at、snapshot_id 必填;field 缺失时可回退为默认字段
成功响应 200,JSON:至少包含 message、field、current_value、updated_at、snapshot_id
失败响应 会话缺失或失效时 401;缺少必要字段时 400
会话要求 必须携带有效会话 Cookie
持久化副作用 必须写回恢复后的当前值与最近恢复记录

5.6 第 26 关接口

状态模型

第 26 关会话状态至少包含以下字段:

字段 类型 说明
width number 棋盘宽度,当前固定为 10
height number 棋盘高度,当前固定为 10
source {x:number,y:number} 起点
targets Array<{x:number,y:number}> 终点列表
cells Tile[][] 二维棋盘
inventory {straight:number, elbow:number, tee:number} 当前库存
solved boolean 当前是否已通关

Tile 至少支持以下形态:

tileType 额外字段 说明
empty 无 空格
source 无 起点
target 无 终点
blocker 无 不可操作障碍
pipe pipeType、rotation、locked? 水管格

Cookie 约束

项目 规格
格式 32 位十六进制字符串
属性 必须为 HttpOnly,SameSite=Lax
会话创建 首次读取棋盘或旧会话失效时自动创建

业务规则

  • 棋盘固定为 10 x 10
  • pipeType 仅允许 straight、elbow、tee
  • rotation 仅允许 0、90、180、270
  • PUT 只能在空格创建玩家水管
  • PATCH 只能修改已有玩家水管的方向,忽略额外字段
  • DELETE 只能删除已有玩家水管
  • locked 水管与 blocker 不可修改
  • 写操作完成后必须重新计算 solved
  • 只有所有终点与起点连通时,solved 才为 true

响应体约束

除 GET /flag 外,本关接口应优先使用以下响应结构:

字段 类型 说明
success boolean 是否成功
message string 玩家可理解消息
solved boolean 当前是否通关

GET /board 额外返回:

字段 类型 说明
board object 序列化后的棋盘
inventory object 当前库存

GET /api/26/board

项目 规格
目的 返回当前棋盘;必要时自动创建新会话
成功响应 200,JSON:包含 success、message、solved、board、inventory
会话要求 无;若无有效会话则自动创建
Cookie 副作用 必须写入或续写会话 Cookie
持久化副作用 无有效会话时必须创建新状态文件

GET /api/26/flag

项目 规格
目的 在已通关会话下返回下一关线索
成功响应 200,JSON:{ "success": true, "message": "<next-flag>" }
失败响应 403,当会话缺失、状态文件缺失或尚未通关
会话要求 必须携带有效且已通关的会话 Cookie
副作用 成功时可续写当前会话 Cookie,不得改写谜题状态

POST /api/26/reset

项目 规格
目的 用新棋盘覆盖当前会话状态
成功响应 200,JSON:包含 success、message、solved
会话要求 无;若无有效会话可先创建会话再重置
持久化副作用 必须将当前会话文件重写为新局面

PUT /api/26/tiles/:x/:y

| 项目 | 规格 | | ------------ | ----------------------------------------------------------------------------------------------- | ------- | -------------------- | --- | --- | ---- | | 目的 | 在指定空格放置玩家水管 | | 路径参数 | x、y,必须为 0-9 整数 | | 请求体 | pipeType: "straight" | "elbow" | "tee",rotation: 0 | 90 | 180 | 270 | | 成功响应 | 200,JSON:success: true,并返回最新 solved | | 请求错误 | 400,用于坐标不合法、水管类型不合法或方向不合法 | | 业务失败 | 200,返回结构化失败信息,并带出可区分库存不足、目标格不可放置或只读设施等原因的玩家可理解消息 | | 会话要求 | 无;若无有效会话可自动创建 | | 持久化副作用 | 成功时必须扣减库存、更新棋盘并落盘 |

PATCH /api/26/tiles/:x/:y

| 项目 | 规格 | | ------------ | ------------------------------------------------------------------------------------------------- | --- | --- | ---- | | 目的 | 修改已有玩家水管的方向 | | 路径参数 | x、y,必须为 0-9 整数 | | 请求体 | rotation: 0 | 90 | 180 | 270 | | 成功响应 | 200,JSON:success: true,并返回最新 solved | | 请求错误 | 400,用于坐标不合法或方向不合法 | | 业务失败 | 200,返回结构化失败信息,并带出可区分目标格为空、目标格不可修改或只读设施等原因的玩家可理解消息 | | 特殊规则 | 必须忽略额外字段,不得借 PATCH 创建水管或修改库存 | | 会话要求 | 无;若无有效会话可自动创建 | | 持久化副作用 | 成功时必须更新棋盘方向并落盘 |

DELETE /api/26/tiles/:x/:y

项目 规格
目的 删除已有玩家水管并返还库存
路径参数 x、y,必须为 0-9 整数
成功响应 200,JSON:success: true,并返回最新 solved
请求错误 400,用于坐标不合法
业务失败 200,返回结构化失败信息,并带出可区分目标格为空、目标格不可删除或只读设施等原因的玩家可理解消息
会话要求 无;若无有效会话可自动创建
持久化副作用 成功时必须清空该格、返还库存并落盘

6. 数据需求

6.1 静态内容数据

  • 页面 HTML
  • CSS、JS、字体、图片和其他线索资源
  • 目录索引、站点地图、隐藏文件、订阅源等辅助线索载体

6.2 运行配置数据

系统必须支持以下配置类别:

配置类别 说明
主 HTTP 服务配置 用于提供常规页面与接口访问入口
HTTPS 服务配置 用于提供需要 HTTPS 的协议型能力
HTTP/2 服务配置 用于提供独立 HTTP/2 入口与 Early Hints 能力
主入口来源配置 用于声明站点主入口地址及必要跨源约束
TLS 相关配置 用于提供 HTTPS 与 HTTP/2 所需的证书和密钥材料
日志相关配置 可用于覆盖默认日志输出与轮转行为

必要配置缺失、非法或彼此冲突时,系统必须在启动阶段显式失败。

6.3 运行时状态数据

  • 日志文件
  • 第 12 关当日口令缓存
  • 第 25 关会话状态文件
  • 第 26 关棋盘状态文件

6.4 持久化要求

  • 状态文件必须位于服务端可控目录下,不得由用户输入直接拼接出任意路径
  • 会话标识必须经过白名单校验后才能映射到文件路径
  • 持久化格式必须可读、可调试、可人工检查
  • 状态文件损坏时必须进入明确恢复路径,不得造成跨玩家串扰

7. 非功能需求

7.1 可用性

  • NFR-01 玩家必须能结合现代浏览器与必要的第三方工具完成当前主要体验
  • NFR-02 首页、起始页和低风险页面应具备基础响应式能力
  • NFR-03 页面结果区应保持稳定,避免明显布局跳动

7.2 可靠性

  • NFR-04 服务启动前必须校验必要配置,错误时显式失败
  • NFR-05 系统应支持优雅停机,减少测试与部署遗留连接
  • NFR-06 状态型关卡必须保持会话隔离,不得跨玩家共享状态
  • NFR-07 特殊协议行为应具备自动化测试或人工验证步骤

7.3 安全与边界清晰性

  • NFR-08 系统不以真实业务安全为主要目标,但不得使用无意义的高风险默认配置
  • NFR-09 用户输入、路径参数、查询参数、请求体和 Cookie 都必须经过显式校验
  • NFR-10 不得在错误响应中泄露内部文件路径、证书路径或其他敏感部署细节
  • NFR-11 状态文件路径必须使用白名单会话标识映射,避免路径穿越

7.4 可维护性

  • NFR-12 代码、静态资源、测试与文档必须分层组织
  • NFR-13 后端关卡逻辑应按关卡拆分,便于增量维护
  • NFR-14 文档必须能支持实现、测试、部署和问题定位
  • NFR-15 状态型关卡的业务规则必须保持可追踪,不得散落在大量隐式工具函数中

7.5 可测试性

  • NFR-16 系统必须提供 npm test 作为统一自动化测试入口
  • NFR-17 健康检查、关键 HTTP 行为、日志初始化和关键协议能力必须纳入自动化覆盖
  • NFR-18 第 25、26 关必须有会话隔离、持久化和主要失败路径回归测试
  • NFR-19 当前不适合自动化的协议或浏览器行为必须保留显式人工验证边界

8. 验收要求

8.1 自动化验收项

  • AR-01 首页、起始页和更新页可正常访问
  • AR-02 第 01 关至第 26 关形成连续主线
  • AR-03 GET /api/status 返回 200 和约定响应体
  • AR-04 普通 HTTP 关卡的关键输入分支、响应头、Cookie 和线索输出符合规格
  • AR-05 第 15 关 WebSocket 与第 17 关 HTTPS Trailer 行为通过自动化验证
  • AR-06 第 25 关的登录、会话隔离、状态读取、提交和恢复流程通过回归测试
  • AR-07 第 26 关的棋盘初始化、会话复用、库存变化、主要失败路径和取 flag 规则通过回归测试
  • AR-08 npm test 通过当前纳入范围的自动化测试

8.2 人工验证验收项

以下验收项当前允许以人工验证方式完成,但必须在验收记录中明确标记执行人、执行日期、访问入口和结果:

  • AR-09 第 21 关独立 HTTP/2 服务可被真实客户端访问,并在正式响应前返回 103 Early Hints
  • AR-10 需要依赖浏览器运行时、视觉比对或反调试环境的留白关卡,其人工复核结论已记录
  • AR-11 部署入口对第 15、17、21 关所需协议能力未发生阻断
  • AR-12 关卡页面的提示入口、例外规则说明和叙事表达与产品需求一致

8.3 人工验证最小步骤

AR-09 第 21 关 HTTP/2 与 Early Hints

执行人应使用支持 HTTP/2 与 103 Early Hints 的客户端或抓包工具,至少完成以下步骤:

  1. 请求第 21 关对应的 HTTP/2 入口。
  2. 确认服务端在正式 200 响应前先返回 103 Early Hints。
  3. 确认 103 中包含 Link: <analytics.js>; rel=preload; as=script。
  4. 继续请求与第 21 关同属一组 HTTP/2 入口的 analytics.js。
  5. 确认脚本内容中包含第 22 关线索。

AR-11 协议入口未被部署层阻断

执行人应至少完成以下连通性检查:

  1. 使用 WebSocket 客户端连接 /api/15/challenge,确认连接建立后收到欢迎消息,并能继续发送 {"action":"init"} 得到地图尺寸反馈。
  2. 使用支持 Trailer 的 HTTPS 客户端请求第 17 关对应的 HTTPS 入口,确认普通响应头包含 Trailer 声明,响应结束时可读取到包含第 18 关线索的 Trailer。
  3. 使用支持 HTTP/2 与 Early Hints 的客户端请求第 21 关对应的 HTTP/2 入口,确认可看到 103 Early Hints,且后续可访问 analytics.js。

AR-12 提示与叙事一致性

执行人应至少完成以下页面级检查:

  1. 抽查首页、起始页和若干代表性关卡页面,确认页面存在关卡标题或等价题面标识。
  2. 抽查存在例外规则或特殊访问方式的关卡,确认题面、提示或公开说明已直接说明相关前提。
  3. 抽查提示文本,确认提示是在引导观察系统行为,而不是直接给出完整答案。
  4. 抽查首页、起始页、关卡页和限制访问材料,确认命名、世界观表述和开放进度不存在明显冲突。

8.4 人工验证责任和范围

  • 责任主体:维护者或指定验收执行人
  • 验证范围:真实协议连通性、浏览器环境特性、自动化未覆盖的可玩性检查
  • 记录要求:至少记录执行日期、环境、步骤、结果和异常现象
  • 失败处理:人工验证失败不得以“自动化未覆盖”为由忽略,必须回到实现或部署层整改

9. 契约到验收

软件需求 主要验收项
FR-06 FR-07 FR-08 FR-09 FR-10 AR-12
FR-11 FR-12 FR-13 FR-14 AR-04
FR-15 FR-16 AR-05
FR-17 FR-18 AR-09 AR-11
FR-19 FR-20 AR-06
FR-21 FR-22 FR-23 FR-24 AR-07
FR-25 AR-03
FR-26 FR-27 FR-28 FR-29 AR-08 与运行层测试

验收到验证

验收项 主要验证方式
AR-03 健康检查相关自动化测试
AR-04 HTTP 主线集成测试
AR-05 协议专项自动化测试
AR-06 第 25 关状态型回归测试
AR-07 第 26 关状态型回归测试
AR-08 当前阶段统一自动化测试入口
AR-09 AR-10 AR-11 AR-12 人工验证记录

10. 关联文档