web_hgdjc_h5/docs/verification.md

# API 对接验证

日期：2026-10-17。

## 2026-10-22 测试与生产环境配置

本项目增加 `config/test.env`、`config/production.env`，保留独立的开发配置。进程变量优先，其次为对应 `*.local.env`，最后为基础配置；本地覆盖文件忽略提交。接口均沿用 `https://91av-wz.80sygtm.com`，默认端口均为 21030。测试部署使用 `APP_ENV=test` 和 `NODE_ENV=production`，构建目录为 `.next-test/`；生产目录为 `.next/`。开发目录为 `.next-dev/`。SEO 快照随对应目录隔离，同 API 的两个环境也不会共用快照。

`npm run build:test`、`npm run check` 通过，全部 290 项测试通过。新增测试覆盖配置优先级、环境隔离、CLI 参数、错误配置、真实子进程退出状态，以及同上游的 SEO 快照隔离。另通过启动脚本分别启动两套实际 Next.js 服务，使用临时端口和本地模拟上游验证静态资源及 API 代理均返回 200，验证结束后关闭临时服务。未执行远程部署。

## 2026-10-22 slug 路由

本项目（`JHA-1050`）的内容链接、轮播、专题/标签/栏目、搜索、书架卡片、选集、评论分页及解锁后跳转统一优先 slug，缺少时用 ID。支持 slug 地址直接访问与刷新，保留原 ID 地址直接访问；业务写入及仅接受 ID 的读取继续使用真实数字 ID。专题详情按当前文档先从分页专题目录解析 ID，不向接口发送未定义的 slug 参数。

生产构建及全部 283 项测试通过。新增回归覆盖 URL 编码、中文及特殊字符、分页目录解析、目录异常与缺失资源、canonical/JSON-LD 一致性、客户端选集与解锁跳转，以及严格 Swagger 参数约束下的 Next.js 生产响应。当前 Swagger 的 slug 查询参数已只读核对；测试使用本地模拟接口，未提交真实付费解锁、订单或评论。

## 2026-10-21 跳转性能优化

公共数据服务增加短期进程内缓存和并发合并：配置、页脚、导航、分类及标签选项 60 秒，首页 30 秒；按上游及查询参数隔离，返回独立副本并限制条目数量。无效数据、错误响应、认证和私人业务读取不缓存，配置/首页可在刷新失败时使用最近一次有效数据。详情、章节、选集、评论和推荐在响应详情之前并行请求，仍在服务端输出完整 HTML。

浏览器直接复用首屏公开配置及页脚，SDK 配置不序列化。公开页从浏览器前进后退缓存恢复时保留文档，后台按当前 Cookie 恢复身份并补报页面访问；账户、播放、支付及打开弹窗的页面保留重新验证。类型检查、生产构建及全部 258 项测试通过，包括跨请求缓存、并发合并、过期、错误恢复、副本隔离、缓存边界、两个账号隔离、首屏配置白名单、并行请求屏障、后退恢复与埋点。

真实接口及 29 个页面检查通过。本机短期采样中，公共缓存预热后列表约 312ms、专题约 287ms、回家的路约 143ms（首字节中位数，各 3 次）；首次游客会话曾超时，另一次交替对比也出现显著上游波动，不能将上述采样当作稳定延迟承诺。未提交真实订单、付费解锁、评论或反馈，未执行浏览器视觉验收。

## 2026-10-21 服务端直接渲染

请求与渲染方式：页面数据在服务端准备，页头、公开列表、搜索、详情/播放、应用目录、回家的路、反馈、个人中心及设置、充值/VIP 的正文随初始 HTML 返回。站内链接、分页和搜索使用原生文档请求，保留当前页面直到新响应到达；不再清空正文显示页面加载占位。浏览器复用首屏快照绑定交互，避免启动时重复读取整页数据。提交成功后重新请求当前页面，轮播、图片解密、实时权限、解锁和支付确认保留。

Proxy 为有效业务页面准备身份，并在本次请求中传递新 Cookie，供服务端读取账户内容；同一 Cookie 同时写回浏览器。客户端复用服务端用户快照，避免再次初始化游客；正式账号失效显示登录入口，服务异常直接提供重试。外部传入的内部身份头先清除，用户、列表、套餐和流水使用明确字段白名单，凭证不写入 HTML；账户响应继续禁止缓存和索引。独立 `/navigation/`、资源、无效地址和尾斜杠重定向不触发该会话流程。

类型检查、生产构建及全部 249 项测试通过，覆盖完整首屏正文、原生跳页保留旧文档、快照绑定不重复取数、两个账号隔离、伪造身份头、正式账号过期与退出、Cookie 传递、套餐及流水、播放器与广告/轮播清理。真实只读接口及 29 个页面检查通过，另确认真实免费与金币章节页面输出完整 HTML。没有创建真实订单、付费解锁、提交评论或反馈；未执行浏览器视觉验收。

## 2026-10-21 动态导航

顶部与侧栏共用 `navigation/header` 的服务端数据，移动抽屉继承同一菜单，底栏按同源数据生成。保留接口名称、顺序、图标和二级条目；过滤底部类型、不安全地址及已移除的独立剧集地址。首屏 HTML 已包含真实链接，原脚本不再插入固定顶部导航或覆盖接口名称。已知 API 的 `/hot` 与空系统入口直接生成本站路径，不新增跳转。

