50 lines
3.1 KiB
Markdown
50 lines
3.1 KiB
Markdown
# 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 代理或首页兜底。内容和价格以采集快照为准，原站异常应记录在清单中。
|