diff --git a/skills/week_report_gen/README.md b/.claude/skills/week_report_gen/README.md similarity index 100% rename from skills/week_report_gen/README.md rename to .claude/skills/week_report_gen/README.md diff --git a/skills/week_report_gen/SKILL.md b/.claude/skills/week_report_gen/SKILL.md similarity index 98% rename from skills/week_report_gen/SKILL.md rename to .claude/skills/week_report_gen/SKILL.md index 3e9ced4..82fa41c 100644 --- a/skills/week_report_gen/SKILL.md +++ b/.claude/skills/week_report_gen/SKILL.md @@ -295,6 +295,7 @@ print(summary_data) - Column structure - Separator rows between projects - Appropriate column widths + - **Template colors and styles**: When a template file is provided, all cell colors, fonts, borders, and other styling from the template's first 4 rows (headers) are automatically preserved in the output 6. **Multiple Team Members**: When multiple people work on the same project, their names are combined in the "參與人員" column and hours are summed. diff --git a/skills/week_report_gen/generate_report.py b/.claude/skills/week_report_gen/generate_report.py similarity index 57% rename from skills/week_report_gen/generate_report.py rename to .claude/skills/week_report_gen/generate_report.py index 5b429c7..dfbc6ba 100644 --- a/skills/week_report_gen/generate_report.py +++ b/.claude/skills/week_report_gen/generate_report.py @@ -8,9 +8,98 @@ import pandas as pd import openpyxl from datetime import datetime from openpyxl.styles import Font, Alignment, PatternFill, Border, Side +from copy import copy import os +# Style constants for consistent coloring +HEADER_FILL_COLOR = 'FF2F75B5' # Blue header background +DATA_FILL_COLOR = 'FFE7E6E6' # Light gray data background +WHITE_BORDER = Border( + left=Side(style='thin', color='FFFFFFFF'), + right=Side(style='thin', color='FFFFFFFF'), + top=Side(style='thin', color='FFFFFFFF'), + bottom=Side(style='thin', color='FFFFFFFF') +) + + +def copy_cell_style(source_cell, target_cell): + """ + Copy all styling from source cell to target cell. + """ + if source_cell.has_style: + target_cell.font = copy(source_cell.font) + target_cell.border = copy(source_cell.border) + target_cell.fill = copy(source_cell.fill) + target_cell.number_format = copy(source_cell.number_format) + target_cell.protection = copy(source_cell.protection) + target_cell.alignment = copy(source_cell.alignment) + + +def copy_sheet_with_format(source_sheet, target_sheet, max_rows=10): + """ + Copy formatting from source sheet template to target sheet. + Only copies the first few rows (headers) to preserve template styling. + """ + # Copy row heights + for row_idx in range(1, max_rows + 1): + if row_idx in source_sheet.row_dimensions: + target_sheet.row_dimensions[row_idx].height = source_sheet.row_dimensions[row_idx].height + + # Copy column widths + for col_letter in ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K']: + if col_letter in source_sheet.column_dimensions: + target_sheet.column_dimensions[col_letter].width = source_sheet.column_dimensions[col_letter].width + + # Copy cell formatting for header rows (first max_rows) + for row_idx in range(1, max_rows + 1): + for col_idx in range(1, 12): # Columns A-K + source_cell = source_sheet.cell(row=row_idx, column=col_idx) + target_cell = target_sheet.cell(row=row_idx, column=col_idx) + + # Copy style + copy_cell_style(source_cell, target_cell) + + # Copy merged cells info (we'll handle merging separately) + + # Copy merged cells from template (only header rows) + for merged_range in source_sheet.merged_cells.ranges: + if merged_range.min_row <= max_rows and merged_range.max_row <= max_rows: + try: + target_sheet.merge_cells(str(merged_range)) + except: + pass # Skip if already merged or invalid + + +def style_header_row(ws, row_idx, template_cell=None, col_start=2, col_end=10): + """ + Apply header styling (blue fill, bold, centered, white grid) to a row. + If template_cell is provided, its style is copied before applying borders. + """ + for col_idx in range(col_start, col_end + 1): + cell = ws.cell(row=row_idx, column=col_idx) + if template_cell and template_cell.has_style: + copy_cell_style(template_cell, cell) + else: + cell.fill = PatternFill(start_color=HEADER_FILL_COLOR, end_color=HEADER_FILL_COLOR, fill_type='solid') + cell.font = Font(bold=True) + cell.alignment = Alignment(horizontal='center', vertical='center', wrap_text=True) + cell.border = WHITE_BORDER + + +def style_data_row(ws, row_idx, fill_color=DATA_FILL_COLOR, col_start=2, col_end=10): + """ + Apply data row styling (fill, wrap text, white grid) to a row. + """ + data_fill = PatternFill(start_color=fill_color, end_color=fill_color, fill_type='solid') + data_align = Alignment(vertical='top', wrap_text=True) + for col_idx in range(col_start, col_end + 1): + cell = ws.cell(row=row_idx, column=col_idx) + cell.fill = data_fill + cell.alignment = data_align + cell.border = WHITE_BORDER + + def read_cost_report(file_path): """ Read cost report and parse the data. @@ -150,15 +239,39 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam if template_file and os.path.exists(template_file): print(f"Loading template from: {template_file}") wb = openpyxl.load_workbook(template_file) + + # Get the template sheet (usually the first or named '周报示例') + template_sheet = None + for sheet_name_candidate in ['周报示例', wb.sheetnames[0]]: + if sheet_name_candidate in wb.sheetnames: + template_sheet = wb[sheet_name_candidate] + break + # Create new sheet for this week sheet_name = f"{end_date.strftime('%Y%m%d')}-{team_name}" ws = wb.create_sheet(sheet_name, 0) # Insert at beginning + + # Copy formatting from template if available + if template_sheet: + print(f"Copying formatting from template sheet: {template_sheet.title}") + copy_sheet_with_format(template_sheet, ws, max_rows=4) + + # Unmerge cells beyond row 4 to allow data writing + # Keep header merges (rows 1-3) but clear any others + merged_ranges_to_remove = [] + for merged_range in ws.merged_cells.ranges: + if merged_range.min_row > 4: + merged_ranges_to_remove.append(merged_range) + + for merged_range in merged_ranges_to_remove: + ws.unmerge_cells(str(merged_range)) else: print("Creating new workbook (no template provided)") wb = openpyxl.Workbook() ws = wb.active sheet_name = f"{end_date.strftime('%Y%m%d')}-{team_name}" ws.title = sheet_name + template_sheet = None # Write header ws['B1'] = '弘訊科技股份有限公司' @@ -170,6 +283,10 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam '參與人員', '工时（个人投入研发工时', '交付物', '代碼（如有）是否上傳', '下周計畫'] for col_idx, header in enumerate(headers, start=2): # Start from column B ws.cell(row=4, column=col_idx, value=header) + + # Ensure header row is uniformly blue (including the 下周計畫 column) + template_header_cell = template_sheet.cell(row=4, column=2) if 'template_sheet' in locals() and template_sheet else None + style_header_row(ws, row_idx=4, template_cell=template_header_cell) # Write data starting from row 5 current_row = 5 @@ -183,62 +300,67 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam ws.cell(row=current_row, column=8, value=row_data['交付物']) ws.cell(row=current_row, column=9, value=row_data['代碼上傳']) ws.cell(row=current_row, column=10, value=row_data['下周計畫']) + + # Apply consistent gray fill and white borders to data row + style_data_row(ws, row_idx=current_row) + current_row += 1 # Add separator row (except after last entry) if idx < len(report_df) - 1: - current_row += 1 ws.cell(row=current_row, column=2, value='專案名稱') for col_idx, header in enumerate(headers[1:], start=3): ws.cell(row=current_row, column=col_idx, value=header) + # Apply blue header styling to separator row (no blank white spacer) + style_header_row(ws, row_idx=current_row, template_cell=template_header_cell) current_row += 1 - # Apply formatting - header_fill = PatternFill(start_color='D3D3D3', end_color='D3D3D3', fill_type='solid') - bold_font = Font(bold=True) - center_align = Alignment(horizontal='center', vertical='center', wrap_text=True) - wrap_align = Alignment(vertical='top', wrap_text=True) - - # Format title rows - ws['B1'].font = Font(bold=True, size=14) - ws['B1'].alignment = center_align - ws['B2'].font = Font(bold=True, size=12) - ws['B2'].alignment = center_align - ws['B3'].font = Font(size=10, italic=True) - ws['B3'].alignment = wrap_align - - # Merge cells for headers - ws.merge_cells('B1:J1') - ws.merge_cells('B2:J2') - ws.merge_cells('B3:J3') - - # Format column headers and separator rows - for row in range(1, current_row + 1): - cell_b = ws.cell(row=row, column=2) - if cell_b.value == '專案名稱' or row == 4: - for col_idx in range(2, 11): - cell = ws.cell(row=row, column=col_idx) - cell.fill = header_fill - cell.font = bold_font - cell.alignment = center_align - - # Set column widths - column_widths = { - 'B': 20, # 專案名稱 - 'C': 20, # 子項目名稱 - 'D': 8, # 進度 - 'E': 35, # 本周主要進展 - 'F': 15, # 參與人員 - 'G': 12, # 工時 - 'H': 15, # 交付物 - 'I': 10, # 代碼上傳 - 'J': 20 # 下周計畫 - } - - for col, width in column_widths.items(): - ws.column_dimensions[col].width = width + # Apply formatting (only if no template was used) + if not template_sheet: + # Format title rows + ws['B1'].font = Font(bold=True, size=14) + ws['B1'].alignment = Alignment(horizontal='center', vertical='center', wrap_text=True) + ws['B2'].font = Font(bold=True, size=12) + ws['B2'].alignment = Alignment(horizontal='center', vertical='center', wrap_text=True) + ws['B3'].font = Font(size=10, italic=True) + ws['B3'].alignment = Alignment(vertical='top', wrap_text=True) + + # Merge cells for headers + ws.merge_cells('B1:J1') + ws.merge_cells('B2:J2') + ws.merge_cells('B3:J3') + + # Set column widths + column_widths = { + 'B': 20, # 專案名稱 + 'C': 20, # 子項目名稱 + 'D': 8, # 進度 + 'E': 35, # 本周主要進展 + 'F': 15, # 參與人員 + 'G': 12, # 工時 + 'H': 15, # 交付物 + 'I': 10, # 代碼上傳 + 'J': 20 # 下周計畫 + } + + for col, width in column_widths.items(): + ws.column_dimensions[col].width = width + else: + # Template was used - only apply formatting to separator rows and data cells + # Get header formatting from row 4 + header_cells = [ws.cell(row=4, column=col_idx) for col_idx in range(2, 11)] + + # Apply header formatting to separator rows + for row in range(5, current_row + 1): + cell_b = ws.cell(row=row, column=2) + if cell_b.value == '專案名稱': + for col_idx in range(2, 11): + target_cell = ws.cell(row=row, column=col_idx) + source_cell = ws.cell(row=4, column=col_idx) + copy_cell_style(source_cell, target_cell) # Apply wrap text to all data cells + wrap_align = Alignment(vertical='top', wrap_text=True) for row in range(5, current_row): for col in range(2, 11): ws.cell(row=row, column=col).alignment = wrap_align diff --git a/skills/week_report_gen/references/cost-report-2026-01-16-T-16-22-3620260116-7-1r1n4h.xls b/.claude/skills/week_report_gen/references/cost-report-2026-01-16-T-16-22-3620260116-7-1r1n4h.xls similarity index 100% rename from skills/week_report_gen/references/cost-report-2026-01-16-T-16-22-3620260116-7-1r1n4h.xls rename to .claude/skills/week_report_gen/references/cost-report-2026-01-16-T-16-22-3620260116-7-1r1n4h.xls diff --git a/skills/week_report_gen/references/項目週報-台灣-軟體部-智能控制組 (20260115).xlsx b/.claude/skills/week_report_gen/references/項目週報-台灣-軟體部-智能控制組 (20260115).xlsx similarity index 100% rename from skills/week_report_gen/references/項目週報-台灣-軟體部-智能控制組 (20260115).xlsx rename to .claude/skills/week_report_gen/references/項目週報-台灣-軟體部-智能控制組 (20260115).xlsx diff --git a/skills/week_report_gen/references/項目週報-模板.xlsx b/.claude/skills/week_report_gen/references/項目週報-模板.xlsx similarity index 100% rename from skills/week_report_gen/references/項目週報-模板.xlsx rename to .claude/skills/week_report_gen/references/項目週報-模板.xlsx diff --git a/.gitignore b/.gitignore index 1de76b8..02a7c99 100644 --- a/.gitignore +++ b/.gitignore @@ -161,3 +161,6 @@ cython_debug/ #.idea/ uv.lock +temp/ +output/ +logs/ diff --git a/README.md b/README.md index 3cde97b..0735884 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,6 @@ This repository contains AI skills for automated report generation. Currently in Automatically generates weekly project reports (項目週報) from exported Excel time tracking data. -**Features:** -- Reads cost report Excel exports from project management systems -- Aggregates work hours by person and project -- Generates formatted weekly reports following company templates -- Auto-populates team members, work hours, and progress notes -- Creates professional Excel output with proper formatting - -**Use Cases:** -- Weekly project status reporting -- Time tracking data transformation -- Team productivity summaries -- Management reporting automation - -**Quick Start:** -```bash -cd skills/week_report_gen -python generate_report.py -``` - -**Documentation:** -- [SKILL.md](skills/week_report_gen/SKILL.md) - Comprehensive skill documentation -- [README.md](skills/week_report_gen/README.md) - Usage guide and examples -- [QUICK_REFERENCE.md](skills/week_report_gen/QUICK_REFERENCE.md) - AI assistant reference - ## Getting Started ### Prerequisites @@ -39,146 +15,4 @@ python generate_report.py ```bash # Create virtual environment and install dependencies uv sync - -# Activate virtual environment (optional - uv run handles this) -.venv\Scripts\activate # Windows -source .venv/bin/activate # Linux/Mac ``` - -> **💡 Tip**: This project uses `pyproject.toml` for reliable dependency management with uv. -> See [UV_SETUP_GUIDE.md](UV_SETUP_GUIDE.md) for detailed setup instructions and best practices. - -### Using with AI Assistants - -Simply tell your AI assistant (GitHub Copilot, Claude, etc.): - -> "Generate a weekly report from the cost report file" - -The AI will automatically: -1. Read the skill documentation -2. Process the input data -3. Generate a formatted report -4. Show you a summary - -### Manual Usage - -```python -from skills.week_report_gen.generate_report import generate_weekly_report - -# Generate report -output_file, summary = generate_weekly_report( - input_file='path/to/cost-report.xls', - output_file='path/to/weekly-report.xlsx' -) - -print(f"Report saved: {output_file}") -``` - -## Repository Structure - -``` -report_skill_expm/ -├── README.md # This file -├── skills/ -│ └── week_report_gen/ # Weekly report generator skill -│ ├── SKILL.md # Skill documentation -│ ├── README.md # User guide -│ ├── QUICK_REFERENCE.md # AI assistant reference -│ ├── generate_report.py # Main script -│ └── references/ # Sample files and templates -│ ├── cost-report-*.xls # Example input -│ ├── 項目週報-模板.xlsx # Standard template -│ └── 項目週報-*.xlsx # Example outputs -└── .venv/ # Virtual environment (created) -``` - -## Input & Output Examples - -### Input: Cost Report -``` -日期 使用者 活動 專案 單位 -2026-01-12 ben sung Development masterXXX 8 -2026-01-12 Ryan Hsueh - AXEL PLC 8 -2026-01-13 傑 羅 Development CNC Library 移植 4 -``` - -### Output: Weekly Report -``` -弘訊科技股份有限公司 -2026年度週報(01月12日-01月16日） - -專案名稱 參與人員 工時 本周主要進展 -────────────────────────────────────────────────── -AXEL PLC Ryan Hsueh 48.0 - -masterXXX ben sung 15.0 Development - migrate to entry based sdo queue -CNC Library移植 傑 羅 8.0 Development - 程式碼整理及重構 -``` - -## Development - -### Adding New Skills - -1. Create a new directory under `skills/` -2. Add a `SKILL.md` file with comprehensive documentation -3. Implement the skill functionality -4. Add examples and tests -5. Update this README - -### Testing - -```bash -# Test the weekly report generator -cd skills/week_report_gen -python generate_report.py -``` - -## Use Cases - -### 1. Weekly Team Reports -Transform time tracking exports into management-ready weekly reports automatically. - -### 2. Project Status Updates -Quickly see which projects are active, who's working on them, and how many hours were invested. - -### 3. Resource Allocation Analysis -Understand how team members' time is distributed across projects. - -### 4. Management Reporting -Generate standardized reports for management review with minimal manual effort. - -## Roadmap - -Future skills being considered: - -- **Monthly Summary Generator**: Aggregate weekly reports into monthly summaries -- **Project Timeline Generator**: Visualize project progress over time -- **Resource Utilization Report**: Analyze team member utilization rates -- **Cost Analysis Report**: Transform time data into cost estimates -- **Multi-team Comparison**: Compare metrics across different teams - -## Contributing - -Contributions welcome! To add a new skill: - -1. Follow the existing skill structure -2. Provide comprehensive documentation -3. Include example files -4. Test thoroughly -5. Submit a pull request - -## License - -MIT License - See individual skill files for specific licensing information. - -## Support - -For questions or issues: -1. Check the skill-specific documentation in `skills/[skill_name]/` -2. Review example files in `references/` directories -3. Open an issue for bugs or feature requests - -## Acknowledgments - -This project demonstrates how AI skills can automate routine reporting tasks, saving time and reducing errors in data transformation and report generation workflows. \ No newline at end of file diff --git a/UV_SETUP_GUIDE.md b/UV_SETUP_GUIDE.md deleted file mode 100644 index 6c0490f..0000000 --- a/UV_SETUP_GUIDE.md +++ /dev/null @@ -1,292 +0,0 @@ -# Quick Start Guide for UV-based Setup - -## Why UV + pyproject.toml? - -✅ **Reliable**: All dependencies locked to specific versions -✅ **Fast**: UV is significantly faster than pip -✅ **Reproducible**: Same environment across all machines -✅ **Simple**: One command to set up everything -✅ **Modern**: Using Python packaging best practices - -## Installation - -### First Time Setup - -```bash -# Install uv (if not already installed) -# Windows (PowerShell) -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - -# Linux/macOS -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Or with pip -pip install uv -``` - -### Project Setup - -```bash -# Clone or navigate to the repository -cd report_skill_expm - -# Create virtual environment and install all dependencies -uv sync - -# That's it! All dependencies are now installed and locked -``` - -## Usage - -### Option 1: Using `uv run` (Recommended) - -No need to activate the virtual environment - uv handles it automatically: - -```bash -# Run the example -uv run python example.py - -# Run the report generator directly -uv run python skills/week_report_gen/generate_report.py - -# Import and use in Python -uv run python -c "from skills.week_report_gen.generate_report import generate_weekly_report; print('Ready!')" -``` - -### Option 2: Traditional Virtual Environment - -```bash -# Activate the virtual environment -.venv\Scripts\activate # Windows -source .venv/bin/activate # Linux/Mac - -# Now you can run Python normally -python example.py -python skills/week_report_gen/generate_report.py -``` - -## What's in pyproject.toml? - -```toml -[project] -name = "report-skill-expm" -version = "1.0.0" -requires-python = ">=3.9" - -dependencies = [ - "openpyxl>=3.1.0", # Excel file handling - "pandas>=2.0.0", # Data processing - "xlrd>=2.0.0", # Reading .xls files -] - -[project.optional-dependencies] -dev = [ - "pytest>=7.0.0", # Testing framework - "black>=23.0.0", # Code formatter - "flake8>=6.0.0", # Linter -] -``` - -## Common Commands - -```bash -# Install/update dependencies -uv sync - -# Install with dev dependencies -uv sync --extra dev - -# Add a new dependency -uv add package-name - -# Remove a dependency -uv remove package-name - -# Update all dependencies -uv sync --upgrade - -# Show installed packages -uv pip list - -# Run any Python script -uv run python your_script.py - -# Run a specific module -uv run python -m skills.week_report_gen.generate_report - -# Start Python REPL with dependencies available -uv run python -``` - -## Benefits Over Manual pip Installation - -### Before (Manual) -```bash -python -m venv .venv -.venv\Scripts\activate -pip install openpyxl pandas xlrd -# Need to remember all packages and versions -# No lock file - different versions on different machines -``` - -### After (UV + pyproject.toml) -```bash -uv sync -# Done! Everything locked and reproducible -``` - -## Dependency Management - -### Adding Dependencies - -```bash -# Add a runtime dependency -uv add requests - -# Add a development dependency -uv add --dev pytest-cov - -# Add with version constraint -uv add "pandas>=2.0,<3.0" -``` - -### Updating Dependencies - -```bash -# Update all dependencies -uv sync --upgrade - -# Update specific package -uv add --upgrade pandas -``` - -### Lock File - -The `uv.lock` file (auto-generated) ensures: -- ✅ Exact versions are used across all environments -- ✅ Transitive dependencies are locked -- ✅ No "works on my machine" issues -- ✅ Fast, deterministic installs - -**Commit `uv.lock` to version control!** - -## Troubleshooting - -### "uv: command not found" - -Install uv first: -```bash -pip install uv -# or -curl -LsSf https://astral.sh/uv/install.sh | sh -``` - -### "No module named 'xxx'" - -Make sure you've run `uv sync`: -```bash -uv sync -``` - -### Virtual Environment Not Found - -Recreate it: -```bash -rm -rf .venv # or rmdir /s .venv on Windows -uv sync -``` - -### Import Errors - -Use `uv run` to automatically activate the environment: -```bash -uv run python your_script.py -``` - -## CI/CD Integration - -### GitHub Actions - -```yaml -- name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.11' - -- name: Install uv - run: pip install uv - -- name: Install dependencies - run: uv sync - -- name: Run tests - run: uv run pytest -``` - -### GitLab CI - -```yaml -test: - script: - - pip install uv - - uv sync - - uv run pytest -``` - -## Migration from requirements.txt - -If you have an old `requirements.txt`: - -```bash -# Import from requirements.txt -uv add $(cat requirements.txt) - -# Or manually add each package -uv add openpyxl pandas xlrd -``` - -## Best Practices - -1. **Always commit `uv.lock`** - Ensures reproducible builds -2. **Use `uv run`** - Simplifies workflow, no activation needed -3. **Keep pyproject.toml clean** - Only list direct dependencies -4. **Use version constraints** - `>=3.1.0` not `==3.1.0` -5. **Separate dev dependencies** - Use `[project.optional-dependencies]` - -## Comparison: pip vs uv - -| Feature | pip | uv | -|---------|-----|-----| -| Speed | 🐌 Slow | 🚀 Fast (10-100x) | -| Lock file | requirements.txt (manual) | uv.lock (automatic) | -| Resolver | Sometimes inconsistent | Always consistent | -| Parallel installs | No | Yes | -| Built-in venv | Need separate commands | Integrated | - -## Resources - -- [UV Documentation](https://github.com/astral-sh/uv) -- [Python Packaging Guide](https://packaging.python.org/) -- [pyproject.toml Specification](https://peps.python.org/pep-0621/) - ---- - -**Quick Reference Card** - -```bash -# Setup -uv sync # Install everything - -# Run -uv run python app.py # Execute with dependencies - -# Manage -uv add pkg # Add dependency -uv remove pkg # Remove dependency -uv sync --upgrade # Update all - -# Dev -uv sync --extra dev # Install dev dependencies -uv run pytest # Run tests -uv run black . # Format code -``` diff --git a/skills/week_report_gen/COMPLETE_GUIDE.md b/skills/week_report_gen/COMPLETE_GUIDE.md deleted file mode 100644 index d5dc2fa..0000000 --- a/skills/week_report_gen/COMPLETE_GUIDE.md +++ /dev/null @@ -1,405 +0,0 @@ -# Weekly Report Generator Skill - Complete Guide - -## 🎯 What This Skill Does - -The **Weekly Report Generator** (`week_report_gen`) is an AI skill that automatically transforms time tracking data from project management systems into professional weekly project reports (項目週報). - -### Key Benefits - -✅ **Saves Time**: Automates report generation from raw time tracking data -✅ **Reduces Errors**: Eliminates manual data entry and calculation mistakes -✅ **Consistent Format**: Uses company standard templates every time -✅ **Smart Aggregation**: Automatically groups work by project and team member -✅ **AI-Powered**: Works seamlessly with GitHub Copilot, Claude, and other AI assistants - ---- - -## 📦 What's Included - -``` -skills/week_report_gen/ -├── SKILL.md # Comprehensive technical documentation -├── README.md # User guide with examples -├── QUICK_REFERENCE.md # AI assistant reference guide -├── generate_report.py # Main Python script -└── references/ - ├── cost-report-*.xls # Example input file - ├── 項目週報-模板.xlsx # Standard template - └── 項目週報-*.xlsx # Example outputs -``` - ---- - -## 🚀 Quick Start - -### 1. Setup (One Time) - -```bash -# From repository root: create venv and install all dependencies -uv sync - -# Activate it (optional - uv run handles this automatically) -.venv\Scripts\activate # Windows -source .venv/bin/activate # Mac/Linux -``` - -### 2. Generate Your First Report - -**Option A: Using AI Assistant** (Easiest) - -Just say: -> "Generate a weekly report from my cost report file" - -**Option B: Command Line** - -```bash -# From repository root -uv run python skills/week_report_gen/generate_report.py - -# Or navigate first -cd skills/week_report_gen -uv run python generate_report.py -``` - -**Option C: Python Script** - -```python -from skills.week_report_gen.generate_report import generate_weekly_report - -output_file, summary = generate_weekly_report( - input_file='cost-report.xls', - output_file='weekly-report.xlsx' -) -``` - ---- - -## 📊 Input → Output - -### Input: Cost Report Excel -Raw time tracking data exported from your project management system. - -| 日期 | 使用者 | 活動 | 專案 | 單位 | -|------|--------|------|------|------| -| 2026-01-12 | ben sung | Development | masterXXX | 8 | -| 2026-01-12 | Ryan Hsueh | - | AXEL PLC | 8 | - -### Output: Weekly Report Excel -Formatted, professional report ready for management review. - -| 專案名稱 | 參與人員 | 工時 | 本周主要進展 | 下周計畫 | -|----------|----------|------|--------------|----------| -| masterXXX | ben sung | 15.0 | Development
migrate to entry based sdo queue | _(fill in)_ | -| AXEL PLC | Ryan Hsueh | 48.0 | - | _(fill in)_ | - ---- - -## 🎨 Key Features - -### 1. Smart Data Aggregation -- Automatically sums hours by project and person -- Groups multiple entries from the same project -- Combines team members who worked on the same project - -### 2. Auto-Population -**Automatically filled:** -- ✅ 專案名稱 (Project name) -- ✅ 參與人員 (Team members) -- ✅ 工時 (Total hours) -- ✅ 本周主要進展 (Progress notes from comments) - -**Leave blank for manual input:** -- ⬜ 進度 (Progress percentage) -- ⬜ 交付物 (Deliverables) -- ⬜ 代碼上傳 (Code upload status) -- ⬜ 下周計畫 (Next week's plan) - -### 3. Professional Formatting -- Company header and branding -- Proper column widths -- Header formatting with gray background -- Separator rows between projects -- Text wrapping for long entries -- Merged cells for titles - -### 4. Date Range Detection -Automatically extracts the reporting period from the data: -``` -2026年度週報(01月12日-01月16日） -``` - ---- - -## 💡 Usage Examples - -### Example 1: Basic Generation - -```bash -# Navigate to skill directory -cd skills/week_report_gen - -# Run with default settings (uses sample file) -python generate_report.py - -# Output: 項目週報-智能控制組-20260116.xlsx -``` - -### Example 2: Custom Files - -```bash -# Specify input and output files -python generate_report.py \ - "path/to/your-cost-report.xls" \ - "path/to/output-weekly-report.xlsx" -``` - -### Example 3: Python Integration - -```python -from generate_report import generate_weekly_report - -# Generate report for specific team -output, summary = generate_weekly_report( - input_file='data/cost-report.xls', - output_file='reports/weekly-20260116.xlsx', - template_file='templates/standard.xlsx', - team_name='研發部-AI組' -) - -# View summary -print(f"Generated report with {len(summary)} projects") -print(f"Total hours: {summary['工時'].sum()}") -``` - -### Example 4: AI Assistant - -``` -You: "Generate a weekly report from cost-report-2026-01-16.xls for the AI team" - -AI: "I'll generate the weekly report for the AI team. - - [Processing...] - - ✓ Report generated successfully! - - Summary of 5 projects: - - Project A (Team Member 1, Team Member 2, 32 hours) - - Project B (Team Member 3, 16 hours) - ... - - Report saved to: 項目週報-AI組-20260116.xlsx - - Please review and fill in: - - Progress percentages - - Deliverables - - Next week's plan" -``` - ---- - -## 📋 After Report Generation - -### Manual Steps Required - -1. **Open the Excel file** in your spreadsheet application - -2. **Review "本周主要進展" (Progress)** - - Check auto-generated progress notes - - Edit for clarity and completeness - - Add any missing accomplishments - -3. **Fill in "進度" (Progress %)** - - Enter progress as decimal (0.5 = 50%) - - Example: 0.75 for 75% complete - -4. **Add "交付物" (Deliverables)** - - List specific deliverables if any - - Include document names, versions, etc. - -5. **Mark "代碼上傳" (Code Upload)** - - Enter "Y" if code was uploaded - - Enter "N" if not applicable - -6. **Plan "下周計畫" (Next Week)** - - Outline next week's goals - - Be specific and actionable - -7. **Add Visual Materials** (Optional) - - Insert diagrams, screenshots, etc. - - Reference in the header suggestion - ---- - -## 🔧 Customization - -### Change Team Name - -```python -generate_weekly_report( - input_file='cost.xls', - output_file='report.xlsx', - team_name='您的團隊名稱' # Your team name -) -``` - -### Adjust Column Widths - -Edit `generate_report.py`: -```python -column_widths = { - 'B': 25, # Wider project name column - 'E': 40, # Wider progress column - # Adjust as needed -} -``` - -### Modify Grouping Logic - -Edit the `format_for_weekly_report()` function to change: -- How projects are grouped -- What information is included in progress -- How team members are listed - ---- - -## 🐛 Troubleshooting - -### Error: "Module not found" - -**Solution:** -```bash -# Make sure you're in the virtual environment -.venv\Scripts\activate - -# Install dependencies -uv pip install openpyxl pandas xlrd -``` - -### Error: "Column not found" - -**Cause:** Input file has different column names - -**Solution:** -1. Open the input Excel file -2. Check column names match: 日期, 使用者, 專案, 單位 -3. If different, the script will try alternative headers -4. Contact support if issues persist - -### Empty or No Output - -**Check:** -1. Input file has data (not just headers) -2. Data starts at expected row (usually row 2) -3. File isn't corrupted or password-protected -4. Required columns have values (not all empty) - -### Report Looks Wrong - -**Verify:** -1. Template file exists and is valid -2. Using correct template for your organization -3. Excel/LibreOffice can open the file -4. File isn't read-only - ---- - -## 📚 Additional Resources - -### Documentation Files - -- **[SKILL.md](SKILL.md)** - Complete technical documentation - - Detailed API reference - - Function descriptions - - Code examples - - Error handling guide - -- **[README.md](README.md)** - Comprehensive user guide - - Feature overview - - Installation instructions - - Usage examples - - Customization options - -- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - AI assistant guide - - How to use with AI assistants - - Common patterns - - Troubleshooting for AI - - Best practices - -### Example Files - -Located in `references/` directory: -- Input example: `cost-report-*.xls` -- Template: `項目週報-模板.xlsx` -- Output example: `項目週報-台灣-軟體部-智能控制組 (20260115).xlsx` - ---- - -## 🎓 Tips & Best Practices - -### For Users - -1. **Run Weekly**: Generate reports at week-end for best workflow -2. **Review Before Sharing**: Always check auto-generated content -3. **Keep Template Updated**: Update template when format changes -4. **Backup Originals**: Keep raw cost reports for audit trail -5. **Consistent Naming**: Use consistent project names in time tracking - -### For Developers - -1. **Test with Real Data**: Use actual cost reports for testing -2. **Handle Edge Cases**: Test with empty data, special characters, etc. -3. **Preserve Formulas**: If using formulas, don't hardcode values -4. **Document Changes**: Update SKILL.md when modifying code -5. **Version Control**: Track changes to template and script - -### For AI Assistants - -1. **Validate First**: Check input file exists before processing -2. **Show Progress**: Display what's being done at each step -3. **Summarize Results**: Show key metrics after generation -4. **Remind Manual Steps**: List fields that need manual input -5. **Handle Errors Gracefully**: Provide helpful error messages - ---- - -## 📞 Support & Contact - -### Getting Help - -1. **Check Documentation**: Review SKILL.md and README.md -2. **Review Examples**: Look at reference files in `references/` -3. **Test Script**: Run the example script: `python example.py` -4. **Open Issue**: Report bugs or request features - -### Reporting Issues - -When reporting issues, include: -- Error message (full stack trace) -- Input file format (column names, sample data) -- Expected vs actual output -- Version of Python and libraries -- Operating system - ---- - -## 📝 License - -MIT License - See individual skill files for complete terms. - ---- - -## 🙏 Acknowledgments - -This skill demonstrates how AI can automate routine reporting tasks, saving valuable time and reducing errors in data transformation workflows. - -**Built with:** -- Python 3.x -- openpyxl (Excel file handling) -- pandas (Data processing) -- Love and attention to detail ❤️ - ---- - -**Version:** 1.0.0 -**Last Updated:** January 16, 2026 -**Status:** Production Ready ✅ diff --git a/skills/week_report_gen/QUICK_REFERENCE.md b/skills/week_report_gen/QUICK_REFERENCE.md deleted file mode 100644 index af8d208..0000000 --- a/skills/week_report_gen/QUICK_REFERENCE.md +++ /dev/null @@ -1,250 +0,0 @@ -# Weekly Report Generator - Quick Reference - -## For AI Assistants (GitHub Copilot/Claude) - -When a user asks to generate a weekly report, follow these steps: - -### 1. Identify the Request - -User might say: -- "Generate a weekly report" -- "Create 項目週報 from cost report" -- "Transform time tracking data into weekly report" -- "Make a weekly project report from the Excel export" - -### 2. Read the Skill Documentation - -```python -# Read the full skill instructions -read_file('skills/week_report_gen/SKILL.md') -``` - -### 3. Use the Generate Report Script - -```python -# Import and run the generator -from skills.week_report_gen.generate_report import generate_weekly_report - -# Generate report with provided file paths -output_file, summary_df = generate_weekly_report( - input_file='path/to/cost-report.xls', - output_file='path/to/output-report.xlsx', - template_file='skills/week_report_gen/references/項目週報-模板.xlsx', - team_name='智能控制組' # Or user-specified team name -) - -print(f"✓ Report generated: {output_file}") -print("\nProject Summary:") -for idx, row in summary_df.iterrows(): - print(f"\n{row['專案名稱']}") - print(f" Team: {row['參與人員']}") - print(f" Hours: {row['工時']}") -``` - -### 4. Alternative: Run via Terminal - -```bash -cd skills/week_report_gen -python generate_report.py "path/to/cost-report.xls" "path/to/output.xlsx" -``` - -## Common Usage Patterns - -### Pattern 1: User Provides Input File - -``` -User: "Generate weekly report from cost-report-2026-01-16.xls" - -Assistant Actions: -1. Locate the input file -2. Determine output filename (based on date and team) -3. Run generate_weekly_report() -4. Show summary of projects and hours -5. Confirm file saved location -``` - -### Pattern 2: User Wants to Customize Output - -``` -User: "Create weekly report for 研發部 team" - -Assistant Actions: -1. Ask for input file if not specified -2. Use team_name parameter: team_name='研發部' -3. Generate report -4. Confirm customization applied -``` - -### Pattern 3: User Has Multiple Cost Reports - -``` -User: "Generate reports for all cost reports in the folder" - -Assistant Actions: -1. List all .xls/.xlsx files in references folder -2. Filter for cost report files -3. Generate report for each -4. Provide summary of all generated reports -``` - -## Key Functions - -### read_cost_report(file_path) -Reads and parses the cost report Excel file. - -**Returns**: DataFrame with columns [日期, 使用者, 活動, 專案, 單位, etc.] - -### aggregate_work_hours(df) -Groups work hours by user and project. - -**Returns**: -- `summary_df`: Aggregated data -- `start_date`: Report start date -- `end_date`: Report end date - -### format_for_weekly_report(summary_df) -Transforms aggregated data into weekly report format. - -**Returns**: DataFrame ready for Excel output - -### generate_weekly_report(input_file, output_file, template_file, team_name) -Main function that orchestrates the entire process. - -**Returns**: -- `output_file`: Path to generated report -- `report_df`: Summary DataFrame - -## Example AI Responses - -### Example 1: Basic Generation - -``` -User: "Generate a weekly report from the cost report file" - -AI Assistant: -"I'll generate the weekly report from your cost report. - -[Runs generate_report.py] - -✓ Weekly report generated successfully! - -Summary of 8 projects: -- AXEL PLC (Ryan Hsueh, 48 hours) -- CNC Library 移植 (傑 羅, 8 hours) -- masterXXX (ben sung, 15 hours) -... - -Report saved to: 項目週報-智能控制組-20260116.xlsx - -Please review and fill in the following fields: -- 進度 (Progress percentages) -- 交付物 (Deliverables) -- 代碼上傳 (Code upload status) -- 下周計畫 (Next week's plan)" -``` - -### Example 2: Custom Team Name - -``` -User: "Create a weekly report for the 研發部-AI組 team" - -AI Assistant: -"I'll create a weekly report for the 研發部-AI組 team. - -[Runs with team_name='研發部-AI組'] - -✓ Report generated with custom team name! - -File: 項目週報-研發部-AI組-20260116.xlsx" -``` - -### Example 3: Batch Processing - -``` -User: "Generate weekly reports for all cost report files" - -AI Assistant: -"I found 3 cost report files. Generating reports... - -1. cost-report-2026-01-16.xls → 項目週報-20260116.xlsx ✓ -2. cost-report-2026-01-09.xls → 項目週報-20260109.xlsx ✓ -3. cost-report-2025-12-30.xls → 項目週報-20251230.xlsx ✓ - -All reports generated successfully!" -``` - -## Troubleshooting Guide for AI - -### Issue: File Not Found - -```python -# Check if file exists -import os -if not os.path.exists(input_file): - # List available files - files = os.listdir('skills/week_report_gen/references') - print(f"Available files: {files}") - # Ask user for correct filename -``` - -### Issue: Missing Columns - -```python -# Check what columns are present -import pandas as pd -df = pd.read_excel(input_file, header=1) -print(f"Available columns: {list(df.columns)}") -# Suggest using different header row or file format -``` - -### Issue: Empty Output - -```python -# Check data was loaded -if len(df) == 0: - print("No data found in file. Check:") - print("1. Correct sheet is being read") - print("2. Data starts at expected row") - print("3. File isn't corrupted") -``` - -## Best Practices for AI Assistants - -1. **Always validate input file exists** before processing -2. **Show summary of data** after reading (number of entries, date range, projects) -3. **Display key metrics** in the output (total hours, number of projects, team members) -4. **Remind user of manual fields** that need to be filled in -5. **Provide file location** of generated report clearly -6. **Handle errors gracefully** with helpful error messages -7. **Suggest next steps** after generation (review, fill in fields, etc.) - -## Quick Code Snippets - -### Check Available Cost Reports -```python -import os -files = [f for f in os.listdir('skills/week_report_gen/references') - if f.startswith('cost-report') and f.endswith(('.xls', '.xlsx'))] -print(f"Found {len(files)} cost report(s): {files}") -``` - -### Validate Input File Structure -```python -import pandas as pd -df = pd.read_excel(file_path, header=1) -required = ['日期', '使用者', '專案', '單位'] -missing = [col for col in required if col not in df.columns] -if missing: - print(f"⚠ Missing columns: {missing}") -else: - print("✓ File structure is valid") -``` - -### Preview Data Before Processing -```python -df = pd.read_excel(file_path, header=1) -print(f"Date range: {df['日期'].min()} to {df['日期'].max()}") -print(f"Total entries: {len(df)}") -print(f"Projects: {', '.join(df['專案'].unique()[:5])}") -print(f"Team members: {', '.join(df['使用者'].unique()[:5])}") -``` diff --git a/skills/week_report_gen/VISUAL_WORKFLOW.md b/skills/week_report_gen/VISUAL_WORKFLOW.md deleted file mode 100644 index 43c4efc..0000000 --- a/skills/week_report_gen/VISUAL_WORKFLOW.md +++ /dev/null @@ -1,282 +0,0 @@ -# Weekly Report Generator - Visual Workflow - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ WEEKLY REPORT GENERATOR WORKFLOW │ -└─────────────────────────────────────────────────────────────────────────┘ - -┌──────────────────┐ -│ INPUT FILE │ -│ (Cost Report) │ -│ .xls/.xlsx │ -└────────┬─────────┘ - │ - │ 日期 使用者 活動 專案 單位 - │ 01-12 ben sung Dev masterXXX 8 - │ 01-12 Ryan - AXEL PLC 8 - │ 01-13 傑 羅 Dev CNC Lib 4 - │ - ▼ -┌─────────────────────────────────┐ -│ STEP 1: READ & PARSE │ -│ • Load Excel file │ -│ • Identify columns │ -│ • Clean missing data │ -│ • Extract date range │ -└────────┬────────────────────────┘ - │ - │ DataFrame with validated data - │ Date range: 2026-01-12 to 2026-01-16 - │ - ▼ -┌─────────────────────────────────┐ -│ STEP 2: AGGREGATE │ -│ • Group by user & project │ -│ • Sum work hours │ -│ • Combine activities │ -│ • Collect comments │ -└────────┬────────────────────────┘ - │ - │ Project: masterXXX - │ • ben sung: 15 hours - │ • Activities: Development, Specification - │ • Notes: migrate to entry based sdo queue... - │ - ▼ -┌─────────────────────────────────┐ -│ STEP 3: FORMAT │ -│ • Group by project │ -│ • List team members │ -│ • Format progress notes │ -│ • Calculate totals │ -└────────┬────────────────────────┘ - │ - │ Formatted report data ready for Excel - │ - ▼ -┌─────────────────────────────────┐ -│ STEP 4: GENERATE EXCEL │ -│ • Load template (if exists) │ -│ • Create new sheet │ -│ • Write headers │ -│ • Write project data │ -│ • Apply formatting │ -│ • Save file │ -└────────┬────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────────────┐ -│ OUTPUT FILE (Weekly Report) │ -│ 項目週報-智能控制組 │ -│ │ -│ 弘訊科技股份有限公司 │ -│ 2026年度週報(01月12日-01月16日） │ -│ │ -│ 專案 參與人員 工時 本周進展 │ -│ ──────────────────────────────────────── │ -│ AXEL Ryan Hsueh 48.0 - │ -│ master ben sung 15.0 Development │ -│ XXX migrate to.. │ -│ │ -└──────────────────────────────────────────────┘ - - -DATA FLOW DIAGRAM -═════════════════ - -Raw Time Data ──────┐ - │ -Export from PM ├─────────► Read Excel ────► Parse Columns -System │ │ - │ │ -Cost Report File ───┘ ▼ - Validate & Clean - │ - ▼ - Extract Date Range - │ - ▼ - Group by Project ────┐ - │ │ - │ │ - Sum Hours ◄──────────┤ - │ │ - │ │ - Combine Teams ◄──────┘ - │ - ▼ - Format Progress - │ - ▼ - Load Template - │ - ▼ - Write to Excel - │ - ▼ - Apply Styling - │ - ▼ - Save Output File - │ - ▼ - Weekly Report ✓ - - -COMPONENT ARCHITECTURE -══════════════════════ - -┌─────────────────────────────────────────────────────────────┐ -│ SKILL ARCHITECTURE │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ User Interface Layer │ │ -│ ├─────────────────────────────────────────────────────┤ │ -│ │ • Command Line Interface │ │ -│ │ • AI Assistant Integration │ │ -│ │ • Python API │ │ -│ └────────────────┬────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ Core Processing Layer │ │ -│ ├─────────────────────────────────────────────────────┤ │ -│ │ • read_cost_report() │ │ -│ │ └─► Load Excel, validate columns │ │ -│ │ │ │ -│ │ • aggregate_work_hours() │ │ -│ │ └─► Group data, sum hours, extract dates │ │ -│ │ │ │ -│ │ • format_for_weekly_report() │ │ -│ │ └─► Transform to report format │ │ -│ │ │ │ -│ │ • generate_weekly_report() │ │ -│ │ └─► Main orchestration function │ │ -│ └────────────────┬────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ Output Generation Layer │ │ -│ ├─────────────────────────────────────────────────────┤ │ -│ │ • Excel Writer (openpyxl) │ │ -│ │ • Template Handler │ │ -│ │ • Style & Format Applier │ │ -│ │ • File Saver │ │ -│ └─────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────┘ - - ▲ ▲ - │ │ - ┌────┴─────┐ ┌──────┴──────┐ - │ pandas │ │ openpyxl │ - │ (Data │ │ (Excel │ - │ Process) │ │ Files) │ - └──────────┘ └─────────────┘ - - -FILE ORGANIZATION -═════════════════ - -skills/week_report_gen/ -│ -├── 📄 SKILL.md ─────────────────► Technical documentation -│ • API reference -│ • Function details -│ • Code examples -│ -├── 📄 README.md ────────────────► User guide -│ • Installation -│ • Quick start -│ • Examples -│ -├── 📄 QUICK_REFERENCE.md ───────► AI assistant guide -│ • Usage patterns -│ • Best practices -│ -├── 📄 COMPLETE_GUIDE.md ────────► Comprehensive guide -│ • Everything combined -│ • Tips & tricks -│ -├── 🐍 generate_report.py ───────► Main script -│ • Core functions -│ • Entry point -│ -└── 📁 references/ - │ - ├── 📊 cost-report-*.xls ────► Example input - ├── 📋 項目週報-模板.xlsx ───► Template - └── 📊 項目週報-*.xlsx ──────► Example output - - -USAGE PATTERNS -══════════════ - -Pattern 1: AI Assistant -──────────────────────── -User: "Generate weekly report" - │ - ▼ -AI reads SKILL.md - │ - ▼ -AI runs generate_report.py - │ - ▼ -AI shows summary - │ - ▼ -Report saved ✓ - - -Pattern 2: Command Line -─────────────────────── -$ python generate_report.py input.xls output.xlsx - │ - ▼ -Script processes data - │ - ▼ -Console shows progress - │ - ▼ -Report saved ✓ - - -Pattern 3: Python Integration -────────────────────────────── -from generate_report import generate_weekly_report - │ - ▼ -output, summary = generate_weekly_report(...) - │ - ▼ -Use summary data in your code - │ - ▼ -Process complete ✓ - - -KEY SUCCESS FACTORS -═══════════════════ - -✓ Input Validation - └─► Verify file exists, columns present, data valid - -✓ Smart Aggregation - └─► Group logically, sum accurately, preserve info - -✓ Template Support - └─► Use existing templates, maintain consistency - -✓ Error Handling - └─► Clear messages, graceful failures, helpful hints - -✓ Formatting - └─► Professional appearance, proper widths, colors - -✓ Documentation - └─► Clear examples, complete reference, AI-friendly - -``` diff --git a/skills/week_report_gen/references/項目週報-智能控制組-20260116.xlsx b/skills/week_report_gen/references/項目週報-智能控制組-20260116.xlsx deleted file mode 100644 index 186d106..0000000 Binary files a/skills/week_report_gen/references/項目週報-智能控制組-20260116.xlsx and /dev/null differ diff --git a/skills/week_report_gen/references/項目週報-示例輸出-20260116.xlsx b/skills/week_report_gen/references/項目週報-示例輸出-20260116.xlsx deleted file mode 100644 index 96a6bda..0000000 Binary files a/skills/week_report_gen/references/項目週報-示例輸出-20260116.xlsx and /dev/null differ