Add implementation plan: record detail context menu

docs/superpowers/plans/2026-06-24-record-detail-context-menu.md

@@ -0,0 +1,372 @@
+# 右键查看完整记录（记录详情 Modal）Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在生产数据表的数据行上右键，弹出自定义菜单「查看完整记录」，点击后用 Modal 完整展示该记录的全部字段。
+
+**Architecture:** 纯逻辑（取标题、格式化单元格值）抽到 `record-detail.ts` 并单测；展示用 `RecordDetailModal`（antd `Modal` + `Descriptions`）；`page.tsx` 增加右键菜单浮层（fixed 定位 + 透明 backdrop 关闭）与 modal 状态。内联表格保持 `ellipsis` 不变。
+
+**Tech Stack:** Next 16.2.9（已存在 `"use client"` 组件内改动，无路由/server/API 变更）、React 19.2.4、antd 6.4.3、vitest（node 环境，仅测纯逻辑）。
+
+## Global Constraints
+
+- antd **6.4.3**：`Modal` 不传 `destroyOnClose`/`destroyOnHidden`（v6 中前者已弃用，本逻辑无需销毁）；`Descriptions`/`Modal`/`Empty` 已确认存在。遵 `AGENTS.md`：留意弃用提示。
+- 改动全部落在现有 `"use client"` 组件 `src/app/page.tsx` 及同目录新文件，**无 Next.js 路由/server/API 变更**。
+- 测试：vitest，`environment: node`，仅匹配 `src/**/*.test.ts`（不渲染 React 组件）；UI 交互以浏览器手验为准。
+- UI 文案用中文（与现有标签一致）；commit message 用英文。
+- **完成后不部署**，仅启动本地 `next dev` 供用户验证，验证通过后再部署。
+
+## File Structure
+
+| 文件 | 责任 | 动作 |
+|------|------|------|
+| `src/app/record-detail.ts` | 纯函数：`pickRecordTitle`、`formatCellValue` | 新增 |
+| `src/app/record-detail.test.ts` | 上述纯函数的 vitest 单测 | 新增 |
+| `src/app/record-detail-modal.tsx` | `RecordDetailModal` 展示组件（Modal + Descriptions） | 新增 |
+| `src/app/page.tsx` | 右键菜单浮层 + onRow.onContextMenu + 状态 + 挂载 Modal | 修改 |
+
+---
+
+## Task 1: 纯函数 `pickRecordTitle` / `formatCellValue`（TDD）
+
+**Files:**
+- Create: `src/app/record-detail.ts`
+- Test: `src/app/record-detail.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `pickRecordTitle(record: DataRow): string` — 按 `生产订单号 → 总排号 → ID` 取首个非空字段字符串；全空返回 `"（未命名）"`。
+  - `formatCellValue(value: string | number | null): string` — `null`/空串/纯空白 → `"—"`；其余 `String(value)`（`0` 视为非空）。
+
+- [ ] **Step 1: 写失败测试**
+
+Create `src/app/record-detail.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { pickRecordTitle, formatCellValue } from "./record-detail";
+import type { DataRow } from "./table-filters";
+
+describe("pickRecordTitle", () => {
+  it("prefers 生产订单号", () => {
+    const row: DataRow = { 生产订单号: "PO-1", 总排号: "X", ID: 1 };
+    expect(pickRecordTitle(row)).toBe("PO-1");
+  });
+  it("falls back to 总排号 when 生产订单号 blank", () => {
+    const row: DataRow = { 生产订单号: "  ", 总排号: "X-9", ID: 1 };
+    expect(pickRecordTitle(row)).toBe("X-9");
+  });
+  it("falls back to ID when earlier are null/empty", () => {
+    const row: DataRow = { 生产订单号: null, 总排号: "", ID: 42 };
+    expect(pickRecordTitle(row)).toBe("42");
+  });
+  it("returns （未命名） when all blank", () => {
+    const row: DataRow = { 生产订单号: null, 总排号: null, ID: null };
+    expect(pickRecordTitle(row)).toBe("（未命名）");
+  });
+});
+
+describe("formatCellValue", () => {
+  it("null -> em dash", () => {
+    expect(formatCellValue(null)).toBe("—");
+  });
+  it("empty / whitespace -> em dash", () => {
+    expect(formatCellValue("")).toBe("—");
+    expect(formatCellValue("   ")).toBe("—");
+  });
+  it("0 is NOT blank", () => {
+    expect(formatCellValue(0)).toBe("0");
+  });
+  it("number stringified", () => {
+    expect(formatCellValue(123)).toBe("123");
+  });
+  it("text preserved", () => {
+    expect(formatCellValue("量程0-1.6MPa")).toBe("量程0-1.6MPa");
+  });
+});
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `npx vitest run src/app/record-detail.test.ts`
+Expected: FAIL — `pickRecordTitle` / `formatCellValue` 未导出（模块不存在）。
+
+- [ ] **Step 3: 写最小实现**
+
+Create `src/app/record-detail.ts`:
+
+```ts
+import type { DataRow } from "./table-filters";
+
+/**
+ * 取记录的友好标识（用于详情 Modal 标题）。
+ * 优先级：生产订单号 > 总排号 > ID > （未命名）。
+ */
+export function pickRecordTitle(record: DataRow): string {
+  for (const key of ["生产订单号", "总排号", "ID"]) {
+    const v = record[key];
+    if (v !== null && v !== undefined && String(v).trim() !== "") {
+      return String(v);
+    }
+  }
+  return "（未命名）";
+}
+
+/**
+ * 格式化单元格值用于详情 Modal 完整展示。
+ * null / 空串 / 纯空白 -> "—"；其余 String(value)。0 视为非空（与 isBlank 一致）。
+ */
+export function formatCellValue(value: string | number | null): string {
+  if (value === null || value === undefined) return "—";
+  const s = String(value);
+  if (s.trim() === "") return "—";
+  return s;
+}
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `npx vitest run src/app/record-detail.test.ts`
+Expected: PASS（全部用例）。
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/app/record-detail.ts src/app/record-detail.test.ts
+git commit -m "Add record-detail helpers (title picker, cell formatter)"
+```
+
+---
+
+## Task 2: RecordDetailModal 组件 + page.tsx 右键菜单与挂载
+
+**Files:**
+- Create: `src/app/record-detail-modal.tsx`
+- Modify: `src/app/page.tsx`（imports ~L4-16、state ~L503、onRow ~L657-660、render ~L689）
+
+**Interfaces:**
+- Consumes: Task 1 的 `pickRecordTitle`、`formatCellValue`；现有 `DataRow`（来自 `./table-filters`）、`columns`（`string[]`，全量数据列名）。
+- Produces: 页面右键 → 菜单 → Modal 完整展示该行所有字段。
+
+- [ ] **Step 1: 新建 `RecordDetailModal` 组件**
+
+Create `src/app/record-detail-modal.tsx`:
+
+```tsx
+"use client";
+
+import type { CSSProperties } from "react";
+import { Modal, Descriptions, Empty } from "antd";
+import type { DataRow } from "./table-filters";
+import { pickRecordTitle, formatCellValue } from "./record-detail";
+
+const VALUE_STYLE: CSSProperties = {
+  whiteSpace: "pre-wrap",
+  wordBreak: "break-all",
+};
+
+export function RecordDetailModal({
+  record,
+  columns,
+  open,
+  onClose,
+}: {
+  record: DataRow | null;
+  columns: string[];
+  open: boolean;
+  onClose: () => void;
+}) {
+  return (
+    <Modal
+      title={`记录详情：${record ? pickRecordTitle(record) : ""}`}
+      open={open}
+      onCancel={onClose}
+      footer={null}
+      width={900}
+    >
+      {record && columns.length > 0 ? (
+        <Descriptions column={2} bordered size="small">
+          {columns.map((col) => (
+            <Descriptions.Item key={col} label={col}>
+              <span style={VALUE_STYLE}>{formatCellValue(record[col])}</span>
+            </Descriptions.Item>
+          ))}
+        </Descriptions>
+      ) : (
+        <Empty description="无数据" />
+      )}
+    </Modal>
+  );
+}
+```
+
+- [ ] **Step 2: 在 `page.tsx` 增加 import**
+
+在 `src/app/page.tsx` 顶部 import 区（`import { nextLockedRow, type DataRow } from "./table-filters";` 之后）追加一行：
+
+```ts
+import { RecordDetailModal } from "./record-detail-modal";
+```
+
+- [ ] **Step 3: 在 `page.tsx` 增加状态**
+
+在 `Home()` 内现有 `const [filters, setFilters] = ...`（约 L503）之后追加：
+
+```ts
+  const [contextMenu, setContextMenu] = useState<{
+    record: DataRow;
+    x: number;
+    y: number;
+  } | null>(null);
+  const [detailRecord, setDetailRecord] = useState<DataRow | null>(null);
+```
+
+并在 `handleClear` 与 `handleSearch` 中已有的 `setFilters({})` 旁，分别追加关闭菜单/弹窗（搜索或清除后重置）：
+
+- `handleSearch` 成功分支（`setFilters({});` 之后）追加：
+  ```ts
+      setContextMenu(null);
+      setDetailRecord(null);
+  ```
+- `handleClear`（`setFilters({});` 之后）追加：
+  ```ts
+    setContextMenu(null);
+    setDetailRecord(null);
+  ```
+
+- [ ] **Step 4: 扩展 `onRow` 捕获右键**
+
+将 `<Table>` 的 `onRow`（约 L657-660）由：
+
+```tsx
+            onRow={(record) => ({
+              onClick: () =>
+                setLockedRowKey((prev) => nextLockedRow(prev, String(record.ID))),
+            })}
+```
+
+改为：
+
+```tsx
+            onRow={(record) => ({
+              onClick: () =>
+                setLockedRowKey((prev) => nextLockedRow(prev, String(record.ID))),
+              onContextMenu: (e) => {
+                e.preventDefault();
+                setContextMenu({ record, x: e.clientX, y: e.clientY });
+              },
+            })}
+```
+
+- [ ] **Step 5: 渲染右键菜单浮层 + 挂载 Modal**
+
+在 `<ColumnSettingsModal ... />`（约 L689-694）**之后**、根 `</div>`（约 L695）**之前**插入：
+
+```tsx
+      {contextMenu && (
+        <>
+          <div
+            style={{ position: "fixed", inset: 0, zIndex: 1049 }}
+            onClick={() => setContextMenu(null)}
+            onContextMenu={(e) => {
+              e.preventDefault();
+              setContextMenu(null);
+            }}
+          />
+          <div
+            style={{
+              position: "fixed",
+              left: contextMenu.x,
+              top: contextMenu.y,
+              zIndex: 1050,
+              background: "#fff",
+              borderRadius: 8,
+              boxShadow: "0 6px 16px rgba(0,0,0,0.12)",
+              border: "1px solid #f0f0f0",
+              padding: 4,
+              minWidth: 140,
+              overflow: "hidden",
+            }}
+            onContextMenu={(e) => e.stopPropagation()}
+          >
+            <div
+              onClick={() => {
+                setDetailRecord(contextMenu.record);
+                setContextMenu(null);
+              }}
+              style={{ padding: "6px 14px", cursor: "pointer", fontSize: 14 }}
+              onMouseEnter={(e) =>
+                (e.currentTarget.style.background = "#f0f7ff")
+              }
+              onMouseLeave={(e) =>
+                (e.currentTarget.style.background = "transparent")
+              }
+            >
+              查看完整记录
+            </div>
+          </div>
+        </>
+      )}
+
+      <RecordDetailModal
+        record={detailRecord}
+        columns={columns}
+        open={!!detailRecord}
+        onClose={() => setDetailRecord(null)}
+      />
+```
+
+> 关闭逻辑说明：浮层背后有透明 backdrop（z-1049），任意左键/右键点击其区域即关闭菜单并屏蔽浏览器默认右键菜单；右键菜单本体（z-1050）`stopPropagation` 防止误关。无 `useEffect`/全局监听，无竞态。
+
+- [ ] **Step 6: 运行全部测试 + lint，确保无回归**
+
+Run: `npm test`
+Expected: 全部 PASS（含原有 `table-filters.test.ts` 与新 `record-detail.test.ts`）。
+
+Run: `npm run lint`
+Expected: 无 error（新增 `.tsx` 文件被 eslint 覆盖）。
+
+- [ ] **Step 7: 浏览器手验（启动本地服务，不部署）**
+
+Run（后台）: `npm run dev`
+打开: http://localhost:3000
+
+验证清单：
+- [ ] 输入车间号查询，出现数据表。
+- [ ] 在**数据行**上右键 → 出现自定义菜单「查看完整记录」，且**不**弹出浏览器默认右键菜单。
+- [ ] 表头 / 空白处右键 → 不出现自定义菜单（浏览器默认菜单照常）。
+- [ ] 点「查看完整记录」→ 弹出 Modal，标题为 `记录详情：<生产订单号/总排号/ID>`；内容为该行**全部字段**（含已隐藏列），按数据列顺序排列。
+- [ ] 长内容字段（如 技术参数 / 缺件明细）在 Modal 内**自动换行、完整可见、不截断**；字段很多时 Modal 内可纵向滚动。
+- [ ] 空值字段显示为 `—`。
+- [ ] 左键点击行 → 仍可锁定/解锁高亮（橙底）；右键与左键互不干扰。
+- [ ] Esc / 点击 Modal 外 / 点 backdrop → 分别能关闭 Modal / 菜单。
+- [ ] 点「清除」或重新查询 → 菜单与 Modal 被重置。
+
+- [ ] **Step 8: 提交**
+
+```bash
+git add src/app/record-detail-modal.tsx src/app/page.tsx
+git commit -m "Add right-click context menu to view full record in modal"
+git push
+```
+
+> 推送但不部署；等用户本地验证通过后，再按 `CLAUDE.local.md` 流程部署到 114。
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- 5.1 交互流程 → Task 2 Step 4/5（onRow.onContextMenu + backdrop 关闭 + 表头不弹）✅
+- 5.2 受控行级菜单 → Task 2 Step 5（backdrop + fixed 浮层，采用兜底自定义浮层方案，避开 antd Dropdown 受控定位风险）✅
+- 5.3 Modal（标题主标识、Descriptions 多列、全字段、滚动）→ Task 2 Step 1 ✅
+- 5.4 值渲染（pre-wrap/break-all、空→—）→ Task 1 `formatCellValue` + Step 1 VALUE_STYLE ✅
+- 5.5 状态与 onRow → Task 2 Step 3/4 ✅
+- 5.6 涉及文件 → File Structure 表 ✅
+- 6 边界（实时刷新快照、空值、超长、表头、筛选隐藏）→ 设计天然覆盖 + Step 7 验证 ✅
+- 7 测试 → Task 1 单测 + Task 2 Step 7 手验清单 ✅
+- 8 待核对（antd v6 API）→ 已核对 antd 6.4.3，Modal 不传 destroy 属性 ✅
+
+**Placeholder scan:** 无 TBD/TODO；所有步骤含完整代码与命令。
+
+**Type consistency:** `pickRecordTitle(record: DataRow)`、`formatCellValue(value: string|number|null): string` 在 Task 1 定义，Task 2 调用签名一致；`RecordDetailModal` props（record/columns/open/onClose）定义与 `page.tsx` 挂载处一致。`DataRow` 统一来自 `./table-filters`。