Skip to content

Commit 3371175

Browse files
pc-studypc-study
committed
docs: update DEVELOPMENT.md, README, and add SETUP-GUIDE
- DEVELOPMENT.md: add stage 4.9 (Apple design, pricing card redesign, CSS subgrid alignment), update cache version refs to os-v33/v=20260321l, add commit history entries, update CSS design system docs - docs/SETUP-GUIDE.md: new concise local dev guide for website contributors - README.md/README_EN.md: add website development section linking to SETUP-GUIDE.md and DEVELOPMENT.md
1 parent 0ea76e1 commit 3371175

4 files changed

Lines changed: 174 additions & 10 deletions

File tree

‎DEVELOPMENT.md‎

Lines changed: 34 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@
121121

122122
/* 圆角 */
123123
--r: 10px; --r-sm: 6px; --r-lg: 14px;
124+
--r-xl: 18px; /* 大圆角 (卡片) */
124125
}
125126
```
126127

@@ -561,7 +562,7 @@ Object.keys(pageI18n).forEach(lang => {
561562

562563
### 6.3 Service Worker 缓存策略 (sw.js)
563564

564-
**缓存版本**: `os-v9` — 每次大版本更新递增版本号
565+
**缓存版本**: `os-v33` — 每次大版本更新递增版本号
565566

566567
**策略分类**:
567568

@@ -800,13 +801,13 @@ grep -rl "G-旧ID" . | xargs sed -i 's/G-旧ID/G-新ID/g'
800801
<meta charset="UTF-8">
801802
<meta name="viewport" content="width=device-width,initial-scale=1">
802803
<title>教程标题 - OracleShellInstall</title>
803-
<link rel="stylesheet" href="../css/style.css?v=20260320b">
804-
<link rel="stylesheet" href="guide.css?v=20260320b">
804+
<link rel="stylesheet" href="../css/style.css?v=20260321l">
805+
<link rel="stylesheet" href="guide.css?v=20260321l">
805806
<!-- 其他 meta 标签参考现有教程 -->
806807
</head>
807808
<body>
808809
<!-- 使用现有教程作为模板 -->
809-
<script src="../js/shared.js?v=20260320b"></script>
810+
<script src="../js/shared.js?v=20260321l"></script>
810811
</body>
811812
</html>
812813
```
@@ -877,14 +878,14 @@ grep -rl "v5.0.0" --include="*.html" --include="*.md" --include="*.txt" . | head
877878

878879
1. **更新查询参数**: 全局替换版本号
879880
```bash
880-
# 将 v=20260320b 替换为新版本号 v=20260321
881-
grep -rl "v=20260320b" --include="*.html" . | xargs sed -i 's/v=20260320b/v=20260321/g'
881+
# 将 v=20260321l 替换为新版本号 v=20260322
882+
grep -rl "v=20260321l" --include="*.html" . | xargs sed -i 's/v=20260321l/v=20260322/g'
882883
```
883884

884885
2. **更新 Service Worker 缓存名**:
885886
编辑 `sw.js` 第 1 行:
886887
```javascript
887-
const CACHE_NAME = 'os-v10'; // 递增版本号
888+
const CACHE_NAME = 'os-v34'; // 递增版本号
888889
```
889890
用户下次访问时，新 SW 会激活并清理旧缓存。
890891

@@ -942,7 +943,7 @@ gh api repos/pc-study/OracleShellInstall/pages/builds --jq '.[0]'
942943

943944
**Service Worker 调试**:
944945
- Chrome DevTools → Application → Service Workers
945-
- 查看缓存内容: Application → Cache Storage → os-v9
946+
- 查看缓存内容: Application → Cache Storage → os-v33
946947
- 强制更新: 勾选 "Update on reload"
947948

948949
**搜索功能调试**:
@@ -1048,6 +1049,9 @@ grep -rl "旧邮箱" --include="*.html" . | xargs sed -i 's/旧邮箱/新邮箱/
10481049
| `a05784c` | 2026-03-20 | 终端动画修正为真实脚本输出 |
10491050
| `57e2f99` | 2026-03-20 | 全面代码审计修复 (P0/P1/P2, 12 项) |
10501051
| `af767f1` | 2026-03-20 | i18n 语言切换往返修复 |
1052+
| `942ab79` | 2026-03-21 | Apple 设计风格调整 + 页面切换闪烁修复 |
1053+
| `44da984` ~ `54ac7c6` | 2026-03-21 | 定价页 Pro 卡片重设计 + 社区版对齐 |
1054+
| `f807b97` ~ `0ea76e1` | 2026-03-21 | 定价卡片尺寸缩小 + CSS subgrid 对齐 |
10511055

