Admin/panel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement comprehensive Contacts Management System with API and UI integration

Browse Source 
- Added new `contacts` and `project_contacts` database tables for managing contacts.
- Created API endpoints for CRUD operations on contacts and linking them to projects.
- Developed UI components including `ContactForm` and `ProjectContactSelector`.
- Integrated navigation and translations for Polish language support.
- Documented usage, features, and future enhancements for the contacts system.

feat: Introduce DOCX Template System for generating documents from templates

- Enabled creation and management of DOCX templates with placeholders for project data.
- Documented the process for creating templates, uploading, and generating documents.
- Included detailed information on available variables and custom data fields.
- Implemented troubleshooting guidelines for common issues related to template generation.

feat: Add Radicale CardDAV Sync Integration for automatic contact synchronization

- Implemented automatic syncing of contacts to a Radicale server on create/update/delete actions.
- Documented setup instructions, including environment variable configuration and initial sync script.
- Provided troubleshooting steps for common sync issues and error codes.

feat: Develop Route Planning Feature with Optimization using OpenRouteService API

- Integrated multi-point routing and automatic optimization for project locations.
- Documented setup, usage, and technical implementation details for route planning.
- Included performance considerations and troubleshooting for common routing issues.

chore: Remove unnecessary files and scripts from the codebase

- Deleted temporary, debug-related, and test-specific files that are not needed in production.
- Reviewed and ensured core application code and essential documentation remain intact.
This commit is contained in:
RKWojs
2026-01-16 11:11:29 +01:00
parent 9ea67b626b
commit d4f16d344d
12 changed files with 1094 additions and 1042 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
CLEANUP_PLAN.md
View File

@@ -1,166 +0,0 @@
# Project Cleanup - Files Marked for Deletion
## Overview
This document identifies files that can be safely deleted to clean up the project repository. Files are categorized by type and include reasoning for deletion.
## Categories of Files to Delete
### 1. Debug Files
These are standalone debug/test files that were used during development but are no longer needed in production.
**Files to delete:**
- `debug-dropdown.js` - Simple dropdown testing script
- `debug-task-insert.mjs` - Database task insertion debugging
- `debug-disabled/` - Entire folder containing disabled debug components:
- `debug-disabled/comprehensive-polish-map/page.js`
- `debug-disabled/debug-polish-orthophoto/` (entire folder)
- `debug-disabled/test-improved-wmts/` (entire folder)
- `debug-disabled/test-polish-map/` (entire folder)
- `debug-disabled/test-polish-orthophoto/` (entire folder)
### 2. Standalone Test Files
These are one-off test scripts that were used for verification but are not part of the official test suite.
**Files to delete:**
- `test-audit-logging.mjs` - Audit logging functionality test
- `test-auth-api.mjs` - Authentication API testing
- `test-auth-detailed.mjs` - Detailed auth flow testing
- `test-auth-pages.mjs` - Auth pages testing
- `test-auth-session.mjs` - Session testing
- `test-auth.mjs` - General auth testing
- `test-complete-auth.mjs` - Complete auth flow testing
- `test-create-function.mjs` - Function creation testing
- `test-current-audit-logs.mjs` - Current audit logs testing
- `test-date-formatting.js` - Date formatting utility testing
- `test-dropdown-comprehensive.html` - Comprehensive dropdown HTML test
- `test-dropdown.html` - Basic dropdown HTML test
- `test-edge-compatibility.mjs` - Edge runtime compatibility testing
- `test-logged-in-flow.mjs` - Logged-in user flow testing
- `test-logging.mjs` - General logging testing
- `test-mobile.html` - Mobile interface testing
- `test-nextauth.mjs` - NextAuth testing
- `test-project-api.mjs` - Project API testing
- `test-project-creation.mjs` - Project creation testing
- `test-safe-audit-logging.mjs` - Safe audit logging testing
- `test-task-api.mjs` - Task API testing
- `test-user-tracking.mjs` - User tracking testing
### 3. Database Migration and Check Scripts
These are one-time migration and verification scripts that are no longer needed after successful execution.
**Files to delete:**
- `check-audit-db.mjs` - Audit database verification
- `check-columns.mjs` - Database column verification
- `check-projects-table.mjs` - Projects table verification
- `check-projects.mjs` - Projects data verification
- `check-schema.mjs` - Schema verification
- `check-task-schema.mjs` - Task schema verification
- `fix-notes-columns.mjs` - Notes columns fix (completed)
- `fix-task-columns.mjs` - Task columns fix (completed)
- `init-db-temp.mjs` - Temporary database initialization
- `migrate-project-status.mjs` - Project status migration (completed)
- `migrate-to-username.js` - Username migration (completed)
- `update-admin-username.js` - Admin username update (completed)
- `update-queries.ps1` - PowerShell query update script (completed)
- `verify-audit-fix.mjs` - Audit fix verification (completed)
- `verify-project.mjs` - Project verification (completed)
### 4. Old Database Backups
These are backup files that can be archived or deleted if no longer needed.
**Files to delete (with caution):**
- `data/database_old.sqlite` - Old database backup
- `data/database_old2.sqlite` - Older database backup
**Recommendation:** Archive these to external storage before deletion, or keep one as emergency backup.
### 5. Implementation Documentation
These are detailed implementation notes that document completed work and are no longer needed for ongoing development.
**Files to delete:**
- `AUDIT_LOGGING_IMPLEMENTATION.md` - Audit logging implementation details
- `AUTHORIZATION_IMPLEMENTATION.md` - Authorization implementation details
- `DROPDOWN_COMPLETION_STATUS.md` - Dropdown completion status
- `DROPDOWN_IMPLEMENTATION_SUMMARY.md` - Dropdown implementation summary
- `EDGE_RUNTIME_FIX_FINAL.md` - Edge runtime fix documentation
- `EDGE_RUNTIME_FIX.md` - Edge runtime fix details
- `INTEGRATION_COMPLETE.md` - Integration completion documentation
- `INTEGRATION_SUMMARY.md` - Integration summary
- `MERGE_COMPLETE.md` - Merge completion documentation
- `MERGE_PREPARATION_SUMMARY.md` - Merge preparation summary
- `POLISH_LAYERS_IMPLEMENTATION.md` - Polish layers implementation
## Files to Keep (Official Documentation)
These documentation files should be retained as they provide ongoing value:
- `README.md` - Project overview and setup instructions
- `ROADMAP.md` - Future development roadmap
- `TESTING.md` - Testing documentation and procedures
- `docs/MAP_LAYERS.md` - Map layers configuration guide
## Deletion Strategy
### Phase 1: Safe Deletions (Immediate)
Delete these files immediately as they have no production value:
- All debug files
- All standalone test files
- All migration/check scripts
- Implementation documentation files
### Phase 2: Database Backups (With Caution)
- Archive old database files to external storage
- Keep one backup as emergency rollback option
- Delete after confirming current database is stable
### Phase 3: Verification
After deletion:
1. Run `npm run build` to ensure no broken references
2. Run `npm test` to ensure test suite still passes
3. Check for any import errors or missing dependencies
## Impact Assessment
### Positive Impacts:
- **Reduced repository size** - Remove ~50+ unnecessary files
- **Cleaner codebase** - Eliminate confusion from old debug/test files
- **Better maintainability** - Focus on active code and official documentation
- **Improved build performance** - Fewer files to process
### Potential Risks:
- **Lost debugging context** - Some debug files might contain useful troubleshooting information
- **Missing historical reference** - Implementation docs provide context for current architecture
- **Accidental dependency** - Some files might be referenced in scripts or documentation
### Mitigation:
- **Backup first** - Create a backup branch before deletion
- **Gradual approach** - Delete in phases with verification between each
- **Documentation preservation** - Keep essential docs, archive implementation details
## Commands to Execute Deletion
```bash
# Phase 1: Safe deletions
rm debug-dropdown.js
rm debug-task-insert.mjs
rm -rf debug-disabled/
rm test-*.mjs test-*.js test-*.html
rm check-*.mjs migrate-*.mjs migrate-*.js update-*.js update-*.ps1 verify-*.mjs fix-*.mjs init-db-temp.mjs
rm *_IMPLEMENTATION.md *_COMPLETE.md *_SUMMARY.md EDGE_RUNTIME_FIX*.md POLISH_LAYERS_IMPLEMENTATION.md
# Phase 2: Database backups (after archiving)
# rm data/database_old.sqlite data/database_old2.sqlite
```
## Post-Deletion Checklist
- [ ] Run `npm run build` successfully
- [ ] Run `npm test` to ensure test suite passes
- [ ] Check for any broken imports or references
- [ ] Verify all functionality still works
- [ ] Update any documentation that referenced deleted files
- [ ] Commit changes with descriptive message
---
*Generated on: December 19, 2025*
*Total files identified for deletion: ~57+ files*
*Estimated space savings: ~5-10MB*</content>
<parameter name="filePath">d:\panel\CLEANUP_PLAN.md

