Files
shanxia2.0/docs/superpowers/plans/2026-11-12-document-reminder-edit-jump.md
T

12 KiB
Raw Blame History

证件到期提醒跳转编辑弹窗 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: 写失败测试

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: 跑测确认失败
cd web-admin && ./node_modules/.bin/tsx --test src/utils/pl-document-reminder-jump.test.ts

Expected: FAIL(模块不存在)

  • Step 3: 实现
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(需授权)
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

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(需授权)
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> 之前插入:

            <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)
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(需授权)
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 定义之后加入:

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 之后:

import { useRouteEditIdOpen } from '@/composables/useRouteEditIdOpen'

useRouteEditIdOpen(async (id) => {
  await handleEdit({ id } as Vehicle)
})

(若自有车页 Vehicle 类型同名,用该页已有类型。)

  • Step 3: Commit(需授权)
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 之后:

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(需授权)
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: 单元测试
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;路径、文件、测试命令、代码块已钉死。