\documentclass[12pt, a4paper]{article}

% ========== 基础包 ==========
\usepackage[UTF8]{ctex}             % 中文支持
\usepackage[margin=2.5cm]{geometry} % 页边距
\usepackage{titlesec}               % 章节标题格式
\usepackage{titletoc}               % 目录格式
\usepackage{fancyhdr}               % 页眉页脚
\usepackage{listings}               % 代码块
\usepackage{xcolor}                 % 颜色
\usepackage{graphicx}               % 图片
\usepackage{amsmath}                % 数学公式
\usepackage{amssymb}                % 数学符号
\usepackage{booktabs}               % 表格
\usepackage{enumitem}               % 列表格式
\usepackage{tcolorbox}              % 彩色盒子
\usepackage{fontawesome5}           % 图标
\usepackage{setspace}               % 行距
\usepackage{hyperref}               % 超链接

% ========== 页面设置 ==========
\onehalfspacing

% ========== 可修改的文档信息 ==========
\newcommand{\doctitle}{XXXX技术文档}
\newcommand{\docsubtitle}{XXXX系统设计与实现}
\newcommand{\projectname}{XXXX项目}
\newcommand{\docauthor}{XXXX}
\newcommand{\docversion}{v1.0}
\newcommand{\docdescription}{本文档用于说明XXXX项目的设计、实现、测试及维护方法。}

% ========== 页眉页脚 ==========
\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{\small \doctitle}
\fancyhead[R]{\small \leftmark}
\fancyfoot[C]{\thepage}
\renewcommand{\headrulewidth}{0.4pt}

% ========== 颜色设置 ==========
\definecolor{codebg}{RGB}{245, 245, 245}
\definecolor{codeframe}{RGB}{200, 200, 200}
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.58,0,0.82}

% ========== 超链接设置 ==========
\hypersetup{
    colorlinks=true,
    linkcolor=blue!70!black,
    urlcolor=blue!70!black,
    citecolor=green!60!black,
    bookmarks=true,
    bookmarksnumbered=true,
    pdftitle={\doctitle},
    pdfauthor={\docauthor}
}

% ========== 代码块设置 ==========
\lstdefinestyle{pythonstyle}{
    backgroundcolor=\color{codebg},
    commentstyle=\color{codegreen},
    keywordstyle=\color{blue}\bfseries,
    numberstyle=\tiny\color{codegray},
    stringstyle=\color{codepurple},
    basicstyle=\ttfamily\footnotesize,
    breakatwhitespace=false,
    breaklines=true,
    captionpos=b,
    keepspaces=true,
    numbers=left,
    numbersep=5pt,
    showspaces=false,
    showstringspaces=false,
    showtabs=false,
    tabsize=4,
    frame=single,
    rulecolor=\color{codeframe},
    language=Python
}

\lstdefinestyle{bashstyle}{
    backgroundcolor=\color{codebg},
    basicstyle=\ttfamily\footnotesize,
    breaklines=true,
    frame=single,
    rulecolor=\color{codeframe},
    language=bash,
    commentstyle=\color{codegreen},
    keywordstyle=\color{blue}
}

\lstset{style=pythonstyle}

% ========== 彩色盒子样式 ==========
\tcbuselibrary{skins, breakable}

