# rdfz-md

**Repository Path**: htmlpan/rdfz-md

## Basic Information

- **Project Name**: rdfz-md
- **Description**: 沙盒网旨在为校园及 Minecraft 社区用户提供一个集内容创作、图片分享、活动组织、论坛讨论与服务器信息展示于一体的综合平台。系统需支持多角色协作、内容审核、互动参与与安全访问控制，保证良好的可扩展性与维护性
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-10-20
- **Last Updated**: 2025-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rdfz-md (Sandbox Campus & Minecraft Community Platform)

Content creation · Image gallery · Events · Forum · Server status · Unified permissions & moderation

## 1. Overview

本项目旨在为校园与 Minecraft 社区提供一个统一门户：文章发布、图集分享、活动组织、论坛讨论、服务器监控与互动统一在一个可扩展平台中。支持角色分级 (member / moderator / admin)、内容审核、统一错误与分页规范、软删除与审计日志。

## 2. Core Features

- User & Auth: 注册 / 登录 / JWT / 刷新令牌（可选） / 角色权限 / 审计日志
- Posts: 分类、标签、全文索引、草稿/发布、评论、点赞、浏览量统计
- Gallery: 图片分类/标签、状态审核 (pending/approved/rejected)、精选、评论、点赞
- Events: 活动创建、报名、状态流转(upcoming/ongoing/ended/cancelled)、统计
- Forum: 分类、主题、回复、置顶、锁定、浏览统计
- Server Monitor: 服务器基础信息、在线玩家快照、历史统计
- Interaction: 统一多态点赞 (post/image/topic/event)
- Observability & Safety: 审计日志、软删除、统一错误响应、字段一致命名策略
- Extensibility: 预留通知、版本历史、国际化、多语言分类
- **Frontend Cache Management**: 自动版本控制，智能缓存破坏，无需用户手动清除缓存

## 3. Documentation

| 文档 | 描述 |
|------|------|
| `../需求文档.md` | 系统需求规格（SRS） |
| `../API接口协议.md` | REST API 规范与示例 |
| `../数据库结构.md` | MySQL 表结构与 DDL |

## 4. Tech & Conventions

- Backend: (待实现) 推荐 Node.js / TypeScript / NestJS 或 Spring Boot（未在此仓库）
- DB: MySQL 8.x，UTF8MB4，InnoDB，统一时间戳字段 (`created_at`/`updated_at`/`deleted_at`)
- Auth: JWT（访问令牌 + 刷新令牌）+ BCrypt 密码哈希
- API 统一：分页 `{ data, pagination{ page, limit, total, totalPages } }`；错误 `{ code, message, details, traceId }`
- 命名：API camelCase；DB snake_case；多态类型字段受控枚举

## 5. Database Entities (Excerpt)

主要表（详见 `../数据库结构.md`）：
`users`, `refresh_tokens`, `audit_logs`, `posts`, `post_categories`, `post_tags`, `post_tag_map`, `post_comments`, `images`, `image_categories`, `image_tags`, `image_tag_map`, `image_comments`, `events`, `event_categories`, `event_participants`, `forum_categories`, `forum_topics`, `forum_replies`, `content_likes`, `servers`, `server_stats`, `server_players`。

## 6. Directory (Current Repo)

```text
./
├── 需求文档.md
├── API接口协议.md
├── 数据库结构.md
├── img/
│   ├── image1.jpg
│   ├── image2.jpg
│   ├── image3.jpeg
│   └── image4.jpeg
├── rdfz-md/
│   └── README.en.md (当前文件)
└── logo.png
```

## 7. 快速开始（FastAPI 后端 + 静态前端）

