From 0f98692b254d4af0433bea478cc33f587903037c Mon Sep 17 00:00:00 2001
From: Leo <98382335+gaoziman@users.noreply.github.com>
Date: Wed, 9 Jul 2025 18:32:38 +0800
Subject: [PATCH] =?UTF-8?q?docs(claude):=20=E6=B8=85=E7=90=86=E5=92=8C?=
=?UTF-8?q?=E4=BC=98=E5=8C=96CLAUDE.md=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?=
=?UTF-8?q?=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
优化CLAUDE.md文档结构，移除重复和过时的示例代码，提高文档的可读性和实用性。
主要变更：
- 删除重复的按钮示例代码片段
- 精简弹框组件使用示例
- 优化图标使用规范的代码示例
- 统一代码样式和格式
- 保持核心规范要求不变
文档优化后更加简洁明了，便于开发团队参考和遵循。
---
CLAUDE.md | 331 ++++++++++++++++++++++++------------------------------
1 file changed, 144 insertions(+), 187 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index 9d346d0..4b64201 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -368,54 +368,6 @@ coiMsgBox('确定要删除吗？', '删除确认').then(() => {
- ❌ 图标与功能语义不匹配
- ❌ 在表格列表页面使用圆角按钮（`round` 属性）
-### 示例：完整的页面按钮实现
-```vue
-
-
-
-
-
-
-
- 新增
-
-
-
-
-
-
-
- 删除
-
-
-
-
-
-
-
- 导出
-
-
-
-
-
-
-
- 搜索
-
-
-
-
-
-
- 重置
-
-
-
-```
-
-**遵循此规范可确保项目界面的一致性和专业性！**
-
### 🚀 render函数中图标渲染规范（强制要求）
**在DataTable等组件的render函数中使用图标时，必须遵循以下规范**
@@ -528,41 +480,6 @@ const columns: DataTableColumns = [
default: () => '编辑',
}))
}
-
- // 删除按钮（带确认）
- if (hasPermission('delete')) {
- buttons.push(h(NPopconfirm, {
- onPositiveClick: () => handleDelete(row.id),
- negativeText: '取消',
- positiveText: '确定',
- }, {
- default: () => '确定删除此项吗？',
- trigger: () => h(NButton, {
- type: 'error',
- size: 'small',
- }, {
- icon: () => h(NIcon, { size: 14, style: 'transform: translateY(-1px)' }, {
- default: () => h(IconParkOutlineDelete)
- }),
- default: () => '删除',
- }),
- }))
- }
-
- // 设置按钮
- if (hasPermission('setting')) {
- buttons.push(h(NButton, {
- type: 'warning',
- size: 'small',
- onClick: () => handleSetting(row),
- }, {
- icon: () => h(NIcon, { size: 14, style: 'transform: translateY(-1px)' }, {
- default: () => h(IconParkOutlineSetting)
- }),
- default: () => '设置',
- }))
- }
-
return h('div', { class: 'flex items-center justify-center gap-2' }, buttons)
},
},
@@ -780,40 +697,6 @@ const deleteDialogRef = ref()
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
```
@@ -1069,20 +952,6 @@ var(--info-color) /* 信息色 */
新增
-
-
-
-
-
- 删除
-
-
-
-
-
-
- 导出
-
@@ -1349,62 +1218,6 @@ import { coiMsgError, coiMsgSuccess, coiMsgWarning } from '@/utils/coi'
新增
-
-
-
-
-
- 删除
-
-
-
-
-
-
- 导出
-
-
-
-
-
-
- 搜索
-
-
-
-
-
-
- 重置
-
-
-
-```
-
-### 错误示例（严格禁止）
-
-```vue
-
-
-
-
-
-
-
- 新增
-
-
-
-
- 新增
-
-
-
-
-
-
-
-
```
@@ -1750,3 +1563,147 @@ import { coiMsgError, coiMsgSuccess, coiMsgWarning } from '@/utils/coi'
- Node.js 21.x
- pnpm 10.x
- 现代浏览器支持ES6+
+
+## 🔢 雪花ID和大数字处理规范（强制要求）
+
+**项目使用雪花ID算法生成唯一标识，必须严格按照以下规范处理大数字精度问题**
+
+### 问题背景
+
+**JavaScript数字精度限制**：
+- 雪花ID长度：19位数字（如：`194285920715864064`）
+- JavaScript安全整数范围：`Number.MAX_SAFE_INTEGER = 9007199254740991`（16位数字）
+- **超过安全整数范围的数字会发生精度丢失**
+
+**典型问题示例**：
+```text
+// 精度丢失示例
+194285920715864064 变成 194285920715864060 // 末尾数字被修改
+```
+
+### 核心原则
+
+1. **全链路字符串保持**：从数据库到前端，再到API调用，都保持字符串格式
+2. **后端安全转换**：只在后端业务逻辑中进行字符串到Long的转换
+3. **前端零转换**：前端严禁将大数字ID转换为Number类型
+4. **向后兼容**：同时支持短ID和长ID的处理
+
+### 强制实施规范
+
+#### 1. **前端API接口设计**
+
+**✅ 正确的API设计**：
+```typescript
+// 接收和发送都使用字符串格式
+export function saveRoleMenuPermission(roleId: string, menuIds: string[]) {
+ const menuIdsStr = menuIds.length > 0 ? menuIds : ['-1']
+ return request.Post>('/coder/sysMenu/saveRoleMenu', {
+ roleId, // 字符串格式
+ menuIds: menuIdsStr // 字符串数组格式
+ })
+}
+```
+
+**❌ 错误的API设计**：
+```typescript
+// 不要在前端进行数字转换
+export function saveRoleMenuPermission(roleId: string, menuIds: string[]) {
+ const menuIdsLong = menuIds.map(id => Number(id)) // ❌ 会造成精度丢失
+ return request.Post('/api/save', {
+ roleId: Number(roleId), // ❌ 会造成精度丢失
+ menuIds: menuIdsLong // ❌ 会造成精度丢失
+ })
+}
+```
+
+#### 2. **前端类型定义规范**
+
+**✅ 正确的类型定义**：
+```typescript
+// 所有ID相关字段使用字符串类型
+export interface RoleMenuPermissionBo {
+ roleId: string // 字符串格式避免精度丢失
+ menuIds: string[] // 字符串数组格式避免精度丢失
+}
+
+export interface UserVo {
+ userId: string // 字符串格式
+ roleId: string // 字符串格式
+ menuIds: string[] // 字符串数组格式
+}
+```
+
+**❌ 错误的类型定义**：
+```typescript
+// 不要使用number类型处理大数字ID
+export interface RoleMenuPermissionBo {
+ roleId: number // ❌ 会造成精度丢失
+ menuIds: number[] // ❌ 会造成精度丢失
+}
+```
+
+#### 3. **前端数据处理规范**
+
+**✅ 正确的数据处理**：
+```typescript
+// 保持字符串格式进行比较和处理
+function handleRowSelectionChange(rowKeys: (string | number)[]) {
+ const stringKeys = rowKeys.map(key => String(key))
+ selectedRows.value = tableData.value.filter(row =>
+ stringKeys.includes(String(row.roleId))
+ )
+}
+
+// 发送API请求时保持字符串格式
+const response = await saveRoleMenuPermission(
+ String(currentRole.roleId),
+ selectedMenuIds // 已经是字符串数组
+)
+```
+
+**❌ 错误的数据处理**：
+```typescript
+// 不要将字符串ID转换为数字
+function handleRowSelectionChange(rowKeys: (string | number)[]) {
+ const numericKeys = rowKeys.map(key => Number(key)) // ❌ 精度丢失
+ selectedRows.value = tableData.value.filter(row =>
+ numericKeys.includes(Number(row.roleId)) // ❌ 精度丢失
+ )
+}
+
+// 不要在发送前进行数字转换
+const menuIds = selectedMenuIds.map(id => Number(id)) // ❌ 精度丢失
+const response = await saveRoleMenuPermission(
+ Number(currentRole.roleId), // ❌ 精度丢失
+ menuIds
+)
+```
+
+### 检查清单
+
+**开发新功能时，必须确保**：
+- [ ] 前端类型定义中所有ID字段使用string类型
+- [ ] 前端API调用保持字符串格式，不进行Number转换
+- [ ] 前端数据处理中避免parseInt()、Number()等数字转换
+- [ ] 后端BO类提供字符串接收和Long转换的安全方法
+- [ ] 后端控制器使用安全转换方法
+- [ ] 后端服务层对无效ID进行过滤处理
+
+### 常见问题排查
+
+**当遇到大数字ID相关问题时，按以下步骤排查**：
+1. **检查前端是否进行了数字转换**：搜索`Number(`、`parseInt(`、`parseFloat(`
+2. **检查API调用参数格式**：确认发送的是字符串而非数字
+3. **检查后端BO类设计**：确认使用字符串接收和安全转换
+4. **检查数据库表字段类型**：确认使用`bigint`类型存储
+5. **检查序列化配置**：确认JSON序列化时大数字转为字符串
+
+### 历史修复案例
+
+**案例：菜单权限分配失败**
+- **问题**：雪花ID在前端Number转换时精度丢失
+- **症状**：部门管理等新菜单权限无法保存
+- **解决**：全链路改为字符串格式，后端安全转换
+- **文件**：`SysRoleMenuBo.java`、`saveRoleMenuPermission API`、角色管理页面
+
+**遵循此规范可彻底避免大数字精度丢失问题，确保系统稳定运行！**