@routerhub/agent-rules 1.5.50 → 1.5.52

package/AGENTS.base.md

@@ -108,7 +108,7 @@ Closes #456
   1. 打开 PR 页面，逐一查看 Copilot review 提出的每一条问题。
   2. 逐条判断问题是否有道理：确实存在的代码缺陷、逻辑错误、安全风险、性能问题等 → 必须修复；误报、与需求不符、风格偏好无实质影响等 → 在评论中回复解释为何不改，然后 Resolve。
   3. 对于有道理的问题，直接修改代码、提交并推送到该 PR 分支。
-  4. 在 PR 评论中回复该问题（如”已修复”或简要说明修改内容），然后点击 Resolve conversation。
+  4. ⚠️ **强制步骤：修改代码并推送后，必须在 GitHub PR 页面上逐条点击 Resolve conversation。** 此步骤不可跳过——即使已回复评论、已推送修复代码，只要未点 Resolve，该条评论仍处于”未解决”状态，reviewer 无法判断是否已处理完毕。每修复一条，立即 Resolve 一条，不要等所有问题修完再批量操作。
   5. 所有问题处理完毕后，重新请求 Copilot review。
   6. 重复以上步骤，直到 Copilot review 不再提出新问题为止。
 - 每一条 Copilot review 评论处理完毕后，必须点击 **Resolve conversation**，不能只回复不 Resolve。不点 Resolve 会导致该评论一直处于未解决状态，无法判断是否已完成处理。
@@ -133,6 +133,7 @@ Closes #456
 - 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
 - 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
+- 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 
 ## 新需求与回归测试准入
@@ -239,6 +240,55 @@ Closes #456
 - 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
 - 提交前移除调试日志和临时代码。
 
+## Modal 内 Tooltip 规范
+
+在 Modal/弹窗内实现 tooltip 时，必须遵守以下规则，避免被 Modal 容器裁剪和消失太快两个问题。
+
+### 1. Tooltip 必须用 Portal 渲染到 document.body
+
+**问题**：Modal 容器通常有 `overflow: hidden` 或 `overflow-y: auto`，用 CSS `position: absolute/fixed` 的 tooltip 会被裁掉。
+
+**解决**：用 React Portal（`createPortal`）把 tooltip 气泡渲染到 `document.body`，完全绕开 Modal 的 overflow 裁剪。
+
+- 用 `getBoundingClientRect()` 获取触发元素（`?` 图标）的屏幕坐标
+- 气泡用 `position: fixed` + `transform: translate(...)` 精确定位在触发元素上方
+- `z-index` 至少 10000，确保在所有弹窗层之上
+
+### 2. 延迟隐藏 + 气泡可 hover
+
+**问题**：鼠标离开触发元素时 tooltip 立即消失，用户来不及把鼠标移到气泡上阅读内容。
+
+**解决**：
+- 隐藏加 200ms 延迟（`setTimeout`），给用户反应时间
+- 气泡本身绑定 `onMouseEnter`（取消隐藏定时器）和 `onMouseLeave`（触发同样的延迟隐藏）
+- CSS 上气泡容器必须 `pointer-events: auto`（不能是 `none`），否则鼠标事件不触发
+
+### 3. 参考实现
+
+实现一个可复用的 `FieldTooltip` 组件，核心结构：
+
+```tsx
+import { createPortal } from 'react-dom';
+
+function FieldTooltip({ text }: { text: string }) {
+  const iconRef = useRef<HTMLSpanElement>(null);
+  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [visible, setVisible] = useState(false);
+  const [pos, setPos] = useState({ top: 0, left: 0 });
+
+  // show() → 取消定时器 → getBoundingClientRect 更新坐标 → setVisible(true)
+  // hide() → 200ms setTimeout → setVisible(false)
+  // clearHideTimer() → clearTimeout
+
+  // ? 图标: onMouseEnter={show}  onMouseLeave={hide}
+  // Portal 气泡: onMouseEnter={clearHideTimer}  onMouseLeave={hide}
+  //              position: fixed, z-index: 10000, pointer-events: auto
+}
+```
+
+- 禁止在 Modal 内用纯 CSS `position: absolute` 的 hover tooltip
+- 写完 tooltip 后必须实际验证：弹窗内滚动时气泡不被裁剪，鼠标能从图标移到气泡上阅读
+
 <!-- @domain: go-backend -->
 
 ## Go 语言规则

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.50",
+  "version": "1.5.52",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/frontend.md

