12 KiB
证件到期提醒跳转编辑弹窗 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 — 导入与跳转逻辑
- 图标:
import { CircleCheck, Filter, EditPen } from '@element-plus/icons-vue' - API:
import { inventoryApi, vehicleApi, personnelApi, type DocumentReminder } from '@/api/pl' import { useRouter } from 'vue-router'(若尚未)import { pickBxData } from '@/utils/http/bx'import { resolveDocumentReminderEditPath, DOCUMENT_REMINDER_JUMP_UNSUPPORTED } from '@/utils/pl-document-reminder-jump'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: 手工冒烟(需登录)
- 打开
/#/pl/document-reminder-module/document-reminder - 点车辆行「维护证件」→ 进入对应自有/三方车辆页且编辑弹窗打开,证件可编辑
- 点人员行同理
- 刷新目标页不重复弹窗(query 已清)
- 原「处理」按钮仍可用
- Step 3: 记录未跑项
若无法登录 UI,在交付说明写明仅完成单测与代码接入,UI 冒烟待用户验证。
Spec coverage
| 设计项 | 任务 |
|---|---|
| 操作列「维护证件」 | Task 3 |
| 按类型/归属分流 path | Task 1 + 3 |
editId 打开编辑并清 query |
Task 2 + 4 + 5 |
| 后端不动 / 不自动 resolve | 全程遵守 |
| 仅 Web | 不改 miniprogram |
Placeholder scan
无 TBD;路径、文件、测试命令、代码块已钉死。