初步建立帮助中心

This commit is contained in:
2026-04-12 21:33:25 +08:00
parent df6d2e7c0d
commit e22dce5183
10 changed files with 843 additions and 0 deletions
+9
View File
@@ -0,0 +1,9 @@
"""
帮助模块
提供在线文档展示功能
"""
from .routers import router as help_router
__all__ = ["help_router"]
+91
View File
@@ -0,0 +1,91 @@
"""
帮助模块路由
提供帮助文档相关的 API 端点
"""
from fastapi import APIRouter, HTTPException
from fastapi.responses import HTMLResponse, JSONResponse
from typing import List, Dict, Any
import json
from .service import help_service
from .schemas import DocItem, DocCategory
router = APIRouter(prefix="/help", tags=["help"])
@router.get("", response_class=HTMLResponse)
async def help_index():
"""
帮助中心主页
返回帮助文档的主页面
"""
return help_service.get_index_page()
@router.get("/api/docs", response_model=List[DocItem])
async def get_docs():
"""
获取文档列表
返回所有可用的帮助文档列表
"""
return help_service.get_docs_list()
@router.get("/api/docs/{doc_id}", response_model=Dict[str, Any])
async def get_doc_content(doc_id: str):
"""
获取文档内容
Args:
doc_id: 文档ID
Returns:
文档内容
"""
doc = help_service.get_doc_by_id(doc_id)
if not doc:
raise HTTPException(status_code=404, detail="文档不存在")
return doc
@router.get("/api/categories", response_model=List[DocCategory])
async def get_categories():
"""
获取文档分类
返回所有文档分类
"""
return help_service.get_categories()
@router.get("/api/categories/{category_id}/docs", response_model=List[DocItem])
async def get_docs_by_category(category_id: str):
"""
获取指定分类的文档
Args:
category_id: 分类ID
Returns:
该分类下的文档列表
"""
return help_service.get_docs_by_category(category_id)
@router.get("/api/structure", response_model=List[Dict[str, Any]])
async def get_structure():
"""
获取帮助中心结构配置
Returns:
帮助中心的结构配置
"""
try:
with open("apps/common/help/structure.json", "r", encoding="utf-8") as f:
structure = json.load(f)
return structure
except Exception as e:
raise HTTPException(status_code=500, detail=f"无法加载结构配置: {str(e)}")
+29
View File
@@ -0,0 +1,29 @@
"""
帮助模块数据模型
定义帮助文档相关的数据结构
"""
from pydantic import BaseModel
from typing import List, Optional
class DocItem(BaseModel):
"""文档项模型"""
id: str
title: str
category_id: str
category_name: str
summary: Optional[str] = None
content: Optional[str] = None
created_at: Optional[str] = None
updated_at: Optional[str] = None
class DocCategory(BaseModel):
"""文档分类模型"""
id: str
name: str
description: Optional[str] = None
icon: Optional[str] = None
order: int = 0
+155
View File
@@ -0,0 +1,155 @@
"""
帮助模块服务
处理帮助文档相关的业务逻辑
"""
from typing import List, Dict, Any, Optional
from .schemas import DocItem, DocCategory
class HelpService:
"""帮助服务类"""
def __init__(self):
"""初始化帮助服务"""
# 模拟数据
self._categories = [
DocCategory(
id="1",
name="产品介绍",
description="关于产品的基本介绍和功能说明",
icon="info",
order=1
),
DocCategory(
id="2",
name="使用指南",
description="产品的使用方法和操作步骤",
icon="book",
order=2
),
DocCategory(
id="3",
name="API文档",
description="API接口的详细说明和使用示例",
icon="code",
order=3
),
DocCategory(
id="4",
name="常见问题",
description="常见问题的解答和解决方案",
icon="question",
order=4
)
]
self._docs = [
DocItem(
id="1",
title="产品概述",
category_id="1",
category_name="产品介绍",
summary="了解产品的基本功能和特点",
content="<h2>产品概述</h2><p>本产品是一个功能强大的系统,提供了多种实用功能...</p>",
created_at="2026-01-01",
updated_at="2026-01-01"
),
DocItem(
id="2",
title="快速开始",
category_id="2",
category_name="使用指南",
summary="快速上手产品的基本操作",
content="<h2>快速开始</h2><p>1. 注册账号<br>2. 登录系统<br>3. 开始使用...</p>",
created_at="2026-01-02",
updated_at="2026-01-02"
),
DocItem(
id="3",
title="API接口说明",
category_id="3",
category_name="API文档",
summary="API接口的详细参数和使用方法",
content="<h2>API接口说明</h2><p>本系统提供了丰富的API接口,支持多种操作...</p>",
created_at="2026-01-03",
updated_at="2026-01-03"
),
DocItem(
id="4",
title="常见问题解答",
category_id="4",
category_name="常见问题",
summary="常见问题的详细解答",
content="<h2>常见问题解答</h2><p>Q: 如何重置密码?<br>A: 点击忘记密码,按照提示操作...</p>",
created_at="2026-01-04",
updated_at="2026-01-04"
)
]
def get_index_page(self) -> str:
"""
获取帮助中心主页
Returns:
HTML页面内容
"""
try:
with open("static/help/index.html", "r", encoding="utf-8") as f:
return f.read()
except Exception as e:
return f"<h1>错误</h1><p>无法加载帮助页面: {str(e)}</p>"
def get_docs_list(self) -> List[DocItem]:
"""
获取文档列表
Returns:
文档列表
"""
return self._docs
def get_doc_by_id(self, doc_id: str) -> Optional[Dict[str, Any]]:
"""
根据ID获取文档
Args:
doc_id: 文档ID
Returns:
文档详情
"""
for doc in self._docs:
if doc.id == doc_id:
return doc.model_dump()
return None
def get_categories(self) -> List[DocCategory]:
"""
获取分类列表
Returns:
分类列表
"""
return self._categories
def get_docs_by_category(self, category_id: str) -> List[DocItem]:
"""
根据分类获取文档
Args:
category_id: 分类ID
Returns:
该分类下的文档列表
"""
return [doc for doc in self._docs if doc.category_id == category_id]
# 实例化服务
try:
help_service = HelpService()
except Exception as e:
print(f"初始化帮助服务失败: {e}")
help_service = None
+70
View File
@@ -0,0 +1,70 @@
[
{
"name": "首页",
"groups": [
{
"header": "欢迎使用帮助中心",
"description": "这里提供了产品的详细文档和使用指南,帮助您快速上手",
"children": [
{
"name": "产品概述",
"url": "https://www.baidu.com",
"icon": "file-text",
"description": "了解产品的基本功能和特点,包括系统架构、核心功能和应用场景",
"updateAt": "2026-01-01"
}
]
}
]
},
{
"name": "文档",
"groups": [
{
"header": "文档",
"description": "接口文档",
"children": [
{
"name": "接口说明",
"url": "https://d6ed58d2b2f5efe6.share.mingdao.net/public/view/69a4facb104c17463048d921",
"icon": "📄",
"description": "接口说明文档",
"updateAt": "2026-03-01"
},
{
"name": "数据对接指引",
"url": "https://docs.qq.com/aio/DWGJBSXdMRHJnb1ZL",
"icon": "📄",
"description": "数据对接指引文档",
"updateAt": "2026-03-01"
},
{
"name": "接口规范",
"url": "https://docs.qq.com/aio/DWGR1UnNhZFhNbktV",
"icon": "📄",
"description": "接口规范文档",
"updateAt": "2026-03-01"
}
]
}
]
},
{
"name": "准备工作",
"groups": [
{
"header": "用友",
"description": "用友系列ERP准备工作",
"children": [
{
"name": "T+",
"url": "https://docs.qq.com/aio/DWEZvekZLRmdtVUJ5",
"icon": "📄",
"description": "用友T+对接前,ERP方的准备事项",
"updateAt": "2026-03-01"
}
]
}
]
}
]
+2
View File
@@ -3,6 +3,7 @@ from fastapi.responses import HTMLResponse
from apps.io_api.routers import rt as io_rt
from apps.data_opt.routers import rt as do_rt
from apps.common.monitor.routers import router as monitor_rt
from apps.common.help.routers import router as help_rt
router = APIRouter()
@@ -10,6 +11,7 @@ def register_routes(app):
app.include_router(io_rt, prefix="/api", tags=[])
app.include_router(do_rt, prefix="/do", tags=[])
app.include_router(monitor_rt, tags=["monitor"])
app.include_router(help_rt, tags=["help"])
@app.get("/monitor", response_class=HTMLResponse, include_in_schema=False)
+1
View File
@@ -1,4 +1,5 @@
@echo off
title MyAPS API SERVER
:: 配置变量
set "PS_SCRIPT=%~dp0run.ps1"
set "ENV_FILE=%~dp0.env"
+205
View File
@@ -0,0 +1,205 @@
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
background-color: #f5f7fa;
color: #333;
}
.header {
background-color: #1E88E5;
color: white;
padding: 15px 20px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
position: sticky;
top: 0;
z-index: 1000;
}
.header-content {
display: flex;
justify-content: flex-start;
align-items: center;
max-width: 1200px;
margin: 0 auto;
}
.nav-menu {
margin-left: 40px;
}
.header h1 {
font-size: 20px;
font-weight: 600;
}
.nav-menu {
display: flex;
list-style: none;
}
.nav-item {
margin-left: 20px;
}
.nav-link {
color: white;
text-decoration: none;
font-size: 14px;
padding: 8px 12px;
border-radius: 4px;
transition: all 0.3s ease;
}
.nav-link:hover {
background-color: rgba(255, 255, 255, 0.1);
}
.nav-link.active {
background-color: rgba(255, 255, 255, 0.2);
}
.main-content {
max-width: 1200px;
margin: 0 auto;
padding: 40px 20px;
}
.content-header {
margin-bottom: 30px;
}
.content-header h2 {
font-size: 24px;
font-weight: 600;
color: #333;
}
.content-header p {
color: #666;
margin-top: 10px;
}
.doc-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
gap: 20px;
}
.doc-card {
background-color: white;
border-radius: 8px;
padding: 20px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
transition: all 0.3s ease;
text-align: center;
border: 1px solid #e0e0e0;
}
.doc-card:hover {
box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
transform: translateY(-2px);
}
.doc-icon {
width: 48px;
height: 48px;
background-color: #E3F2FD;
border-radius: 8px;
display: flex;
align-items: center;
justify-content: center;
margin: 0 auto 15px;
font-size: 24px;
color: #1E88E5;
}
.doc-card h3 {
font-size: 16px;
font-weight: 600;
margin-bottom: 10px;
color: #333;
}
.doc-card p {
color: #666;
font-size: 14px;
line-height: 1.5;
}
.doc-meta {
margin-top: 15px;
font-size: 12px;
color: #999;
}
.group-container {
margin-bottom: 40px;
}
.group-header {
margin-bottom: 20px;
}
.group-header h3 {
font-size: 18px;
font-weight: 600;
color: #333;
margin-bottom: 5px;
}
.group-header p {
color: #666;
font-size: 14px;
}
.group-content {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
gap: 20px;
}
.doc-card h4 {
font-size: 16px;
font-weight: 600;
margin-bottom: 10px;
color: #333;
}
.empty-state {
text-align: center;
padding: 80px 0;
color: #999;
}
.empty-state i {
font-size: 48px;
margin-bottom: 20px;
opacity: 0.5;
}
@media (max-width: 768px) {
.header-content {
flex-direction: column;
align-items: flex-start;
}
.nav-menu {
margin-top: 15px;
flex-wrap: wrap;
}
.nav-item {
margin-left: 0;
margin-right: 15px;
margin-bottom: 10px;
}
.doc-grid {
grid-template-columns: 1fr;
}
}
+199
View File
@@ -0,0 +1,199 @@
/**
* 帮助中心页面脚本
*/
// 页面加载完成后执行
document.addEventListener('DOMContentLoaded', function() {
// 初始化页面
initHelpPage();
});
/**
* 初始化帮助页面
*/
async function initHelpPage() {
try {
// 加载结构配置文件
const structure = await loadStructure();
// 动态生成导航菜单
generateNavMenu(structure);
// 动态生成内容
generateContent(structure[0]); // 默认显示第一个菜单项的内容
console.log('Help page initialized');
} catch (error) {
console.error('Failed to initialize help page:', error);
}
}
/**
* 加载结构配置文件
*/
async function loadStructure() {
try {
const response = await fetch('/help/api/structure');
if (!response.ok) {
throw new Error('Failed to load structure');
}
return await response.json();
} catch (error) {
console.error('Failed to load structure:', error);
// 返回默认结构作为 fallback
return [
{
"name": "首页",
"header": "欢迎使用帮助中心",
"description": "这里提供了产品的详细文档和使用指南,帮助您快速上手",
"children": [
{
"name": "产品概述",
"url": "https://www.baidu.com",
"icon": "file-text",
"description": "了解产品的基本功能和特点,包括系统架构、核心功能和应用场景",
"updateAt": "2026-01-01"
}
]
}
];
}
}
/**
* 动态生成导航菜单
*/
function generateNavMenu(structure) {
const navMenu = document.querySelector('.nav-menu');
if (!navMenu) return;
// 清空现有菜单
navMenu.innerHTML = '';
// 生成菜单项
structure.forEach((item, index) => {
const li = document.createElement('li');
li.className = 'nav-item';
const a = document.createElement('a');
a.href = '#';
a.className = `nav-link ${index === 0 ? 'active' : ''}`;
a.textContent = item.name;
a.addEventListener('click', (event) => {
event.preventDefault();
handleNavClick(event, item);
});
li.appendChild(a);
navMenu.appendChild(li);
});
}
/**
* 导航菜单点击事件处理
*/
function handleNavClick(event, menuItem) {
// 移除所有活动状态
document.querySelectorAll('.nav-link').forEach(link => {
link.classList.remove('active');
});
// 添加活动状态到当前点击的链接
event.target.classList.add('active');
// 生成对应内容
generateContent(menuItem);
}
/**
* 动态生成内容
*/
function generateContent(menuItem) {
const contentHeader = document.querySelector('.content-header');
const docGrid = document.querySelector('.doc-grid');
if (!contentHeader || !docGrid) return;
// 清空内容标题,避免重复显示导航栏中的标题
contentHeader.innerHTML = '';
// 清空现有内容
docGrid.innerHTML = '';
// 生成分组内容
if (menuItem.groups && menuItem.groups.length > 0) {
menuItem.groups.forEach(group => {
// 创建分组容器
const groupContainer = document.createElement('div');
groupContainer.className = 'group-container';
// 添加分组标题和描述
groupContainer.innerHTML = `
<div class="group-header">
<h3>${group.header}</h3>
<p>${group.description}</p>
</div>
<div class="group-content">
</div>
`;
// 获取分组内容容器
const groupContent = groupContainer.querySelector('.group-content');
// 生成文档卡片
if (group.children && group.children.length > 0) {
group.children.forEach(child => {
const card = document.createElement('div');
card.className = 'doc-card';
// 根据icon值生成对应的图标
const iconMap = {
'file-text': '📋',
'rocket': '🚀',
'code': '💻',
'help-circle': '❓'
};
const icon = iconMap[child.icon] || child.icon || '📄';
card.innerHTML = `
<div class="doc-icon">${icon}</div>
<h4>${child.name}</h4>
<p>${child.description}</p>
<div class="doc-meta">
<span>更新时间: ${child.updateAt}</span>
</div>
`;
// 添加点击事件,跳转到对应URL
if (child.url) {
card.style.cursor = 'pointer';
card.addEventListener('click', () => {
// 尝试创建一个更像弹窗的窗口,尽量最小化地址栏显示
window.open(child.url, '_blank', 'width=1000,height=700,toolbar=no,location=yes,menubar=no,scrollbars=yes,resizable=yes');
});
}
groupContent.appendChild(card);
});
} else {
// 无内容时显示空状态
groupContent.innerHTML = `
<div class="empty-state">
<i>📄</i>
<p>暂无文档</p>
</div>
`;
}
docGrid.appendChild(groupContainer);
});
} else {
// 无内容时显示空状态
docGrid.innerHTML = `
<div class="empty-state">
<i>📄</i>
<p>暂无内容</p>
</div>
`;
}
}
+82
View File
@@ -0,0 +1,82 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>帮助中心</title>
<link rel="stylesheet" href="/static/help/help.css">
</head>
<body>
<!-- 顶部菜单栏 -->
<header class="header">
<div class="header-content">
<h1>帮助中心</h1>
<ul class="nav-menu">
<li class="nav-item">
<a href="#" class="nav-link active">首页</a>
</li>
<li class="nav-item">
<a href="#" class="nav-link">产品介绍</a>
</li>
<li class="nav-item">
<a href="#" class="nav-link">使用指南</a>
</li>
<li class="nav-item">
<a href="#" class="nav-link">API文档</a>
</li>
<li class="nav-item">
<a href="#" class="nav-link">常见问题</a>
</li>
</ul>
</div>
</header>
<!-- 主内容区 -->
<main class="main-content">
<div class="content-header">
<h2>欢迎使用帮助中心</h2>
<p>这里提供了产品的详细文档和使用指南,帮助您快速上手</p>
</div>
<div class="doc-grid">
<div class="doc-card">
<div class="doc-icon">📋</div>
<h3>产品概述</h3>
<p>了解产品的基本功能和特点,包括系统架构、核心功能和应用场景</p>
<div class="doc-meta">
<span>更新时间: 2026-01-01</span>
</div>
</div>
<div class="doc-card">
<div class="doc-icon">🚀</div>
<h3>快速开始</h3>
<p>快速上手产品的基本操作,包括账号注册、登录和基本功能使用</p>
<div class="doc-meta">
<span>更新时间: 2026-01-02</span>
</div>
</div>
<div class="doc-card">
<div class="doc-icon">💻</div>
<h3>API接口说明</h3>
<p>API接口的详细参数和使用方法,包括请求格式、响应格式和示例代码</p>
<div class="doc-meta">
<span>更新时间: 2026-01-03</span>
</div>
</div>
<div class="doc-card">
<div class="doc-icon"></div>
<h3>常见问题解答</h3>
<p>常见问题的详细解答,包括账号问题、功能使用问题和故障排除</p>
<div class="doc-meta">
<span>更新时间: 2026-01-04</span>
</div>
</div>
</div>
</main>
<script src="/static/help/help.js"></script>
</body>
</html>