molong/account

Fork 0

Files

molong 836bdc9409 first commit

2026-01-18 09:52:48 +08:00

25 KiB

Raw Permalink Blame History

记账功能模块文档

概述

记账功能模块提供了完整的多用户多家庭记账功能，支持：

多家庭管理（每个用户可以加入多个家庭）
家庭成员管理（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
响应:

{
  "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 (可选): 结束日期
响应:

{
  "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
认证: 需要
响应:

{
  "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，不传则返回当前用户所有家庭的成员
响应:

{
  "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，不传则返回当前用户所有家庭的账户
响应:

{
  "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 (可选): 结束日期
响应:

{
  "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
认证: 需要
响应:

{
  "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 中：

// 家庭管理
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：

{
  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. 启动开发服务器

cd resources/admin
npm install
npm run dev

2. 访问后台

启动后访问：http://localhost:5173

3. 登录系统

使用管理员账号登录后台系统。

4. 使用记账功能

点击左侧菜单"记账管理"
选择子菜单进行操作：
- 家庭管理：管理所有家庭信息
- 账户管理：管理所有账户信息
- 成员管理：管理所有家庭成员
- 记录管理：管理所有收支记录

5. 数据流转

创建家庭 → 添加成员 → 创建账户 → 记录收支

注意事项：

必须先创建家庭，才能添加成员和账户
创建账户时必须选择所属家庭
创建记录时必须选择家庭、账户和成员
所有删除操作都有确认提示

使用说明

数据库迁移

运行以下命令创建数据库表：

php artisan migrate

多家庭架构

本模块支持多用户多家庭架构：

数据隔离

每个用户可以加入多个家庭
每个家庭有独立的成员、账户和记录
所有数据通过family_id字段关联到具体家庭
用户只能访问自己所属家庭的数据

家庭角色权限

角色	创建/编辑家庭	邀请成员	移除成员	修改角色	删除家庭	退出家庭
owner	✅	✅	✅（不能移除owner）	✅（不能修改owner）	✅	❌（只能删除）
admin	✅	✅	✅（不能移除owner）	❌	❌	✅
member	❌	❌	❌	❌	❌	✅

权限判断方法

AccountFamilyMember模型提供以下权限判断方法：

// 判断是否是拥有者
$member->isOwner();

// 判断是否是管理员
$member->isAdmin();

// 判断是否有管理权限（owner或admin）
$member->hasManagePermission();

账户余额自动更新

系统会自动维护账户余额：

创建收入记录时，账户余额增加
创建支出记录时，账户余额减少
更新记录时，自动调整相关账户余额
删除记录时，自动回滚账户余额

软删除

所有数据表都支持软删除：

删除操作不会物理删除数据，只是标记为已删除
后台管理可以查看和恢复已删除的数据
永久删除需要额外操作

数据验证

所有接口都有严格的数据验证：

必填字段检查
数据类型验证
业务逻辑验证（如删除成员前检查是否有关联记录）

注意事项

所有接口都需要认证（除登录接口外）
前端API只能操作当前登录用户及其所属家庭的数据
后台API可以操作所有用户的数据
每个请求都应该指定family_id来操作特定家庭的数据
账户余额建议使用重新计算接口进行校准
删除成员或账户前，系统会检查是否有关联记录
家庭拥有者不能退出家庭，只能删除家庭
删除家庭前，必须先删除或转移该家庭下的所有账户
修改成员角色需要谨慎操作，可能影响其他成员的权限

多家庭使用示例

创建家庭并邀请成员

// 1. 创建家庭
const family = await familyApi.createFamily({
  name: '温馨小家',
  description: '我们的家庭记账',
  avatar: 'avatar.jpg'
})

// 2. 邀请成员（需要知道对方的用户ID）
await familyApi.inviteMember(family.id, 123) // 123是被邀请用户的ID

管理家庭成员

// 1. 获取家庭详情
const family = await familyApi.getFamilyDetail(familyId)

// 2. 修改成员角色（仅owner可以）
await familyApi.updateMemberRole(familyId, memberId, 'admin')

// 3. 移除成员（需要管理权限）
await familyApi.removeMember(familyId, memberId)

在记账时使用家庭

// 创建记账记录时指定家庭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'
})

切换家庭

// 获取用户的所有家庭
const families = await familyApi.getFamilies()

// 在应用中保存当前选择的家庭ID
const currentFamilyId = families.list[0].id

// 后续操作都使用这个family_id

25 KiB Raw Permalink Blame History Unescape Escape

记账功能模块文档

概述

模块架构

命名空间

路由说明

数据库表结构

1. account_families（家庭表）

2. account_family_members（家庭成员关系表）

3. account_records（记账记录表）

2. account_members（家庭成员表）

3. accounts（账户表）

前端API接口

基础URL

记账记录接口

1. 获取记账记录列表

2. 获取记账记录详情

3. 创建记账记录

4. 更新记账记录

5. 删除记账记录

6. 获取统计数据

家庭管理接口

1. 获取用户的家庭列表

2. 获取家庭详情

3. 创建家庭

4. 更新家庭

5. 删除家庭

6. 邀请成员加入家庭

7. 移除家庭成员

8. 更新成员角色

9. 退出家庭

家庭成员接口

1. 获取成员列表

2. 获取成员详情

3. 创建成员

4. 更新成员

5. 删除成员

账户管理接口

1. 获取账户列表

2. 获取账户详情

3. 创建账户

4. 更新账户

5. 删除账户

6. 重新计算账户余额

后台管理接口

基础URL

记账记录管理

1. 获取记账记录列表

2. 获取记账记录详情

3. 删除记账记录

4. 恢复记账记录

5. 获取统计数据

家庭成员管理

1. 获取成员列表

2. 获取成员详情

3. 创建成员

4. 更新成员

5. 删除成员

6. 恢复成员

账户管理

1. 获取账户列表

2. 获取账户详情

3. 创建账户

4. 更新账户

5. 删除账户

6. 恢复账户

7. 重新计算账户余额

8. 获取账户类型列表

后台管理系统

概述

目录结构

功能模块

1. 家庭管理 (/account/families)

2. 账户管理 (/account/accounts)

3. 成员管理 (/account/members)

4. 记录管理 (/account/records)

API接口封装

路由配置

通用功能

表格组件

25 KiB

Raw Permalink Blame History

1. 家庭管理 (`/account/families`)

2. 账户管理 (`/account/accounts`)

3. 成员管理 (`/account/members`)

4. 记录管理 (`/account/records`)