From fba478dcca99e981076d27ae63aca2f5c5c0ef94 Mon Sep 17 00:00:00 2001
From: wuzilong <704541015@qq.com>
Date: Thu, 12 Nov 2026 19:24:37 +0800
Subject: [PATCH] docs: add document reminder edit-jump design and plan

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../2026-11-12-document-reminder-edit-jump.md | 413 ++++++++++++++++++
 ...1-12-document-reminder-edit-jump-design.md | 117 +++++
 2 files changed, 530 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-11-12-document-reminder-edit-jump.md
 create mode 100644 docs/superpowers/specs/2026-11-12-document-reminder-edit-jump-design.md

diff --git a/docs/superpowers/plans/2026-11-12-document-reminder-edit-jump.md b/docs/superpowers/plans/2026-11-12-document-reminder-edit-jump.md
new file mode 100644
index 000000000..07ba76578
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-12-document-reminder-edit-jump.md
@@ -0,0 +1,413 @@
+# 证件到期提醒跳转编辑弹窗 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:** 在证件到期提醒列表增加「维护证件」操作列，按车辆/人员及自有/三方跳到基础信息库对应页并自动打开编辑弹窗。
+
+**Architecture:** 纯函数根据主体类型与归属字段解析目标 path；提醒页 get 详情后 `router.push({ path, query: { editId } })`；车辆/自有车辆/人员页监听 `editId` 调用现有 `handleEdit`，成功后 `replace` 清除 query。后端不动。
+
+**Tech Stack:** Vue 3 / TypeScript / vue-router / Element Plus；`node:test` + `tsx`。
+
+**Spec:** `docs/superpowers/specs/2026-11-12-document-reminder-edit-jump-design.md`
+
+---
+
+## File map
+
+| File | Responsibility |
+| --- | --- |
+| `web-admin/src/utils/pl-document-reminder-jump.ts` | 解析目标 path；错误文案常量 |
+| `web-admin/src/utils/pl-document-reminder-jump.test.ts` | 路径解析单测 |
+| `web-admin/src/composables/useRouteEditIdOpen.ts` | 监听 `editId`、调用 opener、清 query |
+| `web-admin/src/views/pl/inventory/document-reminder.vue` | 操作列 + 跳转 |
+| `web-admin/src/views/pl/vehicle/index.vue` | 接入 `editId` 打开编辑 |
+| `web-admin/src/views/pl/self-vehicle/index.vue` | 同上 |
+| `web-admin/src/views/pl/personnel/index.vue` | 同上（覆盖 self / carrier 两路由） |
+
+说明：提交步骤在已获用户授权时执行；否则暂存改动待授权再 commit。
+
+---
+
+### Task 1: 路径解析纯函数 + 单测
+
+**Files:**
+- Create: `web-admin/src/utils/pl-document-reminder-jump.ts`
+- Create: `web-admin/src/utils/pl-document-reminder-jump.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import {
+  resolveDocumentReminderEditPath,
+  DOCUMENT_REMINDER_JUMP_UNSUPPORTED
+} from './pl-document-reminder-jump'
+
+describe('证件提醒跳转路径', () => {
+  it('车辆按 vehicleType 分流自有与三方', () => {
+    assert.equal(
+      resolveDocumentReminderEditPath({ ownerType: 'vehicle', vehicleType: 'self' }),
+      '/vehicle-mgmt/base-info/self-vehicle'
+    )
+    assert.equal(
+      resolveDocumentReminderEditPath({ ownerType: 'vehicle', vehicleType: 'carrier' }),
+      '/vehicle-mgmt/base-info/vehicle'
+    )
+    assert.equal(
+      resolveDocumentReminderEditPath({ ownerType: 'vehicle', vehicleType: '' }),
+      '/vehicle-mgmt/base-info/vehicle'
+    )
+  })
+
+  it('人员按 personnelAffiliation 分流', () => {
+    assert.equal(
+      resolveDocumentReminderEditPath({
+        ownerType: 'personnel',
+        personnelAffiliation: 'self'
+      }),
+      '/vehicle-mgmt/base-info/personnel'
+    )
+    assert.equal(
+      resolveDocumentReminderEditPath({
+        ownerType: 'personnel',
+        personnelAffiliation: 'carrier'
+      }),
+      '/vehicle-mgmt/base-info/personnel-carrier'
+    )
+    assert.equal(
+      resolveDocumentReminderEditPath({
+        ownerType: 'personnel',
+        personnelAffiliation: ''
+      }),
+      '/vehicle-mgmt/base-info/personnel'
+    )
+  })
+
+  it('不支持的主体返回 null', () => {
+    assert.equal(resolveDocumentReminderEditPath({ ownerType: 'carrier' }), null)
+    assert.equal(resolveDocumentReminderEditPath({ ownerType: '' }), null)
+    assert.equal(DOCUMENT_REMINDER_JUMP_UNSUPPORTED, '暂不支持该主体类型的证件维护跳转')
+  })
+})
+```
+
+- [ ] **Step 2: 跑测确认失败**
+
+```bash
+cd web-admin && ./node_modules/.bin/tsx --test src/utils/pl-document-reminder-jump.test.ts
+```
+
+Expected: FAIL（模块不存在）
+
+- [ ] **Step 3: 实现**
+
+```ts
+export const DOCUMENT_REMINDER_JUMP_UNSUPPORTED = '暂不支持该主体类型的证件维护跳转'
+
+export type ReminderJumpInput = {
+  ownerType?: string | null
+  vehicleType?: string | null
+  personnelAffiliation?: string | null
+}
+
+export function resolveDocumentReminderEditPath(input: ReminderJumpInput): string | null {
+  const ownerType = String(input.ownerType || '').trim()
+  if (ownerType === 'vehicle') {
+    return String(input.vehicleType || '').trim() === 'self'
+      ? '/vehicle-mgmt/base-info/self-vehicle'
+      : '/vehicle-mgmt/base-info/vehicle'
+  }
+  if (ownerType === 'personnel') {
+    return String(input.personnelAffiliation || '').trim() === 'carrier'
+      ? '/vehicle-mgmt/base-info/personnel-carrier'
+      : '/vehicle-mgmt/base-info/personnel'
+  }
+  return null
+}
+```
+
+- [ ] **Step 4: 跑测确认通过**
+
+同 Step 2，Expected: PASS
+
+- [ ] **Step 5: Commit（需授权）**
+
+```bash
+git add web-admin/src/utils/pl-document-reminder-jump.ts \
+  web-admin/src/utils/pl-document-reminder-jump.test.ts
+git commit -m "$(cat <<'EOF'
+feat(web-admin): add document reminder jump path resolver
+
+EOF
+)"
+```
+
+---
+
+### Task 2: `useRouteEditIdOpen` composable
+
+**Files:**
+- Create: `web-admin/src/composables/useRouteEditIdOpen.ts`
+
+- [ ] **Step 1: 实现 composable**
+
+```ts
+import { watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+/**
+ * 监听 route.query.editId，调用 openById；结束后清除 editId，避免刷新重复弹窗。
+ * openById 应自行处理加载失败提示。
+ */
+export function useRouteEditIdOpen(openById: (id: string) => void | Promise<void>) {
+  const route = useRoute()
+  const router = useRouter()
+
+  async function consumeEditId() {
+    const raw = route.query.editId
+    const id = Array.isArray(raw) ? String(raw[0] || '') : String(raw || '')
+    if (!id.trim()) return
+    try {
+      await openById(id.trim())
+    } finally {
+      if (route.query.editId == null) return
+      const query = { ...route.query }
+      delete query.editId
+      await router.replace({ path: route.path, query })
+    }
+  }
+
+  watch(
+    () => route.query.editId,
+    () => {
+      void consumeEditId()
+    },
+    { immediate: true }
+  )
+}
+```
+
+- [ ] **Step 2: Commit（需授权）**
+
+```bash
+git add web-admin/src/composables/useRouteEditIdOpen.ts
+git commit -m "$(cat <<'EOF'
+feat(web-admin): add useRouteEditIdOpen for deep-link edit dialogs
+
+EOF
+)"
+```
+
+---
+
+### Task 3: 提醒列表操作列与跳转
+
+**Files:**
+- Modify: `web-admin/src/views/pl/inventory/document-reminder.vue`
+
+- [ ] **Step 1: 模板 — 在 `</ListTable>` 前增加操作列**
+
+在状态/备注列之后、`</ListTable>` 之前插入：
+
+```vue
+            <el-table-column label="操作" fixed="right" min-width="140" align="center">
+              <template #default="{ row }">
+                <el-button
+                  link
+                  type="primary"
+                  :loading="maintainLoadingId === row.id"
+                  @click="handleMaintainCert(row)"
+                >
+                  <el-icon><EditPen /></el-icon>维护证件
+                </el-button>
+              </template>
+            </el-table-column>
+```
+
+- [ ] **Step 2: script — 导入与跳转逻辑**
+
+1. 图标：`import { CircleCheck, Filter, EditPen } from '@element-plus/icons-vue'`
+2. API：`import { inventoryApi, vehicleApi, personnelApi, type DocumentReminder } from '@/api/pl'`
+3. `import { useRouter } from 'vue-router'`（若尚未）
+4. `import { pickBxData } from '@/utils/http/bx'`
+5. `import { resolveDocumentReminderEditPath, DOCUMENT_REMINDER_JUMP_UNSUPPORTED } from '@/utils/pl-document-reminder-jump'`
+6. `import type { VehicleDetail, PersonnelDetail } from '@/api/pl'`（若类型从同文件导出则合并 import）
+
+```ts
+const router = useRouter()
+const maintainLoadingId = ref<string | null>(null)
+
+async function handleMaintainCert(row: DocumentReminder) {
+  const ownerId = String(row.ownerId || '').trim()
+  const ownerType = String(row.ownerType || '').trim()
+  if (!ownerId || !ownerType) {
+    ElMessage.warning('缺少主体信息，无法跳转维护')
+    return
+  }
+  maintainLoadingId.value = row.id
+  try {
+    let path: string | null = null
+    if (ownerType === 'vehicle') {
+      const res = await vehicleApi.get(ownerId)
+      const detail = pickBxData<VehicleDetail>(res) || (res as any)?.data || res
+      const vehicleType = String((detail as VehicleDetail)?.vehicleType || '')
+      path = resolveDocumentReminderEditPath({ ownerType, vehicleType })
+    } else if (ownerType === 'personnel') {
+      const res = await personnelApi.get(ownerId)
+      const detail = pickBxData<PersonnelDetail>(res) || (res as any)?.data || res
+      const personnelAffiliation = String(
+        (detail as PersonnelDetail)?.personnelAffiliation || ''
+      )
+      path = resolveDocumentReminderEditPath({ ownerType, personnelAffiliation })
+    } else {
+      ElMessage.warning(DOCUMENT_REMINDER_JUMP_UNSUPPORTED)
+      return
+    }
+    if (!path) {
+      ElMessage.warning(DOCUMENT_REMINDER_JUMP_UNSUPPORTED)
+      return
+    }
+    await router.push({ path, query: { editId: ownerId } })
+  } catch {
+    ElMessage.error('无法打开主体档案，请确认数据存在且有权限')
+  } finally {
+    maintainLoadingId.value = null
+  }
+}
+```
+
+确保页面已导入 `ElMessage`（项目若自动导入则无需手写）。
+
+- [ ] **Step 3: Commit（需授权）**
+
+```bash
+git add web-admin/src/views/pl/inventory/document-reminder.vue
+git commit -m "$(cat <<'EOF'
+feat(web-admin): add maintain-cert action on document reminder list
+
+EOF
+)"
+```
+
+---
+
+### Task 4: 车辆 / 自有车辆页响应 `editId`
+
+**Files:**
+- Modify: `web-admin/src/views/pl/vehicle/index.vue`
+- Modify: `web-admin/src/views/pl/self-vehicle/index.vue`
+
+- [ ] **Step 1: vehicle/index.vue**
+
+在 `handleEdit` 定义之后加入：
+
+```ts
+import { useRouteEditIdOpen } from '@/composables/useRouteEditIdOpen'
+
+useRouteEditIdOpen(async (id) => {
+  await handleEdit({ id } as Vehicle)
+})
+```
+
+确认 `handleEdit` 仅依赖 `row.id` 拉详情（现有实现用 `vehicleApi.get(row.id)`）。若 TypeScript 抱怨，使用 `as Vehicle` 或最小对象即可。
+
+- [ ] **Step 2: self-vehicle/index.vue**
+
+同样在 `handleEdit` 之后：
+
+```ts
+import { useRouteEditIdOpen } from '@/composables/useRouteEditIdOpen'
+
+useRouteEditIdOpen(async (id) => {
+  await handleEdit({ id } as Vehicle)
+})
+```
+
+（若自有车页 Vehicle 类型同名，用该页已有类型。）
+
+- [ ] **Step 3: Commit（需授权）**
+
+```bash
+git add web-admin/src/views/pl/vehicle/index.vue \
+  web-admin/src/views/pl/self-vehicle/index.vue
+git commit -m "$(cat <<'EOF'
+feat(web-admin): open vehicle edit dialog from editId query
+
+EOF
+)"
+```
+
+---
+
+### Task 5: 人员页响应 `editId`
+
+**Files:**
+- Modify: `web-admin/src/views/pl/personnel/index.vue`
+
+- [ ] **Step 1: 接入 composable**
+
+在 `handleEdit` 之后：
+
+```ts
+import { useRouteEditIdOpen } from '@/composables/useRouteEditIdOpen'
+
+useRouteEditIdOpen(async (id) => {
+  await handleEdit({ id } as Personnel)
+})
+```
+
+该组件同时挂 `personnel` 与 `personnel-carrier`，两路由都会响应 `editId`。提醒页已按 affiliation 选对 path；若进错页，`handleEdit`/列表数据范围会失败——保持现有错误提示即可，必要时在 `openById` 外包一层 try/catch 用 `ElMessage.error`。
+
+- [ ] **Step 2: Commit（需授权）**
+
+```bash
+git add web-admin/src/views/pl/personnel/index.vue
+git commit -m "$(cat <<'EOF'
+feat(web-admin): open personnel edit dialog from editId query
+
+EOF
+)"
+```
+
+---
+
+### Task 6: 验证
+
+**Files:** 无必须改动。
+
+- [ ] **Step 1: 单元测试**
+
+```bash
+cd web-admin && ./node_modules/.bin/tsx --test src/utils/pl-document-reminder-jump.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 2: 手工冒烟（需登录）**
+
+1. 打开 `/#/pl/document-reminder-module/document-reminder`
+2. 点车辆行「维护证件」→ 进入对应自有/三方车辆页且编辑弹窗打开，证件可编辑
+3. 点人员行同理
+4. 刷新目标页不重复弹窗（query 已清）
+5. 原「处理」按钮仍可用
+
+- [ ] **Step 3: 记录未跑项**
+
+若无法登录 UI，在交付说明写明仅完成单测与代码接入，UI 冒烟待用户验证。
+
+---
+
+## Spec coverage
+
+| 设计项 | 任务 |
+| --- | --- |
+| 操作列「维护证件」 | Task 3 |
+| 按类型/归属分流 path | Task 1 + 3 |
+| `editId` 打开编辑并清 query | Task 2 + 4 + 5 |
+| 后端不动 / 不自动 resolve | 全程遵守 |
+| 仅 Web | 不改 miniprogram |
+
+## Placeholder scan
+
+无 TBD；路径、文件、测试命令、代码块已钉死。
diff --git a/docs/superpowers/specs/2026-11-12-document-reminder-edit-jump-design.md b/docs/superpowers/specs/2026-11-12-document-reminder-edit-jump-design.md
new file mode 100644
index 000000000..765d19615
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-12-document-reminder-edit-jump-design.md
@@ -0,0 +1,117 @@
+# 证件到期提醒跳转基础信息库编辑弹窗（Web）
+
+## 背景与问题
+
+Web【证件到期提醒】（`/#/pl/document-reminder-module/document-reminder`）展示车辆、人员证件过期信息。用户处理时需要到【基础信息库】打开对应档案弹窗补录/更新证件，当前需手动找菜单与记录，路径长。
+
+用户希望列表增加操作列，点击后进入基础信息库并直接打开编辑弹窗。示例链接曾指向承运商页；经核对提醒主体为 `vehicle` / `personnel`，应按主体类型跳到车辆或人员档案，而不是一律进承运商。
+
+## 已确认决策
+
+| 项 | 结论 |
+| --- | --- |
+| 跳转策略 | 按 `ownerType` 分流：车辆 → 车辆档案；人员 → 人员档案 |
+| 车辆细分 | 根据车辆 `vehicleType`：`self` → 山峡自有车辆；否则（含 `carrier`）→ 三方车辆 |
+| 人员细分 | 根据 `personnelAffiliation`：`self` → 山峡驾押人员；`carrier` → 三方驾押人员 |
+| 打开方式 | 目标页自动打开**编辑**弹窗（非仅查看） |
+| 实现方案 | 方案 1：提醒页点操作时先 get 主体详情判定归属，再 `router.push` 带 `editId` |
+| 后端 | 本期不改提醒接口；不新增 `routeHint` 字段 |
+| 范围 | 仅 Web；小程序不改 |
+| 提醒状态 | 不因跳转/保存档案自动标为已处理；仍用现有「处理」按钮 |
+| 证件定位 | 本期不强制 `focusCert`；打开编辑弹窗即可 |
+
+## 范围
+
+**包含**
+
+- `document-reminder.vue`：操作列与跳转编排
+- `vehicle/index.vue`、`self-vehicle/index.vue`：监听 `editId` 打开编辑
+- `personnel/index.vue`（自有与三方共用组件、靠 `meta.affiliationMode`）：监听 `editId` 打开编辑
+
+**不包含**
+
+- 承运商页深链（提醒无承运商主体）
+- 小程序 / 移动 H5
+- 后端提醒列表字段 enrichment
+- 保存档案后自动 resolve 提醒
+- 弹窗内自动滚动到某一证件行（可后续加 `focusCert`）
+
+## 路由约定
+
+| 条件 | 目标 path |
+| --- | --- |
+| vehicle + `vehicleType === 'self'` | `/vehicle-mgmt/base-info/self-vehicle` |
+| vehicle + 其他 | `/vehicle-mgmt/base-info/vehicle` |
+| personnel + `personnelAffiliation === 'carrier'` | `/vehicle-mgmt/base-info/personnel-carrier` |
+| personnel + 其他（默认 self） | `/vehicle-mgmt/base-info/personnel` |
+
+Query：
+
+- `editId`：主体主键（`ownerId`），必填语义
+- 打开弹窗成功后 `router.replace` 去掉 `editId`（保留同页其他 query），避免刷新重复弹窗
+
+深链示例：
+
+`/#/vehicle-mgmt/base-info/vehicle?editId=<vehicleId>`
+
+## 前端设计
+
+### 证件提醒页
+
+文件：`web-admin/src/views/pl/inventory/document-reminder.vue`
+
+- 表格最右增加 `fixed="right"` 操作列，`min-width` ≥ 120（单按钮可略窄，但须符合 Web AGENTS 操作列惯例；若仅一枚按钮可用约 120–140）。
+- 按钮文案：**维护证件**；带前置图标（如 `EditPen` / `Document`）。
+- 点击 `handleMaintainCert(row)`：
+  1. 校验 `row.ownerId` 与 `row.ownerType`；缺失则 `ElMessage.warning`。
+  2. `ownerType === 'vehicle'`：`vehicleApi.get(ownerId)`，取 `vehicleType`，选择 path。
+  3. `ownerType === 'personnel'`：`personnelApi.get(ownerId)`（或现有等价 API），取 `personnelAffiliation`，选择 path。
+  4. 其他 `ownerType`：提示暂不支持。
+  5. `router.push({ path, query: { editId: ownerId } })`。
+  6. get 失败（404/无权限）：`ElMessage.error`，不跳转。
+- 保留工具栏现有「处理」逻辑不变。
+- loading：按钮或行级 loading，避免连点。
+
+### 目标档案页共用行为
+
+在 `vehicle`、`self-vehicle`、`personnel` 页面（personnel 覆盖两种 affiliation 路由）：
+
+1. `watch` / `onMounted` 读取 `route.query.editId`（仅当当前页 path 属于本页）。
+2. 有值则调用现有 `handleEdit` 等价逻辑：先用 `{ id: editId }` 或先 `get(editId)` 再打开编辑弹窗（与页内编辑一致，含证件列表回填）。
+3. 成功打开或明确失败后，清除 `editId` query。
+4. 若 `editId` 不属于本页数据范围（例如自有车页打开了三方车 id）：提示失败并清 query；提醒页已按类型分流，此为兜底。
+
+实现时优先抽一小段 composable（可选，非必须），例如 `useRouteEditIdOpen(handler)`，避免三处复制 watch/replace；若页内差异大则内联亦可，保持最小改动。
+
+### 权限
+
+- 跳转后目标菜单仍受角色菜单与数据范围约束；无菜单权限时路由/页面按现有行为处理。
+- 提醒页不新增后端权限码；操作列对所有能进提醒页的用户可见。
+
+## 后端
+
+无变更。列表继续返回现有 `ownerType` / `ownerId` / `documentType` 等字段。
+
+## UI 规范
+
+- 沿用提醒页现有列表模式与 Fresh Mint；操作列图标+文字，不新造布局。
+- 不因本需求改顶部统计或筛选结构。
+
+## 验收
+
+1. 车辆提醒「维护证件」→ 正确进入自有或三方车辆页，并弹出编辑框，可见证件字段。
+2. 人员提醒同理进入山峡/三方驾押人员页并弹出编辑框。
+3. 无 `ownerId`、主体不存在、无权限时有明确提示且不误跳。
+4. 刷新目标页或清 query 后不重复自动弹窗。
+5. 原「处理」标记已办流程与导出不受影响。
+6. 小程序未改。
+
+## 风险
+
+- 自有/三方分流依赖详情字段；字段异常时可能进错页，需兜底提示。
+- 档案页 `keepAlive` 若开启，需确认二次带 `editId` 进入仍触发打开（watch 全量 query，不只 onMounted）。
+- 连续从提醒跳多条时，依赖清 query + 新 `editId` 再次触发。
+
+## 状态
+
+会话中已确认按主体类型跳转（方案 1）。实现计划：`docs/superpowers/plans/2026-11-12-document-reminder-edit-jump.md`。