# NoticeCard Server

**Repository Path**: candy_xt/noticecard-server

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NoticeCard Server

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

## 特性

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

## 安装

### 从 PyPI 安装（发布后）

```bash
pip install noticecard
```

### 本地开发安装

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

# 安装依赖
pip install -e .
```

## 快速开始

### 启动服务器

```bash
# 使用默认配置启动（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}` - 删除卡片

### 请求示例

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

获取所有卡片：
```bash
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 服务器。

```bash
ncard serve [OPTIONS]
```

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

### init

初始化数据库。

```bash
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
```

### 运行测试

```bash
pip install -e ".[dev]"
pytest
```

### 构建发布包

```bash
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