kb-web/docs/requirements.md

# 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*