# 基础FAST-CMS **Repository Path**: zwjmaxstudio/FAST-CMS ## Basic Information - **Project Name**: 基础FAST-CMS - **Description**: FAST-API 的基础文档 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-24 - **Last Updated**: 2026-02-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FastAPI 基础 CMS 系统接口文档 --- ## 🏗️ 整体结构 ```plaintext app/ ├── api/ # API 路由和业务逻辑核心 ├── assets/ # 静态资源（如图片、样式等） ├── core/ # 核心配置、工具函数、全局依赖 ├── models/ # 数据库模型定义（ORM 映射） ├── schemas/ # Pydantic 数据验证模型（请求/响应格式） ├── services/ # 业务逻辑层（如用户服务、权限服务等） ├── main.py # 应用入口，启动 FastAPI 实例 └── __init__.py # 包初始化文件 db/ # 数据库相关（迁移脚本、种子数据等） doc/ # 文档（接口文档、设计文档等） resource/ # 项目资源（配置文件、模板等） uploads/ # 用户/管理员上传的文件存储目录 ``` --- ## 核心模块详解 ### api/ 目录 - **v1/**：API 版本控制，所有接口都在 `/api/v1/` 下，方便后续迭代升级。 - **endpoints/**：按功能拆分路由文件（如 `auth.py`、`users.py`、`admin.py`），对应接口文档中的各模块。 - **api.py**：将各个 endpoint 路由注册到主应用，统一前缀。 ### core/ 目录 存放全局配置（如数据库连接、JWT 密钥、日志设置）、依赖注入（如登录验证、权限检查）和工具函数。 ### models/ 与 schemas/ - **models**：定义数据库表结构（如 User、Admin、Content 等），与数据库交互。 - **schemas**：定义请求和响应的数据格式，做参数校验和类型提示，保证接口数据安全。 ### services/ 目录 把复杂的业务逻辑从路由中抽离出来，比如「用户注册流程」「内容发布校验」等，让代码更清晰、易于测试。 ### main.py 应用的入口文件，创建 FastAPI 实例，挂载所有路由，配置 CORS、异常处理等中间件。 --- ## 🚀 工程化配套 - **db/**：数据库迁移和初始化脚本，方便团队协作和环境部署。 - **doc/**：存放接口文档和设计文档，与 Swagger UI 对应。 - **uploads/**：统一管理用户和管理员上传的文件，避免文件散落各处。 - **Docker 相关**：`Dockerfile` 和 `docker-compose.yml` 让项目可以容器化部署，保证开发、测试、生产环境一致。 - **supervisord.conf**：进程管理配置，确保服务在生产环境稳定运行，自动重启。 --- ## 这个框架的优点 - **结构清晰**：按功能模块拆分，代码易维护、易扩展。 - **类型安全**：借助 Pydantic 和 Python 类型提示，减少运行时错误。 - **自动文档**：FastAPI 自动生成 Swagger UI，接口调试和文档维护更轻松。 - **可部署性强**：Docker + Supervisor 让上线和运维更简单。 - **易于协作**：明确的目录和职责划分，适合多人团队开发。 --- ## 一、系统概览 这是一个基于 FastAPI 开发的基础 CMS（内容管理系统），主要分为三大模块： 基础服务：健康检查、验证码等 用户服务：注册、登录、个人信息管理等 管理员服务：用户管理、栏目管理、内容管理等 ## 二、基础服务接口（default & auth） 1. 健康检查 接口地址：GET /api/health 作用：检查系统是否正常运行，相当于 “系统心跳” 使用场景：运维监控、服务启动自检 返回示例：{"status": "ok"} 2. 短信验证码相关 发送短信验证码 接口地址：POST /api/v1/auth/sms/send 作用：给指定手机号发送短信验证码 需要传的内容：手机号 使用场景：注册、登录、找回密码前的验证步骤 验证短信验证码 接口地址：POST /api/v1/auth/sms/verify 作用：校验用户输入的短信验证码是否正确 需要传的内容：手机号、验证码 使用场景：注册、登录、找回密码时的验证环节 3. 图片验证码 接口地址：GET /api/v1/auth/captcha/image 作用：返回一张图片验证码，防止机器恶意请求 使用场景：登录、注册前的人机验证 ## 三、用户服务接口（users） 1. 用户注册 接口地址：POST /api/v1/users/register 作用：新用户创建账号 需要传的内容：手机号、密码、短信验证码等 结果：注册成功后，用户可以登录系统 2. 用户登录 接口地址：POST /api/v1/users/login 作用：验证用户身份，返回登录凭证（Token） 需要传的内容：手机号 / 用户名、密码 结果：登录成功后，后续操作都需要携带这个凭证 3. 个人信息管理 获取当前登录用户信息 接口地址：GET /api/v1/users/me 作用：查看自己的账号信息，比如昵称、头像、手机号等 注意：必须先登录，携带 Token 才能访问 更新当前登录用户信息 接口地址：PUT /api/v1/users/me 作用：修改自己的个人信息，比如昵称、头像、简介等 注意：必须先登录，携带 Token 才能操作 4. 站内信 接口地址：GET /api/v1/users/me/notifications 作用：查看系统发给你的消息，比如系统通知、互动提醒等 注意：必须先登录，携带 Token 才能访问 5. 获取用户列表与详情 获取用户列表：GET /api/v1/users/ 作用：查看所有用户（一般管理员用） 获取用户详情：GET /api/v1/users/{user_id} 作用：查看某个用户的详细信息 6. 重置密码 接口地址：POST /api/v1/users/password/reset-by-sms 作用：忘记密码时，通过短信验证码重置密码 需要传的内容：手机号、新密码、短信验证码 7. 上传文件 接口地址：POST /api/v1/users/upload 作用：用户上传头像、附件等文件 结果：返回文件的访问地址，可用于更新个人信息 ## 四、管理员服务接口（admin） 1. 管理员登录 接口地址：POST /api/v1/admin/login 作用：管理员登录后台管理系统 需要传的内容：管理员账号、密码 结果：返回管理员专属的登录凭证（Token） 2. 管理员信息管理 获取当前管理员信息 接口地址：GET /api/v1/admin/me 作用：查看当前登录管理员的信息 获取管理员列表 接口地址：GET /api/v1/admin/ 作用：查看所有管理员账号 创建管理员用户 接口地址：POST /api/v1/admin/ 作用：新增一个管理员账号（需要超级管理员权限） 更新管理员信息 接口地址：PUT /api/v1/admin/{admin_id} 作用：修改某个管理员的信息（需要权限） 3. 用户管理（管理员视角） 接口地址：GET /api/v1/admin/users 作用：分页查看所有注册用户，方便管理 注意：只有管理员能访问 4. 网站栏目管理 获取网站栏目列表 接口地址：GET /api/v1/admin/website_channels 作用：查看网站的所有栏目，比如 “新闻”“教程”“公告” 等 新增网站栏目 接口地址：POST /api/v1/admin/website_channels 作用：创建新的栏目，比如新增一个 “技术分享” 栏目 修改网站栏目 接口地址：PUT /api/v1/admin/website_channels/{channel_id} 作用：修改已有栏目的名称、描述等 5. 网站内容管理 获取网站内容列表（分页） 接口地址：GET /api/v1/admin/website_contents 作用：分页查看所有发布的文章、资讯等内容 新增网站内容 接口地址：POST /api/v1/admin/website_contents 作用：发布新的文章、资讯到指定栏目 获取网站内容详情 接口地址：GET /api/v1/admin/website_contents/{content_id} 作用：查看某篇文章的详细内容 修改网站内容 接口地址：PUT /api/v1/admin/website_contents/{content_id} 作用：编辑已发布的文章内容 6. 管理员上传文件 接口地址：POST /api/v1/admin/upload 作用：管理员上传封面图、附件等文件，用于文章或栏目配图 ## 五、权限说明 大部分接口旁边有个🔒图标，意思是：必须登录，携带 Token 才能访问 管理员接口（admin 开头的）：只有管理员账号登录后才能操作，普通用户用不了 公开接口（比如注册、登录、获取验证码）：不需要登录就能用 ## 六、使用流程示例（用户端） 打开 APP / 网站 → 点击 “注册” 输入手机号 → 调用 “发送短信验证码” 接口 收到验证码 → 输入验证码、设置密码 → 调用 “用户注册” 接口 注册成功 → 输入手机号和密码 → 调用 “用户登录” 接口，拿到 Token 之后查看个人信息、修改资料、查看站内信，都要带着这个 Token ## 七、使用流程示例（管理员端） 打开后台管理页面 → 输入管理员账号密码 → 调用 “管理员登录” 接口，拿到 Token 查看所有用户 → 调用 “获取用户列表（分页）” 接口 新增一篇文章 → 先上传封面图（调用 “管理员上传文件” 接口），再调用 “新增网站内容” 接口 修改文章 → 调用 “修改网站内容” 接口 # 接口返回编码字典表 - 字段说明： - `code`: 整型编码，`0` 表示成功，非零表示错误 - `message`: 人类可读的结果信息 - `data`: 可选，成功时的业务数据 示例： ```json { "code": 0, "message": "OK", "data": { /* 任意业务数据 */ } } { "code": 40002, "message": "图片验证码错误或已过期" } ``` ## 编码规范 - 成功：`0` - 客户端错误（参数/校验）：`400xx` - 认证授权错误：`401xx` - 资源不存在：`404xx` - 资源冲突：`409xx` - 频率限制：`429xx` - 服务器错误：`500xx` ## 编码字典 - `0` 成功 - `40001` 参数校验失败（通用） - `40002` 图片验证码错误或已过期 - `40003` 短信验证码错误或已过期 - `40004` 两次输入的密码不一致 - `40005` 用户未设置密码 - `40101` 未认证或令牌无效 - `40102` 密码错误 - `40401` 用户不存在 - `40901` 该手机号已注册（资源冲突） - `42901` 请求过于频繁（如短信发送频率限制） - `50001` 服务器内部错误 ## 与 HTTP 状态关系（建议） - `200` 成功（`code=0`） - `400` 客户端错误（如 `40001`、`40002`、`40003`、`40004`、`40005`） - `401` 未认证/鉴权失败（如 `40101`、`40102`） - `404` 资源不存在（如 `40401`） - `409` 资源冲突（如 `40901`） - `429` 频率限制（如 `42901`） - `500` 服务器错误（如 `50001`） ## 备注 - 统一采用 `code/message/data` 包装 - 编码字典可根据业务扩展，例如增加更细分的资源或流程编码（`402xx`、`403xx` 等）。