docs(rank): 补中文注释说明埋点组件与 tab 壳子意图

- DocsPageViewTracker 说明埋点目的、sessionStorage 去重策略与静默失败
- RankTabs 解释为什么状态走 URL query 而不是 component state

Author: longsizhuo

app/components/DocsPageViewTracker.tsx

@@ -3,24 +3,38 @@
 import { usePathname } from "next/navigation";
 import { useEffect } from "react";
 
+/**
+ * 文档页面访问埋点组件。
+ *
+ * 放在 app/docs/layout.tsx 下，pathname 变化时向自家 /api/analytics 上报一次 page_view，
+ * 供将来基于 AnalyticsEvent 表做文档热度分析（当前 A-2 功能的热榜是用 GA4 数据，此处并行积累自家数据）。
+ *
+ * 去重策略：同一浏览器会话内同一 path 只报一次（sessionStorage key = "pv_reported:<path>"）。
+ * 为什么用 sessionStorage 不用 localStorage：关闭标签页后应当算新会话，否则长期复访的用户会被严重低估。
+ *
+ * 无返回 UI（return null），仅作副作用组件使用。
+ */
 export function DocsPageViewTracker() {
   const pathname = usePathname();
 
   useEffect(() => {
     if (!pathname) return;
 
+    // 同会话同 path 已上报则跳过，避免刷新/快速切换重复计数
     const key = `pv_reported:${pathname}`;
     if (sessionStorage.getItem(key)) return;
 
     sessionStorage.setItem(key, "1");
 
+    // 如果用户登录了，带上 Sa-Token 让后端能把事件关联到 userId；匿名用户后端会写入 userId=null
     const token =
       typeof window !== "undefined" ? localStorage.getItem("satoken") : null;
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
     };
     if (token) headers["x-satoken"] = token;
 
+    // 埋点失败静默吞掉：不能因为分析接口挂了影响文档页的正常阅读体验
     fetch("/api/analytics", {
       method: "POST",
       headers,

app/components/rank/RankTabs.tsx

@@ -7,11 +7,25 @@ type Tab = "contributors" | "hot";
 type Window = "7d" | "30d" | "all";
 
 interface RankTabsProps {
+  /** Contributors tab 的静态内容，由 /rank/page.tsx SSR 渲染后以 children 传入 */
   children: React.ReactNode;
+  /** SSR 决定的初始 tab，来自 URL query ?tab=；客户端挂载后以 searchParams 为准 */
   initialTab: Tab;
+  /** SSR 决定的初始窗口，Hot Docs tab 用 */
   initialWindow: Window;
 }
 
+/**
+ * /rank 页的 Tab 壳子：Contributors（贡献者榜，静态 JSON）/ Hot Docs（热门文档榜，后端 API）。
+ *
+ * Tab 和窗口状态都写进 URL query（?tab=&window=），而不是组件内 state，这样：
+ *   1. 分享链接能直接定位到具体视图
+ *   2. 浏览器前进/后退正常切换
+ *   3. 刷新不丢状态
+ *
+ * 用 router.push 而非 replaceState 是为了让返回键能回到上一个 tab；窗口切换在 HotDocsTab 内部用
+ * replaceState，避免每切一次就污染历史栈。
+ */
 export function RankTabs({
   children,
   initialTab,
@@ -25,6 +39,7 @@ export function RankTabs({
   const switchTab = (tab: Tab) => {
     const params = new URLSearchParams(searchParams.toString());
     params.set("tab", tab);
+    // 首次切到 Hot Docs 还没选过窗口时默认 30d，避免 HotDocsTab 拿到 undefined
     if (tab === "hot" && !params.get("window")) {
       params.set("window", "30d");
     }