# Copilot / AI Agent 使用说明（精简） 本文件面向 AI 编码代理，提供该项目的「可操作」知识：架构概览、关键文件、常见数据形态、运行/调试指令与代码风格约定。 **High-level Architecture**: 本项目是一个基于 Python + Tkinter 的桌面应用。 - **UI 层**: `src/gui/`（`main_window.py`, `components.py`, `styles.py`），使用 `ttkbootstrap` 主题。 - **业务/算法层**: `src/core/`（`data_manager.py`, `random_selector.py`, `animation_engine.py`）。`DataManager` 是中间协调层。 - **工具/基础层**: `src/utils/`（`database.py`, `file_importer.py`, `helpers.py`）。负责 DB、Excel 导入/导出、通用函数。 - **配置**: `config/settings.json`（数据库类型、Excel 模板路径、动画与评分规则等）。 - **入口**: `main.py`（使用 `ttkbootstrap.Window` 启动 `MainWindow`）。 **Important Singletons & side-effects**: - `src/utils/database.py` 在模块导入时会创建 `db_instance`（会自动 connect 并 create_tables）。 - `src/utils/file_importer.py` 在导入时会创建 `excel_importer` 单例并生成模板文件（会访问 `config/settings.json`）。 - `src/core/random_selector.py` 会在模块末尾创建 `random_selector` 与 `order_selector` 单例。 - `src/core/data_manager.py` 在模块导入时尝试创建 `data_manager`，若 DB 初始化失败会设为 `None`（注意上层消费需检查）。 这些单例会在模块导入阶段导致 I/O（数据库连接、文件写入、读取配置），AI 在修改这些模块时要谨慎：避免在导入时执行长时间或不必要的副作用。 **Config / Path Conventions**: - 多数 util 模块通过计算 `project_root`（基于 `__file__` 的父目录）来定位 `config/settings.json`，请遵循相同做法以保证路径一致性。 - `config/settings.json` 控制 `database.type`（`mysql` 或 `sqlite`）、表名、动画参数、导出模板路径等。 **Database specifics**: - 默认使用 MySQL（项目当前配置连接到 `db4free.net`）。代码在多个位置调用 `db_instance.reconnect()` 来处理远程免费 MySQL 的断连问题。 - `Database` 会根据 `database.type` 选择 MySQL 或 SQLite，并在初始化时创建所需表。 - 学生行的数据结构在代码中被视为 tuple: `(student_id, name, major, total_score, random_call_num)`。许多函数依赖此固定索引顺序。 **Common return shapes / APIs**: - Excel 导入/导出方法返回 `Tuple[bool, str]`（成功标志，信息），例如 `excel_importer.import_students(...)`。 - 调用选人相关函数返回 `(student_tuple, message)` 或 `(None, error_msg)`，请在 UI 层检查返回值再使用。 **Key files to reference when making changes**: - `main.py` — 运行入口，展示如何初始化 UI 与关闭 DB：`db_instance.close()`。 - `src/core/data_manager.py` — 中央协调器，所有 UI 操作通过它与 DB/算法层交互。 - `src/utils/database.py` — DB 连接、建表、增删改查；对 SQL 语句和事务敏感。 - `src/utils/file_importer.py` — Excel 导入/导出、模板生成与日志记录（使用 `logging`）。 - `src/gui/components.py` — 自定义组件定义（表格列名/列数在此处有硬编码），修改表结构时请同时更新这里。 **Developer workflows / commands**: - 安装依赖：`pip install -r requirements.txt`（`requirements.txt` 列出了 `pandas`, `openpyxl`, `ttkbootstrap`, `Pillow`, `pymysql` 等）。 - 运行应用：在项目根目录执行 `python main.py`。 - 配置数据库：编辑 `config/settings.json` 中的 `database` 部分；代码对 `db4free` 环境做了重连与更长超时处理，但仍可能不稳定。 **Project-specific conventions & gotchas (useful for AI changes)**: - 避免在模块导入时做大量阻塞 I/O；若需延迟初始化，优先把连接逻辑放到工厂函数或类的 `init` 方法中（项目当前有若干模块在导入时创建实例，修改时需注意影响范围）。 - 多处使用 `db_instance.reconnect()`：数据库操作实现中常在入口处重连以处理长连接断开，新增 DB 调用请保留相同策略。 - 硬编码的 tuple 索引（学生记录）是跨模块约定：在调整字段或列顺序前，先更新 `StudentTable` 的 `columns` 定义与所有消费处的索引。 - 配置路径和模板路径均基于 `project_root` 拼接；遵循现有 path 计算逻辑可避免相对路径错误（参见 `file_importer.py` 与 `database.py`）。 **Example snippets (how to call things correctly)**: - 获取学生列表（UI 层常用）: `students = data_manager.get_all_students()` → 每个 item 是 `(id, name, major, total_score, random_call_num)`。 - 随机点名（调用链）: UI -> `data_manager.random_call()` -> `random_selector.select()` -> `AnimationEngine.start_roll()`。 - 导入 Excel: UI 调用 `data_manager.import_excel(file_path)`；返回 `(True, msg)` 或 `(False, err_msg)`。 如果本文件有不完整或需要补充的地方，请指出你关心的具体区域（比如：数据库迁移、去导入模块的副作用、或将 UI 分离为服务端 API 等），我会据此迭代补充内容。 *** 结束 ***