cleanup

2026-02-07 09:23:49 +00:00
parent 96eabe3db6
commit 36552903e7
85 changed files with 9820870 additions and 1767 deletions
--- a/bitbylaw/docs/INDEX.md
+++ b/bitbylaw/docs/INDEX.md
@@ -0,0 +1,194 @@
+# Documentation Index
+
+## Getting Started
+
+**New to the project?** Start here:
+
+1. [README.md](../README.md) - Project Overview & Quick Start
+2. [DEVELOPMENT.md](DEVELOPMENT.md) - Setup Development Environment
+3. [CONFIGURATION.md](CONFIGURATION.md) - Configure Environment Variables
+
+## Core Documentation
+
+### For Developers
+- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Complete development guide
+  - Setup, Coding Standards, Testing, Debugging
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design and architecture
+  - Components, Data Flow, Event-Driven Design
+- **[API.md](API.md)** - HTTP Endpoints and Event Topics
+  - Proxy API, Calendar Sync API, Webhook Endpoints
+
+### For Operations
+- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Production deployment
+  - Installation, systemd, nginx, Monitoring
+- **[CONFIGURATION.md](CONFIGURATION.md)** - Environment configuration
+  - All environment variables, secrets management
+- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Problem solving
+  - Common issues, debugging, log analysis
+
+### Special Topics
+- **[GOOGLE_SETUP.md](GOOGLE_SETUP.md)** - Google Service Account setup
+  - Step-by-step guide for Calendar API access
+
+## Component Documentation
+
+### Steps (Business Logic)
+
+**Advoware Proxy** ([Module README](../steps/advoware_proxy/README.md)):
+- [advoware_api_proxy_get_step.md](../steps/advoware_proxy/advoware_api_proxy_get_step.md)
+- [advoware_api_proxy_post_step.md](../steps/advoware_proxy/advoware_api_proxy_post_step.md)
+- [advoware_api_proxy_put_step.md](../steps/advoware_proxy/advoware_api_proxy_put_step.md)
+- [advoware_api_proxy_delete_step.md](../steps/advoware_proxy/advoware_api_proxy_delete_step.md)
+
+**Calendar Sync** ([Module README](../steps/advoware_cal_sync/README.md)):
+- [calendar_sync_cron_step.md](../steps/advoware_cal_sync/calendar_sync_cron_step.md) - Daily trigger
+- [calendar_sync_api_step.md](../steps/advoware_cal_sync/calendar_sync_api_step.md) - Manual trigger
+- [calendar_sync_all_step.md](../steps/advoware_cal_sync/calendar_sync_all_step.md) - Employee cascade
+- [calendar_sync_event_step.md](../steps/advoware_cal_sync/calendar_sync_event_step.md) - Per-employee sync (complex)
+
+**VMH Webhooks** ([Module README](../steps/vmh/README.md)):
+- [beteiligte_create_api_step.md](../steps/vmh/webhook/beteiligte_create_api_step.md) - Create webhook
+- [beteiligte_update_api_step.md](../steps/vmh/webhook/beteiligte_update_api_step.md) - Update webhook (similar)
+- [beteiligte_delete_api_step.md](../steps/vmh/webhook/beteiligte_delete_api_step.md) - Delete webhook (similar)
+- [beteiligte_sync_event_step.md](../steps/vmh/beteiligte_sync_event_step.md) - Sync handler (placeholder)
+
+### Services
+
+- [Advoware Service](../services/ADVOWARE_SERVICE.md) - API Client mit HMAC-512 Auth
+- [Advoware API Swagger](advoware/advoware_api_swagger.json) - Vollständige API-Dokumentation (JSON)
+
+### Utility Scripts
+
+- [Calendar Sync Scripts](../scripts/calendar_sync/README.md) - Wartung und Debugging
+  - `delete_employee_locks.py` - Redis Lock Cleanup
+  - `delete_all_calendars.py` - Google Calendar Reset
+
+---
+
+## Documentation Structure
+
+```
+docs/
+├── INDEX.md                  # This file
+├── ARCHITECTURE.md           # System design
+├── API.md                    # API reference
+├── CONFIGURATION.md          # Configuration
+├── DEPLOYMENT.md             # Deployment guide
+├── DEVELOPMENT.md            # Development guide
+├── GOOGLE_SETUP.md           # Google Calendar setup
+├── TROUBLESHOOTING.md        # Debugging guide
+└── advoware/
+    └── advoware_api_swagger.json  # Advoware API spec
+
+steps/{module}/
+├── README.md                 # Module overview
+└── {step_name}.md            # Step documentation
+
+services/
+└── {service_name}.md         # Service documentation
+
+scripts/{category}/
+├── README.md                 # Script documentation
+└── *.py                      # Utility scripts
+```
+
+## Documentation Standards
+
+### YAML Frontmatter
+
+Each step documentation includes metadata:
+
+```yaml
+---
+type: step
+category: api|event|cron
+name: Step Name
+version: 1.0.0
+status: active|deprecated|placeholder
+tags: [tag1, tag2]
+dependencies: [...]
+emits: [...]
+subscribes: [...]
+---
+```
+
+### Sections
+
+Standard sections in step documentation:
+
+1. **Zweck** - Purpose (one sentence)
+2. **Config** - Motia step configuration
+3. **Input** - Request structure, parameters
+4. **Output** - Response structure
+5. **Verhalten** - Behavior, logic flow
+6. **Abhängigkeiten** - Dependencies (services, Redis, APIs)
+7. **Testing** - Test examples
+8. **KI Guidance** - Tips for AI assistants
+
+### Cross-References
+
+- Use relative paths for links
+- Link related steps and services
+- Link to parent module READMEs
+
+## Quick Reference
+
+### Common Tasks
+
+| Task | Documentation |
+|------|---------------|
+| Setup development environment | [DEVELOPMENT.md](DEVELOPMENT.md#setup) |
+| Configure environment variables | [CONFIGURATION.md](CONFIGURATION.md) |
+| Deploy to production | [DEPLOYMENT.md](DEPLOYMENT.md#installation-steps) |
+| Setup Google Calendar | [GOOGLE_SETUP.md](GOOGLE_SETUP.md) |
+| Debug service issues | [TROUBLESHOOTING.md](TROUBLESHOOTING.md#service-issues) |
+| Understand architecture | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| Test API endpoints | [API.md](API.md) |
+
+### Code Locations
+
+| Component | Location | Documentation |
+|-----------|----------|---------------|
+| API Proxy Steps | `steps/advoware_proxy/` | [README](../steps/advoware_proxy/README.md) |
+| Calendar Sync Steps | `steps/advoware_cal_sync/` | [README](../steps/advoware_cal_sync/README.md) |
+| VMH Webhook Steps | `steps/vmh/` | [README](../steps/vmh/README.md) |
+| Advoware API Client | `services/advoware.py` | [DOC](../services/ADVOWARE_SERVICE.md) |
+| Configuration | `config.py` | [CONFIGURATION.md](CONFIGURATION.md) |
+
+## Contributing to Documentation
+
+### Adding New Step Documentation
+
+1. Create `{step_name}.md` next to `.py` file
+2. Use YAML frontmatter (see template)
+3. Follow standard sections
+4. Add to module README
+5. Add to this INDEX
+
+### Updating Documentation
+
+- Keep code and docs in sync
+- Update version history in step docs
+- Update INDEX when adding new files
+- Test all code examples
+
+### Documentation Reviews
+
+- Verify all links work
+- Check code examples execute correctly
+- Ensure terminology is consistent
+- Validate configuration examples
+
+## External Resources
+
+- [Motia Framework Docs](https://motia.dev) (if available)
+- [Advoware API](https://www2.advo-net.net:90/) (requires auth)
+- [Google Calendar API](https://developers.google.com/calendar)
+- [Redis Documentation](https://redis.io/documentation)
+
+## Support
+
+- **Questions**: Check TROUBLESHOOTING.md first
+- **Bugs**: Document in logs (`journalctl -u motia.service`)
+- **Features**: Propose in team discussions
+- **Urgent**: Check systemd logs and Redis state