961 lines
25 KiB
Markdown
961 lines
25 KiB
Markdown
# 记账功能模块文档
|
||
|
||
## 概述
|
||
|
||
记账功能模块提供了完整的多用户多家庭记账功能，支持：
|
||
- 多家庭管理（每个用户可以加入多个家庭）
|
||
- 家庭成员管理（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
|
||
```
|