AutoControlCourse/README_MODULE.md

# 自动控制原理AI+数智平台 - 模块化架构说明

## 📁 项目结构

```
AutoControl/
├── app.py                    # 原始完整程序（已废弃，保留作参考）
├── app_main.py              # 新的主程序入口 ⭐ 使用这个启动
├── config.py                # 配置文件：API密钥、系统参数
├── utils.py                 # 工具函数：解析、验证、格式化
├── analysis.py              # 分析功能：时域、频域、根轨迹
├── ai_chat.py               # AI聊天：DeepSeek/Gemini接口
├── ui_styles.py             # CSS样式：480+行现代化样式
├── ui_components.py         # UI组件：横幅、知识卡片HTML
└── README_MODULE.md         # 本文件
```

## 🚀 快速开始

### 方法1：使用新的模块化主程序（推荐）

```bash
python app_main.py
```

### 方法2：使用原始完整程序

```bash
python app.py
```

## 📦 模块说明

### 1. `config.py` - 配置管理
**功能：** 集中管理所有配置常量

**内容：**
- `API_KEY`: DeepSeek API密钥
- `API_BASE_URL`: API基础URL
- `API_MODEL`: 使用的模型名称
- `DEFAULT_NUM_COEFFS`: 默认分子系数
- `DEFAULT_DEN_COEFFS`: 默认分母系数
- `TIME_SPAN`: 时间范围设置
- `SERVER_PORT`: 服务器端口
- `PROJECT_INFO`: 项目信息字典

**修改配置：**
```python
# 在 config.py 中修改
API_KEY = "你的API密钥"
SERVER_PORT = 8080  # 更改端口
```

### 2. `utils.py` - 工具函数库
**功能：** 提供数据处理和格式化工具

**主要函数：**
- `coeffs_to_latex(coeffs, var='s')`: 系数转LaTeX多项式
- `parse_coefficients(coeffs_str)`: 解析系数字符串
- `validate_transfer_function(num, den)`: 验证传递函数
- `format_complex_number(c)`: 格式化复数显示

**使用示例：**
```python
from utils import parse_coefficients, validate_transfer_function

num = parse_coefficients("1,2,3")
den = parse_coefficients("1,4,5,2")
is_valid, msg = validate_transfer_function(num, den)
```

### 3. `analysis.py` - 核心分析功能
**功能：** 控制系统的时域、频域、根轨迹分析

**主要函数：**
- `display_transfer_function(num_str, den_str)`: 显示传递函数
- `time_domain_analysis(num_str, den_str)`: 时域分析（阶跃/脉冲响应）
- `frequency_domain_analysis(num_str, den_str, K)`: 频域分析（Bode/Nyquist图）
- `root_locus_analysis(num_str, den_str, log_k)`: 根轨迹分析

**返回值：**
- 图表：matplotlib Figure对象
- 文本：性能指标、极点位置等

### 4. `ai_chat.py` - AI聊天功能
**功能：** 与DeepSeek/Gemini大模型交互

**主要函数：**
- `chat_with_ai(message, history)`: 异步聊天函数（支持流式输出）

**特点：**
- 支持对话历史记录
- 流式响应（实时显示）
- 自动错误处理
- Emoji状态指示

**系统提示词：**
```
你是一位精通自动控制原理的专家教授，擅长用通俗易懂的方式解释复杂概念。
回答要准确、专业，适当使用LaTeX公式，并举例说明。
```

### 5. `ui_styles.py` - CSS样式定义
**功能：** 提供480+行现代化CSS样式

**函数：**
- `get_custom_css()`: 返回完整CSS字符串

**样式特点：**
- 渐变背景和阴影效果
- 动画过渡效果
- 响应式设计（移动端适配）
- 暗色主题支持
- Emoji彩色显示修复

### 6. `ui_components.py` - UI组件库
**功能：** 提供HTML组件和知识卡片

**主要函数：**
- `get_main_title()`: 主标题
- `get_subtitle()`: 副标题
- `get_project_info_banner()`: 项目信息横幅
- `get_tab_tip(tab_name)`: 标签页提示
- `get_time_domain_knowledge_card()`: 时域知识卡片
- `get_frequency_domain_knowledge_card()`: 频域知识卡片
- `get_root_locus_knowledge_card()`: 根轨迹知识卡片
- `get_ai_example_questions()`: AI示例问题

