From 437420ed154d601a1b37c87e1cbf4b591a8cf580 Mon Sep 17 00:00:00 2001 From: kuekhaoyang Date: Sat, 22 Nov 2025 11:12:05 +0800 Subject: [PATCH] docs: add initial project documentation files --- CONTRIBUTING.md | 97 ++++++++++++++++++++++++++++++++++++++++ README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 10 +++++ 3 files changed, 223 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..239faf3 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 变得更好！ diff --git a/README.md b/README.md new file mode 100644 index 0000000..c93e0e8 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +# KVideo + +![KVideo Banner](public/icon.png) + +> 一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言，提供流畅的视觉体验和强大的视频搜索功能。 + +[![Next.js](https://img.shields.io/badge/Next.js-16.0-black?style=for-the-badge&logo=next.js)](https://nextjs.org/) +[![React](https://img.shields.io/badge/React-19.0-blue?style=for-the-badge&logo=react)](https://react.dev/) +[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.0-38B2AC?style=for-the-badge&logo=tailwind-css)](https://tailwindcss.com/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/) +[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](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) 文件。 + +--- + +
+ Made with ❤️ by KuekHaoYang +
diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a231434 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,10 @@ +# 安全策略 (Security Policy) + +## 支持的版本 + +目前我们仅对项目的最新主分支 (`main`) 提供安全更新支持。 + +| 版本 | 支持状态 | +| :--- | :--- | +| `main` (最新版) | ✅ 支持 | +| 历史版本 | ❌ 不支持 |