路由高亮由同一纯函数处理首屏及客户端导航：首页精确匹配，列表分页保持选中，排行榜覆盖三个榜单，具体专题及带查询条件的入口按对应地址匹配，顶部不借用详情页的列表高亮。接口空列表不回填静态菜单；异常只提示导航暂不可用，正文仍能加载。构建、类型检查和全部 248 项测试通过，覆盖动态顺序/名称、二级条目、外链、空列表、异常、旧剧集过滤和高亮规则。

## 2026-10-21 移除独立剧集

按后续确认移除桌面顶部、侧栏、移动端的“剧集”导航，以及独立剧集列表、视频详情和对应分页路由；旧地址无论是否带尾斜杠均直接返回 404，不请求内容接口，也不重定向。首页与 JSON-LD 不再展示旧类型的视频栏目。短剧详情、选集、金币解锁和章节播放保留。构建、类型检查与全部 242 项测试通过，包括入口清理、旧地址 404 和原有播放/解锁回归。

## 2026-10-21 当前 Swagger 对接

按 `91av-wz.80sygtm.com` 当前文档与实际只读响应核对页面接口，端点和参数映射见 [页面接口对照](api-contract.md)。修正短剧列表、专题顶层字段、题材筛选、搜索联想与空结果推荐、详情推荐及章节 SEO/统计字段；删除旧接口代理依赖。首页“更多”保留已确认的 moreUrl 优先规则，未配置时只展示真实首页栏目的数据。按用户后续要求移除独立剧集导航和路由，旧地址及分页直接返回 404；短剧章节播放保留。

构建、类型检查及全部 240 项接口合同与回归测试通过。真实服务验证游客身份、列表/三个榜单、专题、标签、配置、应用、套餐、个人列表和余额记录；另核对 29 个原生页面响应与实际有内容的免费/金币章节（`/play/10923/12723/`、`/play/10923/12726/`）。没有创建真实订单、付费解锁、注册账号或提交评论、反馈。未执行新的浏览器视觉验收。

## 2026-10-20 充值确认弹窗

恢复原 HTML 的支付标题/副标题、订单卡片、基础/赠送/合计金币、金额徽标、渠道图标按钮及选中圆点、确认按钮和底部说明，并复用原稿的尺寸、间距、圆角及移动布局。支付宝、微信、USDT 图标使用原始本地素材；渠道仅来自套餐配置，其他渠道保留名称和通用图标。使用隐藏表单值连接样式按钮和原下单参数，金币充值与 VIP 接口保持不变。

`tests/payment.test.mjs` 验证实际金币字段及金额换算、不注入演示赠送或未配置渠道、方法切换后的订单参数、重复提交拦截、VIP 接口、无效支付地址、无支付方式以及旧表单响应隔离。类型检查、生产构建和全部 152 项测试通过，仅使用本地模拟上游，没有创建真实订单或发起真实支付。

## 2026-10-20 详情选集解锁

对照参考项目 `playletser/chapter.go` 的列表权限规则和 `pages/play.js` 的解锁处理，金币集数使用按钮直接打开 `play-episode-lock`，保留原 HTML 的金币图标、余额/消耗摘要、确认和充值入口样式。弹窗先获取目标章节详情，再展示实际价格及余额；仅确认后提交解锁，成功刷新余额并跳转所选真实章节。已可观看和会员章节按最新权限处理，余额不足和登录过期分别进入充值或登录。

新增测试覆盖：列表权限优先级、详情页弹窗不提前跳转/扣费、最新价格覆盖列表旧价格、正确章节 ID、重复点击及确认防重、支付中禁止切换、迟到响应隔离、关闭/离开页面、余额不足、已可观看/VIP、章节信息不匹配、登录失效、失败重试，以及实际 Route Handler 的凭据和解锁参数转发。类型检查、生产构建与全部 147 项测试通过；测试仅连接本地模拟上游，未提交真实金币解锁。

## 2026-10-20 详情页样式调整

区块留白按原稿保留：横幅上下桌面端 26px、手机端 22px，官方链接至评论区 28px。无横幅数据时，选集与官方链接之间仍保留对应间距，不因条件渲染移除广告区而贴合。

对照原 HTML 的 `overviewMarkup`、操作栏、选集和评论 DOM 恢复结构，复用已有桌面/移动样式及原始 SVG 素材；修复 API 按钮属性与原样式选择器不一致的问题。简介支持三行截断与展开/收起，尺寸变化及离开页面时更新和清理；选集分段只横向调整滚动，保持桌面/手机切换前的章节位置。评论使用原稿的头像、正文、时间/操作行和嵌套回复容器，保留接口和独立分页路由。

`tests/detail.test.mjs` 验证动态字段与文本转义、图片解密入口、真实章节链接、配置官方链接和简介展开/尺寸变化/清理；播放测试补充详情页点赞接口、评论回复结构及移动端集数分段。类型检查、生产构建和全部 137 项测试通过。浏览器视觉复核仍受访问工具策略限制，未生成新的浏览器截图。

## 2026-10-20 登录逻辑调整

游客登录 403 已复现并修复：带 `Origin: http://localhost:3000` 的正常浏览器请求被本地来源校验拒绝，未到达上游。Next.js 使用监听地址 `0.0.0.0` 构造请求 URL，不能将它直接与浏览器 Origin 比较；现在使用实际 HTTP Host 和协议校验。新增真实 HTTP Host 集成测试及来源校验单元测试，覆盖 localhost、IPv4、IPv6、域名、端口、协议及伪造转发头。类型检查、生产构建及全部 131 项测试通过。

