fetch(add): 新增
Some checks failed
构建并部署前端到测试环境 / build-and-deploy (push) Failing after 6s

This commit is contained in:
sexygoat
2026-01-27 09:18:45 +08:00
parent 0eed8244e5
commit 5c6312c407
33 changed files with 4897 additions and 374 deletions

View File

@@ -0,0 +1,278 @@
# Device Management Design
## Context
The system currently has a basic device-import page but lacks comprehensive device management capabilities. Devices are critical assets that need to be tracked throughout their lifecycle - from import, allocation to shops, binding with SIM cards, to eventual recall. This change adds full device management to complement the existing card management features.
Key integration points:
- **Existing Card System**: Devices must bind with cards from the existing card-list module
- **Shop System**: Devices are allocated to shops using the existing ShopService
- **Object Storage**: Imports use the existing StorageService for large file uploads
- **Task System**: Import tasks must integrate with the existing task-management infrastructure
## Goals
1. **Complete Lifecycle Management**: Support all device operations from import to deletion
2. **Seamless Integration**: Reuse existing UI patterns, services, and components
3. **Scalable Import**: Handle large CSV imports efficiently using object storage
4. **Operation Traceability**: Track all device operations through task management
5. **Consistent UX**: Match the look and feel of existing card-list and enterprise-customer pages
## Key Decisions
### Decision 1: Three-Step Object Storage Import
**Choice**: Use StorageService.getUploadUrl → uploadFile → DeviceService.importDevices
**Rationale**:
- Handles large files (thousands of devices) without timeout issues
- Decouples upload from processing (backend can process asynchronously)
- Consistent with modern cloud architecture patterns
- Allows progress tracking through task management
**Alternatives Considered**:
- Direct multipart upload to backend (rejected: not scalable for large files)
- Two-step process without pre-signed URL (rejected: less secure, more backend load)
**Implementation Notes**:
- Frontend only handles upload to object storage, not file parsing
- Backend processes the file asynchronously and creates task records
- Task management provides visibility into import progress
### Decision 2: Device-Card Binding Model
**Choice**: Store binding with explicit slot_position (1-4) in device_cards table
**Rationale**:
- IoT devices have physical SIM slots that need explicit identification
- Each device can have 1-4 slots (max_sim_slots)
- One card can only bind to one device slot (enforced by backend)
- Slot position is critical for physical device configuration
**Alternatives Considered**:
- Auto-assign slot positions (rejected: operators need to know physical slot numbers)
- Allow one card to bind to multiple devices (rejected: not realistic for physical SIMs)
**Implementation Notes**:
- Device detail page shows a 4-slot grid (empty slots show "Bind Card" button)
- Binding dialog requires explicit slot selection
- Unbinding updates bound_card_count and frees the slot
### Decision 3: Unified Task Management
**Choice**: Extend existing task-management to support device import tasks
**Rationale**:
- Reuses existing task infrastructure
- Provides consistent UX for all import operations
- Avoids duplicate task tracking logic
- Allows unified search/filter across task types
**Alternatives Considered**:
- Separate device task management page (rejected: creates UX fragmentation)
- Embed task tracking only in device-import page (rejected: limited visibility)
**Implementation Notes**:
- Add task_type field to distinguish ICCID vs Device imports
- Task detail page renders different content based on task_type
- Device tasks show device_no and bound ICCIDs instead of just ICCID
### Decision 4: Batch Operation Result Display
**Choice**: Show detailed results in dialog after batch allocation/recall
**Rationale**:
- Operations may partially succeed (some devices succeed, others fail)
- Operators need to know exactly which devices failed and why
- Allows retry of failed operations without re-selecting all devices
**Alternatives Considered**:
- Just show toast notification (rejected: insufficient detail for partial failures)
- Navigate to separate results page (rejected: disrupts workflow)
**Implementation Notes**:
- Dialog shows summary: total, success count, failure count
- Expandable table shows failed devices with error messages
- Success closes dialog, partial failure keeps it open for review
### Decision 5: Component Reuse Strategy
**Choice**: Use existing Art* components (ArtTableFullScreen, ArtSearchBar, ArtTable, ArtButtonTable)
**Rationale**:
- Maintains UI consistency across the application
- Reduces development time
- Leverages tested, stable components
- Easier for users familiar with other pages
**Reference Implementation**:
- Device-list follows role/index.vue pattern
- Device-detail follows card-list detail modal pattern
- Search form follows enterprise-customer search pattern
**Implementation Notes**:
- Use CommonStatus for status values (ENABLED/DISABLED)
- Use ElSwitch for status toggles
- Use ArtButtonTable for action buttons
- Follow ElDescriptions layout for detail pages
## Architecture Diagrams
### Device Import Flow
```
┌─────────┐ 1. Select CSV ┌──────────────┐
│ Admin │ ──────────────────> │ device-import│
│ │ │ (Vue) │
└─────────┘ └──────┬───────┘
│ 2. getUploadUrl()
v
┌──────────────┐
│ Storage │
│ Service │
└──────┬───────┘
│ 3. Upload to OSS
v
┌──────────────┐
│ Object │
│ Storage │
└──────────────┘
│ 4. importDevices(file_key)
v
┌──────────────┐
│ Device │
│ Service │
└──────┬───────┘
│ 5. Create Task
v
┌──────────────┐
│ Task │
│ Management │
└──────────────┘
```
### Device-Card Binding
```
┌─────────┐ ┌──────────────┐
│ Device │ ───── bound to ────> │ Card │
│ │ (1 to N) │ │
└─────────┘ └──────────────┘
│ │
│ has_many bindings │ has_one binding
v v
┌─────────────────────────────────────────────┐
│ DeviceCardBinding │
│ - device_id │
│ - card_id │
│ - slot_position (1-4) │
│ - bound_at │
└─────────────────────────────────────────────┘
```
## Data Flow
### Device List Page Load
1. User navigates to /asset-management/device-list
2. Vue component mounts, calls DeviceService.getDevices(params)
3. Backend returns paginated device list with bound_card_count
4. Table renders with status switches and action buttons
### Batch Allocation Flow
1. User selects devices, clicks "Batch Allocate"
2. Dialog opens with shop selector
3. User selects shop, adds remarks, confirms
4. Call DeviceService.allocateDevices({ device_ids, shop_id, remarks })
5. Backend processes each device, returns results array
6. Dialog shows summary and failed device details
### Card Binding Flow
1. User opens device detail page
2. Clicks "Bind Card" for an empty slot
3. Dialog shows card search and slot selection
4. User selects card and slot (e.g., slot 3)
5. Call DeviceService.bindCard(device_id, { card_id, slot_position: 3 })
6. Backend validates slot is empty, creates binding
7. Refresh device detail to show new binding
## Migration Plan
### Updating Existing Device Import Page
**Current State** (`src/views/batch/device-import/index.vue`):
- Uses ElUpload with drag-and-drop
- Mock data for import records
- No real API integration
**Migration Steps**:
1. Replace ElUpload with three-step upload logic
- Add getUploadUrl call
- Add uploadFile to object storage
- Add importDevices call with file_key
2. Remove mock import records
3. Link to task-management for tracking
4. Update CSV format instructions
**Backward Compatibility**:
- This is a new feature area with no existing production data
- No API breaking changes
- UI changes are additive (improve existing page)
### Extending Task Management
**Current State**:
- Only handles ICCID import tasks
- Single task type rendering
**Migration Steps**:
1. Add task_type filter dropdown (default: show all)
2. Add task_type badge in task list
3. Task detail page: switch rendering based on task_type
4. Add device-specific fields to task detail view
**Backward Compatibility**:
- Existing ICCID tasks continue to work unchanged
- Filter defaults to showing all types
- No database schema changes required (task_type already exists)
## Testing Strategy
### Unit Testing
- DeviceService API methods with mock responses
- Form validation logic
- Utility functions (formatters, validators)
### Integration Testing
- Device list search and pagination
- Batch allocation with partial failures
- Card binding/unbinding workflow
- Import task creation and status tracking
### E2E Testing Scenarios
1. Import devices via CSV → verify task created → check task detail
2. Search devices → select multiple → allocate to shop → verify shop assignment
3. View device detail → bind card to slot 2 → unbind → verify empty slot
4. Batch recall devices → verify shop cleared → check operation history
### Performance Considerations
- Device list pagination (default 20 per page)
- Debounced search input (300ms delay)
- Batch operation result pagination (if >100 results)
- Large CSV imports handled asynchronously (no frontend timeout)
## Security Considerations
1. **Authorization**: All device operations require admin role
2. **Input Validation**:
- Device number format validation
- Slot position range (1 to max_sim_slots)
- CSV file size limits
3. **Object Storage Security**: Pre-signed URLs expire after 15 minutes
4. **Batch Operation Limits**: Backend enforces max 1000 devices per batch
5. **XSS Prevention**: All user inputs sanitized before rendering
## Open Questions
None at this time. All major design decisions have been made based on existing system patterns and API specifications.

