# Server

**Repository Path**: Free_520/Server

## Basic Information

- **Project Name**: Server
- **Description**: 这是一个基于 Flask 的服务端项目骨架，目标是逐步构建一个可扩展的个人平台
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Server

[English](README.en.md)

## 项目简介
这是一个基于 Flask 的服务端项目骨架，目标是逐步构建一个可扩展的个人平台，包含以下方向：
- 博客内容管理（文章、评论、标签等）
- 社区交流能力（后续可扩展到类似频道/群组）
- 个人小项目的统一接入

当前仓库阶段以目录架构搭建为主，业务代码将按模块逐步补充。

## 软件架构
当前采用模块化单体（Modular Monolith）设计。

### 目录结构（详细）

```txt
Server/
├─ app/
│  ├─ __init__.py                  # Flask 应用工厂 create_app()；注册蓝图、扩展、错误处理
│  ├─ config.py                    # 配置管理（开发/测试/生产），读取环境变量
│  ├─ extensions.py                # 扩展实例（db、migrate、jwt、redis 客户端等）
│  ├─ blueprints/                  # 按业务领域拆分的接口层
│  │  ├─ auth/                     # 用户认证模块
│  │  │  ├─ __init__.py            # auth 蓝图对象定义
│  │  │  ├─ routes.py              # 注册/登录/个人信息等路由
│  │  │  └─ service.py             # 认证业务逻辑（密码校验、token签发）
│  │  ├─ blog/                     # 博客模块
│  │  │  ├─ __init__.py            # blog 蓝图对象定义
│  │  │  ├─ routes.py              # 文章 CRUD、列表、详情 API
│  │  │  └─ service.py             # 文章业务逻辑（发布、编辑、权限判断）
│  │  ├─ comment/                  # 评论模块
│  │  │  ├─ __init__.py            # comment 蓝图对象定义
│  │  │  ├─ routes.py              # 评论创建/删除/查询 API
│  │  │  └─ service.py             # 评论业务逻辑（关联文章、权限判断）
│  │  └─ channel/                  # 频道/群组模块（扩展预留）
│  │     ├─ __init__.py            # channel 蓝图对象定义
│  │     ├─ routes.py              # 频道、成员、消息相关 API
│  │     └─ service.py             # 频道业务逻辑（成员关系、消息发送规则）
│  ├─ models/                      # 数据模型层（SQLAlchemy）
│  │  ├─ __init__.py               # 导出模型，供迁移工具识别
│  │  ├─ user.py                   # 用户模型（账号、角色、状态）
│  │  ├─ post.py                   # 文章模型（标题、内容、作者、状态）
│  │  ├─ comment.py                # 评论模型（内容、文章、评论人）
│  │  ├─ channel.py                # 频道与成员模型（频道、成员关系、角色）
│  │  └─ message.py                # 频道消息模型（发送者、消息内容、时间）
│  └─ common/                      # 通用能力层
│     ├─ response.py               # 统一响应格式封装
│     ├─ errors.py                 # 自定义异常与全局错误处理
│     ├─ decorators.py             # 通用装饰器（鉴权、角色校验、限流占位）
│     └─ utils.py                  # 工具函数（时间、分页、字符串处理等）
├─ migrations/                     # Alembic/Flask-Migrate 迁移脚本目录
│  ├─ env.py                       # 迁移环境配置
│  ├─ script.py.mako               # 迁移脚本模板
│  └─ versions/                    # 每次迁移生成的版本脚本
├─ tests/                          # 测试目录（pytest）
│  ├─ conftest.py                  # 全局 fixture（测试 app、测试数据库、token 工具）
│  ├─ test_auth.py                 # 认证模块测试
│  ├─ test_blog.py                 # 博客模块测试
│  ├─ test_comment.py              # 评论模块测试
│  └─ test_channel.py              # 频道模块测试
├─ main.py                         # 本地开发启动入口（python main.py）
├─ wsgi.py                         # 生产启动入口（gunicorn wsgi:app）
├─ requirements.txt                # Python 依赖列表
├─ .env.example                    # 环境变量模板
├─ README.md                       # 中文说明文档
└─ README.en.md                    # 英文说明文档
```

### 分层职责约束（建议严格遵守）
- `routes.py` 只做参数接收、调用 service、返回响应，不写复杂业务。
- `service.py` 只做业务编排和规则判断，不直接耦合 HTTP 细节。
- `models/*.py` 只定义数据结构与关系，不放路由逻辑。
- `common/*` 只放跨模块复用代码，禁止写某一个业务模块的专用逻辑。
- `tests/*` 与业务模块一一对应，新增模块必须同时新增对应测试文件。

## 技术规划
首期建议技术栈：
- Python 3.11+
- Flask
- PostgreSQL
- Redis（缓存/消息能力预留）

后续可按需要引入：
- SQLAlchemy + Alembic
- JWT 鉴权
- Celery 异步任务
- WebSocket/Socket.IO 实时通信

## 快速开始
1. 克隆仓库：`git clone <your-repo-url>`
2. 进入目录：`cd Server`
3. 创建并激活虚拟环境：
- Windows: `python -m venv .venv && .venv\Scripts\activate`
- Linux/macOS: `python -m venv .venv && source .venv/bin/activate`

当前阶段尚未固定依赖文件与完整启动脚本，后续补齐后可直接按 README 命令运行。

## 开发路线（建议）
1. 完成基础应用工厂与配置管理
2. 完成用户系统（注册、登录、权限）
3. 完成博客模块（文章、评论）
4. 增加频道模块（成员、消息、权限）
5. 补齐测试、部署与监控

## 贡献指南
1. Fork 本仓库
2. 新建分支（如：`feat/auth-module`）
3. 提交变更并附上说明
4. 发起 Pull Request

## 许可证
本仓库采用 [LICENSE](LICENSE) 中声明的许可证。