noticecard 0.2.0

NoticeCard server with RESTful API and web UI

NoticeCard Server

一个基于 FastAPI 的卡片管理系统，提供完整的 RESTful API 和现代化的 Web UI 界面。

特性

• ✨ 基于 FastAPI 的高性能 RESTful API
• 📝 完整的 CRUD 操作支持
• 🎨 集成 Tabler UI 的响应式前端界面
• 📱 自适应布局，支持手机、平板和桌面设备
• 📚 自动生成的 OpenAPI/Swagger 文档
• 💾 SQLite 数据库，轻量级无需额外配置
• 🛠️ 命令行工具，简化部署和管理
• 🔄 CORS 支持，便于前后端分离开发
• 📄 分页支持，高效处理大量数据
• 🚨 完善的错误处理和事务回滚
• ⚡ 开发模式支持热重载

安装

从 PyPI 安装（发布后）

pip install noticecard

本地开发安装

# 克隆仓库
git clone https://gitee.com/candy_xt/noticecard-server.git
cd noticecard-server

# 安装依赖
pip install -e .

快速开始

启动服务器

# 使用默认配置启动（0.0.0.0:3143）
ncard serve

# 指定主机和端口
ncard serve --host 127.0.0.1 --port 8080

# 指定工作目录（数据库存储位置）
ncard serve --dir ./my_data

# 开发模式（自动重载）
ncard serve --reload

# 指定日志级别
ncard serve --log-level debug

# 组合使用
ncard serve --host 0.0.0.0 --port 8080 --dir ./data --reload --log-level info

访问服务

• Web UI: http://localhost:3143
• API 文档 (Swagger): http://localhost:3143/docs
• API 文档 (ReDoc): http://localhost:3143/redoc
• OpenAPI JSON: http://localhost:3143/openapi.json

API 端点

卡片管理

• GET /cards/ - 获取所有卡片（支持分页）
  • 查询参数：skip（跳过数量，默认0）、limit（限制数量，默认100）
• GET /cards/{card_id} - 获取指定卡片
• POST /cards/ - 创建新卡片
• PUT /cards/{card_id} - 更新卡片
• DELETE /cards/{card_id} - 删除卡片

请求示例

创建卡片：

curl -X POST "http://localhost:3143/cards/" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "会议通知",
    "description": "明天下午2点在一号会议室"
  }'

获取所有卡片：

curl "http://localhost:3143/cards/"

# 使用分页
curl "http://localhost:3143/cards/?skip=0&limit=10"

数据模型

Card

字段	类型	说明
id	Integer	主键，自动生成
title	String	标题（必填）
description	String	描述（可选）
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

CLI 命令

serve

启动 NoticeCard 服务器。

ncard serve [OPTIONS]

选项：

• --host TEXT - 绑定的主机地址（默认：0.0.0.0）
• --port INTEGER - 绑定的端口（默认：3143）
• --dir TEXT - 工作目录，用于存储数据库（默认：当前目录）
• --reload - 启用自动重载（开发模式）
• --log-level - 日志级别：critical, error, warning, info, debug（默认：info）

init

初始化数据库。

ncard init [OPTIONS]

选项：

• --dir TEXT - 工作目录（默认：当前目录）

开发

项目结构

noticecard/
├── noticecard/
│   ├── __init__.py
│   ├── app.py          # FastAPI 应用
│   ├── models.py       # 数据库模型
│   ├── schemas.py      # Pydantic 模型
│   ├── templates.py    # HTML 模板
│   └── cli.py          # CLI 工具
├── pyproject.toml      # 项目配置
├── README.md
└── .gitignore

运行测试

pip install -e ".[dev]"
pytest

构建发布包

pip install build twine
python -m build
twine upload dist/*

技术栈

• FastAPI - 现代化的 Python Web 框架
• SQLAlchemy - SQL 工具包和 ORM
• Pydantic - 数据验证和设置管理
• Click - 命令行工具框架
• Uvicorn - ASGI 服务器
• Tabler UI - 响应式前端框架

贡献

欢迎提交 Issue 和 Pull Request！

仓库地址：https://gitee.com/candy_xt/noticecard-server

许可证

MIT License