View File

@@ -0,0 +1,60 @@
# Change: 添加设备管理功能
## Why
当前系统只有设备导入页面,缺少完整的设备管理能力。需要提供设备的全生命周期管理,包括:
- 查看和搜索设备列表
- 查看设备详情和绑定的卡信息
- 管理设备与卡的绑定关系
- 批量分配和回收设备
- 完善设备导入流程和任务追踪
这是物联网卡管理系统的核心资产管理功能之一。
## What Changes
### 新增功能
- **设备列表页面**: 支持多条件搜索、分页、列筛选、批量操作(分配、回收、删除)
- **设备详情页面**: 展示设备基本信息、绑定的卡列表、操作历史
- **卡绑定管理**: 在设备详情页绑定/解绑卡
- **批量分配对话框**: 选择设备批量分配给店铺
- **批量回收对话框**: 从店铺批量回收设备
- **设备导入改进**: 基于对象存储的三步导入流程
- **导入任务管理**: 任务列表和详情查看
### API 集成
- DeviceService: 11个API接口
- 类型定义: Device, DeviceBinding, ImportTask 等
### UI 组件
- 遵循现有组件模式 (ArtTableFullScreen, ArtSearchBar等)
- 复用 CommonStatus 统一状态变量
- 使用 ElDescriptions、ElTag、ElSwitch 等组件
## Impact
### 影响的功能模块
- **新增**: 资产管理 / 设备列表(主列表页)
- **新增**: 资产管理 / 设备详情
- **改进**: 批量操作 / 设备导入(改为对象存储模式)
- **新增**: 批量操作 / 导入任务列表(独立页面)
### 影响的代码
- `src/api/modules/device.ts` (新增)
- `src/types/api/device.ts` (新增)
- `src/views/asset-management/device-list/index.vue` (新增)
- `src/views/asset-management/device-detail/index.vue` (新增)
- `src/views/asset-management/task-management/index.vue` (修改:支持设备导入任务)
- `src/views/asset-management/task-detail/index.vue` (修改:支持设备导入任务详情)
- `src/views/batch/device-import/index.vue` (修改:使用对象存储)
- `src/router/routes/asyncRoutes.ts` (新增路由)
- `src/router/routesAlias.ts` (新增路由别名)
- `src/locales/langs/zh.json` (新增翻译)
- `src/api/modules/index.ts` (导出 DeviceService)
- `src/types/api/index.ts` (导出 Device 类型)
### 依赖关系
- 依赖现有的 StorageService (对象存储)
- 依赖现有的 ShopService (店铺选择)
- 设备与卡的关联管理
- 任务管理页面需要支持多种任务类型ICCID导入 + 设备导入)

