📝 docs(file): add file relation documentation

- create file relation documentation to record entity-file system association methods
- document UserEntity avatar file association details including fields, schema, and API examples
- define file association naming conventions and database field standards
- describe common usage patterns for file upload, update and deletion processes
- establish template format for future entity-file association documentation expansion

.roo/commands/file-relation.md

@@ -0,0 +1,84 @@
+---
+description: "文件关联关系文档，记录各实体与文件系统的关联方式"
+---
+
+# 文件关联关系文档
+
+## 概述
+本文档记录项目中各实体与文件管理系统的关联关系，包括实体字段、关联方式、使用场景等信息。
+
+## 用户实体 (UserEntity) 文件关联
+
+### 1. 头像文件关联
+- **实体文件**: [`src/server/modules/users/user.entity.ts`](src/server/modules/users/user.entity.ts:29-34)
+- **关联字段**: 
+  - `avatarFileId: number | null` - 头像文件ID
+  - `avatarFile: File | null` - 头像文件实体
+- **关联类型**: Many-to-One
+- **数据库字段**: `avatar_file_id` (INT, unsigned, nullable)
+- **关联实体**: [`File`](src/server/modules/files/file.entity.ts)
+- **使用场景**: 用户头像上传、显示用户头像
+
+### 2. 相关Schema定义
+- **Schema文件**: [`src/server/modules/users/user.schema.ts`](src/server/modules/users/user.schema.ts:33-45)
+- **字段定义**:
+  ```typescript
+  avatarFileId: z.number().int().positive().nullable()
+  avatarFile: z.object({
+    id: z.number(),
+    name: z.string(),
+    fullUrl: z.string(),
+    type: z.string().nullable(),
+    size: z.number().nullable()
+  }).nullable().optional()
+  ```
+
+### 3. API使用示例
+- **创建用户时**:
+  ```typescript
+  {
+    username: 'newuser',
+    password: 'password123',
+    avatarFileId: 123  // 关联已上传的文件ID
+  }
+  ```
+
+- **更新用户时**:
+  ```typescript
+  {
+    avatarFileId: 456  // 更新头像文件ID
+  }
+  ```
+
+## 文件关联规范
+
+### 关联字段命名规范
+- 文件ID字段: `{关联名称}FileId`
+- 文件实体字段: `{关联名称}File`
+
+### 数据库字段命名
+- 文件ID数据库字段: `{关联名称}_file_id` (snake_case)
+
+### 关联配置
+- **关联方式**: `@ManyToOne` 单向关联
+- **级联操作**: 默认不级联，删除文件不会影响关联实体
+- **空值处理**: 支持null，表示无关联文件
+
+## 常见使用模式
+
+### 1. 文件上传流程
+1. 先调用文件上传API获取文件ID
+2. 在创建/更新实体时使用文件ID进行关联
+
+### 2. 文件更新流程
+1. 上传新文件获取新文件ID
+2. 更新实体关联的文件ID
+3. 可选择删除旧文件（需手动处理）
+
+### 3. 文件删除处理
+- 删除文件不会自动清除关联
+- 需要手动更新关联字段为null
+- 建议先检查文件是否被其他实体引用
+
+## 扩展说明
+此文档将作为模板，后续其他实体与文件的关联关系将按此格式补充到本文档中。