32 lines
7.9 KiB
Markdown
32 lines
7.9 KiB
Markdown
<!-- BEGIN:nextjs-agent-rules -->
|
||
|
||
## 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.
|
||
|
||
<!-- END:nextjs-agent-rules -->
|
||
|
||
## 花魁短剧重构记忆
|
||
|
||
- 本仓库是花魁短剧原生 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。
|