修复后对用户正在运行的 `http://localhost:3000/api/app/auth/guest` 进行一次正常游客握手，携带浏览器 Origin 和设备标识，真实响应为 HTTP 200 / code 200，返回用户信息及会话 Cookie。未记录或展示登录凭证，未提交正式账号注册、密码或其他业务写操作。

对照参考项目的 `common/auth.js`、登录/绑定弹窗及 `authser` 调整游客初始化、账号切换、绑定、失效恢复和退出。`tests/auth.test.mjs` 验证账号/邮箱和密码校验、密码确认、协议、设备持久化、首次渠道与邀请码、存储不可用、游客请求合并、登录响应顺序、失败保留原身份、旧请求隔离、正式账号过期只提示一次、手动退出，以及实际弹窗事件的防重复提交和密码清理。

HTTP 集成测试另验证真实 Route Handler 的登录与绑定参数、游客 Authorization、可选邮箱补全、设备头与客户端 IP、getInfo 不返回 token 时续用原凭证、正式账号初始化过期不降级、游客 GET/POST 失效最多重试一次、HTTP 401、缺少 token 的异常登录响应、Cookie 清理和退出后一次自动登录跳过。类型检查、生产构建和全部 127 项测试通过。测试只连接本地模拟上游，没有提交真实账号登录、绑定或密码重置。

## 真实接口

通过本地 Next.js 代理验证首页、配置、底部信息、短剧运营列表、热榜、专题、热搜、应用列表、充值套餐和搜索接口，均返回业务码 200。首页使用服务端请求的实际内容，首页筛选项保持移除。

上游 `POST /api/app/auth/guest` 在直接请求和代理请求中均出现超时（最长等待 25 秒）。无有效 token 的章节列表返回业务码 1000。真实登录态下的播放、用户资料、评论、收藏、订单和金币解锁尚未完成端到端联调；没有向真实接口提交评论、支付订单或解锁请求。

## 本地集成测试

`npm test` 启动独立模拟上游和 Next.js 生产服务，检查：

- 服务端渲染使用上游标题和栏目；API 文本转义；首页筛选项未恢复。
- 首页广告列表显式返回 `null`、轮播/栏目/公告为非数组、数组夹有空项时仍返回 200；有效内容继续显示，空内容显示空状态。
- 纯站点地址和带 `/` 的根地址均直接返回首页及 200，无 Location 响应头；首页入口指向根路径，短剧入口单独指向 `/shorts/`。
- 游客 token 仅写 HttpOnly Cookie，不返回到前端脚本；设备头按参考格式发送。
- 公共请求隔离过期 token；兼容二次编码的 JSON data。
- 正式账号会话失效后，写请求不会自动降级为游客重试。
- 接口白名单、请求方法、跨站写入拒绝。
- 保留真实章节 ID、观看权限和单集金币数。
- 退出登录清理会话 Cookie，不调用上游业务写接口。
- 30 个页面路径以 `/` 结尾，直接返回 200 且没有 Location 响应头；不带尾斜杠的地址也直接返回 200；`/shorts/` 刷新返回 200；无效路径返回可见的 404；首页和业务页面链接直接包含尾斜杠。
- `/navigation/` 直接访问与刷新返回 200，独立渲染入口线路、渠道和 App 下载链接，不加载业务页面运行脚本；首页及其余 30 个路径均不包含入口导航弹窗或隐藏页面的等待状态。
- 顶部、悬浮工具和首页底部的下载入口在配置未知时保持隐藏；页面不包含悬浮二维码面板。独立入口页在下载地址为空或无效时不渲染下载按钮。

`tests/routing.test.mjs` 另检查所有路由类型、中文和含斜线的搜索词、hash 地址不转换或替换、站内链接识别，以及 History 导航的事件通知、重复地址和前进后退记录。

全部分页使用 `原页面路径/page/页码/`，第一页链接使用原路径；页码、上一页和下一页均为真实链接。`tests/pagination.test.mjs` 覆盖短剧、剧集、专题/题材/标签/栏目、榜单、搜索、个人收藏/历史/已购、充值和 VIP 余额明细，以及详情/播放页的评论分页，检查页码解析、首尾页、无效页码、中文搜索词、排序保留和会员接口参数。播放器测试检查评论页码与排序、真实分页链接；HTTP 集成测试检查 20 类路径的两种尾斜杠形式均直接返回 200、刷新不重定向，以及非法分页路径返回 404。本次生产构建及全部 109 项测试通过。

排行榜独立使用 `/rank/hot/`、`/rank/new/`、`/rank/follow/`，对应接口 `rankType=1/2/3`。`tests/rank-pages.test.mjs` 检查真实页面路由逻辑、链接与当前页高亮、标题、刷新和翻页后的榜单类型，以及加载中和请求失败时保留导航；HTTP 集成测试检查三条路径两种尾斜杠形式均直接返回 200、独立标题且没有 Location 响应头。原 `/rank/` 仍直接展示热播榜，不重定向。此次生产构建和全部 100 项测试通过。

`tests/download.test.mjs` 检查下载地址优先级和有效性、各下载入口随配置显示/隐藏、动态插入入口，以及桌面端直接打开链接、移动端点击弹窗与组合键保留浏览器默认操作。

