Files

Knowledge Base System acf549c43c feat: 初始化知识库系统项目

- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统
- 添加用户认证和分组管理功能
- 实现文档上传、分类和权限控制
- 集成 Word 文档自动转换为 Markdown
- 集成 Meilisearch 全文搜索引擎
- 实现文档在线预览功能
- 添加安全日志和审计功能
- 完整的简体中文界面
- 包含完整的项目文档和部署指南

技术栈:
- Laravel 11.x
- Filament 3.X
- Meilisearch 1.5+
- Pandoc 文档转换
- Redis 队列系统
- Pest PHP 测试框架

2025-12-05 14:44:44 +08:00

6.0 KiB

Raw Permalink Blame History

贡献指南

感谢你考虑为知识库系统做出贡献！

行为准则

本项目遵循贡献者公约行为准则。参与本项目即表示你同意遵守其条款。

如何贡献

报告 Bug

如果你发现了 bug，请创建一个 issue 并包含以下信息：

清晰的标题和描述
重现步骤
预期行为
实际行为
环境信息（PHP 版本、Laravel 版本、操作系统等）
相关日志或截图

提出新功能

如果你有新功能的想法：

先在 Discussions 中讨论
确保功能符合项目目标
创建详细的功能请求 issue

提交代码

开发流程

Fork 项目

# 在 GitHub 上 fork 项目
git clone https://github.com/your-username/knowledge-base-system.git
cd knowledge-base-system

创建分支

git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix

安装依赖

composer install
npm install
cp .env.example .env
php artisan key:generate

进行更改

编写代码
添加测试
更新文档

运行测试

php artisan test

提交更改

git add .
git commit -m "feat: 添加新功能描述"

推送到 GitHub

git push origin feature/your-feature-name

创建 Pull Request

在 GitHub 上创建 PR
填写 PR 模板
等待代码审查

提交信息规范

使用语义化提交信息：

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式（不影响代码运行）
refactor: 重构
test: 测试相关
chore: 构建过程或辅助工具的变动

示例：

feat: 添加文档批量上传功能

- 支持同时上传多个文档
- 添加进度条显示
- 更新相关文档

Closes #123

代码规范

PHP 代码
- 遵循 PSR-12 编码标准
- 使用 Laravel Pint 格式化代码
```
./vendor/bin/pint
```
JavaScript 代码
- 使用 2 空格缩进
- 使用单引号
- 添加适当的注释
命名规范
- 类名：PascalCase
- 方法名：camelCase
- 变量名：camelCase
- 常量：UPPER_SNAKE_CASE
注释
- 为复杂逻辑添加注释
- 使用 PHPDoc 注释公共方法
- 注释使用中文

测试要求

所有新功能必须包含测试
Bug 修复应包含回归测试
确保所有测试通过
保持测试覆盖率 ≥ 80%

测试类型：

单元测试：测试独立的类和方法
功能测试：测试完整的用户流程
属性测试：使用 Property-Based Testing

文档要求

如果你的更改影响到：

API：更新 docs/API_REFERENCE.md
配置：更新 docs/DEPLOYMENT.md
功能：更新 README.md 和 docs/PROJECT_OVERVIEW.md
使用方法：添加或更新相关指南

Pull Request 检查清单

在提交 PR 之前，请确保：

代码遵循项目的编码规范
所有测试通过
添加了必要的测试
更新了相关文档
提交信息清晰且符合规范
PR 描述清楚说明了更改内容
没有合并冲突

代码审查

所有提交都需要经过代码审查：

至少一位维护者批准
所有讨论都已解决
CI 检查通过

审查者会关注：

代码质量
测试覆盖率
文档完整性
性能影响
安全问题

开发环境设置

必需软件

PHP 8.1+
Composer 2.x
Node.js 18+
MySQL 8.0+ 或 PostgreSQL 13+
Redis 6.0+
Meilisearch 1.5+

本地开发

配置数据库

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=knowledge_base_dev
DB_USERNAME=root
DB_PASSWORD=

运行迁移

php artisan migrate
php artisan db:seed

启动服务

# 终端 1：Laravel 服务器
php artisan serve

# 终端 2：队列工作进程
php artisan queue:work

# 终端 3：Meilisearch
meilisearch --master-key="dev-key"

# 终端 4：前端构建（开发模式）
npm run dev

创建测试用户

php artisan make:filament-user

调试技巧

使用 Laravel Telescope（如果安装）

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

查看日志

tail -f storage/logs/laravel.log

使用 Tinker

php artisan tinker

调试队列任务

php artisan queue:work --verbose

项目结构

knowledge-base-system/
├── app/
│   ├── Filament/          # Filament 资源和页面
│   ├── Http/              # 控制器
│   ├── Jobs/              # 队列任务
│   ├── Models/            # Eloquent 模型
│   ├── Observers/         # 模型观察者
│   ├── Policies/          # 授权策略
│   └── Services/          # 业务逻辑服务
├── config/                # 配置文件
├── database/              # 迁移和种子
├── docs/                  # 项目文档
├── resources/             # 视图和前端资源
├── tests/                 # 测试文件
└── .kiro/specs/          # 功能规格文档

常见问题

如何添加新的服务类？

在 app/Services/ 创建服务类
添加必要的方法和注释
在 docs/API_REFERENCE.md 中添加文档
编写单元测试

如何添加新的 Filament 资源？

使用 Artisan 命令生成资源

php artisan make:filament-resource ModelName

配置表单和表格
添加必要的策略
更新中文翻译

如何添加新的队列任务？

创建 Job 类

php artisan make:job JobName

实现 handle() 方法
添加错误处理
编写测试

获取帮助

如果你需要帮助：

查看文档
在 Discussions 中提问
加入我们的社区频道

许可证

通过贡献代码，你同意你的贡献将在 MIT 许可证下发布。

再次感谢你的贡献！🎉

6.0 KiB Raw Permalink Blame History Unescape Escape