10521056
### 4.7 第七阶段：首页重设计与终端动画 (2026-03-20 上午)
10531057

@@ -1098,10 +1102,30 @@ document.querySelectorAll('[data-i18n]').forEach(el => {
10981102
- `pricing.html`: `fa2` HTML 默认内容与 `pageI18n.zh` 对齐 (补充 TG/Discord/WhatsApp 联系方式)
10991103
- `compat.html`: `mxNote` Unicode 字符修正 (`&#9432;` → `&#8505;`, `&#10005;` → `&#10007;`)
11001104
- `download.html`: 6 个 FAQ HTML 默认内容从多行格式改为单行，与 `pageI18n.zh` 完全一致
1101-
- 全站 190 个 HTML 文件缓存版本号统一升级到 `v=20260320b`
1105+
- 全站 190 个 HTML 文件缓存版本号统一升级到 `v=20260321l`
11021106

11031107
**验证方法**: Playwright 自动化测试，对 6 个主页面执行 EN→ZH 往返切换，比较所有 `[data-i18n]` 元素的 innerHTML，确认零差异。
11041108

1109+
### 4.9 第九阶段：Apple 设计风格与页面优化 (2026-03-21)
1110+
1111+
**Apple 设计调整 `942ab79`**:
1112+
- 整体视觉向 Apple 设计语言靠拢：更柔和的间距、更克制的动效
1113+
- 导航 CTA 按钮从实色改为半透明风格，降低视觉侵略性
1114+
- 修复页面切换闪烁问题：移除 `@view-transition`，改用 `<head>` 内联脚本即时初始化主题
1115+
- 移除页面顶部进度条，减少快速导航时的视觉噪音
1116+
- 全站 189 个 HTML 文件添加 `<head>` 内联主题初始化脚本
1117+
1118+
**定价页 Pro 卡片重设计 `44da984` ~ `54ac7c6`**:
1119+
- 专业版卡片改为"限时特惠"风格：原价划线 + 大号价格 + 立省标签
1120+
- 社区版卡片结构对齐专业版：统一 header zone 模式
1121+
- 添加信任标签（一次付费/1000+ 用户/专属群）
1122+
1123+
**定价卡片尺寸与对齐 `f807b97` ~ `0ea76e1`**:
1124+
- 缩小卡片整体尺寸：内边距、字号、间距全面收紧
1125+
- 使用 CSS subgrid 实现两张卡片内部行对齐（header zone、分割线、功能列表、CTA 按钮）
1126+
- 修复按钮对齐偏差：移除不一致的 margin-bottom 和 align-self
1127+
- Service Worker 缓存更新至 os-v33
1128+
11051129
---
11061130

1107-
*文档版本: 2026-03-20 | 维护者: Lucifer (pc1107750981@163.com)*
1131+
*文档版本: 2026-03-22 | 维护者: Lucifer (pc1107750981@163.com)*

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,13 @@ sh OracleShellInstall.sh \
238238

239239
网站支持中英文切换、明暗主题、PWA 离线访问。
240240

241+
### 网站开发
242+
243+
网站为纯静态站点（HTML/CSS/JS），推送 `main` 分支自动部署到 GitHub Pages。
244+
245+
- 本地开发指南：[docs/SETUP-GUIDE.md](docs/SETUP-GUIDE.md)
246+
- 完整技术文档：[DEVELOPMENT.md](DEVELOPMENT.md)
247+
241248
---
242249

243250
## 注意事项

‎README_EN.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,13 @@ This repo also hosts the official website: **[www.oracleshellinstall.com](https:
192192

193193
Supports English/Chinese toggle, dark/light theme, and PWA offline access.
194194

195+
### Website Development
196+
197+
The website is a pure static site (HTML/CSS/JS), auto-deployed to GitHub Pages on push to `main`.
198+
199+
- Local setup guide: [docs/SETUP-GUIDE.md](docs/SETUP-GUIDE.md)
200+
- Full technical docs: [DEVELOPMENT.md](DEVELOPMENT.md)
201+
195202
---
196203

197204
## Notes

‎docs/SETUP-GUIDE.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# OracleShellInstall 网站 — 本地开发指南
2+
3+
快速搭建本地开发环境，预览和修改 OracleShellInstall 官方网站。
4+
5+
## 前置条件
6+
7+
| 工具 | 用途 | 必需 |
8+
|------|------|------|
9+
| Git | 版本控制 | 是 |
10+
| Python 3 或 Node.js | 本地 HTTP 服务器 | 二选一 |
11+
| 现代浏览器 | 预览（推荐 Chrome） | 是 |
12+
13+
## 克隆与启动
14+
15+
```bash
16+
git clone https://github.com/pc-study/OracleShellInstall.git
17+
cd OracleShellInstall
18+
19+
# 方法一：Python
20+
python3 -m http.server 8080
21+
22+
# 方法二：Node.js
23+
npx serve -p 8080
24+
```
25+
26+
访问 `http://localhost:8080` 即可预览。
27+
28+
> 不能直接用浏览器打开 HTML 文件 — 搜索索引和 Service Worker 依赖 HTTP 协议。
29+
30+
## 项目结构概览
31+
32+
```
33+
OracleShellInstall/
34+
├── index.html # 首页
35+
├── generator.html # 命令生成器
36+
├── docs.html # 使用文档
37+
├── compat.html # 安装合集（兼容矩阵 + 教程索引）
38+
├── pricing.html # 脚本订阅
39+
├── download.html # 下载中心
40+
├── 404.html # 404 错误页
41+
├── css/style.css # 全站样式（CSS 变量 + 组件 + 响应式）
42+
├── js/shared.js # 核心共享模块（导航/页脚/i18n/主题/滚动）
43+
├── js/search.js # 全站搜索（懒加载索引 + 键盘导航）
44+
├── sw.js # Service Worker（缓存策略）
45+
├── guides/ # 182 篇安装实战教程
46+
│ ├── guide.css # 教程页专用样式
47+
│ └── *.html # 独立教程页
48+
├── search-index.json # 搜索索引（188 条目）
49+
├── sitemap.xml # 站点地图
50+
└── manifest.json # PWA 清单
51+
```
52+
53+
## 开发约定
54+
55+
### 缓存版本管理
56+
57+
修改 CSS/JS 后必须同步更新缓存标识：
58+
59+
1. **HTML 文件的查询参数** — 全局替换 `?v=` 后的版本号：
60+
```bash
61+
grep -rl "v=20260321l" --include="*.html" . | xargs sed -i 's/v=20260321l/v=新版本号/g'
62+
```
63+
64+
2. **Service Worker 缓存名** — 编辑 `sw.js` 第 1 行：
65+
```javascript
66+
const CACHE_NAME = 'os-v34'; // 递增版本号
67+
```
68+
69+
### 国际化 (i18n)
70+
71+
- 所有可翻译元素标注 `data-i18n="keyName"` 属性
72+
- 共享翻译在 `js/shared.js` 的 `i18n` 对象中
73+
- 页面专属翻译在各页面内联 `<script>` 的 `pageI18n` 中
74+
- HTML 默认内容即中文源，`pageI18n.zh` 的值必须与 HTML 默认 innerHTML **完全一致**
75+
76+
### 主题系统
77+
78+
- 暗色（默认）：CSS 变量定义在 `:root`
79+
- 亮色：覆盖定义在 `[data-theme="light"]`
80+
- 主题在 `<head>` 内联脚本中即时初始化，避免闪烁
81+
82+
### Git 提交规范
83+
84+
| 前缀 | 用途 |
85+
|------|------|
86+
| `feat:` | 新页面、新功能 |
87+
| `enhance:` | 现有功能优化、视觉调整 |
88+
| `fix:` | Bug 修复 |
89+
| `cleanup:` | 代码清理、缓存版本更新 |
90+
| `docs:` | 文档更新 |
91+
92+
## 常用维护操作
93+
94+
### 添加新教程
95+
96+
1. 复制现有 `guides/*.html` 作为模板
97+
2. 修改标题、meta、正文内容
98+
3. 截图放入 `guides/img/`
99+
4. 更新 `compat.html` 教程列表、`search-index.json`、`sitemap.xml`
100+
101+
### 添加新页面
102+
103+
1. 复制现有页面作为模板
104+
2. 在 `js/shared.js` 导航生成代码中添加菜单项
105+
3. 添加 i18n 翻译键
106+
4. 更新 `sitemap.xml` 和 `search-index.json`
107+
5. 更新缓存版本号
108+
109+
### 调试 Service Worker
110+
111+
Chrome DevTools → Application → Service Workers：
112+
- 勾选 "Update on reload" 可在每次刷新时更新 SW
113+
- Cache Storage → 查看/清除缓存内容
114+
- 强制清除：Unregister SW → 硬刷新 (Ctrl+Shift+R)
115+
116+
## 部署
117+
118+
推送到 `main` 分支即自动部署到 GitHub Pages：
119+
120+
```bash
121+
git push origin main
122+
```
123+
124+
约 1-3 分钟后生效。如需自定义域名，编辑根目录 `CNAME` 文件并配置 DNS。
125+
126+
详细部署与搜索引擎配置请参阅 [DEVELOPMENT.md](../DEVELOPMENT.md) 第 7 节。

0 commit comments

Comments
 (0)