`tests/render.test.mjs` 检查广告、首页列表及嵌套栏目中的空值和类型异常，保留有效内容顺序及 HTML 转义；弹窗测试另覆盖广告队列中的空项和非对象项。

`tests/images.test.mjs` 使用参考算法的固定密文验证逐字节解密、100 字节边界、MIME 识别和普通图片兼容，并检查重复请求合并与缓存、并发和优先级、失败重试、超时取消、异步切图、Blob 释放、初始/动态节点和视口懒加载。渲染与 SSR 测试另确认接口图片不直接写入 `src`，视频封面使用 `data-poster`。

2026-10-19 只读抽取真实首页接口的 3 张图片验证，均返回 HTTP 200，按参考密钥解密后识别为 WebP；图片 CDN 返回 `Access-Control-Allow-Origin: *`。未保存原始图片，也未提交业务写请求。

`tests/playback.test.mjs` 覆盖播放地址及签名保留、观看权限优先级与旧字段、正片/预告切换、Safari/Chromium/移动壳浏览器选择、HLS 恢复上限、重试重建、切换路由与异步导入竞态、拒绝自动播放后的重试、预告不计入正片记录、真实章节 ID、解锁确认与防重复提交，以及实际控件脚本的播放/重试/解锁事件。HTTP 集成测试覆盖媒体清单、密钥端点两种尾斜杠形式、原始 AES 字节、凭据隔离、Range 和错误状态。

H.264/H.265 兼容测试另覆盖 MSE/原生 HLS 编码错误回退、签名与播放位置保留、重复错误及重试次数限制、网络错误区别处理、MP4 不误走 HLS，以及回退过程中的路由取消。`tests/codec-manifest.test.mjs` 运行真实 hls.js 1.7.3 完整版的清单解析和 LevelController，在模拟设备能力下验证 H.264 回退、`hvc1`/`hev1` 保留、HEVC 单编码清单接受/拒绝；测试不访问网络，不代表真实浏览器或硬件的解码实播结果。

2026-10-19 只读验证真实免费预告：清单返回 200，保留 `id/t/ticket` 参数后密钥代理返回 200 和 16 字节 AES 密钥，首片成功通过 AES-128-CBC 解密，输出首字节为 MPEG-TS 同步字节 `0x47`。不带签名参数的密钥请求会被上游拒绝。本次未保存密钥/媒体，也未提交真实观看上报、解锁或订单请求；真实账号付费章节和浏览器实播仍需联调。

`tests/startup.test.mjs` 对照参考项目的实际脚本规则验证：会话内首次年龄确认、确认早于配置返回、完整广告队列、刷新恢复进度、相同队列不重复弹出、广告码变化后重置、无效图片与失败图片跳过、全部失败后可重试、存储不可用、过期异步结果隔离，以及图片加载超时和取消。DOM 事件适配测试覆盖年龄弹窗禁止 Esc 关闭、广告 Esc/按钮切换下一条、广告链接与展示/点击事件，以及退出行为。

浏览器访问工具受 URL 策略限制，本次未进行浏览器视觉复核。目录中的桌面、手机截图属于原 HTML 迁移阶段的布局基线，不是当前 API 数据截图。

## 2026-10-22 部署脚本与本地发布包

- `bash deploy_test.sh --package-only` 完成测试环境构建、294 项回归测试和 zip/SHA-256 生成；`bash deploy_prod.sh --package-only` 完成生产构建、299 项回归测试和 Linux x64/glibc 包/MD5 生成。构建包含 TypeScript 检查。
- 两份脚本的 `--dry-run` 通过命令替身验证，不执行构建、SSH 或 SCP；缺失/非法部署目标在构建前拒绝。测试和生产共用构建锁。
- 发布包测试覆盖基础配置隔离、本地覆盖/缓存/旧 dist 排除、符号链接目标保护。Next.js 自动追踪漏带的 Turbopack Route Handler 运行文件已显式包含。
- 最终 `dist.zip`（29.87 MiB）解压到临时目录，使用本机裁剪依赖启动 `node start.mjs`；本地模拟 API 下首页、`/healthz`、Next 静态资源和 public 文件均返回 200，健康检查未触发上游请求。测试 zip 按约定不含依赖，真实 Linux 服务器需执行 `npm ci --omit=dev`。
- 最终 `web_jgdj_h5.tar.gz`（44.94 MiB）通过内容、MD5 和目标平台元信息检查；目标 Sharp/libvips 使用 lockfile 固定版本，并通过 Linux x64 ELF 校验，不含 macOS 原生模块。本机未运行 Linux 生产服务。
- `deploy/up_next_h5.sh` 用临时目录和命令替身验证校验失败、安装失败不停止旧服务；健康检查失败恢复旧版本；成功更新保留测试私有覆盖和公开 SEO 缓存。新增部署测试共 8 项通过，已包含在最新生产环境的 299 项回归中。
- 本次仅本地构建和打包，未执行任何真实 SSH/SCP、Supervisor 更新或远端 `running.sh`。部署前需配置本站目标地址，测试 Supervisor 程序及生产跳板机脚本由运维预先配置。

