first commit

2026-01-18 09:52:48 +08:00
commit 836bdc9409
584 changed files with 40891 additions and 0 deletions
@@ -0,0 +1,960 @@
+# 记账功能模块文档
+
+## 概述
+
+记账功能模块提供了完整的多用户多家庭记账功能，支持：
+- 多家庭管理（每个用户可以加入多个家庭）
+- 家庭成员管理（owner/admin/member角色）
+- 收支记录管理
+- 账户管理
+- 数据权限控制
+
+## 模块架构
+
+本模块采用Laravel模块化架构，所有代码位于 `modules/Account` 目录下：
+
+```
+modules/Account/
+├── app/
+│   ├── Controllers/
+│   │   ├── Api/           # 前端API控制器
+│   │   └── Admin/         # 后台管理控制器
+│   ├── Models/            # 数据模型
+│   ├── Providers/         # 服务提供者
+│   └── Services/          # 业务逻辑服务层
+├── database/
+│   └── migrations/        # 数据库迁移文件
+├── routes/
+│   ├── api.php           # 前端API路由
+│   └── admin.php         # 后台管理路由
+└── module.json           # 模块配置文件
+```
+
+### 命名空间
+
+- 模型：`Modules\Account\Models\`
+- 控制器：`Modules\Account\Controllers\Api\` 或 `Modules\Account\Controllers\Admin\`
+- 服务：`Modules\Account\Services\`
+- 路由：自动加载，无需手动配置
+
+### 路由说明
+
+模块路由已自动注册，无需在主路由文件中配置：
+
+- 前端API路由位于 `modules/Account/routes/api.php`
+- 后台管理路由位于 `modules/Account/routes/admin.php`
+
+所有路由由模块的 RouteServiceProvider 自动加载。
+
+## 数据库表结构
+
+### 1. account_families（家庭表）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键ID |
+| name | varchar(50) | 家庭名称 |
+| description | text | 家庭描述 |
+| avatar | varchar(255) | 家庭头像 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+| deleted_at | datetime | 删除时间（软删除） |
+
+### 2. account_family_members（家庭成员关系表）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键ID |
+| family_id | bigint | 家庭ID |
+| user_id | bigint | 用户ID |
+| role | varchar(20) | 角色：owner-拥有者，admin-管理员，member-成员 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+| deleted_at | datetime | 删除时间（软删除） |
+
+**唯一索引**: `family_id` + `user_id`（防止重复加入）
+
+### 3. account_records（记账记录表）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键ID |
+| user_id | bigint | 用户ID |
+| family_id | bigint | 家庭ID |
+| member_id | bigint | 成员ID |
+| account_id | bigint | 账户ID |
+| type | varchar(20) | 类型：income-收入，expense-支出 |
+| amount | decimal(10,2) | 金额 |
+| category | varchar(50) | 分类 |
+| date | date | 日期 |
+| time | varchar(10) | 时间 |
+| remark | text | 备注 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+| deleted_at | datetime | 删除时间（软删除） |
+
+### 2. account_members（家庭成员表）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键ID |
+| user_id | bigint | 用户ID |
+| family_id | bigint | 家庭ID |
+| name | varchar(50) | 成员名称 |
+| avatar | varchar(255) | 头像 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+| deleted_at | datetime | 删除时间（软删除） |
+
+### 3. accounts（账户表）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键ID |
+| user_id | bigint | 用户ID |
+| family_id | bigint | 家庭ID |
+| name | varchar(50) | 账户名称 |
+| type | varchar(20) | 账户类型：cash-现金，bank-银行卡，alipay-支付宝，wechat-微信 |
+| balance | decimal(10,2) | 余额 |
+| icon | varchar(255) | 图标 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+| deleted_at | datetime | 删除时间（软删除） |
+
+## 前端API接口
+
+### 基础URL
+`/api/account`
+
+### 记账记录接口
+
+#### 1. 获取记账记录列表
+- **路径**: `GET /api/account/records`
+- **认证**: 需要
+- **参数**:
+  - `family_id` (可选): 家庭ID，不传则返回当前用户所有家庭的记录
+  - `member_id` (可选): 成员ID
+  - `account_id` (可选): 账户ID
+  - `type` (可选): 类型（income/expense）
+  - `start_date` (可选): 开始日期
+  - `end_date` (可选): 结束日期
+  - `page` (可选): 页码
+  - `limit` (可选): 每页数量，默认30
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "list": [...],
+    "total": 100
+  }
+}
+```
+
+#### 2. 获取记账记录详情
+- **路径**: `GET /api/account/records/{id}`
+- **认证**: 需要
+- **响应**: 单条记录详情
+
+#### 3. 创建记账记录
+- **路径**: `POST /api/account/records`
+- **认证**: 需要
+- **参数**:
+  - `member_id` (必需): 成员ID
+  - `account_id` (必需): 账户ID
+  - `type` (必需): 类型（income/expense）
+  - `amount` (必需): 金额
+  - `category` (必需): 分类
+  - `date` (必需): 日期
+  - `time` (必需): 时间
+  - `remark` (可选): 备注
+- **响应**: 创建的记录
+
+#### 4. 更新记账记录
+- **路径**: `PUT /api/account/records/{id}`
+- **认证**: 需要
+- **参数**: 同创建接口（所有字段可选）
+- **响应**: 更新后的记录
+
+#### 5. 删除记账记录
+- **路径**: `DELETE /api/account/records/{id}`
+- **认证**: 需要
+- **响应**: 删除成功
+
+#### 6. 获取统计数据
+- **路径**: `GET /api/account/records/statistics`
+- **认证**: 需要
+- **参数**:
+  - `start_date` (可选): 开始日期
+  - `end_date` (可选): 结束日期
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "total_income": 10000.00,
+    "total_expense": 5000.00,
+    "balance": 5000.00,
+    "category_stats": [...],
+    "date_stats": [...]
+  }
+}
+```
+
+### 家庭管理接口
+
+#### 1. 获取用户的家庭列表
+- **路径**: `GET /api/account/families`
+- **认证**: 需要
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "name": "我的家",
+        "description": "温馨的家",
+        "avatar": "avatar.jpg",
+        "user_role": "owner",
+        "is_owner": true,
+        "can_manage": true,
+        "family_members": [...],
+        "created_at": "2025-01-01 00:00:00"
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+#### 2. 获取家庭详情
+- **路径**: `GET /api/account/families/{id}`
+- **认证**: 需要
+- **权限**: 用户必须属于该家庭
+- **响应**: 家庭详情（包含成员、账户、记录信息）
+
+#### 3. 创建家庭
+- **路径**: `POST /api/account/families`
+- **认证**: 需要
+- **参数**:
+  - `name` (必需): 家庭名称（最多50字符）
+  - `description` (可选): 家庭描述（最多255字符）
+  - `avatar` (可选): 家庭头像
+- **响应**: 创建的家庭（创建者自动成为owner）
+
+#### 4. 更新家庭
+- **路径**: `PUT /api/account/families/{id}`
+- **认证**: 需要
+- **权限**: owner或admin
+- **参数**: 同创建接口（所有字段可选）
+- **响应**: 更新后的家庭
+
+#### 5. 删除家庭
+- **路径**: `DELETE /api/account/families/{id}`
+- **认证**: 需要
+- **权限**: 仅owner
+- **限制**: 家庭下不能有关联账户
+- **响应**: 删除成功
+
+#### 6. 邀请成员加入家庭
+- **路径**: `POST /api/account/families/{familyId}/invite`
+- **认证**: 需要
+- **权限**: owner或admin
+- **参数**:
+  - `user_id` (必需): 被邀请用户ID
+- **限制**: 用户不能已经在家庭中
+- **响应**: 邀请成功
+
+#### 7. 移除家庭成员
+- **路径**: `DELETE /api/account/families/{familyId}/members/{memberId}`
+- **认证**: 需要
+- **权限**: owner或admin
+- **限制**: 不能移除owner
+- **响应**: 移除成功
+
+#### 8. 更新成员角色
+- **路径**: `PUT /api/account/families/{familyId}/members/{memberId}/role`
+- **认证**: 需要
+- **权限**: 仅owner
+- **参数**:
+  - `role` (必需): 新角色（owner/admin/member）
+- **限制**: 不能修改owner的角色
+- **响应**: 更新成功
+
+#### 9. 退出家庭
+- **路径**: `POST /api/account/families/{id}/leave`
+- **认证**: 需要
+- **限制**: owner不能退出，只能删除家庭
+- **响应**: 退出成功
+
+### 家庭成员接口
+
+#### 1. 获取成员列表
+- **路径**: `GET /api/account/members`
+- **认证**: 需要
+- **参数**:
+  - `family_id` (可选): 家庭ID，不传则返回当前用户所有家庭的成员
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "list": [...],
+    "total": 10
+  }
+}
+```
+
+#### 2. 获取成员详情
+- **路径**: `GET /api/account/members/{id}`
+- **认证**: 需要
+- **响应**: 成员详情
+
+#### 3. 创建成员
+- **路径**: `POST /api/account/members`
+- **认证**: 需要
+- **参数**:
+  - `name` (必需): 成员名称
+  - `avatar` (可选): 头像
+- **响应**: 创建的成员
+
+#### 4. 更新成员
+- **路径**: `PUT /api/account/members/{id}`
+- **认证**: 需要
+- **参数**: 同创建接口（所有字段可选）
+- **响应**: 更新后的成员
+
+#### 5. 删除成员
+- **路径**: `DELETE /api/account/members/{id}`
+- **认证**: 需要
+- **响应**: 删除成功
+
+### 账户管理接口
+
+#### 1. 获取账户列表
+- **路径**: `GET /api/account/accounts`
+- **认证**: 需要
+- **参数**:
+  - `family_id` (可选): 家庭ID，不传则返回当前用户所有家庭的账户
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "list": [...],
+    "total": 5,
+    "total_balance": 10000.00
+  }
+}
+```
+
+#### 2. 获取账户详情
+- **路径**: `GET /api/account/accounts/{id}`
+- **认证**: 需要
+- **响应**: 账户详情
+
+#### 3. 创建账户
+- **路径**: `POST /api/account/accounts`
+- **认证**: 需要
+- **参数**:
+  - `name` (必需): 账户名称
+  - `type` (必需): 账户类型（cash/bank/alipay/wechat）
+  - `balance` (可选): 初始余额
+  - `icon` (可选): 图标
+- **响应**: 创建的账户
+
+#### 4. 更新账户
+- **路径**: `PUT /api/account/accounts/{id}`
+- **认证**: 需要
+- **参数**: 同创建接口（所有字段可选）
+- **响应**: 更新后的账户
+
+#### 5. 删除账户
+- **路径**: `DELETE /api/account/accounts/{id}`
+- **认证**: 需要
+- **响应**: 删除成功
+
+#### 6. 重新计算账户余额
+- **路径**: `POST /api/account/accounts/{id}/recalculate`
+- **认证**: 需要
+- **响应**: 更新后的账户
+
+## 后台管理接口
+
+### 基础URL
+`/admin/account`
+
+### 记账记录管理
+
+#### 1. 获取记账记录列表
+- **路径**: `GET /admin/account/records/index`
+- **认证**: 需要
+- **参数**: 同前端API，额外支持
+  - `user_id` (可选): 用户ID
+- **响应**: 记录列表（包含用户、成员、账户信息）
+
+#### 2. 获取记账记录详情
+- **路径**: `GET /admin/account/records/show`
+- **认证**: 需要
+- **响应**: 记录详情
+
+#### 3. 删除记账记录
+- **路径**: `DELETE /admin/account/records/delete`
+- **认证**: 需要
+- **参数**: `id` (必需): 记录ID
+- **响应**: 删除成功（软删除）
+
+#### 4. 恢复记账记录
+- **路径**: `PUT /admin/account/records/restore`
+- **认证**: 需要
+- **参数**: `id` (必需): 记录ID
+- **响应**: 恢复成功
+
+#### 5. 获取统计数据
+- **路径**: `GET /admin/account/records/statistics`
+- **认证**: 需要
+- **参数**:
+  - `user_id` (可选): 用户ID
+  - `start_date` (可选): 开始日期
+  - `end_date` (可选): 结束日期
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "total_income": 10000.00,
+    "total_expense": 5000.00,
+    "balance": 5000.00,
+    "user_stats": [...],
+    "category_stats": [...],
+    "total_records": 100
+  }
+}
+```
+
+### 家庭成员管理
+
+#### 1. 获取成员列表
+- **路径**: `GET /admin/account/members/index`
+- **认证**: 需要
+- **参数**:
+  - `user_id` (可选): 用户ID
+- **响应**: 成员列表（包含统计信息）
+
+#### 2. 获取成员详情
+- **路径**: `GET /admin/account/members/show`
+- **认证**: 需要
+- **参数**: `id` (必需): 成员ID
+- **响应**: 成员详情（包含关联记录）
+
+#### 3. 创建成员
+- **路径**: `POST /admin/account/members/add`
+- **认证**: 需要
+- **参数**:
+  - `user_id` (必需): 用户ID
+  - `name` (必需): 成员名称
+  - `avatar` (可选): 头像
+- **响应**: 创建的成员
+
+#### 4. 更新成员
+- **路径**: `PUT /admin/account/members/edit`
+- **认证**: 需要
+- **参数**:
+  - `id` (必需): 成员ID
+  - 其他字段同创建接口
+- **响应**: 更新后的成员
+
+#### 5. 删除成员
+- **路径**: `DELETE /admin/account/members/delete`
+- **认证**: 需要
+- **参数**: `id` (必需): 成员ID
+- **响应**: 删除成功（软删除）
+
+#### 6. 恢复成员
+- **路径**: `PUT /admin/account/members/restore`
+- **认证**: 需要
+- **参数**: `id` (必需): 成员ID
+- **响应**: 恢复成功
+
+### 账户管理
+
+#### 1. 获取账户列表
+- **路径**: `GET /admin/account/accounts/index`
+- **认证**: 需要
+- **参数**:
+  - `user_id` (可选): 用户ID
+  - `type` (可选): 账户类型
+- **响应**: 账户列表（包含统计信息）
+
+#### 2. 获取账户详情
+- **路径**: `GET /admin/account/accounts/show`
+- **认证**: 需要
+- **参数**: `id` (必需): 账户ID
+- **响应**: 账户详情（包含关联记录）
+
+#### 3. 创建账户
+- **路径**: `POST /admin/account/accounts/add`
+- **认证**: 需要
+- **参数**:
+  - `user_id` (必需): 用户ID
+  - `name` (必需): 账户名称
+  - `type` (必需): 账户类型
+  - `balance` (可选): 初始余额
+  - `icon` (可选): 图标
+- **响应**: 创建的账户
+
+#### 4. 更新账户
+- **路径**: `PUT /admin/account/accounts/edit`
+- **认证**: 需要
+- **参数**:
+  - `id` (必需): 账户ID
+  - 其他字段同创建接口
+- **响应**: 更新后的账户
+
+#### 5. 删除账户
+- **路径**: `DELETE /admin/account/accounts/delete`
+- **认证**: 需要
+- **参数**: `id` (必需): 账户ID
+- **响应**: 删除成功（软删除）
+
+#### 6. 恢复账户
+- **路径**: `PUT /admin/account/accounts/restore`
+- **认证**: 需要
+- **参数**: `id` (必需): 账户ID
+- **响应**: 恢复成功
+
+#### 7. 重新计算账户余额
+- **路径**: `POST /admin/account/accounts/recalculate`
+- **认证**: 需要
+- **参数**: `id` (必需): 账户ID
+- **响应**: 更新后的账户
+
+#### 8. 获取账户类型列表
+- **路径**: `GET /admin/account/accounts/types`
+- **认证**: 需要
+- **响应**:
+```json
+{
+  "code": 1,
+  "message": "success",
+  "data": {
+    "cash": "现金",
+    "bank": "银行卡",
+    "alipay": "支付宝",
+    "wechat": "微信"
+  }
+}
+```
+
+## 后台管理系统
+
+### 概述
+
+后台管理系统提供了完整的管理功能，位于 `resources/admin` 目录下，使用 Vue 3 + Element Plus + Vite 技术栈。
+
+### 目录结构
+
+```
+resources/admin/src/
+├── api/
+│   ├── module/
+│   │   └── account.js      # 记账模块API接口
+│   └── index.js           # API自动导入
+├── pages/
+│   └── account/           # 记账模块页面
+│       ├── families/       # 家庭管理
+│       ├── accounts/       # 账户管理
+│       ├── members/        # 成员管理
+│       └── records/        # 记录管理
+└── router/
+    ├── accountRouter.js    # 记账模块路由
+    └── index.js            # 路由主文件
+```
+
+### 功能模块
+
+#### 1. 家庭管理 (`/account/families`)
+
+**功能特性**：
+- 家庭列表展示（支持搜索）
+- 查看家庭详情
+- 创建/编辑家庭
+- 删除家庭（含确认提示）
+- 显示成员数量和账户数量统计
+
+**页面组件**：
+- `index.vue`: 家庭列表页
+- `save.vue`: 家庭添加/编辑/查看页
+
+**搜索条件**：
+- 家庭名称
+
+**操作权限**：
+- 添加家庭
+- 编辑家庭信息
+- 查看家庭详情
+- 删除家庭
+
+#### 2. 账户管理 (`/account/accounts`)
+
+**功能特性**：
+- 账户列表展示（支持搜索和筛选）
+- 查看账户详情
+- 创建/编辑账户
+- 删除账户（含确认提示）
+- 显示账户余额（正数绿色，负数红色）
+- 支持多种账户类型（现金、银行卡、信用卡、支付宝、微信等）
+
+**页面组件**：
+- `index.vue`: 账户列表页
+- `save.vue`: 账户添加/编辑/查看页
+
+**搜索条件**：
+- 账户名称
+- 账户类型
+
+**表单字段**：
+- 账户名称（必填，2-50字符）
+- 账户类型（必填）
+- 所属家庭（必填，下拉选择）
+- 初始余额（可选，数字）
+- 备注（可选，最多200字符）
+
+#### 3. 成员管理 (`/account/members`)
+
+**功能特性**：
+- 成员列表展示（支持搜索和筛选）
+- 查看成员详情
+- 添加/编辑成员
+- 移除成员（含确认提示）
+- 显示成员角色（owner/admin/member）
+- 显示成员所属家庭
+
+**页面组件**：
+- `index.vue`: 成员列表页
+- `save.vue`: 成员添加/编辑/查看页
+
+**搜索条件**：
+- 成员昵称
+- 成员角色
+
+**表单字段**：
+- 所属家庭（必填，下拉选择）
+- 用户手机号（必填，用于查找用户）
+- 角色（必填，下拉选择）
+- 自动显示用户详细信息
+
+**角色说明**：
+- owner（家庭主）：最高权限，红色标签
+- admin（管理员）：管理权限，橙色标签
+- member（成员）：普通权限，蓝色标签
+
+#### 4. 记录管理 (`/account/records`)
+
+**功能特性**：
+- 记录列表展示（支持搜索和筛选）
+- 查看记录详情
+- 创建/编辑记录
+- 删除记录（含确认提示）
+- 显示金额（收入绿色+号，支出红色-号）
+- 显示记录类型（收入/支出标签）
+- 支持日期范围筛选
+
+**页面组件**：
+- `index.vue`: 记录列表页
+- `save.vue`: 记录添加/编辑/查看页
+
+**搜索条件**：
+- 关键词
+- 记录类型（收入/支出）
+- 日期范围
+
+**表单字段**：
+- 记录类型（必填，单选：收入/支出）
+- 所属家庭（必填，下拉选择）
+- 账户（必填，下拉选择，根据家庭筛选）
+- 分类（必填，下拉选择，根据记录类型筛选）
+- 金额（必填，数字）
+- 日期（必填，日期选择器）
+- 备注（可选，最多200字符）
+
+**联动功能**：
+- 选择家庭后，自动加载该家庭的账户列表
+- 切换记录类型后，自动筛选对应的分类列表
+
+### API接口封装
+
+所有API接口统一封装在 `resources/admin/src/api/module/account.js` 中：
+
+```javascript
+// 家庭管理
+this.$API.account.family.list.get(params)
+this.$API.account.family.detail.get(params)
+this.$API.account.family.add.post(params)
+this.$API.account.family.edit.post(params)
+this.$API.account.family.delete.post(params)
+
+// 账户管理
+this.$API.account.accounts.list.get(params)
+this.$API.account.accounts.detail.get(params)
+this.$API.account.accounts.add.post(params)
+this.$API.account.accounts.edit.post(params)
+this.$API.account.accounts.delete.post(params)
+
+// 成员管理
+this.$API.account.members.list.get(params)
+this.$API.account.members.detail.get(params)
+this.$API.account.members.add.post(params)
+this.$API.account.members.edit.post(params)
+this.$API.account.members.delete.post(params)
+
+// 记录管理
+this.$API.account.records.list.get(params)
+this.$API.account.records.detail.get(params)
+this.$API.account.records.add.post(params)
+this.$API.account.records.edit.post(params)
+this.$API.account.records.delete.post(params)
+```
+
+### 路由配置
+
+记账模块路由已配置在 `resources/admin/src/router/accountRouter.js`：
+
+```javascript
+{
+  path: "/account",
+  meta: {
+    title: "记账管理",
+    icon: "el-icon-wallet"
+  },
+  children: [
+    {
+      path: "/account/families",
+      meta: { title: "家庭管理", icon: "el-icon-house" }
+    },
+    {
+      path: "/account/accounts",
+      meta: { title: "账户管理", icon: "el-icon-bank-card" }
+    },
+    {
+      path: "/account/members",
+      meta: { title: "成员管理", icon: "el-icon-user" }
+    },
+    {
+      path: "/account/records",
+      meta: { title: "记录管理", icon: "el-icon-notebook-2" }
+    }
+  ]
+}
+```
+
+路由已自动注册到主路由文件 `index.js`，无需额外配置。
+
+### 通用功能
+
+#### 表格组件
+
+使用 `scTable` 组件实现统一的表格功能：
+- 自动分页
+- 自动加载
+- 参数搜索
+- 行选择
+- 固定列
+
+#### 抽屉组件
+
+使用 `el-drawer` 组件实现表单弹窗：
+- 三种模式：add（添加）、edit（编辑）、show（查看）
+- 表单验证
+- 关闭时自动重置
+- 成功回调刷新列表
+
+#### 权限控制
+
+所有删除操作都使用 `el-popconfirm` 进行二次确认：
+- 防止误删除
+- 支持取消操作
+- 显示确认提示文字
+
+#### 数据展示
+
+- 金额显示：保留2位小数，根据正负值显示不同颜色
+- 日期显示：统一格式化
+- 角色标签：使用不同颜色区分
+- 头像显示：支持头像上传和展示
+
+### 使用说明
+
+#### 1. 启动开发服务器
+
+```bash
+cd resources/admin
+npm install
+npm run dev
+```
+
+#### 2. 访问后台
+
+启动后访问：`http://localhost:5173`
+
+#### 3. 登录系统
+
+使用管理员账号登录后台系统。
+
+#### 4. 使用记账功能
+
+1. 点击左侧菜单"记账管理"
+2. 选择子菜单进行操作：
+   - 家庭管理：管理所有家庭信息
+   - 账户管理：管理所有账户信息
+   - 成员管理：管理所有家庭成员
+   - 记录管理：管理所有收支记录
+
+#### 5. 数据流转
+
+```
+创建家庭 → 添加成员 → 创建账户 → 记录收支
+```
+
+**注意事项**：
+- 必须先创建家庭，才能添加成员和账户
+- 创建账户时必须选择所属家庭
+- 创建记录时必须选择家庭、账户和成员
+- 所有删除操作都有确认提示
+
+## 使用说明
+
+### 数据库迁移
+
+运行以下命令创建数据库表：
+
+```bash
+php artisan migrate
+```
+
+### 多家庭架构
+
+本模块支持多用户多家庭架构：
+
+#### 数据隔离
+- 每个用户可以加入多个家庭
+- 每个家庭有独立的成员、账户和记录
+- 所有数据通过`family_id`字段关联到具体家庭
+- 用户只能访问自己所属家庭的数据
+
+#### 家庭角色权限
+
+| 角色 | 创建/编辑家庭 | 邀请成员 | 移除成员 | 修改角色 | 删除家庭 | 退出家庭 |
+|------|--------------|---------|---------|---------|---------|---------|
+| owner | ✅ | ✅ | ✅（不能移除owner） | ✅（不能修改owner） | ✅ | ❌（只能删除） |
+| admin | ✅ | ✅ | ✅（不能移除owner） | ❌ | ❌ | ✅ |
+| member | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+
+#### 权限判断方法
+
+AccountFamilyMember模型提供以下权限判断方法：
+
+```php
+// 判断是否是拥有者
+$member->isOwner();
+
+// 判断是否是管理员
+$member->isAdmin();
+
+// 判断是否有管理权限（owner或admin）
+$member->hasManagePermission();
+```
+
+### 账户余额自动更新
+
+系统会自动维护账户余额：
+- 创建收入记录时，账户余额增加
+- 创建支出记录时，账户余额减少
+- 更新记录时，自动调整相关账户余额
+- 删除记录时，自动回滚账户余额
+
+### 软删除
+
+所有数据表都支持软删除：
+- 删除操作不会物理删除数据，只是标记为已删除
+- 后台管理可以查看和恢复已删除的数据
+- 永久删除需要额外操作
+
+### 数据验证
+
+所有接口都有严格的数据验证：
+- 必填字段检查
+- 数据类型验证
+- 业务逻辑验证（如删除成员前检查是否有关联记录）
+
+## 注意事项
+
+1. 所有接口都需要认证（除登录接口外）
+2. 前端API只能操作当前登录用户及其所属家庭的数据
+3. 后台API可以操作所有用户的数据
+4. 每个请求都应该指定`family_id`来操作特定家庭的数据
+5. 账户余额建议使用重新计算接口进行校准
+6. 删除成员或账户前，系统会检查是否有关联记录
+7. 家庭拥有者不能退出家庭，只能删除家庭
+8. 删除家庭前，必须先删除或转移该家庭下的所有账户
+9. 修改成员角色需要谨慎操作，可能影响其他成员的权限
+
+## 多家庭使用示例
+
+### 创建家庭并邀请成员
+
+```javascript
+// 1. 创建家庭
+const family = await familyApi.createFamily({
+  name: '温馨小家',
+  description: '我们的家庭记账',
+  avatar: 'avatar.jpg'
+})
+
+// 2. 邀请成员（需要知道对方的用户ID）
+await familyApi.inviteMember(family.id, 123) // 123是被邀请用户的ID
+```
+
+### 管理家庭成员
+
+```javascript
+// 1. 获取家庭详情
+const family = await familyApi.getFamilyDetail(familyId)
+
+// 2. 修改成员角色（仅owner可以）
+await familyApi.updateMemberRole(familyId, memberId, 'admin')
+
+// 3. 移除成员（需要管理权限）
+await familyApi.removeMember(familyId, memberId)
+```
+
+### 在记账时使用家庭
+
+```javascript
+// 创建记账记录时指定家庭ID
+await recordApi.createRecord({
+  family_id: 1, // 家庭ID
+  member_id: 2, // 家庭成员ID
+  account_id: 3, // 家庭账户ID
+  type: 'expense',
+  amount: 100,
+  category: '餐饮',
+  date: '2025-01-01',
+  time: '12:00'
+})
+```
+
+### 切换家庭
+
+```javascript
+// 获取用户的所有家庭
+const families = await familyApi.getFamilies()
+
+// 在应用中保存当前选择的家庭ID
+const currentFamilyId = families.list[0].id
+
+// 后续操作都使用这个family_id
+```