# Repository Guidelines

## 项目结构与模块

- `jskcloud/`、`scck/` 是两个独立部署的静态站点，各自包含 HTML、`assets/`、三语页面、404 页面及 nginx 配置。禁止引入跨站目录依赖。
- `scripts/` 存放采集、生成、资源本地化和验证工具，使用 Node.js ES Modules。`sites.mjs` 定义站点，`lib.mjs` 提供公共工具。
- `scripts/static/` 保存生成页面使用的公共 CSS、JS；`scripts/locales/en.json` 保存英文译文。优先修改生成逻辑或源文件，再重新生成，避免只修改会被覆盖的成品。
- `.cache/` 保存采集缓存；`test-results/` 保存验证报告及截图；二者均不提交。

## 安装、开发与构建

在仓库根目录执行命令；工具通过当前工作目录定位文件。

```bash
npm ci
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromium
npm run preview
npm run capture
npm run build
npm run verify
```

`preview` 默认在端口 4173 提供 `/jskcloud/`、`/scck/`。`capture` 采集公开内容，`build` 生成静态文件；二者需要网络，构建前须有采集缓存。浏览器验证还需 Chromium 系统运行库。

仅更新一站可运行 `node scripts/build.mjs jskcloud`；单站预览示例为 `node scripts/preview.mjs scck 4175`。

## 代码风格与命名

新增 JavaScript 使用两空格缩进、单引号、分号及 `async/await`；构建工具使用 `.mjs`、`node:` 内置模块导入。函数和变量使用 `camelCase`，文件采用描述性的短横线命名，如 `verify-nginx.mjs`。

沿用附近代码风格，避免顺带重排现有压缩代码或下载资源。项目未配置 ESLint、Prettier；不要假设存在 lint 命令。

## 验证要求

- `node scripts/verify.mjs --static-only` 检查 HTML、链接、语言及本地资源。
- `npm run verify` 结合 Cheerio、PostCSS 和 Playwright 检查桌面及手机页面、菜单、搜索、外部请求和 404。
- 修改部署配置后运行 `NGINX_BINARY=/实际路径/nginx node scripts/verify-nginx.mjs`，验证独立域名及子目录部署。

验证脚本按 `scripts/verify*.mjs` 命名；当前没有单元测试框架或百分比覆盖率门槛。新增路由、语言或交互时扩展相应检查，确保零错误，并人工查看受影响页面的桌面及手机截图。

## 提交与 Pull Request

当前 Git 尚无提交记录，未形成提交惯例。建议使用简短的祈使式主题并注明范围，例如 `fix(scck): remove purchase controls`。提交包含对应源文件和必要的生成结果，不包含依赖、缓存或测试输出。

PR 应说明变更目的、影响站点与语言、是否刷新采集数据，以及验证命令和结果；存在相关 issue 时附上链接。页面外观变化需附桌面及手机截图。

## 静态部署约束

保留 `zh-cn/`、`zh-hk/`、`en/`，资源使用站内相对路径。登录、注册、购买及控制台功能不得恢复；后台地址必须返回真实 HTTP 404。部署时使用各站的 `nginx.conf.example`，不添加 PHP、API 代理或首页兜底。内容和价格以采集快照为准，原站异常应记录在清单中。