web_huakui_web/AGENTS.md

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

花魁短剧重构记忆

• 本仓库是花魁短剧原生 Next.js App Router + 严格 TypeScript 项目，原站参考目录为 /Users/mac/Desktop/work/web/jha-1045-hgdjnet-web。页面必须使用 React/TSX；不要恢复 Go/HTML 模板解析或 dangerouslySetInnerHTML 页面适配器。
• 保持原站功能、PC/H5 界面和完整 SEO 行为：metadata、JSON-LD、canonical、分页、robots、llms、sitemap、站点验证、IndexNow，以及重定向/404/503 的状态和索引规则。
• 保留服务端 API 转发、请求头和 Cookie 透传、游客会话恢复、多条 Set-Cookie 和私有响应禁止缓存。不要把鉴权或 SDK 私密配置泄露到公开数据、日志或图片 CDN。
• 页面按 src/features/{catalog,account,content,playback} 组织；页头/页尾、卡片、图片解密、播放器、鉴权及支付优先复用 src/components、src/lib、src/server 中的公共实现。
• 业务 CSS 统一在 src/styles/{foundations,components,pages,overrides}，通过 TSX 顶层导入并由 Next 编译为哈希资源；不要恢复 /static/css 或手工 stylesheet 链接。业务类名使用 hk- 与语义组件名称，xgplayer 第三方类名保留；页面样式使用零特异性 html[data-hk-page-styles] 隔离，PWA 最后加载。客户端切页由 PagePresentation 同步作用域与页面 body class，不可覆盖滚动锁/PWA/临时状态。
• 2026-10-14 用户明确重新启用语义新路径并同步全部引用，覆盖此前回退要求。代码入口和对外 URL 使用 /dramas、/drama、/series/watch、/collections、/collection、/account、/navigation 等；旧有效页面 GET/HEAD 一次 301 到新路径，规则统一在 src/lib/routes.ts。页面文件使用 HomePage、BrowsePages、DiscoveryPages、DramaWatchPage、SeriesWatchPage、SettingsPage、SiteNavigationPage，服务端播放模块为 src/server/pages/playback.ts。站内链接、metadata、分页、JSON-LD、llms、安装默认入口使用新路径，API/媒体签名/外链保持原合同与编码。npm run routes:export -- --admin ../hkdj-web-admin 从实际路由生成全部新旧对照及后台路径清单，routes:check 核验无漂移；后台导航分类支持选择静态入口或自由输入，参数模板不作为可选链接。后端 hkdj-web-server 的 h5path、sitemap 与 SEO 推送源同步新路径，Next 仍原字节服务 XML，不在请求中改写生成结果。
• robots/llms/sitemap 完整遵循参考 Go 合同：robots/llms 读取公共配置并使用原永久域名/代理 Host 规则，robots 保留四个磁盘候选与内嵌文本的优先级及原字符串处理。sitemap 只服务后端生成的文件；开发 SITEMAP_DIR=./template/pages/sitemaps，测试/生产 SITEMAP_DIR=../template/pages/sitemaps，仅作为部署目录映射。测试 Node 工作目录 /server/hkdj_net/h5/next，真实产物在父级 h5/template/pages/sitemaps，生产遵循相同目录关系；索引其次读取 ./template/pages/sitemap.xml。请求不读取远端 sitemap、不生成静态回退或合成索引、不改写 XML；缺失/非法文件走原完整 404 页面及共享数据加载。开发仅可显式 npm run sitemap:sync 通过可信 SSH 只读同步索引引用的完整分片，保留原字节/mtime，不修改远端、不删除未知文件；开发 XML 忽略提交，页面 trace 排除；Next 16.4 Node Proxy trace 仍可能带入原始 standalone，必须通过 bundle 脚本在隔离 dist 精确清理 XML，并逐层 lstat 拒绝符号链接父目录，保留 robots/key/未知文件和后端源目录。导航模式与 Go DHInit 一致，不注册抓取文件/验证/API/媒体路由。发布保留后端 XML，持续写入的原目录应外置挂载，不能随前端包清空。
• 成功抓取文件通过原生 Route Handler 返回；Proxy 仅选择成功出口或准备并改写完整 TSX 404，不能直接从 Proxy 输出文件，否则 Next 会过滤 Content-Length。保留 Go ServeFile 的 MIME、原字节、Last-Modified、Content-Length、Accept-Ranges、304/412/206/416、If-Range/多段 Range 和 HEAD；Next compress=false 避免框架自动压缩改变文件响应，外层代理可沿用原传输配置。
• 播放器通过 npm 使用 xgplayer 与 xgplayer-hls；不要恢复 CDN 脚本版 DPlayer/Hls/Swiper 或旧业务脚本。
• /h5/m3u8/**、/enkey、/newenkey 保留服务端媒体转发：签名 query 不重组，UA/IP/Range 保留，上游重定向按原 Go 客户端跟随。签名媒体请求按原合同不附登录 Cookie/Authorization；上游业务 JSON 错误返回 502，不能当播放清单成功响应。
• config/development.env、config/test.env、config/production.env 分别管理三套环境，本地覆盖使用忽略提交的 *.local.env；进程环境优先。2026-10-16 起开发 API 按用户指定使用 http://127.0.0.1:20032（替代原 http://172.104.181.99:30331），不要擅自切回原站 25319 或旧地址。
• SSR 请求准备在 src/proxy.ts 完成，通过 src/server/react/handoff.ts 向 React 交接；保留同请求 Cookie/页面数据一致性。大快照使用私有临时文件，部署多实例时须处理交接存储共享或实例亲和。
• 所有“黄果短剧”统一为“花魁短剧”。占位图品牌 logo 透明度固定为 0.2。Figma 文件为 1vUq4wf5xOs8ZOlmt26Q3O，读取设计使用本地 FIGMA_TOKEN 调用 REST API，不能打印令牌。
• 本地 npm run dev 默认使用 Webpack；该项目已确认 Next 16.4 Turbopack 开发 HMR 存在循环刷新，未经验证不要改回默认。Charles 调试使用 npm run dev:charles，不改业务接口地址。
• 验证至少覆盖 npm run check 和受影响的浏览器链路；图片必须检查真实接口返回的地址、解密后的自然尺寸、背景图及最终可见性（包含 computed opacity），模拟图片测试通过不能证明 CDN 可用。首页 Hero 封面成功/失败均需结束加载状态，保留淡入和失败占位；不能遗漏 CSS 依赖的就绪标记。
• 图片地址由公共 ImageProvider/解密组件统一解析：优先上游 imgCdn、imgAppUsCdn，再用环境 IMAGE_CDN_URL。开发 API 已返回 imgCdn/imgAppUsCdn，测试 API 30331 缺 CDN，环境仍配置已核验的 CloudFront 作为备用；不要把 API 地址当作图片 CDN。保留原 XOR 协议并验证图片文件头，错误响应不能缓存为图片。
• 提交遵循用户全局 AGENTS 规则：无前缀请求使用 [Ai] <type>: <中文主题>，正文具体说明文件/模块/资源；仅确有 Claude 共创时添加 Claude trailer。
• PWA 安装配置使用 src/app/manifest.ts 与 src/lib/pwa/config.ts：fullscreen 优先、standalone 回退、orientation any；全局 viewport-fit cover 与 Apple 独立窗口标签不可只放播放器页。Next 16 的 appleWebApp.capable 仅生成非 Apple 前缀标签，需保留 Metadata.other 中的 apple-mobile-web-app-capable。
• /manifest.webmanifest 与 /sw.js 必须绕过 SSR Proxy/游客初始化，包括 NAVIGATION_ONLY；Worker 源码为 TypeScript，开发/构建自动生成 public/sw.js，不拦截或缓存鉴权 API、HTML/RSC、签名媒体及密钥。PWA 安全区样式最后加载，普通浏览器不改变原布局；验证 npm run test:pwa 与实际 SSR 清单/标签/资源，真实设备安装需 HTTPS。