51｜需求分析与项目结构

前面 50 篇把前端基础、后端基础、后端进阶的知识点逐个拆开讲。从这篇开始，把这些能力合到一个真实项目里——一个运维管理平台（ops-console），管理服务器资产、执行任务、记录事件、做权限控制。不追求功能多，核心是把全栈链路串起来：前端页面 → HTTP 请求 → 后端接口 → 数据库 → 返回数据 → 前端渲染。

一、功能范围

模块	功能	涉及知识点
用户认证	登录、Token、权限控制	JWT、依赖注入、密码哈希
资产管理	服务器增删改查	CRUD、分页、搜索
任务管理	对资产执行操作	后台任务、状态追踪
事件记录	谁在什么时间做了什么	审计日志、关联查询
前端界面	登录页、列表页、表单页、详情页	Vue 组件、路由、状态管理

不做复杂功能：没有实时通知、没有图表可视化、没有多租户。每个模块用到的知识都在前面 50 篇覆盖过，这里是把它们组装起来。

二、技术选型

层	技术	选型理由
后端框架	FastAPI	前面基础篇一直在用，类型提示 + 自动文档
数据库	SQLite（开发）/ PostgreSQL（生产）	开发用 SQLite 省事，生产换 PostgreSQL
ORM	SQLAlchemy	Python 最主流的 ORM
前端框架	Vue 3	前端基础篇学的，组件化 + 数据驱动
前端构建	Vite	开发服务器 + 打包
HTTP 请求	fetch	前端 18 篇封装的 request 函数
认证	JWT	后端 38 篇的方案
部署	Docker + Nginx	58 篇详细讲

三、项目目录结构

前后端在同一个代码仓库，各自独立目录：

ops-console/
├── backend/                 # 后端
│   ├── app/
│   │   ├── main.py          # FastAPI 应用入口
│   │   ├── config.py        # 配置（pydantic-settings）
│   │   ├── database.py      # 数据库引擎和会话
│   │   ├── models.py        # SQLAlchemy 模型
│   │   ├── schemas.py       # Pydantic 请求/响应模型
│   │   ├── auth.py          # 认证（JWT、密码哈希）
│   │   └── routers/         # 路由分模块
│   │       ├── __init__.py
│   │       ├── assets.py    # 资产接口
│   │       ├── tasks.py     # 任务接口
│   │       ├── events.py    # 事件接口
│   │       └── users.py     # 用户接口（登录）
│   ├── alembic/             # 数据库迁移
│   ├── tests/               # 测试
│   ├── pyproject.toml
│   └── .env                 # 配置（不进 Git）
│
├── frontend/                # 前端
│   ├── src/
│   │   ├── main.js          # Vue 入口
│   │   ├── App.vue          # 根组件
│   │   ├── api/             # API 封装
│   │   │   ├── request.js   # 基础请求函数
│   │   │   ├── assets.js    # 资产相关接口
│   │   │   └── tasks.js     # 任务相关接口
│   │   ├── components/      # 通用组件
│   │   │   ├── DataTable.vue
│   │   │   ├── SearchForm.vue
│   │   │   └── Pagination.vue
│   │   ├── views/           # 页面组件
│   │   │   ├── LoginView.vue
│   │   │   ├── AssetList.vue
│   │   │   ├── AssetForm.vue
│   │   │   ├── TaskList.vue
│   │   │   └── EventLog.vue
│   │   ├── router/          # Vue Router 配置
│   │   ├── stores/          # Pinia 状态管理
│   │   └── assets/          # 静态资源
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
│
├── docker-compose.yml       # 编排配置
├── nginx.conf               # Nginx 配置
└── README.md

四、API 设计概览

方法	路径	功能	认证
POST	/api/login	登录	否
GET	/api/me	当前用户信息	是
GET	/api/assets	资产列表	是
POST	/api/assets	创建资产	是
GET	/api/assets/{id}	资产详情	是
PUT	/api/assets/{id}	更新资产	是
DELETE	/api/assets/{id}	删除资产	是（管理员）
GET	/api/tasks	任务列表	是
POST	/api/tasks	创建任务	是
GET	/api/tasks/{id}	任务详情	是
GET	/api/events	事件日志	是（管理员）

五、开发启动方式

后端：

cd backend
uv run uvicorn app.main:app --reload --port 8000

前端：

cd frontend
npm run dev   # 端口 5173

浏览器打开 http://localhost:5173，前端通过 fetch 调用 http://localhost:8000/api/*。