部署配置统一采用本站标识：测试 `root@172.104.181.99:22889` → `/server/web_jgdj/h5`；生产 `server@116.212.120.2` → `/home/server/web_jgdj/h5/nuxt`，SCP 22889 / SSH 22。包名 `web_jgdj_h5.tar.gz`、校验文件和 Supervisor `jgdj_next_h5` 使用本站标识；生产仍只通过完整路径调用原有 `running.sh`。部署测试验证当前配置、环境变量覆盖、无效目标提前失败及 dry-run 不连接远端；本次未执行实际上传或部署。

### 部署配置变化后的测试修复

已复现 `tests/deploy.test.mjs:72` 的目录断言失败：测试仍固定期望旧项目的上传目录，实际测试脚本已配置 `/server/web_jgdj/h5`。修复后不再将主机、路径、端口或 API 域名作为测试不变量，保留对参数覆盖、命令与帮助输出一致、非法目标提前失败、dry-run 不构建/不连接远端的验证。测试服更新的模拟 Supervisor 使用固定测试服务，避免调用者的 `DEPLOY_PROGRAM` 污染测试。两份脚本的帮助内容统一从当前变量生成，修复当时测试 SSH 配置 21030、帮助文案却写 22889 的不一致；保留修复时的上传路径和端口。

`bash deploy_test.sh --package-only` 已完成测试环境构建、全部 299 项测试和 `dist.zip` 打包；压缩内容及 SHA-256 通过校验。另在设置自定义 `DEPLOY_PROGRAM`、`DEPLOY_DIR`、`DEPLOY_SSH_PORT` 后运行部署专项测试，8 项通过。当前 SSH 端口和应用监听端口分别配置，未连接真实服务器验证 SSH 端口或执行上传/部署。

### 测试部署改用 tar.gz

`deploy_test.sh` 现在生成并上传 `web_jgdj_h5.tar.gz`、`web_jgdj_h5.tar.gz.sha256` 和 `up_next_h5.sh`，包名可通过 `DEPLOY_PACKAGE_NAME` 覆盖；同时刷新对应 MD5 文件供本地兼容校验。测试包继续排除依赖、本地覆盖、缓存和 macOS 附加文件，包内使用 `.next-test` 与 `config/test.env`。保留当前上传目录和端口，以及用户注释的远端自动更新命令；实际脚本上传完成后结束。

服务器辅助脚本同步使用 tar.gz：先校验 SHA-256、检查成员路径与类型，再解压、安装依赖和切换版本；损坏包、路径越界、链接及特殊文件在停止旧服务前拒绝。测试覆盖真实 tar.gz 上传参数、校验值、自定义包名、自动更新保持禁用，以及安装/健康检查失败的回滚。

完整本地构建和 304 项测试通过；测试部署专项 13 项通过。生成的测试 tar.gz 为 29.78 MiB、414 个文件，内容、SHA-256 和 MD5 均通过校验。解压后使用本机裁剪依赖和本地模拟 API 验证启动、首页、健康检查、Next 静态资源与 public 文件均返回 200。未执行真实上传或服务器更新。

## 2026-10-22 埋点检查与补全

通过项目自带的官方 SDK v1.2.0 复现了内容事件因空 `parent_item_id` 被拒收的问题；此前测试替身未校验字段，所以没有发现。现在回归测试调用真实 SDK 的具名事件方法，仅使用其初始化前缓存和字段校验，不向外发送测试数据。只读获取当前业务接口配置并在本机解析后，确认页面、内容、搜索、广告、弹窗行为、播放事件均在事件允许列表内；未修改服务端配置或打印密文、签名密钥。

| 范围                        | 事件与检查结果                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| 页面、分页、后退恢复        | `appPageView/pageClick`，保留真实路径及原有访问去重规则                                           |
| 导航与下载                  | `navigation`，补齐独立入口页渠道、App 下载入口选择器                                              |
| 首页及列表内容              | `appPageitemExposure/appPageitemClick`，无父级用字符串 `0`，通过真实 SDK 校验                     |
| 专题、福利应用              | 补齐专题卡片内容元数据；关联 `advitiseId` 的应用按广告上报，其他应用按内容并携带分类父级          |
| 大图广告                    | `adImpression/adClick`，保留原展示、点击触发；独立展示位置及延迟 SDK 队列防止漏报                 |
| 宫格广告                    | 与首页分开去重，滚动后补报可见项；关闭、遮挡或后台标签页不记曝光，恢复后重新观察                  |
| 弹窗行为                    | 补齐参考项目的 `advertising`：show/click/close，使用真实广告 ID；关闭不记 adClick，重复关闭不重报 |
| 搜索                        | `keywordSearch/keywordClick`，保留真实总数、首轮搜索及分页后的全局位置                            |
| 播放、切集、分享、失败      | `dramaEvent/dramaStatusChange`，全部现有行为的载荷通过真实 SDK 校验，预告不作为正片统计           |
| 登录、游客、注册、充值、VIP | 沿用 SDK 原始公共字段透传及 UID 同步，成功业务事件由服务端负责                                    |
| 点赞、收藏、评论、购买解锁  | 保留 BFF 校验后的事件上下文和请求 ID 透传，前端不重复发送服务端成功事件                           |
| 加载、排队、错误            | 配置首读跳过 SDK 等待；脚本失败重试加载；扩大初始化前队列并报告溢出；SDK 拒收和发送失败有脱敏诊断 |

