# WorkClock - Salary Calculator - Full Documentation

## Project Overview
WorkClock is a free, open-source salary calculator designed for office workers. It helps workers understand the true value of their time by calculating earnings in various time units.

## Project Structure
```
workclock/
├── index.html          # Main page
├── about.html          # About page
├── privacy.html        # Privacy policy
├── terms.html          # Terms of service
├── contact.html        # Contact page
├── manifest.json       # PWA manifest
├── sw.js               # Service Worker
├── css/
│   └── style.css       # All styles
├── js/
│   ├── i18n.js         # Internationalization
│   ├── holidays.js     # Chinese holidays
│   ├── salary.js       # Salary calculator
│   ├── export.js       # Data export
│   ├── chart.js        # Chart renderer
│   └── app.js          # Main app
└── public/
    ├── sitemap.xml     # SEO sitemap
    ├── robots.txt      # Crawler instructions
    ├── llms.txt        # AI-readable summary
    ├── llms-full.txt   # This file
    ├── weixin.png      # WeChat QR
    ├── whatsapp.jpg    # WhatsApp QR
    └── youtube.png     # YouTube icon
```

## Core Features

### 1. Salary Calculation Engine (js/salary.js)
- **STORAGE_KEY**: 'salary_settings'
- **Default Settings**: Monthly salary 10000, work time 09:00-18:00
- **Methods**:
  - `loadSettings()`: Load from localStorage
  - `saveSettings(settings)`: Save to localStorage
  - `calculateWorkHoursPerDay()`: Calculate daily work hours
  - `calculateSalaryPerSecond()`: Core calculation
  - `calculateTodayEarnings()`: Today's earnings
  - `calculateMonthEarnings()`: This month
  - `calculateYearEarnings()`: This year
  - `calculateTotalEarnings()`: From entry date
  - `getCountdown()`: Work countdown
  - `getStatistics()`: All stats combined

### 2. Holiday System (js/holidays.js)
- **CHINESE_HOLIDAYS**: Object with yearly holiday data
- **2024-2027**: Pre-configured holiday dates
- **Classes**: HolidayManager
  - `getHolidayDates(year)`: Get all holiday dates
  - `isHoliday(date)`: Check if date is holiday
  - `isWorkday(date)`: Check if workday
  - `getWorkDaysInMonth(year, month)`: Get workdays
  - `getNextHoliday()`: Next holiday info

### 3. Internationalization (js/i18n.js)
- **Translations**: en, zh
- **Class I18n**:
  - `setLocale(locale)`: Change language
  - `t(key, params)`: Get translation
  - `updatePageTranslations()`: Update all elements
- **Stored in**: localStorage 'locale'

### 4. Data Export (js/export.js)
- **Class DataExporter**:
  - `generateCSVData()`: Create CSV data
  - `exportToCSV()`: Download CSV
  - `exportToExcel()`: Download Excel
  - `generateWeeklyData()`: Week statistics
  - `generateMonthlyData()`: Month statistics
  - `generateYearlyData()`: Year statistics
  - `exportSettings()`: Backup settings
  - `importSettings(file)`: Restore settings

### 5. Chart Rendering (js/chart.js)
- **Class ChartRenderer**:
  - `drawBarChart()`: Bar charts
  - `drawLineChart()`: Line charts
  - `drawPieChart()`: Pie charts
  - `renderWeeklyChart()`: Weekly bars
  - `renderMonthlyChart()`: Monthly line
  - `renderYearlyChart()`: Yearly bars
  - `renderWorkDaysPieChart()`: Work distribution

### 6. Main Application (js/app.js)
- **Class WorkClockApp**:
  - `init()`: Initialize app
  - `initTheme()`: Setup theme
  - `toggleTheme()`: Switch light/dark
  - `initSettings()`: Setup settings modal
  - `startTimer()`: Start 1-second updates
  - `updateUI()`: Update all displays
  - `renderCalendar()`: Draw calendar
  - `showStatistics()`: Show charts modal

## HTML Structure

### Main Page (index.html)
- Header with navigation
- Ad banner (top)
- Main content area:
  - Left sidebar (ad)
  - Salary display section:
    - 4 salary cards (today, month, year, total)
    - Countdown ring with SVG
    - Stats grid
    - Calendar
    - Export buttons
  - Right sidebar (ad)
- Settings button (floating)
- Settings modal
- Statistics modal
- Page sections (about, guide, faq)
- Footer

### Ads Integration
Uses Google AdSense:
- Publisher ID: ca-pub-7466787647621398
- 5 ad slots:
  1. Top banner (slot: 1233038262)
  2. Left sidebar (slot: 5989706775)
  3. Right sidebar (slot: 9546642553)
  4. Bottom banner (slot: 1160508778)
  5. Settings modal (optional)

## CSS Architecture (css/style.css)

### Variables
```css
:root {
  --primary: #fbbf24;
  --secondary: #f59e0b;
  --bg-primary: #f9fafb;
  --bg-secondary: #ffffff;
  --text-primary: #1f2937;
  --text-secondary: #6b7280;
  --border-color: #e5e7eb;
  --card-bg: #ffffff;
}
```

### Dark Mode
```css
[data-theme="dark"] {
  --bg-primary: #1a1a1a;
  --bg-secondary: #2d2d2d;
  --text-primary: #ffffff;
  --text-secondary: #a0a0a0;
  --border-color: #404040;
  --card-bg: #2d2d2d;
}
```

### Key Components
- Header: Sticky, shadow
- Navigation: Flexbox, responsive
- Salary cards: Grid, hover effects
- Countdown ring: SVG circle
- Calendar: CSS Grid
- Modals: Fixed position, backdrop
- Responsive breakpoints:
  - 1024px: Hide sidebars
  - 768px: Stack layout
  - 480px: Mobile

## PWA Implementation

### manifest.json
- name: WorkClock - Salary Calculator
- display: standalone
- theme_color: #fbbf24
- icons: 192x192, 512x512

### Service Worker (sw.js)
- Cache name: workclock-v1
- Precache: All static files
- Strategy: Cache-first
- Events: install, activate, fetch, message, sync

## SEO

### sitemap.xml
- All 5 pages included
- Priorities: 1.0 (home), 0.8 (about), 0.6 (contact), 0.5 (legal)
- Changefreq: weekly to yearly

### robots.txt
- Allow all crawlers
- Sitemap reference

## Browser APIs Used
- localStorage
- Service Worker API
- Canvas API
- File API (export)
- Notification API (future)

## Performance
- No external dependencies (except Google APIs)
- Minimal bundle size
- Lazy loading for ads
- Offline-capable

## Security
- No user authentication
- No server-side code
- All data client-side
- HTTPS required for PWA

## Future Enhancements
- Cloud sync
- More languages
- Additional export formats
- Push notifications
- Widget mode
- Browser extension