### 7. `app_main.py` - 主程序入口
**功能：** 简化的主程序，组装所有模块

**代码行数：** ~350行（相比原来的2134行减少84%）

**结构：**
```python
# 导入所有模块
from config import *
from utils import *
from analysis import *
from ai_chat import *
from ui_styles import *
from ui_components import *

# 使用Gradio构建UI
with gr.Blocks(css=get_custom_css()) as demo:
    # UI布局
    # 事件绑定
    pass

# 启动服务器
demo.launch()
```

## 🎯 模块化的优势

### 1. 易于维护
- 每个模块职责单一，代码清晰
- 修改某个功能只需编辑对应模块
- 减少代码重复，提高复用性

### 2. 易于扩展
- 添加新功能：创建新模块或在现有模块添加函数
- 添加新UI：在`ui_components.py`添加新函数
- 添加新样式：在`ui_styles.py`修改CSS

### 3. 易于调试
- 模块独立，可单独测试
- 错误定位更快速
- 日志和异常处理更精确

### 4. 团队协作友好
- 不同开发者可并行工作在不同模块
- 代码冲突减少
- 代码审查更高效

## 📝 常见修改场景

### 场景1：更改API密钥
**文件：** `config.py`
```python
API_KEY = "sk-新的密钥"
```

### 场景2：添加新的分析功能
**文件：** `analysis.py`
```python
def new_analysis_function(num_str, den_str):
    """新的分析功能"""
    # 实现代码
    return figure, metrics
```

**文件：** `app_main.py`（添加UI和事件绑定）
```python
from analysis import new_analysis_function

# 添加UI组件
new_button = gr.Button("新分析")
new_output = gr.Plot()

# 绑定事件
new_button.click(fn=new_analysis_function, inputs=[...], outputs=[...])
```

### 场景3：修改知识卡片内容
**文件：** `ui_components.py`
```python
def get_time_domain_knowledge_card():
    return """
    <div class='knowledge-card'>
        <!-- 修改HTML内容 -->
    </div>
    """
```

### 场景4：调整样式颜色
**文件：** `ui_styles.py`
```python
def get_custom_css():
    return """
    .main-title {
        background: linear-gradient(135deg, #新颜色1, #新颜色2);
    }
    """
```

### 场景5：更改默认参数
**文件：** `config.py`
```python
DEFAULT_DEN_COEFFS = "1,8,15,8"  # 更改默认分母系数
SERVER_PORT = 8080               # 更改服务器端口
```

## 🔧 依赖库

```txt
gradio>=5.0.0
numpy>=1.21.0
matplotlib>=3.5.0
scipy>=1.7.0
control>=0.9.0
aiohttp>=3.8.0  # AI聊天功能
```

**安装命令：**
```bash
pip install gradio numpy matplotlib scipy control aiohttp
```

## ⚠️ 注意事项

1. **首次运行：** 需要在`config.py`中配置DeepSeek API密钥才能使用AI聊天功能
2. **端口冲突：** 如果7860端口被占用，修改`config.py`中的`SERVER_PORT`
3. **模块导入：** 所有模块必须在同一目录下
4. **Python版本：** 建议使用Python 3.8+

## 📊 代码对比

| 指标 | 原版 (app.py) | 模块化版本 |
|-----|--------------|-----------|
| 总代码行数 | 2134行 | 分散在7个文件 |
| 主程序行数 | 2134行 | 350行 (↓84%) |
| 可维护性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 可扩展性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 团队协作 | ⭐⭐ | ⭐⭐⭐⭐⭐ |

## 🎓 学习建议

1. **初学者：** 先运行`app_main.py`，熟悉整体功能
2. **进阶学习：** 阅读各模块代码，理解功能实现
3. **高级应用：** 尝试添加新功能或修改现有模块
4. **问题排查：** 参考模块注释和本文档

## 📮 联系方式

**项目负责人：** 魏鹏飞 教授  
**邮箱：** pengfeiwei@nwpu.edu.cn  
**单位：** 西北工业大学  
**资助：** 2025年校级本科生建设项目

---

**最后更新：** 2025年1月  
**版本：** 2.0 (模块化架构)