浏览器使用真实页面及未修改的官方 SDK，测试专用包装通过 SDK 支持的单次事件地址参数把请求送入本机接收端，避开官方域名解析器对配置地址的 HTTPS 要求。已验证大图广告展示/点击、宫格展示/点击、页面访问、内容曝光，以及原生页面跳转前的内容点击均实际发出带 `event_sig` 的网络记录。UI 点击和弹窗滚动经浏览器执行，未向正式统计后台发测试事件。未验证正式部署的反向代理和统计后台入库结果。

最终验证：测试环境构建（含 TypeScript）及全部 323 项回归测试通过。最后一轮本机浏览器验证收到 78 条带签名的 SDK 事件，其中 `advertising` 为 show 21、click 2、close 21；大图广告的三种行为均到达，宫格关闭只覆盖实际曝光的广告，关闭未增加 `ad_click`。另外一轮已确认原生页面跳转前的 `app_pageitem_click` 实际到达，内容父级字段为字符串 `0`。所有网络验证仅使用本地模拟业务数据和本地测试签名配置。

## 2026-10-26 禁果短剧基础信息迁移

项目编号统一为 `JHA-1050`，应用及埋点 App ID 为 `1050`，npm 包和健康检查应用名为 `jha-1050-jgdj-web`。开发、测试、生产基础配置与测试数据同步更新。站名、页面标题、下载提示、协议品牌名称和 SEO 默认值统一为「禁果短剧」；Logo、侧栏缩略标识、App 下载图标、浏览器/桌面图标及默认分享图均已更新，并核对实际渲染及素材字节数登记。

发布包、默认目录和 Supervisor 使用 `jgdj` 标识，服务器地址与端口保持原配置。侧栏和页脚从后台配置生成官方联系方式，未配置或不安全的链接不输出；版权通知入口改为本站意见反馈，移除参考站邮箱。新增集成测试覆盖首屏联系方式的有效、缺失和不安全配置。

验证结果：生产构建、`npm run typecheck`、全部 **374 项**回归测试和 `git diff --check` 通过。首次测试因沙箱禁止本机端口监听而取消集成用例，获得本地测试所需权限后完整重跑，374 项通过、0 失败、0 取消。未执行部署、推送或 Git remote 切换；上线前需核对新仓库地址、服务器目录/更新脚本/Supervisor，以及应用 `1050` 对应的 Go 上游、后台 SEO 和 `reportSdkConfig`。

## 2026-10-26 按禁果短剧 HTML 调整页面

以用户提供的 `禁果短剧_2组.html` 为视觉参考，提取其样式并保留原级联顺序，导入实际使用的品牌、页头背景、空状态、导航和年龄提示素材。桌面改为双层品牌页头；移动端按参考稿保留菜单、搜索及账户工具，正文使用独立主推轮播和六张横版推荐，模块副标题、热搜标签、排行榜角标、页脚及弹窗使用同一套粉色主题。真实 API 的动态栏目、路径、分页、账户、支付及下载流程继续使用现有实现。

首页横版推荐从启用的真实栏目中去重选取，数量不足时使用有效轮播数据；轮播切换只替换主推区，避免重复替换横版推荐或生成额外曝光。桌面历史面板在悬停或键盘聚焦时读取当前账户的历史接口，支持错误/空状态，关闭及身份变化后忽略过期返回，不持久化私人记录。

生产构建、TypeScript 检查、全部 **376 项**回归测试及 JavaScript 语法检查通过。已用本机模拟接口在浏览器对照桌面、390px 手机和 800px 平板布局，并验证轮播、历史面板的键盘进入和真实接口数据展示。预览中的剧目及账号均为本地测试数据；未执行线上部署或向外部服务发送测试事件。

## 2026-10-26 宫格弹窗限高与独立滚动

按参考项目的宫格弹窗规则，将 `#startup-grid` 最大高度限制为 `80vh / 80dvh`，仅广告列表区域纵向滚动，列表最大高度为视口 80% 减去 60px，预留底部关闭按钮及间距。隐藏滚动条并限制滚动向页面传递；原有四列宫格、手机间距和广告交互继续使用现有实现。

使用真实弹窗结构和当前全局样式，分别在桌面及 390 × 650 手机视口下放入 48 条本地测试数据，验证滚动可到达最后一排，关闭按钮始终可见。弹窗与埋点相关 32 项测试全部通过，`git diff --check` 通过。

## 2026-10-26 请求代理移除来源拦截

按 `jha-1047-91dj-web` 移除 Next.js Route Handler 对 POST 的 `isSameOriginRequest` 校验及不再使用的工具和单元测试。该逻辑原用于防止跨站 POST，运行于服务端代理；当 CDN / 反向代理使浏览器 Origin 与内部 Host 或协议不同时，可能在请求到达 Go 之前返回「请求来源不允许」。本次调整覆盖 `/api/*` 与兼容的 `/api/app/*` 两个入口，保留接口白名单、请求方法限制、HttpOnly / SameSite Cookie、会话失效处理及代理循环检测，上游鉴权错误继续传回。此前记录中的本地来源检查及跨站写入拒绝已由本次规则替代。

集成用例覆盖 localhost、IP、CDN HTTPS、反代内部域名与协议变化、`Origin: null` 及跨站标记，验证请求确实到达本机模拟上游、成功响应不泄漏 token，并检查上游 HTTP 403 仍返回 403。所有业务请求只发送至本机模拟服务。生产构建（含 TypeScript）、全部 **374 项**测试及 `git diff --check` 通过。

## 2026-10-26 生产部署脚本对齐参考项目