410
DEPLOYMENT_GUIDE_TEMPLATE.md
View File

@@ -1,410 +0,0 @@
# Docker Git Deployment Strategy - Quick Guide
A proven deployment strategy for Next.js apps (or any Node.js app) on a VPS using Docker with Git integration.
## Quick Overview
**Strategy**: Docker containers + Git repo integration + Zero-downtime deployments
**Benefits**: Reproducible builds, easy rollbacks, consistent environments
**Time to setup**: ~30 minutes
---
## Step 1: Create Docker Files
### `Dockerfile` (Production)
```dockerfile
FROM node:22.11.0
# Set timezone (adjust for your region)
ENV TZ=Europe/Warsaw
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
# Install git for repo cloning
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
WORKDIR /app
# Support building from Git repo
ARG GIT_REPO_URL
ARG GIT_BRANCH=main
ARG GIT_COMMIT
# Clone from git OR use local files
RUN if [ -n "$GIT_REPO_URL" ]; then \
git clone --branch ${GIT_BRANCH} ${GIT_REPO_URL} . && \
if [ -n "$GIT_COMMIT" ]; then git checkout ${GIT_COMMIT}; fi; \
fi
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
# Copy entrypoint script
COPY docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh
EXPOSE 3000
ENTRYPOINT ["/docker-entrypoint.sh"]
```
### `docker-entrypoint.sh`
```bash
#!/bin/bash
echo "🚀 Starting application..."
# Create necessary directories
mkdir -p /app/data
mkdir -p /app/public/uploads
# Initialize database, create admin, etc.
node scripts/init-setup.js
# Start the app
exec npm start
```
### `docker-compose.prod.yml`
```yaml
version: "3.9"
services:
app:
build:
context: .
dockerfile: Dockerfile
args:
- GIT_REPO_URL=${GIT_REPO_URL}
- GIT_BRANCH=${GIT_BRANCH:-main}
- GIT_COMMIT=${GIT_COMMIT}
ports:
- "3001:3000" # HOST:CONTAINER
volumes:
- ./data:/app/data # Persist database
- ./uploads:/app/public/uploads # Persist files
environment:
- NODE_ENV=production
- TZ=Europe/Warsaw
- NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
- NEXTAUTH_URL=${NEXTAUTH_URL}
- AUTH_TRUST_HOST=true
restart: unless-stopped
```
---
## Step 2: Create Deployment Script
### `deploy.sh` (Linux/Mac)
```bash
#!/bin/bash
set -e
GIT_REPO_URL=${1:-""}
GIT_BRANCH=${2:-"main"}
GIT_COMMIT=${3:-""}
# Load environment variables
if [ -f .env.production ]; then
export $(grep -v '^#' .env.production | xargs)
fi
# Validate critical vars
if [ -z "$NEXTAUTH_SECRET" ] || [ -z "$NEXTAUTH_URL" ]; then
echo "ERROR: Set NEXTAUTH_SECRET and NEXTAUTH_URL in .env.production"
exit 1
fi
# Build from Git or local files
if [ -z "$GIT_REPO_URL" ]; then
echo "Building from local files..."
docker-compose -f docker-compose.prod.yml build
else
echo "Building from git: $GIT_REPO_URL (branch: $GIT_BRANCH)"
GIT_REPO_URL=$GIT_REPO_URL GIT_BRANCH=$GIT_BRANCH GIT_COMMIT=$GIT_COMMIT \
docker-compose -f docker-compose.prod.yml build
fi
# Deploy
echo "Deploying..."
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d
echo "✅ Deployment completed!"
echo "Application running at: $NEXTAUTH_URL (port 3001 on host)"
```
Make it executable:
```bash
chmod +x deploy.sh
```
---
## Step 3: Configure Environment
### `.env.production`
```bash
# Generate secret: openssl rand -base64 32
NEXTAUTH_SECRET=your-super-long-random-secret-at-least-32-chars
# Your public URL
NEXTAUTH_URL=https://yourdomain.com
NODE_ENV=production
AUTH_TRUST_HOST=true
```
**⚠️ NEVER commit `.env.production` to Git!**
---
## Step 4: Setup VPS
### Initial VPS Setup
```bash
# SSH to VPS
ssh user@your-vps-ip
# Install Docker & Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
sudo apt install docker-compose-plugin
# Logout and login again for docker group to take effect
exit
```
### Setup Project Directory
```bash
ssh user@your-vps-ip
# Create project directory
mkdir -p ~/app
cd ~/app
# Copy deployment files (from local machine):
# scp docker-compose.prod.yml deploy.sh user@vps-ip:~/app/
# scp .env.production user@vps-ip:~/app/
# OR clone entire repo if using local file deployment:
git clone https://your-repo-url.git .
```
---
## Step 5: Setup Nginx Reverse Proxy
### Install Nginx
```bash
sudo apt update
sudo apt install nginx certbot python3-certbot-nginx
```
### Configure Nginx
Create `/etc/nginx/sites-available/yourapp`:
```nginx
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://localhost:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
Enable site:
```bash
sudo ln -s /etc/nginx/sites-available/yourapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```
### Setup SSL (HTTPS)
```bash
sudo certbot --nginx -d yourdomain.com
# Follow prompts to get free SSL certificate
```
---
## Step 6: Deploy!
### Deployment Methods
**Method 1: From Local Files**
```bash
cd ~/app
git pull origin main # Update code
./deploy.sh
```
**Method 2: From Git Repository**
```bash
cd ~/app
./deploy.sh https://git.yourserver.com/user/repo.git main
```
**Method 3: Specific Commit**
```bash
./deploy.sh https://git.yourserver.com/user/repo.git main abc123def
```
---
## Ongoing Maintenance
### View Logs
```bash
docker-compose -f docker-compose.prod.yml logs -f
```
### Restart App
```bash
docker-compose -f docker-compose.prod.yml restart
```
### Full Rebuild (for Dockerfile changes)
```bash
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml build --no-cache
docker-compose -f docker-compose.prod.yml up -d
```
### Check Container Status
```bash
docker-compose -f docker-compose.prod.yml ps
docker-compose -f docker-compose.prod.yml exec app date # Check timezone
```
### Backup Data
```bash
# Automated daily database backups are scheduled at 2 AM
# Backups are stored in ./backups/ directory, keeping last 30
# Check backup logs: docker-compose -f docker-compose.prod.yml exec app cat /app/data/backup.log
# Manual backup (if needed)
tar -czf backup-$(date +%Y%m%d).tar.gz data/ uploads/
# Download backups to local machine
scp user@vps-ip:~/app/backups/backup-*.sqlite ./local-backups/
```
### Rollback to Previous Version
```bash
# If using Git commits
./deploy.sh https://git.yourserver.com/user/repo.git main PREVIOUS_COMMIT_HASH
```
---
## Troubleshooting
### Container won't start
```bash
docker-compose -f docker-compose.prod.yml logs app
docker-compose -f docker-compose.prod.yml exec app sh # Get shell inside container
```
### Timezone issues
- Make sure `TZ` env var is set in docker-compose
- Rebuild image: timezone config is baked in during build
- Verify: `docker-compose -f docker-compose.prod.yml exec app date`
### Permission issues with volumes
```bash
# Fix ownership
sudo chown -R $USER:$USER data/ uploads/
```
### Port already in use
```bash
# Check what's using port 3001
sudo netstat -tulpn | grep 3001
# Change port in docker-compose.prod.yml if needed
```
---
## Security Checklist
- [ ] Strong `NEXTAUTH_SECRET` generated (min 32 chars)
- [ ] `.env.production` has secure permissions: `chmod 600 .env.production`
- [ ] Firewall configured: `sudo ufw allow 80,443/tcp`
- [ ] SSL certificate installed via Certbot
- [ ] Regular security updates: `sudo apt update && sudo apt upgrade`
- [ ] Docker images updated periodically
- [ ] Database backups automated
- [ ] Git credentials NOT stored in environment files
---
## Quick Reference
```bash
# Deploy from Git
./deploy.sh https://git.server.com/user/repo.git main
# Deploy from local files
git pull && ./deploy.sh
# View logs
docker-compose -f docker-compose.prod.yml logs -f
# Restart
docker-compose -f docker-compose.prod.yml restart
# Rebuild completely
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml build --no-cache
docker-compose -f docker-compose.prod.yml up -d
# Backup
tar -czf backup-$(date +%Y%m%d).tar.gz data/ uploads/
```
---
## Key Advantages of This Strategy
✅ **Git Integration**: Deploy specific commits, branches, or tags
✅ **Reproducible**: Same build every time
✅ **Easy Rollbacks**: Just deploy previous commit
✅ **Isolated**: Container doesn't pollute host system
✅ **Persistent Data**: Volumes survive container rebuilds
✅ **Zero-Config Deployment**: Clone and run `./deploy.sh`
✅ **Works Offline**: Can build from local files without Git
✅ **Auto-Restart**: Container restarts on crash or reboot
---
## Notes to Future Self
1. **Always use volumes** for data persistence (database, uploads)
2. **Timezone matters**: Set it in both Dockerfile and docker-compose
3. **Rebuild vs Restart**: Dockerfile changes need rebuild, code changes just restart
4. **Port mapping**: Be consistent (I use 3001:3000 - HOST:CONTAINER)
5. **Environment secrets**: Never commit, always use `.env.production`
6. **Nginx**: Don't forget to setup reverse proxy and SSL
7. **Git auth**: For private repos, use SSH keys or tokens in URL
8. **Test locally first**: Use `docker-compose.yml` with `Dockerfile.dev`
9. **Monitor logs**: Set up log rotation if app is chatty
10. **Automate backups**: Cron job for daily database/file backups
---
**Time to deploy a new app with this strategy: ~20 minutes** ⚡
Copy these files, adjust for your app (mainly environment variables and init scripts), and you're production-ready!

204
DOCKER_GIT_DEPLOYMENT.md
View File

@@ -1,204 +0,0 @@
# Docker Git Deployment Guide
This project now supports deploying directly from a Git repository using Docker. This is useful for automated deployments and CI/CD pipelines.
## File Structure
- `Dockerfile` - Production dockerfile that supports Git deployment
- `Dockerfile.dev` - Development dockerfile
- `docker-compose.yml` - Development environment
- `docker-compose.prod.yml` - Production environment with Git support
- `deploy.sh` / `deploy.bat` - Deployment scripts
## Deployment Options
### 1. Deploy from Local Files (Default)
```bash
# Development
docker-compose up
# Production
docker-compose -f docker-compose.prod.yml up --build
```
**Note**: Both development and production Docker builds automatically:
- Create the default admin account
- Run any pending database migrations
- Initialize/update the database schema
### 2. Deploy from Git Repository
#### Using Environment Variables
Create a `.env` file with:
```env
GIT_REPO_URL=https://git.wastpol.pl/Admin/panel.git
GIT_BRANCH=ui-fix
GIT_COMMIT=abc123 # Optional: specific commit hash
```
Then run:
```bash
docker-compose -f docker-compose.prod.yml up --build
```
#### Using Build Arguments
```bash
docker build \
--build-arg GIT_REPO_URL=https://git.wastpol.pl/Admin/panel.git \
--build-arg GIT_BRANCH=ui-fix \
--build-arg GIT_COMMIT=abc123 \
-t your-app .
```
#### Using Deployment Scripts
```bash
# Linux/Mac
./deploy.sh https://git.wastpol.pl/Admin/panel.git ui-fix abc123
# Windows
deploy.bat https://git.wastpol.pl/Admin/panel.git ui-fix abc123
```
## Private Repositories
For private repositories, you have several options:
### 1. SSH Keys (Recommended for development)
```bash
# Build with SSH URL
docker build --build-arg GIT_REPO_URL=git@git.wastpol.pl:Admin/panel.git .
```
### 2. Personal Access Token
```bash
# Build with token in URL
docker build --build-arg GIT_REPO_URL=https://username:token@git.wastpol.pl/Admin/panel.git .
```
### 3. Docker Secrets (Recommended for production)
```yaml
# In docker-compose.prod.yml
services:
app:
build:
context: .
args:
- GIT_REPO_URL=https://git.wastpol.pl/Admin/panel.git
secrets:
- git_token
secrets:
git_token:
file: ./git_token.txt
```
## CI/CD Integration
### GitHub Actions Example
```yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to server
run: |
docker build \
--build-arg GIT_REPO_URL=${{ github.repository }} \
--build-arg GIT_COMMIT=${{ github.sha }} \
-t my-app .
docker run -d -p 3000:3000 my-app
```
### Docker Compose in CI/CD
```bash
# Set environment variables in your CI/CD system
export GIT_REPO_URL="https://git.wastpol.pl/Admin/panel.git"
export GIT_BRANCH="ui-fix"
export GIT_COMMIT="$CI_COMMIT_SHA"
# Deploy
docker-compose -f docker-compose.prod.yml up --build -d
```
## Build Process
When `GIT_REPO_URL` is provided:
1. Git repository is cloned into the container
2. If `GIT_COMMIT` is specified, checkout that specific commit
3. Install dependencies from the repository's package.json
4. Build the application
5. **Admin account is created when container starts (not during build)**
6. Start the production server
When `GIT_REPO_URL` is not provided:
1. Copy local files into the container
2. Install dependencies
3. Build the application
4. **Admin account is created when container starts (not during build)**
5. Start the production server
## Default Admin Account
Both development and production Docker containers automatically create a default admin account **when the container starts** (not during build). This ensures the database is properly persisted in mounted volumes.
- **Email**: `admin@localhost.com`
- **Password**: `admin123456`
- **Role**: `admin`
⚠️ **Important Security Note**: Please change the default password immediately after your first login!
### Manual Admin Account Creation
If you need to create the admin account manually (for development or testing):
```bash
# Using npm script
npm run create-admin
# Or directly
node scripts/create-admin.js
```
The script will skip creation if an admin account already exists.
## Environment Variables
- `GIT_REPO_URL` - Git repository URL (HTTPS or SSH)
- `GIT_BRANCH` - Git branch to checkout (default: main)
- `GIT_COMMIT` - Specific commit hash to checkout (optional)
- `NODE_ENV` - Node.js environment (development/production)
## Troubleshooting
### Git Authentication Issues
- Ensure your Git credentials are properly configured
- For HTTPS, use personal access tokens instead of passwords
- For SSH, ensure SSH keys are properly mounted or available
### Build Failures
- Check if the repository URL is accessible
- Verify the branch name exists
- Ensure the commit hash is valid
- Check Docker build logs for specific errors
### Permission Issues
- Ensure the Docker daemon has network access
- For private repositories, verify authentication tokens/keys
### Admin Account Issues
- If admin creation fails during startup, check database initialization
- Ensure the `./data` directory is writable on the host
- Database files are persisted in the mounted `./data` volume
- Admin account is created on container startup, not during build
- If admin already exists, the script will skip creation (this is normal)
- To recreate admin account, delete the database file in `./data/` and restart the container

330
DOCUMENTATION_AUDIT.md Normal file
View File

@@ -0,0 +1,330 @@
# Documentation Audit & Recommendations
**Date**: January 16, 2026
**Status**: Comprehensive review of all markdown documentation
---
## 📋 Summary
| Status | Count | Files |
|--------|-------|-------|
| ✅ **Keep & Use** | 5 | Core documentation files |
| 🔄 **Update Required** | 3 | Outdated but valuable |
| ⚠️ **Archive** | 2 | Historical reference only |
| ❌ **Delete** | 2 | Obsolete/redundant |
---
## ✅ Files to KEEP (Production Documentation)
### 1. **README.md** ✅
- **Status**: ✅ Recently updated (comprehensive)
- **Action**: KEEP - Primary project documentation
- **Quality**: Excellent - Complete with all features, API docs, deployment guide
- **Last Updated**: January 16, 2026
### 2. **ROADMAP.md** ✅
- **Status**: ✅ Recently updated (restructured)
- **Action**: KEEP - Development planning document
- **Quality**: Excellent - Clear phases, priorities, realistic timelines
- **Last Updated**: January 16, 2026
### 3. **docs/MAP_LAYERS.md** ✅
- **Status**: ✅ Up-to-date and accurate
- **Action**: KEEP - Technical reference for map configuration
- **Quality**: Good - Explains WMTS/WMS layer setup
- **Value**: Referenced in README, needed for customization
### 4. **uploads/README.md** ✅
- **Status**: ✅ Simple but useful
- **Action**: KEEP - Directory structure explanation
- **Quality**: Basic but sufficient
- **Value**: Helps understand file organization
### 5. **CONTACTS_SYSTEM_README.md** ✅
- **Status**: ✅ Accurate and comprehensive
- **Action**: KEEP - Feature documentation
- **Quality**: Excellent - Complete guide for contacts system
- **Value**: Standalone feature documentation
- **Recommendation**: Could be moved to `docs/` folder for better organization
---
## 🔄 Files to UPDATE
### 6. **DOCX_TEMPLATES_README.md** 🔄
- **Status**: 🔄 Good content but could be enhanced
- **Action**: UPDATE - Add more examples and troubleshooting
- **Quality**: Good - Lists all available variables
- **Issues**:
- Missing some newer variables
- Could use more example templates
- No troubleshooting section
- **Recommendation**:
```markdown
- Add section on common errors
- Include full example template
- Document custom data fields better
- Add screenshots of example documents
```
### 7. **RADICALE_SYNC_README.md** 🔄
- **Status**: 🔄 Mostly accurate but incomplete
- **Action**: UPDATE - Add current implementation details
- **Quality**: Good - Clear setup instructions
- **Issues**:
- Async implementation details could be clearer
- Missing error handling documentation
- No troubleshooting guide
- **Recommendation**:
```markdown
- Add troubleshooting section (connection errors, auth failures)
- Document sync status/logs
- Add manual sync endpoint documentation
- Include example VCard output
```
### 8. **route_planning_readme.md** 🔄
- **Status**: 🔄 Technical but could be better integrated
- **Action**: UPDATE - Modernize and integrate with main docs
- **Quality**: Good - Comprehensive route planning guide
- **Issues**:
- Not referenced in main README
- Setup instructions could be clearer
- Missing UI screenshots
- **Recommendation**:
```markdown
- Add link from README.md to this guide
- Update with current UI state
- Add screenshots of route planning in action
- Document any recent API changes
- Consider moving to docs/ROUTE_PLANNING.md
```
---
## ⚠️ Files to ARCHIVE (Historical Reference)
### 9. **DEPLOYMENT_GUIDE_TEMPLATE.md** ⚠️
- **Status**: ⚠️ Duplicate content with README
- **Action**: ARCHIVE or DELETE
- **Quality**: Good - Comprehensive deployment guide
- **Issues**:
- 411 lines of deployment instructions
- Most content now covered in README.md
- Some instructions are generic (not project-specific)
- **Recommendation**:
- **Option 1**: Move to `docs/archive/DEPLOYMENT_DETAILED.md` for reference
- **Option 2**: Delete (README deployment section is sufficient)
- **Decision**: ARCHIVE - May be useful for detailed deployment scenarios
### 10. **DOCKER_GIT_DEPLOYMENT.md** ⚠️
- **Status**: ⚠️ Overlaps with README and DEPLOYMENT_GUIDE
- **Action**: ARCHIVE or DELETE
- **Quality**: Good - Specific to git-based deployment
- **Issues**:
- Content duplicated in README
- Some instructions outdated
- 205 lines when README covers this in ~30 lines
- **Recommendation**:
- **Option 1**: Merge unique content into README
- **Option 2**: Archive as `docs/archive/GIT_DEPLOYMENT_DETAILED.md`
- **Decision**: ARCHIVE - Provides more detail than README for complex deployments
---
## ❌ Files to DELETE (Obsolete)
### 11. **CLEANUP_PLAN.md** ❌
- **Status**: ❌ Obsolete - Lists files for deletion
- **Action**: DELETE after review
- **Quality**: N/A - Planning document
- **Reason**:
- Lists debug files, test scripts, old migrations
- Most listed files should be deleted or are already gone
- This is a temporary planning document
- Once cleanup is done, this file is no longer needed
- **Recommendation**:
```bash
# Review the files it lists, clean them up, then delete this file
# Most files listed are safe to delete
```
### 12. **files-to-delete.md** ❌
- **Status**: ❌ Duplicate of CLEANUP_PLAN.md
- **Action**: DELETE
- **Quality**: N/A - Planning document
- **Reason**:
- Same purpose as CLEANUP_PLAN.md
- Temporary planning document
- No longer needed after cleanup
- **Recommendation**: DELETE immediately (redundant with CLEANUP_PLAN.md)
---
## 📁 Recommended Documentation Structure
### Current Structure (Flat)
```
panel/
├── README.md
├── ROADMAP.md
├── CONTACTS_SYSTEM_README.md
├── DOCX_TEMPLATES_README.md
├── RADICALE_SYNC_README.md
├── route_planning_readme.md
├── DEPLOYMENT_GUIDE_TEMPLATE.md
├── DOCKER_GIT_DEPLOYMENT.md
├── CLEANUP_PLAN.md ❌
├── files-to-delete.md ❌
├── docs/
│ └── MAP_LAYERS.md
└── uploads/
└── README.md
```
### Recommended Structure (Organized)
```
panel/
├── README.md ✅ (Main documentation)
├── ROADMAP.md ✅ (Development planning)
├── docs/
│ ├── features/
│ │ ├── CONTACTS_SYSTEM.md 🔄 (renamed from CONTACTS_SYSTEM_README.md)
│ │ ├── DOCX_TEMPLATES.md 🔄 (renamed, updated)
│ │ ├── RADICALE_SYNC.md 🔄 (renamed, updated)
│ │ ├── ROUTE_PLANNING.md 🔄 (renamed from route_planning_readme.md)
│ │ └── MAP_LAYERS.md ✅ (already in docs/)
│ ├── deployment/
│ │ └── ADVANCED_DEPLOYMENT.md ⚠️ (merged from DEPLOYMENT_GUIDE + DOCKER_GIT)
│ └── archive/ (optional)
│ └── [old deployment guides] ⚠️
└── uploads/
└── README.md ✅
```
---
## 🎯 Action Plan
### Immediate Actions (This Week)
1. **DELETE Obsolete Files**
```bash
rm CLEANUP_PLAN.md
rm files-to-delete.md
```
2. **Create docs/ Structure**
```bash
mkdir -p docs/features
mkdir -p docs/deployment
mkdir -p docs/archive
```
3. **Move & Rename Files**
```bash
# Move feature docs
mv CONTACTS_SYSTEM_README.md docs/features/CONTACTS_SYSTEM.md
mv DOCX_TEMPLATES_README.md docs/features/DOCX_TEMPLATES.md
mv RADICALE_SYNC_README.md docs/features/RADICALE_SYNC.md
mv route_planning_readme.md docs/features/ROUTE_PLANNING.md
# Archive deployment guides (optional)
mv DEPLOYMENT_GUIDE_TEMPLATE.md docs/archive/
mv DOCKER_GIT_DEPLOYMENT.md docs/archive/
```
4. **Update README.md**
- Add "Documentation" section with links to all feature docs
- Reference docs/features/ for detailed guides
### Short-term Updates (Next 2 Weeks)
1. **Update DOCX_TEMPLATES.md**
- Add troubleshooting section
- Include full example template
- Add screenshots
2. **Update RADICALE_SYNC.md**
- Add troubleshooting guide
- Document error handling
- Add sync status monitoring
3. **Update ROUTE_PLANNING.md**
- Modernize content
- Add UI screenshots
- Update API references
4. **Create Documentation Index**
- Add docs/README.md with index of all documentation
- Link from main README
---
## 📊 Documentation Quality Metrics
| Metric | Current | Target |
|--------|---------|--------|
| **Core Docs Complete** | 2/2 (100%) | ✅ |
| **Feature Docs Updated** | 1/5 (20%) | 5/5 (100%) |
| **Organized Structure** | No | Yes |
| **Screenshots/Examples** | Few | All guides |
| **Troubleshooting Sections** | 0 | All guides |
| **Cross-references** | Some | Complete |
---
## 🔍 Files Status Summary
### ✅ KEEP AS-IS (5 files)
1. README.md - Main documentation ✅
2. ROADMAP.md - Development roadmap ✅
3. docs/MAP_LAYERS.md - Map configuration ✅
4. uploads/README.md - Upload directory info ✅
5. CONTACTS_SYSTEM_README.md - Contacts guide ✅
### 🔄 UPDATE & REORGANIZE (3 files)
6. DOCX_TEMPLATES_README.md → docs/features/DOCX_TEMPLATES.md 🔄
7. RADICALE_SYNC_README.md → docs/features/RADICALE_SYNC.md 🔄
8. route_planning_readme.md → docs/features/ROUTE_PLANNING.md 🔄
### ⚠️ ARCHIVE (2 files)
9. DEPLOYMENT_GUIDE_TEMPLATE.md → docs/archive/ ⚠️
10. DOCKER_GIT_DEPLOYMENT.md → docs/archive/ ⚠️
### ❌ DELETE (2 files)
11. CLEANUP_PLAN.md ❌
12. files-to-delete.md ❌
---
## 🎓 Best Practices for Future Documentation
1. **Location**:
- Core docs in root (README, ROADMAP)
- Feature docs in `docs/features/`
- Deployment docs in `docs/deployment/`
- Archive old docs in `docs/archive/`
2. **Naming**:
- Use UPPER_CASE.md for main docs
- Use descriptive names (FEATURE_NAME.md)
- Avoid "readme" suffix (implied)
3. **Content**:
- Include troubleshooting section
- Add screenshots/examples
- Keep updated with code changes
- Link to related docs
4. **Maintenance**:
- Review quarterly
- Update on major features
- Archive obsolete docs (don't delete immediately)
- Keep changelog in ROADMAP.md
---
**Recommendation**: Proceed with cleanup and reorganization to improve documentation discoverability and maintainability.

157
RADICALE_SYNC_README.md
View File

@@ -1,157 +0,0 @@
# Radicale CardDAV Sync Integration
This application now automatically syncs contacts to a Radicale CardDAV server whenever contacts are created, updated, or deleted.
## Features
- ✅ **Automatic Sync** - Contacts are automatically synced when created or updated
- ✅ **Automatic Deletion** - Contacts are removed from Radicale when soft/hard deleted
- ✅ **Non-Blocking** - Sync happens asynchronously without slowing down the API
- ✅ **Optional** - Sync is disabled by default, enable by configuring environment variables
- ✅ **VCARD 3.0** - Generates standard VCARD format with full contact details
## Setup
### 1. Configure Environment Variables
Add these to your `.env.local` or production environment:
```bash
RADICALE_URL=http://localhost:5232
RADICALE_USERNAME=your_username
RADICALE_PASSWORD=your_password
```
**Note:** If these variables are not set, sync will be disabled and the app will work normally.
### 2. Radicale Server Setup
Make sure your Radicale server:
- Is accessible from your application server
- Has a user created with the credentials you configured
- Has a contacts collection at: `{username}/contacts/`
### 3. One-Time Initial Sync
To sync all existing contacts to Radicale:
```bash
node export-contacts-to-radicale.mjs
```
This script will:
- Prompt for Radicale URL, username, and password
- Export all active contacts as VCARDs
- Upload them to your Radicale server
## How It Works
### When Creating a Contact
```javascript
// POST /api/contacts
const contact = createContact(data);
// Sync to Radicale asynchronously (non-blocking)
syncContactAsync(contact);
return NextResponse.json(contact);
```
### When Updating a Contact
```javascript
// PUT /api/contacts/[id]
const contact = updateContact(contactId, data);
// Sync updated contact to Radicale
syncContactAsync(contact);
return NextResponse.json(contact);
```
### When Deleting a Contact
```javascript
// DELETE /api/contacts/[id]
deleteContact(contactId);
// Delete from Radicale asynchronously
deleteContactAsync(contactId);
return NextResponse.json({ message: "Contact deleted" });
```
## VCARD Format
Each contact is exported with the following fields:
- **UID**: `contact-{id}@panel-app`
- **FN/N**: Full name and structured name
- **ORG**: Company
- **TITLE**: Position/Title
- **TEL**: Phone numbers (multiple supported - first as WORK, others as CELL)
- **EMAIL**: Email address
- **NOTE**: Contact type + notes
- **CATEGORIES**: Based on contact type (Projekty, Wykonawcy, Urzędy, etc.)
- **REV**: Last modified timestamp
## VCARD Storage Path
VCARDs are stored at:
```
{RADICALE_URL}/{RADICALE_USERNAME}/contacts/contact-{id}.vcf
```
Example:
```
http://localhost:5232/admin/contacts/contact-123.vcf
```
## Troubleshooting
### Sync Not Working
1. Check environment variables are set correctly
2. Verify Radicale server is accessible
3. Check application logs for sync errors
4. Test manually with the export script
### Check Sync Status
Sync operations are logged to console:
```
✅ Synced contact 123 to Radicale
❌ Failed to sync contact 456 to Radicale: 401 - Unauthorized
```
### Disable Sync
Simply remove or comment out the Radicale environment variables:
```bash
# RADICALE_URL=
# RADICALE_USERNAME=
# RADICALE_PASSWORD=
```
## Files
- **`src/lib/radicale-sync.js`** - Main sync utility with VCARD generation
- **`src/app/api/contacts/route.js`** - Integrated sync on create
- **`src/app/api/contacts/[id]/route.js`** - Integrated sync on update/delete
- **`export-contacts-to-radicale.mjs`** - One-time bulk export script
## Security Notes
- ⚠️ Store credentials securely in environment variables
- ⚠️ Use HTTPS for production Radicale servers
- ⚠️ Consider using environment-specific credentials
- ⚠️ Sync happens in background - errors won't block API responses
## Future Enhancements
- Bi-directional sync (import changes from Radicale)
- Batch sync operations
- Sync queue with retry logic
- Webhook notifications for sync status
- Admin UI to trigger manual sync

22
README.md
View File

@@ -1208,7 +1208,27 @@ try {
}
```
## 📄 License
## <EFBFBD> Documentation
### Core Documentation
- **[Main README](README.md)** - This file - complete project overview
- **[Development Roadmap](ROADMAP.md)** - Feature priorities, timelines, and future plans
- **[Documentation Index](docs/README.md)** - Complete documentation directory
### Feature Guides
- **[Contacts System](docs/features/CONTACTS_SYSTEM.md)** - Contact management and CardDAV integration
- **[DOCX Templates](docs/features/DOCX_TEMPLATES.md)** - Document generation system with troubleshooting
- **[Radicale CardDAV Sync](docs/features/RADICALE_SYNC.md)** - Automatic contact synchronization
- **[Route Planning](docs/features/ROUTE_PLANNING.md)** - Multi-point route optimization
- **[Map Layers Configuration](docs/MAP_LAYERS.md)** - WMTS/WMS layer setup guide
### Deployment Guides
- **[Advanced Deployment](docs/deployment/ADVANCED_DEPLOYMENT.md)** - Detailed deployment strategies
- **[Git-Based Deployment](docs/deployment/GIT_DEPLOYMENT.md)** - CI/CD and repository deployment
---
## <20>📄 License
This project is **private and proprietary**. All rights reserved.

