From b5d3a6aaf3193dcb1c339bfb4298a89a8e5ca776 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Sun, 15 Feb 2026 21:47:25 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E9=9C=80=E6=B1=82=E4=B8=8E?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 项目概述和目标用户 - 功能需求（用户认证、文档管理、元数据展示） - 技术架构（目录结构、数据库设计） - 页面设计说明 - CI/CD 流程 - 样式规范（色彩、字体） - 安全设计 - 扩展计划 - 维护说明 --- .gitignore | 1 + docs/requirements.md | 351 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 352 insertions(+) create mode 100644 docs/requirements.md diff --git a/.gitignore b/.gitignore index 29239f5..4ef9d7d 100644 --- a/.gitignore +++ b/.gitignore @@ -29,3 +29,4 @@ config.php !/tests/ !/src/ !/.gitea/ +!/docs/ diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..5382f49 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,351 @@ +# kb-web 需求与设计文档 + +## 1. 项目概述 + +### 1.1 项目名称 +kb-web（Knowledge Base Web）- 知识库网页系统 + +### 1.2 项目描述 +kb-web 是一个基于 PHP 的知识库管理系统，用于展示和管理用户的知识库内容。系统支持从多种平台（Bilibili、YouTube、知乎等）采集的内容，并提供统一的浏览和搜索界面。 + +### 1.3 目标用户 +- 个人用户：管理自己的知识库 +- 团队用户：共享和管理团队知识资产 + +--- + +## 2. 功能需求 + +### 2.1 用户认证 + +| 功能 | 描述 | +|------|------| +| 用户登录 | 用户名 + 密码登录 | +| 会话管理 | 基于 PHP Session 的会话管理 | +| 登出功能 | 安全退出系统 | + +### 2.2 文档管理 + +| 功能 | 描述 | +|------|------| +| 文档列表 | 分页展示所有文档 | +| 文档搜索 | 全文搜索文档内容 | +| 文档查看 | 在线阅读文档内容 | +| 目录结构 | 支持子目录分类展示 | + +### 2.3 元数据展示 + +| 元数据 | 说明 | +|--------|------| +| 标题 | 文档标题（从 YAML front matter 提取） | +| 作者 | 内容作者 | +| 发布时间 | 原始内容发布时间 | +| 平台 | 来源平台（Bilibili、YouTube、知乎等） | +| 标签 | 内容标签 | +| 时长 | 视频时长（仅视频类型） | +| 类型 | 文章 / 视频 | +| 源链接 | 原始内容链接 | + +### 2.4 界面功能 + +| 功能 | 描述 | +|------|------| +| 响应式设计 | 支持桌面和移动设备 | +| 暗色主题 | 科技感暗色界面 | +| 搜索高亮 | 搜索结果关键词高亮 | +| Markdown 渲染 | 支持基本 Markdown 语法 | + +--- + +## 3. 技术架构 + +### 3.1 技术栈 + +| 层级 | 技术 | +|------|------| +| 前端 | HTML5, CSS3, JavaScript | +| 后端 | PHP 8.0+ | +| 数据库 | MySQL 5.7+ | +| Web 服务器 | Nginx | +| 部署 | Git + CI/CD (Gitea Actions) | + +### 3.2 目录结构 + +``` +kb-web/ +├── index.php # 登录页 +├── dashboard.php # 文档列表页 +├── view.php # 文档查看页 +├── config.php # 配置文件（不纳入版本控制） +├── config.test.php # 测试环境配置模板 +├── style.css # 样式文件 +├── logout.php # 登出处理 +├── add_user.php # 用户添加 +├── init.sql # 数据库初始化脚本 +├── docs/ # 文档目录 +│ └── requirements.md +├── deploy/ # 部署脚本 +│ ├── deploy.sh +│ ├── setup-server.sh +│ └── webhook-receiver.php +├── tests/ # 测试文件 +│ ├── bootstrap.php +│ ├── Unit/ +│ └── Feature/ +├── .gitea/ # CI/CD 配置 +│ └── workflows/ +│ └── ci.yml +├── .gitignore +├── composer.json +├── phpunit.xml +└── README.md +``` + +### 3.3 数据库设计 + +#### 用户表 (users) + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | INT | 主键，自增 | +| username | VARCHAR(50) | 用户名，唯一 | +| password_hash | VARCHAR(255) | 密码哈希 | +| created_at | TIMESTAMP | 创建时间 | + +### 3.4 文件存储结构 + +``` +用户目录/ +├── 用户名1/ +│ ├── analyzed/ # 分析后的 Markdown 文件 +│ ├── metadata/ # 元数据 JSON 文件 +│ ├── content/ # 原始内容文件 +│ └── pending/ # 待处理文件 +└── 用户名2/ + └── ... +``` + +--- + +## 4. 页面设计 + +### 4.1 登录页 (index.php) + +**功能：** +- 用户名密码输入 +- 错误提示 +- 登录验证 + +**设计特点：** +- 居中登录框 +- 渐变背景 + 旋转光效 +- 玻璃拟态卡片 +- 品牌标题 "知识库" + +### 4.2 文档列表页 (dashboard.php) + +**功能：** +- 搜索栏 +- 文档统计 +- 文档卡片列表 +- 用户信息显示 + +**卡片信息展示：** +- 平台图标 +- 类型图标 +- 标题 +- 作者、发布时间、平台、时长 +- 标签（最多5个） +- 源链接 +- 概述（前两行） + +### 4.3 文档查看页 (view.php) + +**功能：** +- 返回列表 +- 元数据卡片 +- Markdown 内容渲染 +- 搜索高亮 + +**元数据卡片：** +- 作者 +- 发布时间 +- 平台（彩色徽章） +- 时长 +- 类型 +- 源链接 +- 标签列表 + +--- + +## 5. CI/CD 流程 + +### 5.1 部署流程 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ feature/* 分支 push │ +│ │ │ +│ ▼ │ +│ 自动部署到测试环境 (http://micecola.top:8081) │ +│ │ │ +│ ▼ │ +│ 运行测试 │ +│ │ 通过 │ +│ ▼ │ +│ 自动合并到 main │ +│ │ │ +│ ▼ │ +│ ⏸️ 等待手动确认... │ +│ │ │ +│ ▼ 手动触发 │ +│ 部署到正式环境 (http://micecola.top) │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 5.2 环境配置 + +| 环境 | 域名 | 目录 | 触发方式 | +|------|------|------|----------| +| 测试 | http://micecola.top:8081 | /www/wwwroot/kb-web-test | 自动 | +| 正式 | http://micecola.top | /www/wwwroot/kb-web | 手动 | + +### 5.3 部署特性 + +- ✅ 配置文件保护（config.php 不被覆盖） +- ✅ 自动备份（保留最近5个版本） +- ✅ 版本回滚支持 +- ✅ 环境隔离 + +--- + +## 6. 样式规范 + +### 6.1 色彩系统 + +| 名称 | 色值 | 用途 | +|------|------|------| +| 背景深色 | #0a0e17 | 页面背景 | +| 背景表面 | #111827 | 卡片背景 | +| 强调色-青 | #38bdf8 | 主色调、链接 | +| 强调色-紫 | #a855f7 | 辅助强调 | +| 强调色-绿 | #22c55e | 成功状态 | +| 文字主色 | #f1f5f9 | 主要文字 | +| 文字次色 | #94a3b8 | 次要文字 | + +### 6.2 平台颜色 + +| 平台 | 色值 | +|------|------| +| Bilibili | #fb7299 | +| YouTube | #ff0000 | +| 知乎 | #0084ff | +| 微信 | #07c160 | + +### 6.3 字体 + +| 用途 | 字体 | +|------|------| +| 正文 | Space Grotesk | +| 代码 | JetBrains Mono | + +--- + +## 7. 安全设计 + +### 7.1 已实现 + +| 安全措施 | 说明 | +|----------|------| +| 密码哈希 | 使用 password_hash() | +| SQL 注入防护 | PDO 预处理语句 | +| XSS 防护 | htmlspecialchars() | +| 目录遍历防护 | 路径检查 | +| 会话管理 | PHP Session | + +### 7.2 待加强 + +- [ ] CSRF 防护 +- [ ] 登录失败次数限制 +- [ ] HTTPS 强制 +- [ ] 密码强度验证 + +--- + +## 8. 扩展计划 + +### 8.1 短期计划 + +- [ ] 分页功能 +- [ ] 标签筛选 +- [ ] 收藏功能 +- [ ] 阅读进度记录 + +### 8.2 长期计划 + +- [ ] 多用户协作 +- [ ] 权限管理 +- [ ] API 接口 +- [ ] 移动端 App +- [ ] 全文搜索优化（Elasticsearch） + +--- + +## 9. 依赖项目 + +### 9.1 关联仓库 + +| 仓库 | 说明 | +|------|------| +| kb-skills | 内容处理技能模块 | +| knowledge-base | 知识库内容存储 | + +### 9.2 知识库同步 + +knowledge-base 仓库独立部署，自动同步到用户目录： +- 测试环境：/www/wwwroot/kb-web-test/zhangqing/ +- 正式环境：/www/wwwroot/kb-web/zhangqing/ + +--- + +## 10. 维护说明 + +### 10.1 日志位置 + +| 日志 | 路径 | +|------|------| +| Nginx 访问日志 | /www/wwwlogs/micecola.top.log | +| Nginx 错误日志 | /www/wwwlogs/micecola.top.error.log | +| 部署日志 | /var/log/kb-web-deploy.log | +| 备份目录 | /www/backup/kb-web/ | + +### 10.2 常用命令 + +```bash +# 手动部署测试环境 +cd /www/wwwroot/kb-web-test && git pull origin main + +# 手动部署正式环境 +cd /www/wwwroot/kb-web && git pull origin main + +# 查看备份 +ls /www/backup/kb-web/ + +# 回滚到备份版本 +tar -xzf /www/backup/kb-web/backup_XXX.tar.gz -C /www/wwwroot/kb-web/ +``` + +--- + +## 11. 版本历史 + +| 版本 | 日期 | 变更内容 | +|------|------|----------| +| 1.0.0 | 2026-02-13 | 初始版本，基础功能 | +| 1.1.0 | 2026-02-15 | 暗色科技感风格改造 | +| 1.2.0 | 2026-02-15 | CI/CD 自动部署 | +| 1.3.0 | 2026-02-15 | 元数据展示优化，标签支持 | + +--- + +*文档最后更新：2026-02-15*