@@ -64,3 +64,52 @@ outputName: "frontend"
 
 - 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
 - 提交前移除调试日志和临时代码。
+
+## Modal 内 Tooltip 规范
+
+在 Modal/弹窗内实现 tooltip 时，必须遵守以下规则，避免被 Modal 容器裁剪和消失太快两个问题。
+
+### 1. Tooltip 必须用 Portal 渲染到 document.body
+
+**问题**：Modal 容器通常有 `overflow: hidden` 或 `overflow-y: auto`，用 CSS `position: absolute/fixed` 的 tooltip 会被裁掉。
+
+**解决**：用 React Portal（`createPortal`）把 tooltip 气泡渲染到 `document.body`，完全绕开 Modal 的 overflow 裁剪。
+
+- 用 `getBoundingClientRect()` 获取触发元素（`?` 图标）的屏幕坐标
+- 气泡用 `position: fixed` + `transform: translate(...)` 精确定位在触发元素上方
+- `z-index` 至少 10000，确保在所有弹窗层之上
+
+### 2. 延迟隐藏 + 气泡可 hover
+
+**问题**：鼠标离开触发元素时 tooltip 立即消失，用户来不及把鼠标移到气泡上阅读内容。
+
+**解决**：
+- 隐藏加 200ms 延迟（`setTimeout`），给用户反应时间
+- 气泡本身绑定 `onMouseEnter`（取消隐藏定时器）和 `onMouseLeave`（触发同样的延迟隐藏）
+- CSS 上气泡容器必须 `pointer-events: auto`（不能是 `none`），否则鼠标事件不触发
+
+### 3. 参考实现
+
+实现一个可复用的 `FieldTooltip` 组件，核心结构：
+
+```tsx
+import { createPortal } from 'react-dom';
+
+function FieldTooltip({ text }: { text: string }) {
+  const iconRef = useRef<HTMLSpanElement>(null);
+  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [visible, setVisible] = useState(false);
+  const [pos, setPos] = useState({ top: 0, left: 0 });
+
+  // show() → 取消定时器 → getBoundingClientRect 更新坐标 → setVisible(true)
+  // hide() → 200ms setTimeout → setVisible(false)
+  // clearHideTimer() → clearTimeout
+
+  // ? 图标: onMouseEnter={show}  onMouseLeave={hide}
+  // Portal 气泡: onMouseEnter={clearHideTimer}  onMouseLeave={hide}
+  //              position: fixed, z-index: 10000, pointer-events: auto
+}
+```
+
+- 禁止在 Modal 内用纯 CSS `position: absolute` 的 hover tooltip
+- 写完 tooltip 后必须实际验证：弹窗内滚动时气泡不被裁剪，鼠标能从图标移到气泡上阅读

package/rules/global.md

@@ -108,7 +108,7 @@ Closes #456
   1. 打开 PR 页面，逐一查看 Copilot review 提出的每一条问题。
   2. 逐条判断问题是否有道理：确实存在的代码缺陷、逻辑错误、安全风险、性能问题等 → 必须修复；误报、与需求不符、风格偏好无实质影响等 → 在评论中回复解释为何不改，然后 Resolve。
   3. 对于有道理的问题，直接修改代码、提交并推送到该 PR 分支。
-  4. 在 PR 评论中回复该问题（如”已修复”或简要说明修改内容），然后点击 Resolve conversation。
+  4. ⚠️ **强制步骤：修改代码并推送后，必须在 GitHub PR 页面上逐条点击 Resolve conversation。** 此步骤不可跳过——即使已回复评论、已推送修复代码，只要未点 Resolve，该条评论仍处于”未解决”状态，reviewer 无法判断是否已处理完毕。每修复一条，立即 Resolve 一条，不要等所有问题修完再批量操作。
   5. 所有问题处理完毕后，重新请求 Copilot review。
   6. 重复以上步骤，直到 Copilot review 不再提出新问题为止。
 - 每一条 Copilot review 评论处理完毕后，必须点击 **Resolve conversation**，不能只回复不 Resolve。不点 Resolve 会导致该评论一直处于未解决状态，无法判断是否已完成处理。
@@ -133,6 +133,7 @@ Closes #456
 - 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
 - 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
+- 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 
 ## 新需求与回归测试准入