`deploy_prod.sh` 与 `jha-1047-91dj-web` 同步，生产远端命令统一为 `REMOTE_UPDATE_COMMAND`，预览和实际 SSH 执行使用相同文本。目录经 `valid_path` 校验后生成 `cd /目录 && bash rsupdate.sh`，移除原实际执行时额外的目录单引号，兼容按命令文本配置的 SSH 白名单；执行前打印远端命令，保留发布日志及失败状态检测。本站品牌、`web_jgdj` 包名和目录、主机与端口沿用当前配置。

脚本语法检查、默认 dry-run、26 项部署专项测试及 `git diff --check` 通过。测试通过本机命令替身验证上传先于更新、白名单命令匹配、权限拒绝、SSH 失败、远端错误输出、curl 401、自定义目录及仅打包行为；未执行真实上传或生产部署。

## 2026-10-26 请求头与 UA 对齐 JHA-1045

对照 `jha-1045-hgdjnet-web/app/static/js/common/request.js`、`pub/common/useragent/build.go`、`app/service/upstream/client.go` 和媒体代理实现，统一浏览器 Accept / Cookie 携带方式、SDK X-User-Agent 生成，以及 API、SSR、媒体和密钥的 UA / IP / SID 转发。原生浏览器 UA 按原值透传，客户端已有 X-User-Agent 优先；缺少时使用参考 Go 的解析规则，补充设备品牌/型号、系统名称/版本、浏览器 BuildID 与 SID。移除固定站点 UA 及虚构的 server-public 设备标识，公开 SSR 在缓存未命中时也使用本次访客的请求信息。应用 1050、接口地址、业务设备参数、会话恢复、公开数据凭证隔离及事件上下文校验沿用当前项目。

直接抽取并运行参考项目的 Go UA 生成函数，生成 12 组样例，覆盖 iPhone / iPad、Android 手机/平板及品牌、Windows / Edge、macOS / Safari、Linux / Firefox、Opera、IE、爬虫和空 UA；TypeScript 输出与 Go 输出逐字一致，样例保存在 `tests/fixtures/request-user-agents.json`。HTTP 集成测试验证两种 API 路径的请求头及 SDK 字段、完整 SSR 请求链路、媒体与密钥转发和凭证隔离。生产构建（含 TypeScript）、全部 **394 项**回归测试及 `git diff --check` 通过；网络验证仅连接本机模拟上游，未执行真实登录、支付或部署。

## 2026-10-26 对齐 SGDJ Swagger

只读获取用户指定的 `https://sgdj-h5.80sygtm.com/swagger/doc.json`，与旧文档核对 70 个应用接口及响应模型；生成 `tests/fixtures/sgdj-app-contract.json`，记录端点、方法、查询和请求字段及原始文档 SHA-256。首页读取 modules，短剧和题材模块分别映射现有页面组件，题材进入自己的 theme 路径；只有未提供 modules 字段时兼容旧首页快照，显式空模块不恢复旧数据。

首页更多使用 home-config/list 的 config、list / topicList、totalCount 和分页字段。短剧四类推荐及搜索换一批使用 operate/list 的 type 参数，移除文档中不存在的 hot/list。专题列表按分组显示，使用各组计数的最大值确定共同分页边界；专题详情直接传 topicSlug 或 ID，题材使用 theme/list 与 all/list 的 themeId / themeSlug、排序和更新状态参数。题材与专题各自保留主地址，正文链接、canonical、面包屑和 JSON-LD 同步，筛选变体继续 noindex。新文档没有要求改变的登录、支付、解锁和章节权限字段沿用原有处理，不恢复此前移除的独立视频路由。

生产构建（含 TypeScript）、全部 **399 项**回归测试、smoke 脚本语法及 `git diff --check` 通过。新增 HTTP 场景验证新首页模块、首页更多第二页的实际数据、专题分组和分页上限、直接 slug 请求没有目录扫描、题材更新状态筛选及 SEO。文档抓取之外，所有业务验证仅连接本机模拟 API；未执行正式账号注册、订单、评论、解锁或部署。应用 1050、服务端上游配置和已对齐的请求头规则继续使用当前项目设置。

## 2026-10-26 本地与测试上游切换 SGDJ 域名

开发、测试基础配置及服务端非生产默认地址统一改为 `https://sgdj-h5.80sygtm.com`，同步本地配置示例、项目说明及配置断言。生产上游继续为 `http://172.104.56.28:26125`。已核对本机没有旧地址的私有环境覆盖或进程覆盖；实际启动配置解析结果与目标地址一致，测试部署 dry-run 也显示新地址。

环境、API 配置及部署专项共 **42 项**测试、`git diff --check` 通过。没有执行实际上传或部署；已运行的本地进程需要重启，测试服需发布新配置并重启后生效。

## 2026-10-26 本地与测试上游域名更正为 JGDJ

按用户更正，开发、测试基础配置和非生产默认上游改为 `https://jgdj-h5.80sygtm.com`，同步配置示例、当前文档及测试断言；Swagger 来源链接继续保留实际核对过的 SGDJ 文档地址。确认本机有效配置与测试部署 dry-run 均采用新 JGDJ 地址，生产配置保持原值。环境及 API 配置 **16 项**测试和 `git diff --check` 通过；本次未上传或部署，运行中的服务需更新配置并重启后生效。

## 2026-10-26 HTML 页面样式核对

