添加需求与设计文档

- 项目概述和目标用户 - 功能需求（用户认证、文档管理、元数据展示） - 技术架构（目录结构、数据库设计） - 页面设计说明 - CI/CD 流程 - 样式规范（色彩、字体） - 安全设计 - 扩展计划 - 维护说明
2026-02-15 21:47:25 +08:00
parent cd38932eb0
commit b5d3a6aaf3
2 changed files with 352 additions and 0 deletions
@@ -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*