forked from Zhubei_iXD/report_skill_expm
feat: improve format
This commit is contained in:
parent
69c955fd57
commit
0db7c83733
|
|
@ -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.
|
||||
|
||||
|
|
@ -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'] = '弘訊科技股份有限公司'
|
||||
|
|
@ -171,6 +284,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
|
||||
for idx, row_data in report_df.iterrows():
|
||||
|
|
@ -183,45 +300,36 @@ 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)
|
||||
|
||||
# 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 = center_align
|
||||
ws['B1'].alignment = Alignment(horizontal='center', vertical='center', wrap_text=True)
|
||||
ws['B2'].font = Font(bold=True, size=12)
|
||||
ws['B2'].alignment = center_align
|
||||
ws['B2'].alignment = Alignment(horizontal='center', vertical='center', wrap_text=True)
|
||||
ws['B3'].font = Font(size=10, italic=True)
|
||||
ws['B3'].alignment = wrap_align
|
||||
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')
|
||||
|
||||
# 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, # 專案名稱
|
||||
|
|
@ -237,8 +345,22 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam
|
|||
|
||||
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
|
||||
|
|
@ -161,3 +161,6 @@ cython_debug/
|
|||
#.idea/
|
||||
|
||||
uv.lock
|
||||
temp/
|
||||
output/
|
||||
logs/
|
||||
|
|
|
|||
166
README.md
166
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.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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<br>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 ✅
|
||||
|
|
@ -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])}")
|
||||
```
|
||||
|
|
@ -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
|
||||
|
||||
```
|
||||
Binary file not shown.
Binary file not shown.
Loading…
Reference in New Issue