12451 b553c4e519 feat: API 统一 + 设备详情补全 + H5 导航优化

- API 路由统一: 移除 /api/h5/，统一 /api/pms/ 入口
- 二进制改名: api-server -> pms-api（与服务名一致）
- nginx: 合并 /api/ + /pms/api/ 为 /api/pms/
- 新增 docs/API.md 接口文档
- 后端: CabinetDetail 增加 rssi/pow_fail/address/soc 等字段
- Redis 管道批量读取仓体实时数据（SOC/电压/电流/功率）
- DB: 所有 TIMESTAMP 列改为 DATETIME（修复类型不匹配）
- 用户管理: 新增创建时间/修改时间列，状态改用 Switch
- 角色管理/用户管理: 操作按钮改为图标
- PC 设备详情: 基本信息补全 RSSI/ICCID/电源/地址
- PC 卡片: 通道统计改用 Lucide 图标，颜色统一
- PC 二维码: canvas 渲染，含编号文字，支持右键下载
- H5: 按 uni-app 规范修正导航（navigateTo 替代 reLaunch）
- H5: 详情页加返回导航条
- H5: 扫码支持摄像头（jsQR）+ ?id= 参数
- H5: 底部 tabBar 在所有页面常显
- H5: 首页统计改为 6 项（设备/通道/空闲/充电/充满/故障）
- H5: 下拉刷新 / 上拉加载
- 产品首页: 添加业务联系
- 文档: 清理过时文件，补充缺失规范章节

2026-07-04 04:03:02 +08:00

3.2 KiB

Raw Blame History

title, impact, impactDescription, type, tags

title

impact

impactDescription

type

Always Provide Unique Keys in v-for Loops

Impact: HIGH - Without proper keys, Vue cannot track element identity when lists change. This causes component state loss, incorrect animations, form input values jumping between items, and bugs that are extremely difficult to debug.

The key attribute tells Vue how your data relates to the DOM elements it renders. When data ordering changes (via sort, filter, add, or remove), Vue uses keys to determine what to update, remove, or create. Without unique keys, Vue reuses DOM elements in-place which can cause one item's state to incorrectly appear on another item.

Task Checklist

Always provide :key with unique, stable identifiers (database IDs, UUIDs)
Never use array index as key - indices shift when items are added/removed
Use primitive values only (strings or numbers) - never use objects as keys
On <template v-for>, place the key on the <template> tag itself (Vue 3 change)
When using components in v-for, keys are mandatory, not optional

Incorrect:

<!-- WRONG: No key provided -->
<li v-for="item in items">{{ item.name }}</li>

<!-- WRONG: Using array index as key - shifts when list changes -->
<li v-for="(item, index) in items" :key="index">
  <input v-model="item.value" />
</li>

<!-- WRONG: Object as key -->
<li v-for="item in items" :key="item">{{ item.name }}</li>

<!-- WRONG (Vue 3): Key on child instead of template -->
<template v-for="item in items">
  <li :key="item.id">{{ item.name }}</li>
</template>

// Bug demonstration: Using index as key
// Initial: ['Alice', 'Bob', 'Charlie'] at indices [0, 1, 2]
// After removing 'Bob': ['Alice', 'Charlie'] at indices [0, 1]
// Charlie now has index 1, so Vue reuses Bob's DOM/component state for Charlie!

Correct:

<!-- CORRECT: Unique identifier as key -->
<li v-for="item in items" :key="item.id">
  {{ item.name }}
</li>

<!-- CORRECT: With components -->
<MyComponent
  v-for="item in items"
  :key="item.id"
  :item="item"
/>

<!-- CORRECT (Vue 3): Key on template tag -->
<template v-for="item in items" :key="item.id">
  <li>{{ item.name }}</li>
  <span>{{ item.description }}</span>
</template>

<!-- CORRECT: With stateful elements -->
<div v-for="user in users" :key="user.id">
  <input v-model="user.email" />
  <select v-model="user.role">
    <option value="admin">Admin</option>
    <option value="user">User</option>
  </select>
</div>

When Keys Are Critical

Keys are absolutely required when v-for loops contain:

Components with local state
Form elements (<input>, <select>, <textarea>)
Elements with initialization logic (mounted/created hooks)
Animations or transitions
Direct DOM manipulation

3.2 KiB Raw Blame History

Always Provide Unique Keys in v-for Loops

Task Checklist

When Keys Are Critical

Reference

3.2 KiB

Raw Blame History