View File

@@ -0,0 +1,159 @@
# Device Management Specification
## ADDED Requirements
### Requirement: Device List Management
The system SHALL provide a searchable device list with multi-condition filtering, pagination, and batch operations.
#### Scenario: Search devices by multiple criteria
**WHEN** an administrator enters search criteria (device number, device name, status, shop, batch number, device type, manufacturer, creation time range)
**THEN** the system shall display only devices matching all specified criteria with pagination support
#### Scenario: View device list with bound card count
**WHEN** the device list is displayed
**THEN** each device row shall show: ID, device number, device name, device model, device type, manufacturer, max slots, bound card count, status, shop, batch number, activation time, creation time
#### Scenario: Toggle device status
**WHEN** an administrator clicks the status switch for a device
**THEN** the system shall update the device status between ENABLED and DISABLED and refresh the display
#### Scenario: Delete a device
**WHEN** an administrator clicks the delete button and confirms the deletion
**THEN** the system shall delete the device and refresh the list
#### Scenario: Select multiple devices for batch operations
**WHEN** an administrator checks multiple device rows
**THEN** the system shall enable batch operation buttons (Allocate, Recall) and track selected device IDs
### Requirement: Device Detail Viewing
The system SHALL display comprehensive device information including basic properties and bound SIM cards.
#### Scenario: View device basic information
**WHEN** an administrator navigates to a device detail page
**THEN** the system shall display all device properties in a descriptive layout: device number, name, model, type, manufacturer, max SIM slots, status, shop, batch number, activation time, creation time
#### Scenario: View bound SIM cards with slot positions
**WHEN** viewing device details
**THEN** the system shall display a table of bound cards showing: slot position (1-4), ICCID, phone number, carrier, card status, and binding time
#### Scenario: Empty slots display
**WHEN** a device has fewer than max_sim_slots cards bound
**THEN** empty slot positions shall be clearly indicated with "Bind Card" action buttons
### Requirement: Device-Card Binding Management
The system SHALL allow administrators to bind and unbind SIM cards to specific device slots.
#### Scenario: Bind a card to a device slot
**WHEN** an administrator selects a card and slot position (1-4) in the binding dialog
**THEN** the system shall create the binding, update the bound card count, and refresh the card list
#### Scenario: Prevent duplicate slot binding
**WHEN** an administrator attempts to bind a card to an already occupied slot
**THEN** the system shall show an error message and prevent the binding
#### Scenario: Unbind a card from device
**WHEN** an administrator clicks unbind for a bound card and confirms
**THEN** the system shall remove the binding, decrement the bound card count, and refresh the card list
#### Scenario: Validate slot range
**WHEN** an administrator selects a slot position
**THEN** the system shall only allow values from 1 to the device's max_sim_slots value
### Requirement: Batch Device Allocation
The system SHALL support batch allocation of devices to shops with result tracking.
#### Scenario: Allocate multiple devices to a shop
**WHEN** an administrator selects multiple devices, chooses a target shop, adds optional remarks, and confirms allocation
**THEN** the system shall allocate all selected devices to the shop and display success/failure results for each device
#### Scenario: Show allocation results
**WHEN** the batch allocation completes
**THEN** the system shall display: total count, success count, failure count, and detailed failure reasons for each failed device
#### Scenario: Prevent allocation of already allocated devices
**WHEN** the batch allocation includes devices already allocated to a shop
**THEN** the system shall show warnings for those devices but proceed with allocating unallocated devices
### Requirement: Batch Device Recall
The system SHALL support batch recall of devices from shops with result tracking.
#### Scenario: Recall multiple devices
**WHEN** an administrator selects multiple devices, adds optional remarks, and confirms recall
**THEN** the system shall recall all selected devices from their shops and display success/failure results
#### Scenario: Show recall results
**WHEN** the batch recall completes
**THEN** the system shall display: total count, success count, failure count, and detailed failure reasons for each failed device
#### Scenario: Prevent recall of unallocated devices
**WHEN** the batch recall includes devices not allocated to any shop
**THEN** the system shall show warnings for those devices but proceed with recalling allocated devices
### Requirement: Device Import via Object Storage
The system SHALL support CSV-based device import using a three-step object storage upload process.
#### Scenario: Import devices with three-step process
**WHEN** an administrator uploads a CSV file
**THEN** the system shall:
1. Get upload URL from StorageService.getUploadUrl
2. Upload file to object storage using StorageService.uploadFile
3. Call DeviceService.importDevices with the file_key
**AND** display the task number for tracking
#### Scenario: Validate CSV format
**WHEN** the CSV file is uploaded
**THEN** the system shall validate the presence of required columns: device_no, device_name, device_model, device_type, max_sim_slots, manufacturer
#### Scenario: Import devices with card bindings
**WHEN** the CSV includes iccid_1, iccid_2, iccid_3, iccid_4 columns
**THEN** the system shall attempt to bind the specified cards to slots 1-4 respectively during import
#### Scenario: Handle import errors
**WHEN** the import process encounters errors (duplicate device_no, invalid ICCID, etc.)
**THEN** the system shall record failed rows in the import task with detailed error messages
### Requirement: Import Task Management
The system SHALL track device import tasks with detailed status and record information.
#### Scenario: List import tasks with type filter
**WHEN** an administrator views the task management page
**THEN** the system shall display both ICCID import tasks and Device import tasks with a type filter dropdown
#### Scenario: View device import task details
**WHEN** an administrator clicks on a device import task
**THEN** the system shall display: task ID, status, total count, success count, failed count, skipped count, created time, completed time
#### Scenario: View successful import records
**WHEN** viewing a device import task detail
**THEN** the system shall show a table of successfully imported devices with: device_no, device_name, bound ICCIDs
#### Scenario: View failed import records
**WHEN** viewing a device import task detail with failures
**THEN** the system shall show a table of failed records with: row number, device_no, failure reason
#### Scenario: Navigate from import page to task detail
**WHEN** a device import completes successfully
**THEN** the system shall display the task number with a link to view task details
## MODIFIED Requirements
### Requirement: Task Type Support
Task management SHALL support multiple task types including ICCID import and Device import with type-specific detail views.
**Previous behavior**: Task management only supported ICCID import tasks.
#### Scenario: Filter tasks by type
**WHEN** an administrator selects a task type filter (ICCID Import / Device Import)
**THEN** the system shall display only tasks of the selected type
#### Scenario: Display task type badges
**WHEN** viewing the task list
**THEN** each task shall display a type badge indicating whether it's an ICCID import or Device import task

