一个基于 Flask + Vue 3 的全栈联系人管理系统,支持联系人的增删改查、分组管理、导入导出和统计分析等功能。
- Flask 3.0+
- MySQL 8.0+
- Flask-JWT-Extended (JWT 认证)
- Flask-CORS (跨域支持)
- Marshmallow (序列化)
- SQLAlchemy (ORM)
- Vue 3 (Composition API)
- Vite 5
- Vue Router 4
- Pinia (状态管理)
- Ant Design Vue 4
- Axios (HTTP 客户端)
- Day.js (日期处理)
- 用户注册
- 用户登录
- JWT Token 认证
- 自动登录状态保持
- 查看联系人列表(卡片视图)
- 添加新联系人
- 编辑联系人信息
- 删除联系人(带确认)
- 支持字段:姓名、电话、邮箱、地址、地区、生日、分组
- 实时搜索(姓名/电话/邮箱)
- 按分组筛选
- 搜索防抖优化
- 清除筛选条件
- 创建/编辑/删除分组
- 查看分组下的联系人数量
- 删除前依赖检查(有联系人的分组不可删除)
- 为联系人分配分组
- 导出联系人为 CSV 文件
- 从 CSV 文件批量导入联系人
- 导入结果反馈(成功/失败数量和错误详情)
- 联系人总数
- 分组数量
- 本周/本月新增统计
- 按分组分布展示
- 按地区分布展示
- 操作日志: 查看所有用户操作记录,支持按类型、用户名筛选
- 记录的操作类型: 用户注册、用户登录、联系人增删改、分组增删改、数据备份/恢复
- 数据备份: 导出整个数据库为 JSON 格式 (用户、联系人、分组、日志、系统设置)
- 数据恢复: 从备份文件恢复数据(支持合并/覆盖模式)
- 系统设置: 配置系统名称、分页大小、日志保留天数等参数
通讯管理系统/
├── backend/ # 后端 Flask 应用
│ ├── app/
│ │ ├── modules/ # 业务模块
│ │ │ ├── auth/ # 认证模块
│ │ │ ├── contacts/ # 联系人模块
│ │ │ ├── groups/ # 分组模块
│ │ │ ├── stats/ # 统计模块
│ │ │ ├── logs/ # 操作日志模块
│ │ │ └── system/ # 系统管理模块
│ │ ├── extensions.py # Flask 扩展配置
│ │ └── __init__.py # 应用工厂
│ ├── config.py # 配置文件
│ ├── requirements.txt # Python 依赖
│ └── run.py # 启动文件
│
├── frontend/ # 前端 Vue 应用
│ ├── public/
│ │ ├── logo.svg # 系统 Logo
│ │ └── favicon.svg # 浏览器图标
│ ├── src/
│ │ ├── components/ # 组件
│ │ ├── pages/ # 页面 (含 system/ 子目录)
│ │ ├── services/ # API 服务
│ │ ├── stores/ # Pinia 状态
│ │ ├── router/ # 路由配置
│ │ ├── utils/ # 工具函数
│ │ ├── App.vue # 根组件
│ │ └── main.js # 入口文件
│ ├── package.json # 依赖配置
│ └── vite.config.js # Vite 配置
│
├── docs/ # 文档目录
└── README.md # 项目说明
- Node.js >= 18.0
- Python >= 3.10
- MySQL >= 8.0
- 创建并激活虚拟环境:
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate- 安装依赖:
pip install -r requirements.txt-
配置数据库:
- 创建 MySQL 数据库:
CREATE DATABASE contact_management; - 修改
config.py中的数据库连接配置
- 创建 MySQL 数据库:
-
初始化数据库:
flask db init
flask db migrate -m "Initial migration"
flask db upgrade- 启动后端服务:
python run.py后端将运行在 http://localhost:5000
- 安装依赖:
cd frontend
npm install-
配置环境变量:
- 复制
.env.example为.env - 确认 API 地址配置:
VITE_API_BASE_URL=http://localhost:5000/api
- 复制
-
启动开发服务器:
npm run dev前端将运行在 http://localhost:3000
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/auth/register | 用户注册 |
| POST | /api/auth/login | 用户登录 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/contacts/ | 获取联系人列表 |
| POST | /api/contacts/ | 创建联系人 |
| GET | /api/contacts/:id | 获取单个联系人 |
| PUT | /api/contacts/:id | 更新联系人 |
| DELETE | /api/contacts/:id | 删除联系人 |
| GET | /api/contacts/export | 导出联系人为CSV |
| POST | /api/contacts/import | 从CSV导入联系人 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/groups/ | 获取分组列表 |
| POST | /api/groups/ | 创建分组 |
| PUT | /api/groups/:id | 更新分组 |
| DELETE | /api/groups/:id | 删除分组 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/stats/ | 获取统计数据 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/logs/ | 获取操作日志列表 |
| GET | /api/system/settings | 获取系统设置 |
| PUT | /api/system/settings | 更新系统设置 |
| POST | /api/system/backup | 执行数据备份 |
| POST | /api/system/restore | 执行数据恢复 |
- 访问 http://localhost:3000
- 点击"注册账号"
- 填写用户名和密码完成注册
- 使用注册的账号登录系统
- 登录后进入"联系人列表"页面
- 点击"添加联系人"按钮创建新联系人
- 填写联系人信息(姓名为必填项)
- 在联系人卡片上可以进行编辑或删除操作
- 点击侧边栏"分组管理"
- 点击"添加分组"创建新分组
- 在添加/编辑联系人时,可以选择分组
- 在联系人列表页可以按分组筛选
- 在联系人列表页点击"导出联系人"下载 CSV 文件
- 点击"导入联系人"选择 CSV 文件批量导入
- 导入时会显示成功和失败的数量
- 点击侧边栏"统计"
- 查看联系人总数、分组分布、地区分布等信息
- 使用管理员账号登录
- 点击侧边栏"操作日志"
- 查看所有用户的操作记录
- 可按操作类型、用户名筛选
- 点击侧边栏"数据备份"
- 选择备份格式(目前支持 JSON)
- 点击"立即备份"下载备份文件
- 恢复时选择备份文件和恢复模式:
- 合并模式: 仅添加新数据,保留现有数据
- 覆盖模式: 清空数据库后完全恢复备份
- 点击侧边栏"系统设置"
- 修改系统名称、分页大小、日志保留天数
- 点击"保存设置"应用更改
- 前端使用 ESLint + Prettier 进行代码格式化
- 后端遵循 PEP 8 Python 代码规范
- 组件命名使用 PascalCase
- 变量命名使用 camelCase
前端测试:
cd frontend
npm run test后端测试:
cd backend
pytest前端构建:
cd frontend
npm run build构建产物将生成在 frontend/dist 目录。
A: 确认后端服务已启动,检查 frontend/.env 中的 API 地址配置是否正确。
A: 确保 CSV 文件格式正确,必须包含"姓名"列,编码为 UTF-8。
A: 检查浏览器是否禁用了 LocalStorage,或清除浏览器缓存后重试。
如有问题,请提交 Issue 或联系开发团队。
MIT License