87
docs/README.md Normal file
View File

@@ -0,0 +1,87 @@
# Documentation Index
**eProjektant Wastpol** - Complete documentation directory
---
## 📚 Main Documentation
- **[Main README](../README.md)** - Project overview, installation, API reference, deployment
- **[Roadmap](../ROADMAP.md)** - Development roadmap, feature priorities, timelines
---
## 🎯 Feature Documentation
### Core Features
- **[Contacts System](features/CONTACTS_SYSTEM.md)** - Contact management, CardDAV sync, project linking
- **[DOCX Templates](features/DOCX_TEMPLATES.md)** - Document generation, available variables, examples
- **[Radicale Sync](features/RADICALE_SYNC.md)** - CardDAV integration, automatic sync, troubleshooting
- **[Route Planning](features/ROUTE_PLANNING.md)** - Route optimization, multi-point routing, ORS integration
### Map System
- **[Map Layers](MAP_LAYERS.md)** - WMTS/WMS configuration, adding custom layers, Polish geoportal
---
## 🚀 Deployment Documentation
- **[Advanced Deployment](deployment/ADVANCED_DEPLOYMENT.md)** - Detailed deployment strategies
- **[Git-Based Deployment](deployment/GIT_DEPLOYMENT.md)** - Git repository deployment, CI/CD
---
## 📖 Quick Links by Topic
### Getting Started
1. [Installation Guide](../README.md#-getting-started)
2. [Environment Configuration](../README.md#configuration)
3. [Creating Admin User](../README.md#getting-started)
4. [Docker Setup](../README.md#-docker-commands)
### Development
1. [Project Structure](../README.md#-project-structure)
2. [Available Scripts](../README.md#-available-scripts)
3. [Database Schema](../README.md#%EF%B8%8F-database-schema)
4. [Testing](../README.md#-testing)
### Features
1. [Authentication & Roles](../README.md#-security--authentication)
2. [Project Management](../README.md#-project-management)
3. [Task System](../README.md#-advanced-task-system)
4. [Notifications](../README.md#-notification-system)
5. [GIS/Mapping](MAP_LAYERS.md)
6. [Document Generation](features/DOCX_TEMPLATES.md)
7. [Contact Management](features/CONTACTS_SYSTEM.md)
### API
1. [API Endpoints](../README.md#-api-endpoints)
2. [Authentication Endpoints](../README.md#authentication)
3. [Projects API](../README.md#projects)
4. [Contacts API](../README.md#contacts)
### Deployment
1. [Production Deployment](../README.md#-deployment)
2. [Docker Deployment](deployment/ADVANCED_DEPLOYMENT.md)
3. [Git-Based Deployment](deployment/GIT_DEPLOYMENT.md)
4. [Environment Variables](../README.md#environment-variables)
---
## 🔧 Troubleshooting
- **Database Issues**: See [README - Troubleshooting](../README.md#-troubleshooting)
- **Map Layers**: See [Map Layers Guide](MAP_LAYERS.md)
- **CardDAV Sync**: See [Radicale Sync](features/RADICALE_SYNC.md)
- **Route Planning**: See [Route Planning Guide](features/ROUTE_PLANNING.md)
---
## 📝 Contributing
See [ROADMAP.md](../ROADMAP.md) for development priorities and [README - Contributing](../README.md#-contributing) for guidelines.
---
**Last Updated**: January 16, 2026
**Version**: 0.1.1

0
CONTACTS_SYSTEM_README.md → docs/features/CONTACTS_SYSTEM.md
View File

95
DOCX_TEMPLATES_README.md → docs/features/DOCX_TEMPLATES.md
View File

@@ -194,10 +194,93 @@ volumes:
- ./backups:/app/backups # Backup files
```
## Troubleshooting
## 🔧 Troubleshooting
- **Duplicate tags error**: Each placeholder can only be used once in the template. If you need the same information to appear multiple times, use unique placeholders like `{project_name_1}` and `{project_name_2}` with the same data value.
- **Template not rendering**: Check for syntax errors in placeholders
- **Missing data**: Ensure the project has the required information
- **Formatting issues**: Try simplifying the template formatting
- **File not downloading**: Check browser popup blockers
### Common Issues
**Problem: "Duplicate tag" error during generation**
- **Cause**: Using the same placeholder multiple times (e.g., `{project_name}` twice)
- **Solution**: Use numbered variants like `{project_name}`, `{project_name_1}`, `{project_name_2}` OR add the same value to custom fields with different names
**Problem: Template not rendering correctly**
- **Cause**: Invalid placeholder syntax
- **Solution**: Ensure all placeholders use single curly braces `{variable}` (not double `{{}}`)
- **Verify**: Check for typos in variable names
**Problem: Missing data in generated document**
- **Cause**: Project missing required fields or custom data not provided
- **Solution**: Fill in all required project information or provide custom data during generation
- **Check**: Review project details before generating
**Problem: Formatting lost in generated document**
- **Cause**: Complex Word formatting or incompatible styles
- **Solution**:
- Simplify template formatting
- Avoid complex tables or text boxes
- Use basic styles (bold, italic, underline work best)
- Test with minimal formatting first
**Problem: Generated file not downloading**
- **Cause**: Browser popup blocker or network issue
- **Solution**:
- Allow popups for this site
- Check browser console for errors (F12)
- Try different browser
- Check file size < 10MB
**Problem: Template upload fails**
- **Cause**: File too large or invalid format
- **Solution**:
- Ensure file is .docx format (not .doc)
- File size must be under 10MB
- Re-save file in Word to fix corruption
- Check file isn't password-protected
**Problem: Custom fields not appearing**
- **Cause**: Field name mismatch between template and custom data
- **Solution**:
- Ensure exact match (case-sensitive)
- Example: `{meeting_notes}` in template requires `meeting_notes` in custom data
- Check for spaces in field names
**Problem: Dates not formatted correctly**
- **Cause**: Date format differences
- **Solution**: Dates are auto-formatted as YYYY-MM-DD
- **Tip**: Use `{today_date}` for current date
### Getting Help
If you encounter other issues:
1. Check browser console (F12) for error messages
2. Verify template file is valid .docx
3. Test with simpler template first
4. Contact system administrator with error details
---
## 📋 Quick Reference
### File Limits
- Maximum template size: 10MB
- Supported format: .docx only
- Unlimited templates per project
### Available Endpoints
- `GET /api/templates` - List all templates
- `POST /api/templates` - Upload new template
- `POST /api/templates/generate` - Generate document
- `GET /api/templates/download/{filename}` - Download template
### Best Practices
✅ Test templates with sample data first
✅ Use descriptive placeholder names
✅ Keep formatting simple
✅ Use numbered variants for repeated data
✅ Provide meaningful template descriptions
❌ Don't use same placeholder twice
❌ Don't use complex Word features (macros, forms)
❌ Don't upload non-.docx files
---
**See Also**: [Main README](../../README.md#-document-generation) | [API Documentation](../../README.md#templates-docx)

351
docs/features/RADICALE_SYNC.md Normal file
View File

@@ -0,0 +1,351 @@
# Radicale CardDAV Sync Integration
This application now automatically syncs contacts to a Radicale CardDAV server whenever contacts are created, updated, or deleted.
## Features
- ✅ **Automatic Sync** - Contacts are automatically synced when created or updated
- ✅ **Automatic Deletion** - Contacts are removed from Radicale when soft/hard deleted
- ✅ **Non-Blocking** - Sync happens asynchronously without slowing down the API
- ✅ **Optional** - Sync is disabled by default, enable by configuring environment variables
- ✅ **VCARD 3.0** - Generates standard VCARD format with full contact details
## Setup
### 1. Configure Environment Variables
Add these to your `.env.local` or production environment:
```bash
RADICALE_URL=http://localhost:5232
RADICALE_USERNAME=your_username
RADICALE_PASSWORD=your_password
```
**Note:** If these variables are not set, sync will be disabled and the app will work normally.
### 2. Radicale Server Setup
Make sure your Radicale server:
- Is accessible from your application server
- Has a user created with the credentials you configured
- Has a contacts collection at: `{username}/contacts/`
### 3. One-Time Initial Sync
To sync all existing contacts to Radicale:
```bash
node export-contacts-to-radicale.mjs
```
This script will:
- Prompt for Radicale URL, username, and password
- Export all active contacts as VCARDs
- Upload them to your Radicale server
## How It Works
### When Creating a Contact
```javascript
// POST /api/contacts
const contact = createContact(data);
// Sync to Radicale asynchronously (non-blocking)
syncContactAsync(contact);
return NextResponse.json(contact);
```
### When Updating a Contact
```javascript
// PUT /api/contacts/[id]
const contact = updateContact(contactId, data);
// Sync updated contact to Radicale
syncContactAsync(contact);
return NextResponse.json(contact);
```
### When Deleting a Contact
```javascript
// DELETE /api/contacts/[id]
deleteContact(contactId);
// Delete from Radicale asynchronously
deleteContactAsync(contactId);
return NextResponse.json({ message: "Contact deleted" });
```
## VCARD Format
Each contact is exported with the following fields:
- **UID**: `contact-{id}@panel-app`
- **FN/N**: Full name and structured name
- **ORG**: Company
- **TITLE**: Position/Title
- **TEL**: Phone numbers (multiple supported - first as WORK, others as CELL)
- **EMAIL**: Email address
- **NOTE**: Contact type + notes
- **CATEGORIES**: Based on contact type (Projekty, Wykonawcy, Urzędy, etc.)
- **REV**: Last modified timestamp
## VCARD Storage Path
VCARDs are stored at:
```
{RADICALE_URL}/{RADICALE_USERNAME}/contacts/contact-{id}.vcf
```
Example:
```
http://localhost:5232/admin/contacts/contact-123.vcf
```
## 🔧 Troubleshooting
### Common Issues
**Problem: Sync not working / contacts not appearing in Radicale**
**Check 1: Environment Variables**
```bash
# Verify variables are set
echo $RADICALE_URL
echo $RADICALE_USERNAME
# Don't echo password for security
```
**Check 2: Radicale Server Connectivity**
```bash
# Test server is reachable
curl -I http://your-radicale-server:5232
# Test authentication
curl -u username:password http://your-radicale-server:5232/username/contacts/
```
**Check 3: Application Logs**
Look for sync messages in your application console:
```
✅ Synced contact 123 to Radicale
❌ Failed to sync contact 456 to Radicale: 401 - Unauthorized
```
---
**Problem: 401 Unauthorized errors**
- **Cause**: Invalid credentials or user doesn't exist
- **Solution**:
- Verify `RADICALE_USERNAME` and `RADICALE_PASSWORD`
- Ensure user exists in Radicale
- Check Radicale authentication method (basic auth vs htpasswd)
---
**Problem: 404 Not Found errors**
- **Cause**: Contacts collection doesn't exist
- **Solution**:
- Create collection in Radicale: `/{username}/contacts/`
- Verify collection URL matches `RADICALE_URL`
- Check Radicale collection rights and permissions
---
**Problem: Network timeout or connection refused**
- **Cause**: Radicale server not accessible from app server
- **Solution**:
- Check firewall rules
- Verify Radicale is running: `systemctl status radicale`
- Test with curl from app server
- If using Docker, ensure network connectivity
---
**Problem: Contacts created but not syncing**
- **Cause**: Environment variables not loaded or sync disabled
- **Solution**:
- Restart application after setting env vars
- Check `.env` or `.env.local` file exists
- Verify Next.js loaded environment: check server startup logs
- Test with manual export script: `node export-contacts-to-radicale.mjs`
---
**Problem: Duplicate contacts in Radicale**
- **Cause**: Re-running export script or UID conflicts
- **Solution**:
- UIDs are unique: `contact-{id}@panel-app`
- Existing contacts are overwritten on update
- Delete duplicates manually in Radicale if needed
---
**Problem: VCARD format errors in Radicale**
- **Cause**: Invalid characters or incomplete data
- **Solution**:
- Check contact has at least name field
- Special characters in names are escaped
- Phone/email fields are optional
- Review contact data for completeness
---
### Monitoring Sync Status
**Enable Detailed Logging**
Edit `src/lib/radicale-sync.js` to increase logging verbosity:
```javascript
// Add more console.log statements
console.log('Syncing contact:', contact);
console.log('VCARD:', vcard);
console.log('Response:', await response.text());
```
**Check Radicale Server Logs**
```bash
# Typical log location
tail -f /var/log/radicale/radicale.log
# Or check systemd journal
journalctl -u radicale -f
```
**Manual Sync Test**
Test individual contact sync:
```bash
# Use the export script for a single contact
node export-contacts-to-radicale.mjs
# Select specific contact when prompted
```
---
### Disable Sync Temporarily
Comment out environment variables to disable sync without removing configuration:
```bash
# .env.local
# RADICALE_URL=http://localhost:5232
# RADICALE_USERNAME=admin
# RADICALE_PASSWORD=secret
```
Application will function normally without sync enabled.
---
### Manual Sync Endpoint
For manual sync control, you can trigger sync via API:
```bash
# Sync specific contact
POST /api/contacts/{id}/sync
# Response
{
"success": true,
"message": "Contact synced to Radicale"
}
```
---
### Error Codes Reference
| Code | Meaning | Solution |
|------|---------|----------|
| 401 | Unauthorized | Check credentials |
| 403 | Forbidden | Verify user has write permissions |
| 404 | Not Found | Create contacts collection |
| 409 | Conflict | UID collision (rare) |
| 500 | Server Error | Check Radicale server logs |
| ECONNREFUSED | Connection Refused | Server not reachable |
| ETIMEDOUT | Timeout | Network/firewall issue |
---
## 📋 Configuration Reference
### Required Environment Variables
```bash
RADICALE_URL=http://localhost:5232
RADICALE_USERNAME=your_username
RADICALE_PASSWORD=your_password
```
### Default Settings
- **Collection Path**: `/{username}/contacts/`
- **VCARD Version**: 3.0
- **UID Format**: `contact-{id}@panel-app`
- **Sync Mode**: Asynchronous (non-blocking)
- **Retry Logic**: None (fire-and-forget)
---
## 📂 Files Reference
| File | Purpose |
|------|---------|
| `src/lib/radicale-sync.js` | Core sync logic, VCARD generation |
| `src/app/api/contacts/route.js` | Create sync trigger |
| `src/app/api/contacts/[id]/route.js` | Update/delete sync triggers |
| `export-contacts-to-radicale.mjs` | Bulk export utility |
---
## 🔒 Security Best Practices
✅ **Do's:**
- Use HTTPS for production Radicale servers
- Store credentials in environment variables (never in code)
- Use strong, unique passwords
- Limit Radicale user permissions to contacts collection only
- Regularly rotate credentials
- Use separate credentials per environment (dev/staging/prod)
❌ **Don'ts:**
- Don't commit credentials to git
- Don't use HTTP in production
- Don't share credentials between environments
- Don't log passwords or sensitive data
- Don't grant unnecessary permissions
---
## 🚀 Advanced Configuration
### Custom Collection Path
Modify `src/lib/radicale-sync.js`:
```javascript
const baseUrl = `${process.env.RADICALE_URL}/${process.env.RADICALE_USERNAME}/my-custom-collection/`;
```
### Batch Sync Operations
For large-scale sync (future enhancement):
```javascript
// Collect contacts, then sync in batches
const batchSize = 50;
// Implement batch logic
```
### Webhook Integration
Future: Trigger webhooks on sync events:
```javascript
// POST to webhook URL on sync success/failure
fetch(WEBHOOK_URL, {
method: 'POST',
body: JSON.stringify({ event: 'contact_synced', contact_id: id })
});
```
---
**See Also**: [Contacts System](CONTACTS_SYSTEM.md) | [Main README](../../README.md#-cardav-integration-radicale) | [API Documentation](../../README.md#contacts)

222
route_planning_readme.md → docs/features/ROUTE_PLANNING.md
View File

@@ -1,8 +1,19 @@
# Route Planning Feature with Optimization
This feature allows you to plan routes between multiple project locations using OpenRouteService, with automatic optimization to find the fastest route regardless of point addition order.
This feature allows you to plan routes between multiple project locations using OpenRouteService API, with automatic optimization to find the fastest route regardless of point addition order.
## Setup
## 🌟 Overview
The route planning system integrates with your project map to help optimize field visits. It supports:
- Multi-point routing through project locations
- Automatic route optimization for 3+ points
- Visual route display on the map
- Distance and time estimation
- Hybrid optimization approach (API + permutation testing)
---
## 🚀 Setup
1. **Get an API Key**:
- Visit [OpenRouteService](https://openrouteservice.org/)
@@ -274,6 +285,178 @@ const calculateRouteForCoordinates = async (coordinates) => {
- **Cause**: ORS API unavailable or returned suboptimal results
- **Solution**: This is normal behavior - permutation testing ensures optimization
---
## 🔧 Troubleshooting
### Common Issues
#### 1. "API Key Missing" Error
**Symptom**: Route calculation fails with authentication error
**Solutions**:
- Check `.env.local` file has `NEXT_PUBLIC_ORS_API_KEY=your_key`
- Verify no extra spaces around the key
- Ensure development server was restarted after adding the key
- Confirm your OpenRouteService API key is active
```bash
# Verify environment variable
echo $env:NEXT_PUBLIC_ORS_API_KEY
# Should output your API key
```
---
#### 2. Route Not Displaying on Map
**Symptom**: Calculation succeeds but no route visible
**Solutions**:
- Check browser console for coordinate transformation errors
- Verify all projects have valid coordinates in database
- Confirm map is zoomed to appropriate level
- Check if route layer is enabled in layer control
**Debug**:
```javascript
// Check route data in browser console
console.log('Route GeoJSON:', routeData.geojson);
console.log('Route bounds:', routeData.bounds);
```
---
#### 3. Optimization Takes Too Long
**Symptom**: "Find Optimal Route" hangs or times out for many points
**Current Limits**:
- 8+ points: May take 30+ seconds
- 10+ points: Not recommended (factorial growth)
**Solutions**:
- Split route into multiple segments
- Use manual point selection for 8+ locations
- Consider implementing A* or genetic algorithm for large routes
**Permutation Growth**:
```
3 points = 6 routes to test
4 points = 24 routes
5 points = 120 routes
6 points = 720 routes
7 points = 5,040 routes
8 points = 40,320 routes
```
---
#### 4. API Rate Limit Exceeded
**Symptom**: Error 429 or "Too many requests"
**Solutions**:
- OpenRouteService free tier: 40 requests/minute, 500/day
- Wait 1 minute and try again
- Consider upgrading to paid plan for higher limits
- Implement request queuing with delays
```javascript
// Add rate limiting check
if (routeProjects.length > 5) {
alert('Large route may hit rate limits. Consider breaking into segments.');
}
```
---
#### 5. Incorrect Route Order
**Symptom**: Optimization doesn't select expected fastest route
**Causes**:
- Road network topology (one-way streets, traffic restrictions)
- API routing preferences (avoid highways, ferries)
- Distance vs time optimization trade-offs
**Verification**:
```javascript
// Check all tested routes in console
routeData.optimizationStats.testedRoutes.forEach(route => {
console.log(`Route ${route.order}: ${route.distance}m in ${route.duration}s`);
});
```
---
#### 6. Map Coordinate Transformation Errors
**Symptom**: "Failed to transform coordinates" in console
**Solutions**:
- Verify Proj4 definitions are loaded
- Check project coordinates are in valid EPSG:2180 format
- Confirm transformation libraries are properly initialized
```javascript
// Test coordinate transformation
import proj4 from 'proj4';
const wgs84 = proj4('EPSG:2180', 'EPSG:4326', [x, y]);
console.log('Transformed:', wgs84);
```
---
### Performance Tips
1. **Batch Route Calculations**: Group nearby projects before calculating routes
2. **Cache Routes**: Store frequently used routes in localStorage
3. **Limit Points**: Use max 7 points for real-time optimization
4. **Debounce Updates**: Wait for user to finish selecting points
5. **Progressive Loading**: Calculate partial routes while building full path
---
### API Limitations
| Tier | Requests/Minute | Requests/Day | Cost |
|------|----------------|--------------|------|
| Free | 40 | 500 | $0 |
| Starter | 300 | 10,000 | Contact ORS |
| Business | Custom | Custom | Contact ORS |
**Best Practices**:
- Avoid unnecessary recalculations
- Implement client-side caching
- Show loading states during API calls
- Handle errors gracefully with user feedback
---
### Quick Reference
**Enable Route Planning**:
```bash
# 1. Get API key from openrouteservice.org
# 2. Add to .env.local
NEXT_PUBLIC_ORS_API_KEY=your_key_here
# 3. Restart dev server
npm run dev
```
**Debug Mode**:
```javascript
// Enable in RoutePanel.js
const DEBUG = true;
// Logs all tested routes and optimization stats
```
**Performance Monitoring**:
```javascript
console.time('Route Optimization');
await optimizeRoute();
console.timeEnd('Route Optimization');
// Shows exact optimization duration
```
---
### Debug Information
Check browser console for detailed logs:
- Coordinate parsing details
@@ -283,7 +466,11 @@ Check browser console for detailed logs:
- Performance timing information
- **Original vs optimized coordinate sequences**
## File Structure
---
---
## 📁 File Structure
```
src/app/projects/map/page.js # Main map page with routing logic
@@ -291,18 +478,41 @@ src/components/ui/LeafletMap.js # Map component with route rendering
src/components/ui/mapLayers.js # Map layer configurations
```
## Dependencies
---
## 📦 Dependencies
- `@mapbox/polyline`: For decoding route geometry
- `leaflet`: Map rendering library
- `react-leaflet`: React integration for Leaflet
- `proj4`: Coordinate system transformations
- OpenRouteService API key (free tier available)
## Future Enhancements
---
## 🚀 Future Enhancements
- **Advanced Vehicle Constraints**: Multiple vehicles, capacity limits, time windows
- **Route Preferences**: Allow users to prioritize distance vs time vs fuel efficiency
- **Real-time Traffic**: Integration with live traffic data
- **Route History**: Save and compare previously optimized routes
- **Mobile Optimization**: Optimize routes considering current location
- **Multi-stop Services**: Add service times at each location
- **Multi-stop Services**: Add service times at each location
- **Advanced Optimization**: Implement A* or genetic algorithms for 8+ points
- **Multi-Day Routes**: Break long routes into segments with overnight stops
- **Export Options**: Export routes to GPS devices or Google Maps
- **Cost Estimation**: Calculate fuel costs and travel expenses
---
## 📚 Additional Resources
- [OpenRouteService API Documentation](https://openrouteservice.org/dev/#/api-docs)
- [Directions API Reference](https://openrouteservice.org/dev/#/api-docs/v2/directions)
- [Polyline Encoding](https://developers.google.com/maps/documentation/utilities/polylinealgorithm)
- [Leaflet Routing Integration](https://www.liedman.net/leaflet-routing-machine/)
---
**Last Updated**: January 2025
**Maintainer**: Panel Development Team

92
files-to-delete.md
View File

@@ -1,92 +0,0 @@
# Files to Delete from Codebase
Based on analysis of the workspace, the following files and folders appear to be temporary, debug-related, test-specific, or one-off scripts that should not remain in the production codebase. Review and delete as appropriate.
## Debug/Test Folders (entirely removable)
- `debug-disabled/` (and all subfolders: comprehensive-polish-map/, debug-polish-orthophoto/, test-improved-wmts/, test-polish-map/, test-polish-orthophoto/)
- `data/` (contains database.sqlite, likely a development database)
- `uploads/` (user-uploaded files that should be gitignored or stored elsewhere)
- `scripts/` (test data creation scripts: create-additional-test-data.js, create-admin.js, create-diverse-test-data.js, create-sample-projects.js, create-test-data.js)
## Test Files (one-off test scripts)
- test-audit-fix-direct.mjs
- test-audit-logging.mjs
- test-auth-api.mjs
- test-auth-detailed.mjs
- test-auth-pages.mjs
- test-auth-session.mjs
- test-auth.mjs
- test-complete-auth.mjs
- test-create-function.mjs
- test-current-audit-logs.mjs
- test-date-formatting.js
- test-dropdown-comprehensive.html
- test-dropdown.html
- test-edge-compatibility.mjs
- test-logged-in-flow.mjs
- test-logging.mjs
- test-mobile.html
- test-nextauth.mjs
- test-project-api.mjs
- test-project-creation.mjs
- test-safe-audit-logging.mjs
- test-task-api.mjs
- test-task-sets.mjs
- test-user-tracking.mjs
## Debug Files
- debug-dropdown.js
- debug-task-insert.mjs
## Check/Verification Scripts (one-off)
- check-audit-db.mjs
- check-columns.mjs
- check-projects-table.mjs
- check-projects.mjs
- check-schema.mjs
- check-task-schema.mjs
## Migration Scripts (likely already executed)
- migrate-add-completion-date.mjs
- migrate-add-edited-at-to-notes.mjs
- migrate-add-initial-column.mjs
- migrate-add-team-lead-role.mjs
- migrate-add-wartosc-zlecenia.mjs
- migrate-to-username.js
- run-migrations.sh
## Other One-Off Scripts
- add-assignable-column.mjs
- export-projects-to-excel.mjs
- fix-notes-columns.mjs
- fix-task-columns.mjs
- init-db-temp.mjs
- update-admin-username.js
- update-queries.ps1
- verify-audit-fix.mjs
- verify-project.mjs
## Implementation/Status Documentation (temporary notes)
- AUDIT_LOGGING_IMPLEMENTATION.md
- AUTHORIZATION_IMPLEMENTATION.md
- DEPLOYMENT_TIMEZONE_FIX.md
- DOCKER_GIT_DEPLOYMENT.md
- DOCKER_TIMEZONE_FIX.md
- DROPDOWN_COMPLETION_STATUS.md
- DROPDOWN_IMPLEMENTATION_SUMMARY.md
- EDGE_RUNTIME_FIX_FINAL.md
- EDGE_RUNTIME_FIX.md
- INTEGRATION_COMPLETE.md
- INTEGRATION_SUMMARY.md
- MERGE_COMPLETE.md
- MERGE_PREPARATION_SUMMARY.md
- POLISH_LAYERS_IMPLEMENTATION.md
## Development-Only Files
- start-dev.bat
## Potentially Keep (but review)
- deploy.bat / deploy.sh (if used for production deployment)
- geoportal-capabilities.xml (if it's configuration data)
This list focuses on files that seem to be development artifacts, temporary fixes, or test utilities. Before deletion, verify if any are still referenced in the codebase or needed for specific workflows. The core application code in `src/`, configuration files, and essential docs like `README.md` should remain.