readFileSystem/AGENTS.md

AGENTS.md

This file provides coding guidelines and commands for AI agents working in this repository.

Project Overview

This is a PySide6-based desktop application for inspection management and file system browsing. The project includes:

• GUI components for inspection workflows (incoming/manual inspection)
• Database integration with PostgreSQL
• XML parsing for element analysis data
• File system browser utility

Tech Stack: Python 3.8+, PySide6 6.7.1, PostgreSQL (psycopg2), pywin32

---

Build & Run Commands

Installation

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Running the Application

# Main inspection application
python run.py

# File system browser (legacy)
python src/main.py

Testing

Note: This project currently has no test suite. When adding tests:

# Install pytest
pip install pytest pytest-qt

# Run all tests
pytest

# Run single test file
pytest tests/test_xml_parser.py

# Run single test function
pytest tests/test_xml_parser.py::test_parse_valid_xml

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=src --cov-report=html

Linting & Formatting

Note: No linter/formatter is currently configured. Recommended setup:

# Install tools
pip install black flake8 mypy

# Format code
black src/ ui/ utils/

# Lint code
flake8 src/ ui/ utils/ --max-line-length=120

# Type checking
mypy src/ ui/ utils/

---

Code Style Guidelines

1. Imports

• Order: Standard library → Third-party → Local modules
• Style: Absolute imports preferred; relative imports allowed within packages
• Grouping: Separate groups with blank lines

# Standard library
import os
from pathlib import Path
from dataclasses import dataclass
from typing import List, Dict, Optional
from datetime import datetime

# Third-party
from PySide6.QtWidgets import QMainWindow, QWidget
from PySide6.QtCore import Qt
import psycopg2

# Local
from src.db_manager import DatabaseManager
from ui.inspection_card import InspectionCard

2. Formatting

• Line length: ~120 characters (flexible, not enforced)
• Indentation: 4 spaces (no tabs)
• Quotes: Double quotes for strings (not strictly enforced)
• Blank lines: 2 between top-level classes/functions, 1 within classes

3. Naming Conventions

• Classes: PascalCase (e.g., FileSystemReader, InspectionWindow)
• Functions/Methods: snake_case (e.g., get_files_and_folders, parse_file)
• Variables: snake_case (e.g., sample_name, data_list)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES)
• Private members: Prefix with _ (e.g., _get_file_type)

4. Type Hints

• Usage: Encouraged but not mandatory
• Style: Use typing module for complex types
• Return types: Always specify for public methods

from typing import List, Dict, Optional

def get_files_and_folders(self) -> List[FileInfo]:
    """Returns list of file information objects"""
    pass

def parse_file(self, file_path: str) -> tuple[Optional[List[Dict]], str]:
    """Returns (data, error_message)"""
    pass

5. Docstrings

• Style: Google-style docstrings (simple format)
• Required for: Public classes, public methods, complex functions
• Not required for: Simple getters/setters, obvious utility functions

def get_files_and_folders(self) -> List[FileInfo]:
    """
    Read all files and folders from the root path

    Returns:
        List[FileInfo]: List of file information objects
    """
    pass

6. Error Handling

• Philosophy: Fail gracefully, skip inaccessible resources
• Pattern: Try-except with specific exceptions, return None/empty on failure
• Logging: Use print() for errors (no logging framework configured)

try:
    conn = psycopg2.connect(**self.config)
    return conn
except Exception as e:
    print(f"Database connection error: {e}")
    return None

7. Data Classes

• Use @dataclass for simple data containers
• Include type hints for all fields
• Add @property methods for computed values

from dataclasses import dataclass

@dataclass
class FileInfo:
    name: str
    path: str
    size: int
    file_type: str
    is_dir: bool
    modified_time: str

    @property
    def size_readable(self) -> str:
        """Convert size to human-readable format"""
        # Implementation

8. PySide6 GUI Patterns

• Initialization: All UI setup in __init__
• Layouts: Use explicit layout objects (QVBoxLayout, QHBoxLayout)
• Styling: Inline stylesheets for component-specific styles
• Font: Microsoft YaHei for Chinese text support

class InspectionWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("检验管理系统")
        
        # Setup layouts
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        main_layout = QVBoxLayout(central_widget)

9. Database Patterns

• Connection: Create connection per operation, close immediately
• Queries: Use parameterized queries (never string interpolation)
• Schema: Explicitly specify schema with self.schema variable
• Cursors: Use RealDictCursor for dict-like results

def get_connection(self):
    try:
        conn = psycopg2.connect(**self.config)
        return conn
    except Exception as e:
        print(f"Database connection error: {e}")
        return None

10. File Operations

• Path handling: Use pathlib.Path (not os.path)
• Existence checks: Always check before operations
• Encoding: UTF-8 default (not explicitly specified)

from pathlib import Path

def parse_file(self, file_path):
    if not os.path.exists(file_path):
        return None, f"文件未找到: {file_path}"

---

Project-Specific Rules

1. Minimal Comments: Code should be self-explanatory; avoid redundant comments
2. Chinese UI Text: All user-facing strings in Chinese (e.g., "入检", "手检")
3. No Tests: Currently no test suite; add tests when implementing new features
4. Entry Points: run.py for inspection app, src/main.py for file browser
5. Database Credentials: Hardcoded in db_manager.py (not production-ready)
6. Error Messages: Return tuple (data, error_message) pattern for parsers

---

Common Patterns

Adding a New UI Component

1. Create class in ui/ directory
2. Inherit from appropriate PySide6 widget
3. Initialize layout in __init__
4. Use inline stylesheets for custom styling

Adding Database Operations

1. Add method to DatabaseManager class
2. Use get_connection() to obtain connection
3. Always close connection in finally block or after operation
4. Return tuple (success: bool, message: str) for write operations

Parsing New XML Structures

1. Add method to XmlParser class
2. Use xml.etree.ElementTree for parsing
3. Return tuple (data: Optional[List[Dict]], error: str)
4. Handle missing elements gracefully with None defaults

---

Notes for AI Agents

• Preserve existing functionality: Only modify code directly related to the task
• No unnecessary refactoring: Keep changes minimal and targeted
• Test manually: No automated tests; verify changes by running the application
• Database access: Be cautious with database operations; test queries carefully
• Chinese text: Maintain Chinese for UI elements, English for code/comments