v1.0.0补全提交

README.md

@@ -1,2 +1,155 @@
-# PerToolBoxServer
+# PerToolBox Server - 后端服务
 
+> 个人工具箱后端 API，基于 FastAPI + MySQL + Redis
+
+---
+
+## 📄 版权信息
+
+* **版权所有**: Sea Network Technology Studio
+* **权利人**: Canglan
+* **联系方式**: [admin@sea-studio.top](mailto:admin@sea-studio.top)
+* **开源协议**: AGPL v3
+
+---
+
+## 🚀 功能特性
+
+* ✅ 用户认证（手机 / 邮箱验证码登录）
+* ✅ 待办事项管理
+* ✅ 便签本
+* ✅ 密码生成器
+* ✅ 二维码生成
+* ✅ 加密工具箱（哈希、Base64、URL、AES）
+* ✅ JSON 校验与格式化
+* ✅ 热度统计（页面访问次数）
+
+---
+
+## 🧰 环境要求
+
+| 组件     | 版本要求 |
+| ------ | ---- |
+| Python | 3.12 |
+| MySQL  | 5.7  |
+| Redis  | 7.x  |
+
+---
+
+## ⚡ 快速开始
+
+### 1️⃣ 克隆代码
+
+```bash
+git clone https://hz-gitea.sea-studio.top/yourname/PerToolBoxServer.git
+cd PerToolBoxServer
+```
+
+### 2️⃣ 创建虚拟环境
+
+```bash
+python3.12 -m venv venv
+source venv/bin/activate
+```
+
+### 3️⃣ 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 4️⃣ 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件，填写数据库、Redis、短信等配置
+
+### 5️⃣ 初始化数据库
+
+```bash
+mysql -u root -p < scripts/init_db.sql
+```
+
+### 6️⃣ 启动服务
+
+```bash
+uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### 7️⃣ 访问 API 文档
+
+```
+http://localhost:8000/api/v1/docs
+```
+
+---
+
+## ⚙️ 部署（systemd）
+
+### 创建服务文件
+
+路径：`/etc/systemd/system/pertoolbox.service`
+
+```ini
+[Unit]
+Description=PerToolBox Backend
+After=network.target
+
+[Service]
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/PerToolBoxServer
+ExecStart=/opt/PerToolBoxServer/venv/bin/gunicorn backend.main:app \
+    -w 4 \
+    -k uvicorn.workers.UvicornWorker \
+    --bind 127.0.0.1:8000
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 启动服务
+
+```bash
+sudo systemctl daemon-reexec
+sudo systemctl daemon-reload
+sudo systemctl enable pertoolbox
+sudo systemctl start pertoolbox
+```
+
+### 查看状态
+
+```bash
+sudo systemctl status pertoolbox
+```
+
+---
+
+## 📡 API 端点
+
+| 模块 | 端点                          | 说明          |
+| -- | --------------------------- | ----------- |
+| 认证 | `/api/v1/auth/*`            | 注册、登录、发送验证码 |
+| 用户 | `/api/v1/user/*`            | 个人信息        |
+| 待办 | `/api/v1/todos/*`           | 待办事项 CRUD   |
+| 便签 | `/api/v1/notes/*`           | 便签 CRUD     |
+| 工具 | `/api/v1/password/generate` | 密码生成        |
+| 工具 | `/api/v1/qrcode/generate`   | 二维码生成       |
+| 工具 | `/api/v1/crypto/*`          | 加密工具        |
+| 工具 | `/api/v1/json/validate`     | JSON 校验     |
+| 统计 | `/api/v1/tool/stats`        | 热度统计        |
+
+---
+
+## 🔧 配置说明
+
+详见 `.env.example` 文件。
+
+---
+
+## 📜 许可证
+
+本项目基于 **AGPL v3** 开源协议发布。

backend/main.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PerToolBox Server - FastAPI 主程序
+Copyright (C) 2024 Sea Network Technology Studio
+Author: Canglan <admin@sea-studio.top>
+License: AGPL v3
+
+API 文档: /api/v1/docs
+健康检查: /health
+"""
+
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.openapi.utils import get_openapi
+from sqlalchemy.orm import Session
+
+from .config import settings
+from .database import engine, Base, get_db
+from .middleware.logging import log_requests
+from .middleware.rate_limit import setup_rate_limit
+from .utils.logger import logger
+from .routers.v1 import (
+    auth_router, user_router, todos_router,
+    notes_router, tools_router, stats_router
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """应用生命周期管理"""
+    logger.info(f"启动 {settings.APP_NAME} v1.0.0")
+    logger.info(f"环境: {settings.ENVIRONMENT}")
+    logger.info(f"调试模式: {settings.DEBUG}")
+
+    # 创建数据库表
+    Base.metadata.create_all(bind=engine)
+    logger.info("数据库表初始化完成")
+
+    yield
+
+    logger.info("应用关闭")
+
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    description="""
+    ## PerToolBox 个人工具箱 API v1
+
+    提供以下功能：
+    - ✅ 用户认证（手机/邮箱验证码登录）
+    - ✅ 待办事项管理
+    - ✅ 便签本
+    - ✅ 密码生成器
+    - ✅ 二维码生成
+    - ✅ 加密工具箱（哈希、Base64、URL、AES）
+    - ✅ JSON 校验与格式化
+    - ✅ 热度统计（页面访问次数）
+
+    ### 版权信息
+    - © 2024 Sea Network Technology Studio
+    - Author: Canglan <admin@sea-studio.top>
+    - License: AGPL v3
+    """,
+    version="1.0.0",
+    docs_url="/api/v1/docs",
+    redoc_url="/api/v1/redoc",
+    openapi_url="/api/v1/openapi.json",
+    lifespan=lifespan
+)
+
+# CORS 配置
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# 限流配置
+setup_rate_limit(app)
+
+# 日志中间件
+app.middleware("http")(log_requests)
+
+
+# 健康检查
+@app.get("/health")
+async def health_check(db: Session = Depends(get_db)):
+    try:
+        db.execute("SELECT 1")
+        return {
+            "status": "healthy",
+            "database": "connected",
+            "version": "1.0.0"
+        }
+    except Exception as e:
+        logger.error(f"健康检查失败: {e}")
+        return {
+            "status": "unhealthy",
+            "database": str(e)
+        }
+
+
+# 注册路由
+app.include_router(auth_router)
+app.include_router(user_router)
+app.include_router(todos_router)
+app.include_router(notes_router)
+app.include_router(tools_router)
+app.include_router(stats_router)
+
+
+# 自定义 OpenAPI
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title=settings.APP_NAME,
+        version="1.0.0",
+        description=app.description,
+        routes=app.routes,
+    )
+
+    openapi_schema["info"]["x-copyright"] = "Sea Network Technology Studio"
+    openapi_schema["info"]["x-author"] = "Canglan <admin@sea-studio.top>"
+    openapi_schema["info"]["x-license"] = "AGPL v3"
+
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+
+app.openapi = custom_openapi
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "backend.main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=settings.DEBUG
+    )