对照 `禁果短剧_2组.html` 的最终样式，用当前页面渲染函数和本地模拟内容检查首页、短剧列表、榜单、专题及详情、题材、标签、更多栏目、搜索、个人中心及四种个人列表、账号设置、金币充值、短剧详情、播放、应用、反馈和六种信息页面，并补查回家入口及独立导航页。桌面和 390px 手机预览分别加载原稿 CSS 与项目 CSS，核对关键组件的字号、字重、行高、内外边距、颜色、圆角和宽度；手机预览同时检查横向溢出。

- 榜单链接恢复原稿 9px 圆角、106px 最小宽度、16px 字号和 13px/24px 内边距；600px 以下按原稿等宽分配，保留真实榜单链接和当前页状态。
- 列表卡片、专题卡片及搜索关键词样式同时兼容语义化的 `h2`、`h3`，恢复原稿标题大小、字重、截断和间距。
- 个人中心、历史、收藏、点赞、已购和设置页按实际组件匹配原稿容器样式，去掉失效页面标识带来的额外面板和内边距；个人列表导航恢复原稿文字、间距和焦点样式。
- 详情及播放页点赞、收藏样式兼容当前业务属性，恢复按钮固定宽度和选中背景；手机端保留原稿自适应宽度。
- 通用 API 表单样式仅用于新增的简介和安全字段，避免覆盖原稿昵称输入框及反馈表单背景、边框和圆角。

浏览器核对的 26 类桌面页面关键样式指标与原稿一致；28 类手机页面（含回家入口和独立导航页）未出现横向溢出，涉及修复的关键组件指标一致。使用模拟内容核对布局，未执行真实付款、解锁、评论或账户修改。生产构建、TypeScript 检查和全部 403 项回归测试通过。

## 2026-10-26 首页分类按 style 渲染

首页模块保留接口 `style` 和 `label`，按 A–E 映射原稿分类布局：A 五列双排海报、B 六列海报、C 三列双排图文、D 六列编号海报、E 四列双排横版题材。A/B/C/D/E 首页预览上限分别为 10/6/6/6/8；分类名称和后台顺序保持原值，D 序号依次从 01 开始。缺失、预留或类型不兼容的 style 保留默认网格。首页 HTML 与 JSON-LD 使用同一预览限制，“查看更多”仍读取完整列表及真实分页。

使用本地模拟内容，将原稿最终 CSS 与项目 CSS 分别加载到 1440px、900px、390px、320px 的浏览器预览中，核对 A–E 的列数、可见数量、间距和封面比例；修正 B 在平板宽度的间距，并检查手机 C 图文卡和 D 封面编号。四种宽度均无横向溢出。

生产构建及全部 **409 项**回归测试通过，覆盖按 style 渲染的初始 SSR、预览上限、名称与顺序无关性、空数据、未知 style、内容转义、真实链接、结构化数据及更多分页。最后的平板间距修正后再次通过生产构建；`git diff --check` 通过。

## 2026-10-27 首页分类数量由 limit 控制

分类模块透传接口 `limit`，替代此前由 A–E 固定的预览上限。`style` 继续决定卡片布局及响应式列数，分类条目按 `limit` 取接口顺序中的前 N 项；数量不足时按实际有效条目数展示。`limit=0` 显示空态，缺失或无效时展示全部有效返回条目。新 `modules` 和旧 `homeConfigData`、短剧和题材、预留或默认 style 均使用相同规则，HTML 与 JSON-LD 同步；更多页继续使用真实总数和分页。

移除 B 样式在平板和手机端按固定序号隐藏条目的规则。在 1440px、900px、390px 浏览器模拟预览中，A/B/C/D/E 分别配置 limit=3/9/8/7/5，各尺寸均显示对应数量，无横向溢出。

生产构建（含 TypeScript）及全部 **411 项**回归测试通过，覆盖动态数量、新旧结构、0 值、缺失/异常 limit、列表不足、接口顺序、结构化数据、SSR 及更多页真实分页；`git diff --check` 通过。

## 2026-10-27 本地与测试上游切换 IP 地址

开发、测试基础配置及非生产默认上游改为 `http://172.104.181.99:26792`，同步配置示例、当前文档和配置断言。实际启动配置解析及测试部署 dry-run 均采用该地址，兼容变量 `API_BASE_URL` 同步解析；应用端口保持 `21030`，生产上游保持 `http://172.104.56.28:26125`。

环境及 API 配置 **16 项**测试和 `git diff --check` 通过。本次未上传或部署；运行中的本地服务需重启，测试服需发布新配置并重启后生效。

## 2026-10-27 业务接口统一 `/api/app/` 前缀

参考 `jha-1051-cgdj2-web`，浏览器业务请求及 API 冒烟脚本统一使用 `/api/app/*`，与已有 SSR 上游路径保持一致；旧 `/api/*` 处理器保留兼容。同步环境配置注释和部署说明，明确请求直达 Go 时会跳过 Next.js 的会话 Cookie、参数转换及 token 过滤。冒烟脚本同时按参考项目改用空登录参数校验，移除已失效的跨站 POST 拒绝断言。

生产构建（含 TypeScript）及全部 **411 项**回归测试通过，覆盖浏览器查询参数、JSON 和 FormData 请求、会话与旧路径兼容，并验证 `current` 模式下 Go 直达与 Next.js 会话处理的差别；`git diff --check` 通过。集成测试使用本机模拟上游，本次未部署或调用真实业务写接口。