新手教程 + 逐步引导
两层一起做，不要只写文章或只加遮罩：
| 层 | 学生看到 | 干什么 |
|---|---|---|
| 图文教程 | /help、/help/teacher |
跟着做一遍的说明 + 截图 |
| 圈选引导 | 登录后自动；教程页「再看一遍」 | driver.js 逐步高亮真实按钮 |
两站都有，正文和入口不要混：
| 站 | 图文 | 重播引导 |
|---|---|---|
OJ https://qiqioj.cn |
/help · /help/teacher |
学生 /home?tour=1；老师 /admin?tour=1 |
题库站 https://tk.qiqioj.cn |
/help · /help/teacher |
学生 /?tour=1；老师 /admin?tab=exams&tour=1 |
本机预览：OJ http://localhost:8066/help。对话里贴这些 URL，不要拿 .vue / .tsx 当页面预览。
何时用
- 「做/改新手教程」
- 「登录后下一步下一步圈按钮」
- 「教程页再看一遍界面引导」
- 「学生一篇、老师一篇」
不要用这技能改「本OJ特色功能说明」（公告 id=2 / ops/features/）。那是功能介绍，不是上手教程。
铁律
- 学生、老师拆开。不要一份混写。老师看完学生引导可以接着进后台引导。
- 开头写清两站分工。OJ = 编程题 / 作业 / 比赛 / 题单；题库站 = 客观题真题和班级考试。OJ 上
source=tk的客观题去题库站改。 - 圈的是真实控件。目标元素加
data-tour="…"，步骤里写同一个选择器。菜单在折叠里就beforeShow先点开。缺元素用skipMissingElement，不要假圈空白。 - 教程页不要自动弹引导。
/help上停掉 tour。重播只走?tour=1。 - 看过就记住。OJ：
oj-tour:v1:{用户名}:{student|teacher}。题库站：quiz-tour:v2:{用户名}:{student|teacher|report}。值为1。 - 文案短、一步一个动作。引导气泡不要贴整章教程。图文才写细。
- 账号密码、截图脚本里的登录口令、同步密钥不写进本文件。
正文写哪（学生才能看到）
ops/guide/ 只是底稿。只改那里，线上不变。
| 站 | 线上正文 | 线上图 | 底稿 |
|---|---|---|---|
| OJ | oj/qiqioj-frontend/public/guides/oj-student.md · oj-teacher.md |
同目录 png | ops/guide/oj-student.md · oj-teacher.md |
| 题库站 | quiz-site/src/content/help-student.md · help-teacher.md |
quiz-site/public/guides/ |
ops/guide/quiz-site-student.md · quiz-site-teacher.md |
OJ 的 Help 页会把 md 里的 ](OJ新手教程截图/ 换成 ](/guides/，所以 png 文件名要和 md 引用一致，放进 public/guides/。题库站 md 直接写 /guides/00-login.png。quiz-site/public/help/ 是旧副本，新图不要只丢那边。
改完底稿必须拷到「线上正文」。中文路径的底稿用编辑器打开，不要只丢 https 链接。
入口：OJ 右上角用户名 →「新手教程」（老师进 /help/teacher）；后台下拉同样。题库站考试中心和教师端顶栏也有。公告 id=1 可以提一句，不要改 id=2。
图文怎么写
# …新手教程（学生|老师）
> 给第一次来的人。跟着做一遍：A → B → C。
> 📍 网站：**https://…**
> 线上教程：**https://…/help**
> （两站分工一句话 + 链到另一站 /help）
## 目录
1. [登录](#1-登录)
…
## 1. 登录
打开网址，点「登录」。
- 切节只认
##。不要用「目录」当内容节（TOC 会跳过它）。 - 一步、一张图、紧跟在操作后面。
- 口吻跟现稿：短句、祈使、「跟着做一遍」。不要写成功能清单。
- 默认密码如果要写，只写老师导入约定
123abc，不要写演示账号口令。
圈选引导怎么改
现成组件接着用，不要另做一套遮罩。
| 站 | 步骤表 | 播放器 | 锚点 |
|---|---|---|---|
| OJ | oj/qiqioj-frontend/src/common/ojTour.js |
components/oj/common/ProductTour.vue |
顶栏 NavBar.vue；后台 admin/Home.vue |
| 题库站 | quiz-site/src/lib/onboarding.ts |
components/onboarding/ProductTour.tsx |
考试中心 / 教师端 nav / 作答页报错按钮 |
driver.js 约定（两站已对齐，不要改文案键）：
- 按钮：下一步 / 上一步 / 完成 / 跳过
allowClose: false（关用「跳过」）skipMissingElement: true，waitForElement: 2500- 进度
{{current}} / {{total}} - 老师步：OJ 用
openAdminSubmenu；题库站用switchTab+ 必要时sessionStorage
老师看完学生引导、且还没看过教师引导：OJ 会跳 /admin?tour=1。题库站学生步末可接「教师端」再进 /admin?tab=exams&tour=1。题库站作答页另有一段 report 圈「题目报错」，只第一次。
新加一步：先在 DOM 加 data-tour，再进行程数组。选择器写 '[data-tour="名字"]'。
截图
- 用现网或本机，演示账号登录后按章节截。
- 文件放进该站
public/guides/（OJ 中文名如00-登录页.png；题库站英文如00-login.png）。 - Glob / Grep 看不见 png，用
ls或 Read 完整路径。不要报「没图」。 ops/guide-screenshots/里有过捕获脚本。脚本里的账号口令不要抄进技能、不要提交新口令。
发版
- OJ：改的是前端
public/guides+ 可能的 Vue。走ops/scripts/build_deploy.sh frontend。 - 题库站：改
quiz-site/。活站/home/ubuntu/quiz-site。sync_src_from_qiqiedu.sh quiz（排除*.db）→npm run build→systemctl restart quiz-site。不要动 OJ 镜像。
自检
- [ ] 学生篇、老师篇都有；开头有两站分工
- [ ] 线上正文路径对（不是只改了
ops/guide/） - [ ] 图在
public/guides/，md 引用能显示 - [ ]
##能抽出 TOC；教程页不自动弹引导 - [ ] 每个圈选步有对应
data-tour；折叠菜单有beforeShow - [ ]
?tour=1能重播；看过写入 localStorage - [ ] 对话里贴了
/help或/help/teacher的 URL