\newtcolorbox{qabox}[2][]{
    enhanced,
    breakable,
    colback=blue!5!white,
    colframe=blue!60!black,
    fonttitle=\bfseries,
    title={Q: #2},
    #1
}

\newtcolorbox{answerbox}[1][]{
    enhanced,
    breakable,
    colback=green!5!white,
    colframe=green!60!black,
    leftrule=4pt,
    #1
}

\newtcolorbox{filebox}[2][]{
    enhanced,
    breakable,
    colback=gray!10!white,
    colframe=gray!60!black,
    fonttitle=\bfseries\ttfamily,
    title={\faFile\ #2},
    #1
}

% ========== 章节标题格式 ==========
\titleformat{\section}
    {\Large\bfseries\color{blue!70!black}}
    {\thesection}{1em}{}
    [\titlerule]

\titleformat{\subsection}
    {\large\bfseries\color{blue!50!black}}
    {\thesubsection}{1em}{}

\titleformat{\subsubsection}
    {\normalsize\bfseries}
    {\thesubsubsection}{1em}{}

\begin{document}

% ========== 封面 ==========
\begin{titlepage}
    \centering
    \vspace*{3cm}

    {\Huge\bfseries \doctitle\\[0.5em]
    \Large \docsubtitle}

    \vspace{2cm}
    \rule{\linewidth}{0.5mm}
    \vspace{1cm}

    {\large
    \begin{tabular}{ll}
        \textbf{项目名称：} & \projectname \\[0.5em]
        \textbf{作者：}     & \docauthor \\[0.5em]
        \textbf{日期：}     & \today \\[0.5em]
        \textbf{版本：}     & \docversion \\
    \end{tabular}
    }

    \vspace{1cm}
    \rule{\linewidth}{0.5mm}

    \vfill
    {\small \docdescription}
\end{titlepage}

% ========== 目录 ==========
\tableofcontents
\newpage

% ============================================================
% 使用时可直接修改下面各章节，也可以复制或删除任意示例
% ============================================================
\section{文档概述}

\subsection{编写目的}
XXXX：说明本文档解决什么问题、面向哪些读者，以及预期达到的目标。

\subsection{项目背景}
XXXX：简要介绍项目来源、应用场景和当前状态。

\subsection{术语说明}
\begin{table}[htbp]
    \centering
    \caption{术语说明示例}
    \begin{tabular}{ll}
        \toprule
        \textbf{术语} & \textbf{说明} \\
        \midrule
        XXXX & 填写术语的完整名称及含义 \\
        XXXX & 填写缩写、单位或专有概念 \\
        \bottomrule
    \end{tabular}
\end{table}

\section{系统设计}

\subsection{总体架构}
XXXX：描述系统组成、模块关系、数据流和部署方式。

\subsection{处理流程}
\begin{enumerate}
    \item XXXX：填写流程的第一步。
    \item XXXX：填写流程的第二步。
    \item XXXX：填写流程的第三步。
\end{enumerate}

\subsection{接口说明}
\begin{table}[htbp]
    \centering
    \caption{接口说明示例}
    \begin{tabular}{llll}
        \toprule
        \textbf{接口} & \textbf{输入} & \textbf{输出} & \textbf{说明} \\
        \midrule
        XXXX & XXXX & XXXX & 填写接口用途 \\
        \bottomrule
    \end{tabular}
\end{table}

\section{程序文件说明}

\subsection{核心文件}
\begin{filebox}{\texttt{xxxx.py}}
\textbf{功能：} XXXX：填写文件的主要作用。\\[0.5em]

\textbf{主要类/函数：}
\begin{itemize}
    \item \texttt{XXXX} —— 填写类或函数的作用
    \item \texttt{xxxx()} —— 填写输入、输出及处理逻辑
\end{itemize}

\textbf{输入：} XXXX：填写数据类型、单位和维度。\\

\textbf{输出：} XXXX：填写返回值、保存文件或执行结果。\\

\textbf{依赖：} XXXX：填写库、环境或外部服务。
\end{filebox}

\subsection{目录结构}
\begin{lstlisting}[style=bashstyle]
project/
|-- src/            # XXXX：源代码
|-- config/         # XXXX：配置文件
|-- tests/          # XXXX：测试代码
`-- README.md       # XXXX：使用说明
\end{lstlisting}

\section{关键方法与原理}

\subsection{方法概述}
XXXX：介绍核心方法的基本思想、适用条件和主要优势。

\subsection{数学模型}
XXXX：在正文中解释公式中各符号的物理意义。例如：
\begin{equation}
    y = f(x;\theta)
    \label{eq:example}
\end{equation}
其中，$x$ 表示XXXX，$y$ 表示XXXX，$\theta$ 表示XXXX。

\subsection{算法步骤}
\begin{enumerate}
    \item XXXX：准备输入数据。
    \item XXXX：执行核心计算。
    \item XXXX：输出并检查结果。
\end{enumerate}

\section{实现说明}

\subsection{环境配置}
\begin{lstlisting}[style=bashstyle]
# XXXX：填写环境创建或依赖安装命令
python --version
pip install xxxx
\end{lstlisting}

\subsection{核心代码}
\begin{lstlisting}[caption={XXXX代码示例}]
def main(input_data):
    """XXXX：填写函数说明。"""
    result = input_data
    return result
\end{lstlisting}

\subsection{配置参数}
\begin{table}[htbp]
    \centering
    \caption{关键参数说明}
    \begin{tabular}{llll}
        \toprule
        \textbf{参数} & \textbf{默认值} & \textbf{单位} & \textbf{说明} \\
        \midrule
        \texttt{xxxx} & XXXX & XXXX & 填写参数作用 \\
        \texttt{xxxx} & XXXX & XXXX & 填写取值范围 \\
        \bottomrule
    \end{tabular}
\end{table}

\section{测试与结果}

\subsection{测试环境}
XXXX：填写硬件、操作系统、软件版本和测试数据。

\subsection{测试方法}
XXXX：填写测试步骤、对照条件和评价指标。

\subsection{结果分析}
\begin{table}[htbp]
    \centering
    \caption{测试结果示例}
    \begin{tabular}{lll}
        \toprule
        \textbf{测试项} & \textbf{结果} & \textbf{结论} \\
        \midrule
        XXXX & XXXX & 通过/不通过 \\
        \bottomrule
    \end{tabular}
\end{table}

% 插入图片时取消下面代码的注释，并上传对应图片文件
% \begin{figure}[htbp]
%     \centering
%     \includegraphics[width=0.8\linewidth]{images/xxxx.png}
%     \caption{XXXX：填写图片说明}
%     \label{fig:example}
% \end{figure}

\section{常见问题}

\begin{qabox}{XXXX：填写常见问题？}
\begin{answerbox}
XXXX：说明问题现象、产生原因、排查步骤和解决方法。
\end{answerbox}
\end{qabox}

\section{后续规划}

\subsection{待完成事项}
\begin{itemize}
    \item XXXX：填写待实现功能。
    \item XXXX：填写待优化问题。
    \item XXXX：填写预计完成时间。
\end{itemize}

\subsection{版本记录}
\begin{table}[htbp]
    \centering
    \caption{版本记录}
    \begin{tabular}{llll}
        \toprule
        \textbf{版本} & \textbf{日期} & \textbf{作者} & \textbf{修改内容} \\
        \midrule
        v1.0 & \today & XXXX & 创建基础文档 \\
        \bottomrule
    \end{tabular}
\end{table}

\end{document}