mirror of
https://github.com/KuekHaoYang/KVideo.git
synced 2026-08-15 16:53:42 +08:00
docs: add initial project documentation files
This commit is contained in:
kuekhaoyang
@@ -0,0 +1,97 @@
|
||||
# 贡献指南 (Contributing Guide)
|
||||
|
||||
感谢你对 **KVideo** 项目感兴趣！我们非常欢迎并感谢社区的任何贡献，无论是修复 Bug、改进文档，还是提出新功能建议。
|
||||
|
||||
为了确保协作顺畅，请在提交贡献前花几分钟阅读以下指南。
|
||||
|
||||
## 🤝 行为准则
|
||||
|
||||
我们致力于构建一个开放、友好、包容的社区。请在参与项目时保持尊重和礼貌。
|
||||
|
||||
## 🛠 开发流程
|
||||
|
||||
### 1. Fork 项目
|
||||
|
||||
首先，将本仓库 Fork 到你自己的 GitHub 账号下。
|
||||
|
||||
### 2. 克隆到本地
|
||||
|
||||
```bash
|
||||
git clone https://github.com/KuekHaoYang/KVideo.git
|
||||
cd KVideo
|
||||
```
|
||||
|
||||
### 3. 创建分支
|
||||
|
||||
请基于 `main` 分支创建新的功能分支。分支命名建议遵循以下规范：
|
||||
|
||||
* `feat/功能名称`: 新功能 (例如: `feat/add-subtitle-support`)
|
||||
* `fix/问题描述`: 修复 Bug (例如: `fix/search-bar-layout`)
|
||||
* `docs/文档修改`: 文档更新 (例如: `docs/update-readme`)
|
||||
* `refactor/重构`: 代码重构 (例如: `refactor/api-client`)
|
||||
|
||||
```bash
|
||||
git checkout -b feat/your-feature-name
|
||||
```
|
||||
|
||||
### 4. 开发与调试
|
||||
|
||||
请确保你的代码符合项目的技术栈和风格：
|
||||
|
||||
* **TypeScript**: 请尽量使用强类型，避免使用 `any`。
|
||||
* **Tailwind CSS**: 使用 Tailwind 类名进行样式开发，保持 "Liquid Glass" 的设计风格。
|
||||
* **组件化**: 保持组件的单一职责，复用 `components/ui` 下的基础组件。
|
||||
|
||||
启动本地开发服务器：
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 5. 提交代码 (Commit)
|
||||
|
||||
我们推荐使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范来编写提交信息：
|
||||
|
||||
* `feat`: 新功能
|
||||
* `fix`: 修复 Bug
|
||||
* `docs`: 文档变更
|
||||
* `style`: 代码格式 (不影响代码运行的变动)
|
||||
* `refactor`: 重构 (既不是新增功能，也不是修改 bug 的代码变动)
|
||||
* `perf`: 性能优化
|
||||
* `test`: 增加测试
|
||||
* `chore`: 构建过程或辅助工具的变动
|
||||
|
||||
示例：
|
||||
```bash
|
||||
git commit -m "feat: 增加视频倍速播放功能"
|
||||
```
|
||||
|
||||
### 6. 提交 Pull Request (PR)
|
||||
|
||||
1. 将代码推送到你的远程仓库：`git push origin feat/your-feature-name`
|
||||
2. 在 GitHub 上发起 Pull Request 到 `KVideo:main` 分支。
|
||||
3. 请在 PR 描述中详细说明你的修改内容、解决的问题以及测试截图（如果是 UI 变更）。
|
||||
|
||||
## 📐 代码风格
|
||||
|
||||
本项目使用 ESLint 和 Prettier 进行代码检查和格式化。在提交代码前，请确保通过了代码检查：
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## 🐛 发现 Bug？
|
||||
|
||||
如果你发现了 Bug，请在 GitHub Issues 中提交报告。提交时请包含以下信息：
|
||||
|
||||
* Bug 的详细描述
|
||||
* 复现步骤
|
||||
* 预期的行为
|
||||
* 截图或报错日志 (如果有)
|
||||
* 你的运行环境 (浏览器版本, OS 等)
|
||||
|
||||
## 💡 提出新功能？
|
||||
|
||||
如果你有新的想法，欢迎在 Issues 中提出 Feature Request。请详细描述该功能的用途和你的实现思路。
|
||||
|
||||
再次感谢你的贡献！让我们一起把 KVideo 变得更好！
|
||||
@@ -0,0 +1,116 @@
|
||||
# KVideo
|
||||
|
||||
|
||||
|
||||
> 一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言，提供流畅的视觉体验和强大的视频搜索功能。
|
||||
|
||||
[](https://nextjs.org/)
|
||||
[](https://react.dev/)
|
||||
[](https://tailwindcss.com/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](LICENSE)
|
||||
|
||||
## 📖 项目简介
|
||||
|
||||
**KVideo** 是一个高性能的视频聚合与播放应用。它利用 Next.js 16 的最新特性，结合 React 19 和 Tailwind CSS v4，打造了一个既美观又强大的视频浏览体验。
|
||||
|
||||
项目的核心设计理念是 **"Liquid Glass" (液态玻璃)** —— 一种强调透明感、模糊效果和流畅交互的视觉风格。
|
||||
|
||||
## ✨ 主要功能
|
||||
|
||||
* **🎥 智能播放器**: 内置功能强大的视频播放器，支持多种流媒体格式，提供流畅的观看体验。
|
||||
* **🔍 聚合并行搜索**: 能够同时在多个视频源中进行并行搜索 (`lib/api/search-api.ts`)，快速定位目标内容。
|
||||
* **🎬 豆瓣深度集成**: 自动对接豆瓣 API (`app/api/douban`)，获取详尽的影视资料、评分和推荐。
|
||||
* **🎨 Liquid Glass UI**: 独特的玻璃拟态设计系统，配合精细的动画效果，带来沉浸式的视觉享受。
|
||||
* **💾 观看历史**: 本地化存储用户的观看进度和历史记录，随时继续观看。
|
||||
* **📱 全端响应式**: 精心设计的响应式布局，在桌面、平板和手机上都能完美运行。
|
||||
* **🌙 主题切换**: 内置深色模式与浅色模式，适应不同环境下的观看需求。
|
||||
|
||||
## 🛠 技术栈
|
||||
|
||||
本项目采用最前沿的前端技术栈构建：
|
||||
|
||||
* **核心框架**: [Next.js 16](https://nextjs.org/) (App Router)
|
||||
* **UI 库**: [React 19](https://react.dev/)
|
||||
* **样式方案**: [Tailwind CSS v4](https://tailwindcss.com/) (配合 CSS Variables 实现动态主题)
|
||||
* **状态管理**: [Zustand](https://github.com/pmndrs/zustand)
|
||||
* **编程语言**: [TypeScript](https://www.typescriptlang.org/)
|
||||
* **代码规范**: ESLint + Prettier
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
按照以下步骤在本地启动项目：
|
||||
|
||||
### 1. 环境准备
|
||||
|
||||
确保你的开发环境满足以下要求：
|
||||
* **Node.js**: v20.0.0 或更高版本
|
||||
* **npm** 或 **yarn** / **pnpm**
|
||||
|
||||
### 2. 获取代码
|
||||
|
||||
```bash
|
||||
git clone https://github.com/KuekHaoYang/KVideo.git
|
||||
cd KVideo
|
||||
```
|
||||
|
||||
### 3. 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
# 或者
|
||||
yarn install
|
||||
# 或者
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 4. 启动开发服务器
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
访问 [http://localhost:3000](http://localhost:3000) 即可看到应用。
|
||||
|
||||
### 5. 构建生产版本
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
## 📂 项目结构
|
||||
|
||||
```
|
||||
KVideo/
|
||||
├── app/ # Next.js App Router 路由与页面
|
||||
│ ├── api/ # 后端 API 路由 (Douban, Search, etc.)
|
||||
│ ├── player/ # 播放器页面
|
||||
│ ├── settings/ # 设置页面
|
||||
│ └── globals.css # 全局样式 (包含 Liquid Glass 样式引入)
|
||||
├── components/ # React UI 组件
|
||||
│ ├── player/ # 播放器相关组件
|
||||
│ ├── search/ # 搜索相关组件
|
||||
│ ├── ui/ # 通用基础组件
|
||||
│ └── ...
|
||||
├── lib/ # 工具函数与核心逻辑
|
||||
│ ├── api/ # API 客户端与数据源定义
|
||||
│ ├── store/ # Zustand 状态管理
|
||||
│ └── utils/ # 通用工具函数
|
||||
├── public/ # 静态资源
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！详细的贡献规范请参考 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目基于 MIT 许可证开源。详情请参阅 [LICENSE](LICENSE) 文件。
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
Made with ❤️ by <a href="https://github.com/KuekHaoYang">KuekHaoYang</a>
|
||||
</div>
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
# 安全策略 (Security Policy)
|
||||
|
||||
## 支持的版本
|
||||
|
||||
目前我们仅对项目的最新主分支 (`main`) 提供安全更新支持。
|
||||
|
||||
| 版本 | 支持状态 |
|
||||
| :--- | :--- |
|
||||
| `main` (最新版) | ✅ 支持 |
|
||||
| 历史版本 | ❌ 不支持 |
|
||||
Reference in New Issue
Block a user