```bash
# 1. 克隆仓库
git clone <repo>
cd rdfz-md

# 2. 创建并启用虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动开发服务（默认使用 SQLite）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

启动后：

- 后端 API 根路径：<http://127.0.0.1:8000/rdfz-md-server>
- Swagger 文档：<http://127.0.0.1:8000/rdfz-md-server/docs>
- 静态前端入口：<http://127.0.0.1:8000/rdfz-md-server/>

静态目录 `static/` 中的页面会自动通过 FastAPI 提供：

| 路径 | 说明 |
|------|------|
| `/rdfz-md-server/` | 首页（`static/index.html`） |
| `/rdfz-md-server/login.html` | 登录页 |
| `/rdfz-md-server/register.html` | 注册页 |
| `/rdfz-md-server/users.html` | 用户列表 |
| `/rdfz-md-server/activities.html` | 活动页 |
| `/rdfz-md-server/gallery.html` | 图库管理与展示 |
| `/rdfz-md-server/profile.html` | 个人中心 |

若部署到其他域名 / 端口，只需保持服务器 `root_path='/rdfz-md-server'` 或相应调整 `static/js/config.js` 中的 API 基址。

### Gallery 前端一览

`static/gallery.html` + `static/js/gallery.js` 提供完整的图库前端体验：

- **筛选与搜索**：按状态、分类、标签、关键词、精选、创建者过滤，排序支持时间/浏览/点赞/评论。
- **上传与编辑**：登录用户可上传图片（支持分类、标签、描述、启用评论）；管理员可直接修改状态。
- **审核与精选**：管理员可在列表中快速审核、驳回、设为精选并添加备注。
- **互动**：内置点赞、评论抽屉（支持删除自己的评论），统计实时刷新。
- **响应式布局**：桌面三列、移动单列，配合浮动上传按钮与导航一致主题。
- **URL 状态同步**：筛选条件写入地址栏，刷新或分享链接保留当前视图。

## 8. API Conventions Summary

| 项目 | 约定 |
|------|------|
| 认证 | Bearer Token (Authorization 头) |
| 分页请求 | `?page=1&limit=20` |
| 分页响应 | `data[] + pagination` 对象 |
| 错误格式 | `{ code, message, details, traceId }` |
| 软删除 | `deleted_at IS NULL` 过滤 |
| 点赞唯一 | `(user_id, content_type, content_id)` 唯一约束 |
| 时间 | 统一 `TIMESTAMP`（UTC 或指定时区） |

## 9. Contribution Guide

欢迎贡献：
 
1. Fork & Clone
2. 创建分支：`feat/<scope>` / `fix/<issue>`
3. 提交信息遵循 Conventional Commits（示例：`feat(post): add post search index`）
4. 提交 PR（描述变更 / 关联 issue / 截图如有 UI）

## 10. Roadmap (Snapshot)

- [ ] 用户体系后端实现
- [ ] 文章 & 图库接口实现 + 测试
- [ ] 活动与论坛模块落地
- [ ] 服务器监控采集任务
- [ ] 通知与 WebSocket 实时消息
- [ ] 国际化多语言支持

## 11. 认证与刷新机制 (当前实现摘要)

后端 FastAPI 已实现用户注册 / 登录 / 刷新 / 登出 / 软删除。

### Token 字段

返回统一驼峰：

- accessToken (短期访问令牌)
- refreshToken (长期刷新令牌，7 天有效，刷新时轮换)
- tokenType (bearer)

### 登录 & 注册

`POST /auth/login` 与 `POST /auth/register` 均返回 accessToken + refreshToken + user。

### 刷新

`POST /auth/refresh` 传 `{ "refreshToken": "..." }`：

- 校验与数据库 token_hash 比对；
- 成功后删除旧记录并颁发新对（一次性使用策略）；
- 失败 / 过期返回 401。

### 登出

`POST /auth/logout` 传 refreshToken，若存在即删除，返回 204（幂等且避免信息泄露）。

### 前端自动刷新策略

`index.html` 内封装 `makeRequest`：接口 401 且本地存在 refreshToken 时自动调用 `/auth/refresh`，成功后重试一次原请求。

### 建议后续强化

- 限制每用户 refresh token 最大数量 (设备多端控制)
- 定时清理过期 refresh token
- 注销账号时批量失效其全部 refresh token
- 记录 refresh token 的 UA / IP / 最后使用时间，提供安全面板
- 高敏操作二次验证（Re-auth / OTP）

## 11. Frontend Cache Management（前端缓存管理）🆕

为解决前端更新后用户需要手动清除缓存的问题，项目已实现**自动缓存破坏（Cache Busting）**方案。

### 特性

- ✅ 自动为静态资源（CSS/JS）添加版本号
- ✅ 用户无需手动清除缓存
- ✅ 浏览器自动加载最新版本
- ✅ 充分利用浏览器缓存提升性能
- ✅ 一键发布工具

### 快速使用

```bash
# 方法一：一键发布（推荐）
./scripts/release.sh          # macOS/Linux
scripts\release.bat           # Windows

# 方法二：手动更新版本号
python scripts/add_cache_buster.py

# 验证配置
python scripts/verify_cache_buster.py
```

### 工作原理

脚本自动将：
```html
<link rel="stylesheet" href="css/style.css">
<script src="js/app.js"></script>
```

转换为：
```html
<link rel="stylesheet" href="css/style.css?v=20251018161938">
<script src="js/app.js?v=20251018161938">
```

版本号变化时，浏览器识别为新资源并自动下载最新版本。

### 相关文档

- [详细使用指南](docs/cache_buster_guide.md)
- [解决方案总结](docs/cache_solution_summary.md)
- [快速开始](scripts/README_CACHE_BUSTER.md)
- [在线演示](static/cache_demo.html)

### 当前状态

- ✅ 16 个HTML文件已配置
- ✅ 70 个静态资源已添加版本号
- ✅ 统一版本号管理
- ✅ 跨平台支持（Windows/macOS/Linux）

## 12. License

待定（建议：MIT 或 Apache-2.0）

## 12. Acknowledgements

灵感来源：校园社群与 Minecraft 社区的综合互动需求。

---
若你正在实现后端，请先阅读：`需求文档.md`、`API接口协议.md`、`数据库结构.md`。

---
Generated documentation baseline. Further improvements welcome.