# py

**Repository Path**: dgly/py

## Basic Information

- **Project Name**: py
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 公司网站后端系统 - FastAPI企业级解决方案

基于FastAPI框架开发的企业级前后端分离公司网站后端系统，采用现代化架构设计，具备高性能、高可用、易扩展等特点。

## 目录

- [项目概述](#项目概述)
- [技术栈](#技术栈)
- [项目架构](#项目架构)
- [快速开始](#快速开始)
- [API接口文档](#api接口文档)
- [数据库设计](#数据库设计)
- [安全策略](#安全策略)
- [部署指南](#部署指南)
- [开发规范](#开发规范)
- [测试](#测试)
- [项目进度](#项目进度)

## 项目概述

本项目是一个完整的企业级公司网站后端系统，提供以下核心功能：

- **用户认证与授权**：JWT Token认证、RBAC权限控制
- **内容管理**：文章/新闻发布、分类管理、标签管理
- **产品管理**：产品/服务展示、分类管理、属性管理
- **联系表单**：客户咨询收集、邮件通知
- **邮件订阅**：Newsletter订阅管理
- **文件上传**：图片/文档上传管理
- **审计日志**：操作记录追踪

## 技术栈

### 后端框架
| 技术 | 版本 | 说明 |
|------|------|------|
| FastAPI | 0.109.2 | 高性能异步Web框架 |
| Uvicorn | 0.27.1 | ASGI服务器 |
| Pydantic | 2.6.1 | 数据验证和序列化 |
| SQLAlchemy | 2.0.27 | ORM框架 |
| Alembic | 1.13.1 | 数据库迁移工具 |

### 数据库与缓存
| 技术 | 版本 | 说明 |
|------|------|------|
| PostgreSQL | 15 | 主数据库 |
| Redis | 7 | 缓存、会话、任务队列 |
| Celery | 5.3.6 | 异步任务处理 |

### 安全与认证
| 技术 | 版本 | 说明 |
|------|------|------|
| python-jose | 3.3.0 | JWT处理 |
| passlib | 1.7.4 | 密码哈希 |
| slowapi | 0.1.9 | 速率限制 |

### 部署与运维
| 技术 | 版本 | 说明 |
|------|------|------|
| Docker | 24+ | 容器化部署 |
| Nginx | 1.24 | 反向代理 |
| GitHub Actions | - | CI/CD自动化 |

## 项目架构

```
company-website-backend/
├── app/                          # 应用主目录
│   ├── api/                      # API路由层
│   │   ├── v1/                   # API版本1
│   │   │   ├── endpoints/        # 业务端点
│   │   │   │   ├── auth.py       # 认证相关
│   │   │   │   ├── users.py      # 用户管理
│   │   │   │   ├── articles.py   # 文章/新闻
│   │   │   │   ├── products.py   # 产品/服务
│   │   │   │   ├── uploads.py    # 文件上传
│   │   │   │   └── contact.py    # 联系表单
│   │   │   └── deps.py           # 依赖注入
│   │   └── deps.py               # 全局依赖
│   ├── core/                     # 核心配置
│   │   ├── config.py             # 配置管理
│   │   ├── security.py           # 安全相关
│   │   └── logging.py            # 日志配置
│   ├── db/                       # 数据库层
│   │   ├── base.py               # 基础模型
│   │   └── session.py            # 会话管理
│   ├── models/                   # ORM模型
│   │   ├── user.py               # 用户模型
│   │   ├── article.py            # 文章模型
│   │   ├── product.py            # 产品模型
│   │   ├── contact.py            # 联系表单模型
│   │   ├── upload.py             # 上传文件模型
│   │   └── audit.py              # 审计日志模型
│   ├── schemas/                  # Pydantic模型
│   │   ├── common.py             # 通用Schema
│   │   ├── user.py               # 用户Schema
│   │   ├── article.py            # 文章Schema
│   │   ├── product.py            # 产品Schema
│   │   ├── contact.py            # 联系表单Schema
│   │   └── upload.py             # 上传文件Schema
│   ├── services/                 # 业务逻辑层
│   │   └── user_service.py       # 用户服务
│   ├── utils/                    # 工具函数
│   ├── __init__.py
│   └── main.py                   # 应用入口
├── tests/                        # 测试目录
├── alembic/                      # 数据库迁移
├── docker/                       # Docker配置
│   └── nginx.conf                # Nginx配置
├── docs/                         # 文档
├── requirements/                 # 依赖文件
│   ├── base.txt                  # 基础依赖
│   ├── dev.txt                   # 开发依赖
│   └── prod.txt                  # 生产依赖
├── .env.example                  # 环境变量示例
├── .gitignore                    # Git忽略文件
├── Dockerfile                    # Docker构建文件
├── docker-compose.yml            # Docker编排配置
├── pytest.ini                  # Pytest配置
└── README.md                     # 项目文档
```

## 快速开始

### 环境要求

- Python 3.11+
- PostgreSQL 15+
- Redis 7+
- Docker & Docker Compose (可选)

### 本地开发环境搭建

1. **克隆项目**
```bash
git clone <repository-url>
cd company-website-backend
```

2. **创建虚拟环境**
```bash
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
```

3. **安装依赖**
```bash
pip install -r requirements/dev.txt
```

4. **配置环境变量**
```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息
```

5. **运行应用**
```bash
# 开发模式（自动重载）
uvicorn app.main:app --reload

# 或运行主程序
python -m app.main
```

6. **访问API文档**
- Swagger UI: http://localhost:8000/api/docs
- ReDoc: http://localhost:8000/api/redoc

### Docker部署

1. **构建并启动服务**
```bash
docker-compose up -d
```

2. **查看日志**
```bash
docker-compose logs -f api
```

3. **停止服务**
```bash
docker-compose down
```

## API接口文档

### 认证模块

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/auth/login` | 用户登录 |
| POST | `/api/v1/auth/refresh` | 刷新Token |
| GET | `/api/v1/auth/me` | 获取当前用户信息 |
| POST | `/api/v1/auth/change-password` | 修改密码 |
| POST | `/api/v1/auth/logout` | 用户登出 |

### 用户管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/users/` | 获取用户列表 |
| POST | `/api/v1/users/` | 创建用户 |
| GET | `/api/v1/users/{id}` | 获取用户详情 |
| PUT | `/api/v1/users/{id}` | 更新用户 |
| DELETE | `/api/v1/users/{id}` | 删除用户 |
| GET | `/api/v1/users/roles/` | 获取角色列表 |
| POST | `/api/v1/users/roles/` | 创建角色 |
| GET | `/api/v1/users/permissions/` | 获取权限列表 |

### 文章管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/articles/` | 获取文章列表 |
| POST | `/api/v1/articles/` | 创建文章 |
| GET | `/api/v1/articles/{id}` | 获取文章详情 |
| GET | `/api/v1/articles/slug/{slug}` | 通过Slug获取文章 |
| PUT | `/api/v1/articles/{id}` | 更新文章 |
| DELETE | `/api/v1/articles/{id}` | 删除文章 |
| GET | `/api/v1/articles/categories/` | 获取分类列表 |
| POST | `/api/v1/articles/categories/` | 创建分类 |
| GET | `/api/v1/articles/tags/` | 获取标签列表 |
| POST | `/api/v1/articles/tags/` | 创建标签 |

### 产品管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/products/` | 获取产品列表 |
| POST | `/api/v1/products/` | 创建产品 |
| GET | `/api/v1/products/{id}` | 获取产品详情 |
| GET | `/api/v1/products/slug/{slug}` | 通过Slug获取产品 |
| PUT | `/api/v1/products/{id}` | 更新产品 |
| DELETE | `/api/v1/products/{id}` | 删除产品 |
| GET | `/api/v1/products/categories/` | 获取产品分类列表 |
| POST | `/api/v1/products/categories/` | 创建产品分类 |

### 联系表单

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/contact/` | 提交联系表单 |
| GET | `/api/v1/contact/` | 获取联系列表(管理) |
| GET | `/api/v1/contact/{id}` | 获取联系详情 |
| PUT | `/api/v1/contact/{id}` | 更新联系状态 |
| DELETE | `/api/v1/contact/{id}` | 删除联系记录 |
| POST | `/api/v1/contact/newsletter/subscribe` | 订阅Newsletter |
| POST | `/api/v1/contact/newsletter/unsubscribe` | 取消订阅 |
| GET | `/api/v1/contact/newsletter/subscribers` | 获取订阅者列表 |

### 文件上传

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/uploads/` | 上传文件 |
| GET | `/api/v1/uploads/` | 获取上传文件列表 |
| GET | `/api/v1/uploads/{id}` | 获取上传文件详情 |
| DELETE | `/api/v1/uploads/{id}` | 删除上传文件 |

### 响应格式

所有API返回统一的响应格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2024-01-01T00:00:00Z"
}
```

列表响应包含分页信息：

```json
{
  "code": 200,
  "message": "success",
  "data": [],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "total_pages": 5,
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## 数据库设计

### 核心表结构

#### 用户表 (users)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| email | String(255) | 邮箱(唯一) |
| username | String(100) | 用户名(唯一) |
| hashed_password | String(255) | 密码哈希 |
| full_name | String(200) | 全名 |
| phone | String(20) | 电话 |
| avatar | String(500) | 头像URL |
| is_active | Boolean | 是否激活 |
| is_superuser | Boolean | 是否超级用户 |
| is_verified | Boolean | 是否验证 |
| last_login | DateTime | 最后登录时间 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

#### 文章表 (articles)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| title | String(300) | 标题 |
| slug | String(300) | URL标识(唯一) |
| summary | Text | 摘要 |
| content | Text | 内容 |
| cover_image | String(500) | 封面图 |
| status | Enum | 状态(draft/published/archived) |
| is_featured | Boolean | 是否推荐 |
| view_count | Integer | 浏览次数 |
| published_at | DateTime | 发布时间 |
| author_id | Integer | 作者ID(外键) |
| category_id | Integer | 分类ID(外键) |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

#### 产品表 (products)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| name | String(200) | 产品名称 |
| slug | String(200) | URL标识(唯一) |
| summary | Text | 摘要 |
| description | Text | 描述 |
| price | Numeric(10,2) | 价格 |
| compare_price | Numeric(10,2) | 原价 |
| currency | String(3) | 货币 |
| featured_image | String(500) | 主图 |
| gallery | Text | 图库(JSON) |
| status | Enum | 状态 |
| is_featured | Boolean | 是否推荐 |
| stock_quantity | Integer | 库存数量 |
| category_id | Integer | 分类ID(外键) |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

#### 联系表单表 (contacts)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| name | String(100) | 姓名 |
| email | String(255) | 邮箱 |
| phone | String(20) | 电话 |
| company | String(200) | 公司 |
| subject | String(200) | 主题 |
| message | Text | 消息内容 |
| status | Enum | 状态 |
| is_read | Boolean | 是否已读 |
| ip_address | String(45) | IP地址 |
| user_agent | Text | 用户代理 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

## 安全策略

### 认证授权
- **JWT Token认证**：使用HS256算法签名，支持Access Token和Refresh Token
- **Token过期策略**：Access Token 30分钟，Refresh Token 7天
- **RBAC权限控制**：基于角色的访问控制，支持细粒度权限管理

### 数据安全
- **密码加密**：使用bcrypt算法进行密码哈希
- **SQL注入防护**：使用SQLAlchemy ORM，参数化查询
- **XSS防护**：输入验证和输出编码
- **CSRF防护**：使用SameSite Cookie和CSRF Token

### 访问控制
- **速率限制**：API接口限制每分钟60次请求
- **CORS配置**：限制允许的跨域来源
- **IP白名单/黑名单**：支持IP访问控制
- **请求签名**：敏感接口支持请求签名验证

## 部署指南

### 生产环境部署

1. **环境准备**
```bash
# 安装Docker和Docker Compose
curl -fsSL https://get.docker.com | sh
```

2. **配置环境变量**
```bash
cp .env.example .env
# 编辑.env文件，设置生产环境配置
```

3. **构建并启动**
```bash
docker-compose -f docker-compose.yml up -d --build
```

4. **执行数据库迁移**
```bash
docker-compose exec api alembic upgrade head
```

5. **创建超级用户**
```bash
docker-compose exec api python -c "
from app.services.user_service import UserService
from app.db.session import AsyncSessionLocal
import asyncio

async def create_superuser():
    async with AsyncSessionLocal() as db:
        user_service = UserService(db)
        await user_service.create({
            'email': 'admin@company.com',
            'username': 'admin',
            'password': 'your-secure-password',
            'is_superuser': True
        })

asyncio.run(create_superuser())
"
```

### 监控与日志

- **日志收集**：使用Loguru进行结构化日志记录
- **错误追踪**：集成Sentry进行错误监控
- **性能监控**：集成Prometheus进行指标收集
- **健康检查**：提供 `/health` 端点进行健康检查

## 开发规范

### 代码规范
- 遵循PEP 8代码风格
- 使用类型注解(Type Hints)
- 编写文档字符串(Docstrings)
- 代码审查通过后方可合并

### Git工作流
- 使用Git Flow分支模型
- 语义化版本控制(Semantic Versioning)
- Conventional Commits提交规范
- Pull Request代码审查

### 分支命名规范
```
feature/xxx    # 新功能
bugfix/xxx     # Bug修复
hotfix/xxx     # 紧急修复
release/xxx    # 版本发布
```

### 提交信息规范
```
feat: 添加新功能
fix: 修复Bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建过程或辅助工具的变动
```

## 测试

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_auth.py

# 运行特定测试函数
pytest tests/test_auth.py::test_login

# 生成覆盖率报告
pytest --cov=app --cov-report=html
```

### 测试覆盖范围
- 单元测试：核心业务逻辑
- 集成测试：API接口
- 性能测试：关键接口性能基准

## 项目进度

| 阶段 | 内容 | 预计时间 | 状态 |
|------|------|----------|------|
| 第1周 | 环境搭建、架构设计、数据库设计 | 5天 | 已完成 |
| 第2周 | 用户认证模块、权限系统 | 5天 | 已完成 |
| 第3周 | 内容管理模块（文章、产品） | 5天 | 已完成 |
| 第4周 | 文件上传、联系表单 | 5天 | 已完成 |
| 第5周 | 测试、文档、部署配置 | 5天 | 已完成 |
| 第6周 | 优化、验收、上线 | 5天 | 进行中 |

## 贡献指南

1. Fork项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建Pull Request

## 许可证

本项目采用MIT许可证 - 详见 [LICENSE](LICENSE) 文件

## 联系方式

- 项目维护者：[Your Name]
- 邮箱：[your.email@company.com]
- 项目地址：[Repository URL]

---

**注意**：本文档为实施方案文档，实际开发中请根据具体需求进行调整。