python/class-call-system (1)/.github/copilot-instructions.md

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 等），我会据此迭代补充内容。

*** 结束 ***