View File

@@ -0,0 +1,126 @@
# Implementation Tasks
## 1. 类型定义和API服务 (Foundation)
- [ ] 1.1 创建 `src/types/api/device.ts` 定义所有设备相关类型
- DeviceItem, DeviceQueryParams, DevicePageResult
- DeviceCardBinding, DeviceCardBindingList
- AllocateDevicesRequest/Response, RecallDevicesRequest/Response
- BindCardRequest/Response, UnbindCardResponse
- ImportDeviceRequest/Response, DeviceImportTask相关类型
- [ ] 1.2 创建 `src/api/modules/device.ts` 实现 DeviceService
- getDevices (列表)
- getDeviceById (详情)
- deleteDevice (删除)
- getDeviceCards (绑定的卡列表)
- bindCard (绑定卡)
- unbindCard (解绑卡)
- allocateDevices (批量分配)
- recallDevices (批量回收)
- importDevices (批量导入)
- getImportTasks (导入任务列表)
- getImportTaskDetail (导入任务详情)
- [ ] 1.3 在 `src/api/modules/index.ts` 导出 DeviceService
- [ ] 1.4 在 `src/types/api/index.ts` 导出 Device 相关类型
## 2. 设备列表页面 (Core UI)
- [ ] 2.1 创建 `src/views/asset-management/device-list/index.vue`
- 搜索栏:设备号、设备名称、状态、店铺、批次号、设备类型、制造商、创建时间范围
- 表格:展示设备信息,支持勾选、列筛选
- 表格列ID、设备号、设备名称、设备型号、设备类型、制造商、最大插槽数、已绑定卡数、状态、店铺、批次号、激活时间、创建时间
- 状态使用 CommonStatus + ElSwitch 显示
- 操作列:查看详情、删除按钮(使用 ArtButtonTable
- [ ] 2.2 实现批量操作按钮
- 批量分配:弹出对话框选择目标店铺
- 批量回收:弹出对话框确认回收
- 导入设备:跳转到设备导入页面
- [ ] 2.3 实现批量分配对话框
- 选择目标店铺(下拉搜索)
- 显示已选设备数量
- 备注输入
- 展示分配结果(成功/失败)
- [ ] 2.4 实现批量回收对话框
- 确认回收设备列表
- 备注输入
- 展示回收结果(成功/失败)
## 3. 设备详情页面 (Detail View)
- [ ] 3.1 创建 `src/views/asset-management/device-detail/index.vue`
- 设备基本信息卡片ElDescriptions
- 绑定的卡列表表格展示4个插槽位置
- 返回按钮
- [ ] 3.2 实现卡绑定管理
- 绑定卡按钮:弹出对话框选择卡和插槽位置
- 解绑按钮:每个绑定记录旁边
- 显示插槽位置1-4
- 展示卡的基本信息ICCID、手机号、运营商、状态
## 4. 任务管理改进 (Task Management)
- [ ] 4.1 修改 `src/views/asset-management/task-management/index.vue`
- 添加任务类型筛选ICCID导入 / 设备导入
- 支持展示设备导入任务
- 任务列表显示任务类型标签
- [ ] 4.2 修改 `src/views/asset-management/task-detail/index.vue`
- 根据任务类型展示不同的详情内容
- 设备导入任务显示设备号、绑定的ICCID、失败原因
- 失败和跳过记录展示
## 5. 设备导入改进 (Import Enhancement)
- [ ] 5.1 修改 `src/views/batch/device-import/index.vue`
- 改用对象存储三步上传流程
1. 获取上传URL (StorageService.getUploadUrl)
2. 上传文件到对象存储 (StorageService.uploadFile)
3. 调用导入接口 (DeviceService.importDevices)
- CSV格式说明device_no, device_name, device_model, device_type, max_sim_slots, manufacturer, iccid_1~iccid_4, batch_no
- 导入成功后显示任务编号,引导去任务管理查看
- [ ] 5.2 优化导入记录展示
- 移除mock数据改为真实API调用
- 点击"查看详情"跳转到任务详情页
## 6. 路由和导航 (Routing)
- [ ] 6.1 在 `src/router/routes/asyncRoutes.ts` 添加路由
- /asset-management/device-list (设备列表)
- /asset-management/device-detail (设备详情带query参数id)
- [ ] 6.2 在 `src/router/routesAlias.ts` 添加路由别名
- DeviceList = '/asset-management/device-list'
- DeviceDetail = '/asset-management/device-detail'
- [ ] 6.3 在 `src/locales/langs/zh.json` 添加翻译
- assetManagement.deviceList: "设备列表"
- assetManagement.deviceDetail: "设备详情"
## 7. 测试和优化 (Testing & Polish)
- [ ] 7.1 功能测试
- 设备列表的搜索、分页、排序
- 批量分配和回收流程
- 设备与卡的绑定/解绑
- 设备导入完整流程
- 任务状态查看
- [ ] 7.2 边界情况处理
- 空列表状态
- 加载失败提示
- 删除确认提示
- 表单验证
- [ ] 7.3 性能优化
- 列表数据懒加载
- 防抖搜索
- 批量操作结果分页展示
- [ ] 7.4 代码审查
- TypeScript类型完整性
- 错误处理
- 代码复用性
- 注释完整性
## Dependencies
- 1.x 必须先完成才能开始 2.x-6.x
- 2.1-2.2 可以并行开发
- 3.x 依赖 1.x可与 2.x 并行
- 4.x 和 5.x 依赖 1.x可与其他任务并行
- 6.x 可在对应页面开发完成后立即进行
- 7.x 在所有功能开发完成后进行