From f4669d730e676d47ede42b66f48542e12acf1f99 Mon Sep 17 00:00:00 2001 From: "gitea-actions[bot]" Date: Sat, 9 May 2026 19:18:12 -0500 Subject: [PATCH] docs: sync wikis from Gitea (54 repos) --- .../client-waas-clarksvillefurs/Home.md | 69 ++ .../accessibility.md | 162 +++ .../authoring-README.-.-.md | 89 ++ .../authoring-ad-schedule.-.-.md | 138 +++ .../authoring-cross-post-preview.-.-.md | 238 ++++ .../authoring-quick-reference.-.-.md | 100 ++ .../authoring-screencast-script.-.-.md | 245 ++++ .../authoring-sop-moderation.-.-.md | 488 ++++++++ .../authoring-sop-website-management.-.-.md | 441 +++++++ .../authoring-style-guide.-.-.md | 178 +++ .../brand-reference.-.-.md | 158 +++ .../content-authoring.-.-.md | 184 +++ .../css-variables.-.-.md | 260 +++++ .../client-waas-clarksvillefurs/deployment.md | 180 +++ .../migration-plan-events.-.-.md | 248 ++++ .../theme-architecture.-.-.md | 151 +++ MokoConsulting/MokoCRM/Home.md | 27 + MokoConsulting/MokoCRM/README.md | 144 +++ MokoConsulting/MokoCRM/changelog.md | 58 + MokoConsulting/MokoCRM/development.md | 404 +++++++ MokoConsulting/MokoCRM/installation.md | 145 +++ .../MokoCRM/module-id-policy.-.-.md | 65 ++ MokoConsulting/MokoCRM/roadmap.md | 103 ++ MokoConsulting/MokoCRM/update-server.-.-.md | 112 ++ MokoConsulting/MokoDPCalendarAPI/Home.md | 28 + .../MokoDPCalendarAPI/INSTALLATION.md | 51 + MokoConsulting/MokoDoliAdInsights/Home.md | 46 + MokoConsulting/MokoDoliAdInsights/README.md | 243 ++++ .../MokoDoliAdInsights/adding-services.-.-.md | 309 +++++ .../MokoDoliAdInsights/architecture.md | 634 ++++++++++ .../MokoDoliAdInsights/changelog.md | 192 +++ .../MokoDoliAdInsights/development.md | 323 ++++++ .../MokoDoliAdInsights/installation.md | 310 +++++ .../module-id-policy.-.-.md | 260 +++++ .../quickstart-service.-.-.md | 222 ++++ .../MokoDoliAdInsights/update-server.-.-.md | 64 + MokoConsulting/MokoDoliArt/Home.md | 43 + MokoConsulting/MokoDoliArt/README.md | 148 +++ MokoConsulting/MokoDoliArt/changelog.md | 70 ++ MokoConsulting/MokoDoliArt/development.md | 323 ++++++ MokoConsulting/MokoDoliArt/installation.md | 173 +++ .../MokoDoliArt/module-id-policy.-.-.md | 260 +++++ .../MokoDoliArt/update-server.-.-.md | 64 + MokoConsulting/MokoDoliAuth/Home.md | 28 + .../MokoDoliAuth/update-server.-.-.md | 64 + MokoConsulting/MokoDoliCare/Home.md | 50 + MokoConsulting/MokoDoliCare/README.md | 317 +++++ .../MokoDoliCare/admin-guide.-.-.md | 966 +++++++++++++++ MokoConsulting/MokoDoliCare/changelog.md | 230 ++++ MokoConsulting/MokoDoliCare/development.md | 416 +++++++ .../MokoDoliCare/family-management.-.-.md | 291 +++++ MokoConsulting/MokoDoliCare/installation.md | 469 ++++++++ .../MokoDoliCare/module-id-policy.-.-.md | 260 +++++ .../MokoDoliCare/quick-start.-.-.md | 402 +++++++ .../MokoDoliCare/remote-checkin.-.-.md | 316 +++++ MokoConsulting/MokoDoliCare/roadmap.md | 505 ++++++++ .../MokoDoliCare/troubleshooting.md | 862 ++++++++++++++ .../MokoDoliCare/update-server.-.-.md | 64 + MokoConsulting/MokoDoliCare/user-guide.-.-.md | 863 ++++++++++++++ .../MokoDoliChimp/DEVELOPMENT_GUIDE.md | 647 +++++++++++ MokoConsulting/MokoDoliChimp/Home.md | 26 + MokoConsulting/MokoDoliClaude/Home.md | 43 + MokoConsulting/MokoDoliClaude/README.md | 148 +++ MokoConsulting/MokoDoliClaude/changelog.md | 70 ++ MokoConsulting/MokoDoliClaude/development.md | 323 ++++++ MokoConsulting/MokoDoliClaude/installation.md | 173 +++ .../MokoDoliClaude/module-id-policy.-.-.md | 260 +++++ .../MokoDoliClaude/update-server.-.-.md | 64 + MokoConsulting/MokoDoliCredits/Home.md | 41 + MokoConsulting/MokoDoliCredits/README.md | 148 +++ MokoConsulting/MokoDoliCredits/changelog.md | 70 ++ MokoConsulting/MokoDoliCredits/development.md | 323 ++++++ .../MokoDoliCredits/installation.md | 173 +++ .../MokoDoliCredits/module-id-policy.-.-.md | 260 +++++ .../MokoDoliCredits/update-server.-.-.md | 64 + MokoConsulting/MokoDoliDymo/Home.md | 43 + MokoConsulting/MokoDoliDymo/README.md | 39 + MokoConsulting/MokoDoliDymo/changelog.md | 33 + MokoConsulting/MokoDoliDymo/development.md | 142 +++ .../MokoDoliDymo/dymo-label-format.-.-.md | 162 +++ MokoConsulting/MokoDoliDymo/installation.md | 90 ++ .../MokoDoliDymo/module-id-policy.-.-.md | 34 + MokoConsulting/MokoDoliG/CHANGELOG.md | 47 + MokoConsulting/MokoDoliG/DEVELOPMENT.md | 247 ++++ MokoConsulting/MokoDoliG/Home.md | 30 + MokoConsulting/MokoDoliG/update-server.-.-.md | 64 + MokoConsulting/MokoDoliGithub/Home.md | 43 + MokoConsulting/MokoDoliGithub/README.md | 148 +++ MokoConsulting/MokoDoliGithub/changelog.md | 70 ++ MokoConsulting/MokoDoliGithub/development.md | 323 ++++++ MokoConsulting/MokoDoliGithub/installation.md | 173 +++ .../MokoDoliGithub/module-id-policy.-.-.md | 260 +++++ .../MokoDoliGithub/update-server.-.-.md | 64 + MokoConsulting/MokoDoliHRM/API.md | 385 ++++++ MokoConsulting/MokoDoliHRM/FAQ.md | 333 ++++++ MokoConsulting/MokoDoliHRM/Home.md | 41 + MokoConsulting/MokoDoliHRM/INSTALLATION.md | 236 ++++ MokoConsulting/MokoDoliHRM/README.md | 167 +++ MokoConsulting/MokoDoliHRM/USER_GUIDE.md | 412 +++++++ .../MokoDoliHRM/update-server.-.-.md | 64 + MokoConsulting/MokoDoliMods/Home.md | 34 + MokoConsulting/MokoDoliMods/INSTALLATION.md | 438 +++++++ .../MokoDoliMods/update-server.-.-.md | 64 + MokoConsulting/MokoDoliMulti/Home.md | 44 + MokoConsulting/MokoDoliMulti/INSTALLATION.md | 304 +++++ .../MokoDoliMulti/PROJECT_SUMMARY.md | 291 +++++ MokoConsulting/MokoDoliMulti/README.md | 81 ++ MokoConsulting/MokoDoliMulti/USAGE.md | 498 ++++++++ MokoConsulting/MokoDoliMulti/api-API.-.-.md | 488 ++++++++ .../architecture-ARCHITECTURE.-.-.md | 367 ++++++ .../MokoDoliMulti/update-server.-.-.md | 64 + MokoConsulting/MokoDoliOffline/Home.md | 41 + MokoConsulting/MokoDoliOffline/README.md | 97 ++ .../MokoDoliOffline/installation.md | 213 ++++ .../MokoDoliOffline/update-server.-.-.md | 64 + .../MokoDoliOffline/user-guide.-.-.md | 268 +++++ MokoConsulting/MokoDoliPhoneCom/Home.md | 43 + MokoConsulting/MokoDoliPhoneCom/README.md | 148 +++ MokoConsulting/MokoDoliPhoneCom/changelog.md | 70 ++ .../MokoDoliPhoneCom/development.md | 323 ++++++ .../MokoDoliPhoneCom/installation.md | 173 +++ .../MokoDoliPhoneCom/module-id-policy.-.-.md | 260 +++++ .../MokoDoliPhoneCom/update-server.-.-.md | 64 + MokoConsulting/MokoDoliProjTemplate/Home.md | 18 + MokoConsulting/MokoDoliProjTemplate/README.md | 77 ++ .../MokoDoliProjTemplate/changelog.md | 74 ++ .../MokoDoliProjTemplate/development.md | 237 ++++ .../MokoDoliProjTemplate/installation.md | 136 +++ .../module-id-policy.-.-.md | 77 ++ .../MokoDoliProjTemplate/update-server.-.-.md | 56 + MokoConsulting/MokoDoliRelease/Home.md | 52 + MokoConsulting/MokoDoliRelease/README.md | 74 ++ MokoConsulting/MokoDoliRelease/ROADMAP.md | 107 ++ .../MokoDoliRelease/XML_UPDATE_STREAMS.md | 589 ++++++++++ .../MokoDoliRelease/api-reference.-.-.md | 282 +++++ .../MokoDoliRelease/architecture.md | 125 ++ .../MokoDoliRelease/configuration.md | 641 ++++++++++ .../enterprise-deployment.-.-.md | 586 ++++++++++ MokoConsulting/MokoDoliRelease/faq.md | 279 +++++ MokoConsulting/MokoDoliRelease/governance.md | 523 +++++++++ .../MokoDoliRelease/installation.md | 166 +++ .../MokoDoliRelease/quick-start.-.-.md | 305 +++++ MokoConsulting/MokoDoliRelease/runbook.md | 563 +++++++++ .../MokoDoliRelease/sla-management.-.-.md | 456 ++++++++ .../MokoDoliRelease/troubleshooting.md | 299 +++++ .../MokoDoliRelease/update-server.-.-.md | 64 + MokoConsulting/MokoDoliSign/ADMIN_GUIDE.md | 673 +++++++++++ MokoConsulting/MokoDoliSign/API.md | 697 +++++++++++ MokoConsulting/MokoDoliSign/BUILD.md | 200 ++++ MokoConsulting/MokoDoliSign/Home.md | 50 + .../MokoDoliSign/IMPLEMENTATION_SUMMARY.md | 125 ++ MokoConsulting/MokoDoliSign/INSTALL.md | 74 ++ .../MokoDoliSign/MIGRATION_GUIDE.md | 369 ++++++ MokoConsulting/MokoDoliSign/MODULE_ID.md | 316 +++++ MokoConsulting/MokoDoliSign/QUICK_START.md | 279 +++++ MokoConsulting/MokoDoliSign/README.md | 491 ++++++++ MokoConsulting/MokoDoliSign/ROADMAP.md | 400 +++++++ MokoConsulting/MokoDoliSign/STRUCTURE.md | 113 ++ MokoConsulting/MokoDoliSign/USER_GUIDE.md | 378 ++++++ .../MokoDoliSign/update-server.-.-.md | 64 + MokoConsulting/MokoDoliTraining/Home.md | 44 + .../MokoDoliTraining/api-manifest.-.-.md | 81 ++ .../MokoDoliTraining/api-module-class.-.-.md | 87 ++ .../guide-backup-recovery.-.-.md | 237 ++++ .../guide-installation.-.-.md | 67 ++ .../MokoDoliTraining/guide-seed-reset.-.-.md | 65 ++ .../policy-enforcement-levels.-.-.md | 73 ++ .../policy-file-header-standards.-.-.md | 95 ++ .../MokoDolibarr/Custom-Modules.-.md | 116 ++ MokoConsulting/MokoDolibarr/Development.md | 135 +++ .../MokoDolibarr/Getting-Started.-.md | 125 ++ MokoConsulting/MokoDolibarr/Home.md | 91 ++ MokoConsulting/MokoGalleryCalendar/Home.md | 42 + .../MokoGalleryCalendar/architecture.md | 153 +++ .../MokoGalleryCalendar/configuration.md | 91 ++ .../MokoGalleryCalendar/development.md | 108 ++ .../MokoGalleryCalendar/installation.md | 65 ++ .../MokoGalleryCalendar/troubleshooting.md | 116 ++ MokoConsulting/MokoGitea/Branding.md | 32 + MokoConsulting/MokoGitea/Deployment.md | 48 + MokoConsulting/MokoGitea/Home.md | 24 + MokoConsulting/MokoGitea/Project-API.md | 202 ++++ MokoConsulting/MokoGitea/roadmap.md | 88 ++ .../MokoISOUpdatePortable/ARCHITECTURE.md | 629 ++++++++++ .../BUILD-DIRECTORY.-.-.md | 39 + MokoConsulting/MokoISOUpdatePortable/BUILD.md | 1033 +++++++++++++++++ .../MokoISOUpdatePortable/CODE_OF_CONDUCT.md | 59 + .../MokoISOUpdatePortable/CONTRIBUTING.md | 116 ++ .../MokoISOUpdatePortable/CSHARP.md | 416 +++++++ .../MokoISOUpdatePortable/GOVERNANCE.md | 218 ++++ MokoConsulting/MokoISOUpdatePortable/Home.md | 51 + .../MokoISOUpdatePortable/INSTALLATION.md | 438 +++++++ .../RELEASE-PROCESS.-.-.md | 403 +++++++ .../REPOSITORY-INDEX.-.-.md | 108 ++ .../MokoISOUpdatePortable/SCRIPTS.md | 26 + .../MokoISOUpdatePortable/SECURITY.md | 234 ++++ .../templates-README-template.-.-.md | 136 +++ .../templates-index.-.-.md | 30 + .../MokoJoomHero/FIREWALL_CONFIGURATION.md | 273 +++++ MokoConsulting/MokoJoomHero/Home.md | 24 + .../MokoJoomHero/IMPLEMENTATION_SUMMARY.md | 175 +++ MokoConsulting/MokoJoomHero/QUICKSTART.md | 182 +++ .../MokoJoomHero/update-server.-.-.md | 110 ++ MokoConsulting/MokoJoomTOS/Configuration.md | 85 ++ MokoConsulting/MokoJoomTOS/Home.md | 21 + MokoConsulting/MokoJoomTOS/How-It-Works.-.md | 158 +++ MokoConsulting/MokoJoomTOS/Installation.md | 100 ++ .../MokoJoomTOS/update-server.-.-.md | 110 ++ MokoConsulting/MokoJoomla/Home.md | 45 + MokoConsulting/MokoOnyx/CSS-Variables.-.md | 234 ++++ MokoConsulting/MokoOnyx/Configuration.md | 147 +++ MokoConsulting/MokoOnyx/Custom-Themes.-.md | 125 ++ MokoConsulting/MokoOnyx/Development.md | 230 ++++ MokoConsulting/MokoOnyx/Home.md | 99 ++ MokoConsulting/MokoOnyx/Installation.md | 66 ++ MokoConsulting/MokoOnyx/Migration.md | 119 ++ MokoConsulting/MokoOnyx/Minification.md | 113 ++ .../MokoOnyx/Template-Overrides.-.md | 110 ++ .../MokoPerfectPublisher-Discord/Home.md | 23 + .../INSTALLATION.md | 438 +++++++ .../templates-README-template.-.-.md | 136 +++ .../templates-index.-.-.md | 30 + MokoConsulting/MokoTesting/Home.md | 28 + MokoConsulting/MokoTesting/INSTALLATION.md | 438 +++++++ MokoConsulting/MokoWaaS/Home.md | 66 ++ .../MokoWaaS/guides-build-guide.-.-.md | 321 +++++ .../guides-configuration-guide.-.-.md | 261 +++++ .../MokoWaaS/guides-installation-guide.-.-.md | 79 ++ .../MokoWaaS/guides-operations-guide.-.-.md | 123 ++ .../guides-rollback-and-recovery-guide.-.-.md | 102 ++ .../MokoWaaS/guides-testing-guide.-.-.md | 296 +++++ .../guides-troubleshooting-guide.-.-.md | 150 +++ ...guides-upgrade-and-versioning-guide.-.-.md | 109 ++ MokoConsulting/MokoWaaS/plugin-basic.-.-.md | 117 ++ .../MokoWaaS/reference-plugin-overview.-.-.md | 42 + MokoConsulting/MokoWaaS/update-server.-.-.md | 134 +++ .../MokoWaaSAnnounce/Architecture.md | 175 +++ .../MokoWaaSAnnounce/Configuration.md | 131 +++ MokoConsulting/MokoWaaSAnnounce/Home.md | 22 + .../MokoWaaSAnnounce/Installation.md | 150 +++ .../templates-README-template.-.-.md | 136 +++ .../MokoWaaSAnnounce/templates-index.-.-.md | 30 + MokoConsulting/MokoWinSetup/Home.md | 42 + MokoConsulting/MokoWinSetup/INSTALLATION.md | 438 +++++++ .../MokoWinSetup/setup-guide.-.-.md | 115 ++ .../MokoWinSetup/technical-reference.-.-.md | 156 +++ .../templates-README-template.-.-.md | 136 +++ .../MokoWinSetup/templates-index.-.-.md | 30 + MokoConsulting/Template-Client-WaaS/Home.md | 63 + .../Template-Client-WaaS/INSTALLATION.md | 438 +++++++ .../Template-Client-WaaS/deployment.md | 122 ++ .../templates-README-template.-.-.md | 136 +++ .../templates-index.-.-.md | 30 + MokoConsulting/Template-Dolibarr/Home.md | 18 + MokoConsulting/Template-Dolibarr/README.md | 140 +++ MokoConsulting/Template-Dolibarr/changelog.md | 62 + .../Template-Dolibarr/development.md | 315 +++++ .../Template-Dolibarr/installation.md | 165 +++ .../Template-Dolibarr/module-id-policy.-.-.md | 252 ++++ .../Template-Dolibarr/update-server.-.-.md | 56 + MokoConsulting/Template-Generic/Home.md | 15 + .../Template-Generic/INSTALLATION.md | 430 +++++++ .../templates-README-template.-.-.md | 128 ++ .../Template-Generic/templates-index.-.-.md | 22 + MokoConsulting/Template-MCP/API.md | 54 + MokoConsulting/Template-MCP/ARCHITECTURE.md | 64 + MokoConsulting/Template-MCP/Home.md | 15 + MokoConsulting/Template-MCP/INSTALLATION.md | 93 ++ .../backup-mcp/Akeeba-Integration.-.md | 49 + MokoConsulting/backup-mcp/Configuration.md | 175 +++ MokoConsulting/backup-mcp/Home.md | 57 + MokoConsulting/backup-mcp/MySQL-Backup.-.md | 176 +++ MokoConsulting/backup-mcp/Restore-Guide.-.md | 211 ++++ .../backup-mcp/Tools-Reference.-.md | 30 + MokoConsulting/deploy-mcp/Configuration.md | 48 + .../deploy-mcp/Deployment-Workflow.-.md | 31 + MokoConsulting/deploy-mcp/Home.md | 54 + MokoConsulting/deploy-mcp/Joomla-Sync.-.md | 171 +++ .../deploy-mcp/Tools-Reference.-.md | 26 + MokoConsulting/deploy-mcp/Troubleshooting.md | 182 +++ .../dolibarr-api-mcp/ARCHITECTURE.md | 104 ++ MokoConsulting/dolibarr-api-mcp/Home.md | 14 + .../dolibarr-api-mcp/INSTALLATION.md | 158 +++ .../dreamhost-mcp/DNS-Management.-.md | 25 + MokoConsulting/dreamhost-mcp/Home.md | 14 + .../dreamhost-mcp/Tools-Reference.-.md | 16 + MokoConsulting/gitea-api-mcp/ARCHITECTURE.md | 136 +++ MokoConsulting/gitea-api-mcp/Home.md | 14 + MokoConsulting/gitea-api-mcp/INSTALLATION.md | 162 +++ MokoConsulting/gitea-org-config/Home.md | 13 + .../gitea-org-config/INSTALLATION.md | 430 +++++++ MokoConsulting/gitea-private/Home.md | 13 + MokoConsulting/gitea-private/INSTALLATION.md | 430 +++++++ .../gitea-server-setup/Architecture.md | 124 ++ .../gitea-server-setup/Backup-Recovery.-.md | 168 +++ MokoConsulting/gitea-server-setup/Home.md | 55 + .../gitea-server-setup/Installation.md | 129 ++ .../gitea-server-setup/Monitoring.md | 155 +++ MokoConsulting/gitea-server-setup/Security.md | 161 +++ MokoConsulting/joomla-api-mcp/API.md | 583 ++++++++++ MokoConsulting/joomla-api-mcp/ARCHITECTURE.md | 74 ++ MokoConsulting/joomla-api-mcp/Home.md | 85 ++ MokoConsulting/joomla-api-mcp/INSTALLATION.md | 139 +++ .../templates-README-template.-.-.md | 136 +++ .../joomla-api-mcp/templates-index.-.-.md | 30 + MokoConsulting/moko-platform/ARCHITECTURE.md | 293 +++++ .../moko-platform/AUTO_CREATE_ORG_PROJECTS.md | 192 +++ .../moko-platform/DRY_RUN_PATTERN.md | 115 ++ .../Documentation-Standards.-.-.md | 130 +++ .../Documentation-Standards.-.md | 102 ++ MokoConsulting/moko-platform/Home.md | 108 ++ MokoConsulting/moko-platform/JOOMLA_SYNC.md | 166 +++ .../LEGAL_DOC_GENERATOR_WEB_README.md | 111 ++ .../moko-platform/MCP-Servers.-.-.-.md | 55 + MokoConsulting/moko-platform/MINIFICATION.md | 108 ++ MokoConsulting/moko-platform/NEW_SCRIPTS.md | 193 +++ .../moko-platform/QUICKSTART_ORG_PROJECTS.md | 116 ++ .../moko-platform/SITE_MONITORING.md | 198 ++++ .../moko-platform/WIKI_STANDARDS.md | 222 ++++ .../moko-platform/WORKFLOW_STANDARDS.md | 208 ++++ .../moko-platform/api-automation-index.-.-.md | 124 ++ .../api-definitions-default-index.-.-.md | 210 ++++ .../api-definitions-sync-index.-.-.md | 220 ++++ .../moko-platform/api-deploy-index.-.-.md | 148 +++ .../moko-platform/api-fix-index.-.-.md | 100 ++ MokoConsulting/moko-platform/api-index.-.-.md | 318 +++++ .../api-maintenance-index.-.-.md | 166 +++ .../moko-platform/api-plugin-index.-.-.md | 162 +++ .../moko-platform/api-tests-index.-.-.md | 59 + .../api-tests-sample-index.-.-.md | 53 + .../moko-platform/api-validate-index.-.-.md | 262 +++++ .../moko-platform/automation-README.-.-.md | 138 +++ ...utomation-branch-version-automation.-.-.md | 339 ++++++ .../automation-push-files.-.-.md | 43 + .../automation-repo-cleanup.-.-.md | 99 ++ .../moko-platform/client-repos.-.-.-.md | 138 +++ .../standards-mokostandards-file-spec.-.-.md | 245 ++++ .../moko-platform/workflows-README.-.-.md | 63 + .../workflows-auto-release.-.-.md | 90 ++ .../workflows-branch-protection.-.-.md | 213 ++++ .../workflows-build-release.-.-.md | 76 ++ .../workflows-cascade-dev.-.-.md | 210 ++++ .../workflows-changelog-management.-.-.md | 324 ++++++ .../workflows-demo-deployment.-.-.md | 61 + .../workflows-dev-branch-tracking.-.-.md | 378 ++++++ .../workflows-dev-deployment.-.-.md | 266 +++++ .../moko-platform/workflows-index.-.-.md | 77 ++ .../workflows-release-system.-.-.md | 200 ++++ .../moko-platform/workflows-renovate.-.-.md | 71 ++ .../workflows-reusable-workflows.-.-.md | 553 +++++++++ .../workflows-rs-deployment.-.-.md | 29 + .../workflows-secret-scanning.-.-.md | 61 + .../workflows-shared-workflows.-.-.md | 225 ++++ .../workflows-standards-compliance.-.-.md | 590 ++++++++++ .../workflows-static-analysis.-.-.md | 61 + .../workflows-sub-issue-management.-.-.md | 221 ++++ .../workflows-update-server.-.-.md | 400 +++++++ .../workflows-workflow-architecture.-.-.md | 52 + MokoConsulting/monitor-mcp/Configuration.md | 141 +++ .../monitor-mcp/Grafana-Integration.-.md | 49 + MokoConsulting/monitor-mcp/Home.md | 54 + .../monitor-mcp/Sites-Monitoring.-.-.md | 109 ++ .../monitor-mcp/Tools-Reference.-.md | 77 ++ MokoConsulting/monitor-mcp/Troubleshooting.md | 157 +++ MokoConsulting/org-profile/Home.md | 13 + MokoConsulting/org-profile/INSTALLATION.md | 430 +++++++ MokoConsulting/project-mcp/Home.md | 15 + MokoConsulting/project-mcp/Milestones.md | 21 + .../project-mcp/Tools-Reference.-.md | 24 + MokoConsulting/project-mcp/Workflow.md | 29 + MokoConsulting/ssh-mcp/ALIASES_AND_HOOKS.md | 322 +++++ MokoConsulting/ssh-mcp/API.md | 478 ++++++++ MokoConsulting/ssh-mcp/ARCHITECTURE.md | 165 +++ MokoConsulting/ssh-mcp/BACKUP_GUIDE.md | 392 +++++++ MokoConsulting/ssh-mcp/DEPLOYMENT_GUIDE.md | 268 +++++ MokoConsulting/ssh-mcp/Home.md | 78 ++ MokoConsulting/ssh-mcp/INSTALLATION.md | 262 +++++ MokoConsulting/ssh-mcp/SEO.md | 268 +++++ .../ssh-mcp/SOCIAL_MEDIA_ANNOUNCEMENT.md | 269 +++++ MokoConsulting/ssh-mcp/TOOL_MANAGEMENT.md | 520 +++++++++ MokoConsulting/wiki-mcp/Home.md | 14 + MokoConsulting/wiki-mcp/Tools-Reference.-.md | 15 + MokoConsulting/wiki-mcp/Usage-Examples.-.md | 28 + README.md | 75 +- 384 files changed, 69107 insertions(+), 13 deletions(-) create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/Home.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/accessibility.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-README.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-ad-schedule.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-cross-post-preview.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-quick-reference.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-screencast-script.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-moderation.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-website-management.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/authoring-style-guide.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/brand-reference.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/content-authoring.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/css-variables.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/deployment.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/migration-plan-events.-.-.md create mode 100644 ClarksvilleFurs/client-waas-clarksvillefurs/theme-architecture.-.-.md create mode 100644 MokoConsulting/MokoCRM/Home.md create mode 100644 MokoConsulting/MokoCRM/README.md create mode 100644 MokoConsulting/MokoCRM/changelog.md create mode 100644 MokoConsulting/MokoCRM/development.md create mode 100644 MokoConsulting/MokoCRM/installation.md create mode 100644 MokoConsulting/MokoCRM/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoCRM/roadmap.md create mode 100644 MokoConsulting/MokoCRM/update-server.-.-.md create mode 100644 MokoConsulting/MokoDPCalendarAPI/Home.md create mode 100644 MokoConsulting/MokoDPCalendarAPI/INSTALLATION.md create mode 100644 MokoConsulting/MokoDoliAdInsights/Home.md create mode 100644 MokoConsulting/MokoDoliAdInsights/README.md create mode 100644 MokoConsulting/MokoDoliAdInsights/adding-services.-.-.md create mode 100644 MokoConsulting/MokoDoliAdInsights/architecture.md create mode 100644 MokoConsulting/MokoDoliAdInsights/changelog.md create mode 100644 MokoConsulting/MokoDoliAdInsights/development.md create mode 100644 MokoConsulting/MokoDoliAdInsights/installation.md create mode 100644 MokoConsulting/MokoDoliAdInsights/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliAdInsights/quickstart-service.-.-.md create mode 100644 MokoConsulting/MokoDoliAdInsights/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliArt/Home.md create mode 100644 MokoConsulting/MokoDoliArt/README.md create mode 100644 MokoConsulting/MokoDoliArt/changelog.md create mode 100644 MokoConsulting/MokoDoliArt/development.md create mode 100644 MokoConsulting/MokoDoliArt/installation.md create mode 100644 MokoConsulting/MokoDoliArt/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliArt/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliAuth/Home.md create mode 100644 MokoConsulting/MokoDoliAuth/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/Home.md create mode 100644 MokoConsulting/MokoDoliCare/README.md create mode 100644 MokoConsulting/MokoDoliCare/admin-guide.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/changelog.md create mode 100644 MokoConsulting/MokoDoliCare/development.md create mode 100644 MokoConsulting/MokoDoliCare/family-management.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/installation.md create mode 100644 MokoConsulting/MokoDoliCare/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/quick-start.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/remote-checkin.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/roadmap.md create mode 100644 MokoConsulting/MokoDoliCare/troubleshooting.md create mode 100644 MokoConsulting/MokoDoliCare/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliCare/user-guide.-.-.md create mode 100644 MokoConsulting/MokoDoliChimp/DEVELOPMENT_GUIDE.md create mode 100644 MokoConsulting/MokoDoliChimp/Home.md create mode 100644 MokoConsulting/MokoDoliClaude/Home.md create mode 100644 MokoConsulting/MokoDoliClaude/README.md create mode 100644 MokoConsulting/MokoDoliClaude/changelog.md create mode 100644 MokoConsulting/MokoDoliClaude/development.md create mode 100644 MokoConsulting/MokoDoliClaude/installation.md create mode 100644 MokoConsulting/MokoDoliClaude/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliClaude/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliCredits/Home.md create mode 100644 MokoConsulting/MokoDoliCredits/README.md create mode 100644 MokoConsulting/MokoDoliCredits/changelog.md create mode 100644 MokoConsulting/MokoDoliCredits/development.md create mode 100644 MokoConsulting/MokoDoliCredits/installation.md create mode 100644 MokoConsulting/MokoDoliCredits/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliCredits/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliDymo/Home.md create mode 100644 MokoConsulting/MokoDoliDymo/README.md create mode 100644 MokoConsulting/MokoDoliDymo/changelog.md create mode 100644 MokoConsulting/MokoDoliDymo/development.md create mode 100644 MokoConsulting/MokoDoliDymo/dymo-label-format.-.-.md create mode 100644 MokoConsulting/MokoDoliDymo/installation.md create mode 100644 MokoConsulting/MokoDoliDymo/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliG/CHANGELOG.md create mode 100644 MokoConsulting/MokoDoliG/DEVELOPMENT.md create mode 100644 MokoConsulting/MokoDoliG/Home.md create mode 100644 MokoConsulting/MokoDoliG/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliGithub/Home.md create mode 100644 MokoConsulting/MokoDoliGithub/README.md create mode 100644 MokoConsulting/MokoDoliGithub/changelog.md create mode 100644 MokoConsulting/MokoDoliGithub/development.md create mode 100644 MokoConsulting/MokoDoliGithub/installation.md create mode 100644 MokoConsulting/MokoDoliGithub/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliGithub/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliHRM/API.md create mode 100644 MokoConsulting/MokoDoliHRM/FAQ.md create mode 100644 MokoConsulting/MokoDoliHRM/Home.md create mode 100644 MokoConsulting/MokoDoliHRM/INSTALLATION.md create mode 100644 MokoConsulting/MokoDoliHRM/README.md create mode 100644 MokoConsulting/MokoDoliHRM/USER_GUIDE.md create mode 100644 MokoConsulting/MokoDoliHRM/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliMods/Home.md create mode 100644 MokoConsulting/MokoDoliMods/INSTALLATION.md create mode 100644 MokoConsulting/MokoDoliMods/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliMulti/Home.md create mode 100644 MokoConsulting/MokoDoliMulti/INSTALLATION.md create mode 100644 MokoConsulting/MokoDoliMulti/PROJECT_SUMMARY.md create mode 100644 MokoConsulting/MokoDoliMulti/README.md create mode 100644 MokoConsulting/MokoDoliMulti/USAGE.md create mode 100644 MokoConsulting/MokoDoliMulti/api-API.-.-.md create mode 100644 MokoConsulting/MokoDoliMulti/architecture-ARCHITECTURE.-.-.md create mode 100644 MokoConsulting/MokoDoliMulti/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliOffline/Home.md create mode 100644 MokoConsulting/MokoDoliOffline/README.md create mode 100644 MokoConsulting/MokoDoliOffline/installation.md create mode 100644 MokoConsulting/MokoDoliOffline/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliOffline/user-guide.-.-.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/Home.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/README.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/changelog.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/development.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/installation.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliPhoneCom/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/Home.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/README.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/changelog.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/development.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/installation.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/module-id-policy.-.-.md create mode 100644 MokoConsulting/MokoDoliProjTemplate/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliRelease/Home.md create mode 100644 MokoConsulting/MokoDoliRelease/README.md create mode 100644 MokoConsulting/MokoDoliRelease/ROADMAP.md create mode 100644 MokoConsulting/MokoDoliRelease/XML_UPDATE_STREAMS.md create mode 100644 MokoConsulting/MokoDoliRelease/api-reference.-.-.md create mode 100644 MokoConsulting/MokoDoliRelease/architecture.md create mode 100644 MokoConsulting/MokoDoliRelease/configuration.md create mode 100644 MokoConsulting/MokoDoliRelease/enterprise-deployment.-.-.md create mode 100644 MokoConsulting/MokoDoliRelease/faq.md create mode 100644 MokoConsulting/MokoDoliRelease/governance.md create mode 100644 MokoConsulting/MokoDoliRelease/installation.md create mode 100644 MokoConsulting/MokoDoliRelease/quick-start.-.-.md create mode 100644 MokoConsulting/MokoDoliRelease/runbook.md create mode 100644 MokoConsulting/MokoDoliRelease/sla-management.-.-.md create mode 100644 MokoConsulting/MokoDoliRelease/troubleshooting.md create mode 100644 MokoConsulting/MokoDoliRelease/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliSign/ADMIN_GUIDE.md create mode 100644 MokoConsulting/MokoDoliSign/API.md create mode 100644 MokoConsulting/MokoDoliSign/BUILD.md create mode 100644 MokoConsulting/MokoDoliSign/Home.md create mode 100644 MokoConsulting/MokoDoliSign/IMPLEMENTATION_SUMMARY.md create mode 100644 MokoConsulting/MokoDoliSign/INSTALL.md create mode 100644 MokoConsulting/MokoDoliSign/MIGRATION_GUIDE.md create mode 100644 MokoConsulting/MokoDoliSign/MODULE_ID.md create mode 100644 MokoConsulting/MokoDoliSign/QUICK_START.md create mode 100644 MokoConsulting/MokoDoliSign/README.md create mode 100644 MokoConsulting/MokoDoliSign/ROADMAP.md create mode 100644 MokoConsulting/MokoDoliSign/STRUCTURE.md create mode 100644 MokoConsulting/MokoDoliSign/USER_GUIDE.md create mode 100644 MokoConsulting/MokoDoliSign/update-server.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/Home.md create mode 100644 MokoConsulting/MokoDoliTraining/api-manifest.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/api-module-class.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/guide-backup-recovery.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/guide-installation.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/guide-seed-reset.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/policy-enforcement-levels.-.-.md create mode 100644 MokoConsulting/MokoDoliTraining/policy-file-header-standards.-.-.md create mode 100644 MokoConsulting/MokoDolibarr/Custom-Modules.-.md create mode 100644 MokoConsulting/MokoDolibarr/Development.md create mode 100644 MokoConsulting/MokoDolibarr/Getting-Started.-.md create mode 100644 MokoConsulting/MokoDolibarr/Home.md create mode 100644 MokoConsulting/MokoGalleryCalendar/Home.md create mode 100644 MokoConsulting/MokoGalleryCalendar/architecture.md create mode 100644 MokoConsulting/MokoGalleryCalendar/configuration.md create mode 100644 MokoConsulting/MokoGalleryCalendar/development.md create mode 100644 MokoConsulting/MokoGalleryCalendar/installation.md create mode 100644 MokoConsulting/MokoGalleryCalendar/troubleshooting.md create mode 100644 MokoConsulting/MokoGitea/Branding.md create mode 100644 MokoConsulting/MokoGitea/Deployment.md create mode 100644 MokoConsulting/MokoGitea/Home.md create mode 100644 MokoConsulting/MokoGitea/Project-API.md create mode 100644 MokoConsulting/MokoGitea/roadmap.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/ARCHITECTURE.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/BUILD-DIRECTORY.-.-.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/BUILD.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/CODE_OF_CONDUCT.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/CONTRIBUTING.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/CSHARP.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/GOVERNANCE.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/Home.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/INSTALLATION.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/RELEASE-PROCESS.-.-.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/REPOSITORY-INDEX.-.-.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/SCRIPTS.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/SECURITY.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/templates-README-template.-.-.md create mode 100644 MokoConsulting/MokoISOUpdatePortable/templates-index.-.-.md create mode 100644 MokoConsulting/MokoJoomHero/FIREWALL_CONFIGURATION.md create mode 100644 MokoConsulting/MokoJoomHero/Home.md create mode 100644 MokoConsulting/MokoJoomHero/IMPLEMENTATION_SUMMARY.md create mode 100644 MokoConsulting/MokoJoomHero/QUICKSTART.md create mode 100644 MokoConsulting/MokoJoomHero/update-server.-.-.md create mode 100644 MokoConsulting/MokoJoomTOS/Configuration.md create mode 100644 MokoConsulting/MokoJoomTOS/Home.md create mode 100644 MokoConsulting/MokoJoomTOS/How-It-Works.-.md create mode 100644 MokoConsulting/MokoJoomTOS/Installation.md create mode 100644 MokoConsulting/MokoJoomTOS/update-server.-.-.md create mode 100644 MokoConsulting/MokoJoomla/Home.md create mode 100644 MokoConsulting/MokoOnyx/CSS-Variables.-.md create mode 100644 MokoConsulting/MokoOnyx/Configuration.md create mode 100644 MokoConsulting/MokoOnyx/Custom-Themes.-.md create mode 100644 MokoConsulting/MokoOnyx/Development.md create mode 100644 MokoConsulting/MokoOnyx/Home.md create mode 100644 MokoConsulting/MokoOnyx/Installation.md create mode 100644 MokoConsulting/MokoOnyx/Migration.md create mode 100644 MokoConsulting/MokoOnyx/Minification.md create mode 100644 MokoConsulting/MokoOnyx/Template-Overrides.-.md create mode 100644 MokoConsulting/MokoPerfectPublisher-Discord/Home.md create mode 100644 MokoConsulting/MokoPerfectPublisher-Discord/INSTALLATION.md create mode 100644 MokoConsulting/MokoPerfectPublisher-Discord/templates-README-template.-.-.md create mode 100644 MokoConsulting/MokoPerfectPublisher-Discord/templates-index.-.-.md create mode 100644 MokoConsulting/MokoTesting/Home.md create mode 100644 MokoConsulting/MokoTesting/INSTALLATION.md create mode 100644 MokoConsulting/MokoWaaS/Home.md create mode 100644 MokoConsulting/MokoWaaS/guides-build-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-configuration-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-installation-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-operations-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-rollback-and-recovery-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-testing-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-troubleshooting-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/guides-upgrade-and-versioning-guide.-.-.md create mode 100644 MokoConsulting/MokoWaaS/plugin-basic.-.-.md create mode 100644 MokoConsulting/MokoWaaS/reference-plugin-overview.-.-.md create mode 100644 MokoConsulting/MokoWaaS/update-server.-.-.md create mode 100644 MokoConsulting/MokoWaaSAnnounce/Architecture.md create mode 100644 MokoConsulting/MokoWaaSAnnounce/Configuration.md create mode 100644 MokoConsulting/MokoWaaSAnnounce/Home.md create mode 100644 MokoConsulting/MokoWaaSAnnounce/Installation.md create mode 100644 MokoConsulting/MokoWaaSAnnounce/templates-README-template.-.-.md create mode 100644 MokoConsulting/MokoWaaSAnnounce/templates-index.-.-.md create mode 100644 MokoConsulting/MokoWinSetup/Home.md create mode 100644 MokoConsulting/MokoWinSetup/INSTALLATION.md create mode 100644 MokoConsulting/MokoWinSetup/setup-guide.-.-.md create mode 100644 MokoConsulting/MokoWinSetup/technical-reference.-.-.md create mode 100644 MokoConsulting/MokoWinSetup/templates-README-template.-.-.md create mode 100644 MokoConsulting/MokoWinSetup/templates-index.-.-.md create mode 100644 MokoConsulting/Template-Client-WaaS/Home.md create mode 100644 MokoConsulting/Template-Client-WaaS/INSTALLATION.md create mode 100644 MokoConsulting/Template-Client-WaaS/deployment.md create mode 100644 MokoConsulting/Template-Client-WaaS/templates-README-template.-.-.md create mode 100644 MokoConsulting/Template-Client-WaaS/templates-index.-.-.md create mode 100644 MokoConsulting/Template-Dolibarr/Home.md create mode 100644 MokoConsulting/Template-Dolibarr/README.md create mode 100644 MokoConsulting/Template-Dolibarr/changelog.md create mode 100644 MokoConsulting/Template-Dolibarr/development.md create mode 100644 MokoConsulting/Template-Dolibarr/installation.md create mode 100644 MokoConsulting/Template-Dolibarr/module-id-policy.-.-.md create mode 100644 MokoConsulting/Template-Dolibarr/update-server.-.-.md create mode 100644 MokoConsulting/Template-Generic/Home.md create mode 100644 MokoConsulting/Template-Generic/INSTALLATION.md create mode 100644 MokoConsulting/Template-Generic/templates-README-template.-.-.md create mode 100644 MokoConsulting/Template-Generic/templates-index.-.-.md create mode 100644 MokoConsulting/Template-MCP/API.md create mode 100644 MokoConsulting/Template-MCP/ARCHITECTURE.md create mode 100644 MokoConsulting/Template-MCP/Home.md create mode 100644 MokoConsulting/Template-MCP/INSTALLATION.md create mode 100644 MokoConsulting/backup-mcp/Akeeba-Integration.-.md create mode 100644 MokoConsulting/backup-mcp/Configuration.md create mode 100644 MokoConsulting/backup-mcp/Home.md create mode 100644 MokoConsulting/backup-mcp/MySQL-Backup.-.md create mode 100644 MokoConsulting/backup-mcp/Restore-Guide.-.md create mode 100644 MokoConsulting/backup-mcp/Tools-Reference.-.md create mode 100644 MokoConsulting/deploy-mcp/Configuration.md create mode 100644 MokoConsulting/deploy-mcp/Deployment-Workflow.-.md create mode 100644 MokoConsulting/deploy-mcp/Home.md create mode 100644 MokoConsulting/deploy-mcp/Joomla-Sync.-.md create mode 100644 MokoConsulting/deploy-mcp/Tools-Reference.-.md create mode 100644 MokoConsulting/deploy-mcp/Troubleshooting.md create mode 100644 MokoConsulting/dolibarr-api-mcp/ARCHITECTURE.md create mode 100644 MokoConsulting/dolibarr-api-mcp/Home.md create mode 100644 MokoConsulting/dolibarr-api-mcp/INSTALLATION.md create mode 100644 MokoConsulting/dreamhost-mcp/DNS-Management.-.md create mode 100644 MokoConsulting/dreamhost-mcp/Home.md create mode 100644 MokoConsulting/dreamhost-mcp/Tools-Reference.-.md create mode 100644 MokoConsulting/gitea-api-mcp/ARCHITECTURE.md create mode 100644 MokoConsulting/gitea-api-mcp/Home.md create mode 100644 MokoConsulting/gitea-api-mcp/INSTALLATION.md create mode 100644 MokoConsulting/gitea-org-config/Home.md create mode 100644 MokoConsulting/gitea-org-config/INSTALLATION.md create mode 100644 MokoConsulting/gitea-private/Home.md create mode 100644 MokoConsulting/gitea-private/INSTALLATION.md create mode 100644 MokoConsulting/gitea-server-setup/Architecture.md create mode 100644 MokoConsulting/gitea-server-setup/Backup-Recovery.-.md create mode 100644 MokoConsulting/gitea-server-setup/Home.md create mode 100644 MokoConsulting/gitea-server-setup/Installation.md create mode 100644 MokoConsulting/gitea-server-setup/Monitoring.md create mode 100644 MokoConsulting/gitea-server-setup/Security.md create mode 100644 MokoConsulting/joomla-api-mcp/API.md create mode 100644 MokoConsulting/joomla-api-mcp/ARCHITECTURE.md create mode 100644 MokoConsulting/joomla-api-mcp/Home.md create mode 100644 MokoConsulting/joomla-api-mcp/INSTALLATION.md create mode 100644 MokoConsulting/joomla-api-mcp/templates-README-template.-.-.md create mode 100644 MokoConsulting/joomla-api-mcp/templates-index.-.-.md create mode 100644 MokoConsulting/moko-platform/ARCHITECTURE.md create mode 100644 MokoConsulting/moko-platform/AUTO_CREATE_ORG_PROJECTS.md create mode 100644 MokoConsulting/moko-platform/DRY_RUN_PATTERN.md create mode 100644 MokoConsulting/moko-platform/Documentation-Standards.-.-.md create mode 100644 MokoConsulting/moko-platform/Documentation-Standards.-.md create mode 100644 MokoConsulting/moko-platform/Home.md create mode 100644 MokoConsulting/moko-platform/JOOMLA_SYNC.md create mode 100644 MokoConsulting/moko-platform/LEGAL_DOC_GENERATOR_WEB_README.md create mode 100644 MokoConsulting/moko-platform/MCP-Servers.-.-.-.md create mode 100644 MokoConsulting/moko-platform/MINIFICATION.md create mode 100644 MokoConsulting/moko-platform/NEW_SCRIPTS.md create mode 100644 MokoConsulting/moko-platform/QUICKSTART_ORG_PROJECTS.md create mode 100644 MokoConsulting/moko-platform/SITE_MONITORING.md create mode 100644 MokoConsulting/moko-platform/WIKI_STANDARDS.md create mode 100644 MokoConsulting/moko-platform/WORKFLOW_STANDARDS.md create mode 100644 MokoConsulting/moko-platform/api-automation-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-definitions-default-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-definitions-sync-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-deploy-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-fix-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-maintenance-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-plugin-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-tests-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-tests-sample-index.-.-.md create mode 100644 MokoConsulting/moko-platform/api-validate-index.-.-.md create mode 100644 MokoConsulting/moko-platform/automation-README.-.-.md create mode 100644 MokoConsulting/moko-platform/automation-branch-version-automation.-.-.md create mode 100644 MokoConsulting/moko-platform/automation-push-files.-.-.md create mode 100644 MokoConsulting/moko-platform/automation-repo-cleanup.-.-.md create mode 100644 MokoConsulting/moko-platform/client-repos.-.-.-.md create mode 100644 MokoConsulting/moko-platform/standards-mokostandards-file-spec.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-README.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-auto-release.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-branch-protection.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-build-release.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-cascade-dev.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-changelog-management.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-demo-deployment.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-dev-branch-tracking.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-dev-deployment.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-index.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-release-system.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-renovate.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-reusable-workflows.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-rs-deployment.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-secret-scanning.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-shared-workflows.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-standards-compliance.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-static-analysis.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-sub-issue-management.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-update-server.-.-.md create mode 100644 MokoConsulting/moko-platform/workflows-workflow-architecture.-.-.md create mode 100644 MokoConsulting/monitor-mcp/Configuration.md create mode 100644 MokoConsulting/monitor-mcp/Grafana-Integration.-.md create mode 100644 MokoConsulting/monitor-mcp/Home.md create mode 100644 MokoConsulting/monitor-mcp/Sites-Monitoring.-.-.md create mode 100644 MokoConsulting/monitor-mcp/Tools-Reference.-.md create mode 100644 MokoConsulting/monitor-mcp/Troubleshooting.md create mode 100644 MokoConsulting/org-profile/Home.md create mode 100644 MokoConsulting/org-profile/INSTALLATION.md create mode 100644 MokoConsulting/project-mcp/Home.md create mode 100644 MokoConsulting/project-mcp/Milestones.md create mode 100644 MokoConsulting/project-mcp/Tools-Reference.-.md create mode 100644 MokoConsulting/project-mcp/Workflow.md create mode 100644 MokoConsulting/ssh-mcp/ALIASES_AND_HOOKS.md create mode 100644 MokoConsulting/ssh-mcp/API.md create mode 100644 MokoConsulting/ssh-mcp/ARCHITECTURE.md create mode 100644 MokoConsulting/ssh-mcp/BACKUP_GUIDE.md create mode 100644 MokoConsulting/ssh-mcp/DEPLOYMENT_GUIDE.md create mode 100644 MokoConsulting/ssh-mcp/Home.md create mode 100644 MokoConsulting/ssh-mcp/INSTALLATION.md create mode 100644 MokoConsulting/ssh-mcp/SEO.md create mode 100644 MokoConsulting/ssh-mcp/SOCIAL_MEDIA_ANNOUNCEMENT.md create mode 100644 MokoConsulting/ssh-mcp/TOOL_MANAGEMENT.md create mode 100644 MokoConsulting/wiki-mcp/Home.md create mode 100644 MokoConsulting/wiki-mcp/Tools-Reference.-.md create mode 100644 MokoConsulting/wiki-mcp/Usage-Examples.-.md diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/Home.md b/ClarksvilleFurs/client-waas-clarksvillefurs/Home.md new file mode 100644 index 0000000..2311615 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/Home.md @@ -0,0 +1,69 @@ +# ClarksvilleFurs.com + +Managed Joomla client site for the Clarksville Furs community — a free, all-ages furry community in Clarksville, TN. + +## Infrastructure + +| Environment | URL | Server | +|---|---|---| +| **Live** | [clarksvillefurs.com](https://clarksvillefurs.com) | DreamHost (iad1-shared-b7-01) | +| **Dev** | [clarksvillefurs.dev.mokoconsulting.tech](https://clarksvillefurs.dev.mokoconsulting.tech) | Moko Dev Server | +| **Monitoring** | [Grafana Dashboard](https://bench.mokoconsulting.tech/d/client-d85a0ed3/) | Moko Bench | + +Both environments share the same database. Dev is an open mirror of live (without offline mode). + +## Quick Links + +| Task | How | +|---|---| +| Deploy to dev | Push to `dev` branch → auto-deploys via workflow | +| Deploy to live | Merge to `main` → auto-deploys dev + live | +| Sync extensions | `deploy_sync_joomla` MCP tool or `sync-servers.yml` workflow | +| Monitor status | [Grafana dashboard](https://bench.mokoconsulting.tech/d/client-d85a0ed3/) | +| Run backup | Akeeba Backup in Joomla admin | + +## Platform + +- **CMS:** Joomla 6.1.0 +- **Template:** MokoOnyx +- **PHP:** 8.4 (web) / 8.2 (CLI) +- **Platform type:** `client` (MokoStandards) + +## Documentation + +### Site Management +- [Deployment](deployment) — server access, deploy workflow, SFTP configs +- [Content Authoring](content-authoring) — article and page management +- [Brand Reference](brand-reference) — logos, colors, voice + +### Content Guides +- [Style Guide](authoring-style-guide) — writing standards +- [Quick Reference](authoring-quick-reference) — common tasks +- [Cross-Post Preview](authoring-cross-post-preview) — social media teasers +- [Ad Schedule](authoring-ad-schedule) — promotion calendar + +### SOPs +- [Website Management](authoring-sop-website-management) — admin procedures +- [Moderation](authoring-sop-moderation) — community moderation + +### Technical +- [Theme Architecture](theme-architecture) — MokoOnyx template structure +- [CSS Variables](css-variables) — custom theme variables +- [Accessibility](accessibility) — WCAG compliance +- [Migration Plan](migration-plan-events) — events system migration + +## MokoStandards + +This repo follows the [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) governance framework. + +- [Site Monitoring](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/SITE_MONITORING) — Prometheus + Grafana monitoring +- [Joomla Sync](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/JOOMLA_SYNC) — dev ↔ live file sync +- [Minification](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/MINIFICATION) — CSS/JS build pipeline + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/accessibility.md b/ClarksvilleFurs/client-waas-clarksvillefurs/accessibility.md new file mode 100644 index 0000000..887a4c3 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/accessibility.md @@ -0,0 +1,162 @@ +← [Home](Home) + +# Accessibility + +WCAG 2.1 AA is the baseline target for all text on the CF site. That means +4.5:1 contrast for normal text and 3:1 for large text (≥18pt or ≥14pt bold) or +UI components. This document tracks issues found during live-site audits, the +theme-level mitigations in place, and the content-edit items that can't be +fixed from CSS. + +## Resolved in the theme + +### Coral-on-sky links fail AA — fixed + +Coral `#FF4B3E` on the sky blue backgrounds used across the site measures +2.06:1 to 2.57:1, all below the 4.5:1 AA threshold. + +| Fg | Bg | Ratio | Where | +|---|---|---|---| +| Coral | Sky Primary `#9CCEDB` | 2.33:1 | block-color-1, hero-primary | +| Coral | Sky Secondary `#7FB7C6` | 2.06:1 | container-bottom-a, offline page bg | +| Coral | Sky Raw `#a3cde2` | 2.57:1 | `.custom.sky` cards, container-top-b | + +**Mitigation:** `user.css` has a scoped override that flips `--link-color` to +ink `#1E1E1E` inside any element with a sky background (selectors cover +`[style*="var(--color-primary)"]`, `[style*="var(--sky)"]`, `.cf-brand-callout`, +`.container-top-b`, `.container-bottom-a`, `.hero-primary`, `.block-color-1`, +`.custom.sky .card`, `.custom.yellow .card`, `.custom.red .card`). + +**Hover state** uses coral, which does fail AA against sky. Hover is +time-limited and visual affordance is already established by underline +thickness change. Monitored but not currently a blocker. + +### White-on-red fails AA — fixed + +White on soft red `#ff7a73` measures 2.53:1. `.custom.red .card-body` now uses +ink text (5.79:1, AA pass) instead of white. + +### Muted text invisible on sky — fixed + +Mascot Grey `#8F8F8F` on sky backgrounds drops below 2:1. Same scoped override +bumps muted text to `#3a3a3a` inside sky surfaces. + +### Light palette drift — fixed + +Several Bootstrap palette variables in `light.custom.css` had accidentally held +dark-mode values (`--light: #1B2027`, `--primary-text-emphasis: #7A1E15`, +`--primary-bg-subtle: #3a1511`, etc.). These were silently breaking +`.bg-primary-subtle`, `.text-primary-emphasis`, `.bg-light`, `.bg-dark` utility +classes site-wide. All corrected to proper light-mode values in v02.02.00. + +## Known exceptions — acceptable + +### Coral on white, small text (3.63:1) + +Coral on white background at body text size measures 3.63:1 — above AA-large +(3:1) but below AA-normal (4.5:1). The `.cf-brand-accent` utility and the +decorative `.text-danger` on headings compat rule only apply this color to +large text (`h1`–`h6`, `.display-*`), where 3.63:1 is AA-pass. Link text with +body font size uses a darker shade via `--link-color: #FF4B3E` + underline for +affordance. + +### Coral hover on dark-tint cards (1.05:1–1.39:1) + +Hover state on `.custom.green` links is 1.39:1. Primary affordance is +underline thickness change, which is preserved. Fix available: swap hover +color to ink (11.4:1 AAA). Not applied by default because coral hover is the +site-wide brand convention. + +## Known issues — content-edit required + +Theme CSS cannot fix these; they must be addressed in Joomla article content +or module configuration. + +### Placeholder URLs + +Found in article content on about-us, faq, news: + +```html +Facebook +``` + +Either replace with the real Facebook URL or remove the Facebook mention. + +### Hardcoded brand-color CTAs + +Home page has inline-styled Discord and Telegram CTAs: + +```html +``` + +Telegram's official light cyan fails AA with white text. Options: + +1. Swap text to ink: `color: #1E1E1E` (5.09:1, AA pass) +2. Use Telegram's darker brand variant `#0088CC` (5.09:1 with white, AA pass) +3. Use a `.btn-primary` instead and accept that all CTAs look the same + +All three require a content edit. Option 2 is most brand-authentic. + +### Decorative `.text-danger` on body text + +If an editor uses `

` to make a paragraph red (as +decoration, not warning), the text renders as soft red `#ff7a73` — 3.14:1 +against white. Fails AA for normal text. The compat rule only applies to +headings. For decorative red body text, use `.cf-brand-accent` (coral) instead +— which also fails AA at body size, but is the intended brand color and is +constrained to short spans. + +Real semantic danger messages should stay in `.text-danger` and be kept to +large-text usage (alerts, form validation summaries). + +## Audit tools + +### Style guide preview + +Open `/style-guide.html` (at the repo root of any theme package delivery) in +a browser. Contains: + +- A Blue Gauntlet section exercising every common element on sky backgrounds +- Contrast audit table computing ratios live for all common color pairs +- Light/dark toggle +- All tinted card variants rendered with sample content + +### Browser DevTools + +Chrome/Firefox DevTools Accessibility panel shows contrast ratios on hover for +any text element. Fastest way to sanity-check a page before committing. + +### WebAIM Contrast Checker + + — paste in two hex values, +confirms AA/AAA grading. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | reference | +| Domain | Accessibility | +| Applies To | CF website (clarksvillefurs.com) | +| Jurisdiction | WCAG 2.1 AA | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/accessibility.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-21 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-21 | Claude | Initial creation | Findings from live-site audit at v02.06.00 | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-README.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-README.-.-.md new file mode 100644 index 0000000..0eaea50 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-README.-.-.md @@ -0,0 +1,89 @@ +← [Home](Home) + +# Authoring Documentation + +Documentation for anyone posting Events or News articles on the +Clarksville Furs website. Written for members of the **Event Authors** +Joomla group and the webmaster. + +## Who these docs are for + +- **Event Authors** — managers and volunteers who create and publish + event listings and news posts through the Joomla admin. +- **Webmaster** — the person responsible for the site, user accounts, + and cross-post integrations. + +## Reading order + +If you're brand new, read in this order: + +1. **[Quick Reference](quick-reference)** — numbered steps to log + in, create an article, attach an image, and publish. One page, + skimmable in under a minute. +2. **[Style Guide](style-guide)** — voice and tone rules, title + format, body length targets, image specs, and what not to do. +3. **[Cross-Post Preview](cross-post-preview)** — how a single + article shows up on Discord, Telegram, and Facebook, and which + fields control what. +4. **[Screencast Script](screencast-script)** — the spoken script + for the recorded walkthrough video. Read this if you want a + scene-by-scene overview of the full workflow before you try it. +5. **[Ad Schedule](ad-schedule)** — promotional posting schedule + for pre-launch (4 weeks) and post-launch (6 months) to drive + traffic to the website. +6. **[SOP — Website Management](sop-website-management)** — user + accounts, content management, events, media, backups, and + emergency procedures. +7. **[SOP — Community Moderation](sop-moderation)** — 4-tier + moderation system, platform-specific procedures, crisis handling, + and moderator self-care. + +If you've posted before and just need a refresher, start and stop at +the Quick Reference. + +## Related documents + +- [Migration Plan — Events](migration-plan-events) — the + upstream plan that defines when and how Events authoring goes live. +- [Content Authoring Guide](content-authoring) — CSS utility + classes available inside article HTML. +- [Brand Reference](brand-reference) — palette, typography, and + design decisions. +- [Deployment Guide](deployment) — how theme changes ship to + dev and production. + +## Questions? + +Use the [Contact Us](https://clarksvillefurs.com/contact-us) page or ask in #server-announcements on Discord. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | index | +| Domain | Content Authoring | +| Applies To | Event Authors group, Webmaster | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/README.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Initial creation | Phase 3 authoring docs index | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-ad-schedule.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-ad-schedule.-.-.md new file mode 100644 index 0000000..f80e8de --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-ad-schedule.-.-.md @@ -0,0 +1,138 @@ +← [Home](Home) + +# Ad Schedule — Pre-Launch and Post-Launch + +Promotional posting schedule for Discord, Telegram, and Facebook to +build awareness of the website and drive traffic to +clarksvillefurs.com. + +All posts should link to the website as the primary destination — not +to direct chat invites. The goal is to get members and newcomers +interacting with the site, reading the FAQ, and using the events page. + +--- + +## Pre-Launch (4 weeks before [LAUNCH DATE]) + +### Week 4 (T-28 days) + +| Day | Platform | Post | +|---|---|---| +| Monday | Discord, Telegram | **Teaser**: "Something new is coming to Clarksville Furs. Stay tuned." (No link yet) | +| Thursday | Facebook | **Teaser**: Same message, post to the Facebook group | + +### Week 3 (T-21 days) + +| Day | Platform | Post | +|---|---|---| +| Monday | Discord, Telegram | **Sneak peek**: "Our new website is almost ready. Here's a preview of what's coming — FAQ, events, and a whole new way to stay connected." Screenshot of the FAQ page. | +| Wednesday | Facebook | **Sneak peek**: Same, with screenshot | +| Friday | Discord | **FAQ highlight**: Share one FAQ answer as a teaser — "This and 11 more answers at clarksvillefurs.com/faq (coming soon)" | + +### Week 2 (T-14 days) + +| Day | Platform | Post | +|---|---|---| +| Monday | Discord, Telegram | **Feature spotlight — Events**: "Soon you'll be able to browse all CF events in one place — and submit your own. clarksvillefurs.com/events" | +| Wednesday | Discord | **Feature spotlight — FAQ**: "Parents asking questions? Friends curious about the fandom? We built a FAQ page that covers it all." | +| Friday | Facebook | **Countdown**: "One week out. The new Clarksville Furs website launches [LAUNCH DATE]." | + +### Week 1 (T-7 days) + +| Day | Platform | Post | +|---|---|---| +| Monday | All platforms | **Countdown**: "This week. clarksvillefurs.com goes live on [LAUNCH DATE]." | +| Wednesday | Discord, Telegram | **Call to action**: "When the site launches, head to clarksvillefurs.com and explore. Read the FAQ. Check out the events page." | +| Friday | All platforms | **Launch eve**: "Tomorrow. clarksvillefurs.com" | + +### Launch Day + +| Platform | Post | +|---|---| +| All platforms | **Launch**: "We're live! The new Clarksville Furs website is here. Explore the FAQ, browse upcoming events, and get to know the community. clarksvillefurs.com" | +| Discord (pinned) | **Pinned**: "The Clarksville Furs website is live at clarksvillefurs.com. This is now the best place to find event details, read the FAQ, and learn about the community." | + +--- + +## Post-Launch: Months 1–6 + +### Monthly recurring posts + +| Frequency | Platform | Post type | +|---|---|---| +| 1st of month | All platforms | **Monthly reminder**: "All upcoming events are on clarksvillefurs.com/events. Browse what's coming up and RSVP." | +| 15th of month | Discord, Telegram | **Submit your own event**: "Did you know members can create their own events? Visit clarksvillefurs.com/events and click Submit Event." | +| Weekly (Mon) | Discord | **FAQ of the week**: Pick one FAQ article and share the intro text with a link. Rotate through all 12 over 3 months. | + +### Month 1 — Establish habits + +| Week | Platform | Post | +|---|---|---| +| 1 | All platforms | **Welcome post**: "New here? Start at clarksvillefurs.com — our FAQ answers the most common questions, and the events page shows you what's coming up." | +| 2 | Discord, Telegram | **For parents**: "Got a kid who's into furries? Our FAQ has a page just for you: clarksvillefurs.com/faq" | +| 3 | Facebook | **Share prompt**: "Know someone curious about the fandom? Share our FAQ with them: clarksvillefurs.com/faq" | +| 4 | Discord | **Event submission reminder**: "Want to organize a game night, movie night, or meetup? Submit it at clarksvillefurs.com/events" | + +### Month 2 — Deepen engagement + +| Week | Platform | Post | +|---|---|---| +| 1 | Discord, Telegram | **Highlight a specific FAQ**: "What is a Therian?" intro text + link | +| 2 | Facebook | **Convention planning**: "Thinking about a con trip? Check our events page for group plans: clarksvillefurs.com/events" | +| 3 | Discord | **Feedback ask**: "Been using the website? Tell us what you think — use the Contact Us page: clarksvillefurs.com/contact-us" | +| 4 | All platforms | **Community stat**: "X members and counting. If you haven't visited the site yet, now's a great time: clarksvillefurs.com" | + +### Months 3–6 — Maintain cadence + +By month 3, reduce to the monthly recurring schedule (1st and 15th) +plus the weekly FAQ rotation on Discord. Add one-off posts only when: + +- A new FAQ article is added +- A major event is coming up +- The website gets a significant update +- A milestone is reached (member count, event count) + +--- + +## Post guidelines + +- **Always link to clarksvillefurs.com** — never give out direct + Discord or Telegram invite links as the primary entry point +- **Teasers, not full details** — drive traffic to the website for + complete information +- **Contact goes through the ticket system** — point people to + clarksvillefurs.com/contact-us, not a direct email address +- **Keep it casual** — match the CF voice (warm, direct, inclusive) +- **One exclamation mark max** per post + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | schedule | +| Domain | Content Marketing | +| Applies To | Webmaster, Event Authors, Social media managers | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/ad-schedule.md | +| Version | 00.01.00 | +| Status | Draft | +| Last Reviewed | 2026-04-27 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-27 | Claude | Initial creation | Pre-launch (4 weeks) and post-launch (6 months) promotional schedule | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-cross-post-preview.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-cross-post-preview.-.-.md new file mode 100644 index 0000000..511a77e --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-cross-post-preview.-.-.md @@ -0,0 +1,238 @@ +← [Home](Home) + +# Cross-Post Preview + +When you publish an article in the **Events** or **News** category, it +automatically cross-posts to three platforms. Each platform pulls +different fields from the article. This page shows you exactly what +goes where so you can tune your intro text and image before hitting +Publish. + +## How cross-posting works + +Two integrations handle the cross-posts: + +| Integration | Destination | Trigger | +|---|---|---| +| **MokoDiscordHook** | Discord — #server-announcements | `onContentAfterSave` fires when an article is saved in a configured category | +| **Perfect Publisher** | Facebook Page + Telegram channel | Rule Engine matches the article category and posts via the FB and Telegram APIs | + +You don't need to do anything extra. Save a published article in the +right category and the cross-posts fire automatically. + +**Important — teasers, not full details.** Cross-posts should hook the +reader and drive them to the website. Write the intro as a short teaser +that makes people want to click through to clarksvillefurs.com/events +for the full info. Don't put the complete date, time, and location in +the intro — save those for the article body. + +## Worked example + +Suppose you create this article: + +| Field | Value | +|---|---| +| **Title** | Monthly Meetup — Downtown Clarksville | +| **Alias** | monthly-meetup-downtown-clarksville | +| **Category** | Events | +| **Intro text** | Our monthly meetup is back! Grab a lawn chair and come hang — full details on the website. | +| **Intro Image** | `images/events/meetup-heritage-park.jpg` (1200x630, pavilion with picnic tables) | +| **Intro Image Alt** | Pavilion at Heritage Park with picnic tables and string lights | +| **Full article body** | (additional details: directions, parking, what to bring, RSVP link) | + +Here's how that article renders on each surface: + +--- + +### Discord — MokoDiscordHook embed + +MokoDiscordHook sends a rich embed to #server-announcements. The +embed uses these article fields: + +| Embed element | Sourced from | +|---|---| +| **Embed title** | Article title | +| **Embed description** | Intro text (first 1–2 sentences of the article body, before the "Read more" break) | +| **Embed image** | Intro Image | +| **Embed link** | Full article URL on clarksvillefurs.com | + +**What it looks like in Discord:** + +``` +┌──────────────────────────────────────────┐ +│ Monthly Meetup — Downtown Clarksville │ +│ │ +│ Our monthly meetup is back! Grab a │ +│ lawn chair and come hang — full │ +│ details on the website. │ +│ │ +│ │ +│ ┌────────────────────────────────────┐ │ +│ │ │ │ +│ │ [ intro image: pavilion with │ │ +│ │ picnic tables and string │ │ +│ │ lights ] │ │ +│ │ │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ clarksvillefurs.com │ +└──────────────────────────────────────────┘ +``` + +**Tips for Discord:** + +- Keep the intro under 200 characters for clean embed layout. +- Title truncates around 70 characters — stay under. +- The image renders full-width in the embed. Landscape (1200x630) is + ideal. +- Discord caches embeds aggressively. If you edit the article after + posting, the Discord embed will **not** update. + +--- + +### Telegram — Perfect Publisher message + +Perfect Publisher posts to @ClarksvilleFurs as a text message +with a link preview. + +| Message element | Sourced from | +|---|---| +| **Message text** | Intro text + article URL | +| **Link preview title** | Article title (from the page's ``) | +| **Link preview image** | Intro Image (from ``) | +| **Link preview description** | Meta description, or intro text if meta description is empty | + +**What it looks like in Telegram:** + +``` +Our monthly meetup is back! Grab a lawn +chair and come hang — full details on +the website. + +clarksvillefurs.com/events/monthly-meetup- +downtown-clarksville + + ┌────────────────────────────────┐ + │ [ link preview card ] │ + │ │ + │ Monthly Meetup — Downtown │ + │ Clarksville │ + │ │ + │ [ intro image thumbnail ] │ + │ │ + │ clarksvillefurs.com │ + └────────────────────────────────┘ +``` + +**Tips for Telegram:** + +- The intro text becomes the message body — write it as a teaser that + hooks the reader and drives them to the website for full details. +- Telegram generates the link preview from Open Graph meta tags. If the + intro image is missing, Telegram may show no preview or a generic + favicon. +- The link preview caches. If you need to refresh it after editing, + use Telegram's [@webpagebot](https://t.me/webpagebot) to clear the + cache for the URL. + +--- + +### Facebook — Perfect Publisher post + +Perfect Publisher creates a post on the linked Facebook Page +(clarksvillefurs) with a link card. + +| Post element | Sourced from | +|---|---| +| **Post text** | Intro text (prepended to the link) | +| **Link card title** | Article title (from ``) | +| **Link card image** | Intro Image (from ``) | +| **Link card description** | Meta description, or intro text if empty | +| **Link card domain** | clarksvillefurs.com | + +**What it looks like on Facebook:** + +``` +Clarksville Furs +Just now · 🌐 + +Our monthly meetup is back! Grab a lawn +chair and come hang — full details on +the website. + + ┌────────────────────────────────────┐ + │ │ + │ [ large link card image: │ + │ pavilion with picnic tables │ + │ and string lights ] │ + │ │ + ├────────────────────────────────────┤ + │ CLARKSVILLEFURS.COM │ + │ Monthly Meetup — Downtown │ + │ Clarksville │ + │ Our monthly meetup is back! │ + │ Grab a lawn chair and come... │ + └────────────────────────────────────┘ + +👍 Like 💬 Comment ↗ Share +``` + +**Tips for Facebook:** + +- The link card image must be at least 600x315 px. The recommended + 1200x630 works perfectly. +- Facebook caches link previews aggressively. If you update the image + or title after the first post, use the Facebook Sharing Debugger to + force a re-scrape of the URL. +- The intro text appears *above* the link card. Keep it short and + punchy — two sentences max. + +--- + +## Field-to-surface cheat sheet + +| Article field | Website | Discord | Telegram | Facebook | +|---|---|---|---|---| +| Title | Page heading | Embed title | Link preview title | Link card title | +| Intro text | Category listing excerpt | Embed description | Message body | Post text | +| Intro Image | Category listing thumbnail | Embed image | Link preview image | Link card image | +| Intro Image Alt | `alt` attribute on `` | Not displayed | Not displayed | Not displayed (but good practice) | +| Full article body | Full article page | Not included | Not included | Not included | +| Article URL | Canonical link | Embed link | Message link | Link card URL | +| Meta description | `` | Not used | Link preview fallback | Link card fallback | + +**Key takeaway:** The **intro text** and **intro image** are the two +fields that matter most for cross-posts. Get those right and every +platform looks good. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | guide | +| Domain | Content Authoring | +| Applies To | Event Authors group, Webmaster | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/cross-post-preview.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Initial creation | Phase 3 cross-post field mapping with worked example | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-quick-reference.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-quick-reference.-.-.md new file mode 100644 index 0000000..373785f --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-quick-reference.-.-.md @@ -0,0 +1,100 @@ +← [Home](Home) + +# Quick Reference — Events and News + +One-page cheat sheet. If you've posted before and just forgot the +steps, this should get you unblocked in under a minute. + +## Log in + +1. Go to `clarksvillefurs.com/administrator` +2. Enter your username and password. +3. Complete the 2FA prompt (authenticator app code). +4. You land on the Home Dashboard. + +## Create a new article + +5. From the Home Dashboard, click **Content > Articles > + New**. +6. Enter the **Title** — use the format described in the + [Style Guide](./style-guide.md#title-format). +7. Set the **Alias** — Joomla auto-generates one from the title. Leave + it unless you need a shorter URL slug. +8. Set the **Category**: + - **Events** for event listings. + - **News** for announcements and updates. + +## Write the body + +9. Write a 1–2 sentence intro paragraph. This is the text that + appears in cross-posts to Discord, Telegram, and Facebook — make + it count. +10. Add the rest of the article body. See the + [Style Guide](./style-guide.md#body-length-targets) for length + guidance. + +## Attach an image + +11. In the **Images** tab (below the editor): + - **Intro Image** — shown in category list views and cross-posts. + - **Full Article Image** — shown at the top of the full article. +12. Click **Select** and upload or pick from the Media Manager. +13. Fill in the **Alt Text** field — describe what's in the image. + See [Style Guide — Image specs](./style-guide.md#image-specs). + +## Set the publish date + +14. In the **Publishing** tab: + - **Start Publishing** — set the date and time the article should + go live. Use this for scheduling future events. + - Leave **Finish Publishing** blank unless the article should + auto-expire. + +## Publish + +15. Set **Status** to **Published** (green toggle at the top). +16. Click **Save & Close**. + +## Verify + +17. Open the site in a new tab and confirm the article appears in the + correct category listing. +18. Check that the intro image renders and the title is correct. +19. Wait 1–2 minutes, then verify the cross-posts arrived: + - Discord — #server-announcements + - Telegram — @ClarksvilleFurs + - Facebook — linked Facebook Page + +If a cross-post didn't arrive, check the article category. Cross-posts +only fire for articles saved in the **Events** or **News** categories. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | guide | +| Domain | Content Authoring | +| Applies To | Event Authors group, Webmaster | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/quick-reference.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Initial creation | Phase 3 quick-reference cheat sheet | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-screencast-script.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-screencast-script.-.-.md new file mode 100644 index 0000000..5ce8f8d --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-screencast-script.-.-.md @@ -0,0 +1,245 @@ +← [Home](Home) + +# Screencast Script — Events and News Walkthrough + +**Runtime target:** 5–8 minutes +**Presenter:** Moko Consulting (to be assigned) +**Format:** Screen recording with voiceover + +This is the read-from script for the recorded walkthrough. Screen +directions are in `[BRACKETS]`. Spoken voiceover is the plain text +beneath each direction. + +--- + +## Scene 1 — Intro (0:00–0:30) + +`[SCREEN: CF website homepage, scrolled to show the Events section]` + +Hey everyone! This is a quick walkthrough of how to post events and +news on the Clarksville Furs website. By the end of this video you'll +know how to log in, create an article, attach an image, and publish — +plus you'll see how your post automatically shows up on Discord, +Telegram, and Facebook. + +Let's jump in. + +--- + +## Scene 2 — Logging in (0:30–1:15) + +`[SCREEN: Browser navigating to clarksvillefurs.com/administrator]` + +First, head to clarksvillefurs.com/administrator. This is the Joomla +admin panel — it's where all content management happens. + +`[SCREEN: Joomla login form — type username and password]` + +Enter your username and password. These were set up for you when your +account was created. If you don't have credentials yet, reach out to +the [Contact Us](https://clarksvillefurs.com/contact-us) page. + +`[SCREEN: 2FA prompt — enter authenticator code]` + +You'll also need to enter a code from your authenticator app. This +is two-factor authentication — it keeps the site secure even if your +password gets compromised. + +`[SCREEN: Home Dashboard loads]` + +And we're in. This is the Home Dashboard. You can see quick links to +articles, media, and users. We're going to create a new article. + +--- + +## Scene 3 — Creating the article (1:15–2:45) + +`[SCREEN: Click Content > Articles > + New in the top menu]` + +Click **Content**, then **Articles**, then the **New** button. This +opens a blank article editor. + +`[SCREEN: Article editor — cursor in Title field]` + +Start with the title. For events, we use the format "Event Name — em +dash — Location." So for our monthly meetup, that's "Monthly Meetup — +Downtown Clarksville." + +`[SCREEN: Type the title "Monthly Meetup — Downtown Clarksville"]` + +Keep it under 70 characters so it doesn't get cut off in Discord +embeds. + +`[SCREEN: Click the Category dropdown, select "Events"]` + +Next, set the category. Pick **Events** for event listings or **News** +for announcements. This is important — the category controls which +cross-post integrations fire. If you pick the wrong category, your +post won't show up on Discord or Telegram. + +`[SCREEN: Click into the editor body area]` + +Now write the body. Start with one or two sentences that summarize the +event — the what, when, and where. This intro text is what people see +on Discord, Telegram, and Facebook before they click through, so make +it count. + +`[SCREEN: Type intro text: "Come hang out with us this Saturday! We're meeting at the pavilion in Heritage Park, 12–3 PM. Bring a lawn chair and a good attitude."]` + +After the intro, add whatever details people need: directions, parking, +what to bring, an RSVP link. But keep it concise — 50 to 150 words is +plenty for an event listing. + +--- + +## Scene 4 — Adding an image (2:45–4:00) + +`[SCREEN: Click the "Images" tab below the editor]` + +Scroll down and click the **Images** tab. You'll see two image slots: +Intro Image and Full Article Image. + +`[SCREEN: Click "Select" next to Intro Image]` + +The **Intro Image** is the one that matters most. It shows up in the +category listing on the website and in every cross-post. Click +**Select** to open the Media Manager. + +`[SCREEN: Media Manager — upload a new image or select an existing one]` + +You can upload a new image or pick one that's already in the library. +For best results, use a landscape photo — 1200 by 630 pixels. Keep the +file size under 500 KB. JPG works great for photos. + +`[SCREEN: Select the image, return to the Images tab]` + +Once you've picked the image, fill in the **Alt Text** field. This is +a short description of what's *in* the image — not the event title. +Something like "Pavilion at Heritage Park with picnic tables and string +lights." Screen readers use this, and it's good practice for +accessibility. + +`[SCREEN: Type alt text into the Alt Text field]` + +Don't skip the alt text. It takes five seconds and makes the site +better for everyone. + +--- + +## Scene 5 — Publishing options (4:00–5:00) + +`[SCREEN: Click the "Publishing" tab]` + +Click the **Publishing** tab. The main field here is **Start +Publishing** — this is when the article goes live on the site. + +`[SCREEN: Set Start Publishing to a date a few days from now]` + +For events, I like to set this a few days before the event so people +have time to see it and plan. You can also set **Finish Publishing** if +you want the article to automatically disappear after the event date, +but that's optional. + +`[SCREEN: Scroll up to the Status toggle at the top]` + +Last thing before we save — make sure the **Status** is set to +**Published**. It's the green toggle at the top of the editor. If this +is set to Unpublished, the article exists but nobody can see it. + +--- + +## Scene 6 — Save and verify (5:00–6:00) + +`[SCREEN: Click "Save & Close" in the toolbar]` + +Click **Save & Close**. Joomla saves the article and drops you back to +the article list. + +`[SCREEN: Open the site frontend in a new tab, navigate to the Events category]` + +Let's verify. Open the site in a new tab and navigate to the Events +page. There's our article — title, intro text, and the image we just +uploaded. + +`[SCREEN: Click into the full article to show the complete content]` + +Click into it to see the full article. Everything looks good. + +--- + +## Scene 7 — Cross-post verification (6:00–7:00) + +`[SCREEN: Switch to Discord — show the channel with the new embed]` + +Now let's check the cross-posts. Over in Discord, in the +#server-announcements channel, you can see the embed that fired +automatically when we saved the article. It pulled in the title, the +intro text, the image, and a link back to the full article on the +website. + +`[SCREEN: Switch to Telegram — show the channel message]` + +Same thing on Telegram. The intro text is the message body, and +there's a link preview card with the title and image. + +`[SCREEN: Switch to Facebook — show the page post]` + +And on Facebook — the page post has the intro text above a link card +with the image and title. + +All three platforms pulled from the same two fields: the **intro text** +and the **intro image**. That's why those two fields matter the most. + +--- + +## Scene 8 — Wrap-up (7:00–7:30) + +`[SCREEN: Back on the CF website Events page]` + +That's the whole workflow. To recap: + +1. Log in with your credentials and 2FA code. +2. Create a new article — set the title, category, and body. +3. Attach an intro image with alt text. +4. Set the publish date and status. +5. Save, verify on the website, and confirm the cross-posts arrived. + +If you get stuck, check the Quick Reference doc — it's a one-page +cheat sheet with all the steps. And if something's not working, reach +out to the [Contact Us](https://clarksvillefurs.com/contact-us) page. + +Thanks for watching, and happy posting! + +`[SCREEN: Fade to CF logo / end card]` + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | script | +| Domain | Content Authoring | +| Applies To | Screencast recording — Moko Consulting presenter | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/screencast-script.md | +| Version | 00.01.00 | +| Status | Draft | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Initial creation | Phase 3 walkthrough script, 8 scenes, ~7 min target | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-moderation.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-moderation.-.-.md new file mode 100644 index 0000000..a04c5f2 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-moderation.-.-.md @@ -0,0 +1,488 @@ +← [Home](Home) + +# SOP — Community Moderation + +Standard operating procedures for moderating the Clarksville Furs +community across all platforms: the website, Discord, Telegram, and +Facebook. + +Clarksville Furs is an all-ages, family-friendly community. These +procedures exist to keep it that way. + +--- + +## 1. Guiding Principles + +- **Safety first** — protect minors, protect vulnerable members, + protect the community's reputation. +- **Assume good intent** — most issues are misunderstandings, not + malice. Educate before you escalate. +- **Consistency** — enforce the same standards everywhere. What's not + okay on Discord is not okay on Telegram, Facebook, or the website. +- **Transparency** — when you take moderation action, explain why. + Members deserve to know what rule was broken. +- **Documentation** — log every moderation action. Patterns matter + more than individual incidents. + +--- + +## 2. Community Guidelines Summary + +The full Community Guidelines are published at +`clarksvillefurs.com/community-guidelines`. Key rules for moderators: + +1. **All-ages content only** in all public spaces +2. **No harassment, bullying, or targeted behavior** +3. **No hate speech** — racism, homophobia, transphobia, or any + identity-based attacks +4. **No unsolicited sexual content** in any public space +5. **No doxxing** — sharing someone's real name, address, workplace, + or photo without consent +6. **No spam or self-promotion** without moderator approval +7. **Respect pronouns and chosen names** +8. **No drama-baiting** — deliberately provocative posts designed to + start arguments + +--- + +## 3. Moderation Tiers + +Not every issue requires the same response. Use the tier system to +match the response to the severity. + +### Tier 1 — Gentle reminder (most common) + +**When to use:** First-time minor infractions. Off-topic posting, +mild language in a family-friendly channel, accidental oversharing. + +**Action:** +1. Send a friendly DM (not a public callout). +2. Explain which guideline was relevant. +3. Ask them to edit or delete the message. +4. No formal record unless it recurs. + +**Example script:** +> Hey! Just a heads-up — we keep things family-friendly in the public +> channels. Would you mind editing/removing that message? Thanks! + +### Tier 2 — Formal warning + +**When to use:** Repeat minor infractions after a Tier 1 reminder, or +a single moderate infraction (heated argument, inappropriate content +that's not extreme, disrespectful behavior). + +**Action:** +1. DM the member with a clear statement of what happened and which + rule was broken. +2. Delete or hide the offending content. +3. Log the warning in the moderation log (see Section 7). +4. Inform other moderators so they're aware. + +**Example script:** +> Hi — this is a formal warning about [specific behavior] in +> [channel/platform]. This violates our Community Guidelines, +> specifically [rule number/name]. Please review the guidelines at +> clarksvillefurs.com/community-guidelines. Further violations may +> result in a temporary or permanent ban. + +### Tier 3 — Temporary ban (24 hours to 30 days) + +**When to use:** Serious single infractions or pattern of Tier 2 +warnings (3+ warnings in 90 days). Examples: explicit content in a +public channel, targeted harassment, sustained disruptive behavior. + +**Action:** +1. Mute or ban the member on the affected platform. +2. DM them with the reason and duration. +3. Log in the moderation log with full context. +4. Notify the moderation team. +5. After the ban expires, send a welcome-back message reminding them + of the guidelines. + +**Duration guidelines:** +- First temp ban: 24–72 hours +- Second temp ban: 7–14 days +- Third temp ban: 30 days, with a note that the next step is permanent + +### Tier 4 — Permanent ban + +**When to use:** Extreme violations (threats, doxxing, CSAM, predatory +behavior toward minors) or failure to reform after multiple Tier 3 +bans. + +**Action:** +1. Immediately ban on all platforms (Discord, Telegram, Facebook, + website). +2. Do not engage in debate — the decision is final. +3. Log the full incident with screenshots and timestamps. +4. Notify the webmaster and Moko Consulting. +5. If the violation involves a minor or is potentially criminal, + see Section 6. + +--- + +## 4. Platform-Specific Procedures + +### 4.1 Discord + +- **Roles**: Moderators have the `Content Moderators` role with + permissions to delete messages, mute members, and manage channels. +- **Slow mode**: Enable slow mode (30–60 seconds) during heated + conversations instead of immediately banning. +- **Channel locks**: Lock a channel temporarily if a situation is + escalating. Announce: "Channel is paused while mods review. Be + back shortly." +- **DM policy**: Always DM the member before or after taking public + action. Never moderate silently — it breeds distrust. +- **Bot logs**: Check the audit log and bot logs for context before + acting. + +### 4.2 Telegram + +- **Admin rights**: Moderators have admin rights in the main chat + group. +- **Announcement channel** (@ClarksvilleFurs): Only admins can post. + No moderation needed — it's outbound only. +- **Main chat group**: Apply the same tier system as Discord. +- **Spam bots**: Telegram is prone to join-spam. Use the group's + anti-spam bot and manually remove/ban spam accounts immediately. + +### 4.3 Facebook group + +- **Admin/Moderator roles**: Moderators have the Moderator role on the + Facebook group. +- **Post approval**: Consider enabling post approval for new members + (first 30 days) to catch spam and inappropriate content before it's + visible. +- **Reporting**: Facebook has its own reporting system. If someone + reports a post, review it promptly — Facebook may act independently + if reports pile up. +- **Non-members**: The group is public, so non-members can see content. + Moderate accordingly — assume parents and employers are reading. + +### 4.4 Website (Joomla) + +Content Moderators have Joomla admin panel access and can manage +content directly. + +- **Admin access**: Content Moderators can log in at + `clarksvillefurs.com/administrator` to manage articles and events. +- **User blocking**: Go to **Users > Manage**, find the user, set + **Block User** to Yes. +- **Content removal**: Unpublish the article or event immediately. + Investigate before permanently deleting — you may need the content + as evidence. +- **Event review**: Event Authors can auto-publish DPCalendar events. + Review recently published events periodically and unpublish anything + that violates Community Guidelines. +- **Protected categories**: Content Moderators cannot edit FAQ, About + Us, Legal, SOP, or News articles. Escalate to a Manager if changes + are needed in those categories. +- **Registration spam**: Check the Community Builder approval queue + regularly. Reject accounts with obviously fake names, disposable + emails, or no profile information. + +--- + +## 5. In-Person Event Moderation + +### 5.1 Meetup ground rules + +All Clarksville Furs meetups follow the same Community Guidelines as +online spaces. Additionally: + +- **All-ages environment** — no alcohol at CF-organized events unless + the venue is 21+ only and the event is explicitly labeled as such. +- **Photography consent** — ask before photographing or filming anyone. + Never photograph minors without explicit parental consent. Fursuiters + may be photographed in public spaces unless they ask not to be. +- **Personal space** — not everyone wants hugs. Ask first. "Can I hug + you?" is always the right question. +- **No weapons** — real or prop. Even if it's part of a costume. + +### 5.2 Handling issues at a meetup + +If someone is making others uncomfortable or violating guidelines: + +1. Pull them aside privately — do not make a scene. +2. Explain the issue calmly and specifically. +3. If they cooperate, move on. No need to escalate. +4. If they refuse or the behavior is serious, ask them to leave. + Be firm but not aggressive: "I need you to head out for today. + We can talk about this later." +5. If they refuse to leave or become threatening, call 911. Do not + physically confront anyone. +6. Log the incident after the event. Follow the tier system for any + online follow-up. + +### 5.3 Photography and social media at events + +- **Before the event**: Announce in Discord/Telegram that photos will + be taken and may be shared on CF social media. +- **At the event**: Designate a photographer if possible. Ask for + verbal consent before posting photos of identifiable people. +- **Minors**: Never post photos of minors on CF social media without + written parental consent. When in doubt, don't post it. +- **Fursuiters**: Fursuiters in public spaces generally expect to be + photographed, but always respect a "no photos" request. + +### 5.4 Venue-specific rules + +Some venues have their own rules (no outside food, specific parking, +noise limits). The event organizer should: + +1. Visit the venue beforehand or call to confirm rules. +2. Post venue rules in the event description. +3. Remind attendees at the start of the meetup. +4. If a member violates venue rules, address it immediately — losing + a venue relationship hurts the whole community. + +--- + +## 6. Handling Sensitive Situations + +### 6.1 A member reports harassment + +1. Thank them for reporting — never dismiss or minimize. +2. Ask for screenshots, timestamps, and any witnesses. +3. Do not reveal the reporter's identity to the accused. +4. Investigate promptly (within 24 hours). +5. Take action based on the tier system. +6. Follow up with the reporter to let them know the outcome (without + sharing details of any punishment). + +### 6.2 A member is in crisis (self-harm, suicidal ideation) + +1. Do not ignore it. Do not dismiss it as attention-seeking. +2. Respond with empathy: "I hear you. I care about you. Can I help + you find support?" +3. Share the 988 Suicide and Crisis Lifeline: **call or text 988**. +4. If you believe there is immediate danger, contact local emergency + services (911). +5. Notify the webmaster privately. +6. Do not share the member's situation publicly or with other members. + +### 6.3 A minor is involved + +1. Any content involving a minor that is sexual, exploitative, or + predatory is an **immediate Tier 4 permanent ban** on all + platforms. +2. Preserve all evidence (screenshots with timestamps). +3. Contact the webmaster and Moko Consulting immediately. +4. If the content may be illegal (CSAM, grooming), report to the + National Center for Missing & Exploited Children (NCMEC) at + CyberTipline.org and contact local law enforcement. +5. Do not attempt to investigate yourself — let authorities handle it. + +--- + +### 6.4 Content takedown or privacy request + +If someone requests removal of content that identifies them (photos, +real name, personal info): + +1. Take the request seriously regardless of who posted the content. +2. Remove or edit the content within 24 hours. +3. If the content has cross-posted to Discord/Telegram/Facebook, + delete those posts manually. +4. Notify the original poster that the content was removed and why. +5. No formal moderation action is needed against the poster unless + the content was posted maliciously (doxxing — Tier 4). + +### 6.5 Handling media or public attention + +If CF receives press coverage, goes viral, or gets attention from +outside the community: + +1. Do not respond to journalists or media on behalf of CF without + webmaster approval. +2. Do not engage with trolls or bad-faith actors on social media. + Ignore, mute, or block. +3. If the attention is negative, consider temporarily setting Discord + to slow mode and enabling Facebook post approval. +4. Coordinate any official response through the webmaster. +5. Document the situation for the team so everyone is on the same page. + +--- + +## 7. Reporting to Authorities + +If a moderation situation involves potential criminal activity: + +1. **Do not delete the evidence.** Screenshot everything with + timestamps and usernames. +2. **Do not confront the individual** — this may cause them to + destroy evidence or flee. +3. Contact local law enforcement (Clarksville Police Department + non-emergency: 931-648-0656) or 911 if there is immediate danger. +4. For online exploitation of minors, file a report at + CyberTipline.org (National Center for Missing & Exploited + Children). +5. Notify the webmaster and Moko Consulting. + +--- + +## 8. Appeals Process + +### 8.1 Who can appeal + +Any member who receives a Tier 2 warning, Tier 3 temporary ban, or +Tier 4 permanent ban may appeal. Tier 1 reminders are informal and +not appealable. + +### 8.2 How to appeal + +1. The member contacts the webmaster via the Contact Us page at + clarksvillefurs.com/contact-us (or by email if they are banned + from the website). +2. The appeal must include: what happened (their perspective), why + they believe the action was incorrect or disproportionate, and + what they would do differently. + +### 8.3 Review process + +1. The webmaster reviews the appeal against the moderation log. +2. If the original moderator is available, get their input — but the + webmaster makes the final call. +3. Possible outcomes: + - **Upheld** — the original action stands. Explain why. + - **Modified** — reduce the severity (e.g., Tier 3 → Tier 2). + Update the moderation log. + - **Overturned** — remove the action entirely. Apologize if + appropriate. Update the moderation log. +4. Respond to the member within 7 days. +5. Appeals are final. There is no second appeal. + +### 8.4 Exceptions + +Tier 4 bans for threats, CSAM, or predatory behavior toward minors +are **not appealable**. These are safety decisions, not judgment calls. + +--- + +## 9. Ban Evasion + +### 9.1 Identifying alt accounts + +Signs that a banned member has returned with a new account: + +- New account created shortly after a ban +- Same writing style, vocabulary, or topics +- Same city/state in Community Builder profile +- References to events or conversations the new account shouldn't + know about +- Other members report recognizing the person + +### 9.2 Handling confirmed evasion + +1. Ban the alt account immediately on all platforms. +2. Log it as a new Tier 4 entry referencing the original ban. +3. Do not engage in debate about whether it's really them. +4. If evasion is persistent (3+ attempts), consider IP-based + restrictions on Discord and website registration. + +--- + +## 10. Moderator Onboarding + +### 10.1 Checklist for new moderators + +When adding a new Content Moderator: + +- [ ] Add to the **Content Moderators** Joomla user group +- [ ] Grant Discord moderator role +- [ ] Grant Telegram admin rights in the main chat group +- [ ] Grant Facebook group moderator role +- [ ] Share access to the moderation log +- [ ] Walk through this SOP document — especially Sections 3 (tiers), + 5 (in-person), and 6 (sensitive situations) +- [ ] Introduce them to the mod team in the private moderator channel +- [ ] Pair them with an experienced moderator for their first 2 weeks + +### 10.2 Moderator expectations + +- Check in on at least one platform daily (even just a glance) +- Respond to reported issues within 24 hours +- Log all Tier 2+ actions +- Attend mod team check-ins (monthly or as scheduled) +- Ask for help when unsure — there's no penalty for escalating + +### 10.3 Removing a moderator + +If a moderator steps down or is removed: + +1. Remove from Content Moderators Joomla group (revokes admin access). +2. Remove moderator roles on Discord, Telegram, and Facebook. +3. Revoke access to the moderation log. +4. Thank them for their service (if voluntary departure). + +--- + +## 11. Moderation Log + +All Tier 2+ actions must be logged. Use a shared document or +spreadsheet accessible to all moderators. + +Each entry should include: + +| Field | Description | +|---|---| +| Date | Date and time of the incident | +| Platform | Discord, Telegram, Facebook, Website | +| Member | Username or display name | +| Incident | Brief description of what happened | +| Rule violated | Which community guideline was broken | +| Tier | 2, 3, or 4 | +| Action taken | Warning, mute, temp ban (duration), permanent ban | +| Moderator | Who handled it | +| Notes | Context, screenshots reference, follow-up needed | + +--- + +## 12. Moderator Self-Care + +Moderation is emotionally taxing. Take care of yourself: + +- **You are not on call 24/7.** If something can wait until tomorrow, + let it wait. Mute the channel and come back fresh. +- **Tag-team difficult situations.** Don't handle a Tier 3 or 4 + alone — loop in another moderator. +- **Step away if you're angry.** You'll make better decisions calm. + Mute the conversation, take a walk, come back. +- **Debrief after hard incidents.** Talk to a fellow moderator or the + webmaster. You shouldn't carry it alone. +- **It's okay to ask for help.** If a situation is beyond your + experience, escalate to the webmaster or Moko Consulting. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | SOP | +| Domain | Community Moderation | +| Applies To | Moderators, Content Moderators, Webmaster | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/sop-moderation.md | +| Version | 00.02.00 | +| Status | Active | +| Last Reviewed | 2026-05-01 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-05-01 | Claude | Expanded: in-person events, appeals, ban evasion, onboarding, privacy/takedown, media handling | Sections 5, 6.4–6.5, 8–10 added; renumbered | +| 2026-04-27 | Claude | Initial creation | 4-tier system, platform procedures, crisis handling, mod log, self-care | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-website-management.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-website-management.-.-.md new file mode 100644 index 0000000..3e8d1bb --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-sop-website-management.-.-.md @@ -0,0 +1,441 @@ +← [Home](Home) + +# SOP — Website Management + +Standard operating procedures for the webmaster and authorized managers +of the Clarksville Furs website (clarksvillefurs.com). + +--- + +## 1. User Account Management + +### 1.1 Creating a new user account + +1. Log in to the Joomla admin at `clarksvillefurs.com/administrator`. +2. Go to **Users > Manage > + New**. +3. Fill in: name, username, email, and a temporary password. +4. Assign the user to the appropriate group(s): + - **Registered** — can log in and view member-only content + - **Event Authors** — can create and auto-publish DPCalendar events, + edit their own. Cannot post News or edit protected categories + (FAQ, About Us, Legal, SOP). + - **Content Moderators** — inherits Event Authors permissions, plus: + can edit all articles, can access the Joomla admin panel, can + manage content across all unlocked categories. + - **Manager** — full content control including News, FAQ, About Us, + Legal, and SOP categories. Admin panel access. +5. Set **Require Password Reset** to Yes. +6. Click **Save & Close**. +7. Notify the user via the Contact Us system — never send credentials + by Discord, Telegram, or any public channel. + +### 1.2 Enabling 2FA for a user + +1. The user logs in for the first time with their temporary password. +2. They are prompted to set a new password. +3. Go to **Users > Manage** and open the user's profile. +4. Under **Multi-factor Authentication**, enable **Authenticator App**. +5. The user scans the QR code with their authenticator app and enters + the verification code. + +### 1.3 Disabling or removing a user + +1. Go to **Users > Manage** and find the user. +2. To temporarily disable: set **Block User** to Yes. The account + remains but cannot log in. +3. To permanently remove: click the user, then **Delete**. This + removes the account but preserves any articles they created. + +### 1.4 Community Builder registration approval + +New registrations through Community Builder require manual approval. + +1. Check the **User Approval Queue** in the Staff Menu. +2. Review the registration: name, email, location, birthday. +3. Approve legitimate registrations. Reject obvious spam (gibberish + names, throwaway emails, empty profiles). +4. Approved users receive a welcome email automatically. + +--- + +## 2. Content Management + +### 2.1 Publishing an article + +See the [Quick Reference](quick-reference) for the step-by-step +workflow. + +### 2.2 Reviewing published content + +Event Authors can auto-publish DPCalendar events. Content Moderators +and Managers should periodically review recently published content: + +1. Go to **Content > Articles** or **Components > DPCalendar > Events** + and sort by most recent. +2. Review for: + - Accurate date, time, and location (in the body, not the intro) + - Intro text is a teaser that drives traffic to the website + - Intro image is set with alt text + - No personal contact info (emails, phone numbers) + - Tone matches the [Style Guide](style-guide) +3. If changes are needed, edit directly or contact the author. +4. If content violates Community Guidelines, unpublish immediately + and follow the [Moderation SOP](sop-moderation). + +### 2.3 Who can post where + +| Category | Event Authors | Content Mods | Manager+ | +|---|---|---|---| +| DPCalendar events | Create + publish + edit own | Edit all | Full | +| News | No access | No access | Full | +| FAQ | No access | No access | Full | +| About Us | No access | No access | Full | +| Legal | No access | No access | Full | +| SOP | No access | No access | Full | + +News articles are authored by Managers only to maintain editorial +control over official announcements. + +### 2.4 Editing an existing article + +1. Go to **Content > Articles** and find the article. +2. Click the title to open the editor. +3. Make changes and click **Save & Close**. +4. **Important**: If the article has already cross-posted to Discord, + the Discord embed will NOT update. Telegram and Facebook link + previews can be refreshed using their respective cache-clearing + tools (see [Cross-Post Preview](cross-post-preview)). + +### 2.5 Unpublishing or removing an article + +1. To hide temporarily: set **Status** to **Unpublished**. The article + stays in the database but is not visible on the site. +2. To remove permanently: set **Status** to **Trashed**, then go to + **Content > Articles**, filter by **Trashed**, select, and + **Empty Trash**. +3. Cross-posts on Discord, Telegram, and Facebook are NOT automatically + removed — delete those manually if needed. + +### 2.6 Managing the FAQ + +FAQ articles are in the **FAQ** category (ID: 31). To add a new FAQ: + +1. Create a new article in the FAQ category. +2. Write a standalone intro paragraph that fully answers the question + (see [Style Guide — Body length targets](style-guide)). +3. Add a readmore break after the intro. +4. Add detailed content below the break. +5. Set the **Ordering** to place it in the right position on the FAQ + page (see the current order by viewing the article list sorted by + ordering). + +--- + +## 3. Events (DPCalendar) + +### 3.1 Creating an event + +Events on the website use the DPCalendar component, not standard +articles. + +1. Go to **Components > DPCalendar > Events > + New**. +2. Fill in: title, start date/time, end date/time, location, and + description. +3. Set the calendar (category) and access level. +4. Add an image if available. +5. Click **Save & Close**. + +### 3.2 Member event submissions + +Members with the **Event Authors** group can submit and auto-publish +events from the frontend at `clarksvillefurs.com/events/submit`. + +Events go live immediately — no approval step. Content Moderators and +Managers should review recently published events periodically (see +Section 2.2). + +If an event needs to be taken down, a Content Moderator or Manager +can unpublish it from the admin panel. + +### 3.3 Recurring events + +For monthly meetups or regular events: + +1. Use DPCalendar's **Recurrence** feature. +2. Set the recurrence pattern (e.g., first Saturday of every month). +3. Individual occurrences can be edited without affecting the series. + +--- + +## 4. Cross-Post Management + +### 4.1 How cross-posting works + +Two integrations automatically share content to social channels: + +| Integration | Destination | Trigger | +|---|---|---| +| MokoDiscordHook | #server-announcements | `onContentAfterSave` for configured categories | +| Perfect Publisher | Facebook group + @ClarksvilleFurs Telegram | Rule Engine on category match | + +### 4.2 Verifying a cross-post + +After publishing an article or event: + +1. Wait 1–2 minutes for the integrations to fire. +2. Check #server-announcements in Discord for the embed. +3. Check @ClarksvilleFurs on Telegram for the message + link preview. +4. Check the Facebook group for the post + link card. +5. If any cross-post is missing, check that the article's category + matches the configured trigger categories. + +### 4.3 Troubleshooting cross-posts + +| Symptom | Likely cause | Fix | +|---|---|---| +| No Discord embed | Article saved in wrong category, or webhook URL expired | Verify category in article. Check MokoDiscordHook plugin settings for valid webhook URL. | +| Discord embed has wrong image | Intro Image not set, or cached | Set Intro Image in the article's Images tab. Discord caches aggressively — the image on the first post is permanent. | +| No Telegram message | Perfect Publisher rule not matching, or bot token expired | Check Rule Engine rules. Verify bot is still a member of the channel. | +| Telegram preview shows old image | Telegram caches link previews | Use [@webpagebot](https://t.me/webpagebot) to clear cache for the URL. | +| No Facebook post | Page token expired, or Rule Engine rule disabled | Re-authenticate the Facebook Page in Perfect Publisher. Check Rule Engine. | +| Facebook card shows wrong image | Facebook caches og:image | Use the [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/) to re-scrape the URL. | + +### 4.4 What cross-posts cannot do + +- Cross-posts do **not** update if you edit the article after + publishing. The Discord embed is permanent. Telegram and Facebook + can be refreshed via cache-clearing tools, but the original post + text does not change. +- Cross-posts do **not** auto-delete if you unpublish or trash the + article. Delete the Discord message, Telegram message, and Facebook + post manually. +- Cross-posts show the **intro text only**, not the full article body. + Write the intro as a teaser (see + [Style Guide](./style-guide.md#body-length-targets)). + +--- + +## 5. Community Builder Management + +### 5.1 Required registration fields + +New registrations require: first name, last name, username, email, +password, city, state, zip code, country, and birthday. + +### 5.2 Profile moderation + +Periodically review Community Builder profiles for: + +- Inappropriate profile images or avatars +- Offensive usernames or display names +- Spam or promotional content in profile bio fields +- Fake or clearly fabricated profile information + +To edit a profile: go to **Components > Community Builder > User +Management**, find the user, click to edit. + +### 5.3 Managing profile fields + +To add, remove, or change required fields: + +1. Go to **Components > Community Builder > Field Management**. +2. Find the field by name. +3. To make a field required: set **Required** to Yes. +4. To show on registration: set **Registration** to Yes. +5. To show on profile: set **Profile** to the desired visibility. + +Current required fields: first name, last name, username, email, +password, city, state, zip code, country, birthday. + +--- + +## 6. Menu Management + +### 6.1 Menu structure + +| Menu | Purpose | Audience | +|---|---|---| +| Main Menu | Primary site navigation | Everyone | +| User Menu | Login, logout, SOPs | Registered users | +| Legal Menu | Terms, Privacy, Community Guidelines | Footer links | +| Staff Menu | Profile, events, drafts, approvals | Staff/moderators | + +### 6.2 Adding a menu item + +1. Go to **Menus > [Menu Name] > + New**. +2. Set the **Menu Item Type** (Single Article, Category Blog, URL, etc.). +3. Set the **Title** and **Alias** (alias becomes the URL slug). +4. Set **Access** to control who sees the menu item (Public, Registered, + Content Moderators, etc.). +5. Set **Parent Item** to control nesting. +6. Click **Save & Close**. + +### 6.3 Reordering menu items + +1. Go to **Menus > [Menu Name]**. +2. Click the ordering column header to enable drag-and-drop. +3. Drag items to the desired position. +4. Changes take effect immediately — no save needed. + +--- + +## 7. Media Management + +### 7.1 Uploading images + +1. Go to **Content > Media** or use the inline media picker in the + article editor. +2. Organize images into folders: `events/`, `news/`, `branding/`. +3. Image requirements: + - Format: JPG for photos, PNG for graphics + - Intro images: 1200 x 630 px, under 500 KB + - Always fill in alt text +4. Do not upload images with personally identifiable information + (license plates, addresses, faces of minors without consent). + +### 7.2 Cleaning up unused media + +Periodically review the Media Manager for orphaned files: + +1. Go to **Content > Media**. +2. Sort by date and review old uploads. +3. Before deleting, search for the filename in article content to + confirm it is not in use. + +--- + +## 8. Backups and Maintenance + +### 8.1 Automated backups + +The site is backed up daily by the hosting provider. Retention: +daily for 30 days, weekly for 90 days, monthly for 12 months. + +### 8.2 Cache clearing + +After any significant content change: + +1. Go to **System > Maintenance > Clear Cache**. +2. Check all boxes and click **Clear Cache**. +3. Go to **System > Maintenance > Purge Expired Cache**. + +### 8.3 Updates + +Joomla core, template, and extension updates are managed by Moko +Consulting. Do not install updates without coordination. + +### 8.4 Scheduled maintenance checklist + +**Weekly:** + +- [ ] Review Community Builder approval queue — approve or reject + pending registrations +- [ ] Check recently published events for accuracy and guideline + compliance +- [ ] Glance at the moderation log for patterns + +**Monthly:** + +- [ ] Review Media Manager for orphaned or oversized files +- [ ] Check cross-post integrations are still firing (publish a test + event, verify all three surfaces, then unpublish) +- [ ] Review user accounts — block any that haven't logged in for + 12+ months if desired, or remove obvious spam accounts +- [ ] Clear Joomla cache (**System > Maintenance > Clear Cache**) + +**Quarterly:** + +- [ ] Review FAQ articles — are answers still accurate? Any new + questions coming up repeatedly in Discord? +- [ ] Review SOP articles — do they still match current permissions + and workflows? +- [ ] Check that 2FA is enabled for all Content Moderators and Managers +- [ ] Verify automated backups are running (check backup logs with + Moko Consulting) +- [ ] Review Community Builder required fields — are they still + appropriate? + +--- + +## 9. Analytics and Reporting + +### 9.1 What to check + +If analytics are configured (Google Analytics or Tag Manager): + +- **Pageviews**: Which pages get the most traffic? FAQ and Events + should be near the top. +- **Referral sources**: Are cross-posts driving traffic from Discord, + Telegram, and Facebook? +- **Search terms**: What are people searching for on the site? Use + this to identify missing FAQ articles. +- **Bounce rate on Events**: If people land on the events page and + leave immediately, the event descriptions may need improvement. + +### 9.2 Reporting cadence + +- **Monthly**: Glance at top pages and referral sources. No formal + report needed — just awareness. +- **Quarterly**: Share a brief summary with the team: top 5 pages, + where traffic comes from, any FAQ gaps identified. + +--- + +## 10. Emergency Procedures + +### 10.1 Site is down + +1. Check if the issue is local (try a different browser/device/network). +2. Check the hosting provider's status page. +3. Contact Moko Consulting via the Contact Us system or the emergency + contact in the onboarding documentation. +4. Do not attempt server-level fixes unless you have been trained. + +### 10.2 Security incident (defacement, unauthorized access) + +1. Do not make changes to the site — preserve evidence. +2. Contact Moko Consulting immediately. +3. If you have admin access, check **Users > Manage** for unfamiliar + accounts. +4. Change your own password immediately from a trusted device. + +### 10.3 Spam or inappropriate content + +1. Unpublish the content immediately. +2. Block the user account if applicable. +3. Document the incident (screenshot, user details, timestamp). +4. Report to Moko Consulting if the spam came through an automated + vector (registration exploit, comment spam). + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | SOP | +| Domain | Website Management | +| Applies To | Webmaster, Content Moderators | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/sop-website-management.md | +| Version | 00.02.00 | +| Status | Active | +| Last Reviewed | 2026-05-01 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-05-01 | Claude | Expanded: cross-posts, CB profiles, menus, analytics, maintenance checklist | Sections 4–6, 8.4, 9 added; permissions updated for auto-publish model | +| 2026-04-27 | Claude | Initial creation | User management, content, events, media, backups, emergencies | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-style-guide.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-style-guide.-.-.md new file mode 100644 index 0000000..2f527ed --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/authoring-style-guide.-.-.md @@ -0,0 +1,178 @@ +← [Home](Home) + +# Style Guide — Events and News + +Rules for writing articles that sound like Clarksville Furs and look +good across every surface (website, Discord, Telegram, Facebook). + +## Voice and tone + +Clarksville Furs articles should feel like a friend inviting you to +hang out — not a corporation issuing a press release. + +**Be:** + +- **Warm** — "We'd love to see you there" over "Attendance is + encouraged." +- **Direct** — short sentences, plain words. Say what's happening, + when, and where. +- **Inclusive** — write for everyone: newcomers, families, kids, people + who've never heard of the fandom. No inside jokes that leave readers + out. +- **Casual** — contractions are fine. "We're" not "We are." First + person plural ("we", "our") for the group. +- **Enthusiastic but not over-the-top** — one exclamation mark per + article is plenty. Let the event speak for itself. + +**Don't be:** + +- Corporate — no "leverage", "synergy", "stakeholders", "action items." +- Vague — "sometime in June" is not a date. Use `TBA` if it's truly + unknown (see below). +- Edgy — keep it family-friendly. No profanity, no sarcasm that could + land wrong. + +## Title format + +Use this pattern for event titles: + +``` +Event Name — Location +``` + +Examples: + +- `Monthly Meetup — Downtown Clarksville` +- `Barnaby TN Ren Fest — Triune, TN` +- `Movie Night — TBA` + +For news articles, just use a clear descriptive title: + +- `We're Live: Introducing Our New Website` +- `Summer Schedule Update` + +Rules: + +- Use an em dash ( — ) between event name and location, not a hyphen. +- Title-case the event name. +- Keep it under 70 characters so it doesn't truncate in Discord embeds. +- Don't put the date in the title — it's in the publish date and the + body. + +## Body length targets + +| Article type | Target length | Notes | +|---|---|---| +| Event listing | 50–150 words | Date, time, location, what to expect, how to RSVP | +| News post | 100–300 words | What happened or is changing, why it matters, what's next | +| Longer feature | 300–600 words | Only when the topic genuinely needs it | + +The first 1–2 sentences are the **intro**. This text appears in +cross-posts and category listings. Write the intro as a **teaser** that +hooks the reader and drives them to the full event page on the website +— do not put the full date, time, and location in the intro. Save +those details for the article body so people click through to +clarksvillefurs.com/events to get the complete picture. + +## Image specs + +Every Events article should have an **Intro Image** set. This image +appears in: + +- The category list view on the website +- Discord embeds (via MokoDiscordHook) +- Facebook link cards (via Perfect Publisher) +- Telegram link previews (via Perfect Publisher) + +| Property | Requirement | +|---|---| +| Format | JPG or PNG (JPG preferred for photos) | +| Dimensions | 1200 x 630 px (landscape, 1.91:1 ratio) | +| File size | Under 500 KB | +| Alt text | Required. Describe what's in the image, not the event title. Example: "Furries in costume at a park picnic table" | + +Tips: + +- Avoid text overlaid on the image — it gets cropped differently on + each platform. +- Use a photo of the venue, the group, or the activity. Generic stock + images feel impersonal. +- If you don't have a photo, use the CF mascot image from the Media + Manager rather than leaving it blank. + +## Using TBA for unknown details + +If the date, time, or location isn't confirmed yet, use `TBA` +(To Be Announced) as a placeholder: + +- **Date unknown:** Set the publish date to today and write "Date: TBA" + in the body. Update the article when the date is confirmed. +- **Location unknown:** Use `TBA` in the title where the location goes: + `Monthly Meetup — TBA` +- **Time unknown:** Write "Time: TBA" in the body. + +Always go back and update TBA fields before the event. A stale TBA +looks like nobody's running things. + +## Recurring events + +For recurring events (monthly meetups, weekly game nights): + +- Create a **new article** for each occurrence. Don't edit the old one. +- Use a consistent title pattern: `Monthly Meetup — Downtown Clarksville` + (same name each time, location may change). +- In the body, reference that this is a recurring event: + "Our monthly meetup is back! This month we're at..." +- Set the **Start Publishing** date to a few days before the event so + it shows up in the listing with lead time. + +## What NOT to do + +- **Don't use HTML in the article body** unless you're using an + approved utility class (see + [Content Authoring Guide](content-authoring)). The editor's + visual mode handles formatting. +- **Don't hardcode brand colors** inline — use `.cf-brand-accent` or + `.cf-brand-callout` instead. See the + [Content Authoring Guide](../content-authoring.md#patterns-to-avoid). +- **Don't leave Alt Text blank** on images. Screen readers need it, and + social platforms use it as fallback text. +- **Don't write a novel.** If your event listing is over 200 words, + you're probably over-explaining. Trust the reader. +- **Don't duplicate the title in the first sentence.** The title is + already displayed above the body. +- **Don't use all caps** for emphasis. Bold a word if you must. +- **Don't link to personal social media accounts** — only official CF + channels. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | guide | +| Domain | Content Authoring | +| Applies To | Event Authors group, Webmaster | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/authoring/style-guide.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Initial creation | Phase 3 voice, title, image, and formatting rules | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/brand-reference.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/brand-reference.-.-.md new file mode 100644 index 0000000..65a3664 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/brand-reference.-.-.md @@ -0,0 +1,158 @@ +← [Home](Home) + +# Brand Reference — Clarksville Furs + +## Core palette + +Nine tokens. Every color on the site should trace back to one of these. + +| Token | Hex | Role | +|---|---|---| +| Sky Primary | `#9CCEDB` | Large surfaces, hero washes, block-color-1 | +| Sky Secondary | `#7FB7C6` | Gradient depth, light-mode `--color-primary`, bottom-a container | +| Sky Raw (`--sky`) | `#a3cde2` | Module tints, `.custom.sky` cards, top-b container background | +| Coral Accent | `#FF4B3E` | CTAs, links, focus, `.btn-primary`, brand-accent text | +| Ink Outline | `#1E1E1E` | Body text, linework, light-mode navigation background | +| Mascot White | `#F4F4F4` | Soft surfaces, on-dark button text | +| Mascot Grey | `#8F8F8F` | Muted text, secondary neutral | +| Gold Eye | `#F5C518` | Highlights, warning states, `.custom.yellow` cards | +| Soft Red | `#ff7a73` | `.btn-danger`, `.custom.red` cards — softer than coral, semantic danger | + +The Sky Raw token `--sky` is available as a CSS custom property for direct +reference in article HTML, module content, and user extensions. Prefer it over +hardcoding `#a3cde2`. + +## Typography + +**Primary:** Fredoka (variable weight 300–700). Loaded locally from +`/media/templates/site/mokoonyx/fonts/Fredoka-Variable.ttf` via `@font-face` in +`user.css`. + +**Secondary:** Nunito (weights 400–700). Loaded from Google Fonts for resilience; +bundle locally if performance audits require it. + +**Stack:** + +```css +--body-font-family: "Fredoka", "Nunito", "Inter", + -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, + "Helvetica Neue", Arial, "Noto Sans", sans-serif; +``` + +**Weight scale (per brand guide):** + +| Element | Weight | Notes | +|---|---|---| +| `h1`–`h3`, `.site-title` | 700 | Fredoka, letter-spacing `-0.01em` | +| `h4`–`h6` | 600 | Fredoka | +| `.lead`, `.callout`, `.subhead` | 500 | Fredoka | +| Body (`p`, `li`, `td`, `dd`) | 400 | Nunito falls back to Fredoka | +| `small`, `.text-muted`, `.meta` | 300 | Nunito | + +**Note on `.site-title`:** MokoOnyx's base template ships with an "Osaka" font +loaded via `fonts/osaka.css`. CF overrides this with `!important` in `user.css` +to force Fredoka on site title markers. If the MokoOnyx template is updated and +this class changes, the override may need to follow. + +## Design decisions + +These are the non-obvious choices that drive the look and won't survive a naïve +"reset to defaults" pass. Read before changing anything in the theme. + +### `--color-primary` is Sky Secondary (#7FB7C6) in light mode, not coral + +MokoOnyx's offline page uses `--color-primary` as a full-viewport background. +Coral at that scale would be jarring. Sky-secondary reads warm and on-brand at +hero scale. Coral retains its role as the action color via Bootstrap's `--primary`. + +### Navigation is ink in light mode, dark-neutral in dark mode + +Light mode uses `#1E1E1E` ink as nav background with mascot-white text — structural +brand presence at the top of every page. Dark mode uses `#151B22` neutral dark so +the nav doesn't compete with content for attention. Active link is coral in light, +sky in dark. + +### Baseline `--border-radius` is 0.875rem + +Matches the template's own offline-card radius. Gives consistent soft-rounded +surfaces across form controls, badges, alerts, dropdowns, popovers, toasts. +Cards use a slightly larger 1rem radius; hero cards use 1.25rem. + +### Coral hover on dark-tint cards fails AA + +`.custom.green` cards (`#448344`) keep white text (4.61:1 AA pass) but the +coral hover on green links is 1.39:1 — visually invisible. This is documented +in-file. If hover legibility becomes a complaint, swap hover to ink. + +### `.custom.red` uses ink text, not white + +White on `#ff7a73` is 2.53:1 (AA fail). Ink is 5.79:1 (AA pass) AND reads +warmer, which matches the "Celebrating Individuality" card's intended tone. +This is a deliberate departure from the "white on colored card" convention. + +### `--danger` is soft red (#ff7a73), not coral + +Bootstrap expects primary and danger to be distinct colors. Coral owns primary +(brand action); soft red owns danger (alarm states). A compatibility rule in +`user.css` keeps `.text-danger` on `h1`–`h6` and `.display-*` rendering as coral +so existing hero content (which uses `.text-danger` decoratively) still reads as +brand-accent. New decorative uses should prefer `.cf-brand-accent`. + +## Accessibility baselines + +All non-incidental text on the live site is checked to at least WCAG AA (4.5:1 +for normal text, 3:1 for ≥18pt or ≥14pt bold). Known exceptions are documented +in [accessibility.md](accessibility). + +**Contrast pairs that pass AA or better:** + +| Foreground | Background | Ratio | Grade | +|---|---|---|---| +| Ink `#1E1E1E` | White `#FFFFFF` | 15.3:1 | AAA | +| Ink `#1E1E1E` | Sky Primary `#9CCEDB` | 10.97:1 | AAA | +| Ink `#1E1E1E` | Sky Secondary `#7FB7C6` | 8.22:1 | AAA | +| Ink `#1E1E1E` | Sky Raw `#a3cde2` | 12.1:1 | AAA | +| Ink `#1E1E1E` | Coral `#FF4B3E` | 5.16:1 | AA | +| Ink `#1E1E1E` | Soft Red `#ff7a73` | 5.79:1 | AA | +| Ink `#1E1E1E` | Gold `#F5C518` | 11.5:1 | AAA | +| White `#F4F4F4` | Ink `#1E1E1E` | 15.3:1 | AAA | +| White `#F4F4F4` | Dark Green `#448344` | 4.61:1 | AA | + +**Contrast pairs that fail AA (known, documented, handled):** + +| Foreground | Background | Ratio | Mitigation | +|---|---|---|---| +| Coral `#FF4B3E` | Sky Primary | 2.33:1 | Scoped override: links on sky containers flip to ink | +| Coral `#FF4B3E` | Sky Secondary | 2.06:1 | Scoped override (same) | +| Coral `#FF4B3E` | White (small text) | 3.63:1 | Only used for large text / headings (AA-large passes) | +| White | Soft Red | 2.53:1 | Not used — `.custom.red` uses ink text instead | + +## Metadata + +| Field | Value | +|---|---| +| Document Type | reference | +| Domain | Brand | +| Applies To | All client-clarksvillefurs theme and content work | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/brand-reference.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-21 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-21 | Claude | Initial creation | Synthesized from brand guide + theme work | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/content-authoring.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/content-authoring.-.-.md new file mode 100644 index 0000000..98730e2 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/content-authoring.-.-.md @@ -0,0 +1,184 @@ +← [Home](Home) + +# Content Authoring Guide + +This is for whoever writes articles, modules, and page content in the Joomla +admin. The CF theme adds a small library of utility classes that make it easy +to put on-brand components into articles without touching CSS. + +## Quick lookup: "I want to…" + +| Goal | Use | Example | +|---|---|---| +| Add a warm welcome/community box | `.cf-brand-callout` | See below | +| Make heading text pop coral | `.cf-brand-accent` | `Your place.` | +| Tint a feature card sky blue | `.custom.sky` wrapper on a `.card` | See below | +| Tint a feature card red/yellow/green | `.custom.red` / `.custom.yellow` / `.custom.green` | See below | +| Heavy sticker outline around any box | `.cf-sticker` | See below | + +## `.cf-brand-callout` — welcome and community boxes + +Use for the "💙 Clarksville Furs is an all-ages, family-friendly community" +pattern on the FAQ page and similar. Handles the sky background, ink text, +readable link color (ink with coral hover), and flex layout for an icon + +paragraph. + +```html +

+ 💙 +

+ Clarksville Furs is an all-ages, family-friendly community. + Find us on Discord, + Telegram, and + Facebook. +

+
+``` + +**Do not** author this as inline `
`. +The utility class handles the contrast scoping automatically — the inline +pattern is legacy and currently works via a selector hack in `user.css` but +should be migrated. + +## `.cf-brand-accent` — coral brand-pop text + +For the "pop of coral" on big headings that used to be done with `.text-danger`. + +```html +

+ Your place. Your pack. +

+``` + +`.text-danger` on h1–h6 and `.display-*` still renders as coral via a +compatibility rule, so existing content doesn't break — but `.cf-brand-accent` +is semantically correct and should be used for all new content. + +## `.custom.{sky|red|yellow|green}` — tinted feature cards + +Wrap a standard Bootstrap `.card` in a `.mod-custom.custom.{color}` module +wrapper (or any div with `custom.{color}`) to paint it with a brand tint. The +card-body text color auto-flips for legibility. + +```html +
+
+
+ +
Belonging First
+

+ Every decision starts with one question: will this make someone + feel welcome? +

+
+
+
+``` + +Tint → text-color mapping: + +| Class | Card bg | Card body text | AA on body | +|---|---|---|---| +| `.custom.sky` | `#a3cde2` | Ink (black) | 12.1:1 AAA | +| `.custom.red` | `#ff7a73` | Ink (black) | 5.79:1 AA | +| `.custom.yellow` | `#ffd166` | Ink (black) | 13.3:1 AAA | +| `.custom.green` | `#448344` | White | 4.61:1 AA | + +Links inside these cards are auto-styled: + +- `.custom.sky`, `.custom.red`, `.custom.yellow` — ink links, coral hover +- `.custom.green` — white links, coral hover (hover contrast is low — don't + rely on hover color alone to indicate interactivity) + +## `.cf-sticker` — heavy-outline sticker aesthetic + +Opt-in mascot-inspired look: thick outline and hard-offset shadow that lifts on +hover. Use sparingly, for feature callouts and stickers where the brand +personality should shout. + +```html +
+

Meet-up this Saturday

+

Join us at the park — bring snacks, bring friends.

+
+``` + +## Patterns to avoid + +### Inline hex colors for brand colors + +```html +Your place. + +Your place. +``` + +Hardcoded hexes don't update when the theme does. If the brand ever shifts +(new accent color, tonal correction), utility classes update site-wide in a +single CSS change. + +### Inline `style="background: var(--color-primary)"` + +Currently works because `user.css` has a scoped override, but it's fragile. +Prefer `.cf-brand-callout` for callout boxes. + +### White-on-coral text + +```html +Join us + +Join us +``` + +The `.btn-primary` class handles the ink-on-coral contrast correctly. Don't +re-invent it inline. + +### Hardcoded brand colors that fail contrast + +The home page currently has a Telegram CTA with `style="background: #26A5E4; +color: #fff;"` — white on Telegram's official light cyan measures 2.44:1, fails +AA. Either use ink text (`color: #1E1E1E`, 5.09:1 AA) or switch to Telegram's +darker brand variant `#0088CC`. + +## Common edits that need a content pass + +When any of these come up in an editor review, expect to fix content, not CSS: + +- **Placeholder URLs** like `/YOUR_FACEBOOK_URL`, `YOUR_DISCORD_INVITE_URL`, + `YOUR_TELEGRAM_URL` — real URLs are `/discord` and `/telegram` (server-side + redirects). Facebook needs a real URL or the mention should be removed. +- **Hardcoded brand-color CTAs** without contrast audit — Discord `#5865F2` + with white text is fine (4.50:1), Telegram `#26A5E4` fails. +- **Decorative `.text-danger`** on body text — only on headings does the + compatibility rule keep it coral. On body text it renders as soft red + (correctly, semantically), which may not be the author's intent. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | guide | +| Domain | Content Authoring | +| Applies To | All Joomla article editors working on the CF site | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/content-authoring.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-21 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-21 | Claude | Initial creation | Covers v02.06.00 theme utility classes | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/css-variables.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/css-variables.-.-.md new file mode 100644 index 0000000..3126d51 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/css-variables.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# CSS Variables Reference + +Quick reference for the CSS custom properties that drive the CF theme. The full +theme files (`light.custom.css` and `dark.custom.css`) declare 924+ variables +each, but most are Bootstrap internals that inherit from the tokens below. Edit +the tokens, not the internals. + +Base template: [MokoOnyx](https://github.com/mokoconsulting-tech/MokoCassiopeia) +(formerly MokoCassiopeia). + +--- + +## Brand tokens + +These are the raw CF brand values. Every other variable in the theme should +trace back to one of these. + +| Token | Variable | Light | Dark | Notes | +|---|---|---|---|---| +| Sky Primary | `--accent-color-secondary` (light) / `--color-primary` (dark) | `#9CCEDB` | `#9CCEDB` | Hero washes, large surfaces | +| Sky Secondary | `--color-primary` (light) / `--accent-color-secondary` (dark) | `#7FB7C6` | `#7FB7C6` | Gradient depth, offline page bg | +| Sky Raw | `--sky` | `#a3cde2` | `#a3cde2` | Module tints, `.custom.sky` cards | +| Coral | `--accent-color-primary` | `#FF4B3E` | `#FF4B3E` | CTAs, links, focus rings | +| Ink | `--body-color` (light) | `#1E1E1E` | n/a | Body text, linework | +| Mascot White | `--white` | `#F4F4F4` | `#F4F4F4` | Soft surfaces, on-dark text | +| Mascot Grey | `--muted-color` | `#8F8F8F` | `#8F8F8F` | Secondary text | +| Gold | `--yellow` | `#F5C518` | `#F5C518` | Highlights, warnings | +| Soft Red | `--danger` | `#ff7a73` | `#ff7a73` | Danger states | + +**Key light/dark swap:** `--color-primary` is Sky Secondary in light mode but +Sky Primary in dark mode. This is intentional — see +[brand-reference.md](./brand-reference.md#--color-primary-is-sky-secondary-7fb7c6-in-light-mode-not-coral) +for the reasoning. + +--- + +## Bootstrap palette mapping + +CF brand tokens mapped to Bootstrap's contextual color system. These drive +`.btn-*`, `.bg-*`, `.text-*`, `.border-*`, `.alert-*`, and `.badge-*` utilities. + +| Bootstrap semantic | Light value | Dark value | CF token | +|---|---|---|---| +| `--primary` | `#FF4B3E` (Coral) | `#FF4B3E` | Coral Accent | +| `--secondary` | `#8F8F8F` (Mascot Grey) | `#8F8F8F` | Mascot Grey | +| `--success` | `#4AA664` | `#4AA664` | -- (standard green) | +| `--info` | `#7FB7C6` (Sky Secondary) | `#7FB7C6` | Sky Secondary | +| `--warning` | `#F5C518` (Gold) | `#F5C518` | Gold Eye | +| `--danger` | `#ff7a73` (Soft Red) | `#ff7a73` | Soft Red | +| `--light` | `#F4F4F4` (Mascot White) | `#F4F4F4` | Mascot White | +| `--dark` | `#1E1E1E` (Ink) | `#1E1E1E` | Ink Outline | + +**Note:** `--primary` is Coral (the action color), not Sky. `--info` is Sky +Secondary. This is deliberate — Coral is the CTA/interaction color across the +site; Sky is the ambient brand surface. + +--- + +## Dark mode color strategy + +The theme supports full light/dark mode switching. Key differences: + +| Property | Light | Dark | Why | +|---|---|---|---| +| `--color-primary` | `#7FB7C6` (Sky Secondary) | `#9CCEDB` (Sky Primary) | Lighter sky reads better against dark backgrounds | +| `--body-color` | `#1E1E1E` (Ink) | `#E6EBF1` (Light gray) | Ink is the text color in light; light gray in dark | +| `--body-bg` | `#FFFFFF` | `#0E1318` (Near-black) | | +| `--heading-color` | `#1E1E1E` | `#F4F4F4` (Mascot White) | | +| `--nav-bg-color` | `#1E1E1E` (Ink) | `#151B22` (Dark neutral) | Ink nav is structural in light; neutral in dark so nav doesn't compete with content | +| `--navbar-active-color` | `#FF4B3E` (Coral) | `#FF4B3E` (Coral) | Same — coral stays the active indicator | +| `--link-color` | `#FF4B3E` (Coral) | `#FF4B3E` (Coral) | Same — coral links in both modes | +| `--link-hover-color` | `#E03828` (Darker coral) | `#E03828` | Same | +| `--code-color` | `#FF4B3E` | `#FF7A6F` (Lighter coral) | Softer in dark for readability | +| `--secondary-bg` | `#F4F4F4` | `#151B22` | Card backgrounds, dropdowns | +| `--card-bg` | `#F4F4F4` (via `--secondary-bg`) | `#151B22` | | +| `--border-color` | `#D6D6D6` | `#2b323b` | | + +The `--sky` token is mode-invariant (`#a3cde2` in both). This means +`.custom.sky` cards and `--sky`-based surfaces look the same regardless of +mode — the surrounding page contrast changes, not the card itself. + +--- + +## Typography variables + +Typography is mode-invariant — defined once in the theme files and reinforced +by `user.css`. + +| Variable | Value | Notes | +|---|---|---| +| `--body-font-family` | `'Fredoka', 'Nunito', -apple-system, ...` | Full stack in both theme files + `user.css` | +| `--body-font-size` | `1rem` | | +| `--body-font-weight` | `400` | Nunito for body text | +| `--body-line-height` | `1.5` | | +| `--font-monospace` | `SFMono-Regular, Menlo, Monaco, ...` | Standard monospace stack | + +Weight hierarchy is enforced by `user.css`, not the theme files — see +[brand-reference.md](./brand-reference.md#typography). + +--- + +## Border & radius + +| Variable | Value | Notes | +|---|---|---| +| `--border-radius` | `0.875rem` | Baseline for all CF components | +| `--border-radius-sm` | `0.5rem` | Badges, small controls | +| `--border-radius-lg` | `1.25rem` | Hero cards | +| `--border-radius-xl` | `1.5rem` | | +| `--border-radius-pill` | `50rem` | Fully rounded (pills, FABs) | +| `--card-border-radius` | `1rem` | Cards slightly larger than baseline | +| `--border-color` | `#D6D6D6` (light) / `#2b323b` (dark) | | + +--- + +## Container color map + +MokoOnyx defines several page-region containers. These are the CF color +assignments: + +| Container | Light bg | Dark bg | Notes | +|---|---|---|---| +| Header | `light_skybackground.png` | (image) | Background image, not a flat color | +| Below Topbar | `#F4F4F4` (Mascot White) | `#151B22` | Soft neutral strip | +| Top A | `none` (transparent) | `none` | Inherits page bg | +| Top B | `var(--sky)` = `#a3cde2` | `var(--sky)` | Sky-tinted — triggers contrast overrides | +| TOC | `var(--secondary-bg)` | `var(--secondary-bg)` | Sidebar table of contents | +| Sidebar | `#F4F4F4` | `#151B22` | 0.75rem radius | +| Bottom A | `#7FB7C6` (Sky Secondary) | varies | Sky-tinted — triggers contrast overrides | +| Bottom B | `#1E1E1E` (Ink) | `#0E1318` | Dark strip, typically footer area | + +**Contrast implications:** Top B and Bottom A use sky backgrounds, which means +links inside them are automatically flipped to ink via the scoped override in +`user.css`. See [accessibility.md](./accessibility.md#coral-on-sky-links-fail-aa--fixed). + +--- + +## Button variants + +All buttons use ink (`#1E1E1E`) text for AA contrast. The `.btn-dark` variant +uses Mascot White text instead. + +### Solid buttons + +| Class | Background | Hover bg | CF token | +|---|---|---|---| +| `.btn-primary` | `#FF4B3E` (Coral) | `#FF6B60` | Coral Accent | +| `.btn-secondary` | `#9CCEDB` (Sky Primary) | `#7FB7C6` | Sky Primary | +| `.btn-success` | `#78D694` | `#9CE3B2` | -- | +| `.btn-info` | `#9CCEDB` (Sky Primary) | `#7FB7C6` | Sky Primary | +| `.btn-warning` | `#F5C518` (Gold) | `#FFD84A` | Gold Eye | +| `.btn-danger` | `#ff7a73` (Soft Red) | `#e5615a` | Soft Red | +| `.btn-light` | `#F4F4F4` (Mascot White) | `#FFFFFF` | Mascot White | +| `.btn-dark` | `#1E1E1E` (Ink) | `#333333` | Ink Outline | + +### Outline buttons + +Outline variants use the brand color as text/border color and fill on hover: + +| Class | Text/border | Hover fill | +|---|---|---| +| `.btn-outline-primary` | Coral `#FF4B3E` | Coral | +| `.btn-outline-secondary` | Sky `#9CCEDB` | Sky | +| `.btn-outline-success` | `#78D694` | Green | +| `.btn-outline-info` | Sky `#9CCEDB` | Sky | +| `.btn-outline-warning` | Gold `#F5C518` | Gold | +| `.btn-outline-danger` | `#c0453e` | Soft Red | +| `.btn-outline-light` | Mascot White | Mascot White | +| `.btn-outline-dark` | `#B8C3CB` | `#B8C3CB` | + +All solid buttons have `--btn-border-color: #1E1E1E` (ink outline) for the +sticker/outlined aesthetic. Outline buttons swap to ink border on hover. + +--- + +## Hero system + +Two hero variants for banner sections: + +| Variant | Background | Overlay | Text color | +|---|---|---|---| +| Primary | Sky Primary `#9CCEDB` | 55% sky gradient | Ink `#1E1E1E` | +| Secondary | Ink `#1E1E1E` | 78% ink overlay | Mascot White `#F4F4F4` | + +Hero card dimensions: `max-width: 800px`, `padding: 3rem 2rem`, +`border-radius: 1.25rem`. Alt card is narrower at `600px`. + +--- + +## Block colors + +Used for module position color rotation (top-a, top-b, bottom-a, bottom-b): + +| Block | Background | Text | Typical use | +|---|---|---|---| +| Block 1 | `var(--secondary-bg)` | `var(--body-color)` | Neutral modules | +| Block 2 | Coral `#FF4B3E` | Mascot White | CTA modules | +| Block 3 | Gold `#F5C518` | Gold | Highlight modules | +| Block 4 | Mascot White `#F4F4F4` | Sky Primary | Light modules | + +Additional block overrides: + +| Variable | Value | Use | +|---|---|---| +| `--block-highlight-bg` | Gold 18% opacity | Subtle gold wash | +| `--block-cta-bg` | Coral solid | Call-to-action blocks | +| `--block-alert-bg` | Coral 18% opacity | Alert/notice blocks | + +--- + +## Editing guidelines + +1. **Edit brand tokens, not internals.** If you need to change a color, find + the brand token it maps to and change that. The 900+ downstream variables + inherit automatically. + +2. **Edit in both theme files.** Every color change in `light.custom.css` + likely needs a corresponding change in `dark.custom.css`. + +3. **Run a contrast audit** after any color change. See + [accessibility.md](./accessibility.md#audit-tools) for tools. + +4. **Bump the file version** in the header comment on every edit. + +5. **Clear Joomla cache** after deploying — see + [deployment.md](deployment) for the full workflow. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | reference | +| Domain | CSS Variables | +| Applies To | All CSS changes in light.custom.css, dark.custom.css, user.css | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/css-variables.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-22 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-22 | Claude | Initial creation | Replaces deleted CSS_VARIABLES.md with focused reference | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/deployment.md b/ClarksvilleFurs/client-waas-clarksvillefurs/deployment.md new file mode 100644 index 0000000..a705597 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/deployment.md @@ -0,0 +1,180 @@ +← [Home](Home) + +# Deployment + +## Environments + +| Environment | URL | Purpose | +|---|---|---| +| Development | `clarksvillefurs.dev.mokoconsulting.tech` | Moko internal staging — first stop for all changes | +| Production | `clarksvillefurs.com` | Live site | + +Development mirrors production's Joomla version, template, extensions, and +data. Testing on dev first is required for every theme change. + +## Theme package deliverables + +A theme-only deploy consists of three CSS files and, if changed, the font file: + +``` +deploy/ +├── images/ +│ └── branding/ +│ ├── logo_full_wide.png +│ ├── mascot.png +│ └── web_logo_full_wide.png +└── media/ + └── templates/ + └── site/ + └── mokoonyx/ + ├── css/ + │ ├── theme/ + │ │ ├── light.custom.css + │ │ └── dark.custom.css + │ └── user.css + └── fonts/ + └── Fredoka-Variable.ttf +``` + +## SFTP deployment (manual, current process) + +Copy SFTP credentials from `docs/templates/sftp-config.json.template` into a +local, gitignored `sftp-config.json`. Connect via any SFTP client (Transmit, +FileZilla, Cyberduck, rsync over ssh). + +**Upload paths** (relative to Joomla web root): + +- `/media/templates/site/mokoonyx/css/theme/light.custom.css` +- `/media/templates/site/mokoonyx/css/theme/dark.custom.css` +- `/media/templates/site/mokoonyx/css/user.css` +- `/media/templates/site/mokoonyx/fonts/Fredoka-Variable.ttf` *(only if font file changed)* +- `/images/branding/*.png` *(only if images changed)* + +**Note:** The template directory on the server may still be +`/media/templates/site/mokocassiopeia/` if the MokoCassiopeia → MokoOnyx rename +has not yet been completed on that environment. Check the actual directory +name with `ls` on the server; the *file contents* reference `mokoonyx` in +their headers regardless of the current folder name, which is correct +forward-looking metadata. + +## Cache busting after deploy + +Joomla caches heavily. After uploading CSS, always: + +1. Joomla admin → **System → Maintenance → Clear Cache** → check all boxes → Clear Cache +2. Joomla admin → **System → Maintenance → Purge Expired Cache** +3. Verify cache-bust query string on the CSS URL changed (e.g. `?475b76` → new hash) + +If the query string didn't change, the template file mod-times weren't +picked up. Touching any file in the template directory (e.g. via SFTP `touch` +or re-saving the template in admin) forces a regeneration. + +Hard-refresh the browser (Ctrl+Shift+R / Cmd+Shift+R) to bypass local cache. + +## Verification checklist + +On the dev environment, after every deploy: + +1. Home page loads without console errors +2. Light mode renders as expected (sky header PNG, ink nav, coral CTAs) +3. Dark mode toggle works — CSS vars all resolve, no broken fallbacks +4. Hero "Your place." renders as coral (not washed pink) in light mode +5. `.custom.{sky,red,yellow,green}` cards render with correct tints and readable text +6. FAQ page blue callout at top — links are ink, not coral +7. Footer / `.container-bottom-a` — sky-secondary bg, ink text, link overrides working +8. No FOUC on Fredoka font load (font-display: swap handles this) +9. Contrast spot-checks on any new text/bg pair using browser DevTools + +If any check fails, roll back (reupload previous version) before promoting +to production. + +## Automated dev → live sync (daily cron) + +Dev and live share the same database, so only the filesystem needs syncing. +A cron job on the dev server runs `rsync` daily at **3:00 AM server time** to +push filesystem changes to live. + +### How it works + +| Component | Location (dev server) | +|---|---| +| Script | `/home/clarksvillefurs/scripts/sync-dev-to-live.sh` | +| SSH key | `~/.ssh/id_sync_to_live` (ed25519, authorized on live) | +| Cron entry | `0 3 * * * /home/clarksvillefurs/scripts/sync-dev-to-live.sh` | +| Log file | `/home/clarksvillefurs/scripts/logs/sync-dev-to-live.log` | + +The script uses `rsync -avz --delete` with excludes for environment-specific +files (`configuration.php`, `.htaccess`, `cache/`, `tmp/`, `logs/`, +dev-only files, DreamHost system files). It includes a PID-based lock file +to prevent overlapping runs. + +### Manual run + +SSH into the dev server and execute directly: + +```bash +/home/clarksvillefurs/scripts/sync-dev-to-live.sh +cat /home/clarksvillefurs/scripts/logs/sync-dev-to-live.log +``` + +### Updating the script + +The canonical copy lives in the repo at `scripts/sync-dev-to-live.sh`. +After editing, SCP it to the dev server: + +```bash +scp scripts/sync-dev-to-live.sh clarksvillefurs@dev.mokoconsulting.tech:/home/clarksvillefurs/scripts/ +ssh clarksvillefurs@dev.mokoconsulting.tech "sed -i 's/\r$//' /home/clarksvillefurs/scripts/sync-dev-to-live.sh" +``` + +The `sed` command strips Windows line endings (required for bash execution). + +## Production promotion (manual) + +Only after full dev verification: + +1. Upload the same files to production SFTP (or wait for the next automated sync at 3 AM) +2. Run the same cache-clear sequence in production Joomla admin +3. Verify the same checklist in an incognito window against the production URL +4. Tag the git commit with the release version (`git tag v02.06.00 && git push --tags`) + +## Rollback + +Keep the previous working version of each CSS file in `/deploy/archive/vXX.YY.ZZ/` +before uploading. If production starts throwing errors or visibly breaks: + +1. SFTP upload the previous version back into place +2. Clear caches +3. Verify the rollback worked +4. Root-cause the failure on dev before re-attempting + +## Metadata + +| Field | Value | +|---|---| +| Document Type | guide | +| Domain | DevOps | +| Applies To | All theme and template deployments | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/deployment.md | +| Version | 00.02.00 | +| Status | Active | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Added automated dev→live sync section | Cron rsync workflow, script reference, manual run instructions | +| 2026-04-21 | Claude | Initial creation | SFTP workflow, cache-busting, rollback | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/migration-plan-events.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/migration-plan-events.-.-.md new file mode 100644 index 0000000..a8b4405 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/migration-plan-events.-.-.md @@ -0,0 +1,248 @@ +← [Home](Home) + +# Migration Plan — Events and News + +End-to-end plan for enabling Clarksville Furs managers to author event +listings and news posts that automatically cross-post to Discord, +Telegram, and Facebook. + +## Goal + +Give the **Event Authors** Joomla group a self-service workflow: +create an article in the Events or News category, attach an image, +publish — and have the post appear on all CF social channels within +minutes, with no webmaster intervention. + +## Stakeholders + +| Role | Responsibility | +|---|---| +| Moko Consulting | Technical implementation, plugin configuration, documentation, training | +| Webmaster | Account provisioning, 2FA setup, day-to-day oversight | +| Event Authors | Article creation and publishing | + +--- + +## Phase 1 — Infrastructure + +Set up the Joomla categories, user group, and plugin wiring. + +### 1.1 Create content categories + +- [ ] **Events** category under `com_content` (published, public access) +- [ ] **News** category under `com_content` (published, public access) + — News (ID: 16) already exists; verify description and alias + +### 1.2 Create the Event Authors user group + +- [ ] Create Joomla user group **Event Authors** (child of Registered) +- [ ] Grant article-create and article-edit-own permissions on the + Events and News categories +- [ ] Deny publish permission — articles default to Unpublished until + a moderator (or the webmaster) approves, unless the author also + holds a higher group +- [ ] Assign initial members + +### 1.3 Configure MokoDiscordHook + +MokoDiscordHook fires `onContentAfterSave` and sends a Discord embed. + +- [ ] Install / verify MokoDiscordHook plugin is enabled +- [ ] Set the target Discord webhook URL for #server-announcements +- [ ] Configure category trigger: Events category ID, News category ID +- [ ] Embed fields mapped: + - **Title** ← article title + - **Description** ← article intro text + - **Image** ← intro image URL + - **Link** ← full article URL on clarksvillefurs.com + +### 1.4 Configure Perfect Publisher + +Perfect Publisher posts to Facebook and Telegram via the Rule Engine. + +- [ ] Install / verify Perfect Publisher is enabled +- [ ] Connect Facebook group (clarksvillefurs) — verify Page token is valid +- [ ] Connect Telegram channel (@ClarksvilleFurs) — verify + bot token and channel membership +- [ ] Create Rule Engine rules: + - **Rule: Events → FB + Telegram** — category match on Events, + action = publish to FB Page + Telegram channel + - **Rule: News → FB + Telegram** — category match on News, + action = publish to FB Page + Telegram channel +- [ ] Post content mapped: + - **Facebook**: intro text as post body, article URL as link + (link card pulls `og:title`, `og:image`, `og:description`) + - **Telegram**: intro text + article URL as message body + (link preview pulls from Open Graph meta tags) + +### 1.5 Verify Open Graph tags + +- [ ] Confirm Joomla outputs `og:title`, `og:description`, `og:image` + for articles (MokoOnyx or a plugin handles this) +- [ ] Test with Facebook Sharing Debugger and Telegram @webpagebot + +--- + +## Phase 2 — Dry run + +Validate the full pipeline end-to-end before handing off to authors. + +### 2.1 Test article pipeline + +- [ ] Create a test article in the Events category with: + - Title following style guide format: `Test Event — Downtown Clarksville` + - 1–2 sentence intro text + - Intro image (1200x630 JPG, with alt text) + - Publish date set to now + - Status = Published +- [ ] Verify article appears on the website Events listing +- [ ] Verify Discord embed arrives in #server-announcements + - Title, description, image, link all correct +- [ ] Verify Telegram message arrives in @ClarksvilleFurs + - Message text, link preview card all correct +- [ ] Verify Facebook post appears on clarksvillefurs group + - Post text, link card image and title all correct +- [ ] Repeat for a News category article +- [ ] Delete or unpublish test articles after verification + +### 2.2 Test author permissions + +- [ ] Log in as an Event Authors member (not a super admin) +- [ ] Confirm the user can create articles in Events and News +- [ ] Confirm the user cannot edit other users' articles +- [ ] Confirm the user cannot access admin areas beyond Content + +### 2.3 Test edge cases + +- [ ] Article with no intro image — cross-posts should still work + (no image in embed, but no error) +- [ ] Article with a very long title (70+ characters) — check + truncation on Discord embed +- [ ] Article saved as Unpublished — cross-posts should NOT fire +- [ ] Article edited after publishing — Discord embed does NOT update + (expected; document this for authors) + +--- + +## Phase 3 — Documentation and training + +Author the manager-facing documentation and record the walkthrough. + +### 3.1 Authoring documentation + +All files live under `docs/authoring/`. See the +[Authoring Documentation Index](authoring-README) for the full +list and reading order. + +| Document | Purpose | +|---|---| +| [README](authoring-README) | Index, audience, reading order | +| [Quick Reference](authoring-quick-reference) | One-page cheat sheet — log in through publish | +| [Style Guide](authoring-style-guide) | Voice, tone, title format, image specs, don'ts | +| [Cross-Post Preview](authoring-cross-post-preview) | Field-to-surface mapping with worked example | +| [Screencast Script](authoring-screencast-script) | 8-scene spoken script for the walkthrough recording | + +### 3.2 Dry-run checklist for docs + +Each document must have: + +- [ ] Moko HTML-comment file header (Copyright, SPDX, FILE INFORMATION) +- [ ] DEFGROUP: `ClarksvilleFurs.Documentation` +- [ ] INGROUP: `ClarksvilleFurs` +- [ ] VERSION starting at `00.01.00` +- [ ] Metadata table and Revision History table at the bottom +- [ ] Pure Markdown body — no HTML except the file header +- [ ] Placeholder tokens for values TBD: + `[LAUNCH DATE]` (the only remaining placeholder) + +### 3.3 Record walkthrough + +- [ ] Record the screencast using the + [Screencast Script](authoring-screencast-script) +- [ ] Presenter: Moko Consulting +- [ ] Runtime target: 5–8 minutes +- [ ] Upload to a location accessible to Event Authors (Google Drive, + YouTube unlisted, or embedded on the site) +- [ ] Link from the authoring README + +### 3.4 Onboard first authors + +- [ ] Schedule a live walkthrough session with initial Event Authors +- [ ] Share the authoring docs link +- [ ] Have each author create a test article and verify cross-posts +- [ ] Collect feedback and update docs as needed + +--- + +## Phase 4 — Launch + +Go live and hand off to the team. + +### 4.1 Fill in placeholders + +- [ ] Replace `[LAUNCH DATE]` across all authoring docs +- [x] ~~Replace `[CF Discord channel name]`~~ → #server-announcements +- [x] ~~Replace `[FB Page ID]`~~ → clarksvillefurs (Facebook group) +- [x] ~~Replace `[Telegram channel handle]`~~ → @ClarksvilleFurs +- [x] ~~Replace `[Webmaster email]`~~ → Contact Us page (clarksvillefurs.com/contact-us) + +### 4.2 Publish + +- [ ] Merge authoring docs to main branch +- [ ] Enable auto-publish permissions for Event Authors (if dry run + proved they don't need moderator approval) +- [ ] Announce in Discord and Telegram that the Events page is live +- [ ] Monitor first 5 real posts for cross-post issues + +### 4.3 Post-launch + +- [ ] Review cross-post analytics after 2 weeks +- [ ] Update docs based on author feedback +- [ ] Consider adding a menu item for Events on the main navigation + (currently hidden: `menu_show=0` on item 457) + +--- + +## Constraints + +- **MokoDiscordHook**: embed with title, intro text, image, link. + Fires `onContentAfterSave` for configured categories. Does NOT + update embeds if the article is edited after initial save. +- **Perfect Publisher**: native FB Page post + Telegram channel post, + triggered by Rule Engine on category match. Link previews depend + on Open Graph meta tags being present and correct. +- **No invented features**: this plan only uses capabilities that + exist in the installed plugins. If a feature isn't listed here, + it doesn't exist. + +--- + +## Metadata + +| Field | Value | +|---|---| +| Document Type | plan | +| Domain | Content Authoring | +| Applies To | Events and News authoring workflow | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/migration-plan-events.md | +| Version | 00.01.00 | +| Status | Draft | +| Last Reviewed | 2026-04-26 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-26 | Claude | Initial creation | 4-phase plan: infrastructure, dry run, documentation, launch | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/ClarksvilleFurs/client-waas-clarksvillefurs/theme-architecture.-.-.md b/ClarksvilleFurs/client-waas-clarksvillefurs/theme-architecture.-.-.md new file mode 100644 index 0000000..a7c7148 --- /dev/null +++ b/ClarksvilleFurs/client-waas-clarksvillefurs/theme-architecture.-.-.md @@ -0,0 +1,151 @@ +← [Home](Home) + +# Theme Architecture + +The CF theme rides on top of MokoOnyx (Joomla 5 template). MokoOnyx provides +everything structural (layout, scaffolding, responsive grid, component behavior). +CF's theme layer only changes colors, fonts, and introduces a small library of +utility classes. + +## File roster + +Three CSS files make up the CF theme layer. They live under the MokoOnyx +template directory and survive template updates because MokoOnyx's CSS cascade +is ordered to read the `.custom` files after its own `.standard` files. + +``` +/media/templates/site/mokoonyx/ +├── css/ +│ ├── theme/ +│ │ ├── light.custom.css ← light-mode palette +│ │ └── dark.custom.css ← dark-mode palette +│ ├── user.css ← persistent overrides (fonts, utilities) +│ └── theme/ +│ ├── light.standard.css ← template default, do NOT edit +│ └── dark.standard.css ← template default, do NOT edit +└── fonts/ + └── Fredoka-Variable.ttf ← brand font +``` + +## Load order + +MokoOnyx loads stylesheets in this order on every page. Later files override +earlier files per CSS cascade rules: + +1. `template.base.css` — Bootstrap 5.3 + MokoOnyx layout primitives +2. `fonts/osaka.css` — template's default heading font (overridden later) +3. `theme/light.standard.css` — Bootstrap palette + MokoOnyx variable defaults +4. `theme/dark.standard.css` — same, dark-mode scoped under `:root[data-bs-theme='dark']` +5. `theme/light.custom.css` — **CF palette** (this is ours) +6. `theme/dark.custom.css` — **CF dark palette** (this is ours) +7. `user.css` — **persistent overrides** (this is ours) +8. `a11y-high-contrast.css` — accessibility toggle +9. `bootstrap.css` — Bootstrap component styles (read vars set above) + +The CF files sit between the template's defaults and Bootstrap's final component +pass, so our variable values flow into every Bootstrap component that reads them. + +## What each CF file is allowed to change + +### `light.custom.css` and `dark.custom.css` + +**Purpose:** Full color palette for each theme mode. These files are a +comprehensive redeclaration of every MokoOnyx / Bootstrap 5 custom property in +the template's scaffold — 684 variables per file at the time of writing. + +**Scope of edits:** + +- All `--color-*` brand tokens +- All Bootstrap contextual colors (`--primary`, `--secondary`, `--success`, `--info`, `--warning`, `--danger`, `--light`, `--dark`) and their `-rgb`, `-text-emphasis`, `-bg-subtle`, `-border-subtle` variants +- Typography tokens that should vary by mode (none currently — font stack is mode-invariant and lives in `user.css`) +- All container backgrounds (`--container-top-a-*`, `--container-top-b-*`, `--container-bottom-a-*`, `--container-bottom-b-*`, `--container-sidebar-*`, `--container-toc-*`, `--container-below-topbar-*`) +- Hero variant styling (`--hero-primary-*`, `--hero-secondary-*`, `--hero-card-*`, `--hero-alt-card-*`) +- Block color rotation (`--block-color-1` through `-4`, plus overrides) +- All Bootstrap component defaults (accordion, alert, badge, breadcrumb, card, dropdown, list-group, modal, nav-tabs, nav-pills, offcanvas, pagination, popover, progress, spinner, table, toast, tooltip) +- Button variants (`.btn-primary` through `.btn-dark`, `.btn-outline-*`, `.btn-link`) — live at stylesheet root, not nested, following the MokoOnyx scaffold convention + +**Not in scope:** typography, layout, spacing outside Bootstrap's defaults. +Those belong in `user.css`. + +### `user.css` + +**Purpose:** Persistent non-color overrides. Edits here survive template updates +and color changes without touching the palette files. + +**Scope of edits:** + +- `@font-face` loading for Fredoka +- `@import` for Nunito from Google Fonts +- Global font-stack override via `:root { --body-font-family }` +- Typography weight hierarchy (per brand guide) +- `.site-title` override to beat Osaka +- Rounded-corner enforcement on `.form-control`, `.form-select`, `.alert`, `.badge`, `.input-group-text`, `.btn` +- `.btn` base sizing (`padding: 0.65rem 1.5rem`) and `.btn-lg` variant +- Opt-in utility classes: `.cf-sticker`, `.cf-brand-callout`, `.cf-brand-accent` +- Tinted card classes: `.custom.sky`, `.custom.red`, `.custom.yellow`, `.custom.green` +- Blue-background contrast override (scoped ink-link treatment inside sky surfaces) +- Decorative `.text-danger` → coral compatibility rule for headings +- `:focus-visible` accessibility outline +- Link underline offset for body text + +## Versioning + +All three files use zero-padded semver in their `FILE INFORMATION` header +comment. Version is displayed prominently near the top of each file and must be +bumped on every edit. + +Current versions (as of last update): + +| File | Version | +|---|---| +| `light.custom.css` | 02.04.00 | +| `dark.custom.css` | 02.02.00 | +| `user.css` | 01.05.00 | + +## Cache busting + +Joomla cache-busts CSS via a query string appended to every asset URL (e.g. +`?475b76`). The cache key is regenerated when any template file changes on +disk. A deploy should always be followed by a template rebuild (Joomla admin → +System → Maintenance → Clear Cache) to make browsers pick up the new version. + +## Safe-edit checklist + +Before committing any CSS change: + +1. Brace balance — count `{` and `}` occurrences, must match +2. File version bumped in header comment +3. No direct hex usage where a `var(--*)` exists — always prefer the token +4. Contrast audit for any color change touching text/background pairs +5. Both light and dark mode tested (toggle in the site header) +6. File header comment still present and valid + +## Metadata + +| Field | Value | +|---|---| +| Document Type | reference | +| Domain | Theme Architecture | +| Applies To | All CSS changes in this repo | +| Jurisdiction | Moko Consulting | +| Owner | Moko Consulting | +| Repo | mokoconsulting-tech/client-clarksvillefurs | +| Path | ./docs/theme-architecture.md | +| Version | 00.01.00 | +| Status | Active | +| Last Reviewed | 2026-04-21 | +| Reviewed By | Claude | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-04-21 | Claude | Initial creation | Based on v02.06.00 theme package | + +--- + +*Repo: [client-clarksvillefurs](https://git.mokoconsulting.tech/ClarksvilleFurs/client-waas-clarksvillefurs) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/Home.md b/MokoConsulting/MokoCRM/Home.md new file mode 100644 index 0000000..44a183c --- /dev/null +++ b/MokoConsulting/MokoCRM/Home.md @@ -0,0 +1,27 @@ +# MokoCRM + +White-label CRM platform for Dolibarr ERP + +--- + +## Pages + +- [README](README) +- [changelog](changelog) +- [development](development) +- [installation](installation) +- [module id policy](module-id-policy) +- [roadmap](roadmap) +- [update server](update-server) + +--- + +**Category:** Dolibarr | **Platform:** [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki) + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoCRM/README.md b/MokoConsulting/MokoCRM/README.md new file mode 100644 index 0000000..9d06fac --- /dev/null +++ b/MokoConsulting/MokoCRM/README.md @@ -0,0 +1,144 @@ +← [Home](Home) + +# MokoCRM Documentation Index + +Welcome to the MokoCRM documentation. This guide will help you navigate all available documentation resources for the MokoCRM Dolibarr white-label module. + +## Quick Links + +- [Installation Guide](installation.md) - Install and enable MokoCRM +- [Development Guide](development.md) - Extend or customise MokoCRM +- [Roadmap](roadmap.md) - Planned features and version milestones +- [Module ID](module-id-policy.md) - Module ID 185067 details +- [Changelog](changelog.md) - Version history and changes + +## Documentation Structure + +### For Administrators + +If you're installing MokoCRM on your Dolibarr instance: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Configuration and setup + - Troubleshooting common issues + +### For Developers + +If you're extending or contributing to MokoCRM: + +1. **[Development Guide](development.md)** + - Module structure and organisation + - White label configuration + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + - Commit message guidelines + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start +- **[Module ID](module-id-policy.md)** - Official module ID 185067 + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Installation Guide](installation.md) to install MokoCRM, then review the [Development Guide](development.md) if you want to extend it. + +**Q: What is MokoCRM's module ID?** +A: MokoCRM uses the officially registered Dolibarr module ID **185067**. See [Module ID](module-id-policy.md) for details. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +**Q: Where are the code examples?** +A: The [Development Guide](development.md) contains code examples and best practices. + +### Support Resources + +- **GitHub Issues**: [mokoconsulting-tech/MokoCRM](https://github.com/mokoconsulting-tech/MokoCRM/issues) +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) + +### Moko Consulting + +- [MokoConsulting Tech](https://mokoconsulting.tech) +- [MokoConsulting Tech GitHub](https://github.com/mokoconsulting-tech) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 185067; // MokoCRM official module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/htdocs/custom/ +git clone https://github.com/mokoconsulting-tech/MokoCRM.git mokocrm +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Module Version**: 01.01.00 +- **Module ID**: 185067 +- **Last Updated**: 2026-03-19 +- **Minimum Dolibarr Version**: 19.0 +- **PHP Version**: 7.1+ + +--- + +**Next Steps**: +- Installing MokoCRM? Start with the [Installation Guide](installation.md) +- Extending MokoCRM? Check out the [Development Guide](development.md) + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/changelog.md b/MokoConsulting/MokoCRM/changelog.md new file mode 100644 index 0000000..f8ac764 --- /dev/null +++ b/MokoConsulting/MokoCRM/changelog.md @@ -0,0 +1,58 @@ +← [Home](Home) + +# Changelog + +All notable changes to MokoCRM will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [01.02.00] - Unreleased + +### Added +- CRM configuration installed automatically on module activation: 37 custom extrafields across 12 Dolibarr objects (`societe`, `socpeople`, `projet`, `propal`, `facture`, `facturedet`, `actioncomm`, `fichinter`, `fichinterdet`, `expensereport`, `expensereport_det`, `facture_fourn`) +- Three custom dictionary tables (`llx_moko_commission_rate`, `llx_moko_meeting_time`, `llx_moko_meeting_day`) created and seeded on activation; exposed in the Dolibarr dictionary admin via `$this->dictionaries` +- 17 module constants registered via `$this->const` (FICHINTER_* workflow flags, proposal/invoice defaults, PDF options) +- Core dictionary data: 3 payment terms, 2 units of measure, 11 expense/fee categories, 6 third-party types, 11 contact roles, 8 opportunity sources, 12 custom activity types, updated lead pipeline stages and prospect qualification levels +- 7 branded HTML email templates (proposals, invoices, contract) with Moko Blue (#1A6FD4) header +- Notification defaults for `PROPAL_VALIDATE` and `BILL_VALIDATE` to `sales@mokoconsulting.tech` +- Payment method additions (ACH, Stripe, Square, Zelle, Venmo Business) and order entry method English relabels +- 8 product–client relation types and 20 US business legal forms +- Physical extrafield columns added via `information_schema`-safe `ALTER TABLE` helper (idempotent, skips missing tables for optional modules) +- Full uninstall: `remove()` deletes all extrafield metadata, drops physical columns, and drops the three custom dictionary tables +- Comprehensive lang file (`langs/en_US/mokocrm.lang`) covering all new labels, select options, roles, and activity types + +## [01.01.00] - 2026-03-12 + +### Added +- Set `MAIN_LOGIN_BACKGROUND` to `access_restricted_banner.png` on module activation and remove it on deactivation using `dolibarr_set_const()` / `dolibarr_del_const()` (`core/lib/admin.lib.php`); `init()` also copies the bundled image to `$conf->mycompany->dir_output/logos/` so Dolibarr can serve it via `viewimage.php?modulepart=mycompany&file=logos/access_restricted_banner.png` +- Set `editor_squarred_logo` to `favicon_256.png@mokocrm` for the module card in Dolibarr admin +- Dynamic development environment warning toast shown once per browser session via `sessionStorage` when `$this->version === 'development'` (`js/mokocrm.js.php`) +- Dynamic `" - Development"` suffix appended to `document.title` on every page when `$this->version === 'development'` (`js/mokocrm.js.php`) + +## [01.00.00] - 2026-03-10 + +### Added +- Initial MokoCRM Dolibarr module with official module ID **185067** +- Module descriptor (`modMokoCRM.class.php`) with white label `overwrite_translation` for `DolibarrProductName` and `Dolibarr` → MokoCRM +- English translation file (`langs/en_US/mokocrm.lang`) with MokoCRM-branded keys +- Admin setup page (`admin/setup.php`) and about page (`admin/about.php`) +- Library file (`lib/mokocrm.lib.php`) with admin navigation helper +- Module icon (`img/object_mokostandards.png`) +- Comprehensive documentation (installation, development, module ID, changelog) + +--- + +[Unreleased]: https://github.com/mokoconsulting-tech/MokoCRM/compare/v01.01.00...HEAD +[01.01.00]: https://github.com/mokoconsulting-tech/MokoCRM/compare/v01.00.00...v01.01.00 +[01.00.00]: https://github.com/mokoconsulting-tech/MokoCRM/releases/tag/v01.00.00 + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/development.md b/MokoConsulting/MokoCRM/development.md new file mode 100644 index 0000000..560efcd --- /dev/null +++ b/MokoConsulting/MokoCRM/development.md @@ -0,0 +1,404 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing and extending the MokoCRM Dolibarr module. + +## Module Structure + +MokoCRM follows the standard Dolibarr module structure under `src/`: + +``` +src/ # Module source (deploy as "mokocrm/") +├── admin/ # Admin pages +│ ├── about.php # About page +│ ├── index.php # Directory index +│ └── setup.php # Configuration page +├── core/ +│ ├── modules/ +│ │ └── modMokoCRM.class.php # Module descriptor +│ └── substitutions/ +│ └── functions_mokocrm.lib.php # White label substitution functions +├── css/ +│ └── mokocrm.css.php # White label CSS overrides +├── img/ +│ ├── access_restricted_banner.png # Login page background image +│ ├── favicon_256.png # Module editor logo (256×256) +│ ├── favicon.gif / favicon.ico / favicon.svg # Favicon variants +│ ├── logo.png / logo.svg # MokoCRM logos +│ └── index.php # Directory index +├── js/ +│ └── mokocrm.js.php # Dynamic JS (dev indicators, title suffix) +├── langs/ +│ └── en_US/ +│ └── mokocrm.lang # English translations +├── lib/ +│ └── mokocrm.lib.php # Admin page helper functions +└── ChangeLog.md # Module changelog +``` + +## Module Descriptor + +The module descriptor (`src/core/modules/modMokoCRM.class.php`) is the core configuration file. + +### Key Properties + +```php +db = $db; + + // Official module ID (registered at wiki.dolibarr.org) + $this->numero = 185067; + + // Module identification + $this->rights_class = 'mokocrm'; + $this->family = 'mokoconsulting'; + $this->module_position = 9999999999; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "MokoCRM white labels Dolibarr ERP/CRM under the MokoCRM brand"; + + // Author / editor info + $this->editor_name = 'Moko Consulting'; + $this->editor_url = 'https://mokoconsulting.tech'; + $this->editor_squarred_logo = 'favicon_256.png@mokocrm'; // shown on the module card + + // Version — use 'development' to enable dev-mode indicators (see below) + $this->version = '01.01.00'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Language files + $this->langfiles = array("mokocrm@mokocrm"); + + // White label: override Dolibarr branding translations + $this->overwrite_translation = array( + 'en_US:DolibarrProductName' => 'MokoCRM', + 'en_US:Dolibarr' => 'MokoCRM', + ); + + // Enable CSS, JS and substitution white label features + $this->module_parts = array( + 'substitutions' => 1, + 'css' => array('/mokocrm/css/mokocrm.css.php'), + 'js' => array('/mokocrm/js/mokocrm.js.php'), + // ... other parts + ); + } +} +``` + +## White Labeling + +MokoCRM applies three layers of white labeling: + +### 1. Translation Overrides (`overwrite_translation`) + +Set in `modMokoCRM.class.php`, this replaces standard Dolibarr translation strings with MokoCRM equivalents throughout the UI without modifying core files. + +```php +$this->overwrite_translation = array( + 'en_US:DolibarrProductName' => 'MokoCRM', + 'en_US:Dolibarr' => 'MokoCRM', +); +``` + +To add more overrides for other languages, add additional entries: + +```php +$this->overwrite_translation = array( + 'en_US:DolibarrProductName' => 'MokoCRM', + 'en_US:Dolibarr' => 'MokoCRM', + 'fr_FR:DolibarrProductName' => 'MokoCRM', + 'fr_FR:Dolibarr' => 'MokoCRM', +); +``` + +### 2. CSS Overrides (`css/mokocrm.css.php`) + +Loaded on every page when the module is active. Use this to override visual branding elements. + +### 3. Substitution Functions (`core/substitutions/functions_mokocrm.lib.php`) + +Called when generating documents and emails. The function `getSubstitutionArray_mokocrm()` injects substitution variables that replace Dolibarr references in generated content. + +### 4. JavaScript (`js/mokocrm.js.php`) + +Served as `application/javascript` and loaded on every page when the module is active. Currently handles development environment indicators (see [Development Environment Indicators](#development-environment-indicators) below). + +## Development Environment Indicators + +When `$this->version` is set to `'development'` in `modMokoCRM.class.php`, the JS file (`js/mokocrm.js.php`) automatically activates two visible indicators on every page. No database write or install step is required — the gate is evaluated at PHP render time on each request. + +### Title suffix + +`document.title` is appended with `" - Development"` immediately and kept in sync via a `MutationObserver` so the suffix persists even after Dolibarr rewrites the title during AJAX navigation. + +### Warning toast + +An amber ⚠ warning toast is injected into `document.body` once per browser session (guarded by `sessionStorage`). It auto-dismisses after 10 seconds and includes a manual close button. + +``` +⚠ Development Environment +This is a non-production instance. Data entered here is for testing only +and may be reset without notice. Do not enter real client or financial data. +``` + +The toast is built entirely with `createElement` / `textContent` — no `innerHTML`, so it is CSP-safe. + +### Enabling / disabling + +| `$this->version` value | Dev indicators | +|------------------------|---------------| +| `'development'` | ✅ Active | +| `'01.01.00'` (or any semver) | ❌ Off | + +To switch a deployment into development mode, change the version string in `modMokoCRM.class.php`: + +```php +$this->version = 'development'; // enables indicators +// $this->version = '01.01.00'; // production — no indicators +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "mokocrm_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->hasRight('mokocrm', 'read')) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use proper escaping +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "mokocrm_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "mokocrm_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "mokocrm_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in the language files: + +```php +// In langs/en_US/mokocrm.lang +MokoCRMSetup = MokoCRM setup +MokoCRMArea = Home MokoCRM +``` + +```php +// In PHP code +$langs->load("mokocrm@mokocrm"); +print $langs->trans("MokoCRMSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModMokoCRMTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class MokoCRMApi extends DolibarrApi +{ + /** + * @url GET /mokocrm/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify white label branding appears correctly (check UI for "MokoCRM" instead of "Dolibarr") +3. Check CSS overrides are loaded +4. Verify substitutions work in generated documents +5. Test with different user roles + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/dolibarr.log` + +## Managing Constants + +Dolibarr provides two helper functions in `core/lib/admin.lib.php` for writing and removing global constants at runtime. MokoCRM uses these directly in `init()` and `remove()` for `MAIN_LOGIN_BACKGROUND` rather than the passive `$this->const` declarative array, because it gives full control: the value is (re-)written every time the module is activated and cleanly deleted on deactivation. + +### Writing a constant — `dolibarr_set_const()` + +```php +require_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php'; + +dolibarr_set_const( + $this->db, // DoliDB handle + 'MAIN_LOGIN_BACKGROUND', // constant name + 'access_restricted_banner.png', // value + 'chaine', // type (chaine | int | yesno | …) + 0, // visible in admin UI (0 = no) + 'Login background image set by MokoCRM', // note / description + $conf->entity // entity scope +); +``` + +`dolibarr_set_const()` performs an INSERT if the constant doesn't exist yet, or an UPDATE if it does. It is the equivalent of what Dolibarr's own admin pages (e.g. `admin/ihm.php`) do when the administrator configures the login background. + +### Removing a constant — `dolibarr_del_const()` + +```php +require_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php'; + +dolibarr_del_const($this->db, 'MAIN_LOGIN_BACKGROUND', $conf->entity); +``` + +Call this in `remove()` to restore the Dolibarr default (no login background) when the module is deactivated. + +### When to prefer `dolibarr_set_const` over `$this->const` + +| Approach | Best for | +|----------|---------| +| `$this->const` array | Simple module-specific constants that Dolibarr manages automatically (set on activate, deleted on deactivate if `deleteonunactive=1`) | +| `dolibarr_set_const()` | Shared/core constants like `MAIN_LOGIN_BACKGROUND`; cases where you need the value to be re-written (not just inserted) on every re-activation; or when you need error handling | + +MokoCRM uses the officially registered Dolibarr module ID **185067**. This ID must not be changed. See [Module ID](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `src/core/modules/modMokoCRM.class.php` +- `docs/changelog.md` +- `src/ChangeLog.md` + +## Publishing / Releasing + +Before a release: + +1. ✅ Update version number in `modMokoCRM.class.php` +2. ✅ Update `docs/changelog.md` and `src/ChangeLog.md` +3. ✅ Test on the minimum supported Dolibarr version (19.0) +4. ✅ Review security best practices +5. ✅ Create a GitHub release tag + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- [MokoCRM GitHub Issues](https://github.com/mokoconsulting-tech/MokoCRM/issues) for MokoCRM-specific questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/installation.md b/MokoConsulting/MokoCRM/installation.md new file mode 100644 index 0000000..3b6f3ad --- /dev/null +++ b/MokoConsulting/MokoCRM/installation.md @@ -0,0 +1,145 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and enabling MokoCRM on your Dolibarr instance. + +## Prerequisites + +Before installing MokoCRM, ensure you have: + +- **Dolibarr ERP/CRM**: Version 19.0 or higher +- **PHP**: Version 7.1 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - gd or imagick + - curl + - json + - xml + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr `custom/` directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone the MokoCRM repository as `mokocrm`: + +```bash +git clone https://github.com/mokoconsulting-tech/MokoCRM.git mokocrm +``` + +> **Important:** The directory must be named `mokocrm` — this is the module's internal identifier used throughout Dolibarr. + +The module source files live in the `src/` subdirectory of the repository. You can either work from there directly or copy the contents of `src/` into the `mokocrm/` directory, depending on your deployment approach. + +### 2. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/mokocrm + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/mokocrm -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/mokocrm -type f -exec chmod 644 {} \; +``` + +### 3. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find **MokoCRM** in the module list (look under the *Moko Consulting* family) +4. Click the **Activate** button + +### 4. Configure Module Settings (optional) + +After activation: + +1. Go to **Home → Setup → Modules/Applications** +2. Click on **MokoCRM** to access its configuration page +3. Configure any required settings +4. Save changes + +## White Label Activation + +Once MokoCRM is enabled, the following white labeling takes effect automatically: + +| Mechanism | File | Effect | +|-----------|------|--------| +| Translation override | `modMokoCRM.class.php` | Replaces "Dolibarr" / "DolibarrProductName" labels with "MokoCRM" in the UI | +| CSS override | `css/mokocrm.css.php` | Applies MokoCRM branding styles | +| Substitution functions | `core/substitutions/functions_mokocrm.lib.php` | Replaces Dolibarr references in generated documents and emails | +| Login background | `MAIN_LOGIN_BACKGROUND` constant | Sets `access_restricted_banner.png` as the login page background (removed when module is deactivated) | +| JS indicators | `js/mokocrm.js.php` | When `$this->version === 'development'`: appends `" - Development"` to the browser title and shows an amber warning toast once per session | + +No additional configuration is required for white labeling to work. + +> **Development mode:** To enable the development environment indicators, set `$this->version = 'development'` in `src/core/modules/modMokoCRM.class.php`. The indicators are evaluated dynamically on each page request — no reinstall is needed. + +## Troubleshooting + +### Module Not Appearing + +- Verify the clone directory is named exactly `mokocrm` +- Clear Dolibarr's module cache: go to **Home → Setup → Modules/Applications** and use the "Refresh modules list" option, or delete `/temp/` contents +- Check file permissions +- Verify PHP syntax: `php -l src/core/modules/modMokoCRM.class.php` + +### White Label Not Taking Effect + +- Confirm the module is **activated** (green toggle in Modules/Applications) +- Check that Dolibarr version is 19.0 or higher (required for `overwrite_translation`) +- Check Dolibarr logs: `/dolibarr.log` + +### Permission Errors + +- Ensure the Apache/Nginx user has read access to all module files +- Check `conf.php` file permissions in the Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Ensure the database user has sufficient permissions + +## Uninstallation + +To remove MokoCRM: + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find MokoCRM and click **Deactivate** +3. Optionally, remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/mokocrm + ``` + +> **Note:** Deactivating the module removes its constants and menus but does not delete any data tables created by the module. + +## Next Steps + +- Review the [Development Guide](development.md) to extend or customise MokoCRM +- Read the [Changelog](changelog.md) for version history + +## Support + +For installation issues: +- Create an issue in the [MokoCRM repository](https://github.com/mokoconsulting-tech/MokoCRM/issues) +- Check Dolibarr logs: `/dolibarr.log` +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/module-id-policy.-.-.md b/MokoConsulting/MokoCRM/module-id-policy.-.-.md new file mode 100644 index 0000000..18312f0 --- /dev/null +++ b/MokoConsulting/MokoCRM/module-id-policy.-.-.md @@ -0,0 +1,65 @@ +← [Home](Home) + +# Module ID + +MokoCRM uses the officially registered Dolibarr module ID **185067**. + +## Registered ID + +| Property | Value | +|----------|-------| +| Module ID | **185067** | +| Module name | `MokoCRM` | +| Rights class | `mokocrm` | +| Organisation | Moko Consulting | +| Distribution | Public | +| Registered at | [wiki.dolibarr.org/index.php/List_of_modules_id](https://wiki.dolibarr.org/index.php/List_of_modules_id) | + +This ID is set in `src/core/modules/modMokoCRM.class.php`: + +```php +$this->numero = 185067; // Official module ID registered at wiki.dolibarr.org +``` + +## Why Module IDs Matter + +Every Dolibarr module requires a unique numeric identifier. This ID is critical for: + +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations in the database (`llx_const`) +- Permission ID generation (e.g., `18506701`, `18506702`, …) + +## Dolibarr Module ID Ranges + +| Range | Purpose | +|-------|---------| +| 0 – 94,999 | Core Dolibarr modules (reserved) | +| 95,000 – 99,999 | Community modules (official Dolibarr repos) | +| 100,000 – 499,999 | Third-party public modules | +| 500,000 – 599,999 | Private / unlisted modules | +| 600,000+ | Development / temporary (not for distribution) | + +MokoCRM's ID **185067** falls in the **100,000 – 499,999** range, appropriate for a publicly distributed third-party module. + +## Checking for Conflicts + +To verify there is no ID conflict on a running Dolibarr installation, run: + +```sql +SELECT name, value FROM llx_const WHERE name = 'MAIN_MODULE_MOKOCRM'; +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/roadmap.md b/MokoConsulting/MokoCRM/roadmap.md new file mode 100644 index 0000000..538ae5c --- /dev/null +++ b/MokoConsulting/MokoCRM/roadmap.md @@ -0,0 +1,103 @@ +← [Home](Home) + +# MokoCRM Roadmap + +This document describes the planned development trajectory for MokoCRM. Completed milestones are included for historical context. Items within a future version are subject to change — open an issue to propose additions or reprioritisations. + +## Status legend + +| Symbol | Meaning | +|---|---| +| ✅ | Complete and released | +| 🔄 | In progress (active development branch) | +| 🗓️ | Planned (not yet started) | +| 💡 | Under consideration | + +--- + +## ✅ 01.00.00 — Foundation *(released 2026-03-10)* + +Initial MokoCRM module release establishing the white-label base. + +- ✅ Module descriptor (`modMokoCRM.class.php`) with official module ID **185067** +- ✅ White-label translation overrides (`DolibarrProductName` → MokoCRM, `Dolibarr` → MokoCRM) +- ✅ English translation file (`langs/en_US/mokocrm.lang`) +- ✅ Admin setup page (`admin/setup.php`) and about page (`admin/about.php`) +- ✅ Library file (`lib/mokocrm.lib.php`) with admin navigation helper +- ✅ Comprehensive documentation (installation, development, module ID, changelog) + +--- + +## ✅ 01.01.00 — Branding Polish *(released 2026-03-12)* + +Login-page customisation and developer-mode indicators. + +- ✅ Custom login page background (`access_restricted_banner.png`) set on activation, removed on deactivation +- ✅ Module card editor logo (`favicon_256.png@mokocrm`) displayed in the Dolibarr admin panel +- ✅ Development mode: one-time session toast warning when `$this->version === 'development'` +- ✅ Development mode: `" — Development"` suffix appended to the browser tab title + +--- + +## 🔄 01.02.00 — Documentation *(in progress — branch `dev/01.02.00`)* + +Documentation overhaul. + +- ✅ Regenerate all README files with accurate MokoCRM content (replacing moko-platform template placeholders) +- ✅ Fix stale documentation and Makefile module identity (correct `MODULE_NAME`, `MODULE_VERSION`, `MODULE_NUMBER`, `SRC_DIR`) +- ✅ Remove deleted deployment references from docs and changelog +- ✅ Roadmap document (`docs/roadmap.md`) + +--- + +## 🗓️ 01.03.00 — Extended White Label *(planned)* + +Deeper brand coverage across more Dolibarr surfaces. + +- 🗓️ French translation file (`langs/fr_FR/mokocrm.lang`) mirroring the English keys +- 🗓️ Custom help URL override — replace Dolibarr help links with MokoCRM documentation +- 🗓️ CSS overrides for the Dolibarr top-bar logo and favicon injection +- 🗓️ Custom "About" content driven by module constants rather than hardcoded strings + +--- + +## 🗓️ 01.04.00 — Admin Experience *(planned)* + +Quality-of-life improvements for administrators managing a MokoCRM instance. + +- 🗓️ Admin dashboard widget showing module version, active features, and support links +- 🗓️ Setup page: configurable company name and support URL constants stored in `llx_const` +- 🗓️ Setup page: one-click "apply branding" action to refresh all white-label constants + +--- + +## 💡 Under consideration + +These items have no committed version yet. Open an issue to discuss prioritisation. + +- 💡 Multi-entity support — per-entity white-label overrides for hosted/multi-tenant deployments +- 💡 Theme selection — allow administrators to switch between bundled CSS colour themes +- 💡 Custom email footer — inject MokoCRM branding into outbound Dolibarr emails +- 💡 Automated compatibility matrix — CI job to test against multiple Dolibarr versions + +--- + +## Contributing + +To propose a new roadmap item: + +1. Open an issue at [mokoconsulting-tech/MokoCRM/issues](https://github.com/mokoconsulting-tech/MokoCRM/issues) describing the feature and its value +2. Reference the issue in a pull request targeting the relevant `dev/X.Y.Z` branch +3. Follow the contribution guidelines in [CONTRIBUTING.md](CONTRIBUTING) + +--- + +*Last updated: 2026-03-19* + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoCRM/update-server.-.-.md b/MokoConsulting/MokoCRM/update-server.-.-.md new file mode 100644 index 0000000..69eba91 --- /dev/null +++ b/MokoConsulting/MokoCRM/update-server.-.-.md @@ -0,0 +1,112 @@ +← [Home](Home) + +# Module Update Server + +This module uses `update.json` hosted in the repo root to enable Dolibarr's built-in update checker. + +## How It Works + +1. When a PR is merged to `main`, the `auto-release.yml` workflow: + - Reads the version from `README.md` + - Sets `$this->version` in the module descriptor to the real version + - Creates a GitHub Release with a git tag + - Writes `update.json` to the repo root +2. The module descriptor's `$this->url_last_version` points to the raw `update.json` URL +3. Dolibarr's admin panel fetches this URL to check for available updates + +## Setup + +### 1. Module Descriptor + +In `src/core/modules/mod*.class.php`, ensure these lines are in the constructor: + +```php +// Version — 'development' on dev branches, real version set by auto-release on merge to main +$this->version = 'development'; + +// Update check — points to update.json written by auto-release workflow +$this->url_last_version = 'https://raw.githubusercontent.com/mokoconsulting-tech/REPO_NAME/main/update.json'; +``` + +Replace `REPO_NAME` with this repository's name. + +### 2. Version Parser + +Add this method to the module descriptor class to parse the JSON response: + +```php +/** + * Get the latest available version from the update server. + * + * Reads update.json from the GitHub repo and extracts the version field. + * Called by Dolibarr's module update checker. + * + * @return string Latest version number, or empty string on failure + */ +public function getLatestVersion(): string +{ + if (empty($this->url_last_version)) { + return ''; + } + + $content = @file_get_contents($this->url_last_version); + if ($content === false) { + return ''; + } + + $data = json_decode($content, true); + return $data['version'] ?? ''; +} +``` + +### 3. That's It + +Everything else is automated: +- `deploy-dev.yml` sets version to `"development"` on dev branches +- `auto-release.yml` sets the real version and writes `update.json` on release +- `sync-version-on-merge.yml` bumps the patch version in README.md + +## update.json Format + +```json +{ + "version": "01.02.03", + "tag": "v01.02.03", + "repo": "mokoconsulting-tech/REPO_NAME", + "release_url": "https://github.com/mokoconsulting-tech/REPO_NAME/releases/tag/v01.02.03", + "updated": "2026-03-27T00:00:00Z" +} +``` + +> **Do not edit `update.json` manually** — it is auto-generated by the release workflow. + +## Version Lifecycle + +``` +dev/** branch → $this->version = "development" (no update.json) +merge to main → $this->version = "01.02.03" → update.json written → GitHub Release +next commit → README auto-bumps to 01.02.04 (no release yet) +``` + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| `update.json` doesn't exist | Merge a PR to main — the first release creates it | +| Version shows "development" | Expected on `dev/**` branches — real version set on release | +| Dolibarr doesn't detect updates | Check `$this->url_last_version` URL returns valid JSON | +| Wrong version in update.json | Check README.md VERSION field — it's the source of truth | + +### Test the URL + +```bash +curl -s https://raw.githubusercontent.com/mokoconsulting-tech/REPO_NAME/main/update.json | jq . +``` + +--- + +*Repo: [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDPCalendarAPI/Home.md b/MokoConsulting/MokoDPCalendarAPI/Home.md new file mode 100644 index 0000000..d847bca --- /dev/null +++ b/MokoConsulting/MokoDPCalendarAPI/Home.md @@ -0,0 +1,28 @@ +# MokoDPCalendarAPI + +Joomla Web Services plugin exposing DPCalendar events, calendars, and locations via REST API + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [INSTALLATION](INSTALLATION) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDPCalendarAPI](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDPCalendarAPI/INSTALLATION.md b/MokoConsulting/MokoDPCalendarAPI/INSTALLATION.md new file mode 100644 index 0000000..6b0a9a7 --- /dev/null +++ b/MokoConsulting/MokoDPCalendarAPI/INSTALLATION.md @@ -0,0 +1,51 @@ +← [Home](Home) + +# Installation + +## Prerequisites + +- Joomla 5.x or 6.x +- DPCalendar 9.x+ installed and enabled +- PHP 8.1+ + +## Install from Release + +1. Download the latest ZIP from Releases +2. In Joomla admin: **System > Install > Extensions** +3. Upload and install the ZIP +4. Go to **System > Manage > Plugins** +5. Search for "DPCalendar" and enable **Web Services - DPCalendar** + +## Install from Source + +```sh +git clone https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI.git +cd MokoDPCalendarAPI +``` + +Install the `src/` directory as a Joomla extension via Install from Folder or symlink. + +## Verify + +```sh +curl -s https://your-site.com/api/index.php/v1/dpcalendar/events \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Accept: application/vnd.api+json" +``` + +## Troubleshooting + +### "Resource not found" +- Ensure the plugin is enabled in Plugins manager +- Verify DPCalendar component is installed + +### Empty responses +- Check API user has access to the calendars + +--- + +*Repo: [MokoDPCalendarAPI](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/Home.md b/MokoConsulting/MokoDoliAdInsights/Home.md new file mode 100644 index 0000000..a3a42a3 --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/Home.md @@ -0,0 +1,46 @@ +# MokoDoliAdInsights + +A Dolibarr module used to bridge multiple advertising services (Google Ads, Meta Ads, LinkedIn Ads, etc.) reporting with Claude AI analysis + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | +| [quickstart service](quickstart-service.-.-) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | +| [architecture](architecture) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [adding services](adding-services.-.-) | ← [Home](Home) | +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliAdInsights/README.md b/MokoConsulting/MokoDoliAdInsights/README.md new file mode 100644 index 0000000..c25425c --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/README.md @@ -0,0 +1,243 @@ +← [Home](Home) + +# MokoDoliAdInsights Documentation + +Welcome to the **MokoDoliAdInsights** module documentation. This module integrates multiple advertising platforms (Google Ads, Facebook Ads, Microsoft Ads, and more) with Claude AI analysis in your Dolibarr ERP/CRM system. + +## Quick Links + +- [Installation Guide](installation.md) - Get started with installing the module +- [Architecture Overview](architecture.md) - Understand the multi-platform design +- [Development Guide](development.md) - Learn how to extend the module +- [Adding Services](adding-services.md) - Add support for new ad platforms (plugin system) +- [Changelog](changelog.md) - Track version history and changes + +## Documentation Structure + +### For New Users + +If you're new to this module, start here: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Platform-specific API credential setup + - Configuration and testing + - Troubleshooting common issues + +2. **Module Overview** + - **Multi-Platform Support**: Connect to Google Ads, Facebook Ads, or Microsoft Ads + - **Claude AI Integration**: Get AI-powered insights and recommendations + - **Campaign Reports**: Generate comprehensive performance reports + - **Extensible Architecture**: Easy to add support for additional platforms + +### For Developers + +If you're extending the module or adding new ad platforms: + +1. **[Architecture Overview](architecture.md)** + - Interface-based design pattern + - Services architecture (new!) + - Factory pattern implementation + - Data flow and structure + - Database schema + +2. **[Development Guide](development.md)** + - Module structure and organization + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +3. **[Adding Services](adding-services.md)** - **NEW!** + - Complete guide to adding new ad platforms + - Service architecture explained + - Step-by-step implementation + - Code examples and templates + - Best practices for services + - OAuth, rate limiting, error handling + + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start +- **[src/README.md](src-README)** - Detailed module documentation + +## Getting Help + +### Common Questions + +**Q: Which ad platforms are supported?** +A: Currently Google Ads, Facebook Ads, and Microsoft Ads. The architecture makes it easy to add more platforms. + +**Q: How do I switch between ad platforms?** +A: Go to module configuration and select your preferred ad system from the dropdown. + +**Q: Can I use multiple ad platforms simultaneously?** +A: Currently, one platform is active at a time. You can switch between them in configuration. + +**Q: How do I add a new ad platform?** +A: See the [Adding Services guide](adding-services.md) for step-by-step instructions. + +**Q: Where do I get API credentials?** +A: Each platform has its own developer console: +- **Google Ads**: https://ads.google.com/home/tools/manager-accounts/ +- **Facebook Ads**: https://developers.facebook.com/apps/ +- **Microsoft Ads**: https://ads.microsoft.com/ + +### Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Claude AI Docs**: https://docs.anthropic.com/ + +## Key Concepts + +### Ad System Clients + +All ad platform integrations implement the `AdSystemClientInterface`: + +```php +interface AdSystemClientInterface { + public function getSystemName(); // e.g., 'googleads' + public function getSystemDisplayName(); // e.g., 'Google Ads' + public function isConfigured(); + public function fetchCampaignData($dateStart, $dateEnd); + public function getError(); +} +``` + +### Factory Pattern + +The `AdSystemFactory` creates the appropriate client based on configuration: + +```php +// Get client for configured system +$client = AdSystemFactory::create($db); + +// Or specify a system +$client = AdSystemFactory::create($db, 'googleads'); +``` + +### Unified Data Format + +All platforms return data in a standardized format: + +```json +{ + "ad_system": "googleads|facebookads|microsoftads", + "ad_system_display": "Google Ads|Facebook Ads|Microsoft Ads", + "campaigns": [...], + "totals": {...}, + "period": {...} +} +``` + +## Module Architecture + +**New Services Architecture (v1.3.0+):** +``` +services/ +├── AdServiceInterface (interface) +├── BaseAdService (abstract class) +├── google/GoogleAdsService +├── facebook/FacebookAdsService +├── microsoft/MicrosoftAdsService +└── examples/ExampleAdService (template) + +AdServiceFactory +└── create($db, $serviceId) → returns service + +Report (data model) +├── ad_system_data (campaign data JSON) +├── ad_system_type (platform identifier) +└── report_type (program/competitive/general) +``` + + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Create ad system client +$client = AdSystemFactory::create($db, 'googleads'); + +// Check if configured +if ($client->isConfigured()) { + $data = $client->fetchCampaignData($dateStart, $dateEnd); +} +``` + +```bash +# Install module in Dolibarr +cd /path/to/dolibarr/htdocs/custom/ +git clone https://github.com/mokoconsulting-tech/MokoDoliAdInsights.git mokodoliadinsights +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file in the `docs/` directory +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Module Name**: MokoDoliAdInsights (starts with MokoDoli, references Dolibarr) +- **Module Version**: 1.3.0 (in development) +- **Last Updated**: 2026-03-04 +- **Minimum Dolibarr Version**: 19.0 +- **PHP Version**: 7.4+ +- **Supported Ad Platforms**: + - Google Ads API + - Facebook Marketing API + - Microsoft Advertising API + - **Extensible**: Easy to add more platforms via services architecture + +## External Resources + +### Official Documentation + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Google Ads API](https://developers.google.com/google-ads/api/docs/start) +- [Facebook Marketing API](https://developers.facebook.com/docs/marketing-apis) +- [Microsoft Advertising API](https://docs.microsoft.com/en-us/advertising/guides/) +- [Claude AI API](https://docs.anthropic.com/) + +### MokoConsulting Tech + +- [GitHub Organization](https://github.com/mokoconsulting-tech) +- [MokoDoliAdInsights Repository](https://github.com/mokoconsulting-tech/MokoDoliAdInsights) + +--- + +**Next Steps**: +- New to the module? Start with [Installation Guide](installation.md) +- Want to understand the architecture? Check [Architecture Overview](architecture.md) +- Ready to develop? Read the [Development Guide](development.md) +- Adding a new platform? See [Adding Services](adding-services.md) + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/adding-services.-.-.md b/MokoConsulting/MokoDoliAdInsights/adding-services.-.-.md new file mode 100644 index 0000000..8a8e3ca --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/adding-services.-.-.md @@ -0,0 +1,309 @@ +← [Home](Home) + +# How to Add a New Ad Platform Service + +This guide walks you through adding support for a new advertising platform to +**MokoDoliAdInsights**. + +## Overview + +MokoDoliAdInsights uses a service-based plugin architecture. Adding a new +platform requires **no changes to the factory or the admin setup page** — +`AdSystemFactory` discovers services automatically by scanning the +`src/services/` directory at runtime. + +## What You Need To Do + +1. Create the service class file (and directory) +2. Add translations (display name + config field labels) +3. *(Optional)* Create a `README.md` for your service + +That's it. The factory, the admin dropdown, and the configuration form sections +are all populated automatically. + +--- + +## Step 1 — Create the Service Directory and Class + +```bash +cd src/services/ +mkdir yourplatform +``` + +Create `src/services/yourplatform/YourPlatformService.class.php`: + +```php +serviceId = self::SERVICE_ID; + $this->serviceName = self::SERVICE_NAME; + $this->provider = 'your_company'; + parent::__construct($db); + } + + // --- Required method implementations below --- + + protected function loadConfiguration() + { + $this->config = array( + 'api_key' => getDolGlobalString('MOKODOLIADINSIGHTS_YOURPLATFORM_API_KEY'), + 'account_id' => getDolGlobalString('MOKODOLIADINSIGHTS_YOURPLATFORM_ACCOUNT_ID'), + ); + } + + public function isConfigured() + { + return $this->isConfigValueSet('api_key') && + $this->isConfigValueSet('account_id'); + } + + public function validateCredentials() + { + if (!$this->isConfigured()) { + $this->setError('Service not configured'); + return false; + } + // Make a lightweight test API call here + return true; + } + + public function fetchCampaignData($dateStart, $dateEnd, $options = array()) + { + if (!$this->isConfigured()) { + $this->setError('Service not configured'); + return false; + } + try { + $start = $this->normalizeDate($dateStart); + $end = $this->normalizeDate($dateEnd); + + // TODO: call your platform's API and build $campaigns / $totals arrays + $campaigns = array(); + $totals = array('impressions' => 0, 'clicks' => 0, 'spend' => 0.0); + + return $this->formatResponse($campaigns, $totals, $dateStart, $dateEnd); + } catch (Exception $e) { + $this->setError('Failed to fetch data: ' . $e->getMessage()); + return false; + } + } + + public function getAvailableMetrics() + { + return array( + 'impressions' => array('name' => 'Impressions', 'type' => 'integer'), + 'clicks' => array('name' => 'Clicks', 'type' => 'integer'), + 'spend' => array('name' => 'Spend', 'type' => 'currency', 'currency' => 'USD'), + 'ctr' => array('name' => 'CTR', 'type' => 'percentage', 'calculated' => true), + ); + } + + /** + * Defines the credential fields shown in the admin configuration form. + * These are rendered automatically by admin/setup.php — no edits needed there. + * + * 'secure' => true causes the value to be encrypted in the database. + * 'placeholder' shown in the input field as a hint. + * 'description' shown as help text next to the field. + */ + public function getConfigurationFields() + { + return array( + 'MOKODOLIADINSIGHTS_YOURPLATFORM_API_KEY' => array( + 'label' => 'API Key', + 'type' => 'text', + 'required' => true, + 'secure' => true, + 'description' => 'Your Platform API key', + ), + 'MOKODOLIADINSIGHTS_YOURPLATFORM_ACCOUNT_ID' => array( + 'label' => 'Account ID', + 'type' => 'text', + 'required' => true, + 'secure' => false, + 'description' => 'Your advertising account ID', + 'placeholder' => 'acct_123456789', + ), + ); + } + + public function getCapabilities() + { + return array( + 'campaign_reporting', + 'date_range_filtering', + ); + } +} +``` + +### Auto-Discovery Rules + +`AdSystemFactory` discovers your service if **all** of the following are true: + +| Rule | Detail | +|------|--------| +| Subdirectory of `src/services/` | Direct child directory only | +| Not `examples/` | That directory is reserved for templates | +| Filename `Service.class.php` | Class name must match filename | +| Class extends `BaseAdService` | Via `is_subclass_of()` check | +| `const SERVICE_ID` is a non-empty string | Acts as the registry key | + +--- + +## Step 2 — Add Translations + +Edit `src/langs/en_US/mokodoliadinsights.lang` and add: + +``` +# Your Platform +YourPlatformName = Your Platform Name +YourPlatformNameSection = Your Platform Name Configuration +MOKODOLIADINSIGHTS_YOURPLATFORM_API_KEY = API Key +MOKODOLIADINSIGHTS_YOURPLATFORM_ACCOUNT_ID = Account ID +``` + +**Naming convention for the section heading key:** +Remove all spaces from `SERVICE_NAME` and append `Section`: +`'Your Platform Name'` → `'YourPlatformNameSection'` + +If no translation key is found Dolibarr falls back to displaying the raw key, +so adding translations is recommended but not strictly required. + +--- + +## Step 3 — *(Optional)* Create a README + +Document platform-specific setup in +`src/services/yourplatform/README.md`: + +```markdown +# Your Platform Service + +## Requirements +- Your Platform account with API access + +## Getting Credentials +1. Log in to the developer dashboard +2. Create an API key under Settings → API Access + +## Supported Features +- Campaign reporting +- Date range filtering + +## Known Limitations +- Maximum 90-day date range +- Rate limit: 100 req/hour +``` + +--- + +## Verifying the Integration + +After adding your service: + +1. Open the MokoDoliAdInsights admin setup page. +2. Confirm **Your Platform Name** appears in the **Ad System** dropdown. +3. Confirm the **Your Platform Name Configuration** section appears with the + fields defined in `getConfigurationFields()`. +4. Enter credentials and save. +5. Navigate to **Generate Report**, select the new platform, and verify data is + fetched. + +--- + +## Reference + +### Files You Always Edit + +| File | What to add | +|------|-------------| +| `src/services//Service.class.php` | The service class (required) | +| `src/langs/en_US/mokodoliadinsights.lang` | Translation strings (recommended) | + +### Files You Never Need to Edit + +| File | Why it's automatic | +|------|-------------------| +| `src/class/adsystemfactory.class.php` | Auto-discovers from `src/services/` | +| `src/admin/setup.php` | Generates config sections from `getConfigurationFields()` | + +### BaseAdService Helper Methods + +```php +// Configuration +protected function isConfigValueSet($key); // true/false +protected function getConfigValue($key, $default); // read config value +protected function loadConfiguration(); // override to load credentials + +// Data +protected function normalizeDate($date); // date/timestamp → int +protected function formatResponse($campaigns, $totals, $start, $end); // standard JSON + +// Error handling +protected function setError($message); // store error +public function getError(); // retrieve last error +``` + +### Standard Response Format + +`formatResponse()` produces: + +```json +{ + "service_id": "yourplatform", + "service_name": "Your Platform Name", + "provider": "your_company", + "campaigns": [ { "id": "...", "name": "...", "impressions": 0 } ], + "totals": { "impressions": 0, "clicks": 0, "spend": 0.0 }, + "period": { "start": "2025-01-01", "end": "2025-01-31" }, + "generated_at": "2025-01-31 12:00:00" +} +``` + +### Capabilities You Can Declare + +```php +public function getCapabilities() +{ + return array( + 'campaign_reporting', // basic campaign metrics + 'conversion_tracking', // conversion data + 'date_range_filtering', // custom date ranges + 'geographic_breakdown', // geographic data + 'device_breakdown', // device-specific data + 'video_metrics', // video views / completion + 'video_completion_tracking',// quartile completion rates + 'engagement_tracking', // likes, shares, comments + 'audience_insights', // audience demographics + 'keyword_analysis', // keyword performance + ); +} +``` + +### Example Service + +See `src/services/examples/ExampleAdService.class.php` for a complete +annotated template. + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/architecture.md b/MokoConsulting/MokoDoliAdInsights/architecture.md new file mode 100644 index 0000000..06acf3b --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/architecture.md @@ -0,0 +1,634 @@ +← [Home](Home) + +# Architecture Overview + +This document explains the technical architecture of the MokoDoliAdInsights module and how it achieves multi-platform advertising system integration with Claude AI analysis. + +## Design Principles + +The module is built on these core principles: + +1. **Interface-based Design**: All ad clients implement a common interface +2. **Factory Pattern**: Centralized client instantiation +3. **Extensibility**: Easy to add new platforms +4. **Security**: Encrypted credential storage +5. **Separation of Concerns**: Clear boundaries between data fetching, analysis, and presentation + +## System Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Dolibarr Interface │ +│ (Admin UI, Report Pages, Dashboard, Scheduled Tasks) │ +└───────────────────────┬─────────────────────────────────────┘ + │ +┌───────────────────────▼─────────────────────────────────────┐ +│ AdSystemFactory │ +│ • create($db, $system) │ +│ • getAvailableSystems() │ +│ • getCurrentSystem() │ +└───────────────────────┬─────────────────────────────────────┘ + │ + ┌──────────────┼──────────────┐ + │ │ │ +┌────────▼───────┐ ┌───▼───────┐ ┌───▼──────────┐ +│ GoogleAdsClient│ │FacebookAds│ │MicrosoftAds │ +│ │ │ Client │ │ Client │ +└────────┬───────┘ └───┬───────┘ └───┬──────────┘ + │ │ │ + └─────────────┼─────────────┘ + │ implements + ┌─────────────▼──────────────┐ + │ AdSystemClientInterface │ + │ • getSystemName() │ + │ • getSystemDisplayName() │ + │ • isConfigured() │ + │ • fetchCampaignData() │ + │ • getError() │ + └─────────────┬───────────────┘ + │ + ┌─────────────▼───────────────┐ + │ Report Class │ + │ • ad_system_data │ + │ • ad_system_type │ + │ • claude_analysis │ + └─────────────┬───────────────┘ + │ + ┌─────────────▼───────────────┐ + │ Claude AI Client │ + │ • analyzeData() │ + │ • generateInsights() │ + └──────────────────────────────┘ +``` + +## Core Components + +### 1. AdSystemClientInterface + +The foundation of the multi-platform architecture. All ad system clients must implement this interface. + + +**Methods**: + +```php +interface AdSystemClientInterface +{ + /** + * Get the system identifier (e.g., 'googleads', 'facebookads') + * @return string + */ + public function getSystemName(); + + /** + * Get the display name (e.g., 'Google Ads', 'Facebook Ads') + * @return string + */ + public function getSystemDisplayName(); + + /** + * Check if all required credentials are configured + * @return bool + */ + public function isConfigured(); + + /** + * Fetch campaign data for the specified date range + * @param string|int $dateStart + * @param string|int $dateEnd + * @return string|false JSON-encoded data or false on error + */ + public function fetchCampaignData($dateStart, $dateEnd); + + /** + * Get the last error message + * @return string + */ + public function getError(); +} +``` + +**Purpose**: +- Ensures consistency across all ad platform implementations +- Makes the codebase predictable and maintainable +- Allows polymorphic usage of clients + +### 2. Ad System Clients + +Individual implementations for each advertising platform. + +#### GoogleAdsClient + + +**Configuration Requirements**: +- `MOKODOLIADINSIGHTS_GOOGLEADS_CLIENT_ID` +- `MOKODOLIADINSIGHTS_GOOGLEADS_CLIENT_SECRET` +- `MOKODOLIADINSIGHTS_GOOGLEADS_DEVELOPER_TOKEN` +- `MOKODOLIADINSIGHTS_GOOGLEADS_REFRESH_TOKEN` +- `MOKODOLIADINSIGHTS_GOOGLEADS_CUSTOMER_ID` + +**Data Structure**: +```json +{ + "ad_system": "googleads", + "ad_system_display": "Google Ads", + "campaigns": [ + { + "id": "12345678", + "name": "Campaign Name", + "impressions": 10000, + "clicks": 250, + "cost": 125.50, + "conversions": 15, + "ctr": 2.50, + "cpc": 0.50 + } + ], + "totals": {...}, + "period": {...} +} +``` + +#### FacebookAdsClient + + +**Configuration Requirements**: +- `MOKODOLIADINSIGHTS_FACEBOOKADS_APP_ID` +- `MOKODOLIADINSIGHTS_FACEBOOKADS_APP_SECRET` +- `MOKODOLIADINSIGHTS_FACEBOOKADS_ACCESS_TOKEN` +- `MOKODOLIADINSIGHTS_FACEBOOKADS_ACCOUNT_ID` + +#### MicrosoftAdsClient + + +**Configuration Requirements**: +- `MOKODOLIADINSIGHTS_MICROSOFTADS_CLIENT_ID` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_CLIENT_SECRET` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_DEVELOPER_TOKEN` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_REFRESH_TOKEN` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_ACCOUNT_ID` + +### 3. AdSystemFactory + +Centralized factory for creating ad system clients. + + +**Methods**: + +```php +class AdSystemFactory +{ + /** + * Get list of available ad systems + * @return array ['googleads' => 'Google Ads', ...] + */ + public static function getAvailableSystems(); + + /** + * Create an ad system client + * @param DoliDB $db Database handler + * @param string $systemName Optional system name + * @return AdSystemClientInterface|false + */ + public static function create(DoliDB $db, $systemName = null); + + /** + * Get currently configured system + * @return string + */ + public static function getCurrentSystem(); +} +``` + +**Usage Examples**: + +```php +// Create client for configured system +$client = AdSystemFactory::create($db); + +// Create specific client +$googleClient = AdSystemFactory::create($db, 'googleads'); +$facebookClient = AdSystemFactory::create($db, 'facebookads'); + +// Get available systems +$systems = AdSystemFactory::getAvailableSystems(); +// Returns: ['googleads' => 'Google Ads', 'facebookads' => 'Facebook Ads', ...] + +// Get current system +$current = AdSystemFactory::getCurrentSystem(); +// Returns: 'googleads' (or configured system) +``` + +### 4. Report Class + +Manages report data and persistence. + + +**Properties**: + +```php +class Report extends CommonObject +{ + public $ad_system_data; // JSON string of campaign data + public $ad_system_type; // 'googleads', 'facebookads', 'microsoftads' + public $claude_analysis; // JSON string of AI analysis + public $date_start; // Report period start + public $date_end; // Report period end + // ... other properties +} +``` + +**Key Features**: +- Handles both old and new database schemas +- Automatic ref generation with format `ADCL[YYMMDD][NNNN]` + +### 5. Claude AI Analyzer + +Handles AI-powered analysis of campaign data. + + +**Configuration**: +- `MOKODOLIADINSIGHTS_CLAUDE_API_KEY` +- `MOKODOLIADINSIGHTS_CLAUDE_MODEL` + +## Data Flow + +### Report Generation Flow + +``` +1. User triggers report generation + ↓ +2. System reads configuration to determine active ad system + ↓ +3. AdSystemFactory::create() instantiates appropriate client + ↓ +4. Client->fetchCampaignData() retrieves data from API + ↓ +5. Data is validated and normalized + ↓ +6. ClaudeAnalyzer->analyze() sends data to Claude AI + ↓ +7. AI returns insights and recommendations + ↓ +8. Report object created with: + - ad_system_data (campaign metrics) + - ad_system_type (platform identifier) + - claude_analysis (AI insights) + ↓ +9. Report saved to database + ↓ +10. User sees comprehensive report with insights +``` + +### Scheduled Task Flow + +``` +1. Cron/Scheduled task triggers + ↓ +2. Check if auto-refresh is enabled + ↓ +3. Determine date range based on schedule (daily/weekly/monthly) + ↓ +4. Create ad system client via factory + ↓ +5. Fetch campaign data + ↓ +6. Analyze with Claude AI + ↓ +7. Create and save report + ↓ +8. Notify users (if configured) +``` + +## Database Schema + +### llx_mokodoliadinsights_report + +Primary table for storing reports. + +```sql +CREATE TABLE llx_mokodoliadinsights_report( + rowid integer AUTO_INCREMENT PRIMARY KEY NOT NULL, + ref varchar(128) NOT NULL, + label varchar(255), + description text, + date_report datetime NOT NULL, + date_start datetime NOT NULL, + date_end datetime NOT NULL, + ad_system_data longtext, -- Campaign data JSON + ad_system_type varchar(50) DEFAULT 'googleads' NOT NULL, + claude_analysis longtext, -- AI analysis JSON + metrics_summary text, + status integer DEFAULT 0 NOT NULL, + note_public text, + note_private text, + date_creation datetime NOT NULL, + tms timestamp DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + fk_user_creat integer NOT NULL, + fk_user_modif integer, + entity integer DEFAULT 1 NOT NULL, + INDEX idx_mokodoliadinsights_report_ad_system_type (ad_system_type) +) ENGINE=innodb; +``` + +**Key Fields**: +- `ad_system_data`: Stores JSON-encoded campaign data from any platform +- `ad_system_type`: Identifies which platform the data came from +- `claude_analysis`: Stores AI-generated insights +- Index on `ad_system_type` for efficient filtering + +## Configuration Management + +### Configuration Keys + +All configuration is stored in Dolibarr's `const` table: + +**Ad System Selection**: +- `MOKODOLIADINSIGHTS_AD_SYSTEM`: Current active platform + +**Google Ads**: +- `MOKODOLIADINSIGHTS_GOOGLEADS_CLIENT_ID` +- `MOKODOLIADINSIGHTS_GOOGLEADS_CLIENT_SECRET` +- `MOKODOLIADINSIGHTS_GOOGLEADS_DEVELOPER_TOKEN` +- `MOKODOLIADINSIGHTS_GOOGLEADS_REFRESH_TOKEN` +- `MOKODOLIADINSIGHTS_GOOGLEADS_CUSTOMER_ID` + +**Facebook Ads**: +- `MOKODOLIADINSIGHTS_FACEBOOKADS_APP_ID` +- `MOKODOLIADINSIGHTS_FACEBOOKADS_APP_SECRET` +- `MOKODOLIADINSIGHTS_FACEBOOKADS_ACCESS_TOKEN` +- `MOKODOLIADINSIGHTS_FACEBOOKADS_ACCOUNT_ID` + +**Microsoft Ads**: +- `MOKODOLIADINSIGHTS_MICROSOFTADS_CLIENT_ID` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_CLIENT_SECRET` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_DEVELOPER_TOKEN` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_REFRESH_TOKEN` +- `MOKODOLIADINSIGHTS_MICROSOFTADS_ACCOUNT_ID` + +**Claude AI**: +- `MOKODOLIADINSIGHTS_CLAUDE_API_KEY` +- `MOKODOLIADINSIGHTS_CLAUDE_MODEL` + +**Report Settings**: +- `MOKODOLIADINSIGHTS_AUTO_REFRESH` +- `MOKODOLIADINSIGHTS_DEFAULT_DATE_RANGE` + +**Scheduled Tasks** (new): +- `MOKODOLIADINSIGHTS_SCHEDULED_FREQUENCY`: daily/weekly/monthly +- `MOKODOLIADINSIGHTS_SCHEDULED_ENABLED`: 0/1 + +### Security + +Sensitive credentials are stored with encryption: +- Uses `setAsSecureKey()` in form setup +- Dolibarr's encryption mechanism protects API keys +- Never exposed in logs or error messages + +## Extensibility + +### Adding a New Ad Platform + +To add support for a new advertising platform (e.g., LinkedIn Ads): + +**1. Create Client Class** + +```php +// src/class/linkedinadsclient.class.php +require_once __DIR__.'/adsystemclientinterface.class.php'; + +class LinkedInAdsClient implements AdSystemClientInterface +{ + private $db; + private $clientId; + private $clientSecret; + private $accessToken; + + public function __construct(DoliDB $db) + { + global $conf; + $this->db = $db; + $this->clientId = getDolGlobalString('MOKODOLIADINSIGHTS_LINKEDIN_CLIENT_ID'); + $this->clientSecret = getDolGlobalString('MOKODOLIADINSIGHTS_LINKEDIN_CLIENT_SECRET'); + $this->accessToken = getDolGlobalString('MOKODOLIADINSIGHTS_LINKEDIN_ACCESS_TOKEN'); + } + + public function getSystemName() + { + return 'linkedinads'; + } + + public function getSystemDisplayName() + { + return 'LinkedIn Ads'; + } + + public function isConfigured() + { + return !empty($this->clientId) && !empty($this->clientSecret) && + !empty($this->accessToken); + } + + public function fetchCampaignData($dateStart, $dateEnd) + { + // Implement LinkedIn Ads API call + // Return standardized JSON format + } + + public function getError() + { + return $this->error; + } +} +``` + +**2. Register in Factory** + +```php +// In src/class/adsystemfactory.class.php +public static function getAvailableSystems() +{ + return array( + 'googleads' => 'Google Ads', + 'facebookads' => 'Facebook Ads', + 'microsoftads' => 'Microsoft Ads', + 'linkedinads' => 'LinkedIn Ads' // Add this + ); +} + +public static function create(DoliDB $db, $systemName = null) +{ + // ... existing code ... + + switch ($systemName) { + // ... existing cases ... + case 'linkedinads': + require_once __DIR__.'/linkedinadsclient.class.php'; + return new LinkedInAdsClient($db); + } +} +``` + +**3. Add Configuration** + +```php +// In src/admin/setup.php +$formSetup->newItem('LinkedInAdsSection')->setAsTitle(); + +$item = $formSetup->newItem('MOKODOLIADINSIGHTS_LINKEDIN_CLIENT_ID'); +$item->helpText = 'Your LinkedIn Ads Client ID'; + +$item = $formSetup->newItem('MOKODOLIADINSIGHTS_LINKEDIN_CLIENT_SECRET'); +$item->setAsSecureKey(); +$item->helpText = 'Your LinkedIn Ads Client Secret'; + +$item = $formSetup->newItem('MOKODOLIADINSIGHTS_LINKEDIN_ACCESS_TOKEN'); +$item->setAsSecureKey(); +$item->helpText = 'Your LinkedIn Ads Access Token'; +``` + +**4. Add Translations** + +``` +// In src/langs/en_US/mokodoliadinsights.lang +LinkedInAds = LinkedIn Ads +LinkedInAdsSection = LinkedIn Ads Configuration +MOKODOLIADINSIGHTS_LINKEDIN_CLIENT_ID = LinkedIn Client ID +... +``` + +**5. Update Documentation** + +Add LinkedIn Ads to: +- README files +- Installation guide +- This architecture document + +That's it! The new platform is fully integrated. + +## Performance Considerations + +### Caching + +- Campaign data is cached in the report table +- No need to re-fetch for existing reports +- Scheduled tasks can pre-generate reports + +### API Rate Limits + +Each platform has rate limits: +- **Google Ads**: 15,000 operations per day +- **Facebook Ads**: 200 calls per hour per user +- **Microsoft Ads**: Varies by account type + +The module handles rate limiting by: +- Caching fetched data +- Using scheduled tasks to spread API calls +- Implementing retry logic with exponential backoff + +### Database Performance + +- Index on `ad_system_type` for filtering +- Index on `date_report` for date-based queries +- Longtext fields for large JSON payloads + +## Security Architecture + +### Credential Storage + +- API keys stored encrypted via Dolibarr's security system +- Never logged or displayed in UI +- Transmitted only over HTTPS (recommended) + +### Input Validation + +- All user inputs sanitized +- Date ranges validated +- Platform selection validated against allowed values + +### Output Encoding + +- HTML output escaped +- JSON properly encoded +- XSS prevention throughout + +### Permissions + +Module defines granular permissions: +- Read reports +- Create/Update reports +- Delete reports +- Configure module + +## Error Handling + +### Graceful Degradation + +- If API call fails, error is logged and user-friendly message shown +- Reports can still be viewed even if new data can't be fetched +- System continues to work if one platform is misconfigured + +### Logging + +Errors are logged to: +- Dolibarr system log +- Module-specific error properties +- Database error fields + +### User Feedback + +- Clear error messages for configuration issues +- Helpful hints for common problems +- Links to documentation + +## Testing Strategy + +### Unit Testing + +Test individual components: +- Each ad client in isolation +- Factory pattern logic +- Report class methods + +### Integration Testing + +Test component interaction: +- Factory creating correct clients +- Clients returning valid data format +- Reports storing data correctly + +### End-to-End Testing + +Test complete workflows: +- Configure platform → Generate report +- Switch platforms → Generate report +- Scheduled task execution + +## Future Enhancements + +Potential architecture improvements: + +1. **Multi-platform Reports**: Compare data across platforms +2. **Data Warehouse**: Historical trend analysis +3. **Real-time Updates**: WebSocket-based live data +4. **Advanced Analytics**: Custom metrics and calculations +5. **API Endpoints**: REST API for external access +6. **Webhooks**: Event-driven updates + +## Conclusion + +The MokoDoliAdInsights architecture is: +- **Flexible**: Easy to add new platforms +- **Maintainable**: Clear separation of concerns +- **Scalable**: Handles multiple platforms efficiently +- **Secure**: Encrypted credentials and proper validation +- **User-friendly**: Simple configuration and usage + +The interface-based design with factory pattern provides a solid foundation for long-term growth and maintenance. + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/changelog.md b/MokoConsulting/MokoDoliAdInsights/changelog.md new file mode 100644 index 0000000..a29ecd1 --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/changelog.md @@ -0,0 +1,192 @@ +← [Home](Home) + +# Changelog + +All notable changes to the MokoDoliAdInsights module will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Changed +- **Module picto**: Updated module icon to Font Awesome `rectangle-ad` (classic/solid) — `fa-rectangle-ad` — across the module descriptor, Report object, and all admin/page headers. + +### Added +- **Google Ads, Facebook Ads, Microsoft Ads services**: Migrated to `BaseAdService` subclasses in `src/services/` (previously legacy clients in `src/class/`). Each service now exposes `getConfigurationFields()`, `getAvailableMetrics()`, `getCapabilities()`, and full PHPDoc. +- **Per-service admin tabs**: Every ad platform has its own configuration tab in the Dolibarr admin panel, rendered by the new `admin/service.php` page. Tabs are populated automatically from `AdSystemFactory::getAvailableSystems()` — no file edits needed when adding a new service. +- **`admin/service.php`**: Generic per-service credential configuration page. Validates the `?service=` parameter against the factory whitelist, renders `getConfigurationFields()` via `FormSetup`, and shows a configured/not-configured status indicator. +- **Video Advertising Services**: Two new ad platform integrations for video campaigns + - **YouTube Ads** (`youtubeads`): Integrates with Google Ads API v17 for YouTube video campaigns. Exposes video-specific metrics: video views, view rate, average CPE, engagements, and video completion quartiles (Q1/Q2/Q3/full). + - **TikTok Ads** (`tiktokads`): Integrates with TikTok for Business Marketing API v1.3. Exposes TikTok video metrics: video play actions, 2-second views, 6-second views, completion quartiles, and average video play duration per user. + - Both services declare `video_metrics` and `video_completion_tracking` capabilities. +- **Real Claude AI Analysis**: `ClaudeAnalyzer::analyzeData()` now makes live HTTP requests to the Anthropic Messages API (`api.anthropic.com/v1/messages`) instead of returning static mock data. +- **Auto-Discovery Service Architecture**: Adding a new ad platform service no longer requires editing any existing file. `AdSystemFactory` is pure auto-discovery — no hardcoded registrations. +- **Translation keys**: `ServiceSettingsPage`, `ServiceConfigured`, `ServiceNotConfigured` added. + +### Changed +- **`AdSystemFactory`**: Completely rewritten as pure auto-discovery. All hardcoded legacy client references and switch cases removed. `create()` and `getAvailableSystems()` are 100% driven by the filesystem scan of `src/services/`. +- **`admin/setup.php`**: Removed all per-service credential sections. Now contains only global settings: active ad system selector, Claude AI, report settings, and scheduled task settings. +- **`lib/mokodoliadinsights.lib.php`**: `mokodoliadinsightsAdminPrepareHead()` dynamically adds one tab per service from `AdSystemFactory::getAvailableSystems()`. + +### Removed +- `src/class/googleadsclient.class.php` — replaced by `src/services/google/GoogleAdsService.class.php` +- `src/class/facebookadsclient.class.php` — replaced by `src/services/facebook/FacebookAdsService.class.php` +- `src/class/microsoftadsclient.class.php` — replaced by `src/services/microsoft/MicrosoftAdsService.class.php` +- `src/class/adsystemclientinterface.class.php` — superseded by `src/services/AdServiceInterface.class.php` + +### Planned +- Multi-platform concurrent reporting (view multiple ad systems simultaneously) +- Live API integration for all services (currently placeholder mock data) +- Advanced competitive analysis features +- Custom report templates +- Data export to CSV/Excel +- Dashboard widgets for Dolibarr home + +## [1.2.0] - 2026-03-02 + +### Added +- **Scheduled Tasks**: Automated report generation using Dolibarr's cron system + - Configurable frequency: daily, weekly, or monthly + - Automatic date range calculation based on frequency + - Runs in background without user interaction +- **Report Types**: Support for different report categories + - Program Reports: Standard campaign performance analysis + - Competitive Analysis: Competitor insights and comparisons + - General Reports: Flexible general-purpose reporting +- **Configuration Options**: + - Default report type selection + - Scheduled task enable/disable + - Frequency selection (daily/weekly/monthly) +- Comprehensive scheduled task documentation +- Translation support for new features + +### Changed +- Updated module descriptor to version 1.2.0 +- Enhanced Report class with report_type field +- Improved admin configuration interface +- Updated all language files with new translations + +### Technical +- New class: `ScheduledTask` for automated reporting +- New database column: `report_type` with index +- Cron job registered in module descriptor + +## [1.1.0] - 2026-03-01 + +### Added +- **Multi-Platform Support**: Extended beyond Google Ads + - Facebook Ads integration + - Microsoft Ads integration + - Interface-based architecture for easy extensibility +- **Factory Pattern**: Centralized client creation via `AdSystemFactory` +- **Configuration UI**: Platform selection and credential management for all systems +- Comprehensive architecture documentation +- Installation and integration guides + +### Changed +- Added `ad_system_type` column to track platform source +- Module name updated to "Ad Systems + Claude AI" +- Enhanced README files for clarity + +### Technical +- New interface: `AdSystemClientInterface` +- New classes: + - `AdSystemFactory` + - `FacebookAdsClient` + - `MicrosoftAdsClient` +- Updated `GoogleAdsClient` to implement interface +- Database indexes added for performance + +## [1.0.0] - 2026-01-16 + +### Added +- Initial release of MokoDoliAdInsights +- Google Ads API integration +- Claude AI analysis integration +- Report generation with AI insights +- Dashboard for viewing reports +- Admin configuration interface +- Multi-entity support +- Permission system +- Translation support (English) +- Documentation + +### Features +- Fetch Google Ads campaign data +- AI-powered analysis via Claude +- Generate comprehensive reports +- View historical reports +- Configurable date ranges +- Secure credential storage + +--- + +## Version History Summary + +| Version | Date | Key Features | +|---------|------|--------------| +| 1.2.0 | 2026-03-02 | Scheduled tasks, report types, frequency options | +| 1.1.0 | 2026-03-01 | Multi-platform support (Facebook, Microsoft) | +| 1.0.0 | 2026-01-16 | Initial release with Google Ads + Claude AI | + +## Upgrade Guide + +### Upgrading to 1.2.0 from 1.1.0 + +1. **Backup**: Always backup your database before upgrading +2. **Update Files**: Pull latest code or download new version +3. **Run Migration**: + ```sql + source htdocs/custom/mokodoliadinsights/sql/llx_mokodoliadinsights_report-1.2.0.sql + ``` +4. **Clear Cache**: Delete Dolibarr cache files +5. **Test**: Generate a test report to verify functionality +6. **Configure**: Set up scheduled tasks if desired + +## Breaking Changes + +### Version 1.2.0 +- None. + +### Version 1.1.0 +- None. + +## Known Issues + +### Version 1.2.0 +- Scheduled tasks require Dolibarr cron to be properly configured +- Large date ranges may exceed API rate limits +- Competitive analysis features are basic (enhanced features planned) + +### Version 1.1.0 +- API credentials must be configured for each platform separately +- Only one platform can be active at a time +- Platform switching requires changing configuration + +## Support & Contributions + +Found a bug? Have a feature request? +- Create an issue: https://github.com/mokoconsulting-tech/MokoDoliAdInsights/issues +- Submit a pull request with improvements +- Check documentation: `/docs/` + +## License + +This module is licensed under the GNU General Public License v3.0. +See LICENSE file for details. + +--- + +**Note**: This changelog follows [Semantic Versioning](https://semver.org/). +- **MAJOR** version: Incompatible API changes +- **MINOR** version: Added functionality (backward compatible) +- **PATCH** version: Bug fixes (backward compatible) + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/development.md b/MokoConsulting/MokoDoliAdInsights/development.md new file mode 100644 index 0000000..4fc161d --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/development.md @@ -0,0 +1,323 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - use 600,000+ for development + $this->numero = 600001; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Development Phase + +Use module ID > 600,000: + +```php +$this->numero = 600001; +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/installation.md b/MokoConsulting/MokoDoliAdInsights/installation.md new file mode 100644 index 0000000..1619070 --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/installation.md @@ -0,0 +1,310 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring the MokoDoliAdInsights module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 19.0 or higher +- **PHP**: Version 7.4 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - curl (for API calls) + - json + - xml + +### API Requirements + +You'll need credentials for at least one advertising platform: + +#### Google Ads API +- Google Ads account with API access enabled +- OAuth 2.0 credentials (Client ID, Client Secret) +- Developer Token +- Refresh Token +- Customer ID + +**How to get**: [Google Ads API Documentation](https://developers.google.com/google-ads/api/docs/get-started/overview) + +#### Facebook Ads API +- Facebook Developer account +- Facebook App with Marketing API access +- App ID and App Secret +- Long-lived Access Token +- Ad Account ID + +**How to get**: [Facebook Marketing API Documentation](https://developers.facebook.com/docs/marketing-apis/get-started) + +#### Microsoft Ads API +- Microsoft Advertising account +- Registered application +- OAuth 2.0 credentials (Client ID, Client Secret) +- Developer Token +- Refresh Token +- Account ID + +**How to get**: [Microsoft Advertising API Documentation](https://docs.microsoft.com/en-us/advertising/guides/get-started) + +#### Claude AI API +- Anthropic account +- Claude API key + +**How to get**: [Claude AI API Documentation](https://docs.anthropic.com/) + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr's custom directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone the module repository: + +```bash +git clone https://github.com/mokoconsulting-tech/MokoDoliAdInsights.git mokodoliadinsights +``` + +### 2. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/mokodoliadinsights + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/mokodoliadinsights -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/mokodoliadinsights -type f -exec chmod 644 {} \; +``` + +### 3. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find "MokoDoliAdInsights" module in the list +4. Click the **Activate** button + +### 4. Configure the Module + +After activation, configure your ad system and API credentials: + +#### Select Ad System + +1. Go to **MokoDoliAdInsights → Setup** +2. In the **Ad System** dropdown, select your preferred platform: + - Google Ads + - Facebook Ads + - Microsoft Ads + +#### Configure Google Ads (if selected) + +1. Enter your **Client ID** +2. Enter your **Client Secret** (will be encrypted) +3. Enter your **Developer Token** (will be encrypted) +4. Enter your **Refresh Token** (will be encrypted) +5. Enter your **Customer ID** (format: XXX-XXX-XXXX) + +#### Configure Facebook Ads (if selected) + +1. Enter your **App ID** +2. Enter your **App Secret** (will be encrypted) +3. Enter your **Access Token** (will be encrypted) +4. Enter your **Account ID** (format: act_XXXXXXXXX) + +#### Configure Microsoft Ads (if selected) + +1. Enter your **Client ID** +2. Enter your **Client Secret** (will be encrypted) +3. Enter your **Developer Token** (will be encrypted) +4. Enter your **Refresh Token** (will be encrypted) +5. Enter your **Account ID** + +#### Configure Claude AI + +1. Enter your **Claude API Key** (will be encrypted) +2. Select your preferred **Claude Model** (default: claude-3-5-sonnet-20241022) + +#### Configure Report Settings + +1. **Auto-refresh Data**: Enable to automatically fetch new data when generating reports +2. **Default Date Range**: Select default period for reports (Last 7/30/90 Days, This Month, Last Month) + +### 6. Verify Installation + +Test the installation: + +1. Go to **MokoDoliAdInsights → Dashboard** +2. Click **Generate Report** +3. Select a date range +4. Click **Generate** + +If configured correctly: +- The system will fetch data from your selected ad platform +- Claude AI will analyze the data +- You'll see a comprehensive report with insights and recommendations + +## Database Tables + +The module creates the following database table: + +- `llx_mokodoliadinsights_report`: Stores reports with campaign data and AI analysis + +### Table Structure + +```sql +CREATE TABLE llx_mokodoliadinsights_report( + rowid integer AUTO_INCREMENT PRIMARY KEY NOT NULL, + ref varchar(128) NOT NULL, + label varchar(255), + description text, + date_report datetime NOT NULL, + date_start datetime NOT NULL, + date_end datetime NOT NULL, + ad_system_data longtext, -- Campaign data from ad platform + ad_system_type varchar(50), -- Platform: googleads/facebookads/microsoftads + claude_analysis longtext, -- AI analysis results + metrics_summary text, + status integer DEFAULT 0 NOT NULL, + -- Additional fields... +) ENGINE=innodb; +``` + +## Troubleshooting + +### Module Not Appearing + +**Problem**: Module doesn't appear in the modules list + +**Solutions**: +- Clear Dolibarr cache: Delete `documents/install.lock` and refresh browser +- Check file permissions (Apache/Nginx user needs read access) +- Verify directory name is `mokodoliadinsights` (all lowercase) +- Check PHP error logs: `/var/log/apache2/error.log` or `/var/log/nginx/error.log` + +### Module Activation Fails + +**Problem**: Error when clicking Activate + +**Solutions**: +- Check database connectivity in `conf/conf.php` +- Verify database user has CREATE TABLE permissions +- Check Dolibarr logs: `documents/dolibarr.log` +- Ensure no syntax errors: `php -l core/modules/modMokoDoliAdInsights.class.php` + +### API Connection Errors + +**Problem**: "Error connecting to [Platform] API" + +**Solutions**: + +For **Google Ads**: +- Verify OAuth 2.0 credentials are correct +- Ensure Developer Token is approved +- Check Customer ID format (XXX-XXX-XXXX) +- Verify API access is enabled in Google Ads account + +For **Facebook Ads**: +- Verify App has Marketing API permissions +- Ensure Access Token hasn't expired +- Check Ad Account ID format (act_XXXXXXXXX) +- Verify you have access to the specified ad account + +For **Microsoft Ads**: +- Verify OAuth credentials are correct +- Ensure Developer Token is valid +- Check Account ID is correct +- Verify API access is enabled + +For **Claude AI**: +- Verify API key is correct and active +- Check if you have sufficient API credits +- Ensure your plan supports the selected model + +### Data Not Fetching + +**Problem**: Report generates but shows no data + +**Solutions**: +- Verify date range has actual campaign data +- Check if campaigns were active during selected period +- Ensure ad account has campaigns +- Review API rate limits (you may be throttled) +- Check network connectivity and firewall settings + +### Permission Errors + +**Problem**: "Access forbidden" errors + +**Solutions**: +- Verify user has module permissions in Dolibarr +- Check user belongs to correct group +- Ensure module permissions are properly defined +- Log in as administrator to test + +## Uninstallation + +To remove the module: + +### 1. Deactivate + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find "MokoDoliAdInsights" module +3. Click **Deactivate** + +### 2. Remove Files (Optional) + +```bash +rm -rf /path/to/dolibarr/htdocs/custom/mokodoliadinsights +``` + +### 3. Remove Database Tables (Optional) + +**Warning**: This will delete all reports and data! + +```sql +DROP TABLE llx_mokodoliadinsights_report; +``` + +## Next Steps + +After successful installation: + +- Read the [Architecture Overview](architecture.md) to understand the system +- Review the [Development Guide](development.md) if you plan to customize +- See the [Adding Services guide](adding-services.md) to add more platforms +- See [Usage Examples](../src/README.md#usage) in the main documentation + +## Support + +For installation issues: +- Check Dolibarr logs: `documents/dolibarr.log` +- Review PHP error logs +- Create an issue in the [GitHub repository](https://github.com/mokoconsulting-tech/MokoDoliAdInsights/issues) +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +## Security Notes + +- API credentials are stored encrypted in the database +- Use HTTPS for production installations +- Restrict file permissions appropriately +- Keep API keys secret and never commit them to version control +- Regularly update the module and Dolibarr core +- Review the [Security Policy](SECURITY) for best practices + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/module-id-policy.-.-.md b/MokoConsulting/MokoDoliAdInsights/module-id-policy.-.-.md new file mode 100644 index 0000000..f318578 --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/quickstart-service.-.-.md b/MokoConsulting/MokoDoliAdInsights/quickstart-service.-.-.md new file mode 100644 index 0000000..d5f22f7 --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/quickstart-service.-.-.md @@ -0,0 +1,222 @@ +← [Home](Home) + +# Quick Start: Adding a New Ad Platform + +This is a condensed guide for experienced developers. For detailed explanations, see [adding-services.md](adding-services.md). + +## 1. Copy Template (2 minutes) + +```bash +cd src/services/ +cp -r examples/ yourplatform/ +cd yourplatform/ +mv ExampleAdService.class.php YourPlatformService.class.php +``` + +## 2. Update Service Class (10 minutes) + +Edit `YourPlatformService.class.php`: + +```php +class YourPlatformService extends BaseAdService +{ + public function __construct(DoliDB $db) + { + $this->serviceId = 'your_platform'; + $this->serviceName = 'Your Platform'; + $this->provider = 'company_name'; + parent::__construct($db); + } + + protected function loadConfiguration() + { + $this->config = array( + 'api_key' => getDolGlobalString('MOKODOLIADINSIGHTS_YOURPLATFORM_API_KEY'), + 'api_secret' => getDolGlobalString('MOKODOLIADINSIGHTS_YOURPLATFORM_API_SECRET'), + ); + } + + public function isConfigured() + { + return $this->isConfigValueSet('api_key') && + $this->isConfigValueSet('api_secret'); + } + + // Implement other required methods... +} +``` + +## 3. Add Configuration (5 minutes) + +Edit `src/admin/setup.php`: + +```php +$formSetup->newItem('YourPlatformSection')->setAsTitle(); + +$item = $formSetup->newItem('MOKODOLIADINSIGHTS_YOURPLATFORM_API_KEY'); +$item->setAsSecureKey(); +$item->helpText = 'Your Platform API Key'; + +$item = $formSetup->newItem('MOKODOLIADINSIGHTS_YOURPLATFORM_API_SECRET'); +$item->setAsSecureKey(); +$item->helpText = 'Your Platform API Secret'; +``` + +## 4. Add Translations (2 minutes) + +Edit `src/langs/en_US/mokodoliadinsights.lang`: + +``` +YourPlatform = Your Platform +YourPlatformSection = Your Platform Configuration +MOKODOLIADINSIGHTS_YOURPLATFORM_API_KEY = API Key +MOKODOLIADINSIGHTS_YOURPLATFORM_API_SECRET = API Secret +``` + +## 5. Register Service (3 minutes) + +Edit `src/class/adsystemfactory.class.php`: + +```php +public static function getAvailableSystems() +{ + return array( + // ... existing systems ... + 'your_platform' => 'Your Platform', + ); +} + +public static function create(DoliDB $db, $systemName = null) +{ + switch ($systemName) { + // ... existing cases ... + case 'your_platform': + require_once __DIR__.'/../services/yourplatform/YourPlatformService.class.php'; + return new YourPlatformService($db); + } +} +``` + +## 6. Test (5 minutes) + +1. Configure credentials in Dolibarr +2. Select your platform +3. Generate test report +4. Verify data + +## Total Time: ~30 minutes + +## Key Files + +| File | Purpose | +|------|---------| +| `YourPlatformService.class.php` | Main service logic | +| `admin/setup.php` | Configuration UI | +| `langs/en_US/mokodoliadinsights.lang` | Translations | +| `class/adsystemfactory.class.php` | Service registration | + +## Common Patterns + +### API Call with Error Handling + +```php +try { + $ch = curl_init($apiUrl); + curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); + curl_setopt($ch, CURLOPT_HTTPHEADER, array( + 'X-API-Key: ' . $this->getConfigValue('api_key'), + )); + + $response = curl_exec($ch); + $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); + curl_close($ch); + + if ($httpCode !== 200) { + $this->setError('API error: HTTP ' . $httpCode); + return false; + } + + return json_decode($response, true); +} catch (Exception $e) { + $this->setError($e->getMessage()); + return false; +} +``` + +### Data Transformation + +```php +$campaigns = array(); +foreach ($apiData['items'] as $item) { + $campaigns[] = array( + 'id' => $item['campaign_id'], + 'name' => $item['campaign_name'], + 'impressions' => (int)$item['metrics']['impressions'], + 'clicks' => (int)$item['metrics']['clicks'], + 'spend' => (float)$item['metrics']['cost'], + ); +} + +return $this->formatResponse($campaigns, $totals, $dateStart, $dateEnd); +``` + +### OAuth Token Refresh + +```php +protected function getAccessToken() +{ + $refreshToken = $this->getConfigValue('refresh_token'); + + $response = $this->makeOAuthRequest('/oauth/token', array( + 'grant_type' => 'refresh_token', + 'refresh_token' => $refreshToken, + 'client_id' => $this->getConfigValue('client_id'), + 'client_secret' => $this->getConfigValue('client_secret'), + )); + + return $response['access_token']; +} +``` + +## Need Help? + +- 📖 **Full Guide**: [adding-services.md](adding-services.md) +- 📝 **Template**: [services/examples/ExampleAdService.class.php](../src/services/examples/ExampleAdService.class.php) +- 🏗️ **Architecture**: [architecture.md](architecture.md) +- 💬 **Questions**: Create an issue on GitHub + +## Checklist + +Before submitting: + +- [ ] Service class extends `BaseAdService` +- [ ] All required methods implemented +- [ ] Configuration added to `setup.php` +- [ ] Translations added to `.lang` file +- [ ] Service registered in factory +- [ ] Tested with real API credentials +- [ ] Error handling implemented +- [ ] Documentation created (`README.md` in service directory) +- [ ] Code follows module standards +- [ ] No security vulnerabilities introduced + +## Pro Tips + +1. **Start Simple**: Get basic data fetching working first +2. **Use Existing Services**: Check Google/Facebook/Microsoft for patterns +3. **Test Incrementally**: Test each method as you implement it +4. **Handle Errors**: Always catch exceptions and set clear error messages +5. **Document Quirks**: Note platform-specific limitations in comments +6. **Rate Limiting**: Respect API rate limits from day one +7. **Validate Data**: Check API responses before processing +8. **Use Constants**: Define API URLs and defaults as class constants + +Happy coding! 🚀 + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAdInsights/update-server.-.-.md b/MokoConsulting/MokoDoliAdInsights/update-server.-.-.md new file mode 100644 index 0000000..2bcf78c --- /dev/null +++ b/MokoConsulting/MokoDoliAdInsights/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliAdInsights/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliAdInsights](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAdInsights) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliArt/Home.md b/MokoConsulting/MokoDoliArt/Home.md new file mode 100644 index 0000000..e5d146f --- /dev/null +++ b/MokoConsulting/MokoDoliArt/Home.md @@ -0,0 +1,43 @@ +# MokoDoliArt + +A Dolibarr module used to send proofs of art to clients for approval. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliArt/README.md b/MokoConsulting/MokoDoliArt/README.md new file mode 100644 index 0000000..2d7bc32 --- /dev/null +++ b/MokoConsulting/MokoDoliArt/README.md @@ -0,0 +1,148 @@ +← [Home](Home) + +# Documentation Index + +Welcome to the moko-platform Dolibarr Template documentation. This guide will help you navigate all available documentation resources. + +## Quick Links + +- [Installation Guide](installation.md) - Get started with installing the template +- [Development Guide](development.md) - Learn how to develop Dolibarr modules +- [Module ID Policy](module-id-policy.md) - Understand module ID assignment process +- [Changelog](changelog.md) - Track version history and changes + +## Documentation Structure + +### For New Users + +If you're new to this template, start here: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Configuration and setup + - Troubleshooting common issues + +2. **[Module ID Policy](module-id-policy.md)** + - Understanding module IDs + - Development vs. production IDs + - How to request an official ID + - Best practices + +### For Developers + +If you're developing a module, these guides will help: + +1. **[Development Guide](development.md)** + - Module structure and organization + - Module descriptor configuration + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + - Commit message guidelines + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Installation Guide](installation.md) to set up the template, then review the [Development Guide](development.md) for building your module. + +**Q: What module ID should I use?** +A: Use an ID greater than 600,000 during development. See the [Module ID Policy](module-id-policy.md) for details. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +**Q: Where are the code examples?** +A: The [Development Guide](development.md) contains numerous code examples and best practices. + +### Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) + +### moko-platform + +- [MokoConsulting Tech GitHub](https://github.com/mokoconsulting-tech) +- Template Repository: [moko-platform-Template-Dolibarr](https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 600001; // Development module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/ +git clone repo-url +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Template Version**: 1.0.0 +- **Last Updated**: 2026-01-16 +- **Minimum Dolibarr Version**: 12.0 +- **PHP Version**: 7.4+ + +--- + +**Next Steps**: +- New to the template? Start with [Installation Guide](installation.md) +- Ready to develop? Check out [Development Guide](development.md) +- Need to request a module ID? Review [Module ID Policy](module-id-policy.md) + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliArt/changelog.md b/MokoConsulting/MokoDoliArt/changelog.md new file mode 100644 index 0000000..5c25d74 --- /dev/null +++ b/MokoConsulting/MokoDoliArt/changelog.md @@ -0,0 +1,70 @@ +← [Home](Home) + +# Changelog + +All notable changes to this project template will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Comprehensive README.md with project overview and usage instructions +- Module ID policy documentation +- Installation guide with detailed setup instructions +- Development guide with best practices and examples +- Contributing guidelines +- Documentation structure following moko-platform + +## [1.0.0] - 2026-01-16 + +### Added +- Initial template structure for Dolibarr modules +- Basic documentation framework +- Module ID policy requiring issue-based requests +- Support for temporary development IDs (600,000+) + +--- + +## Template Usage Notes + +When using this template for your module: + +1. Copy this changelog to your project +2. Update the version numbers as you develop +3. Document all changes in the appropriate category: + - **Added** for new features + - **Changed** for changes in existing functionality + - **Deprecated** for soon-to-be removed features + - **Removed** for now removed features + - **Fixed** for any bug fixes + - **Security** for vulnerability fixes + +Example entry: +```markdown +## [1.1.0] - 2026-02-15 + +### Added +- New feature X for handling Y +- Support for Z functionality + +### Fixed +- Bug in module activation +- Permission check in admin page + +### Changed +- Updated module descriptor format +- Improved error handling +``` + +[Unreleased]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/releases/tag/v1.0.0 + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliArt/development.md b/MokoConsulting/MokoDoliArt/development.md new file mode 100644 index 0000000..556144b --- /dev/null +++ b/MokoConsulting/MokoDoliArt/development.md @@ -0,0 +1,323 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - use 600,000+ for development + $this->numero = 600001; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Development Phase + +Use module ID > 600,000: + +```php +$this->numero = 600001; +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliArt/installation.md b/MokoConsulting/MokoDoliArt/installation.md new file mode 100644 index 0000000..2128a35 --- /dev/null +++ b/MokoConsulting/MokoDoliArt/installation.md @@ -0,0 +1,173 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring your Dolibarr module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 12.0 or higher +- **PHP**: Version 7.4 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - gd or imagick + - curl + - json + - xml + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr's custom directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone this template repository: + +```bash +git clone https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr.git yourmodule +``` + +Replace `yourmodule` with your desired module name (lowercase, no spaces). + +### 2. Rename and Configure + +Navigate to the module directory: + +```bash +cd yourmodule +``` + +Rename the module descriptor file: + +```bash +mv modYourmodule.class.php modYourModuleName.class.php +``` + +### 3. Configure Module ID + +Open the module descriptor file and set a temporary module ID greater than 600,000: + +```php +// In modYourModuleName.class.php +$this->numero = 600001; // Use a number > 600,000 for development +``` + +**Important:** Before publishing, request an official module ID by creating an issue in the repository. + +### 4. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/yourmodule + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type f -exec chmod 644 {} \; +``` + +### 5. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find your module in the list +4. Click the **Activate** button + +### 6. Configure Module Settings (if applicable) + +After activation: + +1. Go to **Home → Setup → Modules/Applications** +2. Click on your module name to access its configuration page +3. Configure any required settings +4. Save changes + +## Database Setup + +If your module requires database tables: + +### Automatic Setup + +The module descriptor can handle automatic table creation during activation. Ensure your SQL files are in the `sql/` directory: + +``` +sql/ +├── llx_yourmodule_table.sql +└── llx_yourmodule_table.key.sql +``` + +### Manual Setup + +Alternatively, run SQL scripts manually: + +```bash +mysql -u username -p database_name < sql/llx_yourmodule_table.sql +``` + +## Troubleshooting + +### Module Not Appearing + +- Clear Dolibarr cache: Delete `/documents/install.lock` and refresh +- Check file permissions +- Verify PHP syntax errors: `php -l modYourModuleName.class.php` + +### Permission Errors + +- Ensure Apache/Nginx user has read access to all module files +- Check `conf.php` file permissions in Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Check SQL file syntax +- Ensure database user has CREATE TABLE permissions + +## Uninstallation + +To remove the module: + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find your module and click **Deactivate** +3. Optionally, remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/yourmodule + ``` + +**Note:** Deactivating the module does not remove database tables. To remove data: + +```sql +DROP TABLE llx_yourmodule_table; +``` + +## Next Steps + +- Review the [Development Guide](development.md) to start customizing your module +- Check the [Module ID Policy](module-id-policy.md) before distribution +- Read the [Changelog](changelog.md) for version history + +## Support + +For installation issues: +- Create an issue in the repository +- Check Dolibarr logs: `/documents/dolibarr.log` +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliArt/module-id-policy.-.-.md b/MokoConsulting/MokoDoliArt/module-id-policy.-.-.md new file mode 100644 index 0000000..62b2e68 --- /dev/null +++ b/MokoConsulting/MokoDoliArt/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliArt/update-server.-.-.md b/MokoConsulting/MokoDoliArt/update-server.-.-.md new file mode 100644 index 0000000..830b3de --- /dev/null +++ b/MokoConsulting/MokoDoliArt/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliArt/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliArt](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliArt) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliAuth/Home.md b/MokoConsulting/MokoDoliAuth/Home.md new file mode 100644 index 0000000..0e11228 --- /dev/null +++ b/MokoConsulting/MokoDoliAuth/Home.md @@ -0,0 +1,28 @@ +# MokoDoliAuth + +A Dolibarr authentication suite + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAuth) | + +--- + +## Documentation + +| Page | Description | +|---|---| +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliAuth](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAuth) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliAuth/update-server.-.-.md b/MokoConsulting/MokoDoliAuth/update-server.-.-.md new file mode 100644 index 0000000..6a093e4 --- /dev/null +++ b/MokoConsulting/MokoDoliAuth/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliAuth/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliAuth](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliAuth) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/Home.md b/MokoConsulting/MokoDoliCare/Home.md new file mode 100644 index 0000000..e5039f1 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/Home.md @@ -0,0 +1,50 @@ +# MokoDoliCare + +A childcare management software built on Dolibarr. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | +| [quick start](quick-start.-.-) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [admin guide](admin-guide.-.-) | ← [Home](Home) | +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [family management](family-management.-.-) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [remote checkin](remote-checkin.-.-) | ← [Home](Home) | +| [roadmap](roadmap) | ← [Home](Home) | +| [troubleshooting](troubleshooting) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | +| [user guide](user-guide.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliCare/README.md b/MokoConsulting/MokoDoliCare/README.md new file mode 100644 index 0000000..918d253 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/README.md @@ -0,0 +1,317 @@ +← [Home](Home) + +# Documentation Index + +Welcome to the MokoDoliCare Childcare Management Module documentation. This comprehensive guide will help you install, configure, use, and maintain the module. + +## Quick Links + +### Getting Started +- [Quick Start Guide](quick-start.md) - **⚡ Get up and running in 10 minutes** +- [Installation Guide](installation.md) - Detailed installation and setup instructions +- [Module ID Policy](module-id-policy.md) - Understand module ID assignment process + +### User Documentation +- [User Guide](user-guide.md) - **📖 Complete guide for daily operations** +- [Remote Check-In Guide](remote-checkin.md) - **📱 Tablet check-in and payroll time clock** +- [Family Management Guide](family-management.md) - **👨‍👩‍👧‍👦 Managing families and linking children** +- [Database Schema](database-schema.md) - Detailed database structure reference + +### Administrator Documentation +- [Admin Guide](admin-guide.md) - System configuration and management +- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions + +### Developer Documentation +- [Development Guide](development.md) - Module development guidelines +- [Changelog](changelog.md) - Version history and planned features +- [Product Roadmap](roadmap.md) - **🗺️ Strategic vision and feature timeline** + +## Documentation Structure + +### 🚀 For New Users + +If you're new to MokoDoliCare, **start here**: + +1. **[Quick Start Guide](quick-start.md)** ⚡ **START HERE** + - 10-minute setup walkthrough + - Add your first child + - Record attendance + - Schedule activities + - Quick reference card + +2. **[Installation Guide](installation.md)** + - System requirements + - Detailed installation instructions + - Post-installation setup + - Troubleshooting installation issues + +3. **[User Guide](user-guide.md)** + - Complete feature documentation + - Child management workflows + - Attendance tracking procedures + - Activity planning and scheduling + - Daily operational workflows + - Tips and best practices + +### 👥 For Daily Users + +Essential guides for staff and teachers: + +1. **[User Guide](user-guide.md)** - Your main reference + - Child management + - Attendance tracking + - Activity scheduling + - Reports and analytics + - Daily workflows + +2. **[Quick Start Guide](quick-start.md)** - Quick reference + - Common tasks + - Keyboard shortcuts + - Quick reference card + +3. **[Troubleshooting Guide](troubleshooting.md)** - When things go wrong + - Common issues + - Error messages + - Quick fixes + +### 🔧 For System Administrators + +Complete system management documentation: + +1. **[Admin Guide](admin-guide.md)** - Primary admin reference + - Installation and configuration + - User management and permissions + - Security and compliance + - Backup and recovery + - Performance tuning + - Maintenance procedures + +2. **[Database Schema](database-schema.md)** - Technical reference + - Complete table structures + - Field descriptions + - Relationships and foreign keys + - Indexes and performance + - Example queries + +3. **[Troubleshooting Guide](troubleshooting.md)** - Problem solving + - Installation issues + - Database problems + - Permission issues + - Performance optimization + - Diagnostic tools + +### 💻 For Developers + +If you're developing or customizing the module: + +1. **[Development Guide](development.md)** + - Module structure and architecture + - Coding standards + - Security best practices + - Database operations + - API development + - Testing procedures + +2. **[Database Schema](database-schema.md)** + - Complete schema documentation + - Field definitions + - Query examples + - Performance considerations + +3. **[Module ID Policy](module-id-policy.md)** + - Understanding module IDs + - Development vs. production IDs + - How to request official ID + +4. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Pull request process + - Code review standards + +### 📚 Reference Materials + +- **[Changelog](changelog.md)** - Version history and planned features +- **[Product Roadmap](roadmap.md)** - Strategic vision and feature timeline +- **[README](README)** - Project overview +- **[Database Schema](database-schema.md)** - Complete technical reference +- **[Module ID Policy](module-id-policy.md)** - Module ID guidelines + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Quick Start Guide](quick-start.md) for a 10-minute walkthrough, or see [Installation Guide](installation.md) for detailed setup. + +**Q: How do I add a child?** +A: See [User Guide - Child Management](user-guide.md#child-management) for step-by-step instructions. + +**Q: How do I record attendance?** +A: See [User Guide - Attendance Tracking](user-guide.md#attendance-tracking) for daily attendance procedures. + +**Q: Something's not working, what do I do?** +A: Check the [Troubleshooting Guide](troubleshooting.md) for common issues and solutions. + +**Q: What module ID should I use?** +A: Use an ID greater than 600,000 during development. See the [Module ID Policy](module-id-policy.md) for details. + +**Q: How do I configure user permissions?** +A: See [Admin Guide - User Management](admin-guide.md#user-management) for detailed permission setup. + +**Q: Where's the database documentation?** +A: See [Database Schema](database-schema.md) for complete table structures, fields, and relationships. + +**Q: What features are planned for the future?** +A: See the [Product Roadmap](roadmap.md) for our strategic vision and upcoming features. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +### Support Resources + +- **GitHub Issues**: [Report bugs or request features](https://github.com/mokoconsulting-tech/MokoDoliCare/issues) +- **Troubleshooting Guide**: [troubleshooting.md](troubleshooting.md) - Check here first! +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ +- **Professional Support**: Contact [Moko Consulting](https://mokoconsulting.tech) + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) +- [Dolibarr Forum](https://www.dolibarr.org/forum) + +### MokoDoliCare Project + +- [GitHub Repository](https://github.com/mokoconsulting-tech/MokoDoliCare) +- [Issue Tracker](https://github.com/mokoconsulting-tech/MokoDoliCare/issues) +- [MokoConsulting Tech](https://github.com/mokoconsulting-tech) +- [Moko Consulting](https://mokoconsulting.tech) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 185065; // Official Dolibarr module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/ +git clone repo-url +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Documentation Overview + +### Complete Documentation Set + +| Document | Purpose | Audience | Length | +|----------|---------|----------|--------| +| [Quick Start Guide](quick-start.md) | Get running in 10 minutes | New users | 10 min read | +| [User Guide](user-guide.md) | Complete operational guide | Daily users | 45 min read | +| [Remote Check-In Guide](remote-checkin.md) | Tablet check-in setup | All users | 20 min read | +| [Family Management Guide](family-management.md) | Family management | All users | 25 min read | +| [Admin Guide](admin-guide.md) | System management | Administrators | 60 min read | +| [Installation Guide](installation.md) | Setup instructions | Administrators | 20 min read | +| [Database Schema](database-schema.md) | Technical reference | Developers/DBAs | 30 min read | +| [Troubleshooting Guide](troubleshooting.md) | Problem solving | All users | Reference | +| [Development Guide](development.md) | Development guidelines | Developers | 45 min read | +| [Module ID Policy](module-id-policy.md) | Module ID process | Developers | 15 min read | +| [Product Roadmap](roadmap.md) | Strategic vision | All users | 20 min read | +| [Changelog](changelog.md) | Version history | All users | 10 min read | + +### Documentation Statistics + +- **Total Pages**: 12 comprehensive guides +- **Total Content**: ~145+ pages of documentation +- **Last Updated**: 2026-03-03 +- **Documentation Version**: 1.1.0 + +## Version Information + +- **Module Version**: 1.1.0 +- **Documentation Version**: 1.1.0 +- **Last Updated**: 2026-03-03 +- **Minimum Dolibarr Version**: 12.0 +- **PHP Version**: 7.4+ +- **Database**: MySQL 5.7+ / MariaDB 10.3+ / PostgreSQL 11+ + +--- + +## Quick Navigation by Task + +### I want to... + +**Install the module** +→ Start: [Installation Guide](installation.md) +→ Quick: [Quick Start Guide](quick-start.md) + +**Learn how to use it** +→ Read: [User Guide](user-guide.md) +→ Quick: [Quick Start Guide](quick-start.md) + +**Add children and track attendance** +→ See: [User Guide - Child Management](user-guide.md#child-management) +→ See: [User Guide - Attendance](user-guide.md#attendance-tracking) + +**Configure the system** +→ Read: [Admin Guide](admin-guide.md) +→ Setup: [Admin Guide - Configuration](admin-guide.md#configuration) + +**Understand the database** +→ Read: [Database Schema](database-schema.md) + +**Fix a problem** +→ Check: [Troubleshooting Guide](troubleshooting.md) + +**Develop or customize** +→ Read: [Development Guide](development.md) +→ Schema: [Database Schema](database-schema.md) + +**Contribute to the project** +→ Read: [Contributing Guidelines](CONTRIBUTING) +→ Policy: [Module ID Policy](module-id-policy.md) + +--- + +**Next Steps**: +- ⚡ **New user?** Start with [Quick Start Guide](quick-start.md) - 10 minutes! +- 📖 **Daily user?** Read [User Guide](user-guide.md) for complete features +- 🔧 **Administrator?** Check [Admin Guide](admin-guide.md) for configuration +- 💻 **Developer?** Review [Development Guide](development.md) for code guidelines + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/admin-guide.-.-.md b/MokoConsulting/MokoDoliCare/admin-guide.-.-.md new file mode 100644 index 0000000..572ff4a --- /dev/null +++ b/MokoConsulting/MokoDoliCare/admin-guide.-.-.md @@ -0,0 +1,966 @@ +← [Home](Home) + +# Administrator Guide + +Complete guide for system administrators managing MokoDoliCare childcare module installation, configuration, and maintenance. + +## Table of Contents + +1. [System Requirements](#system-requirements) +2. [Installation](#installation) +3. [Configuration](#configuration) +4. [User Management](#user-management) +5. [Permissions and Security](#permissions-and-security) +6. [Backup and Recovery](#backup-and-recovery) +7. [Performance Tuning](#performance-tuning) +8. [Troubleshooting](#troubleshooting) +9. [Maintenance Tasks](#maintenance-tasks) + +--- + +## System Requirements + +### Minimum Requirements + +| Component | Requirement | +|-----------|-------------| +| **Dolibarr** | Version 12.0 or higher | +| **PHP** | Version 7.4 or higher (8.0+ recommended) | +| **Database** | MySQL 5.7+ / MariaDB 10.3+ / PostgreSQL 11+ | +| **Web Server** | Apache 2.4+ or Nginx 1.18+ | +| **Disk Space** | 50 MB for module + data storage | +| **Memory** | 256 MB PHP memory_limit minimum | + +### Recommended Requirements + +| Component | Recommendation | +|-----------|----------------| +| **PHP** | 8.1 or 8.2 | +| **Database** | MariaDB 10.6+ | +| **Memory** | 512 MB PHP memory_limit | +| **CPU** | 2+ cores | +| **Storage** | SSD for database | + +### Required PHP Extensions + +```bash +# Check installed extensions +php -m | grep -E "mysqli|pdo|gd|curl|json|xml|mbstring" +``` + +Required extensions: +- `mysqli` or `pgsql` - Database connectivity +- `gd` or `imagick` - Image processing +- `curl` - External communications +- `json` - JSON handling +- `xml` - XML processing +- `mbstring` - Multi-byte string support + +--- + +## Installation + +### Pre-Installation Checklist + +```bash +# 1. Verify Dolibarr installation +ls -la /path/to/dolibarr/htdocs/ + +# 2. Check custom directory exists and is writable +mkdir -p /path/to/dolibarr/htdocs/custom +chmod 755 /path/to/dolibarr/htdocs/custom + +# 3. Verify database credentials +mysql -u dolibarr_user -p dolibarr_db -e "SELECT VERSION();" + +# 4. Check PHP version and extensions +php -v +php -m +``` + +### Installation Methods + +#### Method 1: From ZIP File (Recommended for Production) + +1. Download the latest release ZIP +2. Log into Dolibarr as administrator +3. Navigate to **Home → Setup → Modules → Deploy External Module** +4. Upload the ZIP file +5. Wait for upload and extraction to complete +6. Click **Activate** on the Childcare module + +#### Method 2: From Git Repository (Recommended for Development) + +```bash +# Navigate to custom directory +cd /path/to/dolibarr/htdocs/custom/ + +# Clone repository +git clone https://github.com/mokoconsulting-tech/MokoDoliCare.git childcare + +# Copy module files from src/ to childcare/ +cp -r childcare/src/* childcare/ + +# Set permissions +chown -R www-data:www-data childcare/ +find childcare/ -type d -exec chmod 755 {} \; +find childcare/ -type f -exec chmod 644 {} \; + +# Activate in Dolibarr +# Home → Setup → Modules → Find "Childcare Management" → Activate +``` + +#### Method 3: Manual Installation + +```bash +# 1. Extract module files +unzip module_childcare-1.0.0.zip -d /path/to/dolibarr/htdocs/custom/childcare/ + +# 2. Set ownership +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/childcare/ + +# 3. Set permissions +chmod -R 755 /path/to/dolibarr/htdocs/custom/childcare/ + +# 4. Activate via Dolibarr web interface +``` + +### Post-Installation Verification + +```bash +# 1. Check database tables created +mysql -u user -p database -e "SHOW TABLES LIKE 'llx_childcare%';" + +# Expected output: +# llx_childcare_activity +# llx_childcare_attendance +# llx_childcare_child + +# 2. Check module files +ls -la /path/to/dolibarr/htdocs/custom/childcare/core/modules/ + +# Expected: modMokoDoliCare.class.php + +# 3. Verify module is active +mysql -u user -p database -e "SELECT * FROM llx_const WHERE name = 'MAIN_MODULE_CHILDCARE';" + +# Expected: value = '1' +``` + +--- + +## Configuration + +### Module Configuration Page + +**Access**: Home → Setup → Modules → Childcare Management → Setup + +### Basic Configuration + +#### Module Settings + +| Setting | Options | Description | +|---------|---------|-------------| +| **Default Status** | Active/Inactive | Default status for new children | +| **Attendance Required** | Yes/No | Require attendance record for active children | +| **Auto-Generate References** | Yes/No | Automatically generate child/activity references | +| **Reference Format** | CHILD###, C### | Format for auto-generated references | + +#### Configuration Constants + +Add to Dolibarr configuration if needed: + +```php +// In Home → Setup → Other Setup → System +// Or directly in database + +INSERT INTO llx_const (name, value, type, note, entity) +VALUES +('CHILDCARE_DEFAULT_STATUS', '1', 'chaine', 'Default child status', 1), +('CHILDCARE_AUTO_REF', '1', 'chaine', 'Auto-generate references', 1), +('CHILDCARE_REF_FORMAT', 'CHILD###', 'chaine', 'Reference number format', 1), +('CHILDCARE_ATTENDANCE_REQUIRED', '1', 'chaine', 'Require daily attendance', 1); +``` + +### Multi-Entity Configuration + +For managing multiple facilities: + +1. Enable multi-entity in Dolibarr: + - Home → Setup → Other Setup → Multi-entity → Enable + +2. Configure entity access: + ```sql + -- Assign childcare module to specific entities + UPDATE llx_childcare_child SET entity = 2 WHERE facility_id = 'FACILITY_B'; + ``` + +3. User entity assignments: + - Home → Users & Groups → Users → [User] → Entity tab + - Assign users to appropriate entities + +### Email Notification Settings + +Configure email notifications (if implemented): + +```php +// Configuration constants for notifications +'CHILDCARE_EMAIL_ATTENDANCE', '1' // Email daily attendance summary +'CHILDCARE_EMAIL_INCIDENTS', '1' // Email incident reports +'CHILDCARE_EMAIL_TEMPLATE', 'childcare' // Email template to use +``` + +### Appearance Customization + +#### Custom CSS + +Create custom styles: + +```bash +# Create custom CSS file +nano /path/to/dolibarr/htdocs/custom/childcare/css/childcare_custom.css +``` + +```css +/* Custom childcare styles */ +.childcare-alert-high { + background-color: #ff6b6b; + color: white; + padding: 10px; + border-radius: 5px; +} + +.childcare-attendance-present { + color: green; + font-weight: bold; +} +``` + +#### Module Icon + +Replace default icon: + +```bash +cp your_icon.png /path/to/dolibarr/htdocs/custom/childcare/img/object_childcare.png +``` + +--- + +## User Management + +### Creating Users + +1. **Navigate**: Home → Users & Groups → New User +2. **Fill in details**: + - Login, Name, Email + - Password (enforce strong passwords) + - Employee/External +3. **Save** and assign permissions + +### User Roles and Permissions + +#### Role: Administrator + +**Recommended Permissions**: +``` +Childcare Module: +✓ Read child records +✓ Create/Edit child records +✓ Delete child records +✓ Read attendance +✓ Create/Edit attendance +✓ Delete attendance +✓ Read activities +✓ Create/Edit activities +✓ Delete activities +✓ View reports +✓ Export data + +Other Modules: +✓ User management (if needed) +✓ System configuration (if needed) +``` + +#### Role: Lead Teacher + +**Recommended Permissions**: +``` +Childcare Module: +✓ Read child records +✓ Create/Edit child records +✗ Delete child records +✓ Read attendance +✓ Create/Edit attendance +✗ Delete attendance +✓ Read activities +✓ Create/Edit activities +✗ Delete activities +✓ View reports +✓ Export data +``` + +#### Role: Teacher + +**Recommended Permissions**: +``` +Childcare Module: +✓ Read child records +✗ Create/Edit child records +✗ Delete child records +✓ Read attendance +✓ Create/Edit attendance +✗ Delete attendance +✓ Read activities +✗ Create/Edit activities +✗ Delete activities +✗ View reports +✗ Export data +``` + +#### Role: Office Staff + +**Recommended Permissions**: +``` +Childcare Module: +✓ Read child records +✓ Create/Edit child records +✗ Delete child records +✓ Read attendance +✗ Create/Edit attendance +✗ Delete attendance +✓ Read activities +✗ Create/Edit activities +✗ Delete activities +✓ View reports +✓ Export data +``` + +### Bulk User Permission Setup + +```sql +-- Grant all childcare permissions to a user group +-- Example: Group ID 5 = Teachers + +INSERT INTO llx_user_rights (fk_user, fk_id) +SELECT u.rowid, 18506501 -- Read child records +FROM llx_user u +JOIN llx_usergroup_user ugu ON u.rowid = ugu.fk_user +WHERE ugu.fk_usergroup = 5; +``` + +--- + +## Permissions and Security + +### Permission Structure + +Childcare module uses these permission IDs (based on module ID 185065): + +| Permission | ID | Description | +|------------|------|-------------| +| Read child records | 18506501 | View child information | +| Create/Edit child records | 18506502 | Add and modify children | +| Delete child records | 18506503 | Remove child records | +| Read attendance | 18506521 | View attendance records | +| Create/Edit attendance | 18506522 | Record attendance | +| Read activities | 18506531 | View activities | +| Create/Edit activities | 18506532 | Manage activities | + +### Security Best Practices + +#### 1. Password Policy + +```php +// In conf/conf.php +$dolibarr_main_authentication = 'dolibarr'; // Use Dolibarr auth +$dolibarr_main_demo = '0'; // Disable demo mode +``` + +Enforce strong passwords: +- Minimum 12 characters +- Mix of upper/lowercase, numbers, symbols +- No dictionary words +- Regular password changes (90 days) + +#### 2. Session Security + +```php +// In conf/conf.php +$dolibarr_main_force_https = '1'; // Force HTTPS +$dolibarr_main_cookie_cryptkey = 'random_string'; // Secure cookie key +``` + +#### 3. File Permissions + +```bash +# Secure configuration file +chmod 600 /path/to/dolibarr/htdocs/conf/conf.php +chown www-data:www-data /path/to/dolibarr/htdocs/conf/conf.php + +# Secure module directory +chmod 755 /path/to/dolibarr/htdocs/custom/childcare/ +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/childcare/ +``` + +#### 4. Database Security + +```sql +-- Create dedicated database user with minimal privileges +CREATE USER 'childcare_user'@'localhost' IDENTIFIED BY 'strong_password'; +GRANT SELECT, INSERT, UPDATE, DELETE ON dolibarr_db.llx_childcare_* + TO 'childcare_user'@'localhost'; +FLUSH PRIVILEGES; +``` + +#### 5. Backup Encryption + +```bash +# Backup with encryption +mysqldump -u user -p dolibarr_db \ + llx_childcare_child \ + llx_childcare_attendance \ + llx_childcare_activity | \ + openssl enc -aes-256-cbc -salt -out childcare_backup_encrypted.sql.enc +``` + +### Audit Trail + +Enable detailed logging: + +```sql +-- Check who created/modified records +SELECT + c.ref, + c.firstname, + c.lastname, + u1.login as created_by, + c.date_creation, + u2.login as modified_by, + c.tms as last_modified +FROM llx_childcare_child c +LEFT JOIN llx_user u1 ON c.fk_user_creat = u1.rowid +LEFT JOIN llx_user u2 ON c.fk_user_modif = u2.rowid +ORDER BY c.tms DESC +LIMIT 20; +``` + +### GDPR Compliance + +For European Union data protection: + +1. **Right to Access**: Provide data export functionality +2. **Right to Erasure**: Implement data deletion procedures +3. **Data Minimization**: Only collect necessary information +4. **Consent**: Document parental consent for data collection +5. **Breach Notification**: Establish incident response procedures + +#### Data Retention Policy + +```sql +-- Archive old attendance records (older than 3 years) +CREATE TABLE llx_childcare_attendance_archive LIKE llx_childcare_attendance; + +INSERT INTO llx_childcare_attendance_archive +SELECT * FROM llx_childcare_attendance +WHERE attendance_date < DATE_SUB(CURDATE(), INTERVAL 3 YEAR); + +-- After verification, delete from main table +DELETE FROM llx_childcare_attendance +WHERE attendance_date < DATE_SUB(CURDATE(), INTERVAL 3 YEAR); +``` + +--- + +## Backup and Recovery + +### Backup Strategy + +#### Daily Backups + +```bash +#!/bin/bash +# /usr/local/bin/childcare_daily_backup.sh + +BACKUP_DIR="/backups/childcare" +DATE=$(date +%Y%m%d_%H%M%S) +DB_NAME="dolibarr_db" +DB_USER="backup_user" +DB_PASS="backup_password" + +# Create backup directory +mkdir -p "$BACKUP_DIR" + +# Backup database tables +mysqldump -u $DB_USER -p$DB_PASS $DB_NAME \ + llx_childcare_child \ + llx_childcare_attendance \ + llx_childcare_activity \ + > "$BACKUP_DIR/childcare_db_$DATE.sql" + +# Backup module files +tar -czf "$BACKUP_DIR/childcare_files_$DATE.tar.gz" \ + /path/to/dolibarr/htdocs/custom/childcare/ + +# Compress backup +gzip "$BACKUP_DIR/childcare_db_$DATE.sql" + +# Keep only last 30 days +find "$BACKUP_DIR" -name "childcare_*" -mtime +30 -delete + +echo "Backup completed: $DATE" +``` + +#### Weekly Full Backup + +```bash +#!/bin/bash +# Weekly full system backup including Dolibarr + +BACKUP_DIR="/backups/weekly" +DATE=$(date +%Y%m%d) + +# Full database backup +mysqldump -u root -p --all-databases > "$BACKUP_DIR/full_db_$DATE.sql" + +# Full Dolibarr backup +tar -czf "$BACKUP_DIR/dolibarr_full_$DATE.tar.gz" /path/to/dolibarr/ + +# Keep 8 weeks +find "$BACKUP_DIR" -mtime +56 -delete +``` + +#### Automated Backup with Cron + +```bash +# Edit crontab +crontab -e + +# Add backup schedules +# Daily backup at 2 AM +0 2 * * * /usr/local/bin/childcare_daily_backup.sh >> /var/log/childcare_backup.log 2>&1 + +# Weekly backup on Sundays at 3 AM +0 3 * * 0 /usr/local/bin/weekly_full_backup.sh >> /var/log/weekly_backup.log 2>&1 +``` + +### Recovery Procedures + +#### Restore from Backup + +```bash +# 1. Stop web server +sudo systemctl stop apache2 # or nginx + +# 2. Restore database +gunzip childcare_db_20260219_020000.sql.gz +mysql -u root -p dolibarr_db < childcare_db_20260219_020000.sql + +# 3. Restore files +tar -xzf childcare_files_20260219_020000.tar.gz -C / + +# 4. Fix permissions +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/childcare/ + +# 5. Restart web server +sudo systemctl start apache2 +``` + +#### Disaster Recovery + +Full system recovery: + +```bash +# 1. Restore Dolibarr +tar -xzf dolibarr_full_20260219.tar.gz -C / + +# 2. Restore full database +mysql -u root -p < full_db_20260219.sql + +# 3. Verify module activation +mysql -u root -p dolibarr_db -e "SELECT * FROM llx_const WHERE name='MAIN_MODULE_CHILDCARE';" + +# 4. Test functionality +# Log in and verify childcare module works +``` + +### Testing Backups + +**Monthly backup testing**: + +```bash +# 1. Restore to test environment +# 2. Verify data integrity +# 3. Test key functions +# 4. Document results +``` + +--- + +## Performance Tuning + +### Database Optimization + +#### Index Optimization + +```sql +-- Check index usage +SELECT + TABLE_NAME, + INDEX_NAME, + CARDINALITY +FROM information_schema.STATISTICS +WHERE TABLE_SCHEMA = 'dolibarr_db' + AND TABLE_NAME LIKE 'llx_childcare%' +ORDER BY TABLE_NAME, INDEX_NAME; + +-- Add missing indexes if needed +ALTER TABLE llx_childcare_attendance +ADD INDEX idx_attendance_child_date (fk_child, attendance_date); +``` + +#### Query Performance + +```sql +-- Analyze slow queries +EXPLAIN SELECT * FROM llx_childcare_attendance +WHERE attendance_date >= DATE_SUB(CURDATE(), INTERVAL 30 DAY); + +-- Optimize tables periodically +OPTIMIZE TABLE llx_childcare_child; +OPTIMIZE TABLE llx_childcare_attendance; +OPTIMIZE TABLE llx_childcare_activity; +``` + +### PHP Configuration + +```ini +# /etc/php/8.1/apache2/php.ini + +memory_limit = 512M +max_execution_time = 300 +post_max_size = 50M +upload_max_filesize = 50M +max_input_vars = 5000 + +# Enable OPcache +opcache.enable=1 +opcache.memory_consumption=256 +opcache.max_accelerated_files=10000 +opcache.revalidate_freq=2 +``` + +### Web Server Optimization + +#### Apache + +```apache +# /etc/apache2/sites-available/dolibarr.conf + + + # Enable compression + AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript + + # Enable caching + + ExpiresActive On + ExpiresByType image/jpg "access plus 1 month" + ExpiresByType image/jpeg "access plus 1 month" + ExpiresByType image/gif "access plus 1 month" + ExpiresByType image/png "access plus 1 month" + ExpiresByType text/css "access plus 1 week" + ExpiresByType application/javascript "access plus 1 week" + + +``` + +#### Nginx + +```nginx +# /etc/nginx/sites-available/dolibarr + +server { + # Enable gzip compression + gzip on; + gzip_types text/css application/javascript text/javascript application/json; + gzip_min_length 1000; + + # Cache static files + location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { + expires 1M; + add_header Cache-Control "public, immutable"; + } +} +``` + +### Monitoring + +#### Database Monitoring + +```sql +-- Monitor table sizes +SELECT + table_name, + ROUND(((data_length + index_length) / 1024 / 1024), 2) AS "Size (MB)" +FROM information_schema.TABLES +WHERE table_schema = 'dolibarr_db' + AND table_name LIKE 'llx_childcare%' +ORDER BY (data_length + index_length) DESC; + +-- Monitor slow queries +SELECT * FROM mysql.slow_log +WHERE sql_text LIKE '%llx_childcare%' +ORDER BY start_time DESC +LIMIT 10; +``` + +--- + +## Troubleshooting + +See detailed [Troubleshooting Guide](troubleshooting.md) for common issues and solutions. + +### Quick Diagnostics + +```bash +# Check module is active +mysql -u user -p database -e "SELECT value FROM llx_const WHERE name='MAIN_MODULE_CHILDCARE';" + +# Check table existence +mysql -u user -p database -e "SHOW TABLES LIKE 'llx_childcare%';" + +# Check file permissions +ls -la /path/to/dolibarr/htdocs/custom/childcare/ + +# Check PHP errors +tail -f /var/log/apache2/error.log +# or +tail -f /var/log/nginx/error.log + +# Check Dolibarr logs +tail -f /path/to/dolibarr/documents/dolibarr.log +``` + +--- + +## Maintenance Tasks + +### Daily Tasks + +- [ ] Monitor backup completion +- [ ] Check error logs for issues +- [ ] Verify system is accessible + +### Weekly Tasks + +- [ ] Review user activity logs +- [ ] Check database performance +- [ ] Test backup restoration +- [ ] Review attendance completion rates + +### Monthly Tasks + +- [ ] Update module (if new version available) +- [ ] Optimize database tables +- [ ] Review and archive old data +- [ ] Generate and review reports +- [ ] Update documentation if needed + +### Quarterly Tasks + +- [ ] Review user permissions +- [ ] Audit security settings +- [ ] Performance review and tuning +- [ ] Disaster recovery drill +- [ ] User training refresher + +--- + +## Support and Resources + +### Documentation +- [Installation Guide](installation.md) +- [User Guide](user-guide.md) +- [Database Schema](database-schema.md) +- [Troubleshooting Guide](troubleshooting.md) + +### External Resources +- [Dolibarr Documentation](https://www.dolibarr.org/doc/) +- [Dolibarr Forum](https://www.dolibarr.org/forum) +- [GitHub Repository](https://github.com/mokoconsulting-tech/MokoDoliCare) + +--- + +## CSV Import for Children + +### Importing Children Records + +The module supports CSV import for bulk enrollment of children records. + +#### Accessing the Import Tool + +1. Navigate to **Home → Import** +2. Select **Import - Children** from the dataset dropdown +3. Download the CSV template + +#### CSV File Format + +The CSV file should contain the following columns: + +| Column | Required | Format | Example | +|--------|----------|--------|---------| +| Ref | Yes | Alphanumeric | CHILD001 | +| FirstName | Yes | Text | Emma | +| LastName | Yes | Text | Smith | +| DateOfBirth | Yes | YYYY-MM-DD | 2020-05-15 | +| Gender | No | Text | Female | +| Allergies | No | Text | Peanuts, dairy | +| MedicalNotes | No | Text | None | +| EmergencyContact | No | Text | Parent: 555-1234 | +| EnrollmentDate | No | YYYY-MM-DD | 2025-01-15 | +| ThirdParty | No | Text | Smith Family | +| Status | No | 0 or 1 | 1 | +| Label | No | Text | Optional label | +| NotePublic | No | Text | Public notes | +| NotePrivate | No | Text | Private notes | + +#### Import Process + +1. **Prepare CSV File**: Create a CSV file with the required columns +2. **Upload File**: Use the import wizard to upload your CSV file +3. **Map Fields**: Verify field mappings (auto-detected from column names) +4. **Validate**: Review validation errors and warnings +5. **Import**: Execute the import +6. **Review Results**: Check import summary and any errors + +#### Example CSV + +```csv +Ref,FirstName,LastName,DateOfBirth,Gender,ThirdParty,Status +CHILD001,Emma,Smith,2020-05-15,Female,Smith Family,1 +CHILD002,Noah,Johnson,2021-03-22,Male,Johnson Family,1 +CHILD003,Olivia,Williams,2019-11-08,Female,Williams Family,1 +``` + +#### Tips for Successful Import + +- Ensure dates are in YYYY-MM-DD format +- Status field: 1 = Active, 0 = Inactive +- ThirdParty field should match existing third party names +- Ref must be unique for each child +- UTF-8 encoding recommended for special characters + +--- + +## Auto-Invoice Generation + +### Overview + +The module can automatically generate invoices for families based on enrolled children and billing periods. + +### Billing Models + +The invoice generation service supports multiple billing models: + +- **Monthly**: Fixed monthly fee per child +- **Weekly**: Weekly billing cycle +- **Daily**: Per-day attendance billing + +### Accessing Invoice Generation + +1. Navigate to **Childcare → Generate Invoices** +2. Choose between: + - **All Families**: Generate invoices for all families with active children + - **Single Family**: Generate invoice for a specific family + +### Generating Invoices + +#### For All Families + +1. Select **Billing Period** (Monthly/Weekly/Daily) +2. Set **Period Start Date** +3. Set **Period End Date** +4. Click **Generate Invoices** + +The system will: +- Find all families with active children +- Create one invoice per family +- Add a line item for each child +- Link invoice to the third party (family) + +#### For a Single Family + +1. Select the **Third Party (Family)** +2. Select **Billing Period** +3. Set **Period Start** and **Period End** dates +4. Click **Generate Invoice** + +### Invoice Line Items + +Each invoice automatically includes: + +**Child-Based Items**: +- One line per active child +- Description includes child's name +- Default rates (configurable): + - Monthly: €800 + - Weekly: €200 + - Daily: €40 + +**Family-Level Items** (optional): +- Registration fees +- Activity fees +- Material fees +- Other services + +### Configuring Billing Rates + +Rates can be customized in the invoice generation code or via configuration. + +Default rates are set in `/services/InvoiceService.php`: + +```php +$default_rates = array( + 'monthly' => 800.00, // Monthly childcare fee + 'daily' => 40.00, // Daily rate + 'weekly' => 200.00 // Weekly rate +); +``` + +### Family Linking + +**Important**: For invoice generation to work, children must be linked to a third party (family): + +1. Edit the child record +2. Set the **Family/Third Party** field +3. Save the record + +Children without a linked third party will not be included in automatic invoice generation. + +### Invoice Workflow + +1. **Generation**: Invoices are created in draft status +2. **Review**: Admin reviews and adjusts if needed +3. **Validation**: Validate invoice to lock it +4. **Payment**: Process payments as usual in Dolibarr + +### Best Practices + +- Run invoice generation at the start of each billing period +- Review generated invoices before validation +- Set up automated reminders for unpaid invoices +- Use consistent billing periods per family +- Document special rates or discounts in invoice notes + +--- + +**Last Updated**: 2026-03-03 +**Version**: 1.2.0-dev +**For**: MokoDoliCare Childcare Management Module + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/changelog.md b/MokoConsulting/MokoDoliCare/changelog.md new file mode 100644 index 0000000..96f30a4 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/changelog.md @@ -0,0 +1,230 @@ +← [Home](Home) + +# Changelog + +All notable changes to MokoDoliCare (Childcare Management Module) will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Planned +- Advanced reporting and analytics dashboard +- Email notifications for parents +- Multi-language support (Spanish, French, German) +- Photo galleries for activities +- Medical records and vaccination tracking +- Meal planning and nutritional tracking +- Invoice generation for childcare fees +- Calendar integration with Google Calendar/Outlook +- Mobile-responsive interface improvements +- REST API endpoints for mobile app integration +- Document management for child records +- Staff scheduling and management +- Emergency alert system + +## [1.2.0] - 2026-03-03 + +### Added +- **Official Module ID Assignment** + - Module ID changed from 600001 (development) to 185065 (official) + - Updated permission IDs to match new module number + - Updated all documentation references + +- **CSV Import Functionality** + - Dolibarr-standard CSV import for children records + - Support for bulk child enrollment + - Field mapping configuration + - Import validation and error handling + +- **Auto-Invoice Generation** + - Automatic invoice creation based on child records + - Family-level billing via third party (fk_soc) linking + - Support for child-based line items + - Additional invoice items at family level + - Configurable billing periods and rates + +### Changed +- Module ID: 600001 → 185065 +- Permission IDs updated to reflect new module number + +### Removed +- Legacy/sample files cleaned up + +## [1.1.0] - 2026-03-03 + +### Added +- **Remote Check-In System** + - Parent/Guardian authentication with username and PIN + - Secure PIN storage using bcrypt hashing + - Tablet-optimized check-in interface + - Digital signature capture using HTML5 Canvas + - Touch-friendly UI with gradient design + - 3-step check-in workflow (authenticate, select action, sign) + - Session-based parent authentication + - Support for multiple parents per child + - Primary contact designation + +- **Payroll Time Clock Functionality** + - Accurate timestamp recording for check-in/check-out + - Parent accountability tracking + - Digital signature storage for both check-in and check-out + - Audit trail showing which parent performed each action + - Query examples for calculating billable hours + +- **Parent Management Interface** + - Parent/guardian CRUD operations + - Parent list view with filtering + - Parent card for creating/editing parent accounts + - Relationship tracking (Mother, Father, Legal Guardian, Other) + - Contact information management (email, phone) + - Username uniqueness validation per entity + +- **Database Schema Updates** + - New table: `llx_childcare_parent` for parent credentials + - Username and PIN hash storage + - Relationship and contact information + - Primary contact flag + - Foreign key to child records + - Updated table: `llx_childcare_attendance` + - Added: `fk_parent_checkin` - tracks parent who checked in + - Added: `fk_parent_checkout` - tracks parent who checked out + - Added: `signature_checkin` - base64-encoded check-in signature + - Added: `signature_checkout` - base64-encoded check-out signature + - Foreign keys linking attendance to parent records + - Indexes for performance on parent lookups + +- **Security Enhancements** + - XSS protection: sanitized form action URLs + - Input validation for signatures (500KB size limit) + - Secure PIN hashing with bcrypt + - System user context for audit trail in public interface + - Session-based authentication for tablet interface + +- **Documentation** + - Comprehensive remote check-in guide (9,000+ words) + - Setup instructions for tablet devices + - Security best practices + - Troubleshooting section + - SQL query examples for payroll reporting + - Updated database schema documentation + - Updated main README with feature highlights + +- **Menu Items** + - Parents submenu with list and create options + - Tablet Check-In menu item (opens in new tab) + - Integration with existing childcare menu structure + +### Changed +- Enhanced attendance tracking with parent accountability +- Updated database schema version to 1.1.0 +- Improved documentation structure with new guides + +### Technical Details +- Added 30+ language translations for remote check-in features +- Implemented HTML5 Canvas-based signature capture +- Touch and mouse event support for signature pad +- Base64 encoding for signature storage +- Password verification using PHP's `password_verify()` +- Session management for tablet check-in workflow + +### Security +- Fixed potential XSS vulnerabilities in form submissions +- Implemented proper input sanitization throughout +- Added signature size validation +- Secure credential storage with industry-standard hashing + +## [1.0.0] - 2025-02-19 + +### Added +- **Child Management System** + - Comprehensive child profiles with personal information + - Date of birth and age tracking + - Gender recording + - Medical notes and allergy documentation + - Emergency contact information + - Enrollment date tracking + - Active/Inactive status management + - Public and private notes + - Integration with Dolibarr user system + +- **Attendance Tracking** + - Daily attendance recording + - Check-in and check-out time tracking + - Attendance status indicators + - Notes for daily activities and observations + - Attendance history by child + - Date-based filtering + - User tracking for who recorded attendance + +- **Activity Management** + - Activity scheduling and planning + - Activity type categorization (Learning, Play, Outdoor, Meals, Naps, Arts, Music, Story Time) + - Description and notes for each activity + - Date and time scheduling + - Status tracking for activities + - Reference system for activity identification + +- **Database Schema** + - `llx_childcare_child` - Child records table + - `llx_childcare_attendance` - Attendance tracking table + - `llx_childcare_activity` - Activity management table + - Foreign key constraints for data integrity + - Proper indexing for performance + - Multi-entity support + +- **Permission System** + - Granular permissions for child records (read, write, delete) + - Attendance permissions (read, write) + - Activity permissions (read, write) + - Role-based access control + - Integration with Dolibarr permission system + +- **User Interface** + - Main dashboard with statistics + - Top menu navigation + - Children submenu with list and create options + - Attendance tracking interface + - Activities management interface + - Responsive design following Dolibarr standards + +- **Documentation** + - Comprehensive README with feature overview + - Installation instructions + - Usage guide + - Database schema documentation + - Module structure documentation + - Language file with all translations (English) + +### Technical Details +- Module ID: 600001 (development range) +- Module Family: Human Resources (hr) +- Module Position: 50 +- Minimum Dolibarr Version: 12.0 +- Minimum PHP Version: 7.4 +- Database Support: MySQL 5.7+, MariaDB 10.3+, PostgreSQL 9.6+ +- License: GPL v3 / MIT +- Icon: FontAwesome child icon (fa-child) + +### Development Setup +- Modular architecture following Dolibarr standards +- PSR-compatible code structure +- Security-first approach with input sanitization +- Database abstraction layer usage +- Translation-ready infrastructure +- Multi-entity support from the ground up + +--- + +[Unreleased]: https://github.com/mokoconsulting-tech/MokoDoliCare/compare/v1.1.0...HEAD +[1.1.0]: https://github.com/mokoconsulting-tech/MokoDoliCare/compare/v1.0.0...v1.1.0 +[1.0.0]: https://github.com/mokoconsulting-tech/MokoDoliCare/releases/tag/v1.0.0 + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/development.md b/MokoConsulting/MokoDoliCare/development.md new file mode 100644 index 0000000..826ffbb --- /dev/null +++ b/MokoConsulting/MokoDoliCare/development.md @@ -0,0 +1,416 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── services/ # Service classes (NEW) +│ ├── README.md # Services documentation +│ ├── ExampleService.php # Service template +│ ├── api/ # API services +│ ├── integrations/ # Third-party integrations +│ └── plugins/ # Plugin services +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - Official Dolibarr module ID + $this->numero = 185065; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. Service Development + +Services encapsulate reusable business logic and provide a clean separation between controllers and business operations. + +#### Creating a Service + +Services are stored in the `services/` directory: + +```php +db = $db; + $this->user = $user; + } + + /** + * Send notification to parent + * + * @param int $parentId Parent ID + * @param string $message Message content + * @return array Result array + */ + public function sendNotification($parentId, $message) + { + try { + // Business logic here + return array( + 'success' => true, + 'data' => array('sent' => true) + ); + } catch (Exception $e) { + return array( + 'success' => false, + 'message' => $e->getMessage() + ); + } + } +} +``` + +#### Using a Service + +Include and use services in your pages: + +```php +sendNotification($parentId, $message); + +if ($result['success']) { + setEventMessages($langs->trans("NotificationSent"), null, 'mesgs'); +} +``` + +#### Service Best Practices + +1. **Return consistent formats**: Always return arrays with `success`, `data`, and `message` keys +2. **Inject dependencies**: Pass required objects through constructor +3. **Handle errors properly**: Use try-catch blocks and log errors +4. **Document methods**: Use PHPDoc format for all public methods +5. **Keep services focused**: Each service should have a single, well-defined purpose + +See the [Services README](src-services-README) for comprehensive documentation and examples. + +### 7. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Official Module ID + +For public distribution, use your officially assigned module ID: + +```php +$this->numero = 185065; // MokoDoliCare official ID +``` + +### Development Phase + +For testing new features, you may use development IDs > 600,000: + +```php +$this->numero = 600001; // For development only +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/family-management.-.-.md b/MokoConsulting/MokoDoliCare/family-management.-.-.md new file mode 100644 index 0000000..8e5aec7 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/family-management.-.-.md @@ -0,0 +1,291 @@ +← [Home](Home) + +# Family Management Guide + +## Overview + +The MokoDoliCare module uses Dolibarr's Third Party (Societe) system to manage families. Each child can be linked to a **Family** third party, which serves as a grouping mechanism for siblings and shared billing/communication. + +## What is a Family? + +A **Family** is a special type of third party in Dolibarr that represents a household or family unit. By linking children to families, you can: + +- **Group siblings together** under one family unit +- **Shared billing** - Invoice the family for multiple children +- **Consolidated communication** - Send reports and notifications to the family +- **Family contacts** - Manage multiple parent/guardian contacts under one family +- **Simplified administration** - Update family information once for all children + +## Creating a Family + +### Method 1: During Child Creation + +1. Navigate to **Childcare → Children → New Child** +2. Fill in the child's basic information +3. In the **Family Name** field, click the **+ icon** (plus sign) +4. You'll be redirected to create a new third party: + - **Third Party Name**: Enter the family name (e.g., "Smith Family", "Johnson Family") + - **Third Party Type**: Select appropriate type or leave default + - Add family address, phone, email + - Add contacts (parents/guardians) under the Contacts tab +5. Save the third party +6. Return to the child creation form (it will be pre-selected) +7. Complete and save the child record + +### Method 2: Create Family First + +1. Navigate to **Third Parties → New Third Party** +2. Create the family: + - **Name**: Family name (e.g., "Martinez Family") + - **Type**: Customer, Prospect, or Neither (recommended: Neither for families) + - **Address**: Family home address + - **Phone/Email**: Primary family contact information +3. Add parent/guardian contacts: + - Go to the **Contacts/Addresses** tab + - Click **Add Contact** + - Enter parent/guardian information + - Assign appropriate role (e.g., "Parent", "Guardian", "Emergency Contact") +4. Save the family + +5. Then create children linked to this family: + - Navigate to **Childcare → Children → New Child** + - Select the family from the **Family Name** dropdown + - Complete child information + +## Best Practices + +### Naming Conventions + +Use consistent naming for families: + +**Recommended formats:** +- `[LastName] Family` - e.g., "Johnson Family" +- `[Parent1] and [Parent2] [LastName]` - e.g., "John and Mary Smith" +- `The [LastName] Family` - e.g., "The Garcia Family" + +**Avoid:** +- Using individual parent names only (e.g., "John Smith") - use "Smith Family" instead +- Special characters or abbreviations +- Temporary or placeholder names + +### Family Structure + +For each family, set up: + +1. **Primary Contact**: Main parent/guardian for billing and communication +2. **Secondary Contact**: Second parent/guardian +3. **Emergency Contacts**: Additional authorized pickup persons +4. **Billing Address**: Where invoices should be sent +5. **Email**: For digital communications and notifications + +### Multiple Families + +Some children may have separated parents or complex custody arrangements: + +**Option 1: Single Family (Recommended for most cases)** +- Create one family representing the primary household +- Add both parents as contacts with appropriate roles +- Use contact notes to document custody arrangements + +**Option 2: Multiple Records** +- For complex custody situations, you may create duplicate child records +- Link each to a different family (one for each household) +- Use status or notes to indicate which is primary + +**Option 3: Shared Custody** +- Create one family, add both parents as primary contacts +- Document custody schedule in child notes +- Use custom fields if available for detailed tracking + +## Linking Children to Families + +### During Child Creation + +Simply select the family from the **Family Name** dropdown when creating a new child. + +### Updating Existing Children + +If you need to add family links to existing children: + +1. Open the child's card +2. Click **Edit** (modify) +3. Select the family from the **Family Name** dropdown +4. Save changes + +**Note**: This feature requires running the database migration script. See [Migration Instructions](#migration-instructions) below. + +## Family Reports and Views + +### Viewing Family Children + +1. Navigate to **Third Parties → Third Party List** +2. Find and open the family +3. View linked children in the childcare module section (if configured) + +### Filtering by Family + +In the children list: +1. Use filters to show children by family +2. Sort by family name to group siblings together + +## Billing Families + +Link invoices to the family third party: + +1. Navigate to **Customers/Prospects → New Invoice** +2. Select the **Family** as the third party +3. Add line items for each child's services +4. Use product references to indicate which child (e.g., "Childcare - Emma Smith") +5. Send invoice to family contact + +**Best Practice**: Create separate invoice lines for each child to provide clear breakdowns. + +## Communication with Families + +### Email Notifications + +Configure email notifications to go to family contacts: +- Check-in/check-out confirmations +- Monthly attendance summaries +- Activity updates +- Billing reminders + +### Parent Portal Access + +If using the parent portal: +- Assign login credentials to family contacts +- Parents can view all children in their family +- Shared document access for family + +## Migration Instructions + +### For New Installations + +The family field (`fk_soc`) is included automatically in the child table when you install the module. + +### For Existing Installations + +If you installed the module before the family feature was added, run the migration script: + +```sql +-- Run this SQL script on your database +-- File: sql/llx_childcare_child_add_family.sql + +ALTER TABLE llx_childcare_child ADD COLUMN fk_soc integer DEFAULT NULL AFTER entity; +ALTER TABLE llx_childcare_child ADD INDEX idx_childcare_child_fk_soc (fk_soc); +ALTER TABLE llx_childcare_child ADD CONSTRAINT fk_childcare_child_soc +FOREIGN KEY (fk_soc) REFERENCES llx_societe(rowid); +``` + +**How to run:** + +1. Backup your database first! +2. Access your database via phpMyAdmin, MySQL CLI, or other tool +3. Execute the SQL commands from `sql/llx_childcare_child_add_family.sql` +4. Verify the column was added: `DESCRIBE llx_childcare_child;` +5. Refresh your Dolibarr interface + +## Troubleshooting + +### "Family Name dropdown is empty" + +**Cause**: No third parties exist in your database +**Solution**: Create at least one third party (family) first + +### "Can't save child with family selected" + +**Cause**: Database migration not run or foreign key constraint issue +**Solution**: +1. Check if `fk_soc` column exists in `llx_childcare_child` table +2. Run migration script if needed +3. Verify the selected family exists in `llx_societe` table + +### "Family link disappeared after saving" + +**Cause**: Form submission not including the `socid` parameter +**Solution**: Check the form processing logic in your page + +### "How do I unlink a child from a family?" + +**Solution**: +1. Edit the child record +2. Select the blank option in the Family Name dropdown +3. Save + +## Advanced Usage + +### Custom Family Types + +You can configure Dolibarr to use a custom third party type for families: + +1. Go to **Setup → Dictionaries → Third Party Types** +2. Add a new type: "Family" with code `family` +3. Modify the family selector to filter by this type + +### Family Custom Fields + +Add extra fields to families via Dolibarr's extrafields: + +1. Go to **Setup → Extra Fields** +2. Select **Third Parties** +3. Add custom fields: + - Number of children enrolled + - Preferred communication method + - Billing cycle preference + - Special notes or requirements + +### Integration with Dolibarr Modules + +Families work seamlessly with other Dolibarr features: + +- **Invoicing**: Bill families for childcare services +- **Proposals**: Send enrollment proposals to families +- **Contracts**: Create service contracts with families +- **Contacts**: Manage multiple parents/guardians +- **Agenda**: Schedule meetings and events with families +- **Documents**: Share documents with family contacts + +## Frequently Asked Questions + +**Q: Do I have to use families?** +A: No, the family field is optional. Children can exist without a family link. + +**Q: Can a child belong to multiple families?** +A: No, each child can only be linked to one family at a time. For split custody, see [Multiple Families](#multiple-families). + +**Q: What type should I use for family third parties?** +A: You can use any type. Common choices: +- **Neither customer nor prospect** (type 0) - For families not involved in other business +- **Customer** (type 1) - If you invoice them for childcare services +- Create a custom "Family" type in dictionaries + +**Q: Can I bill families automatically?** +A: Future versions will include automatic invoice generation. For now, manually create invoices linked to the family third party. + +**Q: How do I export family data?** +A: Use Dolibarr's export tool: +1. **Tools → Export** +2. Select **Third Parties** and **Children** +3. Include family name fields +4. Export to CSV or Excel + +## Related Documentation + +- [User Guide](user-guide.md) - General module usage +- [Database Schema](database-schema.md) - Technical field reference +- [Development Guide](development.md) - For developers integrating family features +- [Dolibarr Third Party Documentation](https://wiki.dolibarr.org/index.php/Third_parties_/_Customers_/_Prospects) + +--- + +**Version**: 1.1.0 +**Last Updated**: March 2026 +**Module**: MokoDoliCare Childcare Management + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/installation.md b/MokoConsulting/MokoDoliCare/installation.md new file mode 100644 index 0000000..9533b85 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/installation.md @@ -0,0 +1,469 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring the MokoDoliCare Childcare Management Module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 12.0 or higher +- **PHP**: Version 7.4 or higher (8.0+ recommended) +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql (database connectivity) + - gd or imagick (image processing) + - curl (external communications) + - json (JSON handling) + - xml (XML processing) + - mbstring (multi-byte string support) + +## Installation Steps + +### Method 1: Installation from ZIP File (Recommended) + +If you have a ready-to-deploy ZIP file (e.g., `module_childcare-1.0.0.zip`): + +1. **Log in** to Dolibarr as an administrator +2. Navigate to **Home → Setup → Modules → Deploy External Module** +3. Click **Browse** and select the ZIP file +4. Click **Upload** +5. Wait for the upload and extraction to complete +6. The module will appear in the modules list + +### Method 2: Installation from Git Repository + +For development or latest version: + +```bash +# Navigate to Dolibarr's custom directory +cd /path/to/dolibarr/htdocs/custom/ + +# Clone the repository +git clone https://github.com/mokoconsulting-tech/MokoDoliCare.git childcare + +# Copy module files from src/ directory +cp -r childcare/src/* childcare/ + +# Set proper permissions +chown -R www-data:www-data childcare/ +find childcare/ -type d -exec chmod 755 {} \; +find childcare/ -type f -exec chmod 644 {} \; +``` + +### Method 3: Manual Installation from Extracted Files + +```bash +# Extract module files to custom directory +unzip module_childcare-1.0.0.zip -d /path/to/dolibarr/htdocs/custom/childcare/ + +# Set ownership (adjust user:group for your system) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/childcare/ + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/childcare/ -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/childcare/ -type f -exec chmod 644 {} \; +``` + +## Activating the Module + +After installation files are in place: + +1. **Log in** to Dolibarr as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. In the search box, type **"Childcare"** +4. Find **"Childcare Management"** in the list +5. Click the **Activate** toggle button +6. Wait for confirmation: "Module activated successfully" + +### Verify Installation + +After activation, verify the module is working: + +1. **Check Menu**: You should see **"Childcare"** in the top navigation menu +2. **Check Tables**: Database tables should be created automatically + ```sql + SHOW TABLES LIKE 'llx_childcare%'; + ``` + Expected: `llx_childcare_child`, `llx_childcare_attendance`, `llx_childcare_activity` + +3. **Check Module Status**: + ```sql + SELECT value FROM llx_const WHERE name = 'MAIN_MODULE_CHILDCARE'; + ``` + Expected: `1` (active) + +## Post-Installation Configuration + +### 1. Configure User Permissions + +Set up permissions for your staff: + +1. Go to **Home → Users & Groups → Users** +2. Click on a user name +3. Go to the **Permissions** tab +4. Under **Childcare** section, enable appropriate permissions: + - **Read child records** - View child information + - **Create/Edit child records** - Add and modify children + - **Delete child records** - Remove child records (admins only) + - **Read attendance** - View attendance records + - **Create/Edit attendance** - Record attendance + - **Read activities** - View activities + - **Create/Edit activities** - Manage activities +5. Click **Save** + +### 2. Module Settings (Optional) + +Configure module options: + + +1. Navigate to **Home → Setup → Modules → Childcare Management → Setup** +2. Configure options as needed (configuration interface may be minimal in v1.0.0) +3. Save changes + +### 3. Test Functionality + +Verify the module works correctly: + +1. **Create a Test Child**: + - Go to **Childcare → Children → New Child** + - Fill in required fields (First Name, Last Name, Date of Birth) + - Click **Create** + - Verify child appears in list + +2. **Record Test Attendance**: + - Go to **Childcare → Attendance → New Record** + - Select the test child + - Enter today's date and check-in time + - Click **Save** + - Verify record appears + +3. **Create Test Activity**: + - Go to **Childcare → Activities → New Activity** + - Fill in Label, Date + - Click **Create** + - Verify activity appears in schedule + +## Database Setup + +### Automatic Setup (Default) + +The module automatically creates database tables when activated. Tables created: + +- `llx_childcare_child` - Child records +- `llx_childcare_attendance` - Attendance tracking +- `llx_childcare_activity` - Activity management + +### Manual Setup (If Automatic Fails) + +If tables aren't created automatically: + +```bash +cd /path/to/dolibarr/htdocs/custom/childcare/sql/ + +# Create tables +mysql -u username -p database_name < llx_childcare_child.sql +mysql -u username -p database_name < llx_childcare_attendance.sql +mysql -u username -p database_name < llx_childcare_activity.sql + +# Create indexes and foreign keys +mysql -u username -p database_name < llx_childcare_child.key.sql +mysql -u username -p database_name < llx_childcare_attendance.key.sql +mysql -u username -p database_name < llx_childcare_activity.key.sql +``` + +### Verify Database Setup + +```sql +-- Check tables exist +SHOW TABLES LIKE 'llx_childcare%'; + +-- Check table structure +DESCRIBE llx_childcare_child; +DESCRIBE llx_childcare_attendance; +DESCRIBE llx_childcare_activity; + +-- Verify foreign keys +SELECT CONSTRAINT_NAME, TABLE_NAME, REFERENCED_TABLE_NAME +FROM information_schema.KEY_COLUMN_USAGE +WHERE TABLE_SCHEMA = 'your_database_name' + AND TABLE_NAME LIKE 'llx_childcare%' + AND REFERENCED_TABLE_NAME IS NOT NULL; +``` + + +## Troubleshooting + +### Module Not Appearing + +**Problem**: Can't find "Childcare Management" in module list + +**Solutions**: + +1. **Clear Cache**: + ```bash + rm -rf /path/to/dolibarr/documents/install.lock + ``` + Then refresh browser (Ctrl+Shift+R) + +2. **Check File Location**: + ```bash + ls -la /path/to/dolibarr/htdocs/custom/childcare/core/modules/modMokoDoliCare.class.php + ``` + File must exist + +3. **Check Permissions**: + ```bash + # Files should be readable by web server + chmod 644 /path/to/dolibarr/htdocs/custom/childcare/core/modules/modMokoDoliCare.class.php + ``` + +4. **Check PHP Syntax**: + ```bash + php -l /path/to/dolibarr/htdocs/custom/childcare/core/modules/modMokoDoliCare.class.php + ``` + Should show "No syntax errors" + +### Permission Errors + +**Problem**: "Access Forbidden" or can't access files + +**Solutions**: + +1. **Fix File Ownership**: + ```bash + chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/childcare/ + ``` + +2. **Fix File Permissions**: + ```bash + find /path/to/dolibarr/htdocs/custom/childcare/ -type d -exec chmod 755 {} \; + find /path/to/dolibarr/htdocs/custom/childcare/ -type f -exec chmod 644 {} \; + ``` + +3. **Check SELinux** (if applicable): + ```bash + # Temporarily disable to test + setenforce 0 + ``` + +### Database Errors + +**Problem**: Tables not created or database errors + +**Solutions**: + +1. **Check Database User Permissions**: + ```sql + SHOW GRANTS FOR 'dolibarr_user'@'localhost'; + ``` + User needs: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP + +2. **Manually Create Tables**: See [Manual Setup](#manual-setup-if-automatic-fails) above + +3. **Check Database Connection**: + ```bash + mysql -u dolibarr_user -p dolibarr_db -e "SELECT 1;" + ``` + +### Module Activates But Doesn't Work + +**Problem**: Module active but menu doesn't appear or features don't work + +**Solutions**: + +1. **Check User Permissions**: + - User must have at least "Read" permission + - Go to **Users & Groups → [User] → Permissions** + - Enable Childcare permissions + +2. **Clear All Caches**: + ```bash + # Server cache + rm -rf /path/to/dolibarr/documents/install.lock + + # Browser cache + # Press Ctrl+Shift+Del and clear cache + ``` + +3. **Check Error Logs**: + ```bash + tail -f /var/log/apache2/error.log + # or + tail -f /var/log/nginx/error.log + # and + tail -f /path/to/dolibarr/documents/dolibarr.log + ``` + +## Advanced Configuration + +### Multi-Entity Setup + +For managing multiple childcare facilities: + +1. **Enable Multi-Entity** in Dolibarr: + - Home → Setup → Other Setup → Multi-entity + - Enable multi-entity mode + +2. **Create Entities**: + - Home → Setup → Entities → New Entity + - Create entity for each facility + +3. **Assign Users to Entities**: + - Home → Users & Groups → [User] → Entity tab + - Select appropriate entities + +4. **Data Separation**: Each entity will have separate children, attendance, and activities + +### Custom Configuration Constants + +Add custom configuration: + +```sql +-- Example: Set default child status +INSERT INTO llx_const (name, value, type, note, entity) +VALUES ('CHILDCARE_DEFAULT_STATUS', '1', 'chaine', 'Default child status (1=Active)', 1); + +-- Example: Enable auto-reference generation +INSERT INTO llx_const (name, value, type, note, entity) +VALUES ('CHILDCARE_AUTO_REF', '1', 'chaine', 'Auto-generate references', 1); +``` + + +## Uninstallation + +To remove the module: + +### Step 1: Deactivate Module + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find "Childcare Management" and click **Deactivate** +3. Confirm deactivation + +### Step 2: Remove Files (Optional) + +```bash +# Backup first! +tar -czf childcare_backup.tar.gz /path/to/dolibarr/htdocs/custom/childcare/ + +# Remove module directory +rm -rf /path/to/dolibarr/htdocs/custom/childcare/ +``` + +### Step 3: Remove Database Tables (Optional) + +**Warning**: This permanently deletes all childcare data! + +```bash +# Backup database first! +mysqldump -u user -p database_name \ + llx_childcare_child \ + llx_childcare_attendance \ + llx_childcare_activity > childcare_backup.sql + +# Then drop tables +mysql -u user -p database_name << EOF +DROP TABLE IF EXISTS llx_childcare_attendance; +DROP TABLE IF EXISTS llx_childcare_activity; +DROP TABLE IF EXISTS llx_childcare_child; +EOF +``` + +### Step 4: Remove Configuration (Optional) + +```sql +-- Remove module constants +DELETE FROM llx_const WHERE name LIKE '%CHILDCARE%'; + +-- Remove module permissions +DELETE FROM llx_user_rights WHERE fk_id >= 60000101 AND fk_id <= 60000107; +``` + +## Upgrading + +### From Version X.X to Version Y.Y + +1. **Backup Everything**: + ```bash + # Backup files + tar -czf childcare_files_backup.tar.gz /path/to/dolibarr/htdocs/custom/childcare/ + + # Backup database + mysqldump -u user -p database llx_childcare_child llx_childcare_attendance llx_childcare_activity > backup.sql + ``` + +2. **Deactivate Module**: + - Home → Setup → Modules → Childcare → Deactivate + +3. **Update Files**: + ```bash + cd /path/to/dolibarr/htdocs/custom/childcare/ + git pull origin main + # or extract new version ZIP + ``` + +4. **Reactivate Module**: + - Home → Setup → Modules → Childcare → Activate + - Database migrations run automatically + +5. **Verify**: + - Test key functionality + - Check for errors in logs + - Verify data integrity + +## System Requirements Check + +Run this checklist before installation: + +```bash +# PHP version (should be 7.4+) +php -v + +# Required PHP extensions +php -m | grep -E "mysqli|pdo|gd|curl|json|xml|mbstring" + +# Database connectivity +mysql -u dolibarr_user -p -e "SELECT VERSION();" + +# Disk space (need at least 100MB free) +df -h /path/to/dolibarr/ + +# Directory writable +touch /path/to/dolibarr/htdocs/custom/test && rm /path/to/dolibarr/htdocs/custom/test && echo "Writable" || echo "Not writable" +``` + +## Next Steps + +After successful installation: + +1. ⚡ **Quick Start**: Follow the [Quick Start Guide](quick-start.md) for 10-minute setup +2. 📖 **Learn Features**: Read the [User Guide](user-guide.md) for complete documentation +3. 🔧 **Configure**: See [Admin Guide](admin-guide.md) for advanced configuration +4. 👥 **Set Up Users**: Configure permissions for all staff members +5. 📝 **Add Data**: Start adding children, recording attendance, and scheduling activities + +## Need Help? + +- 📖 **Documentation**: [docs/README.md](README.md) +- 🛠️ **Troubleshooting**: [troubleshooting.md](troubleshooting.md) +- 🐛 **Report Issues**: [GitHub Issues](https://github.com/mokoconsulting-tech/MokoDoliCare/issues) +- 💬 **Community**: [Dolibarr Forum](https://www.dolibarr.org/forum) +- 🏢 **Professional Support**: [Moko Consulting](https://mokoconsulting.tech) + +--- + +**Last Updated**: 2026-02-19 +**Version**: 1.0.0 +**For**: MokoDoliCare Childcare Management Module + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/module-id-policy.-.-.md b/MokoConsulting/MokoDoliCare/module-id-policy.-.-.md new file mode 100644 index 0000000..8db3be2 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/quick-start.-.-.md b/MokoConsulting/MokoDoliCare/quick-start.-.-.md new file mode 100644 index 0000000..9649b15 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/quick-start.-.-.md @@ -0,0 +1,402 @@ +← [Home](Home) + +# Quick Start Guide + +Get up and running with MokoDoliCare in 10 minutes. This guide walks you through the essential steps to start managing your childcare facility. + +## Prerequisites + +Before you begin, ensure: +- ✅ Dolibarr 12.0+ is installed and running +- ✅ You have administrator access to Dolibarr +- ✅ The MokoDoliCare module is installed (see [Installation Guide](installation.md)) + +## Step 1: Activate the Module (2 minutes) + +1. **Log in** to Dolibarr as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. In the search box, type "Childcare" +4. Find **"Childcare Management"** in the list +5. Click the **toggle/activate button** next to it +6. Wait for confirmation message: "Module activated successfully" + +✅ **Success Check**: You should now see "Childcare" in the top navigation menu. + +--- + +## Step 2: Configure Permissions (3 minutes) + +Set up user permissions for your staff. + +### For Administrators + +1. Go to **Home → Users & Groups → Users** +2. Click on a user name +3. Go to the **Permissions** tab +4. Under **Childcare** section, enable: + - ✅ **Read child records** + - ✅ **Create/Edit child records** + - ✅ **Delete child records** + - ✅ **Read attendance** + - ✅ **Create/Edit attendance** + - ✅ **Read activities** + - ✅ **Create/Edit activities** +5. Click **Save** + +### For Regular Staff + +Enable only necessary permissions: +- ✅ Read child records +- ✅ Read/Create attendance +- ✅ Read activities + +### Permission Quick Reference + +| Role | Child Records | Attendance | Activities | +|------|---------------|------------|------------| +| **Administrator** | Read/Write/Delete | Read/Write | Read/Write | +| **Lead Teacher** | Read/Write | Read/Write | Read/Write | +| **Teacher** | Read | Read/Write | Read | +| **Office Staff** | Read/Write | Read | Read | + +--- + +## Step 3: Add Your First Child (2 minutes) + +Let's create a child record. + +1. Click **Childcare** in the top menu +2. Select **Children → New Child** +3. Fill in the required fields: + + **Basic Information:** + - **Reference**: `CHILD001` (auto-generated if left blank) + - **First Name**: `Emma` + - **Last Name**: `Johnson` + - **Date of Birth**: `2020-03-15` (use date picker) + - **Gender**: `Female` + + **Important Information:** + - **Allergies**: `Peanut allergy (severe - EpiPen required)` + - **Medical Notes**: `Asthma - uses inhaler as needed` + - **Emergency Contact**: `Sarah Johnson (Mother) - (555) 123-4567` + - **Enrollment Date**: `2023-09-01` + + **Status:** + - **Status**: `Active` (checked) + +4. Click **Create** + +✅ **Success Check**: You should see the child's card page with all entered information. + +### Quick Tips for Child Records + +- 📝 **Reference numbers** help identify children quickly. Use a consistent format like `CHILD001`, `CHILD002`, etc. +- 🚨 **Emergency contacts** are critical. Always include phone numbers and relationships. +- 💊 **Allergies and medical notes** should be detailed and specific. +- 📅 **Date of Birth** is used to calculate age automatically. + +--- + +## Step 4: Record Attendance (2 minutes) + +Track when children check in and out. + +1. From the top menu: **Childcare → Attendance** +2. Click **New Attendance Record** +3. Fill in the form: + - **Child**: Select `Emma Johnson` from dropdown + - **Date**: Today's date (default) + - **Check-in Time**: `08:30 AM` + - **Check-out Time**: `03:30 PM` (can be left blank if child is still present) + - **Status**: `Present` + - **Notes**: `Had a great day. Ate all lunch. Participated in painting activity.` +4. Click **Save** + +✅ **Success Check**: The attendance record appears in the list. + +### Attendance Recording Tips + +- ⏰ **Check-in time** can be recorded immediately when child arrives +- ⏰ **Check-out time** can be added later when child is picked up +- 📝 **Daily notes** help parents stay informed about their child's day +- 📊 **Status** options: Present (1), Absent (0), Partial attendance (2) + +### Quick Attendance Workflow + +``` +Morning: +1. Child arrives → Record check-in time +2. Add any morning notes (mood, items brought, etc.) + +Afternoon: +3. Throughout day → Update notes (meals, activities, behavior) +4. Child departs → Record check-out time +5. Add final notes for parents +``` + +--- + +## Step 5: Schedule an Activity (1 minute) + +Plan activities for your children. + +1. Go to **Childcare → Activities** +2. Click **New Activity** +3. Complete the form: + - **Reference**: `ACT-2026-02-19-001` (or auto-generate) + - **Label**: `Morning Circle Time` + - **Description**: `Group circle time with songs, weather, and calendar` + - **Date**: Today's date + - **Time**: `09:00 AM` + - **Activity Type**: `Learning` + - **Status**: `Scheduled` +4. Click **Create** + +✅ **Success Check**: Activity appears in today's schedule. + +### Activity Types Reference + +| Type | Use For | Examples | +|------|---------|----------| +| **Learning** | Educational activities | ABC, numbers, shapes, colors | +| **Play** | Free or structured play | Toys, games, building blocks | +| **Outdoor** | Outside time | Playground, nature walk, sports | +| **Meals** | Eating times | Breakfast, lunch, snacks | +| **Naps** | Rest time | Afternoon nap, quiet time | +| **Arts** | Creative activities | Painting, drawing, crafts | +| **Music** | Musical activities | Singing, instruments, dancing | +| **Story Time** | Reading | Books, storytelling circle | + +--- + +## Common Daily Workflows + +### Morning Routine + +``` +1. Review today's attendance list +2. Record check-ins as children arrive +3. Check activity schedule for the day +4. Update any last-minute schedule changes +``` + +### During the Day + +``` +1. Update attendance notes throughout the day +2. Mark activities as completed +3. Document any incidents or special observations +4. Take photos (future feature - manual for now) +``` + +### End of Day + +``` +1. Record all check-out times +2. Complete daily notes for each child +3. Review tomorrow's activity schedule +4. Prepare any parent communications needed +``` + +--- + +## Quick Navigation Guide + +### Top Menu Structure + +``` +Childcare +├── Dashboard (overview and statistics) +├── Children +│ ├── List (view all children) +│ └── New Child (add new record) +├── Attendance +│ ├── Today's Attendance +│ ├── Attendance History +│ └── New Attendance Record +└── Activities + ├── Activity Schedule + └── New Activity +``` + +### Keyboard Shortcuts + +- `Alt+N` - Quick new record (when on list page) +- `Alt+S` - Save current form +- `Alt+C` - Cancel and return to list +- `Esc` - Close current dialog + +--- + +## Sample Data Scenarios + +### Scenario 1: Part-Time Child + +For a child who only attends certain days: + +1. Create child record with enrollment date +2. Only record attendance on days they attend +3. Leave check-out time blank if they're still present +4. Use Status = "Partial" for half-days + +### Scenario 2: Child With Allergies + +Critical information to document: + +1. **Allergies field**: List all allergies with severity +2. **Medical Notes**: Include emergency procedures +3. **Emergency Contact**: Ensure parent contact is accurate +4. **Public Notes**: Add reminder visible to all staff: "CHECK ALLERGY LIST" + +### Scenario 3: Daily Activity Planning + +Planning a full day of activities: + +``` +09:00 - Morning Circle (Learning) +09:30 - Free Play (Play) +10:00 - Snack Time (Meals) +10:30 - Outdoor Play (Outdoor) +11:30 - Art Project (Arts) +12:00 - Lunch (Meals) +12:30 - Nap Time (Naps) +14:30 - Story Time (Story Time) +15:00 - Music and Movement (Music) +15:30 - Pick-up time +``` + +--- + +## Troubleshooting Quick Fixes + +### Can't See Childcare Menu + +**Problem**: Childcare doesn't appear in top menu +**Solution**: +1. Check module is activated (Home → Setup → Modules) +2. Verify you have at least "Read" permission +3. Refresh your browser (Ctrl+F5) + +### Can't Create New Records + +**Problem**: "Create" button is grayed out or missing +**Solution**: +1. Check your permissions (need "Write" permission) +2. Ensure you're logged in as correct user +3. Contact administrator to grant permissions + +### Child Not Appearing in Attendance Dropdown + +**Problem**: Can't find child when recording attendance +**Solution**: +1. Verify child status is "Active" +2. Check child record was saved properly +3. Refresh the page +4. Verify you're in the correct entity (multi-entity installations) + +### Times Not Saving Correctly + +**Problem**: Check-in/out times showing wrong time +**Solution**: +1. Check Dolibarr server timezone settings +2. Use 24-hour format (HH:MM) +3. Ensure time is in valid format +4. Check browser timezone matches server + +--- + +## Next Steps + +Now that you're up and running, explore these features: + +### Week 1 Goals +- [ ] Add all currently enrolled children +- [ ] Set up user permissions for all staff +- [ ] Record attendance for 3 consecutive days +- [ ] Create a week's worth of activity schedules + +### Week 2 Goals +- [ ] Review attendance reports +- [ ] Update any missing medical information +- [ ] Establish daily workflow patterns +- [ ] Train all staff on the system + +### Month 1 Goals +- [ ] Generate first monthly reports +- [ ] Fine-tune activity types for your facility +- [ ] Establish backup procedures +- [ ] Gather feedback from staff + +--- + +## Getting Help + +### Documentation Resources + +- 📖 [User Guide](user-guide.md) - Detailed feature documentation +- 🔧 [Admin Guide](admin-guide.md) - System configuration and management +- 💾 [Database Schema](database-schema.md) - Technical database details +- 🛠️ [Troubleshooting](troubleshooting.md) - Common issues and solutions + +### Support Channels + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: Community support for general questions +- **Documentation**: Check this guide and other docs first + +### Training Resources + +- Watch video tutorials (coming soon) +- Download user manual PDF (coming soon) +- Schedule training session with administrator + +--- + +## Quick Reference Card + +Print this for your desk: + +``` +╔══════════════════════════════════════════════════════════╗ +║ MokoDoliCare Quick Reference ║ +╠══════════════════════════════════════════════════════════╣ +║ NEW CHILD: Childcare → Children → New Child ║ +║ ATTENDANCE: Childcare → Attendance → New Record ║ +║ ACTIVITY: Childcare → Activities → New Activity ║ +║ ║ +║ REQUIRED FIELDS: ║ +║ • Child: First/Last Name, Date of Birth ║ +║ • Attendance: Child, Date ║ +║ • Activity: Label, Date ║ +║ ║ +║ EMERGENCY INFO: ║ +║ Always include: Contact Name, Phone, Relationship ║ +║ ║ +║ DAILY CHECKLIST: ║ +║ ☐ Record morning check-ins ║ +║ ☐ Update daily notes ║ +║ ☐ Record check-outs ║ +║ ☐ Review tomorrow's schedule ║ +╚══════════════════════════════════════════════════════════╝ +``` + +--- + +**Congratulations!** 🎉 You're now ready to use MokoDoliCare to manage your childcare facility efficiently. + +**Next**: Read the [User Guide](user-guide.md) for complete feature documentation. + +--- + +**Last Updated**: 2026-02-19 +**Version**: 1.0.0 +**Estimated Time**: 10 minutes + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/remote-checkin.-.-.md b/MokoConsulting/MokoDoliCare/remote-checkin.-.-.md new file mode 100644 index 0000000..8dd1c58 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/remote-checkin.-.-.md @@ -0,0 +1,316 @@ +← [Home](Home) + +# Remote Check-In and Payroll Time Clock Feature + +## Overview + +The Remote Check-In feature enables parents/guardians to independently sign their children in and out using a tablet interface at the childcare facility. This eliminates the need for staff to manually record every check-in/check-out, streamlining the attendance process while maintaining accurate records with digital signatures. + +## Key Features + +### 1. Parent/Guardian Authentication +- Each parent/guardian has a unique username and PIN (4-6 digits) +- PIN is securely hashed using PHP's password_hash() function +- Multiple parents can be associated with a single child +- Primary contact designation + +### 2. Tablet Check-In Interface +- Full-screen, tablet-optimized interface +- Simple 3-step process: + 1. Parent enters username and PIN + 2. Parent selects Check-In or Check-Out + 3. Parent signs on touchscreen +- Beautiful gradient design optimized for tablets +- Touch-friendly buttons and signature pad + +### 3. Digital Signature Capture +- Canvas-based signature pad +- Touch and mouse support +- Signatures stored as base64-encoded images +- Separate signatures for check-in and check-out + +### 4. Attendance Tracking +- Automatic timestamp recording +- Links attendance to specific parent who performed the action +- Stores digital signatures with each transaction +- Prevents duplicate check-ins/check-outs + +### 5. Payroll Time Clock +- Accurate time tracking with check-in/check-out timestamps +- Parent accountability through signature requirements +- Audit trail showing which parent performed each action +- Can be used to calculate hours for billing purposes + +## Database Schema + +### New Table: llx_childcare_parent + +Stores parent/guardian information and credentials: + +| Field | Type | Description | +|-------|------|-------------| +| rowid | integer | Primary key | +| entity | integer | Multi-entity support | +| fk_child | integer | Foreign key to child | +| firstname | varchar(128) | Parent's first name | +| lastname | varchar(128) | Parent's last name | +| email | varchar(255) | Contact email | +| phone | varchar(50) | Contact phone | +| relationship | varchar(50) | Relationship to child | +| username | varchar(50) | Unique username for check-in | +| pin_hash | varchar(255) | Hashed PIN | +| is_primary | integer | Primary contact flag | +| status | integer | Active/Inactive status | + +### Updated Table: llx_childcare_attendance + +Added fields for remote check-in: + +| Field | Type | Description | +|-------|------|-------------| +| fk_parent_checkin | integer | Parent who checked in | +| fk_parent_checkout | integer | Parent who checked out | +| signature_checkin | text | Check-in signature (base64) | +| signature_checkout | text | Check-out signature (base64) | + +## Setup Instructions + +### 1. Enable the Module + +After updating the module, Dolibarr will automatically create the new database tables when you enable the module. + +### 2. Add Parent/Guardian Accounts + +1. Navigate to **Childcare → Parents → New Parent** +2. Fill in parent information: + - First Name and Last Name + - Relationship to child + - Contact information (email, phone) + - Username (used for tablet login) + - PIN (4-6 digits) +3. Optionally mark as primary contact +4. Save the parent record + +### 3. Set Up Tablet Device + +1. Open a web browser on the tablet +2. Navigate to: `https://your-dolibarr-url/custom/childcare/tablet_checkin.php` +3. Bookmark this page or add it to the home screen +4. Set the tablet to prevent sleep/lock +5. Consider setting up a kiosk mode browser for security + +### 4. Configure Permissions + +The tablet check-in interface is publicly accessible (no Dolibarr login required) to allow parents to use it independently. However, you should: + +1. Set appropriate network restrictions (e.g., restrict to facility WiFi) +2. Use HTTPS for secure communication +3. Place tablet in supervised location + +### 5. Staff Access + +Staff with appropriate permissions can: +- View attendance records with parent information +- Manage parent accounts +- View digital signatures +- Generate reports + +## Usage Guide + +### For Parents + +1. **Start Check-In** + - Approach the tablet at the check-in station + - Enter your username + - Enter your 4-6 digit PIN + - Tap Continue + +2. **Select Action** + - Your name and child's name will be displayed + - Tap "Check In" or "Check Out" + +3. **Sign** + - Sign on the signature pad using your finger or stylus + - Tap "Clear Signature" if you need to redo it + - Tap "Confirm Check-In" or "Confirm Check-Out" + +4. **Done** + - You'll see a success message + - Tap "Done" to return to the login screen + +### For Staff + +#### Managing Parents + +1. Navigate to **Childcare → Parents** +2. View list of all parents/guardians +3. Click "New Parent" to add a new parent +4. Click on a parent to view/edit details + +#### Viewing Attendance with Parent Info + +1. Navigate to **Childcare → Attendance** +2. Attendance records now show: + - Which parent performed check-in + - Which parent performed check-out + - Digital signatures + - Timestamps + +#### Accessing Tablet Interface + +1. Navigate to **Childcare → Tablet Check-In** +2. Opens in a new tab optimized for tablets + +## Security Considerations + +### PIN Security + +- PINs are hashed using `password_hash()` with bcrypt +- Never stored in plain text +- Cannot be retrieved, only reset + +### Network Security + +Recommendations: +1. Use HTTPS for all connections +2. Restrict tablet to facility WiFi network +3. Set up IP whitelisting if possible +4. Use tablet in supervised area + +### Session Security + +- Sessions expire after successful check-in/check-out +- No persistent login on tablet +- Each transaction requires re-authentication + +### Data Privacy + +- Signatures are stored securely in the database +- Access controlled by Dolibarr permissions +- Complies with childcare record-keeping requirements + +## Troubleshooting + +### "Invalid username or PIN" + +- Verify parent account is active +- Check username is entered correctly (case-sensitive) +- Verify PIN is 4-6 digits +- Ensure parent is associated with an active child + +### Signature Not Working + +- Try using a different browser (Chrome or Safari recommended) +- Check touch screen calibration +- Try using a stylus instead of finger +- Clear browser cache + +### "Session expired" + +- Start over from the beginning +- This is a security feature to prevent unauthorized use +- Re-authenticate with username and PIN + +### Database Errors + +If you see database errors after upgrading: +1. Disable the module +2. Re-enable the module to run SQL updates +3. Check database logs for specific errors +4. Verify database user has CREATE TABLE permissions + +## Payroll Time Clock Usage + +### Calculate Hours + +The attendance records can be used for payroll calculations: + +```sql +SELECT + c.firstname, c.lastname, + a.attendance_date, + a.check_in_time, + a.check_out_time, + TIMEDIFF(a.check_out_time, a.check_in_time) as hours_attended, + p1.firstname as checkin_parent, + p2.firstname as checkout_parent +FROM llx_childcare_attendance a +INNER JOIN llx_childcare_child c ON a.fk_child = c.rowid +LEFT JOIN llx_childcare_parent p1 ON a.fk_parent_checkin = p1.rowid +LEFT JOIN llx_childcare_parent p2 ON a.fk_parent_checkout = p2.rowid +WHERE a.attendance_date BETWEEN '2026-03-01' AND '2026-03-31' +ORDER BY c.lastname, a.attendance_date; +``` + +### Export for Payroll + +You can export attendance data including: +- Child name +- Date and time stamps +- Total hours +- Parent signatures (for verification) + +### Billing Integration + +Use the attendance data to: +- Calculate hourly billing +- Generate monthly invoices +- Track overtime hours +- Provide detailed statements to parents + +## Future Enhancements + +Potential improvements for future versions: + +1. **Photo Verification**: Capture photo during check-in/check-out +2. **QR Code Login**: Alternative to username/PIN +3. **Biometric Authentication**: Fingerprint or face recognition +4. **SMS Notifications**: Alert parents on check-in/check-out +5. **Mobile App**: Dedicated mobile application +6. **Reports Dashboard**: Real-time attendance dashboard +7. **Bulk Operations**: Check in/out multiple children at once +8. **Schedule Integration**: Compare attendance to scheduled times +9. **Late Pickup Alerts**: Automatic notifications for late pickups +10. **Attendance Analytics**: Patterns and statistics + +## API Integration + +For custom integrations, you can query the attendance data: + +```php +// Get today's attendance +$sql = "SELECT a.*, c.firstname, c.lastname, + p1.firstname as checkin_parent_name, + p2.firstname as checkout_parent_name + FROM ".MAIN_DB_PREFIX."childcare_attendance a + INNER JOIN ".MAIN_DB_PREFIX."childcare_child c ON a.fk_child = c.rowid + LEFT JOIN ".MAIN_DB_PREFIX."childcare_parent p1 ON a.fk_parent_checkin = p1.rowid + LEFT JOIN ".MAIN_DB_PREFIX."childcare_parent p2 ON a.fk_parent_checkout = p2.rowid + WHERE a.attendance_date = CURDATE()"; +``` + +## Support + +For issues or questions: +1. Check this documentation +2. Review the troubleshooting section +3. Create an issue on GitHub +4. Contact Moko Consulting for professional support + +## License + +This feature is part of the MokoDoliCare module and is licensed under GPL v3. + +--- + +**Version**: 1.1.0 +**Last Updated**: 2026-03-03 +**Author**: Moko Consulting + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/roadmap.md b/MokoConsulting/MokoDoliCare/roadmap.md new file mode 100644 index 0000000..96efb90 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/roadmap.md @@ -0,0 +1,505 @@ +← [Home](Home) + +# MokoDoliCare Roadmap + +**Strategic Product Roadmap and Feature Timeline** + +This document outlines the strategic direction and planned features for the MokoDoliCare Childcare Management Module. Our goal is to create the most comprehensive, secure, and user-friendly childcare management solution for Dolibarr. + +--- + +## 📍 Current Status + +**Version**: 1.1.0 (Released: March 2026) + +### Released Features +- ✅ Child record management with medical info and emergency contacts +- ✅ Remote check-in/check-out system with parent authentication +- ✅ Digital signature capture for check-in/check-out +- ✅ Payroll time clock with parent accountability +- ✅ Parent/guardian management with secure PIN authentication +- ✅ Daily attendance tracking with timestamps +- ✅ Activity scheduling and management +- ✅ Basic reporting and statistics +- ✅ Multi-entity support +- ✅ Role-based permissions + +--- + +## 🎯 Product Vision + +**Mission**: Empower childcare facilities with enterprise-grade management tools that save time, improve safety, and enhance parent communication - all within the trusted Dolibarr platform. + +### Core Principles +1. **Safety First**: Every feature prioritizes child safety and regulatory compliance +2. **Parent-Centric**: Easy communication and transparency for parents +3. **Staff Efficiency**: Reduce administrative burden with automation +4. **Dolibarr Integration**: Seamless integration with existing Dolibarr workflows +5. **Mobile-Ready**: Optimize for tablets and mobile devices +6. **Data Privacy**: Protect sensitive child and family information + +--- + +## 🗓️ Release Timeline + +### Version 1.2.0 - Enhanced Communication (Q2 2026) +**Theme**: Connecting parents and staff through better communication tools + +**Target Release**: May 2026 + +#### Features +- **Email Notifications for Parents** + - Automated attendance confirmations + - Activity updates and newsletters + - Event reminders and announcements + - Daily summary emails + - Customizable notification preferences + +- **SMS/Text Notifications** (Optional) + - Check-in/check-out confirmations + - Emergency alerts + - Pickup reminders + - Integration with popular SMS gateways + +- **Parent Portal Enhancements** + - View child's daily schedule + - Access attendance history + - Download monthly reports + - Update contact information + +- **Document Management Phase 1** + - Upload and attach documents to child records + - Store enrollment forms and agreements + - Medical records and vaccination documents + - Photo gallery for activities + - Document version control + +**Technical Goals** +- Email templating system +- Background job queue for notifications +- Document storage integration +- File upload security enhancements + +--- + +### Version 1.3.0 - Advanced Operations (Q3 2026) +**Theme**: Streamlining daily operations and staff management + +**Target Release**: August 2026 + +#### Features +- **Staff Scheduling and Management** + - Staff roster creation + - Shift planning and assignments + - Time-off requests and approvals + - Staff attendance tracking + - Minimum staffing ratio alerts + +- **Meal Planning and Nutritional Tracking** + - Weekly/monthly meal planning + - Nutritional information database + - Allergen tracking and alerts + - Meal consumption tracking per child + - Dietary restriction management + - Parent meal notifications + +- **Medical Records and Vaccination Tracking** + - Vaccination schedule templates + - Vaccination due date reminders + - Medical history tracking + - Medication administration log + - Illness tracking and reporting + - Doctor and insurance information + +- **Enhanced Activity Management** + - Activity templates library + - Lesson plans and curriculum tracking + - Learning milestones and assessments + - Photo/video attachments to activities + - Parent sharing of activity photos + +**Technical Goals** +- Staff scheduling algorithm +- Medical records encryption +- Photo storage optimization +- Activity template engine + +--- + +### Version 1.4.0 - Reporting & Analytics (Q4 2026) +**Theme**: Data-driven insights and compliance reporting + +**Target Release**: November 2026 + +#### Features +- **Advanced Reporting Dashboard** + - Executive dashboard with KPIs + - Attendance analytics and trends + - Revenue and billing insights + - Staff utilization reports + - Child development tracking + - Customizable report builder + +- **Export and Integration** + - PDF report generation + - Excel export functionality + - Chart and graph visualizations + - Data export for accounting systems + - API for third-party integrations + +- **Compliance Reporting** + - Licensing and regulatory reports + - Incident and accident reports + - Staff-to-child ratio monitoring + - Health inspection documentation + - Fire drill and safety logs + +**Technical Goals** +- Reporting engine development +- Chart library integration +- PDF generation optimization +- REST API endpoints + +--- + +### Version 2.0.0 - Financial Management (Q1 2027) +**Theme**: Complete financial operations for childcare businesses + +**Target Release**: February 2027 + +#### Major Features + +##### Billing and Invoicing +- **Invoice Generation for Childcare Fees** + - Automated monthly/weekly billing + - Hourly rate calculations from attendance + - Flat rate and sliding scale pricing + - Late fees and discounts + - Multi-child discounts + - Integration with Dolibarr invoicing + +- **Payment Processing** + - Online payment gateway integration + - Credit card payment processing + - ACH/bank transfers + - Payment plans and schedules + - Past-due account management + - Payment reminder emails + +- **Subsidy and Grant Management** + - Government subsidy tracking + - Scholarship management + - Grant reporting and compliance + - Co-payment calculations + +##### Financial Reporting +- Accounts receivable aging reports +- Revenue forecasting +- Profitability analysis by program +- Budget vs. actual tracking +- Tax reporting documentation + +**Technical Goals** +- Payment gateway integration (Stripe, PayPal) +- Financial calculation engine +- PCI compliance for payment data +- Dolibarr accounting module integration + +--- + +### Version 2.1.0 - Mobile Experience (Q2 2027) +**Theme**: Mobile-first experience for parents and staff + +**Target Release**: May 2027 + +#### Features +- **Progressive Web App (PWA)** + - Install as mobile app + - Offline functionality + - Push notifications + - Fast, app-like experience + +- **Mobile-Responsive Interface Improvements** + - Redesigned mobile layouts + - Touch-optimized interactions + - Improved tablet check-in interface + - Mobile-friendly reports + +- **Native Mobile App** (Future consideration) + - iOS and Android apps + - Native performance + - Camera integration for photos + - Biometric authentication + +**Technical Goals** +- PWA implementation +- Service worker for offline mode +- Mobile UI framework +- Push notification service + +--- + +### Version 2.2.0 - Integration & Automation (Q3 2027) +**Theme**: Connect with external systems and automate workflows + +**Target Release**: August 2027 + +#### Features +- **Calendar Integration** + - Google Calendar sync + - Microsoft Outlook integration + - Apple Calendar support + - Event and activity syncing + - Shared calendars for parents + +- **REST API Endpoints** + - Complete API documentation + - Authentication and authorization + - Webhooks for events + - Mobile app integration + - Third-party system integration + +- **Workflow Automation** + - Automated enrollment workflows + - Attendance reminders + - Re-enrollment campaigns + - Birthday notifications + - License renewal reminders + +**Technical Goals** +- REST API development +- OAuth 2.0 implementation +- Webhook infrastructure +- API rate limiting and monitoring + +--- + +### Version 3.0.0 - Enterprise & Multi-Site (Q4 2027) +**Theme**: Scaling for enterprise childcare organizations + +**Target Release**: November 2027 + +#### Features +- **Multi-Site Management** + - Central dashboard for multiple facilities + - Cross-site reporting and analytics + - Centralized staff management + - Resource sharing between sites + - Consolidated billing + +- **Waitlist Management** + - Online enrollment application + - Waitlist prioritization + - Automated enrollment offers + - Waitlist analytics + +- **Advanced Security** + - Two-factor authentication (2FA) + - Single Sign-On (SSO) integration + - Enhanced audit logging + - Data retention policies + - GDPR compliance tools + +- **Marketing and CRM** + - Lead tracking and nurturing + - Tour scheduling and management + - Marketing campaign management + - Parent satisfaction surveys + - Referral tracking + +**Technical Goals** +- Multi-tenant architecture optimization +- SSO provider integration +- Enhanced security framework +- CRM module integration + +--- + +## 🌟 Future Considerations (Post-3.0) + +These features are on our long-term radar but not yet scheduled: + +### Advanced Features +- **AI-Powered Insights** + - Predictive attendance patterns + - Staff scheduling optimization + - Revenue forecasting + - Anomaly detection for safety + +- **Learning Management System (LMS)** + - Curriculum builder + - Assessment tracking + - Portfolio management + - Parent-teacher conferences scheduling + +- **Transportation Management** + - Bus route planning + - Driver assignments + - Pick-up/drop-off tracking + - GPS integration + +- **Inventory Management** + - Supplies and materials tracking + - Automatic reorder alerts + - Asset management + - Vendor management + +- **Emergency Management** + - Emergency contact drills + - Evacuation planning + - Real-time emergency alerts + - Incident command system integration + +### International Features +- **Multi-Language Support** + - Spanish (Español) + - French (Français) + - German (Deutsch) + - Portuguese (Português) + - Additional languages based on demand + +- **Localization** + - Regional date/time formats + - Currency localization + - Compliance with local regulations + - Cultural customization + +--- + +## 🎯 Feature Priority Matrix + +### High Priority (Must Have) +- Email notifications (v1.2.0) +- Document management (v1.2.0) +- Staff scheduling (v1.3.0) +- Medical records (v1.3.0) +- Billing and invoicing (v2.0.0) + +### Medium Priority (Should Have) +- Advanced reporting (v1.4.0) +- Meal planning (v1.3.0) +- Calendar integration (v2.2.0) +- Mobile PWA (v2.1.0) +- REST API (v2.2.0) + +### Low Priority (Nice to Have) +- SMS notifications (v1.2.0) +- Native mobile apps (v2.1.0+) +- Marketing CRM (v3.0.0) +- Waitlist management (v3.0.0) +- AI insights (Future) + +--- + +## 📊 Success Metrics + +We'll measure success through: + +### Adoption Metrics +- Number of active installations +- Number of children managed +- Number of daily check-ins +- User satisfaction scores + +### Usage Metrics +- Parent portal engagement +- Mobile vs. desktop usage +- Feature adoption rates +- Average session duration + +### Business Metrics +- Support ticket reduction +- Time saved on administrative tasks +- Parent retention rates +- Revenue growth for customers + +### Technical Metrics +- System uptime (target: 99.9%) +- Page load times (target: <2s) +- API response times (target: <500ms) +- Bug resolution time (target: <48h) + +--- + +## 🤝 Community Input + +We welcome community feedback on this roadmap! + +### How to Contribute Ideas +1. **GitHub Issues**: Submit feature requests +2. **Community Forums**: Discuss features with other users +3. **User Surveys**: Participate in our quarterly surveys +4. **Beta Testing**: Sign up for early access to new features + +### Voting on Features +- Star feature requests on GitHub to vote +- Most popular features may be prioritized +- We balance community requests with strategic vision + +--- + +## 📋 Development Process + +### Release Cadence +- **Major releases** (x.0.0): Quarterly with significant new features +- **Minor releases** (x.x.0): Monthly with enhancements and fixes +- **Patch releases** (x.x.x): As needed for critical bugs + +### Quality Standards +- All features must have documentation +- Unit test coverage >80% +- Security review for all features +- User acceptance testing +- Performance benchmarking + +### Open Source Commitment +- Transparent development on GitHub +- Community code contributions welcome +- Regular security audits +- Responsive to bug reports + +--- + +## 🔄 Roadmap Updates + +This roadmap is a living document and will be updated: +- **Quarterly**: Major roadmap reviews and updates +- **Monthly**: Feature status updates +- **As Needed**: For strategic shifts or major announcements + +**Last Updated**: March 3, 2026 +**Next Review**: June 2026 +**Roadmap Version**: 1.0 + +--- + +## 📞 Questions or Suggestions? + +Have ideas for features not on this roadmap? Want to discuss priorities? + +- **Email**: support@mokoconsulting.tech +- **GitHub Issues**: https://github.com/mokoconsulting-tech/MokoDoliCare/issues +- **Documentation**: https://github.com/mokoconsulting-tech/MokoDoliCare/tree/main/docs + +--- + +## See Also + +- [Changelog](changelog.md) - Detailed version history +- [Development Guide](development.md) - Contributing to the project +- [Installation Guide](installation.md) - Getting started +- [User Guide](user-guide.md) - Feature documentation + +--- + +**Strategic Direction**: Building the future of childcare management, one feature at a time. + +*This roadmap reflects our current plans and priorities. Features and timelines are subject to change based on community feedback, technical considerations, and strategic decisions.* + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/troubleshooting.md b/MokoConsulting/MokoDoliCare/troubleshooting.md new file mode 100644 index 0000000..37f72a4 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/troubleshooting.md @@ -0,0 +1,862 @@ +← [Home](Home) + +# Troubleshooting Guide + +Comprehensive troubleshooting guide for MokoDoliCare Childcare Management Module. This guide covers common issues, error messages, and solutions. + +## Table of Contents + +1. [Installation Issues](#installation-issues) +2. [Module Activation Problems](#module-activation-problems) +3. [Database Issues](#database-issues) +4. [Permission Problems](#permission-problems) +5. [Data Entry Issues](#data-entry-issues) +6. [Performance Issues](#performance-issues) +7. [User Interface Problems](#user-interface-problems) +8. [Error Messages](#error-messages) +9. [Diagnostic Tools](#diagnostic-tools) + +--- + +## Installation Issues + +### Module Not Appearing in Module List + +**Symptoms**: +- Can't find "Childcare Management" in module list +- Module list doesn't load + +**Possible Causes & Solutions**: + +#### 1. Files Not in Correct Location + +**Check**: +```bash +ls -la /path/to/dolibarr/htdocs/custom/childcare/core/modules/ +``` + +**Expected**: `modMokoDoliCare.class.php` should exist + +**Solution**: +```bash +# Copy files from src/ if they're in wrong location +cp -r /path/to/MokoDoliCare/src/* /path/to/dolibarr/htdocs/custom/childcare/ +``` + +#### 2. Incorrect File Permissions + +**Check**: +```bash +ls -la /path/to/dolibarr/htdocs/custom/childcare/ +``` + +**Should see**: +- Directories: `755` (drwxr-xr-x) +- Files: `644` (-rw-r--r--) +- Owner: `www-data` (or your web server user) + +**Solution**: +```bash +# Fix ownership +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/childcare/ + +# Fix permissions +find /path/to/dolibarr/htdocs/custom/childcare/ -type d -exec chmod 755 {} \; +find /path/to/dolibarr/htdocs/custom/childcare/ -type f -exec chmod 644 {} \; +``` + +#### 3. PHP Syntax Errors + +**Check**: +```bash +php -l /path/to/dolibarr/htdocs/custom/childcare/core/modules/modMokoDoliCare.class.php +``` + +**Expected**: "No syntax errors detected" + +**If errors found**: Review the PHP error and fix syntax issues + +#### 4. Cache Issues + +**Solution**: +```bash +# Clear Dolibarr cache +rm -rf /path/to/dolibarr/documents/install.lock + +# Clear browser cache +# Press Ctrl+Shift+Del (Chrome/Firefox) +# Or use incognito/private mode +``` + +### Installation Fails with "Include of main fails" + +**Symptom**: Error message when accessing module files + +**Cause**: Module can't find Dolibarr's main.inc.php + +**Solution**: + +1. **Verify Dolibarr Installation**: + ```bash + ls -la /path/to/dolibarr/htdocs/main.inc.php + ``` + +2. **Check Module Location**: + Must be in: `/path/to/dolibarr/htdocs/custom/childcare/` + +3. **Check Dolibarr Configuration**: + ```php + // In /path/to/dolibarr/htdocs/conf/conf.php + $dolibarr_main_document_root_alt = '/path/to/dolibarr/htdocs/custom'; + $dolibarr_main_url_root_alt = '/custom'; + ``` + +### Database Tables Not Created + +**Symptoms**: +- Module activates but doesn't work +- Errors about missing tables + +**Check**: +```sql +SHOW TABLES LIKE 'llx_childcare%'; +``` + +**Expected**: Should show 3 tables: +- `llx_childcare_child` +- `llx_childcare_attendance` +- `llx_childcare_activity` + +**Solution**: + +1. **Manual Table Creation**: + ```bash + mysql -u username -p database_name < /path/to/dolibarr/htdocs/custom/childcare/sql/llx_childcare_child.sql + mysql -u username -p database_name < /path/to/dolibarr/htdocs/custom/childcare/sql/llx_childcare_attendance.sql + mysql -u username -p database_name < /path/to/dolibarr/htdocs/custom/childcare/sql/llx_childcare_activity.sql + mysql -u username -p database_name < /path/to/dolibarr/htdocs/custom/childcare/sql/llx_childcare_child.key.sql + mysql -u username -p database_name < /path/to/dolibarr/htdocs/custom/childcare/sql/llx_childcare_attendance.key.sql + mysql -u username -p database_name < /path/to/dolibarr/htdocs/custom/childcare/sql/llx_childcare_activity.key.sql + ``` + +2. **Check Database Permissions**: + ```sql + SHOW GRANTS FOR 'dolibarr_user'@'localhost'; + ``` + + Should include: `CREATE`, `ALTER`, `INDEX` privileges + +--- + +## Module Activation Problems + +### Can't Activate Module + +**Symptom**: Click activate button but nothing happens or error appears + +#### Solution 1: Check User Permissions + +**Required**: Must be logged in as administrator + +**Verify**: +1. Go to **Home → Users & Groups → Your User** +2. Check **Administrator** box is checked +3. Verify **Super-administrator** rights if needed + +#### Solution 2: Check for Conflicting Modules + +Some modules may conflict. Check error logs: + +```bash +tail -f /path/to/dolibarr/documents/dolibarr.log +``` + +Look for error messages when attempting activation + +#### Solution 3: Database Connection Issues + +```sql +-- Check module constant +SELECT * FROM llx_const WHERE name = 'MAIN_MODULE_CHILDCARE'; + +-- If exists but value = 0, manually set to 1 +UPDATE llx_const SET value = '1' WHERE name = 'MAIN_MODULE_CHILDCARE'; + +-- If doesn't exist, insert it +INSERT INTO llx_const (name, value, type, note, entity) +VALUES ('MAIN_MODULE_CHILDCARE', '1', 'chaine', 'Module childcare enabled', 1); +``` + +### Module Activates But Menu Doesn't Appear + +**Symptoms**: +- Module shows as "Active" +- No "Childcare" menu in top navigation + +**Solutions**: + +#### 1. Clear Cache and Refresh + +```bash +# Server-side +rm -rf /path/to/dolibarr/documents/install.lock + +# Client-side +# Hard refresh browser: Ctrl+Shift+R (or Ctrl+F5) +``` + +#### 2. Check User Permissions + +User must have at least **Read** permission in Childcare module: + +1. Go to **Home → Users & Groups → [Your User]** +2. Click **Permissions** tab +3. Find **Childcare** section +4. Check at least one permission (e.g., "Read child records") +5. Save + +#### 3. Check Menu Configuration + +```sql +-- Verify menu entries +SELECT * FROM llx_menu +WHERE module = 'childcare' +ORDER BY position; + +-- If no results, menu may not be configured properly +-- Deactivate and reactivate module +``` + +--- + +## Database Issues + +### Foreign Key Constraint Errors + +**Symptom**: Error when trying to delete records + +**Error Message**: `Cannot delete or update a parent row: a foreign key constraint fails` + +**Explanation**: Record has related records that must be deleted first + +**Example**: Can't delete a child who has attendance records + +**Solutions**: + +#### Option 1: Delete Related Records First + +```sql +-- Find attendance records for child ID 5 +SELECT * FROM llx_childcare_attendance WHERE fk_child = 5; + +-- Delete attendance records +DELETE FROM llx_childcare_attendance WHERE fk_child = 5; + +-- Now delete child +DELETE FROM llx_childcare_child WHERE rowid = 5; +``` + +#### Option 2: Deactivate Instead of Delete + +Instead of deleting, set status to inactive: + +```sql +UPDATE llx_childcare_child SET status = 0 WHERE rowid = 5; +``` + +### Duplicate Entry Errors + +**Error Message**: `Duplicate entry 'CHILD001' for key 'ref'` + +**Cause**: Reference number already exists + +**Solutions**: + +1. **Use Different Reference**: + - Let system auto-generate reference + - Use next number in sequence (CHILD002, CHILD003, etc.) + +2. **Check Existing References**: + ```sql + SELECT ref FROM llx_childcare_child ORDER BY ref; + ``` + +### Table Doesn't Exist Error + +**Error Message**: `Table 'dolibarr_db.llx_childcare_child' doesn't exist` + +**Cause**: Database tables not created during activation + +**Solution**: See [Database Tables Not Created](#database-tables-not-created) above + +### Character Encoding Issues + +**Symptoms**: +- Special characters display as `�` or garbled text +- Names with accents don't save correctly + +**Solution**: + +```sql +-- Check table encoding +SHOW CREATE TABLE llx_childcare_child; + +-- Should be UTF8 +-- If not, convert: +ALTER TABLE llx_childcare_child CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +ALTER TABLE llx_childcare_attendance CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +ALTER TABLE llx_childcare_activity CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +``` + +--- + +## Permission Problems + +### User Can't See Any Childcare Data + +**Symptom**: Module menu appears but lists are empty or "Access Forbidden" + +**Diagnosis**: + +1. **Check User Has Permissions**: + - Home → Users & Groups → [User] → Permissions tab + - Look for Childcare section + - At minimum need "Read" permission + +2. **Check User is Active**: + ```sql + SELECT login, statut FROM llx_user WHERE rowid = [user_id]; + ``` + `statut` should be `1` (active) + +3. **Check Multi-Entity Access**: + If using multi-entity, user must have access to correct entity + +**Solution**: + +```sql +-- Grant read permissions to user ID 5 +INSERT INTO llx_user_rights (fk_user, fk_id) +VALUES +(5, 18506501); -- Read child records + +-- Or grant all childcare permissions +INSERT INTO llx_user_rights (fk_user, fk_id) +SELECT 5, 18506501 UNION ALL +SELECT 5, 18506502 UNION ALL +SELECT 5, 18506503 UNION ALL +SELECT 5, 18506521 UNION ALL +SELECT 5, 18506522 UNION ALL +SELECT 5, 18506531 UNION ALL +SELECT 5, 18506532; +``` + +### Can See Data But Can't Edit + +**Symptom**: User can view records but edit buttons are grayed out or missing + +**Cause**: User has "Read" but not "Write" permission + +**Solution**: Grant write permissions + +1. Navigate to: **Home → Users & Groups → [User] → Permissions** +2. In Childcare section, check: + - ☑ Create/Edit child records + - ☑ Create/Edit attendance + - ☑ Create/Edit activities +3. Click **Save** + +### Permission Changes Don't Take Effect + +**Solutions**: + +1. **Force User to Re-login**: + - Log out completely + - Clear browser cookies + - Log back in + +2. **Clear Session Cache**: + ```bash + rm -rf /path/to/dolibarr/documents/sessions/* + ``` + +3. **Verify in Database**: + ```sql + -- Check user's permissions + SELECT ur.fk_id, r.label + FROM llx_user_rights ur + JOIN llx_rights_def r ON ur.fk_id = r.id + WHERE ur.fk_user = [user_id] + AND r.module = 'childcare'; + ``` + +--- + +## Data Entry Issues + +### Can't Create New Child + +**Symptom**: Save button doesn't work or error message appears + +**Common Issues**: + +#### 1. Required Fields Missing + +**Required fields**: +- First Name +- Last Name +- Date of Birth +- Reference (if not auto-generated) + +**Solution**: Fill in all required fields (marked with *) + +#### 2. Invalid Date Format + +**Error**: Date of birth invalid + +**Correct Format**: YYYY-MM-DD (e.g., 2020-03-15) + +**Solution**: Use date picker or enter in correct format + +#### 3. Duplicate Reference + +**Error**: "Reference already exists" + +**Solution**: +- Leave reference blank for auto-generation +- Use unique reference number + +### Dates Not Saving or Display Incorrectly + +**Symptoms**: +- Dates save as 0000-00-00 +- Dates display in wrong format +- Times show wrong timezone + +**Solutions**: + +#### Check Date Format + +```sql +-- View date formats +SELECT date_of_birth, enrollment_date FROM llx_childcare_child LIMIT 5; +``` + +Should be: `2020-03-15` (not `03/15/2020` or `15-03-2020`) + +#### Check Server Timezone + +```bash +# PHP timezone +php -r "echo date_default_timezone_get();" + +# MySQL timezone +mysql -u user -p -e "SELECT @@global.time_zone, @@session.time_zone;" +``` + +**Set in Dolibarr**: +- Home → Setup → Other Setup → Timezone +- Select correct timezone + +### Check-In/Out Times Not Saving + +**Symptoms**: +- Times save as 00:00:00 +- Times display incorrectly + +**Solutions**: + +1. **Use 24-hour Format**: + - Correct: `14:30` or `14:30:00` + - Incorrect: `2:30 PM` + +2. **Check Time Field in Database**: + ```sql + SELECT check_in_time, check_out_time + FROM llx_childcare_attendance + WHERE attendance_date = CURDATE(); + ``` + +3. **Verify Field Type**: + ```sql + DESCRIBE llx_childcare_attendance; + ``` + `check_in_time` and `check_out_time` should be `time` type + +--- + +## Performance Issues + +### Slow Page Loading + +**Symptoms**: +- Pages take 5+ seconds to load +- Timeout errors + +**Diagnosis**: + +```bash +# Check PHP error log +tail -f /var/log/apache2/error.log | grep childcare + +# Check MySQL slow query log +mysql -u root -p -e "SELECT * FROM mysql.slow_log WHERE sql_text LIKE '%childcare%' ORDER BY start_time DESC LIMIT 10;" +``` + +**Solutions**: + +#### 1. Database Optimization + +```sql +-- Analyze tables +ANALYZE TABLE llx_childcare_child; +ANALYZE TABLE llx_childcare_attendance; +ANALYZE TABLE llx_childcare_activity; + +-- Optimize tables +OPTIMIZE TABLE llx_childcare_child; +OPTIMIZE TABLE llx_childcare_attendance; +OPTIMIZE TABLE llx_childcare_activity; +``` + +#### 2. Check Index Usage + +```sql +-- Verify indexes exist +SHOW INDEX FROM llx_childcare_child; +SHOW INDEX FROM llx_childcare_attendance; +SHOW INDEX FROM llx_childcare_activity; +``` + +#### 3. PHP Memory and Execution Time + +```php +// Check in Home → Setup → Other Setup → System +// Or edit php.ini +memory_limit = 512M +max_execution_time = 300 +``` + +### Large Database Size + +**Check Database Size**: + +```sql +SELECT + table_name, + ROUND(((data_length + index_length) / 1024 / 1024), 2) AS "Size (MB)", + table_rows +FROM information_schema.TABLES +WHERE table_schema = 'dolibarr_db' + AND table_name LIKE 'llx_childcare%' +ORDER BY (data_length + index_length) DESC; +``` + +**Solutions**: + +1. **Archive Old Data**: + ```sql + -- Archive attendance older than 2 years + CREATE TABLE llx_childcare_attendance_archive + AS SELECT * FROM llx_childcare_attendance + WHERE attendance_date < DATE_SUB(CURDATE(), INTERVAL 2 YEAR); + + -- Delete from main table after verification + DELETE FROM llx_childcare_attendance + WHERE attendance_date < DATE_SUB(CURDATE(), INTERVAL 2 YEAR); + ``` + +2. **Delete Unnecessary Data**: + ```sql + -- Delete cancelled activities older than 1 year + DELETE FROM llx_childcare_activity + WHERE status = 0 + AND activity_date < DATE_SUB(CURDATE(), INTERVAL 1 YEAR); + ``` + +--- + +## User Interface Problems + +### Menu Items Missing + +**Symptom**: Some menu items don't appear + +**Check**: +1. User permissions (need appropriate rights) +2. Browser cache (clear and refresh) +3. Module fully activated + +### Page Layout Broken + +**Symptoms**: +- CSS not loading +- Elements overlapping +- Responsive design not working + +**Solutions**: + +1. **Clear Browser Cache**: Ctrl+Shift+Del + +2. **Check CSS Files Exist**: + ```bash + ls -la /path/to/dolibarr/htdocs/custom/childcare/css/ + ``` + +3. **Check for JavaScript Errors**: + - Open browser Developer Tools (F12) + - Check Console tab for errors + +4. **Verify File Permissions**: + ```bash + chmod 644 /path/to/dolibarr/htdocs/custom/childcare/css/*.css + ``` + +### Dropdown Lists Empty + +**Symptom**: Child selection dropdown is empty + +**Causes**: + +1. **No Active Children**: + ```sql + SELECT COUNT(*) FROM llx_childcare_child WHERE status = 1; + ``` + +2. **Wrong Entity** (multi-entity setups): + ```sql + SELECT * FROM llx_childcare_child WHERE entity = [your_entity_id]; + ``` + +3. **JavaScript Error**: Check browser console (F12) + +--- + +## Error Messages + +### "Access Forbidden" + +**Full Message**: "Access to this area is forbidden. You are logged in but do not have permission..." + +**Cause**: User lacks required permissions + +**Solution**: See [Permission Problems](#permission-problems) + +### "Table doesn't exist" + +**Full Message**: "Table 'dolibarr_db.llx_childcare_child' doesn't exist" + +**Solution**: See [Table Doesn't Exist Error](#table-doesnt-exist-error) + +### "Cannot add or update a child row" + +**Full Message**: "Cannot add or update a child row: a foreign key constraint fails" + +**Cause**: Trying to reference non-existent record + +**Example**: Creating attendance for child ID that doesn't exist + +**Solution**: +```sql +-- Verify child exists +SELECT * FROM llx_childcare_child WHERE rowid = [child_id]; + +-- If doesn't exist, create child first +``` + +### "Duplicate entry" + +**Full Message**: "Duplicate entry 'CHILD001' for key 'ref'" + +**Solution**: See [Duplicate Entry Errors](#duplicate-entry-errors) + +### "Out of memory" + +**Full Message**: "Allowed memory size of 134217728 bytes exhausted" + +**Solution**: + +```php +// Increase PHP memory limit +// In php.ini or conf/conf.php +memory_limit = 512M +``` + +```bash +# Restart web server +sudo systemctl restart apache2 +# or +sudo systemctl restart nginx +``` + +--- + +## Diagnostic Tools + +### System Information + +```bash +# Dolibarr version +cat /path/to/dolibarr/htdocs/filefunc.inc.php | grep DOL_VERSION + +# PHP version and modules +php -v +php -m + +# Database version +mysql --version + +# Disk space +df -h + +# Memory usage +free -h +``` + +### Module Status Check + +```sql +-- Module activation status +SELECT * FROM llx_const WHERE name = 'MAIN_MODULE_CHILDCARE'; + +-- Module version +SELECT * FROM llx_const WHERE name LIKE '%CHILDCARE%'; + +-- Tables exist +SHOW TABLES LIKE 'llx_childcare%'; + +-- Record counts +SELECT + 'children' as table_name, COUNT(*) as count FROM llx_childcare_child +UNION ALL +SELECT 'attendance', COUNT(*) FROM llx_childcare_attendance +UNION ALL +SELECT 'activities', COUNT(*) FROM llx_childcare_activity; +``` + +### Log Files + +```bash +# Apache error log +tail -f /var/log/apache2/error.log + +# Nginx error log +tail -f /var/log/nginx/error.log + +# Dolibarr log +tail -f /path/to/dolibarr/documents/dolibarr.log + +# MySQL error log +tail -f /var/log/mysql/error.log + +# PHP error log +tail -f /var/log/php/error.log +``` + +### Debug Mode + +Enable Dolibarr debug mode: + +```php +// In /path/to/dolibarr/htdocs/conf/conf.php +$dolibarr_main_prod = 0; // 0 = debug mode, 1 = production mode +``` + +**Warning**: Only use debug mode temporarily. Always return to production mode. + +--- + +## Getting Additional Help + +### Before Asking for Help + +Gather this information: + +1. **System Information**: + - Dolibarr version + - PHP version + - Database type and version + - Web server type and version + +2. **Error Details**: + - Exact error message + - Steps to reproduce + - When did it start happening + - What changed recently + +3. **Log Files**: + - Relevant error log entries + - Timestamps of issues + +### Support Channels + +1. **Documentation**: + - [User Guide](user-guide.md) + - [Admin Guide](admin-guide.md) + - [Database Schema](database-schema.md) + +2. **Community Support**: + - GitHub Issues: Report bugs or feature requests + - Dolibarr Forum: Community help + +3. **Professional Support**: + - Contact Moko Consulting for professional support + +--- + +## Appendix: Quick Reference Commands + +### Database Backup + +```bash +mysqldump -u user -p dolibarr_db \ + llx_childcare_child \ + llx_childcare_attendance \ + llx_childcare_activity > backup.sql +``` + +### Database Restore + +```bash +mysql -u user -p dolibarr_db < backup.sql +``` + +### Check Module Active + +```bash +mysql -u user -p dolibarr_db -e "SELECT value FROM llx_const WHERE name='MAIN_MODULE_CHILDCARE';" +``` + +### Reset Module + +```bash +# Deactivate +mysql -u user -p dolibarr_db -e "UPDATE llx_const SET value='0' WHERE name='MAIN_MODULE_CHILDCARE';" + +# Reactivate (via Dolibarr UI or) +mysql -u user -p dolibarr_db -e "UPDATE llx_const SET value='1' WHERE name='MAIN_MODULE_CHILDCARE';" +``` + +### Clear All Data (DANGER!) + +```sql +-- WARNING: This deletes ALL childcare data! +-- Backup first! +TRUNCATE TABLE llx_childcare_attendance; +TRUNCATE TABLE llx_childcare_activity; +TRUNCATE TABLE llx_childcare_child; +``` + +--- + +**Last Updated**: 2026-02-19 +**Version**: 1.0.0 +**For**: MokoDoliCare Childcare Management Module + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/update-server.-.-.md b/MokoConsulting/MokoDoliCare/update-server.-.-.md new file mode 100644 index 0000000..f769d65 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliCare/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCare/user-guide.-.-.md b/MokoConsulting/MokoDoliCare/user-guide.-.-.md new file mode 100644 index 0000000..6675d23 --- /dev/null +++ b/MokoConsulting/MokoDoliCare/user-guide.-.-.md @@ -0,0 +1,863 @@ +← [Home](Home) + +# User Guide + +Complete guide to using MokoDoliCare for childcare facility management. This guide covers all features and workflows for daily operations. + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [Child Management](#child-management) +3. [Attendance Tracking](#attendance-tracking) +4. [Activity Management](#activity-management) +5. [Reports and Analytics](#reports-and-analytics) +6. [Daily Workflows](#daily-workflows) +7. [Tips and Best Practices](#tips-and-best-practices) + +--- + +## Getting Started + +### Accessing MokoDoliCare + +1. **Log in** to your Dolibarr installation +2. Look for **"Childcare"** in the top navigation menu +3. Click to access the childcare dashboard + +### Dashboard Overview + +The dashboard provides an at-a-glance view of: +- 📊 **Total Active Children** - Current enrollment count +- 📅 **Today's Attendance** - Present/Absent status +- 🎯 **Scheduled Activities** - Today's activity schedule +- 📈 **Recent Updates** - Latest changes and additions + +### Navigation Menu + +``` +Childcare +├── Dashboard → Overview and statistics +├── Children → Manage child records +│ ├── List → View all children +│ └── New Child → Add new child +├── Attendance → Track daily attendance +│ ├── List → View attendance records +│ └── New Record → Record attendance +└── Activities → Manage activities + ├── Schedule → View activity schedule + └── New Activity → Create new activity +``` + +--- + +## Child Management + +### Adding a New Child + +#### Step-by-Step Process + +1. Navigate to **Childcare → Children → New Child** +2. Fill in the required information +3. Click **Create** to save + +#### Required Fields + +| Field | Description | Example | +|-------|-------------|---------| +| **Reference** | Unique identifier (auto-generated if blank) | `CHILD001` | +| **First Name** | Child's given name | `Emma` | +| **Last Name** | Child's family name | `Johnson` | +| **Date of Birth** | Birth date (YYYY-MM-DD) | `2020-03-15` | + +#### Optional but Important Fields + +| Field | Description | Best Practices | +|-------|-------------|----------------| +| **Gender** | Child's gender | Use for statistics; optional | +| **Allergies** | Food/environmental allergies | ⚠️ Be specific and include severity | +| **Medical Notes** | Health conditions, medications | Include emergency procedures | +| **Emergency Contact** | Emergency contact info | Name, relationship, phone number | +| **Enrollment Date** | When child started | Used for enrollment tracking | +| **Status** | Active/Inactive | Check "Active" for current students | +| **Public Notes** | Notes visible to all staff | General information | +| **Private Notes** | Confidential notes | Restricted access | + +#### Example: Complete Child Record + +``` +Reference: CHILD001 +First Name: Emma +Last Name: Johnson +Date of Birth: March 15, 2020 (Age: 5 years) +Gender: Female + +Allergies: + - Peanut allergy (SEVERE - EpiPen required in red bag) + - Mild lactose intolerance (can have small amounts) + +Medical Notes: + - Asthma (uses blue inhaler as needed - in office) + - Regular checkups with Dr. Smith at City Pediatrics + - No other medical conditions + +Emergency Contact: + Primary: Sarah Johnson (Mother) - (555) 123-4567 + Secondary: Mike Johnson (Father) - (555) 123-4568 + Emergency: Grandma Susan - (555) 123-4569 + +Enrollment Date: September 1, 2023 +Status: ✓ Active +``` + +### Viewing Child Records + +#### Children List View + +**Navigation**: Childcare → Children → List + +**Features**: +- **Search bar** - Find children by name or reference +- **Filter by status** - Active, Inactive, or All +- **Sort options** - By name, enrollment date, or status +- **Quick actions** - Edit, view, or delete from list + +**List Columns**: +| Column | Description | +|--------|-------------| +| Ref | Child reference number | +| Name | Full name (First Last) | +| Date of Birth | Birth date and calculated age | +| Status | Active/Inactive indicator | +| Actions | Edit, View, Delete buttons | + +#### Child Card View + +**Navigation**: Click on child name from list + +**Tabs**: +1. **Overview** - Basic information and status +2. **Attendance** - Historical attendance records +3. **Medical** - Allergies and medical information +4. **Contacts** - Emergency contacts and guardians +5. **Notes** - Public and private notes + +### Editing Child Information + +1. Go to **Children → List** +2. Click on the child's name or click **Edit** button +3. Modify the information +4. Click **Save** to update + +**Important**: Changes are logged with timestamp and user who made the change. + +### Deactivating a Child + +When a child leaves the facility: + +1. Open the child's record +2. Uncheck **"Active"** status +3. Add note with departure date and reason (optional) +4. Click **Save** + +**Note**: Deactivating preserves all historical data but removes child from active lists. + +### Searching and Filtering + +#### Search by Name +``` +Search box: "Emma" → Shows all Emmas +Search box: "John" → Shows Johns and Johnsons +``` + +#### Filter Options +- **Status**: Active / Inactive / All +- **Enrollment Date**: This Year / Last Year / All Time +- **Age Range**: Infants / Toddlers / Preschool / All + +#### Advanced Search Tips +- Use reference numbers for exact matches: `CHILD001` +- Search by partial names: `Joh` finds `Johnson`, `John`, `Johnny` +- Combine filters: Active + This Year = Current year enrollees + +--- + +## Attendance Tracking + +### Recording Daily Attendance + +#### Quick Check-In Process + +**Morning Arrival**: + +1. Go to **Childcare → Attendance → New Record** +2. Select child from dropdown +3. Date auto-fills to today +4. Enter **Check-in Time** (e.g., `08:30`) +5. Status: **Present** (default) +6. Add morning notes (optional): `Brought show-and-tell item` +7. Click **Save** + +**Alternative Quick Method**: +- From **Attendance List**, click **Quick Check-In** +- Select multiple children +- Bulk check-in with same time + +#### Recording Check-Out + +**Afternoon Departure**: + +1. Go to **Attendance → List** +2. Find today's record for the child +3. Click **Edit** +4. Enter **Check-out Time** (e.g., `15:30`) +5. Add afternoon notes: `Had a great day. Ate all lunch.` +6. Click **Save** + +### Attendance Status Codes + +| Status | Value | Use When | +|--------|-------|----------| +| **Present** | 1 | Child attended full or partial day | +| **Absent** | 0 | Child did not attend (sick, vacation, etc.) | +| **Partial** | 2 | Child attended only part of scheduled time | + +### Daily Notes Best Practices + +Good daily notes help parents and document child development: + +**Structure Your Notes**: + +``` +Morning: +- Mood on arrival: Happy, excited +- Items brought: Blue backpack, water bottle + +Midday: +- Meals: Ate all lunch, drank juice +- Activities: Participated in art project, outdoor play +- Nap: Slept 1.5 hours (12:30-2:00) + +Afternoon: +- Behavior: Played well with others, shared toys +- Incidents: Small scrape on knee (cleaned, bandaid applied) +- Departure: Left with grandmother at 3:30 PM +``` + +**Example Excellent Daily Note**: + +``` +Emma had a wonderful day! She arrived happy at 8:30 AM with her +stuffed bear for show-and-tell. She ate all of her lunch and tried +new carrots. She participated enthusiastically in our art project +(painting will come home tomorrow). Napped well from 12:30-2:00 PM. +Played nicely with friends during outdoor time. Small scrape on right +knee from playground - cleaned and bandaid applied, no tears. +Departed happy with mom at 3:45 PM. +``` + +### Attendance Reports + +#### View Attendance History + +**For One Child**: +1. Open child's card +2. Click **Attendance** tab +3. View full history with notes + +**For All Children**: +1. Go to **Attendance → List** +2. Filter by date range +3. Export to PDF or Excel (if available) + +#### Common Attendance Reports + +**Today's Attendance Summary**: +- Total Present: 15 +- Total Absent: 3 +- Not Yet Recorded: 2 +- Attendance Rate: 83.3% + +**Monthly Attendance**: +- Total Days: 20 +- Average Daily Attendance: 16.5 +- Most Absent Day: Friday +- Perfect Attendance: 8 children + +### Late Check-In/Early Check-Out + +Document timing issues: + +1. Record actual check-in/out time +2. Add note explaining: `Late arrival - parent called ahead` +3. Track patterns for parent discussions if needed + +### Handling Special Situations + +#### Child is Absent + +1. Create attendance record +2. Select child and date +3. Set Status: **Absent** +4. Leave check-in/out times blank +5. Add reason if known: `Sick - parent called` +6. Click **Save** + +#### Half-Day Attendance + +1. Record check-in time +2. Record check-out time (earlier than usual) +3. Set Status: **Partial** +4. Add note: `Half day - doctor appointment at 12:00` + +#### Forgot to Record + +You can always add historical records: +1. Select the past date +2. Enter check-in/out times +3. Add note: `Retroactive entry - forgot to record` + +--- + +## Activity Management + +### Planning Activities + +#### Creating a New Activity + +1. Navigate to **Childcare → Activities → New Activity** +2. Fill in the details: + +| Field | Required | Example | +|-------|----------|---------| +| **Reference** | No (auto) | `ACT-2026-02-19-001` | +| **Label** | Yes | `Morning Circle Time` | +| **Description** | No | `Songs, weather, calendar, sharing` | +| **Date** | Yes | `2026-02-19` | +| **Time** | No | `09:00` | +| **Activity Type** | No | `Learning` | +| **Status** | Yes | `Scheduled` | + +3. Click **Create** + +### Activity Types Guide + +#### Learning Activities + +**Purpose**: Educational and developmental activities + +**Examples**: +- ABC and letter recognition +- Number counting and math concepts +- Shape and color identification +- Science experiments +- Puzzles and problem-solving +- Calendar and weather learning + +**Documentation**: +``` +Label: Alphabet Practice +Description: Practiced letters A-E using flashcards and songs +Type: Learning +Duration: 20 minutes +Participation: 12 of 15 children +Notes: Emma and Jacob excelled, Tommy needs more practice with letter C +``` + +#### Play Activities + +**Purpose**: Free or structured playtime + +**Examples**: +- Building blocks +- Dramatic play (kitchen, dress-up) +- Board games +- Toy vehicles and figures +- Sensory play (sand, water) +- Indoor gym time + +**Tips**: +- Rotate toys weekly to maintain interest +- Document social interactions +- Note emerging friendships +- Record any conflicts and resolutions + +#### Outdoor Activities + +**Purpose**: Physical exercise and fresh air + +**Examples**: +- Playground time +- Nature walks +- Ball games +- Riding toys (tricycles, scooters) +- Gardening +- Chalk drawing + +**Safety Notes**: +- Always document weather conditions +- Note any injuries immediately +- Record sunscreen application +- Document water intake on hot days + +#### Arts & Crafts + +**Purpose**: Creative expression and fine motor skills + +**Examples**: +- Painting (watercolor, finger, brush) +- Drawing and coloring +- Collage and cutting +- Clay or playdough +- Seasonal crafts +- Parent gift projects + +**Documentation**: +``` +Label: Spring Flower Painting +Description: Watercolor flowers using sponges and stamps +Materials: Paper, watercolors, sponges, stamps +Type: Arts +Outcome: All paintings will dry and go home tomorrow +Notes: Emma loved mixing colors, Jacob made a purple flower +``` + +#### Music Activities + +**Purpose**: Rhythm, movement, and auditory development + +**Examples**: +- Group singing +- Musical instruments +- Dance and movement +- Listening to music +- Rhythm games +- Music and story combination + +#### Story Time + +**Purpose**: Language development and imagination + +**Examples**: +- Picture books +- Chapter book readings (for older children) +- Storytelling (without books) +- Puppet shows +- Children retelling stories +- Author studies + +**Best Practices**: +``` +Label: "The Very Hungry Caterpillar" Story Time +Books Read: + - The Very Hungry Caterpillar (Eric Carle) + - Follow-up: Lifecycle discussion +Type: Story Time +Duration: 15 minutes +Engagement: High - children participated in counting fruits +Notes: Will create butterfly craft tomorrow as follow-up +``` + +#### Meal Times + +**Purpose**: Nutrition and social skills + +**Types**: +- Breakfast +- Morning snack +- Lunch +- Afternoon snack + +**Documentation**: +``` +Label: Lunch Time +Type: Meals +Menu: + - Chicken nuggets + - Carrot sticks + - Apple slices + - Milk +Notes: + - Emma ate all lunch + - Jacob refused carrots (gave extra apples) + - Tommy spilled milk (cleaned up, refilled) + - New child Sarah ate well on first day +``` + +#### Nap/Rest Time + +**Purpose**: Physical rest and recovery + +**Documentation**: +``` +Label: Afternoon Nap Time +Type: Naps +Time: 12:30 PM - 2:30 PM +Notes: + - 14 of 15 children slept + - Emma awoke after 45 minutes (looked at books quietly) + - Jacob slept full 2 hours + - Room temp: 70°F, lights dimmed, soft music +``` + +### Activity Scheduling + +#### Daily Schedule Template + +``` +08:00 - 08:30 Arrival & Free Play +08:30 - 09:00 Breakfast +09:00 - 09:30 Morning Circle Time (Learning) +09:30 - 10:30 Outdoor Play (Outdoor) +10:30 - 11:00 Snack Time (Meals) +11:00 - 12:00 Learning Activity (Learning) +12:00 - 12:30 Lunch (Meals) +12:30 - 14:30 Nap Time (Naps) +14:30 - 15:00 Snack Time (Meals) +15:00 - 15:30 Story Time or Music (varies) +15:30 - 16:00 Free Play & Pickup +``` + +#### Weekly Activity Planning + +**Monday**: Science/Nature focus +**Tuesday**: Arts & Crafts day +**Wednesday**: Music & Movement +**Thursday**: Story & Drama +**Friday**: Special Activity & Show & Tell + +### Managing Activity Status + +**Status Options**: + +| Status | Code | Use When | +|--------|------|----------| +| **Scheduled** | 1 | Activity is planned, not yet completed | +| **Completed** | 2 | Activity finished successfully | +| **Cancelled** | 0 | Activity didn't happen (weather, etc.) | + +**Updating Status**: +1. Go to **Activities → Schedule** +2. Find the activity +3. Click **Edit** +4. Change **Status** to **Completed** +5. Add completion notes +6. Click **Save** + +### Activity Reports + +View and analyze activities: + +**By Type**: See distribution of activity types +**By Date**: View daily/weekly schedules +**By Completion**: Track planned vs. completed activities + +--- + +## Reports and Analytics + +### Available Reports + +#### Attendance Reports + +**Daily Attendance Report**: +- Children present today +- Check-in/out times +- Daily notes summary +- Missing attendance records + +**Monthly Attendance Report**: +- Attendance percentage per child +- Perfect attendance recognition +- Absence patterns +- Late arrival/early departure tracking + +**Attendance Trends**: +- Busiest days of week +- Seasonal attendance patterns +- Individual child attendance history + +#### Activity Reports + +**Activity Summary**: +- Total activities by type +- Completion rate +- Most popular activities +- Staff activity creation metrics + +**Activity Calendar**: +- Visual monthly calendar +- Color-coded by activity type +- Filter by type or date range + +#### Child Reports + +**Individual Child Report**: +- Enrollment information +- Attendance summary +- Activity participation +- Developmental notes +- Medical information + +**Enrollment Report**: +- Active children count +- New enrollments this month/year +- Departures/withdrawals +- Age distribution +- Capacity utilization + +### Generating Reports + +1. Go to **Childcare → Reports** +2. Select report type +3. Choose date range +4. Apply filters (optional) +5. Click **Generate** +6. View on-screen or download (PDF/Excel) + +### Exporting Data + +Export options for external analysis: +- **PDF**: Formatted reports for printing +- **Excel**: Raw data for custom analysis +- **CSV**: Compatible with most software + +--- + +## Daily Workflows + +### Morning Workflow + +**8:00 AM - Opening**: +``` +☐ Review today's activity schedule +☐ Check for any special notes (birthdays, events) +☐ Prepare attendance list +☐ Set up first activity area +``` + +**8:30 AM - Arrivals Begin**: +``` +☐ Greet each child and parent +☐ Record check-in time immediately +☐ Note any items brought from home +☐ Ask parents about morning routine/concerns +☐ Add morning notes to attendance +``` + +### Midday Workflow + +**Throughout the Day**: +``` +☐ Update attendance notes regularly +☐ Mark activities as completed +☐ Document incidents immediately +☐ Take photos (manual storage for now) +☐ Note food intake and nap times +``` + +**Meal and Activity Transitions**: +``` +☐ Check activity schedule +☐ Prepare next activity materials +☐ Document current activity completion +☐ Transition children smoothly +``` + +### Afternoon Workflow + +**3:00 PM - Pickup Begins**: +``` +☐ Record check-out times as children leave +☐ Complete daily notes for each child +☐ Verbally share highlights with parents +☐ Send home any artwork or papers +☐ Note parent communications needed +``` + +**5:00 PM - Closing**: +``` +☐ Ensure all check-outs recorded +☐ Review day's notes for completeness +☐ Prepare tomorrow's schedule +☐ Document any concerns for admin +☐ Clean up and secure facility +``` + +### Weekly Workflow + +**Monday**: +``` +☐ Review week's activity plan +☐ Check for birthdays or special events +☐ Order/prepare materials needed +☐ Review last week's attendance +``` + +**Friday**: +``` +☐ Complete weekly activity report +☐ Review attendance for the week +☐ Plan next week's activities +☐ Send parent communications +☐ Organize files and records +``` + +### Monthly Workflow + +**End of Month**: +``` +☐ Generate monthly attendance report +☐ Review activity completion rates +☐ Update any medical information +☐ Schedule parent conferences if needed +☐ Archive completed records +☐ Plan next month's special activities +``` + +--- + +## Tips and Best Practices + +### Data Entry Best Practices + +**Be Consistent**: +- Use same time format (24-hour recommended) +- Follow naming conventions for references +- Complete records same day when possible +- Use standard abbreviations + +**Be Thorough**: +- Document everything immediately +- Include context in notes +- Note both positives and concerns +- Cross-reference related records + +**Be Accurate**: +- Double-check times and dates +- Verify child selection in dropdowns +- Review before saving +- Correct errors immediately + +### Security and Privacy + +**Protecting Child Information**: +- ✅ Log out when leaving computer +- ✅ Never share login credentials +- ✅ Use private notes for sensitive info +- ✅ Follow facility privacy policies +- ❌ Don't leave screens visible to unauthorized persons +- ❌ Don't discuss child info in public areas + +**Access Levels**: +- Understand your permission level +- Request appropriate access from admin +- Report suspicious access attempts +- Maintain confidentiality always + +### Communication Tips + +**With Parents**: +- Share daily notes verbally at pickup +- Highlight positive moments +- Address concerns professionally +- Document all parent communications +- Maintain friendly but professional tone + +**With Staff**: +- Share important notes at shift changes +- Document handoffs clearly +- Alert others to urgent information +- Collaborate on activity planning + +### Time Management + +**Efficiency Tips**: +1. **Use keyboard shortcuts** when available +2. **Batch similar tasks** (all check-ins at once) +3. **Prepare templates** for common notes +4. **Set reminders** for regular tasks +5. **Review dashboard** at start of day + +**Quick Data Entry**: +``` +Instead of: "Emma Johnson arrived at 8:32 AM. She brought her stuffed + bear. Mom said she had a good morning." + +Use: "8:32 arrival. Brought bear. Good morning per mom." +``` + +### Troubleshooting Common Issues + +**Can't Find a Child**: +- Check if child status is "Active" +- Verify correct spelling +- Try searching by reference number +- Check if viewing correct entity + +**Time Not Saving**: +- Use 24-hour format (HH:MM) +- Check timezone settings +- Verify time is in valid range +- Refresh page and try again + +**Report Not Generating**: +- Check date range is valid +- Verify you have permission to view reports +- Try smaller date range +- Contact administrator if persists + +--- + +## Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| `Alt + H` | Go to home/dashboard | +| `Alt + N` | New record (context-sensitive) | +| `Alt + S` | Save current form | +| `Alt + C` | Cancel and return | +| `Alt + E` | Edit current record | +| `Ctrl + F` | Find/Search | +| `Esc` | Close dialog/cancel | + +--- + +## Additional Resources + +- 📖 [Quick Start Guide](quick-start.md) - Get started in 10 minutes +- 🔧 [Admin Guide](admin-guide.md) - System configuration +- 💾 [Database Schema](database-schema.md) - Technical details +- 🛠️ [Troubleshooting Guide](troubleshooting.md) - Problem solving + +--- + +## Getting Help + +**Questions about using a feature?** +- Check this guide first +- Ask your facility administrator +- Consult Dolibarr documentation + +**Found a bug or issue?** +- Document the exact steps to reproduce +- Note error messages +- Report to your system administrator + +**Need training?** +- Ask for hands-on training session +- Practice with test data +- Review video tutorials (when available) + +--- + +**Last Updated**: 2026-02-19 +**Version**: 1.0.0 +**For**: MokoDoliCare Childcare Management Module + +--- + +*Repo: [MokoDoliCare](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCare) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliChimp/DEVELOPMENT_GUIDE.md b/MokoConsulting/MokoDoliChimp/DEVELOPMENT_GUIDE.md new file mode 100644 index 0000000..7de61ca --- /dev/null +++ b/MokoConsulting/MokoDoliChimp/DEVELOPMENT_GUIDE.md @@ -0,0 +1,647 @@ +← [Home](Home) + +# MokoDoliChimp Development Guide + +This comprehensive guide covers the complete development workflow for MokoDoliChimp, with detailed steps for FTP-based development (editing files on remote server) and local development (editing files locally). + +--- + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Initial Setup](#initial-setup) +- [FTP-Based Development Workflow](#ftp-based-development-workflow) +- [Local Development Workflow](#local-development-workflow) +- [Common Development Tasks](#common-development-tasks) +- [Testing Your Changes](#testing-your-changes) +- [Troubleshooting](#troubleshooting) + +--- + +## Prerequisites + +### Required Software + +1. **Git** - Version control + ```bash + git --version + ``` + +2. **PHP 7.0+** - For syntax checking + ```bash + php --version + ``` + +3. **Make** - Build automation + ```bash + make --version + ``` + +4. **rsync** - File synchronization (for FTP workflow) + ```bash + rsync --version + ``` + +5. **FTP Client** (Optional - for direct FTP editing) + - FileZilla, Cyberduck, or command-line FTP + +### Access Requirements + +- SSH/FTP access to your Dolibarr server +- Write permissions to Dolibarr's `htdocs/custom/` directory +- Dolibarr admin access for module activation + +--- + +## Initial Setup + +### Step 1: Clone the Repository + +Clone the repository with submodules: + +```bash +# Navigate to your development directory +cd ~/projects + +# Clone with submodules +git clone https://github.com/mokoconsulting-tech/MokoDoliChimp.git + +# Navigate to project directory +cd MokoDoliChimp +``` + +### Step 2: Verify Project Structure + +```bash +# Check all required directories exist +ls -la + +# Expected output should include: +# - src/ (Source code) +# - src/admin/ (Admin pages) +# - src/class/ (Business logic) +# - src/core/ (Module descriptor) +# - src/lang/ (Translations) +# - docs/ (Documentation) +# - scripts/ (Build scripts) +# - Makefile (Build automation) +``` + +### Step 3: Validate Installation + +```bash +# Check PHP syntax for all files +make check + +# Expected output: +# Checking PHP syntax... +# ✓ PHP syntax check completed + +# Validate module structure +make validate + +# Expected output: +# Validating module structure... +# ✓ Module structure validated +``` + +--- + +## FTP-Based Development Workflow + +This workflow is ideal when you have FTP/SSH access to your Dolibarr server and want to edit files locally, then sync to the server. + +### Overview + +1. Edit files locally on your computer +2. Use `make dev-sync` to upload changes to server +3. Test changes in Dolibarr +4. Repeat as needed + +### Step-by-Step Guide + +#### Step 1: Configure Server Path + +Set your Dolibarr installation path. You have two options: + +**Option A: Set environment variable (recommended)** +```bash +# Add to your ~/.bashrc or ~/.zshrc for permanent setting +export DOLIBARR_PATH=/var/www/html/dolibarr + +# Or set for current session only +export DOLIBARR_PATH=/path/to/your/dolibarr +``` + +**Option B: Specify path with each command** +```bash +# You'll need to add DOLIBARR_PATH=/path/to/dolibarr to each command +make dev-sync DOLIBARR_PATH=/var/www/html/dolibarr +``` + +#### Step 2: Initial Installation to Server + +First, install the module to your Dolibarr server: + +```bash +# If you set DOLIBARR_PATH as environment variable: +make install + +# Or specify path directly: +make install DOLIBARR_PATH=/var/www/html/dolibarr + +# You may need sudo if the directory requires elevated permissions: +sudo make install DOLIBARR_PATH=/var/www/html/dolibarr +``` + +**Expected Output:** +``` +Installing module to /var/www/html/dolibarr/htdocs/custom/mokodolichimp... +Copying module files... +Setting permissions... +✓ Ownership set to www-data:www-data +✓ Module installed to /var/www/html/dolibarr/htdocs/custom/mokodolichimp + +Next steps: + 1. Go to Dolibarr: Home → Setup → Modules/Applications + 2. Find 'MokoDoliChimp' and click Activate + 3. Configure the module settings +``` + +#### Step 3: Activate Module in Dolibarr + +1. Open your Dolibarr installation in a web browser +2. Navigate to: **Home → Setup → Modules/Applications** +3. Search for "MokoDoliChimp" +4. Click the **Activate** button +5. Click the **Settings** button to configure API keys + +#### Step 4: Development Cycle + +Now you're ready to develop! Follow this iterative cycle: + +**A. Edit Files Locally** + +Use your favorite editor to modify files: + +```bash +# Example: Edit the main module file +code src/mokodolichimp.php + +# Or edit a class file +code src/class/mailchimpclient.class.php + +# Or edit the admin page +code src/admin/setup.php +``` + +**B. Validate Changes Locally** + +Before syncing, check for syntax errors: + +```bash +# Check PHP syntax +make check + +# Expected output: +# Checking PHP syntax... +# ✓ PHP syntax check completed +``` + +**C. Sync Changes to Server** + +Upload your changes to the server: + +```bash +# Sync files to server +make dev-sync + +# Expected output: +# Syncing changes to /var/www/html/dolibarr/htdocs/custom/mokodolichimp... +# Syncing files from src/ (excluding development artifacts)... +# sending incremental file list +# mokodolichimp.php +# class/mailchimpclient.class.php +# +# ✓ Files synced successfully +# Synced from: /home/user/projects/MokoDoliChimp/src/ +# Synced to: /var/www/html/dolibarr/htdocs/custom/mokodolichimp +``` + +**D. Test in Dolibarr** + +1. Refresh your Dolibarr page in the browser +2. Test your changes +3. Check for errors in Dolibarr's error logs if needed: + ```bash + # On the server + tail -f /var/www/html/dolibarr/documents/dolibarr.log + ``` + +**E. Repeat** + +Continue the cycle: Edit → Check → Sync → Test + +### Understanding dev-sync Behavior + +The `make dev-sync` command: + +- **Syncs all module files** from your local directory to server +- **Excludes development files** (.git, build artifacts, etc.) +- **Uses rsync with --delete** to mirror your local changes exactly +- **Creates directory** if it doesn't exist on server +- **Preserves permissions** on the server + +**Files that are excluded from sync:** +- `.git/` and `.gitignore` +- `build/` and `dist/` directories +- `Makefile` +- `.editorconfig` + +### Step 5: Committing Changes to Git + +After testing and verifying your changes work: + +```bash +# Check what files changed +git status + +# View specific changes +git diff src/mokodolichimp.php + +# Stage your changes +git add src/mokodolichimp.php +git add src/class/mailchimpclient.class.php + +# Commit with descriptive message +git commit -m "feat: add new feature to sync contacts" + +# Push to your branch +git push origin your-branch-name +``` + +--- + +## Local Development Workflow + +This workflow is for local development where Dolibarr runs on the same machine as your development environment. + +### Step 1: Install Dolibarr Locally + +Ensure Dolibarr is installed locally (e.g., via XAMPP, MAMP, or Docker). + +### Step 2: Create Development Symlink + +This creates a symbolic link, so changes in your development directory immediately reflect in Dolibarr: + +```bash +# Create symlink +sudo make dev-install DOLIBARR_PATH=/path/to/local/dolibarr + +# Expected output: +# Creating development symlink... +# ✓ Development symlink created +# Note: Changes in this directory will be immediately reflected in Dolibarr +``` + +### Step 3: Activate Module + +Follow the same activation steps as in FTP workflow. + +### Step 4: Development Cycle + +1. **Edit files** in your development directory +2. **Changes are immediate** (no sync needed) +3. **Refresh browser** to see changes in Dolibarr +4. **Test** your changes +5. **Commit** when done + +--- + +## Common Development Tasks + +### Checking Syntax Before Sync + +Always validate your code before syncing: + +```bash +# Check all PHP files +make check + +# If there are errors, they'll be shown with line numbers +``` + +### Building Distribution Package + +Create a ZIP package for distribution: + +```bash +# Build package +make build + +# Output will be in dist/mokodolichimp-1.0.0.zip +ls -lh dist/ +``` + +### Updating Existing Installation + +If you've already installed and want to update: + +```bash +# Update installation +make update + +# Or for FTP workflow, just use dev-sync: +make dev-sync +``` + +### Cleaning Build Artifacts + +Remove temporary build files: + +```bash +# Clean build and dist directories +make clean + +# Expected output: +# Cleaning build artifacts... +# ✓ Clean completed +``` + +### Viewing All Available Commands + +```bash +# Show help +make help + +# Output shows all available commands with descriptions +``` + +--- + +## Testing Your Changes + +### Manual Testing Checklist + +After making changes, test the following: + +1. **Module Activation** + - Module appears in Modules/Applications list + - Activation completes without errors + +2. **Configuration Page** + - Navigate to module settings + - All fields display correctly + - Can save configuration + +3. **Mailchimp Integration** + - API key validation works + - Contact sync functionality works + - User sync functionality works + +4. **Error Handling** + - Invalid API keys show appropriate errors + - Network errors are handled gracefully + +### Checking Dolibarr Logs + +```bash +# On the server, monitor logs in real-time +tail -f /var/www/html/dolibarr/documents/dolibarr.log + +# Or check recent errors +tail -50 /var/www/html/dolibarr/documents/dolibarr.log | grep ERROR +``` + +### PHP Error Logs + +```bash +# Check Apache error logs (Ubuntu/Debian) +sudo tail -f /var/log/apache2/error.log + +# Check PHP-FPM logs (if using PHP-FPM) +sudo tail -f /var/log/php-fpm/error.log +``` + +--- + +## Troubleshooting + +### Issue: "make: command not found" + +**Solution:** Install make utility + +```bash +# Ubuntu/Debian +sudo apt-get install make + +# macOS (via Homebrew) +brew install make + +# CentOS/RHEL +sudo yum install make +``` + +### Issue: "rsync: command not found" + +**Solution:** Install rsync + +```bash +# Ubuntu/Debian +sudo apt-get install rsync + +# macOS (usually pre-installed, but if needed) +brew install rsync + +# CentOS/RHEL +sudo yum install rsync +``` + +### Issue: Permission Denied When Syncing + +**Solution:** Use sudo or fix permissions + +```bash +# Option 1: Use sudo +sudo make dev-sync + +# Option 2: Fix directory permissions (on server) +sudo chown -R $USER:www-data /var/www/html/dolibarr/htdocs/custom +sudo chmod -R 775 /var/www/html/dolibarr/htdocs/custom +``` + +### Issue: Module Not Appearing in Dolibarr + +**Checklist:** + +1. Verify files are in correct directory: + ```bash + ls -la /var/www/html/dolibarr/htdocs/custom/mokodolichimp/ + ``` + +2. Check file permissions: + ```bash + ls -la /var/www/html/dolibarr/htdocs/custom/mokodolichimp/*.php + # Files should be readable by web server (644 or 755) + ``` + +3. Check Dolibarr module cache: + - In Dolibarr, go to: Home → Setup → Other + - Clear all caches + - Refresh the Modules/Applications page + +4. Check for PHP errors: + ```bash + tail -f /var/www/html/dolibarr/documents/dolibarr.log + ``` + +### Issue: Changes Not Reflected After Sync + +**Solutions:** + +1. **Clear browser cache:** Use Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac) + +2. **Clear Dolibarr cache:** + - Home → Setup → Other → "Clear all cache" + +3. **Verify sync completed:** + ```bash + # Check file timestamps on server + ls -lat /var/www/html/dolibarr/htdocs/custom/mokodolichimp/ | head -10 + ``` + +4. **Force full sync:** + ```bash + # Remove module directory and re-sync + sudo rm -rf /var/www/html/dolibarr/htdocs/custom/mokodolichimp + sudo make dev-sync + ``` + +### Issue: PHP Syntax Errors + +**Solution:** Run syntax check and fix errors + +```bash +# Check syntax +make check + +# Fix the reported errors +# Then re-sync +make dev-sync +``` + +--- + +## Best Practices + +### 1. Always Check Syntax Before Syncing + +```bash +make check && make dev-sync +``` + +### 2. Use Version Control Branches + +```bash +# Create feature branch +git checkout -b feature/my-new-feature + +# Make changes, sync, test +# ... + +# Commit and push +git add . +git commit -m "feat: add my new feature" +git push origin feature/my-new-feature +``` + +### 3. Test in Staging Before Production + +- Use a separate Dolibarr staging instance +- Test all changes thoroughly +- Only deploy to production after validation + +### 4. Keep Development Environment Updated + +```bash +# Pull latest changes +git pull origin main + +# Update submodules +git submodule update --remote + +# Re-sync to server +make dev-sync +``` + +### 5. Document Your Changes + +- Update CHANGELOG.md for significant changes +- Add comments to complex code +- Update README.md if adding new features + +--- + +## Quick Reference + +### Common Commands + +```bash +# Initial setup +git clone --recurse-submodules https://github.com/mokoconsulting-tech/MokoDoliChimp.git +cd MokoDoliChimp + +# Set Dolibarr path (add to ~/.bashrc for permanence) +export DOLIBARR_PATH=/var/www/html/dolibarr + +# Validate code +make check + +# Sync to server (FTP workflow) +make dev-sync + +# Create symlink (Local workflow) +sudo make dev-install + +# Build distribution +make build + +# Show all commands +make help +``` + +### File Locations + +- **Module files on server:** `/var/www/html/dolibarr/htdocs/custom/mokodolichimp/` +- **Dolibarr logs:** `/var/www/html/dolibarr/documents/dolibarr.log` +- **Apache logs:** `/var/log/apache2/error.log` +- **Distribution packages:** `./dist/mokodolichimp-1.0.0.zip` + +### Key Files to Edit + +- **Main module file:** `src/mokodolichimp.php` +- **Module descriptor:** `src/core/modules/modMokoDoliChimp.class.php` +- **Mailchimp client:** `src/class/mailchimpclient.class.php` +- **Hook actions:** `src/class/actions_mokodolichimp.class.php` +- **Admin setup page:** `src/admin/setup.php` +- **Translations:** `src/lang/en_US/mokodolichimp.lang` + +--- + +## Getting Help + +- **Issues:** https://github.com/mokoconsulting-tech/MokoDoliChimp/issues +- **moko-platform:** https://github.com/mokoconsulting-tech/moko-platform +- **Dolibarr Wiki:** https://wiki.dolibarr.org/ + +--- + +**Happy Coding! 🚀** + +--- + +*Repo: [MokoDoliChimp](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliChimp) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliChimp/Home.md b/MokoConsulting/MokoDoliChimp/Home.md new file mode 100644 index 0000000..98fed17 --- /dev/null +++ b/MokoConsulting/MokoDoliChimp/Home.md @@ -0,0 +1,26 @@ +# MokoDoliChimp + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliChimp) | + +--- + +## Documentation + +| Page | Description | +|---|---| +| [DEVELOPMENT_GUIDE](DEVELOPMENT_GUIDE) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliChimp](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliChimp) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliClaude/Home.md b/MokoConsulting/MokoDoliClaude/Home.md new file mode 100644 index 0000000..a8ecf25 --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/Home.md @@ -0,0 +1,43 @@ +# MokoDoliClaude + +A connector for Dolibarr and Claude + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliClaude/README.md b/MokoConsulting/MokoDoliClaude/README.md new file mode 100644 index 0000000..d01066e --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/README.md @@ -0,0 +1,148 @@ +← [Home](Home) + +# Documentation Index + +Welcome to the moko-platform Dolibarr Template documentation. This guide will help you navigate all available documentation resources. + +## Quick Links + +- [Installation Guide](installation.md) - Get started with installing the template +- [Development Guide](development.md) - Learn how to develop Dolibarr modules +- [Module ID Policy](module-id-policy.md) - Understand module ID assignment process +- [Changelog](changelog.md) - Track version history and changes + +## Documentation Structure + +### For New Users + +If you're new to this template, start here: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Configuration and setup + - Troubleshooting common issues + +2. **[Module ID Policy](module-id-policy.md)** + - Understanding module IDs + - Development vs. production IDs + - How to request an official ID + - Best practices + +### For Developers + +If you're developing a module, these guides will help: + +1. **[Development Guide](development.md)** + - Module structure and organization + - Module descriptor configuration + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + - Commit message guidelines + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Installation Guide](installation.md) to set up the template, then review the [Development Guide](development.md) for building your module. + +**Q: What module ID should I use?** +A: Use an ID greater than 600,000 during development. See the [Module ID Policy](module-id-policy.md) for details. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +**Q: Where are the code examples?** +A: The [Development Guide](development.md) contains numerous code examples and best practices. + +### Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) + +### moko-platform + +- [MokoConsulting Tech GitHub](https://github.com/mokoconsulting-tech) +- Template Repository: [moko-platform-Template-Dolibarr](https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 600001; // Development module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/ +git clone repo-url +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Template Version**: 1.0.0 +- **Last Updated**: 2026-01-16 +- **Minimum Dolibarr Version**: 12.0 +- **PHP Version**: 7.4+ + +--- + +**Next Steps**: +- New to the template? Start with [Installation Guide](installation.md) +- Ready to develop? Check out [Development Guide](development.md) +- Need to request a module ID? Review [Module ID Policy](module-id-policy.md) + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliClaude/changelog.md b/MokoConsulting/MokoDoliClaude/changelog.md new file mode 100644 index 0000000..5776678 --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/changelog.md @@ -0,0 +1,70 @@ +← [Home](Home) + +# Changelog + +All notable changes to this project template will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Comprehensive README.md with project overview and usage instructions +- Module ID policy documentation +- Installation guide with detailed setup instructions +- Development guide with best practices and examples +- Contributing guidelines +- Documentation structure following moko-platform + +## [1.0.0] - 2026-01-16 + +### Added +- Initial template structure for Dolibarr modules +- Basic documentation framework +- Module ID policy requiring issue-based requests +- Support for temporary development IDs (600,000+) + +--- + +## Template Usage Notes + +When using this template for your module: + +1. Copy this changelog to your project +2. Update the version numbers as you develop +3. Document all changes in the appropriate category: + - **Added** for new features + - **Changed** for changes in existing functionality + - **Deprecated** for soon-to-be removed features + - **Removed** for now removed features + - **Fixed** for any bug fixes + - **Security** for vulnerability fixes + +Example entry: +```markdown +## [1.1.0] - 2026-02-15 + +### Added +- New feature X for handling Y +- Support for Z functionality + +### Fixed +- Bug in module activation +- Permission check in admin page + +### Changed +- Updated module descriptor format +- Improved error handling +``` + +[Unreleased]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/releases/tag/v1.0.0 + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliClaude/development.md b/MokoConsulting/MokoDoliClaude/development.md new file mode 100644 index 0000000..e0a3093 --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/development.md @@ -0,0 +1,323 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - use 600,000+ for development + $this->numero = 600001; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Development Phase + +Use module ID > 600,000: + +```php +$this->numero = 600001; +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliClaude/installation.md b/MokoConsulting/MokoDoliClaude/installation.md new file mode 100644 index 0000000..4f0fba7 --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/installation.md @@ -0,0 +1,173 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring your Dolibarr module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 12.0 or higher +- **PHP**: Version 7.4 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - gd or imagick + - curl + - json + - xml + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr's custom directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone this template repository: + +```bash +git clone https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr.git yourmodule +``` + +Replace `yourmodule` with your desired module name (lowercase, no spaces). + +### 2. Rename and Configure + +Navigate to the module directory: + +```bash +cd yourmodule +``` + +Rename the module descriptor file: + +```bash +mv modYourmodule.class.php modYourModuleName.class.php +``` + +### 3. Configure Module ID + +Open the module descriptor file and set a temporary module ID greater than 600,000: + +```php +// In modYourModuleName.class.php +$this->numero = 600001; // Use a number > 600,000 for development +``` + +**Important:** Before publishing, request an official module ID by creating an issue in the repository. + +### 4. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/yourmodule + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type f -exec chmod 644 {} \; +``` + +### 5. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find your module in the list +4. Click the **Activate** button + +### 6. Configure Module Settings (if applicable) + +After activation: + +1. Go to **Home → Setup → Modules/Applications** +2. Click on your module name to access its configuration page +3. Configure any required settings +4. Save changes + +## Database Setup + +If your module requires database tables: + +### Automatic Setup + +The module descriptor can handle automatic table creation during activation. Ensure your SQL files are in the `sql/` directory: + +``` +sql/ +├── llx_yourmodule_table.sql +└── llx_yourmodule_table.key.sql +``` + +### Manual Setup + +Alternatively, run SQL scripts manually: + +```bash +mysql -u username -p database_name < sql/llx_yourmodule_table.sql +``` + +## Troubleshooting + +### Module Not Appearing + +- Clear Dolibarr cache: Delete `/documents/install.lock` and refresh +- Check file permissions +- Verify PHP syntax errors: `php -l modYourModuleName.class.php` + +### Permission Errors + +- Ensure Apache/Nginx user has read access to all module files +- Check `conf.php` file permissions in Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Check SQL file syntax +- Ensure database user has CREATE TABLE permissions + +## Uninstallation + +To remove the module: + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find your module and click **Deactivate** +3. Optionally, remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/yourmodule + ``` + +**Note:** Deactivating the module does not remove database tables. To remove data: + +```sql +DROP TABLE llx_yourmodule_table; +``` + +## Next Steps + +- Review the [Development Guide](development.md) to start customizing your module +- Check the [Module ID Policy](module-id-policy.md) before distribution +- Read the [Changelog](changelog.md) for version history + +## Support + +For installation issues: +- Create an issue in the repository +- Check Dolibarr logs: `/documents/dolibarr.log` +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliClaude/module-id-policy.-.-.md b/MokoConsulting/MokoDoliClaude/module-id-policy.-.-.md new file mode 100644 index 0000000..1ab98b5 --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliClaude/update-server.-.-.md b/MokoConsulting/MokoDoliClaude/update-server.-.-.md new file mode 100644 index 0000000..467c65b --- /dev/null +++ b/MokoConsulting/MokoDoliClaude/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliClaude/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliClaude](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliClaude) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCredits/Home.md b/MokoConsulting/MokoDoliCredits/Home.md new file mode 100644 index 0000000..abc77e2 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/Home.md @@ -0,0 +1,41 @@ +# MokoDoliCredits + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliCredits/README.md b/MokoConsulting/MokoDoliCredits/README.md new file mode 100644 index 0000000..b6ae7a7 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/README.md @@ -0,0 +1,148 @@ +← [Home](Home) + +# Documentation Index + +Welcome to the moko-platform Dolibarr Template documentation. This guide will help you navigate all available documentation resources. + +## Quick Links + +- [Installation Guide](installation.md) - Get started with installing the template +- [Development Guide](development.md) - Learn how to develop Dolibarr modules +- [Module ID Policy](module-id-policy.md) - Understand module ID assignment process +- [Changelog](changelog.md) - Track version history and changes + +## Documentation Structure + +### For New Users + +If you're new to this template, start here: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Configuration and setup + - Troubleshooting common issues + +2. **[Module ID Policy](module-id-policy.md)** + - Understanding module IDs + - Development vs. production IDs + - How to request an official ID + - Best practices + +### For Developers + +If you're developing a module, these guides will help: + +1. **[Development Guide](development.md)** + - Module structure and organization + - Module descriptor configuration + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + - Commit message guidelines + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Installation Guide](installation.md) to set up the template, then review the [Development Guide](development.md) for building your module. + +**Q: What module ID should I use?** +A: Use an ID greater than 600,000 during development. See the [Module ID Policy](module-id-policy.md) for details. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +**Q: Where are the code examples?** +A: The [Development Guide](development.md) contains numerous code examples and best practices. + +### Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) + +### moko-platform + +- [MokoConsulting Tech GitHub](https://github.com/mokoconsulting-tech) +- Template Repository: [moko-platform-Template-Dolibarr](https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 600001; // Development module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/ +git clone repo-url +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Template Version**: 1.0.0 +- **Last Updated**: 2026-01-16 +- **Minimum Dolibarr Version**: 12.0 +- **PHP Version**: 7.4+ + +--- + +**Next Steps**: +- New to the template? Start with [Installation Guide](installation.md) +- Ready to develop? Check out [Development Guide](development.md) +- Need to request a module ID? Review [Module ID Policy](module-id-policy.md) + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCredits/changelog.md b/MokoConsulting/MokoDoliCredits/changelog.md new file mode 100644 index 0000000..9e52529 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/changelog.md @@ -0,0 +1,70 @@ +← [Home](Home) + +# Changelog + +All notable changes to this project template will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Comprehensive README.md with project overview and usage instructions +- Module ID policy documentation +- Installation guide with detailed setup instructions +- Development guide with best practices and examples +- Contributing guidelines +- Documentation structure following moko-platform + +## [1.0.0] - 2026-01-16 + +### Added +- Initial template structure for Dolibarr modules +- Basic documentation framework +- Module ID policy requiring issue-based requests +- Support for temporary development IDs (600,000+) + +--- + +## Template Usage Notes + +When using this template for your module: + +1. Copy this changelog to your project +2. Update the version numbers as you develop +3. Document all changes in the appropriate category: + - **Added** for new features + - **Changed** for changes in existing functionality + - **Deprecated** for soon-to-be removed features + - **Removed** for now removed features + - **Fixed** for any bug fixes + - **Security** for vulnerability fixes + +Example entry: +```markdown +## [1.1.0] - 2026-02-15 + +### Added +- New feature X for handling Y +- Support for Z functionality + +### Fixed +- Bug in module activation +- Permission check in admin page + +### Changed +- Updated module descriptor format +- Improved error handling +``` + +[Unreleased]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/releases/tag/v1.0.0 + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCredits/development.md b/MokoConsulting/MokoDoliCredits/development.md new file mode 100644 index 0000000..05f1b80 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/development.md @@ -0,0 +1,323 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - use 600,000+ for development + $this->numero = 600001; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Development Phase + +Use module ID > 600,000: + +```php +$this->numero = 600001; +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCredits/installation.md b/MokoConsulting/MokoDoliCredits/installation.md new file mode 100644 index 0000000..13108d2 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/installation.md @@ -0,0 +1,173 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring your Dolibarr module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 12.0 or higher +- **PHP**: Version 7.4 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - gd or imagick + - curl + - json + - xml + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr's custom directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone this template repository: + +```bash +git clone https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr.git yourmodule +``` + +Replace `yourmodule` with your desired module name (lowercase, no spaces). + +### 2. Rename and Configure + +Navigate to the module directory: + +```bash +cd yourmodule +``` + +Rename the module descriptor file: + +```bash +mv modYourmodule.class.php modYourModuleName.class.php +``` + +### 3. Configure Module ID + +Open the module descriptor file and set a temporary module ID greater than 600,000: + +```php +// In modYourModuleName.class.php +$this->numero = 600001; // Use a number > 600,000 for development +``` + +**Important:** Before publishing, request an official module ID by creating an issue in the repository. + +### 4. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/yourmodule + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type f -exec chmod 644 {} \; +``` + +### 5. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find your module in the list +4. Click the **Activate** button + +### 6. Configure Module Settings (if applicable) + +After activation: + +1. Go to **Home → Setup → Modules/Applications** +2. Click on your module name to access its configuration page +3. Configure any required settings +4. Save changes + +## Database Setup + +If your module requires database tables: + +### Automatic Setup + +The module descriptor can handle automatic table creation during activation. Ensure your SQL files are in the `sql/` directory: + +``` +sql/ +├── llx_yourmodule_table.sql +└── llx_yourmodule_table.key.sql +``` + +### Manual Setup + +Alternatively, run SQL scripts manually: + +```bash +mysql -u username -p database_name < sql/llx_yourmodule_table.sql +``` + +## Troubleshooting + +### Module Not Appearing + +- Clear Dolibarr cache: Delete `/documents/install.lock` and refresh +- Check file permissions +- Verify PHP syntax errors: `php -l modYourModuleName.class.php` + +### Permission Errors + +- Ensure Apache/Nginx user has read access to all module files +- Check `conf.php` file permissions in Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Check SQL file syntax +- Ensure database user has CREATE TABLE permissions + +## Uninstallation + +To remove the module: + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find your module and click **Deactivate** +3. Optionally, remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/yourmodule + ``` + +**Note:** Deactivating the module does not remove database tables. To remove data: + +```sql +DROP TABLE llx_yourmodule_table; +``` + +## Next Steps + +- Review the [Development Guide](development.md) to start customizing your module +- Check the [Module ID Policy](module-id-policy.md) before distribution +- Read the [Changelog](changelog.md) for version history + +## Support + +For installation issues: +- Create an issue in the repository +- Check Dolibarr logs: `/documents/dolibarr.log` +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCredits/module-id-policy.-.-.md b/MokoConsulting/MokoDoliCredits/module-id-policy.-.-.md new file mode 100644 index 0000000..7d24239 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliCredits/update-server.-.-.md b/MokoConsulting/MokoDoliCredits/update-server.-.-.md new file mode 100644 index 0000000..0babda1 --- /dev/null +++ b/MokoConsulting/MokoDoliCredits/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliCredits/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliCredits](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliCredits) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliDymo/Home.md b/MokoConsulting/MokoDoliDymo/Home.md new file mode 100644 index 0000000..407049a --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/Home.md @@ -0,0 +1,43 @@ +# MokoDoliDymo + +A module to design label documents for Dymo LabelWriter + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | +| [dymo label format](dymo-label-format.-.-) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliDymo/README.md b/MokoConsulting/MokoDoliDymo/README.md new file mode 100644 index 0000000..8cc7d55 --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/README.md @@ -0,0 +1,39 @@ +← [Home](Home) + +# MokoDoliDymo Documentation + +## Quick Links + +- [Installation Guide](installation.md) — Setup and configuration +- [Development Guide](development.md) — Architecture, coding standards, extending the module +- [Changelog](changelog.md) — Version history + +## For Users + +Start with the [Installation Guide](installation.md) to get MokoDoliDymo running on your Dolibarr instance. Once installed, the module adds a **MokoDoliDymo** entry to the top menu where you can design and manage label templates. + +## For Developers + +The [Development Guide](development.md) covers the module architecture, how to add new label field types, and how to extend data binding to additional Dolibarr objects. + +This module follows [moko-platform](https://github.com/mokoconsulting-tech/moko-platform) conventions. See the [Contributing Guidelines](CONTRIBUTING) for PR and coding requirements. + +## Resources + +- [moko-platform](https://github.com/mokoconsulting-tech/moko-platform) — Governance and coding standards +- [MokoDoliDymo Repository](https://github.com/mokoconsulting-tech/MokoDoliDymo) +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) + +## Module Info + +- **Module ID**: 185072 +- **Minimum Dolibarr**: 19.0 +- **PHP**: 8.1+ + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliDymo/changelog.md b/MokoConsulting/MokoDoliDymo/changelog.md new file mode 100644 index 0000000..c518c74 --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/changelog.md @@ -0,0 +1,33 @@ +← [Home](Home) + +# Changelog + +All notable changes to MokoDoliDymo will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [01.00.00] - 2026-03-31 + +### Added + +- Initial module scaffolding for MokoDoliDymo +- Module descriptor with ID 185072 +- Admin setup and about pages +- Language file with label designer translations +- Permissions: label read, write, delete, print +- Top menu entry for MokoDoliDymo +- Documentation: installation guide, development guide, changelog + +[Unreleased]: https://github.com/mokoconsulting-tech/MokoDoliDymo/compare/v01.00.00...HEAD +[01.00.00]: https://github.com/mokoconsulting-tech/MokoDoliDymo/releases/tag/v01.00.00 + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliDymo/development.md b/MokoConsulting/MokoDoliDymo/development.md new file mode 100644 index 0000000..d1cb004 --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/development.md @@ -0,0 +1,142 @@ +← [Home](Home) + +# Development Guide + +This guide covers developing and extending MokoDoliDymo. + +## Module Structure + +``` +mokodolidymo/ +├── core/ +│ └── modules/ +│ └── modMokoDoliDymo.class.php # Module descriptor (ID 185072) +├── class/ # Business logic classes +├── langs/ +│ └── en_US/ +│ └── mokodolidymo.lang # Translations +├── sql/ # Database schema +├── lib/ +│ └── mokodolidymo.lib.php # Shared library functions +├── admin/ +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── img/ # Icons and images +└── mokodolidymoindex.php # Module home page +``` + +## Module Descriptor + +The module descriptor at `core/modules/modMokoDoliDymo.class.php` defines: + +- **Module ID**: `185072` — permanently registered, never change +- **Rights class**: `mokodolidymo` +- **Permissions**: `label.read`, `label.write`, `label.delete`, `label.print` +- **Version**: Must match `README.md` + +## Coding Standards + +This project follows [moko-platform](https://github.com/mokoconsulting-tech/moko-platform): + +| Context | Convention | +|---------|-----------| +| PHP class | `PascalCase` | +| PHP method | `camelCase` | +| PHP variable | `$snake_case` | +| PHP constant | `UPPER_SNAKE_CASE` | +| Indentation | Tabs (per `.editorconfig`) | + +### Security + +```php +// Always check permissions +if (!$user->hasRight('mokodolidymo', 'label', 'read')) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOSTINT('id'); +$name = GETPOST('name', 'alpha'); + +// Escape output +print dol_escape_htmltag($user_input); +``` + +### Translations + +Add keys to `langs/en_US/mokodolidymo.lang`: + +``` +MyNewKey = My translated string +``` + +Use in PHP: + +```php +$langs->load("mokodolidymo@mokodolidymo"); +print $langs->trans("MyNewKey"); +``` + +### Database + +SQL files go in `sql/` and are auto-loaded on module activation: + +``` +sql/ +├── llx_mokodolidymo_label.sql +└── llx_mokodolidymo_label.key.sql +``` + +## Version Management + +- **`README.md`** is the single source of truth for the version +- `$this->version` in the module descriptor must always match +- Bump patch version on every PR (`01.00.00` -> `01.00.01`) +- Format: zero-padded semver `XX.YY.ZZ` + +## File Headers + +Every new PHP file requires a copyright header: + +```php + + * + * SPDX-License-Identifier: GPL-3.0-or-later + * + * FILE INFORMATION + * DEFGROUP: MokoDoliDymo.Module + * INGROUP: MokoDoliDymo + * REPO: https://github.com/mokoconsulting-tech/MokoDoliDymo + * PATH: /src/class/MyClass.php + * VERSION: 01.00.00 + * BRIEF: One-line description + */ +``` + +## Testing + +```bash +# Run PHP linting +php -l src/core/modules/modMokoDoliDymo.class.php + +# Run PHPStan +composer phpstan + +# Run code style checks +composer phpcs +``` + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [moko-platform](https://github.com/mokoconsulting-tech/moko-platform) + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliDymo/dymo-label-format.-.-.md b/MokoConsulting/MokoDoliDymo/dymo-label-format.-.-.md new file mode 100644 index 0000000..457e08a --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/dymo-label-format.-.-.md @@ -0,0 +1,162 @@ +← [Home](Home) + +# DYMO Label File Format + +This document describes the DYMO Desktop Label XML format (`.dymo` / `.label` files) used by DYMO Connect and DYMO Label software. MokoDoliDymo can import these files as label template starting points. + +## File Structure + +DYMO label files are XML with the root element ``. + +```xml + + + + + Blank + + + + + +``` + +## Key Elements + +### DYMOLabel + +The main label definition container. + +| Element | Description | +|---------|-------------| +| `Description` | Human-readable label description | +| `Orientation` | `Landscape` or `Portrait` | +| `LabelName` | DYMO label stock name (e.g. `Address30251`, `Shipping30256`) | +| `DYMORect` | Label printable area rectangle | +| `DynamicLayoutManager > LabelObjects` | Container for all label elements | + +### DYMORect / ObjectLayout — Coordinates + +All coordinates and sizes are in **inches**. Each object has an `ObjectLayout` block: + +```xml + + + + + + +``` + +**Conversion**: 1 inch = 25.4 mm + +The label's printable area is defined by `DYMORect` with the same `DYMOPoint` + `Size` structure. + +### Label Objects + +Objects live inside `DynamicLayoutManager > LabelObjects`. Supported types: + +#### TextObject + +```xml + + TextObject0 + + + + Hello World + + Segoe UI + 26.9 + False + False + False + + + + + ... + +``` + +#### BarcodeObject + +```xml + + BarcodeObject0 + 123456789 + ... + +``` + +Common barcode formats: `Code128Auto`, `QRCode`, `EAN13`, `EAN8`, `UPCA`, `Code39`, `ITF14`, `PDF417`, `DataMatrix` + +#### ImageObject + +```xml + + ImageObject0 + ... + +``` + +#### ShapeObject + +```xml + + ShapeObject0 + ... + +``` + +### Common Properties + +All label objects share these: + +| Property | Values | Description | +|----------|--------|-------------| +| `Rotation` | `Rotation0`, `Rotation90`, `Rotation180`, `Rotation270` | Element rotation | +| `Brushes` | Complex | Fill, border, stroke, and background colors | +| `Margin` | `DYMOThickness Left/Top/Right/Bottom` | Inner padding (inches) | +| `BorderStyle` | `SolidLine`, `None` | Border drawing style | +| `OutlineThickness` | Float | Outline stroke width | + +### Label Stock Names + +The `LabelName` field identifies the DYMO label roll. Common values: + +| LabelName | DYMO Part# | Size (inches) | Size (mm) | +|-----------|-----------|---------------|-----------| +| `Address30251` | 30251 | 1-1/8 x 3-1/2 | 28.6 x 88.9 | +| `Address30252` | 30252 | 1-1/8 x 3-1/2 | 28.6 x 88.9 | +| `Shipping30256` | 30256 | 2-5/16 x 4 | 58.7 x 101.6 | +| `ReturnAddress30330` | 30330 | 3/4 x 2 | 19.1 x 50.8 | +| `MultiPurpose30334` | 30334 | 1 x 2-1/8 | 25.4 x 57.2 | +| `FileFolder30327` | 30327 | 9/16 x 3-7/16 | 14.3 x 87.3 | +| `NameBadge30857` | 30857 | 2-1/4 x 4 | 57.2 x 101.6 | + +## MokoDoliDymo Import Behavior + +When importing a `.dymo` or `.label` file: + +1. The XML is parsed to extract the label dimensions from `DYMORect` +2. Each `LabelObject` is converted to a MokoDoliDymo layout element +3. Coordinates are converted from inches to millimeters (multiply by 25.4) +4. Font sizes and text properties are preserved where possible +5. Barcode types are mapped to Dolibarr-compatible formats +6. Image data is extracted and stored separately +7. The resulting JSON layout can be further edited in the visual designer + +## References + +- [DYMO Developer SDK](https://developers.dymo.com/) +- [DYMO Connect JavaScript Framework](https://developers.dymo.com/tag/javascript/) +- [DYMO Label Framework Technical Reference](https://developers.dymo.com/2010/06/02/dymo-label-framework-javascript-library-samples-and-docs/) + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliDymo/installation.md b/MokoConsulting/MokoDoliDymo/installation.md new file mode 100644 index 0000000..ef60753 --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/installation.md @@ -0,0 +1,90 @@ +← [Home](Home) + +# Installation Guide + +## Prerequisites + +- **Dolibarr ERP/CRM**: Version 19.0 or higher +- **PHP**: 8.1 or higher +- **DYMO LabelWriter**: LabelWriter 450, 550, or compatible model +- **PHP Extensions**: mysqli or pgsql, gd, curl, json + +## Installation + +### 1. Clone the Repository + +Navigate to your Dolibarr custom modules directory and clone: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +git clone https://github.com/mokoconsulting-tech/MokoDoliDymo.git mokodolidymo +``` + +### 2. Set File Permissions + +```bash +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/mokodolidymo +find /path/to/dolibarr/htdocs/custom/mokodolidymo -type d -exec chmod 755 {} \; +find /path/to/dolibarr/htdocs/custom/mokodolidymo -type f -exec chmod 644 {} \; +``` + +### 3. Enable the Module + +1. Log in to Dolibarr as an administrator +2. Navigate to **Home > Setup > Modules/Applications** +3. Find **MokoDoliDymo** under the **Moko Consulting** family +4. Click **Activate** + +### 4. Configure Permissions + +After activation, assign permissions to users: + +1. Go to **Home > Users & Groups** +2. Select the user or group +3. Under **Permissions**, find **MokoDoliDymo** and enable: + - **Read label templates** — view existing labels + - **Create/Update label templates** — design and edit labels + - **Delete label templates** — remove labels + - **Print labels** — send labels to the printer + +### 5. Configure Module Settings + +1. Go to **Home > Setup > Modules/Applications** +2. Click on **MokoDoliDymo** to access settings +3. Configure printer connection and default label sizes + +## Troubleshooting + +### Module Not Appearing + +- Verify the module directory is named `mokodolidymo` (lowercase) +- Clear Dolibarr cache and refresh +- Check PHP syntax: `php -l src/core/modules/modMokoDoliDymo.class.php` +- Ensure `$dolibarr_main_document_root_alt` is set in `conf/conf.php` + +### Permission Errors + +- Ensure the web server user has read access to all module files +- Verify the module is activated before assigning permissions + +## Uninstallation + +1. Go to **Home > Setup > Modules/Applications** +2. Find **MokoDoliDymo** and click **Deactivate** +3. Optionally remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/mokodolidymo + ``` + +## Next Steps + +- Read the [Development Guide](development.md) if you want to extend the module +- Check the [Changelog](changelog.md) for version history + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliDymo/module-id-policy.-.-.md b/MokoConsulting/MokoDoliDymo/module-id-policy.-.-.md new file mode 100644 index 0000000..64be6ff --- /dev/null +++ b/MokoConsulting/MokoDoliDymo/module-id-policy.-.-.md @@ -0,0 +1,34 @@ +← [Home](Home) + +# Module ID Policy + +## MokoDoliDymo Module ID + +**Module ID: 185072** — registered in the [Moko Consulting module registry](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md). + +This ID is **permanent and immutable**. It is stored in `$this->numero` in the module descriptor and must never be changed after deployment. Changing it would break all existing Dolibarr installations using this module. + +## Dolibarr Module ID Ranges + +| Range | Purpose | +|-------|---------| +| 0 – 94,999 | Core Dolibarr modules | +| 95,000 – 99,999 | Community modules (official repos) | +| 100,000 – 499,999 | Third-party public modules | +| 500,000 – 599,999 | Private/unlisted modules | +| 600,000+ | Development/temporary (never distribute) | + +MokoDoliDymo's ID (185072) falls in the third-party public range. + +## References + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Moko Consulting Module Registry](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md) + +--- + +*Repo: [MokoDoliDymo](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliDymo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliG/CHANGELOG.md b/MokoConsulting/MokoDoliG/CHANGELOG.md new file mode 100644 index 0000000..d632ab2 --- /dev/null +++ b/MokoConsulting/MokoDoliG/CHANGELOG.md @@ -0,0 +1,47 @@ +← [Home](Home) + +# CHANGELOG FOR MODULE MOKODOLIG + +## [01.00.00] - Unreleased +### Added +- Initial module structure following [moko-platform](https://github.com/mokoconsulting-tech/MokoCodingDefaults) +- Core module descriptor with Google services focus +- **License key validation system** - Requires valid license from Moko release system +- License management interface in admin setup page +- Admin pages (setup, tools, about) for configuration +- Language files (en_US) with Google services terminology +- Development scripts (build, test, run) +- Validation scripts for code quality +- PHPUnit test infrastructure +- Security hardening with blank index files +- OAuth 2.0 authentication framework placeholder +- Google Sign-In / SSO authentication integration +- User auto-provisioning from Google accounts +- Gmail API integration foundation +- Google Drive integration foundation +- Automated Dolibarr backup upload to Google Drive +- Backup retention and management system +- Google Calendar sync foundation +- Google Meet integration foundation +- Google Voice integration foundation + +### Changed +- N/A + +### Fixed +- N/A + +### Security +- OAuth 2.0 authentication preparation +- Token encryption infrastructure +- Secure API communication setup + +## 01.00.00 + +--- + +*Repo: [MokoDoliG](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliG) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliG/DEVELOPMENT.md b/MokoConsulting/MokoDoliG/DEVELOPMENT.md new file mode 100644 index 0000000..d13f127 --- /dev/null +++ b/MokoConsulting/MokoDoliG/DEVELOPMENT.md @@ -0,0 +1,247 @@ +← [Home](Home) + +# MokoDoliG Development Guide + +## Overview + +MokoDoliG is a comprehensive Google Workspace integration module for Dolibarr, providing: +- Google Sign-In / OAuth authentication +- Gmail integration +- Google Drive file management and automated backup uploads +- Google Calendar synchronization +- Google Meet video conferencing +- Google Voice telephony + +This project follows [moko-platform (MokoCodingDefaults)](https://github.com/mokoconsulting-tech/MokoCodingDefaults) for coding conventions, project structure, and best practices. + +## Module Information + +- **Module ID**: 185057 +- **Version**: 01.00.00 +- **License**: GPL-3.0-or-later +- **Vendor**: Moko Consulting + +## Repository Structure + +The repository follows both Dolibarr standards and modern PHP practices: + +### Dolibarr Standard Directories + +- `admin/` - Administrative interface pages (setup, tools, about) +- `core/modules/` - Module descriptor (modMokoDoliG.class.php) +- `class/` - Dolibarr-style classes (for compatibility) +- `lib/` - Library functions and helpers +- `langs/` - Language files (en_US) +- `css/` - Stylesheets +- `js/` - JavaScript files +- `img/` - Images and logos +- `sql/` - Database schemas and update scripts +- `migrations/` - Data migration scripts + +### Modern PHP Structure + +- `src/` - PSR-4 autoloaded modern PHP classes + - `Auth/` - Google authentication (GoogleAuthenticator) + - `Services/` - Google service integrations (Gmail, Drive, Calendar, Meet, Voice) + - `Backup/` - Backup management (BackupManager) + - `Helpers/` - Utility classes + +### Development Infrastructure + +- `tests/` - PHPUnit tests +- `scripts/dev/` - Development scripts (build, test, run) +- `scripts/validate/` - Validation scripts (syntax, changelog, versions, security) +- Configuration: composer.json, phpcs.xml, phpstan.neon, phpunit.xml +- Standards: .editorconfig, .gitignore, .gitattributes + +## Features Implemented + +### ✅ Repository Structure +- Complete Dolibarr-compliant directory structure +- Modern `src/` directory with PSR-4 namespacing +- Security hardening with blank index files in all directories +- Proper .htaccess configuration + +### ✅ Module Descriptor +- Module ID: 185057 +- Complete metadata and configuration +- Permission structure +- Menu integration ready + +### ✅ Admin Interface +- Setup page for configuration +- Tools page for utilities +- About page for information +- Tabbed navigation system + +### ✅ Google Services Foundation + +#### Authentication (src/Auth/) +- GoogleAuthenticator class for OAuth 2.0 +- Single Sign-On (SSO) support +- User auto-provisioning +- Domain restrictions +- Account linking/unlinking + +#### Google Drive (src/Services/Drive/) +- DriveService class for file operations +- Upload/download capabilities +- Folder management +- File sharing + +#### Backup Management (src/Backup/) +- BackupManager class +- Automated backup uploads to Google Drive +- Retention policies +- Backup listing and management + +### ✅ Development Tools +- Build script (syntax check, PHPCS, PHPStan) +- Test runner (PHPUnit) +- Development server launcher +- Validation scripts for code quality + +### ✅ Documentation +- Comprehensive README with features and usage +- CHANGELOG with version history +- CONTRIBUTING guidelines +- CODE_OF_CONDUCT +- This DEVELOPMENT guide + +### ✅ Testing Infrastructure +- PHPUnit configuration +- Test bootstrap +- Example test class +- Test scripts + +### ✅ Code Quality Tools +- PHP CodeSniffer (PSR-12) +- PHPStan (Level 5) +- EditorConfig +- Validation scripts + +## Next Steps (TODO) + +### Google API Integration +- [ ] Implement actual Google API client library integration +- [ ] Complete OAuth token exchange +- [ ] User info retrieval from Google +- [ ] Gmail API implementation +- [ ] Calendar API implementation +- [ ] Meet API implementation +- [ ] Voice API implementation + +### Authentication +- [ ] Database schema for Google account linking +- [ ] Login page integration +- [ ] User provisioning logic +- [ ] Session management +- [ ] OAuth callback handler + +### Backup System +- [ ] Database table for backup tracking +- [ ] Scheduled uploads (cron) +- [ ] Retention policy implementation +- [ ] Backup restoration +- [ ] Encryption support + +### Testing +- [ ] Unit tests for all classes +- [ ] Integration tests with Google APIs +- [ ] Mock Google API responses +- [ ] End-to-end testing + +### UI/UX +- [ ] Configuration wizard +- [ ] Connection status indicators +- [ ] Sync progress indicators +- [ ] Error handling and user feedback +- [ ] Module logo/icon + +## Development Workflow + +1. **Install dependencies**: + ```bash + composer install + ``` + +2. **Run build checks**: + ```bash + ./scripts/dev/build.sh + ``` + +3. **Run tests**: + ```bash + ./scripts/dev/test.sh + ``` + +4. **Validate code**: + ```bash + ./scripts/validate/php_syntax.sh + ./scripts/validate/version_alignment.sh + ./scripts/validate/changelog.sh + ./scripts/validate/paths.sh + ``` + +5. **Development server** (for testing outside Dolibarr): + ```bash + ./scripts/dev/run.sh + ``` + +## Integration with Dolibarr + +To install and test with Dolibarr: + +1. Copy the module to Dolibarr's custom directory: + ```bash + cp -r . /path/to/dolibarr/htdocs/custom/mokodolig/ + ``` + +2. Log in to Dolibarr as administrator + +3. Go to: Home → Setup → Modules/Applications + +4. Find "MokoDoliG" and activate it + +5. Configure Google credentials in module settings + +## Google API Setup + +1. Create project in Google Cloud Console +2. Enable required APIs: + - Gmail API + - Google Drive API + - Google Calendar API + - People API (for user info) +3. Create OAuth 2.0 credentials +4. Add authorized redirect URI: `https://your-dolibarr.com/custom/mokodolig/oauth/callback.php` +5. Configure OAuth consent screen + +## Security Considerations + +- OAuth tokens stored encrypted +- Domain restrictions for SSO +- Input validation on all forms +- CSRF protection +- Rate limiting for API calls +- Audit logging + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. + +## Support + +For questions or issues, contact: hello@mokoconsulting.tech + +--- + +© 2025 Moko Consulting | GPL-3.0-or-later + +--- + +*Repo: [MokoDoliG](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliG) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliG/Home.md b/MokoConsulting/MokoDoliG/Home.md new file mode 100644 index 0000000..d24f5dc --- /dev/null +++ b/MokoConsulting/MokoDoliG/Home.md @@ -0,0 +1,30 @@ +# MokoDoliG + +A Dolibarr module to extend the interface to Google Workspace. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliG) | + +--- + +## Documentation + +| Page | Description | +|---|---| +| [CHANGELOG](CHANGELOG) | ← [Home](Home) | +| [DEVELOPMENT](DEVELOPMENT) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliG](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliG) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliG/update-server.-.-.md b/MokoConsulting/MokoDoliG/update-server.-.-.md new file mode 100644 index 0000000..56c2954 --- /dev/null +++ b/MokoConsulting/MokoDoliG/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliG/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliG](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliG) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliGithub/Home.md b/MokoConsulting/MokoDoliGithub/Home.md new file mode 100644 index 0000000..61cdab4 --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/Home.md @@ -0,0 +1,43 @@ +# MokoDoliGithub + +A Dolibarr module to bridge to Github + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliGithub/README.md b/MokoConsulting/MokoDoliGithub/README.md new file mode 100644 index 0000000..c8c1776 --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/README.md @@ -0,0 +1,148 @@ +← [Home](Home) + +# Documentation Index + +Welcome to the moko-platform Dolibarr Template documentation. This guide will help you navigate all available documentation resources. + +## Quick Links + +- [Installation Guide](installation.md) - Get started with installing the template +- [Development Guide](development.md) - Learn how to develop Dolibarr modules +- [Module ID Policy](module-id-policy.md) - Understand module ID assignment process +- [Changelog](changelog.md) - Track version history and changes + +## Documentation Structure + +### For New Users + +If you're new to this template, start here: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Configuration and setup + - Troubleshooting common issues + +2. **[Module ID Policy](module-id-policy.md)** + - Understanding module IDs + - Development vs. production IDs + - How to request an official ID + - Best practices + +### For Developers + +If you're developing a module, these guides will help: + +1. **[Development Guide](development.md)** + - Module structure and organization + - Module descriptor configuration + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + - Commit message guidelines + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Installation Guide](installation.md) to set up the template, then review the [Development Guide](development.md) for building your module. + +**Q: What module ID should I use?** +A: Use an ID greater than 600,000 during development. See the [Module ID Policy](module-id-policy.md) for details. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +**Q: Where are the code examples?** +A: The [Development Guide](development.md) contains numerous code examples and best practices. + +### Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) + +### moko-platform + +- [MokoConsulting Tech GitHub](https://github.com/mokoconsulting-tech) +- Template Repository: [moko-platform-Template-Dolibarr](https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 600001; // Development module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/ +git clone repo-url +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Template Version**: 1.0.0 +- **Last Updated**: 2026-01-16 +- **Minimum Dolibarr Version**: 12.0 +- **PHP Version**: 7.4+ + +--- + +**Next Steps**: +- New to the template? Start with [Installation Guide](installation.md) +- Ready to develop? Check out [Development Guide](development.md) +- Need to request a module ID? Review [Module ID Policy](module-id-policy.md) + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliGithub/changelog.md b/MokoConsulting/MokoDoliGithub/changelog.md new file mode 100644 index 0000000..4df65db --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/changelog.md @@ -0,0 +1,70 @@ +← [Home](Home) + +# Changelog + +All notable changes to this project template will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Comprehensive README.md with project overview and usage instructions +- Module ID policy documentation +- Installation guide with detailed setup instructions +- Development guide with best practices and examples +- Contributing guidelines +- Documentation structure following moko-platform + +## [1.0.0] - 2026-01-16 + +### Added +- Initial template structure for Dolibarr modules +- Basic documentation framework +- Module ID policy requiring issue-based requests +- Support for temporary development IDs (600,000+) + +--- + +## Template Usage Notes + +When using this template for your module: + +1. Copy this changelog to your project +2. Update the version numbers as you develop +3. Document all changes in the appropriate category: + - **Added** for new features + - **Changed** for changes in existing functionality + - **Deprecated** for soon-to-be removed features + - **Removed** for now removed features + - **Fixed** for any bug fixes + - **Security** for vulnerability fixes + +Example entry: +```markdown +## [1.1.0] - 2026-02-15 + +### Added +- New feature X for handling Y +- Support for Z functionality + +### Fixed +- Bug in module activation +- Permission check in admin page + +### Changed +- Updated module descriptor format +- Improved error handling +``` + +[Unreleased]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/releases/tag/v1.0.0 + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliGithub/development.md b/MokoConsulting/MokoDoliGithub/development.md new file mode 100644 index 0000000..27f9b3c --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/development.md @@ -0,0 +1,323 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - use 600,000+ for development + $this->numero = 600001; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Development Phase + +Use module ID > 600,000: + +```php +$this->numero = 600001; +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliGithub/installation.md b/MokoConsulting/MokoDoliGithub/installation.md new file mode 100644 index 0000000..20430e1 --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/installation.md @@ -0,0 +1,173 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring your Dolibarr module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 12.0 or higher +- **PHP**: Version 7.4 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - gd or imagick + - curl + - json + - xml + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr's custom directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone this template repository: + +```bash +git clone https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr.git yourmodule +``` + +Replace `yourmodule` with your desired module name (lowercase, no spaces). + +### 2. Rename and Configure + +Navigate to the module directory: + +```bash +cd yourmodule +``` + +Rename the module descriptor file: + +```bash +mv modYourmodule.class.php modYourModuleName.class.php +``` + +### 3. Configure Module ID + +Open the module descriptor file and set a temporary module ID greater than 600,000: + +```php +// In modYourModuleName.class.php +$this->numero = 600001; // Use a number > 600,000 for development +``` + +**Important:** Before publishing, request an official module ID by creating an issue in the repository. + +### 4. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/yourmodule + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type f -exec chmod 644 {} \; +``` + +### 5. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find your module in the list +4. Click the **Activate** button + +### 6. Configure Module Settings (if applicable) + +After activation: + +1. Go to **Home → Setup → Modules/Applications** +2. Click on your module name to access its configuration page +3. Configure any required settings +4. Save changes + +## Database Setup + +If your module requires database tables: + +### Automatic Setup + +The module descriptor can handle automatic table creation during activation. Ensure your SQL files are in the `sql/` directory: + +``` +sql/ +├── llx_yourmodule_table.sql +└── llx_yourmodule_table.key.sql +``` + +### Manual Setup + +Alternatively, run SQL scripts manually: + +```bash +mysql -u username -p database_name < sql/llx_yourmodule_table.sql +``` + +## Troubleshooting + +### Module Not Appearing + +- Clear Dolibarr cache: Delete `/documents/install.lock` and refresh +- Check file permissions +- Verify PHP syntax errors: `php -l modYourModuleName.class.php` + +### Permission Errors + +- Ensure Apache/Nginx user has read access to all module files +- Check `conf.php` file permissions in Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Check SQL file syntax +- Ensure database user has CREATE TABLE permissions + +## Uninstallation + +To remove the module: + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find your module and click **Deactivate** +3. Optionally, remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/yourmodule + ``` + +**Note:** Deactivating the module does not remove database tables. To remove data: + +```sql +DROP TABLE llx_yourmodule_table; +``` + +## Next Steps + +- Review the [Development Guide](development.md) to start customizing your module +- Check the [Module ID Policy](module-id-policy.md) before distribution +- Read the [Changelog](changelog.md) for version history + +## Support + +For installation issues: +- Create an issue in the repository +- Check Dolibarr logs: `/documents/dolibarr.log` +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliGithub/module-id-policy.-.-.md b/MokoConsulting/MokoDoliGithub/module-id-policy.-.-.md new file mode 100644 index 0000000..de15a7e --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliGithub/update-server.-.-.md b/MokoConsulting/MokoDoliGithub/update-server.-.-.md new file mode 100644 index 0000000..2e8797e --- /dev/null +++ b/MokoConsulting/MokoDoliGithub/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliGithub/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliGithub](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliGithub) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliHRM/API.md b/MokoConsulting/MokoDoliHRM/API.md new file mode 100644 index 0000000..77c862b --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/API.md @@ -0,0 +1,385 @@ +← [Home](Home) + +# MokoDoliHRM API Documentation + +## Classes Overview + +### MokoEmployee Class + +Located in: `src/class/employee.class.php` + +The MokoEmployee class manages employee records in the system. + +#### Properties + +| Property | Type | Description | +|----------|------|-------------| +| id | int | Employee ID (primary key) | +| ref | string | Employee reference (e.g., EMP00001) | +| firstname | string | First name | +| lastname | string | Last name | +| email | string | Email address | +| phone | string | Phone number | +| address | string | Street address | +| city | string | City | +| zip | string | Zip/postal code | +| country_code | string | Country code (ISO 3166-1 alpha-2) | +| date_birth | timestamp | Date of birth | +| position | string | Job position/title | +| department | string | Department name | +| date_hire | timestamp | Hire date | +| date_termination | timestamp | Termination date | +| status | int | Status (0=Draft, 1=Active, 9=Terminated) | +| social_security_number | string | Social security number | +| bank_account | string | Bank account number | +| note_public | string | Public notes | +| note_private | string | Private notes | + +#### Methods + +##### create($user, $notrigger = 0) +Creates a new employee record in the database. + +**Parameters:** +- `$user` (User): User object performing the creation +- `$notrigger` (int): 0 = launch triggers, 1 = disable triggers + +**Returns:** +- int: Employee ID if successful, negative value on error + +**Example:** +```php +$employee = new MokoEmployee($db); +$employee->firstname = 'John'; +$employee->lastname = 'Doe'; +$employee->email = 'john.doe@example.com'; +$employee->status = 1; +$result = $employee->create($user); +``` + +##### fetch($id, $ref = null) +Loads an employee record from the database. + +**Parameters:** +- `$id` (int): Employee ID +- `$ref` (string): Employee reference (optional, alternative to ID) + +**Returns:** +- int: 1 if found and loaded, 0 if not found, negative value on error + +**Example:** +```php +$employee = new MokoEmployee($db); +$result = $employee->fetch(123); +// or +$result = $employee->fetch(0, 'EMP00001'); +``` + +##### update($user, $notrigger = 0) +Updates an existing employee record in the database. + +**Parameters:** +- `$user` (User): User object performing the update +- `$notrigger` (int): 0 = launch triggers, 1 = disable triggers + +**Returns:** +- int: 1 if successful, negative value on error + +**Example:** +```php +$employee = new MokoEmployee($db); +$employee->fetch(123); +$employee->position = 'Senior Developer'; +$result = $employee->update($user); +``` + +##### delete($user, $notrigger = 0) +Deletes an employee record from the database. + +**Parameters:** +- `$user` (User): User object performing the deletion +- `$notrigger` (int): 0 = launch triggers, 1 = disable triggers + +**Returns:** +- int: 1 if successful, negative value on error + +**Example:** +```php +$employee = new MokoEmployee($db); +$employee->fetch(123); +$result = $employee->delete($user); +``` + +##### getNextNumRef() +Generates the next available employee reference number. + +**Returns:** +- string: Next reference number (e.g., EMP00001) + +##### getFullName() +Returns the employee's full name with leading/trailing whitespace removed. + +**Returns:** +- string: Full name (Firstname Lastname, trimmed) + +##### getLibStatut($mode = 0) +Returns the status label for the employee. + +**Parameters:** +- `$mode` (int): Display mode (0-5) + +**Returns:** +- string: Status label with appropriate formatting + +--- + +### MokoContract Class + +Located in: `src/class/contract.class.php` + +The MokoContract class manages employment contract records. + +#### Properties + +| Property | Type | Description | +|----------|------|-------------| +| id | int | Contract ID (primary key) | +| ref | string | Contract reference (e.g., CONT00001) | +| fk_employee | int | Employee ID (foreign key) | +| contract_type | string | Contract type (permanent, temporary, etc.) | +| date_start | timestamp | Contract start date | +| date_end | timestamp | Contract end date | +| salary | float | Salary amount | +| salary_currency | string | Currency code | +| salary_period | string | Payment period (monthly, weekly, hourly) | +| working_hours | int | Working hours per week | +| annual_leave_days | int | Annual leave days | +| status | int | Status (0=Draft, 1=Active, 9=Terminated) | +| note_public | string | Public notes | +| note_private | string | Private notes | + +#### Methods + +The MokoContract class implements the same CRUD methods as MokoEmployee: +- `create($user, $notrigger = 0)` +- `fetch($id, $ref = null)` +- `update($user, $notrigger = 0)` +- `delete($user, $notrigger = 0)` +- `getNextNumRef()` - Returns references like CONT00001 +- `getLibStatut($mode = 0)` + +--- + +### MokoPayroll Class + +Located in: `src/class/payroll.class.php` + +The MokoPayroll class manages payroll records. + +#### Properties + +| Property | Type | Description | +|----------|------|-------------| +| id | int | Payroll ID (primary key) | +| ref | string | Payroll reference (e.g., PAY00001) | +| fk_employee | int | Employee ID (foreign key) | +| fk_contract | int | Contract ID (foreign key, optional) | +| period_start | timestamp | Payroll period start date | +| period_end | timestamp | Payroll period end date | +| gross_salary | float | Gross salary amount | +| net_salary | float | Net salary amount | +| tax_amount | float | Tax amount | +| social_security | float | Social security contributions | +| bonuses | float | Bonus amount | +| deductions | float | Deductions amount | +| payment_date | timestamp | Payment date | +| payment_method | string | Payment method | +| status | int | Status (0=Draft, 1=Validated, 2=Paid, 9=Cancelled) | +| note_public | string | Public notes | +| note_private | string | Private notes | + +#### Methods + +The MokoPayroll class implements the same CRUD methods as MokoEmployee: +- `create($user, $notrigger = 0)` +- `fetch($id, $ref = null)` +- `update($user, $notrigger = 0)` +- `delete($user, $notrigger = 0)` +- `getNextNumRef()` - Returns references like PAY00001 +- `getLibStatut($mode = 0)` + +--- + +## Status Values + +### Employee & Contract Status +- `0` - Draft +- `1` - Active +- `9` - Terminated + +### Payroll Status +- `0` - Draft +- `1` - Validated +- `2` - Paid +- `9` - Cancelled + +--- + +## Database Schema + +### llx_mokodolihrm_employee Table + +Primary table for storing employee information. + +**Indexes:** +- Primary key on `rowid` +- Unique key on `ref` + `entity` +- Index on `entity` +- Index on `status` + +### llx_mokodolihrm_contract Table + +Stores employment contract information with foreign key to employees. + +**Indexes:** +- Primary key on `rowid` +- Unique key on `ref` + `entity` +- Index on `entity` +- Index on `fk_employee` +- Index on `status` +- Foreign key constraint to `llx_mokodolihrm_employee` + +### llx_mokodolihrm_payroll Table + +Stores payroll records with foreign keys to employees and contracts. + +**Indexes:** +- Primary key on `rowid` +- Unique key on `ref` + `entity` +- Index on `entity` +- Index on `fk_employee` +- Index on `fk_contract` +- Index on `status` +- Foreign key constraint to `llx_mokodolihrm_employee` +- Foreign key constraint to `llx_mokodolihrm_contract` + +--- + +## Usage Examples + +### Creating an Employee with Contract and Payroll + +```php +// Load Dolibarr environment +require_once DOL_DOCUMENT_ROOT.'/main.inc.php'; +require_once DOL_DOCUMENT_ROOT.'/custom/mokodolihrm/class/employee.class.php'; +require_once DOL_DOCUMENT_ROOT.'/custom/mokodolihrm/class/contract.class.php'; +require_once DOL_DOCUMENT_ROOT.'/custom/mokodolihrm/class/payroll.class.php'; + +// Create employee +$employee = new MokoEmployee($db); +$employee->firstname = 'John'; +$employee->lastname = 'Doe'; +$employee->email = 'john.doe@example.com'; +$employee->position = 'Software Developer'; +$employee->department = 'IT'; +$employee->date_hire = dol_now(); +$employee->status = 1; +$employee_id = $employee->create($user); + +if ($employee_id > 0) { + // Create contract + $contract = new MokoContract($db); + $contract->fk_employee = $employee_id; + $contract->contract_type = 'permanent'; + $contract->date_start = dol_now(); + $contract->salary = 5000; + $contract->salary_currency = 'USD'; + $contract->salary_period = 'monthly'; + $contract->working_hours = 40; + $contract->annual_leave_days = 20; + $contract->status = 1; + $contract_id = $contract->create($user); + + if ($contract_id > 0) { + // Create payroll + $payroll = new MokoPayroll($db); + $payroll->fk_employee = $employee_id; + $payroll->fk_contract = $contract_id; + $payroll->period_start = dol_time_plus_duree(dol_now(), -1, 'm'); + $payroll->period_end = dol_now(); + $payroll->gross_salary = 5000; + $payroll->tax_amount = 750; + $payroll->social_security = 500; + $payroll->net_salary = 3750; + $payroll->payment_date = dol_now(); + $payroll->payment_method = 'bank_transfer'; + $payroll->status = 2; // Paid + $payroll_id = $payroll->create($user); + } +} +``` + +### Listing All Active Employees + +```php +$sql = "SELECT rowid, ref, firstname, lastname, position, department"; +$sql .= " FROM ".MAIN_DB_PREFIX."mokodolihrm_employee"; +$sql .= " WHERE status = 1"; +$sql .= " ORDER BY lastname, firstname"; + +$resql = $db->query($sql); +if ($resql) { + while ($obj = $db->fetch_object($resql)) { + echo $obj->ref.' - '.$obj->firstname.' '.$obj->lastname; + echo ' ('.$obj->position.', '.$obj->department.')'."\n"; + } +} +``` + +--- + +## Error Handling + +All methods return negative values on error. Check the `$object->error` and `$object->errors` properties for details: + +```php +$result = $employee->create($user); +if ($result < 0) { + echo "Error: ".$employee->error; + foreach ($employee->errors as $error) { + echo "- ".$error."\n"; + } +} +``` + +--- + +## Permissions + +Check permissions before performing operations: + +```php +// Check read permission +if ($user->rights->mokodolihrm->employee->read) { + // Allow reading employee data +} + +// Check write permission +if ($user->rights->mokodolihrm->employee->write) { + // Allow creating/updating employee data +} + +// Check delete permission +if ($user->rights->mokodolihrm->employee->delete) { + // Allow deleting employee data +} +``` + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliHRM/FAQ.md b/MokoConsulting/MokoDoliHRM/FAQ.md new file mode 100644 index 0000000..4226d9b --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/FAQ.md @@ -0,0 +1,333 @@ +← [Home](Home) + +# MokoDoliHRM Frequently Asked Questions (FAQ) + +## General Questions + +### Q: What is MokoDoliHRM? +**A:** MokoDoliHRM is a comprehensive Human Resources Management module for Dolibarr ERP/CRM that provides tools for managing employees, employment contracts, and payroll processing. + +### Q: What version of Dolibarr is required? +**A:** MokoDoliHRM requires Dolibarr version 13.0 or higher and PHP 7.0 or higher. + +### Q: Is MokoDoliHRM free? +**A:** Yes, MokoDoliHRM is open source software released under the GNU General Public License v3.0. + +### Q: Can I use MokoDoliHRM in a production environment? +**A:** Yes, but we recommend thorough testing in a development environment first and ensuring you have proper backups in place. + +## Installation & Setup + +### Q: How do I install MokoDoliHRM? +**A:** See the detailed [Installation Guide](INSTALLATION.md). In brief: +1. Copy the module files to `htdocs/custom/mokodolihrm/` +2. Set proper permissions +3. Activate the module in Dolibarr +4. Configure user permissions + +### Q: The module doesn't appear in the modules list. What should I do? +**A:** +- Verify files are in the correct location: `htdocs/custom/mokodolihrm/` +- Check file permissions (web server must be able to read the files) +- Clear Dolibarr cache by removing `documents/install/locks/*.lock` +- Refresh the modules page in your browser + +### Q: Database tables aren't created automatically. What should I do? +**A:** +- Manually run the SQL script: `mysql -u username -p database < src/sql/llx_mokodolihrm.sql` +- Replace `llx_` with your Dolibarr table prefix if different +- Ensure your database user has CREATE TABLE privileges + +### Q: Can I customize the module? +**A:** Yes, the module is open source and can be modified. However, we recommend creating a fork or custom version to preserve your changes during updates. + +## Employee Management + +### Q: What information can I store about employees? +**A:** Employee records include: +- Personal information (name, birth date, address) +- Contact details (email, phone) +- Employment information (position, department, hire date) +- Financial information (social security number, bank account) +- Notes (public and private) + +### Q: Can I track employee history? +**A:** The module tracks creation and modification dates. For detailed history tracking, consider integrating with Dolibarr's audit log module or implementing custom triggers. + +### Q: What happens if I delete an employee? +**A:** ⚠️ Deleting an employee will cascade delete all associated contracts and payroll records. Consider setting the status to "Terminated" instead. + +### Q: Can I import employees from another system? +**A:** The module doesn't include built-in import functionality. Options include: +- Manual entry for small numbers of employees +- Using Dolibarr's import module +- Writing a custom import script using the API +- Direct database import (requires technical knowledge) + +### Q: How do I handle employee promotions or role changes? +**A:** +1. Edit the employee record to update position and department +2. Create a new contract reflecting the new terms +3. Terminate or end the old contract + +## Contract Management + +### Q: What types of contracts are supported? +**A:** The module supports: +- Permanent (full-time, ongoing) +- Temporary (fixed-term) +- Consultant (contract-based) +- Intern (training/educational) + +You can also enter custom contract types. + +### Q: Can an employee have multiple contracts? +**A:** Yes, an employee can have multiple contracts (e.g., historical contracts, concurrent part-time positions). + +### Q: How do I handle contract renewals? +**A:** +1. Set an end date on the current contract +2. Create a new contract with the new terms and start date +3. Both contracts remain in the system for historical tracking + +### Q: Can I track probation periods? +**A:** While there's no dedicated probation field, you can: +- Use the notes field to record probation end date +- Create a short-term contract for the probation period +- Create a permanent contract after successful completion + +### Q: What currencies are supported? +**A:** The salary currency field accepts any 3-letter currency code (USD, EUR, GBP, etc.). Display formatting follows Dolibarr's regional settings. + +## Payroll Management + +### Q: Does MokoDoliHRM calculate taxes automatically? +**A:** No, the module does not include automatic tax calculations. You must calculate taxes according to your jurisdiction's rules and enter the amounts manually. + +### Q: Can I integrate with payroll services? +**A:** The module doesn't have built-in integrations. You would need to: +- Export data from MokoDoliHRM +- Import into your payroll service +- Or develop a custom integration using the API + +### Q: How often should I create payroll records? +**A:** Create payroll records according to your pay schedule (weekly, bi-weekly, monthly, etc.). Each payment period should have its own record. + +### Q: Can I correct a payroll mistake? +**A:** +- If status is "Draft": Edit the record directly +- If status is "Validated" or "Paid": Create a correction/adjustment record or set to cancelled and create a new one + +### Q: Where is the net salary calculated? +**A:** Net salary is not automatically calculated. You must enter it based on: +``` +Net Salary = Gross Salary - Tax Amount - Social Security - Deductions + Bonuses +``` + +### Q: Can I generate payslips? +**A:** The current version doesn't include payslip generation. You can: +- Export data and use external tools +- Create custom reports using Dolibarr's reporting features +- Extend the module with payslip generation functionality + +## Permissions & Security + +### Q: How do I control who can access HR data? +**A:** Use Dolibarr's permission system: +1. Go to **Home → Setup → Users & Groups** +2. Select a user or group +3. Configure MokoDoliHRM permissions (Read, Write, Delete for each module) + +### Q: Can I limit access to sensitive information? +**A:** +- Use private notes for sensitive information +- Grant "Read" permission only to users who need access +- Consider custom modifications for field-level security + +### Q: Is the data encrypted? +**A:** Data is stored in the Dolibarr database. Encryption depends on: +- Database configuration (enable encryption at rest) +- HTTPS for data in transit +- Dolibarr's security settings + +### Q: Should I backup HR data separately? +**A:** Yes, HR data is critical. We recommend: +- Regular automated database backups +- Separate backups before major changes +- Testing restoration procedures +- Offsite backup storage + +## Customization & Development + +### Q: Can I add custom fields? +**A:** Yes, but it requires: +1. Modifying the database schema (add columns) +2. Updating class files to include new fields +3. Modifying UI pages to display/edit fields +4. Following moko-platform structure + +### Q: How do I add new features? +**A:** +1. Fork the repository +2. Add your features following the existing code structure +3. Test thoroughly +4. Consider contributing back to the main project + +### Q: Can I change the look and feel? +**A:** Yes, through: +- Dolibarr themes (affects entire system) +- Custom CSS in the module +- Modifying page templates + +### Q: Is there an API? +**A:** The classes provide programmatic access. See [API Documentation](API.md) for details on using the PHP classes. For REST API, you'd need to extend Dolibarr's API module. + +## Data & Reporting + +### Q: How do I export data? +**A:** Options include: +- Using Dolibarr's export module +- Direct database queries +- Custom export scripts +- Using the search/filter features and copying visible data + +### Q: Can I generate reports? +**A:** +- Use Dolibarr's built-in reporting features +- Export data to external tools (Excel, BI software) +- Develop custom reports as module extensions + +### Q: How long should I keep records? +**A:** This depends on: +- Legal requirements in your jurisdiction +- Company policy +- Type of records (employee files, payroll, contracts) + +Consult with legal counsel for your specific requirements. + +### Q: Can I archive old records? +**A:** The module doesn't include an archive feature. Options: +- Set status to "Terminated" for ended employment +- Export old records to external storage +- Keep all records in the database (recommended for compliance) + +## Troubleshooting + +### Q: Why can't I see the MokoDoliHRM menu? +**A:** +- Module may not be activated +- You may not have Read permission +- Browser cache may need clearing + +### Q: Employee list is slow to load +**A:** +- Use search filters to limit results +- Check database indexes are created +- Optimize Dolibarr database +- Upgrade to faster hardware if needed + +### Q: I see "Error: Permission denied" +**A:** Your user account doesn't have the required permission. Contact your administrator to grant appropriate access. + +### Q: Changes aren't being saved +**A:** +- Check for error messages +- Verify Write permission +- Check database connection +- Review Dolibarr error log + +### Q: Where are error logs located? +**A:** Dolibarr logs are typically at: `documents/dolibarr.log` + +## Compliance & Legal + +### Q: Is MokoDoliHRM GDPR compliant? +**A:** The module provides tools for HR management, but compliance depends on how you use it: +- Implement proper access controls +- Have data processing agreements +- Implement right to erasure procedures +- Maintain audit logs +- Consult with a GDPR specialist + +### Q: Can employees access their own data? +**A:** Not by default. You would need to: +- Create employee user accounts +- Grant them limited Read permissions +- Possibly develop an employee self-service portal + +### Q: How do I handle data protection requests? +**A:** +- Right to access: Export employee's data +- Right to rectification: Edit employee records +- Right to erasure: Delete employee record (be aware of legal retention requirements) + +### Q: What about tax compliance? +**A:** The module is a record-keeping tool. You are responsible for: +- Correct tax calculations +- Timely tax payments +- Compliance with local regulations +- Proper reporting + +Consult with tax professionals for your jurisdiction. + +## Support & Community + +### Q: Where can I get help? +**A:** +- Read the documentation (README, Installation Guide, User Guide, API docs) +- Check this FAQ +- Review the code comments +- Submit issues on the project repository + +### Q: Can I contribute to the project? +**A:** Yes! Contributions are welcome: +- Bug fixes +- New features +- Documentation improvements +- Translations +- Testing and feedback + +### Q: How do I report bugs? +**A:** +1. Check if the issue already exists +2. Gather information (version, error messages, steps to reproduce) +3. Submit a detailed issue report +4. Include screenshots if relevant + +### Q: Are there commercial support options? +**A:** Contact Moko Consulting for professional support, customization, and training services. + +## Upgrading & Maintenance + +### Q: How do I upgrade to a new version? +**A:** +1. Backup your database and files +2. Deactivate the module +3. Replace module files +4. Reactivate the module +5. Test thoroughly + +### Q: Will upgrades delete my data? +**A:** No, data remains in the database. However, always backup before upgrading. + +### Q: How often should I update? +**A:** Update when: +- Security fixes are released +- New features you need are added +- Bug fixes address issues you're experiencing +- Compatibility updates for Dolibarr are released + +### Q: Can I skip versions when upgrading? +**A:** Generally yes, but review release notes for any special upgrade procedures or breaking changes. + +--- + +**Still have questions?** Check the [User Guide](USER_GUIDE.md) or [API Documentation](API.md) for more detailed information. + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliHRM/Home.md b/MokoConsulting/MokoDoliHRM/Home.md new file mode 100644 index 0000000..07c10e0 --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/Home.md @@ -0,0 +1,41 @@ +# MokoDoliHRM + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [INSTALLATION](INSTALLATION) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [API](API) | ← [Home](Home) | +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [FAQ](FAQ) | ← [Home](Home) | +| [USER_GUIDE](USER_GUIDE) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliHRM/INSTALLATION.md b/MokoConsulting/MokoDoliHRM/INSTALLATION.md new file mode 100644 index 0000000..ea68c1d --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/INSTALLATION.md @@ -0,0 +1,236 @@ +← [Home](Home) + +# MokoDoliHRM Installation Guide + +## Prerequisites + +Before installing MokoDoliHRM, ensure you have: + +- Dolibarr ERP/CRM version 13.0 or higher +- PHP version 7.0 or higher +- MySQL or MariaDB database +- Administrative access to your Dolibarr installation + +## Installation Steps + +### Method 1: Manual Installation + +1. **Download the Module** + - Download the MokoDoliHRM module files from the repository + - Extract the files to a temporary location + +2. **Copy Files to Dolibarr** + ```bash + # Navigate to your Dolibarr installation directory + cd /path/to/dolibarr + + # Create the custom module directory + mkdir -p htdocs/custom/mokodolihrm + + # Copy the src folder contents to the module directory + cp -r /path/to/mokoDoliHRM/src/* htdocs/custom/mokodolihrm/ + ``` + +3. **Set Proper Permissions** + ```bash + # Set ownership (adjust user:group as needed) + chown -R www-data:www-data htdocs/custom/mokodolihrm + + # Set directory permissions + find htdocs/custom/mokodolihrm -type d -exec chmod 755 {} \; + + # Set file permissions + find htdocs/custom/mokodolihrm -type f -exec chmod 644 {} \; + ``` + +4. **Activate the Module** + - Log in to Dolibarr as an administrator + - Navigate to: Home → Setup → Modules/Applications + - Search for "MokoDoliHRM" in the modules list + - Click the "On/Off" switch to activate the module + - The module will automatically create the required database tables + +5. **Configure Permissions** + - Navigate to: Home → Setup → Users & Groups + - Select a user or group + - Grant the appropriate MokoDoliHRM permissions: + - Employee: Read, Write, Delete + - Contract: Read, Write, Delete + - Payroll: Read, Write, Delete + +### Method 2: Using Installation Script + +1. **Navigate to the Scripts Directory** + ```bash + cd /path/to/mokoDoliHRM/scripts + ``` + +2. **Run the Installation Script** + ```bash + chmod +x install.sh + ./install.sh /path/to/dolibarr + ``` + +3. **Follow On-Screen Instructions** + - The script will copy files and set proper permissions + - Activate the module through the Dolibarr interface as described above + +## Post-Installation Configuration + +### 1. Verify Installation + +After activating the module, verify the installation: + +- Check that the "MokoDoliHRM" menu appears in the top navigation +- Navigate to MokoDoliHRM → Employees and ensure the page loads correctly +- Check the database to verify that the following tables were created: + - `llx_mokodolihrm_employee` + - `llx_mokodolihrm_contract` + - `llx_mokodolihrm_payroll` + +### 2. Database Verification + +Connect to your database and run: + +```sql +SHOW TABLES LIKE 'llx_mokodolihrm_%'; +``` + +You should see three tables listed. + +### 3. Configure Module Settings + +Navigate to: Home → Setup → Modules/Applications → MokoDoliHRM → Setup + +Configure any module-specific settings as needed. + +## Troubleshooting + +### Module Not Appearing in Module List + +If the module doesn't appear in the modules list: + +1. Clear Dolibarr cache: + ```bash + rm -rf documents/install/locks/*.lock + ``` + +2. Verify file permissions: + ```bash + ls -la htdocs/custom/mokodolihrm/core/modules/modMokodoliHRM/ + ``` + +3. Check that `modMokodoliHRM.class.php` exists and is readable + +### Database Tables Not Created + +If the tables are not created automatically: + +1. Manually run the SQL script: + ```bash + mysql -u your_db_user -p your_db_name < src/sql/llx_mokodolihrm.sql + ``` + +2. Replace `llx_` prefix with your Dolibarr table prefix if different + +### Permission Errors + +If you encounter permission errors: + +1. Verify web server user ownership: + ```bash + ls -la htdocs/custom/mokodolihrm/ + ``` + +2. Ensure the web server user (usually `www-data`, `apache`, or `nginx`) owns the files: + ```bash + chown -R www-data:www-data htdocs/custom/mokodolihrm/ + ``` + +### Module Activation Fails + +If activation fails: + +1. Check Dolibarr error logs: + - Location: `documents/dolibarr.log` + +2. Check PHP error logs: + - Location varies by system (e.g., `/var/log/apache2/error.log`) + +3. Ensure database user has CREATE TABLE privileges + +## Upgrading + +### From a Previous Version + +1. **Backup Your Data** + ```bash + # Backup database + mysqldump -u user -p database_name > mokodolihrm_backup.sql + + # Backup files + cp -r htdocs/custom/mokodolihrm htdocs/custom/mokodolihrm.backup + ``` + +2. **Deactivate the Module** + - Navigate to: Home → Setup → Modules/Applications + - Deactivate MokoDoliHRM + +3. **Replace Files** + ```bash + rm -rf htdocs/custom/mokodolihrm/* + cp -r /path/to/new/version/src/* htdocs/custom/mokodolihrm/ + ``` + +4. **Reactivate the Module** + - Navigate to: Home → Setup → Modules/Applications + - Activate MokoDoliHRM + - Any database schema updates will be applied automatically + +## Uninstallation + +To completely remove the module: + +1. **Deactivate the Module** + - Navigate to: Home → Setup → Modules/Applications + - Deactivate MokoDoliHRM + +2. **Remove Files** + ```bash + rm -rf htdocs/custom/mokodolihrm + ``` + +3. **Remove Database Tables (Optional)** + + ⚠️ **Warning**: This will permanently delete all employee, contract, and payroll data. + + ```sql + DROP TABLE IF EXISTS llx_mokodolihrm_payroll; + DROP TABLE IF EXISTS llx_mokodolihrm_contract; + DROP TABLE IF EXISTS llx_mokodolihrm_employee; + ``` + +## Support + +For installation issues or questions: + +- Check the documentation in the `docs/` folder +- Review the FAQ in `docs/FAQ.md` +- Submit an issue on the project repository + +## Next Steps + +After successful installation: + +1. Read the user guide: `docs/USER_GUIDE.md` +2. Configure user permissions +3. Start adding employee records +4. Explore contract and payroll management features + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliHRM/README.md b/MokoConsulting/MokoDoliHRM/README.md new file mode 100644 index 0000000..1c27ffe --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/README.md @@ -0,0 +1,167 @@ +← [Home](Home) + +# MokoDoliHRM - Employee, Contract and Payroll Management for Dolibarr + +## Overview + +MokoDoliHRM is a comprehensive Human Resources Management module for Dolibarr ERP/CRM that provides complete functionality for managing employees, employment contracts, and payroll processing. + +## Features + +### Employee Management +- Create and manage employee records with complete personal information +- Track employee status (Draft, Active, Terminated) +- Store employee contact details, addresses, and identification information +- Record hire dates, termination dates, positions, and departments +- Manage social security numbers and bank account information +- Add public and private notes to employee records + +### Employee Contract Management +- Create and manage employment contracts for each employee +- Support multiple contract types (Permanent, Temporary, Consultant, Intern) +- Define contract periods with start and end dates +- Manage salary information with currency and payment period +- Track working hours and annual leave entitlements +- Monitor contract status throughout its lifecycle + +### Payroll Management +- Generate and manage payroll records for employees +- Track payroll periods with start and end dates +- Calculate gross salary, net salary, taxes, and social security contributions +- Manage bonuses and deductions +- Record payment dates and payment methods +- Support multiple payroll statuses (Draft, Validated, Paid, Cancelled) + +## Module Structure + +Following moko-platform, the module is organized into the following folders: + +``` +mokoDoliHRM/ +├── docs/ # Documentation files +├── scripts/ # Installation and utility scripts +├── tests/ # Test files +└── src/ # Source code + ├── class/ # PHP classes for business logic + ├── core/ # Core module files + │ └── modules/ + │ └── modMokodoliHRM/ + ├── lang/ # Language translation files + ├── pages/ # User interface pages + │ ├── employee/ + │ ├── contract/ + │ └── payroll/ + └── sql/ # Database schema files +``` + +## Installation + +1. Copy the `src` folder contents to your Dolibarr `custom/mokodolihrm/` directory +2. Log in to Dolibarr as an administrator +3. Navigate to Home → Setup → Modules/Applications +4. Find "MokoDoliHRM" in the list of modules +5. Click the "Activate" button to enable the module +6. The module will automatically create the required database tables + +## Usage + +### Managing Employees + +1. Navigate to MokoDoliHRM → Employees from the main menu +2. Click "New Employee" to create a new employee record +3. Fill in the required information (First Name, Last Name) +4. Add optional details such as contact information, position, department, etc. +5. Save the employee record + +### Managing Contracts + +1. Navigate to MokoDoliHRM → Contracts +2. Click "New Contract" to create a new employment contract +3. Select the employee for whom the contract is being created +4. Choose the contract type and define the contract period +5. Enter salary information and working conditions +6. Save the contract + +### Managing Payroll + +1. Navigate to MokoDoliHRM → Payroll +2. Click "New Payroll" to create a new payroll record +3. Select the employee and optionally link to a contract +4. Define the payroll period (start and end dates) +5. Enter gross salary and calculate deductions (taxes, social security) +6. Add any bonuses or additional deductions +7. Record the payment date and method +8. Save the payroll record + +## Permissions + +The module includes granular permissions for each area: + +### Employee Permissions +- Read employees +- Create/Update employees +- Delete employees + +### Contract Permissions +- Read contracts +- Create/Update contracts +- Delete contracts + +### Payroll Permissions +- Read payroll +- Create/Update payroll +- Delete payroll + +Permissions can be configured per user or user group in Dolibarr's user management interface. + +## Database Schema + +The module creates three main tables: + +### llx_mokodolihrm_employee +Stores employee information including personal details, contact information, position, and status. + +### llx_mokodolihrm_contract +Stores employment contract information linked to employees, including contract type, dates, salary, and working conditions. + +### llx_mokodolihrm_payroll +Stores payroll records linked to employees and optionally to contracts, including salary calculations, taxes, and payment information. + +## Technical Details + +### Module Information +- **Module Number**: 185060 +- **Module Machine Name**: `mokodolihrm` (folder, DB prefix, conf key, permission key, `$this->name`) +- **Module Family**: HR (Human Resources) +- **Version**: 1.0.0 +- **Minimum PHP Version**: 7.0 +- **Minimum Dolibarr Version**: 13.0 + +### Classes + +#### MokoEmployee +Main class for employee management with CRUD operations. + +#### MokoContract +Class for managing employment contracts with relationships to employees. + +#### MokoPayroll +Class for payroll processing with relationships to employees and contracts. + +## Support and Contribution + +For issues, questions, or contributions, please refer to the project repository. + +## License + +This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. + +Copyright (C) 2024 Moko Consulting + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliHRM/USER_GUIDE.md b/MokoConsulting/MokoDoliHRM/USER_GUIDE.md new file mode 100644 index 0000000..edea9e1 --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/USER_GUIDE.md @@ -0,0 +1,412 @@ +← [Home](Home) + +# MokoDoliHRM User Guide + +## Table of Contents +1. [Introduction](#introduction) +2. [Getting Started](#getting-started) +3. [Employee Management](#employee-management) +4. [Contract Management](#contract-management) +5. [Payroll Management](#payroll-management) +6. [Best Practices](#best-practices) +7. [Troubleshooting](#troubleshooting) + +## Introduction + +MokoDoliHRM is a comprehensive HR management module for Dolibarr that helps you manage your workforce efficiently. This guide will walk you through all the features and show you how to make the most of the module. + +### Key Features + +- **Employee Database**: Maintain complete employee records with personal and professional information +- **Contract Management**: Track employment contracts with detailed terms and conditions +- **Payroll Processing**: Process and track employee compensation and deductions + +## Getting Started + +### Accessing MokoDoliHRM + +After installation and activation: + +1. Log in to Dolibarr +2. Look for the "MokoDoliHRM" menu in the top navigation bar +3. Click on it to access the main menu with three sections: + - Employees + - Contracts + - Payroll + +### User Permissions + +Before using MokoDoliHRM, ensure you have the appropriate permissions: + +- **Read**: View employee, contract, and payroll records +- **Write**: Create and modify records +- **Delete**: Remove records from the system + +Administrators can configure these permissions in: **Home → Setup → Users & Groups** + +## Employee Management + +### Creating a New Employee + +1. Navigate to **MokoDoliHRM → Employees** +2. Click the **New Employee** button +3. Fill in the required information: + - **First Name** (required) + - **Last Name** (required) + - Email + - Phone + - Position + - Department + - Hire Date + - Status (Draft or Active) +4. Click **Create** to save the employee record + +### Employee Information Fields + +#### Personal Information +- **First Name & Last Name**: Employee's legal name +- **Date of Birth**: Used for age calculations and legal compliance +- **Address, City, Zip**: Residential address +- **Country**: Select from country list + +#### Contact Information +- **Email**: Primary email address for communication +- **Phone**: Primary contact number + +#### Employment Information +- **Reference**: Auto-generated employee ID (e.g., EMP00001) +- **Position**: Job title or role +- **Department**: Organizational unit +- **Hire Date**: Employment start date +- **Termination Date**: Set when employment ends + +#### Financial Information +- **Social Security Number**: For tax and benefits administration +- **Bank Account**: For direct deposit payments + +#### Notes +- **Public Notes**: Visible to users with read permission +- **Private Notes**: Visible only to users with elevated permissions + +### Viewing Employee Records + +1. Navigate to **MokoDoliHRM → Employees** +2. The list displays all employees with: + - Employee reference + - Name + - Position + - Department + - Status +3. Click on any employee reference to view full details + +### Searching and Filtering + +Use the search fields at the top of the employee list: +- **Reference**: Search by employee ID +- **First Name**: Filter by first name +- **Last Name**: Filter by last name +- **Position**: Filter by job title +- **Department**: Filter by department +- **Status**: Filter by employment status + +Click the **Search** button to apply filters. + +### Editing Employee Information + +1. Open the employee record +2. Click the **Modify** button +3. Update the necessary fields +4. Click **Save** to commit changes + +### Managing Employee Status + +Employees can have three statuses: + +- **Draft (0)**: Preliminary record, not yet active +- **Active (1)**: Currently employed +- **Terminated (9)**: Employment ended + +To change status: +1. Edit the employee record +2. Select the new status from the dropdown +3. If terminating, set the termination date +4. Save the changes + +### Deleting Employees + +⚠️ **Warning**: Deleting an employee will also delete all associated contracts and payroll records due to database constraints. + +1. Open the employee record +2. Click the **Delete** button +3. Confirm the deletion +4. The employee and all related data will be removed + +## Contract Management + +### Understanding Employment Contracts + +Contracts define the terms of employment including: +- Contract type and duration +- Compensation details +- Working conditions +- Leave entitlements + +### Creating a New Contract + +1. Navigate to **MokoDoliHRM → Contracts** +2. Click the **New Contract** button +3. Select the employee +4. Fill in contract details: + - **Contract Type**: Permanent, Temporary, Consultant, or Intern + - **Start Date**: When the contract begins + - **End Date**: When the contract ends (if applicable) + - **Salary**: Compensation amount + - **Currency**: Payment currency + - **Salary Period**: Monthly, Weekly, or Hourly + - **Working Hours**: Hours per week + - **Annual Leave Days**: Vacation entitlement +5. Click **Create** to save + +### Contract Types + +- **Permanent**: Ongoing employment with no fixed end date +- **Temporary**: Fixed-term employment +- **Consultant**: Contract-based engagement +- **Intern**: Training or educational placement + +### Salary Configuration + +When setting up salary information: +1. Enter the gross salary amount +2. Select the appropriate currency (USD, EUR, etc.) +3. Specify the payment period: + - **Monthly**: Salary paid once per month + - **Weekly**: Salary paid weekly + - **Hourly**: Compensation per hour worked + +### Viewing Contracts + +1. Navigate to **MokoDoliHRM → Contracts** +2. The list shows: + - Contract reference + - Employee name + - Contract type + - Start date + - Salary + - Status +3. Click on a contract reference for full details + +### Contract Status Management + +Contracts follow the same status workflow as employees: +- **Draft**: Being prepared +- **Active**: Currently in effect +- **Terminated**: Ended + +### Modifying Contracts + +To update contract terms: +1. Open the contract record +2. Click **Modify** +3. Update the necessary fields +4. Save changes + +**Best Practice**: When salary or terms change significantly, consider creating a new contract rather than modifying the existing one to maintain historical records. + +## Payroll Management + +### Overview + +The payroll module helps you track employee compensation, calculate deductions, and maintain payment records. + +### Creating a Payroll Record + +1. Navigate to **MokoDoliHRM → Payroll** +2. Click **New Payroll** +3. Fill in the payroll details: + - **Employee**: Select from the list + - **Contract**: Optionally link to a specific contract + - **Period Start**: Beginning of pay period + - **Period End**: End of pay period + - **Gross Salary**: Total compensation before deductions + - **Tax Amount**: Income tax withheld + - **Social Security**: Social security contributions + - **Bonuses**: Additional compensation + - **Deductions**: Other deductions + - **Net Salary**: Final amount paid (calculated or entered) + - **Payment Date**: When payment was/will be made + - **Payment Method**: Bank Transfer, Cash, or Check +4. Set the status (Draft, Validated, or Paid) +5. Click **Create** + +### Payroll Calculation + +While the module doesn't automatically calculate taxes, you can: + +1. Calculate externally or using your country's tax rules +2. Enter the calculated values into the fields +3. The net salary is: Gross Salary - Tax - Social Security - Deductions + Bonuses + +**Formula**: +``` +Net Salary = Gross Salary - Tax Amount - Social Security - Deductions + Bonuses +``` + +### Payroll Status Workflow + +1. **Draft (0)**: Payroll being prepared +2. **Validated (1)**: Payroll approved and ready for payment +3. **Paid (2)**: Payment has been made +4. **Cancelled (9)**: Payroll voided + +### Viewing Payroll Records + +1. Navigate to **MokoDoliHRM → Payroll** +2. The list displays: + - Payroll reference + - Employee name + - Pay period dates + - Net salary + - Status +3. Click on a reference to view full details + +### Reporting on Payroll + +To extract payroll data: +1. Use the search and filter features +2. Filter by employee, date range, or status +3. Export data for external reporting tools + +## Best Practices + +### Employee Management + +1. **Complete Records**: Fill in as much information as possible for each employee +2. **Regular Updates**: Keep contact information and positions current +3. **Status Management**: Always update status when employment circumstances change +4. **Documentation**: Use notes fields to record important events or information + +### Contract Management + +1. **Create Contracts Immediately**: Set up contracts when employees are hired +2. **Document Changes**: Create new contracts for significant changes (promotions, role changes) +3. **Track End Dates**: Monitor temporary contracts and renew or terminate as needed +4. **Salary Reviews**: Update contracts during annual reviews or compensation changes + +### Payroll Processing + +1. **Consistent Timing**: Process payroll on the same schedule each period +2. **Verify Calculations**: Double-check tax and deduction calculations +3. **Link to Contracts**: Associate payroll with contracts for better tracking +4. **Status Progression**: Move through statuses systematically (Draft → Validated → Paid) +5. **Backup Records**: Maintain external backups of payroll data for compliance + +### Data Security + +1. **Access Control**: Grant permissions based on job requirements +2. **Private Information**: Use private notes for sensitive information +3. **Regular Audits**: Review who has access to HR data +4. **Backup**: Regularly backup your Dolibarr database + +## Troubleshooting + +### Common Issues + +#### Cannot See MokoDoliHRM Menu + +**Solution**: +- Verify the module is activated: **Home → Setup → Modules** +- Check your user permissions +- Clear browser cache and reload + +#### Cannot Create Employees + +**Solution**: +- Verify you have "Write" permission for employees +- Check that required fields (First Name, Last Name) are filled +- Review error messages for specific issues + +#### Database Errors + +**Solution**: +- Ensure the database tables were created during installation +- Check that your database user has appropriate privileges +- Review Dolibarr error logs: `documents/dolibarr.log` + +#### Salary Not Displaying Correctly + +**Solution**: +- Verify the currency is set correctly +- Check regional settings in Dolibarr +- Ensure numeric values don't contain invalid characters + +### Getting Help + +If you encounter issues not covered here: + +1. Check the API documentation: `docs/API.md` +2. Review installation guide: `docs/INSTALLATION.md` +3. Check Dolibarr logs for error details +4. Verify your Dolibarr version meets minimum requirements (13.0+) + +### Performance Tips + +For large employee databases: + +1. Use filters effectively to limit result sets +2. Archive terminated employees rather than deleting them +3. Regular database maintenance and optimization +4. Consider pagination when viewing large lists + +## Appendix + +### Keyboard Shortcuts + +- **Tab**: Navigate between form fields +- **Enter**: Submit forms (when focused on a button) +- **Esc**: Close modals or cancel operations + +### Module Settings + +Access module configuration: +**Home → Setup → Modules → MokoDoliHRM → Setup** + +Available settings: +- Default Annual Leave Days +- Default Working Hours + +### Data Export + +While MokoDoliHRM doesn't include built-in export features, you can: + +1. Use Dolibarr's export module for standard exports +2. Query the database directly: + - `llx_mokodolihrm_employee` + - `llx_mokodolihrm_contract` + - `llx_mokodolihrm_payroll` +3. Use the API to extract data programmatically + +### Legal Compliance + +**Important**: This module is a tool for managing HR data. You are responsible for ensuring compliance with: + +- Local labor laws +- Tax regulations +- Data protection requirements (GDPR, etc.) +- Record retention policies + +Consult with legal and HR professionals to ensure proper usage. + +--- + +**Version**: 1.0.0 +**Last Updated**: 2024 +**Copyright**: Moko Consulting + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliHRM/update-server.-.-.md b/MokoConsulting/MokoDoliHRM/update-server.-.-.md new file mode 100644 index 0000000..a18e11f --- /dev/null +++ b/MokoConsulting/MokoDoliHRM/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliHRM/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliHRM](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliHRM) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMods/Home.md b/MokoConsulting/MokoDoliMods/Home.md new file mode 100644 index 0000000..cfdc2aa --- /dev/null +++ b/MokoConsulting/MokoDoliMods/Home.md @@ -0,0 +1,34 @@ +# MokoDoliMods + +The DoliMods is the repository of the Dolibarr ERP CRM modules, developed by the DoliCloud.com team. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMods) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [INSTALLATION](INSTALLATION) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliMods](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMods) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliMods/INSTALLATION.md b/MokoConsulting/MokoDoliMods/INSTALLATION.md new file mode 100644 index 0000000..877c84e --- /dev/null +++ b/MokoConsulting/MokoDoliMods/INSTALLATION.md @@ -0,0 +1,438 @@ +← [Home](Home) + +# Installation + +## Overview + +This document provides comprehensive installation and setup instructions for **[PROJECT_NAME]**. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Installation Methods](#installation-methods) +- [Quick Start](#quick-start) +- [Detailed Installation](#detailed-installation) +- [Configuration](#configuration) +- [Verification](#verification) +- [Troubleshooting](#troubleshooting) +- [Next Steps](#next-steps) + +## Prerequisites + +### System Requirements + +- **Operating System**: [Specify supported OS versions] +- **Runtime**: [e.g., PHP 8.1+, Node.js 20+, Python 3.9+] +- **Memory**: [Minimum RAM required] +- **Disk Space**: [Minimum disk space required] + +### Software Dependencies + +**Required:** +- [List required dependencies with versions] +- Example: Git 2.30+ +- Example: Composer 2.0+ + +**Optional:** +- [List optional dependencies] + +### Access Requirements + +- [Any required access permissions, credentials, or accounts] +- Example: GitHub account for cloning private repositories +- Example: Database access credentials + +## Installation Methods + +### Method 1: Using Package Manager (Recommended) + +**For [Platform/Package Manager]:** + +```bash +# Installation command +[package-manager] install [package-name] + +# Verify installation +[package-name] --version +``` + +### Method 2: From Source + +**Clone the repository:** + +```bash +# Clone from GitHub +git clone https://github.com/[organization]/[repository].git +cd [repository] + +# Checkout stable version (recommended) +git checkout tags/v[VERSION] +``` + +### Method 3: Using Pre-built Binary/Package + +**Download and install:** + +```bash +# Download release +wget https://github.com/[organization]/[repository]/releases/download/v[VERSION]/[package-name] + +# Make executable (if applicable) +chmod +x [package-name] + +# Move to system path (optional) +sudo mv [package-name] /usr/local/bin/ +``` + +## Quick Start + +For users who want to get started quickly: + +```bash +# 1. Install +[installation-command] + +# 2. Configure +[configuration-command] + +# 3. Run +[run-command] + +# 4. Verify +[verification-command] +``` + +## Detailed Installation + +### Step 1: Prepare Environment + +**1.1 Install System Dependencies** + +For Ubuntu/Debian: +```bash +sudo apt update +sudo apt install [dependencies] +``` + +For macOS: +```bash +brew install [dependencies] +``` + +For Windows: +```powershell +# PowerShell commands or link to Windows-specific guide +``` + +**1.2 Set Up Environment Variables** + +```bash +# Add to ~/.bashrc or ~/.zshrc +export [VAR_NAME]=[value] + +# Reload shell configuration +source ~/.bashrc +``` + +### Step 2: Install Application + +**2.1 Install via [Method]** + +```bash +[Detailed installation commands with explanations] +``` + +**2.2 Install Dependencies** + +```bash +# For PHP projects +composer install --no-dev + +# For Node.js projects +npm install --production + +# For Python projects +pip install -r requirements.txt +``` + +### Step 3: Initial Configuration + +**3.1 Create Configuration File** + +```bash +# Copy example configuration +cp config/config.example.php config/config.php + +# Or use configuration wizard +php bin/configure.php +``` + +**3.2 Configure Database (if applicable)** + +```bash +# Create database +mysql -u root -p -e "CREATE DATABASE [db_name];" + +# Import schema +mysql -u root -p [db_name] < database/schema.sql + +# Update configuration +nano config/database.php +``` + +**3.3 Set Permissions** + +```bash +# Set appropriate ownership +sudo chown -R www-data:www-data /var/www/[project] + +# Set directory permissions (755) +find /var/www/[project] -type d -exec chmod 755 {} \; + +# Set file permissions (644 for most files) +find /var/www/[project] -type f -exec chmod 644 {} \; + +# Make executable files executable (if needed) +chmod +x /var/www/[project]/bin/* + +# Restrict sensitive directories (storage, cache, logs) +chmod 750 /var/www/[project]/storage +chmod 750 /var/www/[project]/cache +``` + +### Step 4: Initialize Application + +**4.1 Run Setup Script** + +```bash +# Run initialization +php bin/setup.php + +# Or for other platforms +./scripts/setup.sh +``` + +**4.2 Create Admin User (if applicable)** + +```bash +# Create first admin user +php bin/create-admin.php --email=admin@example.com --name="Admin User" +``` + +## Configuration + +### Configuration Files + +| File | Purpose | Required | +|------|---------|----------| +| `config/config.php` | Main configuration | Yes | +| `config/database.php` | Database settings | Yes | +| `config/cache.php` | Cache configuration | No | +| `.env` | Environment variables | Yes | + +### Essential Configuration Options + +**config/config.php:** + +```php +return [ + 'app_name' => '[APPLICATION_NAME]', + 'app_url' => 'https://example.com', + 'debug' => false, // Set to true for development + 'timezone' => 'UTC', +]; +``` + +**Database Configuration:** + +```php +return [ + 'host' => 'localhost', + 'port' => 3306, + 'database' => '[db_name]', + 'username' => '[db_user]', + 'password' => '[db_password]', +]; +``` + +### Environment Variables + +Create `.env` file: + +```bash +APP_ENV=production +APP_DEBUG=false +APP_URL=https://example.com + +DB_HOST=localhost +DB_PORT=3306 +DB_DATABASE=[db_name] +DB_USERNAME=[db_user] +DB_PASSWORD=[db_password] +``` + +## Verification + +### Verify Installation + +**Check version:** + +```bash +[command] --version +# Expected output: v[VERSION] +``` + +**Run health check:** + +```bash +[command] health-check +# or +php bin/health-check.php +``` + +**Test basic functionality:** + +```bash +# Run test command +[command] test + +# Access web interface +curl http://localhost:[port]/health +``` + +### Expected Output + +``` +✓ Application installed successfully +✓ Database connection established +✓ All dependencies available +✓ Configuration valid +✓ System ready for use +``` + +## Troubleshooting + +### Common Issues + +#### Issue: Installation fails with dependency error + +**Symptom:** +``` +Error: Package [package-name] not found +``` + +**Solution:** +```bash +# Update package manager +[package-manager] update + +# Retry installation +[package-manager] install [package-name] +``` + +#### Issue: Database connection fails + +**Symptom:** +``` +Error: SQLSTATE[HY000] [2002] Connection refused +``` + +**Solution:** +1. Verify database service is running: + ```bash + sudo systemctl status mysql + ``` + +2. Check database credentials in configuration + +3. Verify database host and port are correct + +#### Issue: Permission denied errors + +**Symptom:** +``` +Error: Permission denied: /var/www/[project]/storage +``` + +**Solution:** +```bash +# Fix ownership +sudo chown -R www-data:www-data /var/www/[project] + +# Fix permissions +sudo chmod -R 755 /var/www/[project]/storage +``` + +### Getting Help + +If you encounter issues not covered here: + +1. **Check Logs:** + ```bash + tail -f logs/application.log + tail -f /var/log/apache2/error.log + ``` + +2. **Enable Debug Mode:** + ```bash + # In config/config.php + 'debug' => true + ``` + +3. **Consult Documentation:** + - [Troubleshooting Guide](guide/troubleshooting.md) + - [FAQ](guide/faq.md) + +4. **Community Support:** + - GitHub Issues: [link] + - Discussion Forum: [link] + - Email: support@example.com + +## Next Steps + +After successful installation: + +1. **Review Configuration:** + - [Configuration Guide](guide/configuration.md) + - [Security Hardening](guide/security.md) + +2. **Read Getting Started:** + - [Quick Start Guide](guide/quickstart.md) + - [User Guide](guide/user-guide.md) + +3. **For Developers:** + - [Development Setup](development/setup.md) + - [Contributing Guidelines](CONTRIBUTING) + +4. **For Operators:** + - [Deployment Guide](deployment/procedures.md) + - [Monitoring Setup](operations/monitoring.md) + +## Additional Resources + +- [Project Documentation](README.md) +- [API Reference](reference/api/) +- [Change Log](CHANGELOG) +- [Security Policy](SECURITY) + +--- + +## Support + +For installation support: +- **Documentation**: Review all guides in [docs/guide/](guide/) +- **Issues**: Report problems at [GitHub Issues](https://github.com/[organization]/[repository]/issues) +- **Email**: support@mokoconsulting.tech + +--- + +*Last Updated: [DATE]* +*Version: [VERSION]* + +--- + +*Repo: [MokoDoliMods](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMods) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMods/update-server.-.-.md b/MokoConsulting/MokoDoliMods/update-server.-.-.md new file mode 100644 index 0000000..0d30d1f --- /dev/null +++ b/MokoConsulting/MokoDoliMods/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.04.00-blue)](https://github.com/mokoconsulting-tech/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliMods/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX.YY +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX.YY` branch +4. **Frozen Snapshot** (`version/XX.YY`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://github.com/mokoconsulting-tech/moko-platform). See [docs/workflows/update-server.md](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliMods](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMods) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/Home.md b/MokoConsulting/MokoDoliMulti/Home.md new file mode 100644 index 0000000..8ec04d8 --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/Home.md @@ -0,0 +1,44 @@ +# MokoDoliMulti + +Domain‑based multi‑tenant orchestration for Dolibarr using one codebase and per‑tenant configuration, documents, and databases mapped by virtual host. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [INSTALLATION](INSTALLATION) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | +| [api API](api-API.-.-) | ← [Home](Home) | +| [architecture ARCHITECTURE](architecture-ARCHITECTURE.-.-) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [PROJECT_SUMMARY](PROJECT_SUMMARY) | ← [Home](Home) | +| [USAGE](USAGE) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliMulti/INSTALLATION.md b/MokoConsulting/MokoDoliMulti/INSTALLATION.md new file mode 100644 index 0000000..66b997c --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/INSTALLATION.md @@ -0,0 +1,304 @@ +← [Home](Home) + +# MokoDoliMulti Installation Guide + +This guide walks you through installing and configuring MokoDoliMulti for domain-based multi-tenant Dolibarr orchestration. + +## Prerequisites + +- Dolibarr 11.0 or higher +- PHP 7.0 or higher with extensions: + - mysqli or pdo_mysql + - mbstring + - json + - curl +- MySQL/MariaDB or PostgreSQL +- Apache 2.4+ or Nginx 1.10+ +- Linux server with shell access + +## Installation Steps + +### 1. Install Dolibarr + +First, install Dolibarr following the official installation guide. Install it once in a central location (e.g., `/var/www/dolibarr`). + +```bash +cd /var/www +git clone https://github.com/Dolibarr/dolibarr.git +# or download and extract the latest release +``` + +### 2. Clone MokoDoliMulti + +Clone this repository to a location accessible by your web server: + +```bash +cd /var/www +git clone https://github.com/mokoconsulting-tech/MokoDoliMulti.git +cd MokoDoliMulti +``` + +### 3. Run Setup Script + +Execute the setup script to create necessary directories: + +```bash +sudo ./scripts/setup.sh +``` + +This will: +- Create base document directories +- Set up permissions +- Create example configurations +- Check PHP requirements + +### 4. Configure Tenants + +#### Create Tenant Configurations + +For each tenant, create a configuration file in `src/config/tenants/`: + +```bash +./scripts/create-tenant.sh tenant1 tenant1.example.com dolibarr_tenant1 +``` + +Or manually create `src/config/tenants/tenant1.php`: + +```php + 'tenant1', + 'tenant_name' => 'Tenant 1 Company', + 'main_url' => 'https://tenant1.example.com', + + 'database' => array( + 'type' => 'mysqli', + 'host' => 'localhost', + 'port' => 3306, + 'name' => 'dolibarr_tenant1', + 'user' => 'dolibarr_tenant1', + 'password' => 'secure_password', + 'prefix' => 'llx_', + 'charset' => 'utf8mb4', + ), + + 'storage' => array( + 'document_root' => '/var/www/documents/tenant1', + ), + + 'authentication' => array( + 'mode' => 'dolibarr', + ), + + 'settings' => array( + 'timezone' => 'America/New_York', + 'language' => 'en_US', + 'currency' => 'USD', + ), +); +``` + +#### Update Domain Mapping + +Edit `src/config/tenants/mapping.php` to map domains to tenants: + +```php + 'tenant1', + 'tenant2.example.com' => 'tenant2', + '*.wildcard.com' => 'wildcard_tenant', +); +``` + +### 5. Create Databases + +For each tenant, create a dedicated database: + +```sql +CREATE DATABASE dolibarr_tenant1 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +CREATE USER 'dolibarr_tenant1'@'localhost' IDENTIFIED BY 'secure_password'; +GRANT ALL PRIVILEGES ON dolibarr_tenant1.* TO 'dolibarr_tenant1'@'localhost'; +FLUSH PRIVILEGES; +``` + +### 6. Configure Web Server + +#### Apache Configuration + +Create a virtual host configuration for each tenant domain, or use a wildcard configuration: + +```apache + + ServerName tenant1.example.com + ServerAdmin admin@tenant1.example.com + + DocumentRoot /var/www/dolibarr/htdocs + + # Enable MokoDoliMulti bootstrap + php_value auto_prepend_file /var/www/MokoDoliMulti/src/bootstrap.php + + + Options -Indexes +FollowSymLinks + AllowOverride All + Require all granted + + + ErrorLog ${APACHE_LOG_DIR}/tenant1-error.log + CustomLog ${APACHE_LOG_DIR}/tenant1-access.log combined + +``` + +Enable the site and reload Apache: + +```bash +sudo a2ensite tenant1.conf +sudo systemctl reload apache2 +``` + +#### Nginx Configuration + +Create a server block for each tenant: + +```nginx +server { + listen 80; + server_name tenant1.example.com; + + root /var/www/dolibarr/htdocs; + index index.php index.html; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + include snippets/fastcgi-php.conf; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/MokoDoliMulti/src/bootstrap.php"; + } + + location ~ /\.ht { + deny all; + } + + access_log /var/log/nginx/tenant1-access.log; + error_log /var/log/nginx/tenant1-error.log; +} +``` + +Test and reload Nginx: + +```bash +sudo nginx -t +sudo systemctl reload nginx +``` + +### 7. Initialize Each Tenant + +For each tenant, run the Dolibarr installation wizard: + +1. Browse to `https://tenant1.example.com/install/` +2. Follow the installation wizard +3. The database credentials will be automatically loaded from tenant configuration +4. Complete the installation + +### 8. Verify Installation + +Test each tenant by accessing their respective domains: + +```bash +curl -I https://tenant1.example.com +curl -I https://tenant2.example.com +``` + +Check logs for any errors: + +```bash +tail -f /var/log/apache2/tenant1-error.log +# or +tail -f /var/log/nginx/tenant1-error.log +``` + +## Directory Structure + +After installation, your directory structure should look like: + +``` +/var/www/ +├── dolibarr/ # Single Dolibarr codebase +│ └── htdocs/ +├── MokoDoliMulti/ # Multi-tenant orchestration +│ ├── src/ +│ │ ├── core/ +│ │ ├── database/ +│ │ ├── storage/ +│ │ ├── config/ +│ │ │ └── tenants/ +│ │ └── bootstrap.php +│ ├── scripts/ +│ ├── docs/ +│ └── tests/ +└── documents/ # Per-tenant document storage + ├── tenant1/ + ├── tenant2/ + └── ... +``` + +## Security Considerations + +1. **File Permissions**: Ensure document directories are writable by the web server but not publicly accessible +2. **Database Credentials**: Protect tenant configuration files (chmod 600) +3. **SSL/TLS**: Use HTTPS for all tenant domains +4. **Firewall**: Restrict database access to localhost or specific IPs +5. **Backups**: Implement per-tenant backup strategies + +## Troubleshooting + +### Tenant Not Resolving + +Check logs for errors: +```bash +tail -f /var/log/apache2/error.log +``` + +Verify domain mapping in `src/config/tenants/mapping.php` + +### Database Connection Issues + +Test database connection: +```bash +mysql -u dolibarr_tenant1 -p -h localhost dolibarr_tenant1 +``` + +Verify database credentials in tenant configuration + +### Document Storage Issues + +Check directory permissions: +```bash +ls -la /var/www/documents/tenant1 +sudo chown -R www-data:www-data /var/www/documents/tenant1 +``` + +## Next Steps + +- Configure SSL certificates for each domain +- Set up automated backups +- Configure monitoring and alerting +- Review tenant-specific settings +- Set up cron jobs for Dolibarr maintenance + +## Support + +For issues and questions: +- GitHub Issues: https://github.com/mokoconsulting-tech/MokoDoliMulti/issues +- Documentation: https://github.com/mokoconsulting-tech/MokoDoliMulti/docs + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/PROJECT_SUMMARY.md b/MokoConsulting/MokoDoliMulti/PROJECT_SUMMARY.md new file mode 100644 index 0000000..00a69a6 --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/PROJECT_SUMMARY.md @@ -0,0 +1,291 @@ +← [Home](Home) + +# Project Summary: MokoDoliMulti + +## Overview + +MokoDoliMulti is a complete domain-based multi-tenant orchestration system for Dolibarr, enabling multiple organizations to run on a single Dolibarr installation while maintaining complete isolation. + +**Module ID**: 185059 + +## Implementation Status + +✅ **COMPLETE** - All requirements met, tested, and documented + +## Key Achievements + +### 1. Core Functionality (100% Complete) + +#### TenantResolver +- ✅ Domain-based tenant identification +- ✅ Wildcard domain support (*.example.com) +- ✅ Configuration loading with dot-notation access +- ✅ Mapping cache for performance +- ✅ Port-stripping for compatibility + +#### DatabaseRouter +- ✅ Per-tenant database configuration +- ✅ MySQL/MariaDB support +- ✅ PostgreSQL support +- ✅ Connection testing +- ✅ Dolibarr global variable override + +#### StorageRouter +- ✅ Per-tenant document storage +- ✅ Automatic directory creation +- ✅ Path traversal protection +- ✅ Disk usage monitoring +- ✅ Temporary file cleanup +- ✅ Security boundary enforcement + +#### Bootstrap System +- ✅ PHP auto_prepend_file integration +- ✅ Namespace autoloading +- ✅ Global helper functions +- ✅ No Dolibarr core modifications + +### 2. Testing (100% Pass Rate) + +#### Unit Tests (7 tests) +- ✅ TenantResolverTest (7 test methods) +- ✅ DatabaseRouterTest (6 test methods) +- ✅ StorageRouterTest (7 test methods) + +#### Integration Tests (5 tests) +- ✅ Complete bootstrap flow +- ✅ Tenant isolation verification +- ✅ Storage isolation verification +- ✅ Database configuration application +- ✅ Helper functions verification + +**Total**: 12 tests, 0 failures, 100% pass rate + +### 3. Documentation (Complete) + +#### Core Documentation +- ✅ README.md - Project overview and quick start +- ✅ INSTALLATION.md - Step-by-step installation guide +- ✅ ARCHITECTURE.md - System architecture and design +- ✅ API.md - Complete API reference +- ✅ USAGE.md - 17 practical usage examples +- ✅ CHANGELOG.md - Version history + +#### Code Documentation +- ✅ PHPDoc comments on all classes +- ✅ Method documentation with parameters and returns +- ✅ Inline comments for complex logic +- ✅ Example configurations + +### 4. Operational Tools + +#### Scripts +- ✅ setup.sh - Initial environment setup +- ✅ create-tenant.sh - New tenant wizard +- ✅ run-tests.sh - Test runner + +#### Examples +- ✅ Apache VirtualHost configurations +- ✅ Nginx server block configurations +- ✅ Tenant configuration templates +- ✅ Domain mapping examples + +### 5. Standards Compliance + +#### moko-platform +- ✅ Directory structure: docs/, scripts/, tests/, src/ +- ✅ Proper documentation hierarchy +- ✅ Executable scripts with proper permissions +- ✅ Test organization (unit/, integration/) + +#### Code Quality +- ✅ PSR-compliant namespace structure +- ✅ Consistent coding style +- ✅ Error handling and logging +- ✅ Security best practices +- ✅ Code review completed and addressed + +## Project Structure + +``` +MokoDoliMulti/ +├── src/ # Source code +│ ├── core/ +│ │ ├── TenantResolver.php # 5.6 KB - Tenant resolution +│ │ └── modules/ +│ │ └── modMokoDoliMulti.class.php # Dolibarr module +│ ├── database/ +│ │ └── DatabaseRouter.php # 6.2 KB - Database routing +│ ├── storage/ +│ │ └── StorageRouter.php # 7.0 KB - Storage routing +│ ├── config/ +│ │ └── tenants/ # Tenant configurations +│ └── bootstrap.php # 4.1 KB - Bootstrap layer +│ +├── tests/ # Test suite +│ ├── unit/ # Unit tests (3 files) +│ └── integration/ # Integration tests (1 file) +│ +├── scripts/ # Operational scripts +│ ├── setup.sh # 5.0 KB +│ ├── create-tenant.sh # 5.0 KB +│ └── run-tests.sh # 1.5 KB +│ +├── docs/ # Documentation +│ ├── INSTALLATION.md # 6.8 KB +│ ├── USAGE.md # 11.8 KB +│ ├── architecture/ +│ │ └── ARCHITECTURE.md # 9.0 KB +│ └── api/ +│ └── API.md # 9.3 KB +│ +├── README.md # 7.4 KB +├── CHANGELOG.md # 2.0 KB +├── LICENSE # GPL-3.0 +└── .gitignore +``` + +**Total Lines of Code**: +- PHP Code: ~1,500 lines +- Tests: ~900 lines +- Documentation: ~3,000 lines +- Scripts: ~400 lines + +## Features Summary + +### Security +- Database isolation per tenant +- File system boundary enforcement +- Path traversal protection +- Separate authentication per tenant +- Configuration file protection + +### Scalability +- Supports unlimited tenants +- Wildcard domain routing +- Separate database servers per tenant +- Flexible storage backends (NFS, local, etc.) +- Horizontal scaling ready + +### Flexibility +- MySQL/MariaDB or PostgreSQL +- Custom storage paths +- Per-tenant settings (timezone, language, currency) +- Authentication mode configuration +- Development/staging/production support + +### Operations +- Automated tenant creation +- Easy backup per tenant +- Disk usage monitoring +- Temporary file cleanup +- Database connection testing + +## Usage Scenarios + +The system supports: +1. ✅ SaaS multi-tenant hosting +2. ✅ Development/staging/production environments +3. ✅ Client-specific deployments +4. ✅ Wildcard subdomain routing +5. ✅ Separate infrastructure per tenant +6. ✅ Mixed database types (MySQL + PostgreSQL) +7. ✅ Custom storage backends + +## Integration Points + +### Web Server +- Apache: `php_value auto_prepend_file` +- Nginx: `fastcgi_param PHP_VALUE` + +### Dolibarr +- Database configuration override +- Document root override +- No core modifications required + +### External Systems +- Can integrate per-tenant APIs +- OAuth providers per tenant +- LDAP authentication per tenant + +## Performance + +### Optimizations +- Configuration caching (opcache) +- Tenant mapping cache +- Minimal overhead per request +- No database queries for resolution + +### Resource Usage +- Memory: < 1 MB per request overhead +- CPU: Negligible impact +- Disk: Per-tenant document storage + +## Production Readiness + +✅ **Ready for Production** + +### Checklist +- ✅ All features implemented +- ✅ 100% test coverage passing +- ✅ Complete documentation +- ✅ Security best practices +- ✅ Error handling and logging +- ✅ Code review completed +- ✅ Example configurations provided +- ✅ Operational scripts included + +## Known Limitations + +None at this time. System is fully functional and tested. + +## Future Enhancements (Optional) + +Potential future additions: +- Admin web UI for tenant management +- REST API for tenant operations +- Monitoring dashboard +- Auto-scaling support +- Backup automation +- Tenant migration tools +- Billing/usage tracking + +## Deployment Checklist + +Before deploying to production: +1. ✅ Change default passwords in configurations +2. ✅ Set proper file permissions (600 for configs) +3. ✅ Configure SSL/TLS certificates +4. ✅ Set up firewall rules +5. ✅ Configure backup strategy +6. ✅ Test tenant resolution +7. ✅ Verify database connections +8. ✅ Test document storage access +9. ✅ Configure monitoring +10. ✅ Document deployment specifics + +## Support Resources + +- **Documentation**: Complete guide in docs/ +- **Examples**: 17 usage scenarios in docs/USAGE.md +- **Tests**: Run ./scripts/run-tests.sh +- **Issues**: GitHub Issues for support + +## Conclusion + +MokoDoliMulti successfully implements a production-ready, domain-based multi-tenant orchestration system for Dolibarr. The implementation follows moko-platform, includes comprehensive testing and documentation, and is ready for immediate deployment. + +**Project Status**: ✅ COMPLETE AND PRODUCTION READY + +--- + +*Generated: 2026-01-09* +*Module ID: 185059* +*Version: 1.0.0* + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/README.md b/MokoConsulting/MokoDoliMulti/README.md new file mode 100644 index 0000000..fce42b7 --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/README.md @@ -0,0 +1,81 @@ +← [Home](Home) + +# MokoDoliMulti Documentation + +Welcome to the MokoDoliMulti documentation. This directory contains comprehensive guides, references, and examples for using and contributing to MokoDoliMulti. + +## Documentation Structure + +### Getting Started + +- **[Installation Guide](INSTALLATION.md)** - Step-by-step installation instructions +- **[Usage Guide](USAGE.md)** - Practical usage examples and common scenarios + +### Technical Documentation + +- **[Architecture](architecture/ARCHITECTURE.md)** - System architecture, design decisions, and data flow +- **[API Reference](api/API.md)** - Complete API documentation for all classes and methods + +### Project Information + +- **[Project Summary](PROJECT_SUMMARY.md)** - Overview of implementation, features, and statistics + +### Examples + +The **[examples/](examples/)** directory contains: +- `apache-vhost.conf` - Apache virtual host configuration template +- `nginx-site.conf` - Nginx server block configuration template + +## Quick Links + +### For Users + +1. Start with the [Installation Guide](INSTALLATION.md) +2. Review the [Usage Guide](USAGE.md) for practical examples +3. Check [Architecture](architecture/ARCHITECTURE.md) to understand how it works + +### For Developers + +1. Read the [Architecture](architecture/ARCHITECTURE.md) documentation +2. Review the [API Reference](api/API.md) +3. See [../CONTRIBUTING.md](CONTRIBUTING) for contribution guidelines +4. Check [../CODE_OF_CONDUCT.md](CODE_OF_CONDUCT) for community standards + +### For Contributors + +- [Contributing Guidelines](CONTRIBUTING) +- [Code of Conduct](CODE_OF_CONDUCT) +- [Governance](GOVERNANCE) + +## Documentation Standards + +This documentation follows [moko-platform](https://github.com/mokoconsulting-tech/moko-platform) for consistency and quality: + +- Clear, concise language +- Practical code examples +- Structured with logical hierarchies +- Maintained alongside code changes +- Accessible and easy to navigate + +## Feedback + +Found an issue with the documentation? Please: + +1. [Open an issue](https://github.com/mokoconsulting-tech/MokoDoliMulti/issues) describing the problem +2. Or submit a pull request with improvements + +## License + +Documentation is part of the MokoDoliMulti project and is licensed under GPL-3.0-or-later. + +--- + +**Last Updated**: January 2026 + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/USAGE.md b/MokoConsulting/MokoDoliMulti/USAGE.md new file mode 100644 index 0000000..71ed8e4 --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/USAGE.md @@ -0,0 +1,498 @@ +← [Home](Home) + +# Usage Examples + +This document provides practical examples of using MokoDoliMulti in various scenarios. + +## Basic Setup + +### 1. Single Server with Multiple Tenants + +**Scenario**: Host multiple clients on one server with separate domains. + +**Setup**: +```bash +# Create tenants +./scripts/create-tenant.sh acme acme.example.com dolibarr_acme +./scripts/create-tenant.sh globex globex.example.com dolibarr_globex +./scripts/create-tenant.sh initech initech.example.com dolibarr_initech +``` + +**Apache Configuration** (`/etc/apache2/sites-available/dolibarr-multitenant.conf`): +```apache +# Common configuration for all tenants + + ServerName acme.example.com + DocumentRoot /var/www/dolibarr/htdocs + php_value auto_prepend_file /var/www/MokoDoliMulti/src/bootstrap.php + + + Options -Indexes +FollowSymLinks + AllowOverride All + Require all granted + + + + + ServerName globex.example.com + DocumentRoot /var/www/dolibarr/htdocs + php_value auto_prepend_file /var/www/MokoDoliMulti/src/bootstrap.php + + + Options -Indexes +FollowSymLinks + AllowOverride All + Require all granted + + + + + ServerName initech.example.com + DocumentRoot /var/www/dolibarr/htdocs + php_value auto_prepend_file /var/www/MokoDoliMulti/src/bootstrap.php + + + Options -Indexes +FollowSymLinks + AllowOverride All + Require all granted + + +``` + +### 2. Wildcard Domain Setup + +**Scenario**: Each client gets a subdomain: `clientname.saas.example.com` + +**Configuration** (`src/config/tenants/mapping.php`): +```php + 'saas', + // All subdomains route to 'saas' tenant with dynamic handling +); +``` + +**Extended Resolver** (if you need per-subdomain logic): +```php + 'bigclient', + 'tenant_name' => 'Big Client Corp', + 'main_url' => 'https://bigclient.example.com', + + 'database' => array( + 'type' => 'mysqli', + 'host' => 'db-bigclient.internal.example.com', // Dedicated DB server + 'port' => 3306, + 'name' => 'dolibarr_bigclient', + 'user' => 'bigclient_user', + 'password' => 'secure_password', + 'prefix' => 'llx_', + 'charset' => 'utf8mb4', + ), + + 'storage' => array( + 'document_root' => '/mnt/bigclient-storage/documents', // Dedicated storage mount + ), +); +``` + +### 4. Custom Storage Backend (NFS/S3) + +**Tenant with NFS Storage** (`src/config/tenants/enterprise.php`): +```php + 'enterprise', + 'tenant_name' => 'Enterprise Client', + + 'database' => array( + 'type' => 'mysqli', + 'host' => 'localhost', + 'name' => 'dolibarr_enterprise', + 'user' => 'enterprise_user', + 'password' => 'secure_password', + ), + + 'storage' => array( + 'document_root' => '/mnt/nfs/enterprise-docs', // NFS mount point + ), +); +``` + +### 5. PostgreSQL Configuration + +**PostgreSQL Tenant** (`src/config/tenants/pgclient.php`): +```php + 'pgclient', + 'tenant_name' => 'PostgreSQL Client', + + 'database' => array( + 'type' => 'pgsql', + 'host' => 'localhost', + 'port' => 5432, + 'name' => 'dolibarr_pgclient', + 'user' => 'pgclient_user', + 'password' => 'secure_password', + 'prefix' => 'llx_', + 'charset' => 'utf8', + ), +); +``` + +### 6. Development and Staging Environments + +**Development Configuration** (`src/config/tenants/dev.php`): +```php + 'dev', + 'tenant_name' => 'Development Environment', + 'main_url' => 'http://localhost:8080', + + 'database' => array( + 'type' => 'mysqli', + 'host' => 'localhost', + 'name' => 'dolibarr_dev', + 'user' => 'root', + 'password' => 'devpass', + ), + + 'storage' => array( + 'document_root' => '/tmp/dolibarr_dev_docs', + ), + + 'settings' => array( + 'timezone' => 'UTC', + 'language' => 'en_US', + ), +); +``` + +**Mapping for Development**: +```php + 'dev', + 'localhost:8080' => 'dev', + '127.0.0.1' => 'dev', +); +``` + +## Operational Tasks + +### 7. Tenant Backup Script + +```bash +#!/bin/bash +# backup-tenant.sh + +TENANT_ID="$1" +BACKUP_DIR="/backup/tenants/$TENANT_ID" +DATE=$(date +%Y%m%d_%H%M%S) + +# Load tenant configuration +source <(php -r " +\$config = include '/var/www/MokoDoliMulti/src/config/tenants/$TENANT_ID.php'; +echo 'DB_NAME=' . \$config['database']['name'] . \"\n\"; +echo 'DB_USER=' . \$config['database']['user'] . \"\n\"; +echo 'DB_PASS=' . \$config['database']['password'] . \"\n\"; +echo 'DOC_ROOT=' . \$config['storage']['document_root'] . \"\n\"; +") + +# Create backup directory +mkdir -p "$BACKUP_DIR" + +# Backup database +mysqldump -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" \ + | gzip > "$BACKUP_DIR/database_${DATE}.sql.gz" + +# Backup documents +tar -czf "$BACKUP_DIR/documents_${DATE}.tar.gz" -C "$(dirname "$DOC_ROOT")" "$(basename "$DOC_ROOT")" + +echo "Backup completed: $BACKUP_DIR" +``` + +### 8. Tenant Migration Script + +```bash +#!/bin/bash +# migrate-tenant.sh - Move tenant to new server + +SOURCE_TENANT="$1" +DEST_SERVER="$2" + +# Export tenant database +./backup-tenant.sh "$SOURCE_TENANT" + +# Copy to destination +scp -r "/backup/tenants/$SOURCE_TENANT" "$DEST_SERVER:/backup/tenants/" + +# SSH to destination and restore +ssh "$DEST_SERVER" << 'EOF' + cd /var/www/MokoDoliMulti + ./scripts/restore-tenant.sh "$SOURCE_TENANT" +EOF +``` + +### 9. Monitoring Disk Usage + +```php +getDiskUsage(); + + echo sprintf( + "%-20s %10s MB %10d files\n", + $tenantId, + number_format($usage['total_mb'], 2), + $usage['file_count'] + ); +} +``` + +### 10. Clean Temporary Files + +```php +cleanTempFiles(86400); + + echo "Tenant $tenantId: Deleted $deleted temporary files\n"; +} +``` + +## Security Best Practices + +### 11. Secure Configuration Files + +```bash +# Protect tenant configuration files +chmod 600 src/config/tenants/*.php +chown www-data:www-data src/config/tenants/*.php + +# Protect mapping file +chmod 644 src/config/tenants/mapping.php +``` + +### 12. Database User Permissions + +```sql +-- Create tenant database user with restricted permissions +CREATE USER 'tenant1_user'@'localhost' IDENTIFIED BY 'secure_password'; +GRANT SELECT, INSERT, UPDATE, DELETE ON dolibarr_tenant1.* TO 'tenant1_user'@'localhost'; +GRANT CREATE, DROP, ALTER, INDEX ON dolibarr_tenant1.* TO 'tenant1_user'@'localhost'; +FLUSH PRIVILEGES; +``` + +### 13. Document Storage Permissions + +```bash +# Set up proper document storage permissions +for tenant in /var/www/documents/*; do + chown -R www-data:www-data "$tenant" + chmod -R 750 "$tenant" +done + +# Prevent direct web access to documents +cat > /var/www/documents/.htaccess << 'EOF' +Order Deny,Allow +Deny from all +EOF +``` + +## Troubleshooting + +### 14. Debug Tenant Resolution + +```php +resolve($host); + +if ($result) { + echo "✓ Tenant resolved successfully\n"; + echo "Tenant ID: " . $resolver->getTenantId() . "\n"; + echo "Configuration:\n"; + print_r($resolver->getConfig()); +} else { + echo "✗ Failed to resolve tenant\n"; + echo "Check:\n"; + echo "- Domain mapping in src/config/tenants/mapping.php\n"; + echo "- Tenant configuration file exists\n"; +} +``` + +### 15. Test Database Connection + +```php +\n"); +} + +use MokoDoliMulti\Core\TenantResolver; +use MokoDoliMulti\Database\DatabaseRouter; + +$resolver = new TenantResolver(); +$config = include __DIR__ . "/src/config/tenants/{$tenantId}.php"; + +// Mock resolution +$resolver->resolve('test.local'); + +$router = new DatabaseRouter($resolver); + +if ($router->testConnection()) { + echo "✓ Database connection successful\n"; + echo "Database: " . $router->getDatabaseName() . "\n"; +} else { + echo "✗ Database connection failed\n"; + echo "Check database credentials and server availability\n"; +} +``` + +## Nginx Examples + +### 16. Nginx with Multiple Server Blocks + +```nginx +# /etc/nginx/sites-available/dolibarr-multitenant + +server { + listen 80; + server_name acme.example.com; + + root /var/www/dolibarr/htdocs; + index index.php; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + include snippets/fastcgi-php.conf; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/MokoDoliMulti/src/bootstrap.php"; + } +} + +server { + listen 80; + server_name globex.example.com; + + root /var/www/dolibarr/htdocs; + index index.php; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + include snippets/fastcgi-php.conf; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/MokoDoliMulti/src/bootstrap.php"; + } +} +``` + +### 17. Nginx with Wildcard SSL + +```nginx +server { + listen 443 ssl http2; + server_name *.example.com; + + ssl_certificate /etc/ssl/certs/wildcard.example.com.crt; + ssl_certificate_key /etc/ssl/private/wildcard.example.com.key; + + root /var/www/dolibarr/htdocs; + index index.php; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + include snippets/fastcgi-php.conf; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + fastcgi_param PHP_VALUE "auto_prepend_file=/var/www/MokoDoliMulti/src/bootstrap.php"; + } +} +``` + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/api-API.-.-.md b/MokoConsulting/MokoDoliMulti/api-API.-.-.md new file mode 100644 index 0000000..66284c0 --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/api-API.-.-.md @@ -0,0 +1,488 @@ +← [Home](Home) + +# API Reference + +## Core Classes + +### TenantResolver + +**Namespace**: `MokoDoliMulti\Core` + +**Purpose**: Resolves tenant configuration based on HTTP Host header. + +#### Constructor + +```php +public function __construct($configDir = null) +``` + +**Parameters**: +- `$configDir` (string|null): Path to tenant configurations directory. Defaults to `src/config/tenants`. + +#### Methods + +##### resolve() + +```php +public function resolve($host = null): bool +``` + +Resolve tenant from HTTP request. + +**Parameters**: +- `$host` (string|null): Override host for testing. Defaults to HTTP_HOST. + +**Returns**: `bool` - True if tenant resolved successfully. + +**Example**: +```php +$resolver = new TenantResolver(); +if ($resolver->resolve()) { + echo "Tenant: " . $resolver->getTenantId(); +} +``` + +##### getTenantId() + +```php +public function getTenantId(): ?string +``` + +Get current tenant identifier. + +**Returns**: `string|null` - Tenant ID or null if not resolved. + +##### getConfig() + +```php +public function getConfig($key = null): mixed +``` + +Get tenant configuration. + +**Parameters**: +- `$key` (string|null): Configuration key. Supports dot notation (e.g., 'database.host'). If null, returns full config. + +**Returns**: `mixed` - Configuration value or null if not found. + +**Examples**: +```php +// Get full config +$config = $resolver->getConfig(); + +// Get top-level key +$dbConfig = $resolver->getConfig('database'); + +// Get nested key with dot notation +$dbHost = $resolver->getConfig('database.host'); +``` + +##### isResolved() + +```php +public function isResolved(): bool +``` + +Check if tenant is resolved. + +**Returns**: `bool` - True if tenant was successfully resolved. + +--- + +### DatabaseRouter + +**Namespace**: `MokoDoliMulti\Database` + +**Purpose**: Routes database connections to tenant-specific databases. + +#### Constructor + +```php +public function __construct(TenantResolver $tenantResolver) +``` + +**Parameters**: +- `$tenantResolver` (TenantResolver): Tenant resolver instance. + +#### Methods + +##### getDatabaseConfig() + +```php +public function getDatabaseConfig(): ?array +``` + +Get database configuration for current tenant. + +**Returns**: `array|null` - Database configuration array or null on error. + +**Configuration Structure**: +```php +array( + 'type' => 'mysqli', // Database type + 'host' => 'localhost', // Database host + 'port' => 3306, // Database port + 'name' => 'db_name', // Database name + 'user' => 'db_user', // Database user + 'password' => 'db_pass', // Database password + 'prefix' => 'llx_', // Table prefix + 'charset' => 'utf8mb4' // Character set +) +``` + +##### applyConfiguration() + +```php +public function applyConfiguration(): bool +``` + +Apply database configuration to Dolibarr global variables. + +**Returns**: `bool` - True if successful. + +**Side Effects**: Sets global Dolibarr database variables: +- `$dolibarr_main_db_type` +- `$dolibarr_main_db_host` +- `$dolibarr_main_db_port` +- `$dolibarr_main_db_name` +- `$dolibarr_main_db_user` +- `$dolibarr_main_db_pass` +- `$dolibarr_main_db_prefix` +- `$dolibarr_main_db_character_set` + +##### testConnection() + +```php +public function testConnection(): bool +``` + +Test database connection. + +**Returns**: `bool` - True if connection successful. + +##### getConnectionString() + +```php +public function getConnectionString(): string +``` + +Get PDO connection string for tenant database. + +**Returns**: `string` - PDO DSN connection string. + +##### getDatabaseName() + +```php +public function getDatabaseName(): ?string +``` + +Get tenant database name. + +**Returns**: `string|null` - Database name. + +##### getDatabasePrefix() + +```php +public function getDatabasePrefix(): ?string +``` + +Get tenant database table prefix. + +**Returns**: `string|null` - Table prefix. + +--- + +### StorageRouter + +**Namespace**: `MokoDoliMulti\Storage` + +**Purpose**: Routes document storage to tenant-specific directories. + +#### Constructor + +```php +public function __construct(TenantResolver $tenantResolver, $baseDocumentRoot = null) +``` + +**Parameters**: +- `$tenantResolver` (TenantResolver): Tenant resolver instance. +- `$baseDocumentRoot` (string|null): Base documents directory. Defaults to `/var/www/documents`. + +#### Methods + +##### getDocumentRoot() + +```php +public function getDocumentRoot(): ?string +``` + +Get tenant document root path. + +**Returns**: `string|null` - Document root path or null on error. + +##### ensureDirectories() + +```php +public function ensureDirectories(): bool +``` + +Ensure tenant document directories exist. + +**Returns**: `bool` - True if directories exist or were created. + +**Creates**: +- Document root +- Standard subdirectories: company, invoices, proposals, orders, contracts, products, users, temp, medias + +##### applyConfiguration() + +```php +public function applyConfiguration(): bool +``` + +Apply storage configuration to Dolibarr. + +**Returns**: `bool` - True if successful. + +**Side Effects**: Sets global variable `$dolibarr_main_data_root`. + +##### getDocumentPath() + +```php +public function getDocumentPath($type, $ref = ''): ?string +``` + +Get path for specific document type. + +**Parameters**: +- `$type` (string): Document type (company, invoice, etc.) +- `$ref` (string): Optional document reference + +**Returns**: `string|null` - Full path to document directory. + +**Example**: +```php +$router->getDocumentPath('invoices', 'INV001'); +// Returns: /var/www/documents/tenant1/invoices/INV001 +``` + +##### isPathSafe() + +```php +public function isPathSafe($path): bool +``` + +Check if path is within tenant boundary. + +**Parameters**: +- `$path` (string): Path to validate + +**Returns**: `bool` - True if path is safe. + +##### getTempDirectory() + +```php +public function getTempDirectory(): ?string +``` + +Get temporary directory for tenant. + +**Returns**: `string|null` - Temporary directory path. + +##### cleanTempFiles() + +```php +public function cleanTempFiles($maxAge = 86400): int +``` + +Clean old temporary files. + +**Parameters**: +- `$maxAge` (int): Maximum age in seconds (default: 24 hours) + +**Returns**: `int` - Number of files deleted. + +##### getDiskUsage() + +```php +public function getDiskUsage(): array +``` + +Get disk usage for tenant. + +**Returns**: `array` - Usage information: +```php +array( + 'total_bytes' => 1234567, + 'total_mb' => 1.18, + 'file_count' => 42 +) +``` + +##### getStorageConfig() + +```php +public function getStorageConfig(): array +``` + +Get storage configuration. + +**Returns**: `array` - Storage configuration: +```php +array( + 'document_root' => '/path/to/documents', + 'tenant_id' => 'tenant1', + 'base_root' => '/var/www/documents' +) +``` + +--- + +## Helper Functions + +These global functions are available after bootstrapping: + +### mokodolimulti_bootstrap() + +```php +function mokodolimulti_bootstrap($configDir = null): bool +``` + +Bootstrap multi-tenant orchestration. + +**Parameters**: +- `$configDir` (string|null): Optional configuration directory override + +**Returns**: `bool` - True if bootstrap successful + +### mokodolimulti_get_tenant_resolver() + +```php +function mokodolimulti_get_tenant_resolver(): ?TenantResolver +``` + +Get current tenant resolver instance. + +**Returns**: `TenantResolver|null` + +### mokodolimulti_get_tenant_id() + +```php +function mokodolimulti_get_tenant_id(): ?string +``` + +Get current tenant ID. + +**Returns**: `string|null` + +### mokodolimulti_get_database_router() + +```php +function mokodolimulti_get_database_router(): ?DatabaseRouter +``` + +Get database router instance. + +**Returns**: `DatabaseRouter|null` + +### mokodolimulti_get_storage_router() + +```php +function mokodolimulti_get_storage_router(): ?StorageRouter +``` + +Get storage router instance. + +**Returns**: `StorageRouter|null` + +### mokodolimulti_is_active() + +```php +function mokodolimulti_is_active(): bool +``` + +Check if multi-tenant mode is active. + +**Returns**: `bool` - True if active + +--- + +## Usage Examples + +### Basic Tenant Resolution + +```php +require_once 'src/bootstrap.php'; + +// Bootstrap automatically called via auto_prepend_file +if (mokodolimulti_is_active()) { + $tenantId = mokodolimulti_get_tenant_id(); + echo "Current tenant: $tenantId"; +} +``` + +### Manual Resolution + +```php +use MokoDoliMulti\Core\TenantResolver; + +$resolver = new TenantResolver(); +if ($resolver->resolve('client1.example.com')) { + $dbHost = $resolver->getConfig('database.host'); + $docRoot = $resolver->getConfig('storage.document_root'); +} +``` + +### Database Operations + +```php +use MokoDoliMulti\Core\TenantResolver; +use MokoDoliMulti\Database\DatabaseRouter; + +$resolver = new TenantResolver(); +$resolver->resolve(); + +$router = new DatabaseRouter($resolver); +if ($router->testConnection()) { + echo "Database connection OK"; +} +``` + +### Storage Operations + +```php +use MokoDoliMulti\Core\TenantResolver; +use MokoDoliMulti\Storage\StorageRouter; + +$resolver = new TenantResolver(); +$resolver->resolve(); + +$router = new StorageRouter($resolver); +$router->ensureDirectories(); + +$invoicePath = $router->getDocumentPath('invoices', 'INV001'); +$usage = $router->getDiskUsage(); + +echo "Storage used: {$usage['total_mb']} MB"; +``` + +### Custom Integration + +```php +// In your Dolibarr hook or custom module +global $mokodolimulti_tenant_resolver; + +if ($mokodolimulti_tenant_resolver) { + $settings = $mokodolimulti_tenant_resolver->getConfig('settings'); + $timezone = $settings['timezone'] ?? 'UTC'; + date_default_timezone_set($timezone); +} +``` + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/architecture-ARCHITECTURE.-.-.md b/MokoConsulting/MokoDoliMulti/architecture-ARCHITECTURE.-.-.md new file mode 100644 index 0000000..d830219 --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/architecture-ARCHITECTURE.-.-.md @@ -0,0 +1,367 @@ +← [Home](Home) + +# MokoDoliMulti Architecture + +## Overview + +MokoDoliMulti provides domain-based multi-tenant orchestration for Dolibarr, enabling multiple organizations to run on a single Dolibarr codebase while maintaining complete isolation of data, configuration, and documents. + +## Architecture Principles + +### 1. Single Codebase + +All tenants share a single Dolibarr installation, reducing: +- Maintenance overhead +- Storage requirements +- Update complexity +- Security patching effort + +### 2. Per-Tenant Isolation + +Each tenant has isolated: +- Database (separate MySQL/PostgreSQL database) +- Document storage (separate file system directory) +- Configuration (tenant-specific settings) +- URL/Domain (unique virtual host) + +### 3. Domain-Based Routing + +Tenant resolution is based on the HTTP Host header, allowing: +- Clean URL separation (tenant1.example.com, tenant2.example.com) +- Wildcard domain support (*.company.com) +- Subdomain or full domain routing + +## Components + +### Bootstrap Layer (`src/bootstrap.php`) + +The bootstrap layer initializes before Dolibarr loads and: +1. Resolves the tenant from HTTP_HOST +2. Loads tenant-specific configuration +3. Overrides Dolibarr database settings +4. Sets document storage paths +5. Applies tenant-specific settings + +**Integration Point**: Configured via PHP `auto_prepend_file` directive in web server configuration. + +### Tenant Resolver (`src/core/TenantResolver.php`) + +**Responsibility**: Identify and load tenant configuration based on domain. + +**Key Methods**: +- `resolve($host)`: Main resolution logic +- `getTenantId()`: Get current tenant identifier +- `getConfig($key)`: Access tenant configuration +- `isResolved()`: Check if tenant was successfully resolved + +**Resolution Process**: +1. Extract HTTP_HOST from request +2. Look up tenant ID from domain mapping +3. Load tenant configuration file +4. Cache mapping for performance + +**Mapping Strategies**: +- Direct mapping: `'tenant1.example.com' => 'tenant1'` +- Wildcard patterns: `'*.client.com' => 'client'` + +### Database Router (`src/database/DatabaseRouter.php`) + +**Responsibility**: Route database connections to tenant-specific databases. + +**Key Methods**: +- `getDatabaseConfig()`: Get database configuration for current tenant +- `applyConfiguration()`: Override Dolibarr database globals +- `testConnection()`: Verify database connectivity +- `getConnectionString()`: Build PDO connection string + +**Database Isolation**: +Each tenant has a completely separate database instance: +- Different database name +- Optionally different user credentials +- Independent schema and data +- Can be on different database servers + +**Supported Databases**: +- MySQL/MariaDB (mysqli) +- PostgreSQL (pgsql) + +### Storage Router (`src/storage/StorageRouter.php`) + +**Responsibility**: Route document storage to tenant-specific directories. + +**Key Methods**: +- `getDocumentRoot()`: Get tenant document root path +- `applyConfiguration()`: Set Dolibarr document path +- `ensureDirectories()`: Create required directory structure +- `isPathSafe()`: Validate paths stay within tenant boundary +- `getDiskUsage()`: Monitor tenant storage consumption + +**Storage Structure**: +``` +/var/www/documents/ +├── tenant1/ +│ ├── company/ +│ ├── invoices/ +│ ├── proposals/ +│ ├── orders/ +│ ├── contracts/ +│ ├── products/ +│ ├── users/ +│ ├── temp/ +│ └── medias/ +├── tenant2/ +│ └── ... +``` + +**Security**: +- Path traversal protection +- Tenant boundary enforcement +- Directory permission management + +## Configuration + +### Tenant Configuration Schema + +Each tenant has a configuration file: `src/config/tenants/{tenant_id}.php` + +```php +return array( + 'tenant_id' => 'unique_identifier', + 'tenant_name' => 'Display Name', + 'main_url' => 'https://domain.com', + + 'database' => array( + 'type' => 'mysqli', + 'host' => 'localhost', + 'port' => 3306, + 'name' => 'database_name', + 'user' => 'database_user', + 'password' => 'secure_password', + 'prefix' => 'llx_', + 'charset' => 'utf8mb4', + ), + + 'storage' => array( + 'document_root' => '/path/to/documents', + ), + + 'authentication' => array( + 'mode' => 'dolibarr', + // Optional: LDAP, OAuth, etc. + ), + + 'settings' => array( + 'timezone' => 'UTC', + 'language' => 'en_US', + 'currency' => 'USD', + ), +); +``` + +### Domain Mapping + +Central mapping file: `src/config/tenants/mapping.php` + +```php +return array( + 'exact.domain.com' => 'tenant_id', + '*.wildcard.com' => 'tenant_id', +); +``` + +## Request Flow + +``` +1. HTTP Request arrives + ↓ +2. Web server loads bootstrap.php (auto_prepend_file) + ↓ +3. TenantResolver extracts HTTP_HOST + ↓ +4. Lookup tenant ID from mapping + ↓ +5. Load tenant configuration + ↓ +6. DatabaseRouter overrides DB globals + ↓ +7. StorageRouter sets document paths + ↓ +8. Dolibarr loads with tenant-specific configuration + ↓ +9. Request processed in tenant context + ↓ +10. Response returned +``` + +## Performance Considerations + +### Caching + +- Tenant mapping cached in memory per request +- Configuration loaded once per request +- No persistent cache required (PHP opcache handles file caching) + +### Database Connections + +- Each tenant uses separate connection pool +- Connection pooling handled by PHP/database driver +- Consider connection limits with many concurrent tenants + +### File System + +- Document directories isolated per tenant +- Use fast storage (SSD) for document root +- Consider separate mount points for large tenants + +## Scalability + +### Horizontal Scaling + +MokoDoliMulti supports horizontal scaling: + +1. **Load Balancer**: Distribute requests across multiple web servers +2. **Shared Storage**: Use NFS, GlusterFS, or object storage for documents +3. **Database Scaling**: + - Read replicas for tenant databases + - Separate database servers per tenant or tenant group +4. **CDN**: Cache static assets + +### Vertical Scaling + +- Increase web server resources +- Optimize database server +- Use PHP-FPM process management + +### Tenant Isolation Levels + +**Standard**: All tenants on same infrastructure +**Enhanced**: Critical tenants on dedicated database servers +**Complete**: Full infrastructure isolation per tenant + +## Security Architecture + +### Isolation Boundaries + +1. **Network**: Separate virtual hosts +2. **Database**: Separate databases with different credentials +3. **File System**: Separate directories with permission boundaries +4. **Application**: Dolibarr session isolation + +### Security Controls + +- Path traversal protection in storage router +- Database credential isolation per tenant +- No shared sessions between tenants +- Audit logging per tenant +- Input validation on tenant ID resolution + +### Threat Model + +**Protected Against**: +- Cross-tenant data access +- Path traversal attacks +- SQL injection (via Dolibarr) +- Session hijacking between tenants + +**Shared Resources** (potential attack surface): +- PHP process space (mitigated by process isolation) +- Dolibarr codebase (updates affect all tenants) +- Web server configuration + +## Monitoring and Operations + +### Health Checks + +Monitor per tenant: +- Database connectivity +- Document storage availability +- Disk usage +- Response times + +### Logging + +Separate logs per tenant: +- Web server access logs +- Web server error logs +- Application logs (if configured) + +### Backup Strategy + +Per-tenant backup requirements: +1. Database dump per tenant +2. Document directory backup per tenant +3. Configuration backup (all tenants) + +### Maintenance Windows + +- Updates applied to shared codebase affect all tenants +- Plan maintenance windows accordingly +- Test updates on staging tenant first + +## Integration Points + +### Web Server + +- Apache: `php_value auto_prepend_file` +- Nginx: `fastcgi_param PHP_VALUE` + +### Dolibarr + +- Database configuration override +- Document root override +- Configuration constants + +### External Systems + +- Can integrate per-tenant external services +- API keys stored in tenant configuration +- OAuth providers per tenant + +## Future Enhancements + +Potential future developments: + +1. **Admin Interface**: Web UI for tenant management +2. **API**: REST API for tenant operations +3. **Monitoring Dashboard**: Real-time tenant health +4. **Auto-scaling**: Dynamic resource allocation +5. **Tenant Migration**: Tools for moving tenants between servers +6. **Billing Integration**: Usage tracking per tenant +7. **Backup Automation**: Scheduled per-tenant backups + +## Design Decisions + +### Why PHP Bootstrap? + +- Executes before Dolibarr loads +- No Dolibarr code modifications required +- Simple integration via web server config + +### Why File-Based Configuration? + +- Simple and readable +- Version control friendly +- No external dependencies +- Fast (opcache) + +### Why Separate Databases? + +- Complete data isolation +- Independent scaling +- Easier backup/restore +- Better security boundaries + +### Why Document Root Isolation? + +- File system security +- Quota management per tenant +- Independent backup +- Storage migration flexibility + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliMulti/update-server.-.-.md b/MokoConsulting/MokoDoliMulti/update-server.-.-.md new file mode 100644 index 0000000..b71bedc --- /dev/null +++ b/MokoConsulting/MokoDoliMulti/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliMulti/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliMulti](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMulti) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliOffline/Home.md b/MokoConsulting/MokoDoliOffline/Home.md new file mode 100644 index 0000000..1eb857e --- /dev/null +++ b/MokoConsulting/MokoDoliOffline/Home.md @@ -0,0 +1,41 @@ +# MokoDoliOffline + +A Dolibarr module enabling offline mode and PWA. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliOffline) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [update server](update-server.-.-) | ← [Home](Home) | +| [user guide](user-guide.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliOffline](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliOffline) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliOffline/README.md b/MokoConsulting/MokoDoliOffline/README.md new file mode 100644 index 0000000..c633b3f --- /dev/null +++ b/MokoConsulting/MokoDoliOffline/README.md @@ -0,0 +1,97 @@ +← [Home](Home) + +# MokoDoliOffline Documentation + +Welcome to the MokoDoliOffline documentation. This module enables offline mode and Progressive Web App (PWA) capabilities for Dolibarr ERP & CRM. + +## Documentation Index + +### Getting Started + +- **[Installation Guide](installation.md)** - Complete installation instructions +- **[User Guide](user-guide.md)** - End-user documentation for using offline features + +### Reference + +- **[README](README)** - Project overview and features +- **[CHANGELOG](CHANGELOG)** - Version history and changes +- **[LICENSE](../LICENSE)** - License information (GPL-3.0-or-later) + +### Contributing + +- **[CONTRIBUTING](CONTRIBUTING)** - Contribution guidelines +- **[SECURITY](SECURITY)** - Security policy and vulnerability reporting + +## Quick Links + +### For Users + +- [Installing as a PWA](user-guide.md#installing-as-a-pwa) +- [Using Offline Mode](user-guide.md#using-offline-mode) +- [Troubleshooting](user-guide.md#troubleshooting) + +### For Administrators + +- [Installation Steps](installation.md#installation-methods) +- [Module Configuration](installation.md#configuration) +- [Verification](installation.md#verification) + +### For Developers + +- [Module Structure](../README.md#architecture) +- [Code Standards](../CONTRIBUTING.md#coding-standards) +- [Contributing](../CONTRIBUTING.md#getting-started) + +## Module Information + +- **Module ID**: 185062 +- **Module Key**: mokodolioffline +- **Version**: 1.0.0 +- **License**: GPL-3.0-or-later +- **Author**: Moko Consulting +- **Repository**: https://github.com/mokoconsulting-tech/MokoDoliOffline + +## Features + +✅ **Offline Caching** - Service worker for offline page access +✅ **PWA Support** - Install as native-like application +✅ **Network Status** - Visual online/offline indicator +✅ **Auto-Update** - Automatic service worker updates +✅ **Configurable** - Admin interface for settings + +## Support + +- **Issues**: [GitHub Issues](https://github.com/mokoconsulting-tech/MokoDoliOffline/issues) +- **Discussions**: [GitHub Discussions](https://github.com/mokoconsulting-tech/MokoDoliOffline/discussions) +- **Email**: hello@mokoconsulting.tech + +## Standards Compliance + +This module follows [moko-platform](https://github.com/mokoconsulting-tech/MokoCodingDefaults): + +- ✅ SPDX-compliant file headers +- ✅ GPL-3.0-or-later license +- ✅ Conventional commit messages +- ✅ Dolibarr coding conventions +- ✅ Comprehensive documentation +- ✅ Security best practices + +## Additional Resources + +- [Dolibarr Documentation](https://wiki.dolibarr.org) +- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) +- [Progressive Web Apps](https://web.dev/progressive-web-apps/) +- [moko-platform](https://github.com/mokoconsulting-tech/MokoCodingDefaults) + +--- + +Last Updated: 2025-01-13 +Version: 1.0.0 + +--- + +*Repo: [MokoDoliOffline](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliOffline) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliOffline/installation.md b/MokoConsulting/MokoDoliOffline/installation.md new file mode 100644 index 0000000..4aa7a0f --- /dev/null +++ b/MokoConsulting/MokoDoliOffline/installation.md @@ -0,0 +1,213 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing MokoDoliOffline in your Dolibarr instance. + +## Prerequisites + +Before installing MokoDoliOffline, ensure you have: + +- Dolibarr 13.0 or higher installed and running +- PHP 7.0 or higher +- HTTPS enabled (required for service workers and PWA) +- Administrator access to your Dolibarr installation +- Write permissions to the Dolibarr `custom` directory + +## Installation Methods + +### Method 1: Manual Installation (Recommended) + +1. **Download the Module** + + Download the latest release from the [GitHub releases page](https://github.com/mokoconsulting-tech/MokoDoliOffline/releases). + +2. **Extract and Copy Files** + + ```bash + # Extract the archive + unzip mokodolioffline-v1.0.0.zip + + # Copy to Dolibarr custom directory + cp -r src /path/to/dolibarr/htdocs/custom/mokodolioffline + ``` + +3. **Set Permissions** + + ```bash + # Set ownership (adjust user/group as needed) + chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/mokodolioffline + + # Set permissions + chmod -R 755 /path/to/dolibarr/htdocs/custom/mokodolioffline + ``` + +4. **Verify Installation** + + Check that the directory structure is correct: + ```bash + ls -la /path/to/dolibarr/htdocs/custom/mokodolioffline/ + ``` + + You should see: admin, class, core, css, js, lang, lib, sql directories + +### Method 2: Git Clone + +1. **Clone the Repository** + + ```bash + cd /path/to/dolibarr/htdocs/custom/ + git clone https://github.com/mokoconsulting-tech/MokoDoliOffline.git mokodolioffline + cd mokodolioffline + mv src/* . + rm -rf src + ``` + +2. **Set Permissions** + + Same as Method 1, step 3. + +## Activation + +1. **Log in to Dolibarr** + + Access your Dolibarr instance as an administrator. + +2. **Navigate to Modules** + + Go to **Home → Setup → Modules/Applications** + +3. **Find the Module** + + Scroll down or search for "Offline Mode & PWA" or "MokoDoliOffline" + +4. **Activate the Module** + + Click the **Activate** button next to the module name. + +5. **Verify Activation** + + The module status should change to "Enabled" with a green checkmark. + +## Configuration + +After activation, configure the module: + +1. **Access Settings** + + Click on the gear icon next to the module name, or navigate to: + **Home → Setup → Modules/Applications → Offline Mode & PWA → Settings** + +2. **Configure Options** + + - **Enable Service Worker Cache**: Toggle on to enable offline caching + - **Cache Version**: Set initial version (e.g., "v1") + - **Enable PWA**: Toggle on to enable Progressive Web App features + - **PWA Application Name**: Enter your preferred app name (e.g., "Dolibarr ERP") + - **PWA Short Name**: Enter a short name (e.g., "Dolibarr") + +3. **Save Settings** + + Click **Save** to apply your configuration. + +## Verification + +### Verify Service Worker + +1. Open your Dolibarr instance in a modern browser (Chrome, Firefox, Edge) +2. Open Developer Tools (F12) +3. Go to the **Application** tab (Chrome/Edge) or **Storage** tab (Firefox) +4. Under **Service Workers**, you should see the registered service worker +5. Check that the status shows "activated and is running" + +### Verify PWA + +1. In supported browsers, you should see an install icon in the address bar +2. Clicking it should offer to install Dolibarr as an app +3. After installation, the app should appear in your application menu + +### Test Offline Mode + +1. Open Developer Tools +2. Go to **Application → Service Workers** +3. Check the "Offline" checkbox +4. Navigate through Dolibarr - cached pages should load +5. Uncheck "Offline" to return to normal mode + +## Troubleshooting + +### Service Worker Not Registering + +- **HTTPS Required**: Service workers only work over HTTPS (or localhost) + - Solution: Enable HTTPS on your server + +- **Path Issues**: Service worker script not found + - Solution: Verify file paths in browser console + - Check that `/custom/mokodolioffline/js/sw.js` is accessible + +### Module Not Appearing + +- **File Permissions**: Incorrect permissions + - Solution: Run permission commands from step 3 of installation + +- **Cache Issues**: Dolibarr cache needs clearing + - Solution: Clear Dolibarr cache in Setup → Other + +### PWA Not Installable + +- **HTTPS Required**: PWA requires HTTPS + - Solution: Enable HTTPS + +- **Manifest Issues**: Manifest not loading + - Solution: Check `/custom/mokodolioffline/js/manifest.json.php` loads correctly + +- **Browser Support**: Browser doesn't support PWA + - Solution: Use Chrome, Edge, Safari, or Firefox + +## Uninstallation + +If you need to uninstall the module: + +1. **Deactivate Module** + + Go to **Home → Setup → Modules/Applications** and click **Deactivate** + +2. **Remove Files** (Optional) + + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/mokodolioffline + ``` + +3. **Clear Service Worker** (Optional) + + - Open Developer Tools → Application → Service Workers + - Click "Unregister" next to the service worker + +4. **Clear Browser Cache** + + Clear your browser cache to remove cached files + +## Next Steps + +After successful installation: + +- Read the [User Guide](user-guide.md) to learn how to use the module +- Review [Security Best Practices](SECURITY) +- Check the [Configuration Guide](configuration.md) for advanced settings + +## Support + +If you encounter issues: + +- Check the [Troubleshooting](troubleshooting.md) guide +- Search [GitHub Issues](https://github.com/mokoconsulting-tech/MokoDoliOffline/issues) +- Create a new issue with details about your problem +- Contact: hello@mokoconsulting.tech + +--- + +*Repo: [MokoDoliOffline](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliOffline) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliOffline/update-server.-.-.md b/MokoConsulting/MokoDoliOffline/update-server.-.-.md new file mode 100644 index 0000000..3e9df27 --- /dev/null +++ b/MokoConsulting/MokoDoliOffline/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliOffline/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliOffline](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliOffline) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliOffline/user-guide.-.-.md b/MokoConsulting/MokoDoliOffline/user-guide.-.-.md new file mode 100644 index 0000000..7b02650 --- /dev/null +++ b/MokoConsulting/MokoDoliOffline/user-guide.-.-.md @@ -0,0 +1,268 @@ +← [Home](Home) + +# User Guide + +This guide explains how to use MokoDoliOffline's features as an end user. + +## Overview + +MokoDoliOffline enables you to: + +- Access Dolibarr pages offline when no internet connection is available +- Install Dolibarr as a standalone application on your device +- See your network connection status at all times +- Continue working with cached data when offline + +## Installing as a PWA + +### Desktop (Chrome/Edge/Brave) + +1. Open Dolibarr in your browser +2. Look for the install icon (⊕ or 🖥️) in the address bar +3. Click the icon +4. Click "Install" in the popup dialog +5. Dolibarr will open in a new window and appear in your applications + +### Desktop (Firefox) + +1. Click the menu button (≡) +2. Select "Install [site name]" +3. Follow the prompts + +### Mobile (iOS Safari) + +1. Open Dolibarr in Safari +2. Tap the Share button (square with arrow) +3. Scroll down and tap "Add to Home Screen" +4. Give it a name and tap "Add" +5. The app icon will appear on your home screen + +### Mobile (Android Chrome) + +1. Open Dolibarr in Chrome +2. Tap the menu button (⋮) +3. Tap "Install app" or "Add to Home Screen" +4. Follow the prompts +5. The app will appear in your app drawer + +## Using Offline Mode + +### How It Works + +When you visit pages in Dolibarr: + +1. Pages and assets are automatically cached +2. When offline, you can access cached pages +3. A network status indicator shows your connection status +4. When back online, new content is fetched automatically + +### Network Status Indicator + +Look for the status badge in the top-right corner: + +- **Green "Online"**: You have internet connection +- **Red "Offline"**: No internet connection, using cached content + +### What Works Offline + +Currently cached for offline access: + +- Previously visited pages +- CSS stylesheets +- JavaScript files +- Images and logos +- Static assets + +### What Doesn't Work Offline + +Not available when offline: + +- Creating new records (requires server) +- Updating existing records (requires server) +- Loading pages not previously visited +- Real-time data (will show last cached version) + +## Working with Cached Content + +### Viewing Cached Pages + +1. Visit pages while online to cache them +2. When offline, navigate to previously visited pages +3. Content will load from cache +4. You can browse and read cached information + +### Cache Updates + +The cache updates automatically: + +- When you visit pages while online +- When the administrator updates the cache version +- When the service worker updates + +### Manual Cache Refresh + +To ensure you have the latest content: + +1. While online, refresh the page (F5 or Ctrl+R) +2. This will fetch and cache the newest version +3. The updated content will be available offline + +## Managing the PWA + +### Uninstalling the PWA + +#### Desktop + +1. Right-click the app icon in your taskbar/dock +2. Select "Uninstall" or "Remove" +3. Confirm the uninstallation + +Or: + +1. Open the app +2. Click the menu (⋮) +3. Select "Uninstall [app name]" + +#### Mobile (iOS) + +1. Long-press the app icon +2. Tap "Remove App" +3. Confirm removal + +#### Mobile (Android) + +1. Long-press the app icon +2. Tap "App info" +3. Tap "Uninstall" + +## Tips and Best Practices + +### For Optimal Offline Experience + +1. **Cache Important Pages**: While online, visit pages you'll need offline +2. **Check Connection**: Monitor the network status indicator +3. **Sync When Online**: Let the app sync when you're back online +4. **Update Regularly**: Keep the app updated for best performance + +### Understanding Limitations + +- **Read-Only Offline**: You can view but not modify data when offline +- **Stale Data**: Offline data may be outdated until you reconnect +- **Storage Limits**: Browsers limit cache size (usually 50MB+) +- **Cache Expiration**: Old cache may be cleared automatically + +### Maximizing Productivity + +1. **Plan Ahead**: Cache important data before going offline +2. **Note Changes**: Keep track of changes you want to make when back online +3. **Verify Updates**: Check that data is current after reconnecting +4. **Use Bookmarks**: Bookmark frequently used pages for quick access + +## Troubleshooting + +### App Not Installing + +**Problem**: Install option doesn't appear + +**Solutions**: +- Ensure you're using HTTPS +- Use a supported browser (Chrome, Edge, Safari, Firefox) +- Check that you haven't already installed it +- Try refreshing the page + +### Offline Content Not Loading + +**Problem**: Pages don't load when offline + +**Solutions**: +- Make sure you visited the pages while online first +- Check network status indicator +- Clear cache and revisit pages while online +- Contact your administrator about cache settings + +### Update Notification + +**Problem**: "New version available" message appears + +**Solutions**: +- Click "OK" to reload and get the update +- This ensures you have the latest features and fixes +- Your cached content will be preserved + +### Cache Full Warning + +**Problem**: Browser cache is full + +**Solutions**: +- Clear browser cache: Settings → Privacy → Clear browsing data +- Uninstall and reinstall the PWA +- Contact your administrator about cache optimization + +## Keyboard Shortcuts + +Standard Dolibarr shortcuts work in the PWA: + +- **Ctrl+S** (Cmd+S on Mac): Save current form +- **Ctrl+F** (Cmd+F on Mac): Search within page +- **Alt+Left/Right**: Navigate back/forward + +## Privacy and Security + +### Data Storage + +- Cached data is stored locally on your device +- Cache is browser-specific (Chrome cache ≠ Firefox cache) +- Cache persists until cleared or replaced + +### Security Notes + +- Always log out when done +- Use device security (PIN, password, biometric) +- Clear cache on shared devices +- Report security concerns to your administrator + +### Data Sync + +- Data syncs automatically when online +- No manual sync required (in current version) +- Future versions will support explicit sync control + +## Getting Help + +### Common Questions + +See our [FAQ](faq.md) for answers to common questions. + +### Support Resources + +- **Documentation**: Read module documentation +- **Administrator**: Contact your Dolibarr administrator +- **Issues**: Report bugs on [GitHub](https://github.com/mokoconsulting-tech/MokoDoliOffline/issues) + +### Feedback + +We welcome your feedback: + +- Feature requests: [GitHub Discussions](https://github.com/mokoconsulting-tech/MokoDoliOffline/discussions) +- Bug reports: [GitHub Issues](https://github.com/mokoconsulting-tech/MokoDoliOffline/issues) +- General inquiries: hello@mokoconsulting.tech + +## What's Next + +Future versions will include: + +- Offline data entry and editing +- Background synchronization +- Push notifications +- Enhanced offline capabilities +- More configuration options + +Stay tuned for updates! + +--- + +*Repo: [MokoDoliOffline](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliOffline) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliPhoneCom/Home.md b/MokoConsulting/MokoDoliPhoneCom/Home.md new file mode 100644 index 0000000..e597f16 --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/Home.md @@ -0,0 +1,43 @@ +# MokoDoliPhoneCom + +A Dolibarr module to bridge to Phone.com service + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [changelog](changelog) | ← [Home](Home) | +| [development](development) | ← [Home](Home) | +| [module id policy](module-id-policy.-.-) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliPhoneCom/README.md b/MokoConsulting/MokoDoliPhoneCom/README.md new file mode 100644 index 0000000..51876df --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/README.md @@ -0,0 +1,148 @@ +← [Home](Home) + +# Documentation Index + +Welcome to the moko-platform Dolibarr Template documentation. This guide will help you navigate all available documentation resources. + +## Quick Links + +- [Installation Guide](installation.md) - Get started with installing the template +- [Development Guide](development.md) - Learn how to develop Dolibarr modules +- [Module ID Policy](module-id-policy.md) - Understand module ID assignment process +- [Changelog](changelog.md) - Track version history and changes + +## Documentation Structure + +### For New Users + +If you're new to this template, start here: + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation instructions + - Configuration and setup + - Troubleshooting common issues + +2. **[Module ID Policy](module-id-policy.md)** + - Understanding module IDs + - Development vs. production IDs + - How to request an official ID + - Best practices + +### For Developers + +If you're developing a module, these guides will help: + +1. **[Development Guide](development.md)** + - Module structure and organization + - Module descriptor configuration + - Coding standards and best practices + - Security guidelines + - Database operations + - Testing and debugging + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + - Commit message guidelines + +### Reference Materials + +- **[Changelog](changelog.md)** - Version history and release notes +- **[README](README)** - Project overview and quick start + +## Getting Help + +### Common Questions + +**Q: Where do I start?** +A: Begin with the [Installation Guide](installation.md) to set up the template, then review the [Development Guide](development.md) for building your module. + +**Q: What module ID should I use?** +A: Use an ID greater than 600,000 during development. See the [Module ID Policy](module-id-policy.md) for details. + +**Q: How do I contribute?** +A: Check out the [Contributing Guidelines](CONTRIBUTING) for the complete process. + +**Q: Where are the code examples?** +A: The [Development Guide](development.md) contains numerous code examples and best practices. + +### Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ +- **Dolibarr Documentation**: https://www.dolibarr.org/doc/html/ + +## External Resources + +### Official Dolibarr Documentation + +- [Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [API Reference](https://www.dolibarr.org/doc/html/) + +### moko-platform + +- [MokoConsulting Tech GitHub](https://github.com/mokoconsulting-tech) +- Template Repository: [moko-platform-Template-Dolibarr](https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr) + +## Documentation Conventions + +Throughout this documentation, you'll see these conventions: + +- **Bold text**: Important concepts or required fields +- `Code formatting`: File names, code snippets, commands +- > Blockquotes: Important notes or warnings +- ✅ Checkmarks: Best practices or recommended actions +- ❌ Cross marks: Things to avoid + +### Code Examples + +Code examples use syntax highlighting and include comments: + +```php +// Example PHP code with explanation +$this->numero = 600001; // Development module ID +``` + +```bash +# Example command line operations +cd /path/to/dolibarr/ +git clone repo-url +``` + +## Contributing to Documentation + +Found an error or want to improve the documentation? + +1. Fork the repository +2. Edit the relevant markdown file +3. Submit a pull request +4. Follow the [Contributing Guidelines](CONTRIBUTING) + +Good documentation helps everyone! + +## Version Information + +- **Template Version**: 1.0.0 +- **Last Updated**: 2026-01-16 +- **Minimum Dolibarr Version**: 12.0 +- **PHP Version**: 7.4+ + +--- + +**Next Steps**: +- New to the template? Start with [Installation Guide](installation.md) +- Ready to develop? Check out [Development Guide](development.md) +- Need to request a module ID? Review [Module ID Policy](module-id-policy.md) + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliPhoneCom/changelog.md b/MokoConsulting/MokoDoliPhoneCom/changelog.md new file mode 100644 index 0000000..2427ca2 --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/changelog.md @@ -0,0 +1,70 @@ +← [Home](Home) + +# Changelog + +All notable changes to this project template will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Comprehensive README.md with project overview and usage instructions +- Module ID policy documentation +- Installation guide with detailed setup instructions +- Development guide with best practices and examples +- Contributing guidelines +- Documentation structure following moko-platform + +## [1.0.0] - 2026-01-16 + +### Added +- Initial template structure for Dolibarr modules +- Basic documentation framework +- Module ID policy requiring issue-based requests +- Support for temporary development IDs (600,000+) + +--- + +## Template Usage Notes + +When using this template for your module: + +1. Copy this changelog to your project +2. Update the version numbers as you develop +3. Document all changes in the appropriate category: + - **Added** for new features + - **Changed** for changes in existing functionality + - **Deprecated** for soon-to-be removed features + - **Removed** for now removed features + - **Fixed** for any bug fixes + - **Security** for vulnerability fixes + +Example entry: +```markdown +## [1.1.0] - 2026-02-15 + +### Added +- New feature X for handling Y +- Support for Z functionality + +### Fixed +- Bug in module activation +- Permission check in admin page + +### Changed +- Updated module descriptor format +- Improved error handling +``` + +[Unreleased]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr/releases/tag/v1.0.0 + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliPhoneCom/development.md b/MokoConsulting/MokoDoliPhoneCom/development.md new file mode 100644 index 0000000..dcad338 --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/development.md @@ -0,0 +1,323 @@ +← [Home](Home) + +# Development Guide + +This guide provides best practices and guidelines for developing Dolibarr modules using this template. + +## Module Structure + +A well-organized Dolibarr module follows this structure: + +``` +yourmodule/ +├── class/ # Business logic classes +│ ├── yourmodule.class.php # Main business object +│ └── api_yourmodule.class.php # REST API endpoints (optional) +├── core/ # Core integrations +│ ├── modules/ # Numbering modules +│ └── triggers/ # Event triggers +│ └── interface_99_modYourmodule_YourmoduleTriggers.class.php +├── lang/ # Translations +│ ├── en_US/ +│ │ └── yourmodule.lang +│ └── fr_FR/ +│ └── yourmodule.lang +├── sql/ # Database scripts +│ ├── llx_yourmodule_table.sql +│ └── llx_yourmodule_table.key.sql +├── css/ # Stylesheets +│ └── yourmodule.css +├── js/ # JavaScript +│ └── yourmodule.js +├── img/ # Images and icons +│ └── object_yourmodule.png +├── lib/ # Helper functions +│ └── yourmodule.lib.php +├── docs/ # Documentation +├── admin/ # Admin pages +│ ├── setup.php # Configuration page +│ └── about.php # About page +├── yourmodule_page.php # Main module page +├── modYourmodule.class.php # Module descriptor +└── README.md +``` + +## Module Descriptor + +The module descriptor (`modYourmodule.class.php`) is the core configuration file. + +### Essential Properties + +```php +db = $db; + + // Module ID - use 600,000+ for development + $this->numero = 600001; + + // Module identification + $this->rights_class = 'yourmodule'; + $this->family = "other"; + $this->module_position = '1000'; + + // Module name and description + $this->name = preg_replace('/^mod/i', '', get_class($this)); + $this->description = "Module description"; + $this->descriptionlong = "Detailed module description"; + + // Version + $this->version = '1.0.0'; + $this->const_name = 'MAIN_MODULE_' . strtoupper($this->name); + + // Dependencies + $this->depends = array(); // e.g., array('modThirdparty', 'modProduct') + $this->requiredby = array(); + $this->conflictwith = array(); + + // Language files + $this->langfiles = array("yourmodule@yourmodule"); + + // Configuration page + $this->config_page_url = array("setup.php@yourmodule"); + + // Constants + $this->const = array(); + + // Permissions + $this->rights = array(); + $r = 0; + + $this->rights[$r][0] = $this->numero . sprintf("%02d", $r + 1); + $this->rights[$r][1] = 'Read objects of YourModule'; + $this->rights[$r][4] = 'yourmodule'; + $this->rights[$r][5] = 'read'; + $r++; + + // Menus + $this->menu = array(); + } +} +``` + +## Best Practices + +### 1. Coding Standards + +Follow Dolibarr coding standards: + +- **Indentation**: Use tabs for indentation +- **Naming**: Use camelCase for functions, lowercase for files +- **Comments**: Use PHPDoc format for documentation +- **Security**: Always sanitize inputs and escape outputs + +Example: + +```php +/** + * Get list of objects + * + * @param string $sortfield Sort field + * @param string $sortorder Sort order + * @param int $limit Limit + * @param int $offset Offset + * @return array Array of objects + */ +public function fetchAll($sortfield = 's.rowid', $sortorder = 'ASC', $limit = 0, $offset = 0) +{ + $sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; + // Add security and parameters +} +``` + +### 2. Security + +Always implement proper security: + +```php +// Check permissions +if (!$user->rights->yourmodule->read) { + accessforbidden(); +} + +// Sanitize inputs +$id = GETPOST('id', 'int'); +$name = GETPOST('name', 'alpha'); + +// Use prepared statements +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "table WHERE id = " . (int)$id; + +// Escape output +print dol_escape_htmltag($user_input); +``` + +**Important**: Review our [Security Policy](SECURITY) for comprehensive security guidelines and best practices. + +### 3. Database Operations + +Use Dolibarr's database abstraction: + +```php +// Insert +$sql = "INSERT INTO " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " (field1, field2) VALUES ('" . $this->db->escape($value1) . "', '" . $this->db->escape($value2) . "')"; +$resql = $this->db->query($sql); + +// Update +$sql = "UPDATE " . MAIN_DB_PREFIX . "yourmodule_table"; +$sql .= " SET field1 = '" . $this->db->escape($value) . "'"; +$sql .= " WHERE rowid = " . (int)$id; +$resql = $this->db->query($sql); + +// Select +$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "yourmodule_table"; +$resql = $this->db->query($sql); +if ($resql) { + $num = $this->db->num_rows($resql); + while ($i < $num) { + $obj = $this->db->fetch_object($resql); + // Process object + $i++; + } +} +``` + +### 4. Translations + +Use translation keys in language files: + +```php +// In lang/en_US/yourmodule.lang +YourModuleSetup = Your Module Setup +YourModuleDescription = This is your module +``` + +```php +// In PHP code +$langs->load("yourmodule@yourmodule"); +print $langs->trans("YourModuleSetup"); +``` + +### 5. Hooks and Triggers + +Implement triggers for event handling: + +```php +class InterfaceModYourmoduleTriggers +{ + public function runTrigger($action, $object, $user, $langs, $conf) + { + if ($action == 'BILL_CREATE') { + // Handle invoice creation + } + return 0; + } +} +``` + +### 6. API Development + +Create REST API endpoints: + +```php +class YourModuleApi extends DolibarrApi +{ + /** + * @url GET /yourmodule/objects + */ + public function index($sortfield = "t.rowid", $sortorder = 'ASC', $limit = 100, $page = 0) + { + // Implement API logic + } +} +``` + +## Testing + +### Manual Testing + +1. Test module activation/deactivation +2. Verify permissions work correctly +3. Check database operations +4. Test with different user roles +5. Verify translations + +### Debugging + +Enable Dolibarr debugging: + +```php +// In conf/conf.php +$dolibarr_main_prod = 0; // Development mode +``` + +View logs in `/documents/dolibarr.log` + +## Module ID Management + +### Development Phase + +Use module ID > 600,000: + +```php +$this->numero = 600001; +``` + +### Before Distribution + +1. Create an issue in the repository requesting a module ID +2. Wait for approval and assignment +3. Update the module descriptor with the assigned ID +4. Test thoroughly before release + +See [Module ID Policy](module-id-policy.md) for details. + +## Version Control + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Update version in: +- `modYourmodule.class.php` +- `docs/changelog.md` +- Documentation files + +## Publishing + +Before publishing your module: + +1. ✅ Request and receive official module ID +2. ✅ Complete all documentation +3. ✅ Test on multiple Dolibarr versions +4. ✅ Review security best practices +5. ✅ Add license file +6. ✅ Update changelog +7. ✅ Create release notes + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) +- [Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +## Support + +- Repository issues for template questions +- [Dolibarr Forum](https://www.dolibarr.org/forum) for development help +- [Dolibarr GitHub](https://github.com/Dolibarr/dolibarr) for core issues + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliPhoneCom/installation.md b/MokoConsulting/MokoDoliPhoneCom/installation.md new file mode 100644 index 0000000..31bf94a --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/installation.md @@ -0,0 +1,173 @@ +← [Home](Home) + +# Installation Guide + +This guide provides detailed instructions for installing and configuring your Dolibarr module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version 12.0 or higher +- **PHP**: Version 7.4 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **PHP Extensions**: + - mysqli or pgsql + - gd or imagick + - curl + - json + - xml + +## Installation Steps + +### 1. Clone the Repository + +Navigate to your Dolibarr's custom directory: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +``` + +Clone this template repository: + +```bash +git clone https://github.com/mokoconsulting-tech/moko-platform-Template-Dolibarr.git yourmodule +``` + +Replace `yourmodule` with your desired module name (lowercase, no spaces). + +### 2. Rename and Configure + +Navigate to the module directory: + +```bash +cd yourmodule +``` + +Rename the module descriptor file: + +```bash +mv modYourmodule.class.php modYourModuleName.class.php +``` + +### 3. Configure Module ID + +Open the module descriptor file and set a temporary module ID greater than 600,000: + +```php +// In modYourModuleName.class.php +$this->numero = 600001; // Use a number > 600,000 for development +``` + +**Important:** Before publishing, request an official module ID by creating an issue in the repository. + +### 4. Set File Permissions + +Ensure proper file permissions: + +```bash +# Set ownership (adjust user:group as needed) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/yourmodule + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/yourmodule -type f -exec chmod 644 {} \; +``` + +### 5. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as an administrator +2. Navigate to **Home → Setup → Modules/Applications** +3. Find your module in the list +4. Click the **Activate** button + +### 6. Configure Module Settings (if applicable) + +After activation: + +1. Go to **Home → Setup → Modules/Applications** +2. Click on your module name to access its configuration page +3. Configure any required settings +4. Save changes + +## Database Setup + +If your module requires database tables: + +### Automatic Setup + +The module descriptor can handle automatic table creation during activation. Ensure your SQL files are in the `sql/` directory: + +``` +sql/ +├── llx_yourmodule_table.sql +└── llx_yourmodule_table.key.sql +``` + +### Manual Setup + +Alternatively, run SQL scripts manually: + +```bash +mysql -u username -p database_name < sql/llx_yourmodule_table.sql +``` + +## Troubleshooting + +### Module Not Appearing + +- Clear Dolibarr cache: Delete `/documents/install.lock` and refresh +- Check file permissions +- Verify PHP syntax errors: `php -l modYourModuleName.class.php` + +### Permission Errors + +- Ensure Apache/Nginx user has read access to all module files +- Check `conf.php` file permissions in Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Check SQL file syntax +- Ensure database user has CREATE TABLE permissions + +## Uninstallation + +To remove the module: + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find your module and click **Deactivate** +3. Optionally, remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/yourmodule + ``` + +**Note:** Deactivating the module does not remove database tables. To remove data: + +```sql +DROP TABLE llx_yourmodule_table; +``` + +## Next Steps + +- Review the [Development Guide](development.md) to start customizing your module +- Check the [Module ID Policy](module-id-policy.md) before distribution +- Read the [Changelog](changelog.md) for version history + +## Support + +For installation issues: +- Create an issue in the repository +- Check Dolibarr logs: `/documents/dolibarr.log` +- Visit the [Dolibarr Forum](https://www.dolibarr.org/forum) + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliPhoneCom/module-id-policy.-.-.md b/MokoConsulting/MokoDoliPhoneCom/module-id-policy.-.-.md new file mode 100644 index 0000000..e8dde1a --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/module-id-policy.-.-.md @@ -0,0 +1,260 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed using this template. + +## Overview + +Every Dolibarr module requires a unique numeric identifier (module ID). This ID is critical for: +- Module identification within Dolibarr +- Preventing conflicts with other modules +- Tracking module permissions and configurations +- Database table prefixes and naming conventions + +## Module ID Ranges + +Dolibarr uses the following ID ranges: + +| Range | Purpose | Registration Required | +|-------|---------|----------------------| +| 0 - 94,999 | Core Dolibarr modules | Reserved by Dolibarr core team | +| 95,000 - 99,999 | Community modules (official repos) | Yes, via Dolibarr GitHub | +| 100,000 - 499,999 | Third-party public modules | Yes, via official registry | +| 500,000 - 599,999 | Private/unlisted modules | Recommended for permanent private use | +| 600,000+ | Development/temporary modules | **Use this range during development** | + +## Development Phase + +### Use Temporary ID (600,000+) + +While developing your module, always use an ID greater than 600,000: + +```php +// In modYourmodule.class.php +class modYourmodule extends DolibarrModules +{ + public function __construct($db) + { + $this->db = $db; + + // Temporary development ID + $this->numero = 600001; // or 600002, 600003, etc. + + // ... rest of configuration + } +} +``` + +### Why Use 600,000+? + +- **No registration required**: Immediate development without waiting for approval +- **No conflicts**: This range is intentionally unreserved for development +- **Easy to change**: Simple to update before distribution +- **Clear indicator**: Shows the module is in development phase + +### Choosing Your Temporary ID + +1. Pick any number greater than 600,000 +2. Use sequential numbers if developing multiple modules (600,001, 600,002, etc.) +3. Document your temporary ID in your development notes +4. Remember to replace it before distribution + +## Production Phase + +### Request Official Module ID + +Before distributing or publishing your module, you **must** request an official module ID. + +### How to Request + +1. **Create an Issue** in this repository + - Use the title: "Request Module ID Assignment: [Your Module Name]" + - Use the "Module ID Request" label if available + +2. **Provide Required Information**: + ```markdown + ## Module ID Request + + **Module Name**: Your Module Name + + **Description**: Brief description of what your module does + + **Organization/Developer**: Your organization or name + + **Distribution Plan**: + - [ ] Public (Dolibarr Marketplace) + - [ ] Public (GitHub/other platform) + - [ ] Private (internal use only) + - [ ] Commercial + + **Target Audience**: Who will use this module? + + **Additional Notes**: Any other relevant information + ``` + +3. **Wait for Approval** + - A maintainer will review your request + - You'll receive an assigned module ID + - The ID will be from the appropriate range based on your distribution plan + +### ID Assignment Criteria + +Module IDs are assigned based on: + +- **100,000 - 499,999**: Public modules intended for broad distribution + - Dolibarr Marketplace modules + - Open-source modules on GitHub + - Modules with public documentation + +- **500,000 - 599,999**: Private or limited distribution + - Internal company modules + - Client-specific customizations + - Modules not intended for public use + +### After Receiving Your ID + +1. **Update Module Descriptor**: + ```php + // Change from development ID + $this->numero = 600001; + + // To your assigned ID + $this->numero = 123456; // Your assigned ID + ``` + +2. **Update Documentation**: + - Update README.md with the official ID + - Note the ID in your changelog + - Document the assignment date + +3. **Test Thoroughly**: + - Reinstall module with new ID + - Verify no conflicts with existing installations + - Check all database operations + +4. **Commit Changes**: + ```bash + git add modYourmodule.class.php + git commit -m "Update to official module ID: 123456" + ``` + +## Module ID Registry + +### Official Dolibarr Registry + +For modules intended for the official Dolibarr ecosystem, you may also need to register on the official wiki: + +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) + +### moko-platform Registry + +This repository maintains its own registry of assigned IDs to prevent conflicts among moko-platform projects. + +## Special Cases + +### Multiple Modules + +If you're developing multiple related modules: +- Request a block of IDs (e.g., 123450-123459) +- Document which ID is used by which module +- Keep sequential IDs for related functionality + +### Module Forking + +If forking an existing module: +- You **must** request a new module ID +- Do not reuse the original module's ID +- Document the relationship to the original module + +### Module Renaming + +If renaming a module: +- Keep the same module ID +- Update the module name and descriptor +- Document the name change in changelog + +## Troubleshooting + +### ID Conflicts + +If you experience ID conflicts: +1. Check installed modules: `SELECT * FROM llx_const WHERE name LIKE 'MAIN_MODULE_%';` +2. Verify your ID doesn't conflict +3. If conflict exists, request a new ID +4. Update and redeploy + +### Lost or Forgotten ID + +If you've lost track of your assigned ID: +1. Check the issues in this repository +2. Search module registry documentation +3. Create a new issue asking for clarification + +## Best Practices + +1. ✅ **Always start with 600,000+** during development +2. ✅ **Request official ID early** if planning to distribute +3. ✅ **Document your ID** in all relevant files +4. ✅ **Test after ID changes** to ensure no issues +5. ✅ **Never use another module's ID** even in development +6. ❌ **Don't distribute modules** with temporary IDs (600,000+) +7. ❌ **Don't request multiple IDs** without justification +8. ❌ **Don't change IDs** after public distribution + +## Examples + +### Development Stage +```php +// Good - using temporary development ID +$this->numero = 600001; +``` + +### Production Stage (Private Module) +```php +// Good - assigned ID from private range +$this->numero = 550001; +``` + +### Production Stage (Public Module) +```php +// Good - assigned ID from public range +$this->numero = 125000; +``` + +### Bad Practice +```php +// BAD - using another module's ID +$this->numero = 1; // This is a core module ID! + +// BAD - random low number +$this->numero = 42; + +// BAD - distributing with development ID +$this->numero = 600001; // Only for development! +``` + +## References + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_development#Module_descriptor) + +## Contact + +For questions about module ID assignment: +- Create an issue in this repository +- Tag it with "module-id-question" +- Provide as much context as possible + +--- + +**Remember**: Using the correct module ID ensures your module integrates seamlessly with Dolibarr and avoids conflicts with other modules in the ecosystem. + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliPhoneCom/update-server.-.-.md b/MokoConsulting/MokoDoliPhoneCom/update-server.-.-.md new file mode 100644 index 0000000..d0b4629 --- /dev/null +++ b/MokoConsulting/MokoDoliPhoneCom/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliPhoneCom/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliPhoneCom](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliPhoneCom) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliProjTemplate/Home.md b/MokoConsulting/MokoDoliProjTemplate/Home.md new file mode 100644 index 0000000..8708f2a --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/Home.md @@ -0,0 +1,18 @@ +# MokoDoliProjTemplate + +Project templates for Dolibarr + +--- + +## Pages + +- [README](README ) +- [changelog](changelog ) +- [development](development ) +- [installation](installation ) +- [module id policy](module-id-policy ) +- [update server](update-server) + +--- + +**Category:** Dolibarr | **Platform:** [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki) diff --git a/MokoConsulting/MokoDoliProjTemplate/README.md b/MokoConsulting/MokoDoliProjTemplate/README.md new file mode 100644 index 0000000..7015e00 --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/README.md @@ -0,0 +1,77 @@ +← [Home](Home) + +# Documentation Index — MokoProjTemplate + +Welcome to the MokoProjTemplate module documentation. Use the links below to navigate all available resources. + +## Quick Links + +- [Installation Guide](installation.md) — Get the module running in your Dolibarr instance +- [Development Guide](development.md) — Module internals, class structure, and extension points +- [Changelog](changelog.md) — Version history and release notes + +## Documentation Structure + +### For New Users + +1. **[Installation Guide](installation.md)** + - Prerequisites and requirements + - Step-by-step installation + - Enabling the module and assigning permissions + - Troubleshooting + +### For Developers + +1. **[Development Guide](development.md)** + - Database schema + - Class overview (`ProjTemplate`, `ProjTemplateDet`) + - Adding new features + - Coding standards + +2. **[Contributing Guidelines](CONTRIBUTING)** + - How to contribute + - Code standards + - Pull request process + +### Reference + +- **[Changelog](changelog.md)** — Version history +- **[README](README)** — Project overview and quick start + +## Getting Help + +**Q: Where do I start?** +Start with the [Installation Guide](installation.md). + +**Q: How do I create a project template?** +After enabling the module, go to **Projects → Project Templates → New Project Template** in Dolibarr. + +**Q: How do I apply a template to a new project?** +Open a template card and use the **Apply Template** action to create a new project with all predefined tasks. + +**Q: How do I contribute?** +See the [Contributing Guidelines](CONTRIBUTING). + +## Support Resources + +- **GitHub Issues**: Report bugs or request features +- **Dolibarr Forum**: https://www.dolibarr.org/forum +- **Dolibarr Wiki**: https://wiki.dolibarr.org/ + +## External Resources + +- [Dolibarr Developer Documentation](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [MokoConsulting Tech](https://github.com/mokoconsulting-tech) + +## Version Information + +- **Module Version**: development +- **Minimum Dolibarr Version**: 17.0 +- **PHP Version**: 7.4+ + +--- + +**Next Steps**: +- New? Start with [Installation Guide](installation.md) +- Developing? Check out [Development Guide](development.md) diff --git a/MokoConsulting/MokoDoliProjTemplate/changelog.md b/MokoConsulting/MokoDoliProjTemplate/changelog.md new file mode 100644 index 0000000..e19ebf3 --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/changelog.md @@ -0,0 +1,74 @@ +← [Home](Home) + +# Changelog — MokoProjTemplate + +All notable changes to the **MokoProjTemplate** Dolibarr module are documented here. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- **Product/service attachment**: templates can now be linked to a Dolibarr product or service via a new `fk_product` column on `llx_mokoprojtemplate`. The product/service selector appears on the create and edit forms; the linked product is shown as a clickable link in view mode. +- **SQL schema files** (`src/sql/`): added all four base table-creation files (`llx_mokoprojtemplate.sql`, `.key.sql`, `llx_mokoprojtemplate_det.sql`, `.key.sql`) and a migration file (`llx_mokoprojtemplate_alter_add_fk_product.sql`) for existing installations. +- **Edit form**: the template card page now renders a proper edit form (`action=edit`) allowing all header fields (label, description, status, linked product) to be updated inline. +- **Import/export**: + - Import profile `mokoprojtemplate_0` (template headers) updated to include the new `fk_product` field. + - New import profile `mokoprojtemplate_1` for template task lines (`llx_mokoprojtemplate_det`). + - New export profile `mokoprojtemplate_0` for template headers (all columns). + - New export profile `mokoprojtemplate_1` for template lines joined with the parent template reference. +- **`src/DOLIBARR_MODULE_ID.txt`**: new file recording the officially reserved module ID 185064 as required by the moko-platform module registry. +- **Favicon / branding images** (`src/img/`): imported the Moko Consulting primary brand favicon images from [moko-platform `templates/images/primary/`](https://github.com/mokoconsulting-tech/moko-platform/tree/main/templates/images/primary): `object_favicon_256.png`, `object_favicon_120.png`, `object_favicon-96x96.png`, `object_favicon.ico`, `object_favicon.svg`, and `object_apple-touch-icon.png`. All image files use the `object_` prefix per Dolibarr convention. + +### Changed + +- Module display name updated from `Moko Dolibarr Project Templates` to `Moko Project Templates` for a cleaner, less redundant presentation in the Dolibarr UI +- Module version set to `development` to hold for active development; will be bumped to a release version when ready +- **Module family** changed from `"projects"` to `"mokoconsulting"` to comply with moko-platform requirements; `familyinfo` array added so the module is grouped under the Moko Consulting family in the Dolibarr module manager. +- **`editor_squarred_logo`** updated from `'favicon_256.png@mokocrm'` to `'object_favicon_256.png@mokoprojtemplate'` — now references the locally bundled copy of the Moko Consulting brand icon (with the required `object_` prefix) instead of depending on the separate `mokocrm` module. +- **`docs/module-id-policy.md`** rewritten to reflect the actual Moko Consulting module ID reservation process via moko-platform, replacing the generic scaffold content. + +## [1.0.0] - 2026-03-03 + +### Added + +- **Module descriptor** (`modMokoProjTemplate.class.php`) + - Module number 185064 (official Dolibarr community ID) + - Family: `projects`; requires core `modProjet` + - Permissions: `projtemplate` read / write / delete + - Left-menu entries under Projects: **Project Templates**, **New Project Template**, **List of Project Templates** +- **Database schema** + - `llx_mokoprojtemplate` — project templates table + - `llx_mokoprojtemplate_det` — template task lines table with FK cascade +- **`ProjTemplate` class** (`class/projtemplate.class.php`) + - `create()`, `fetch()`, `fetchLines()`, `update()`, `delete()`, `fetchAll()` + - `applyToProject()` — creates a new Dolibarr project with pre-populated tasks + - `getLibStatut()` / `LibStatut()` — status label helpers +- **`ProjTemplateDet` class** (`class/projtemplatedet.class.php`) + - `create()`, `update()`, `delete()` for individual task lines +- **Library** (`lib/mokoprojtemplate.lib.php`) + - `mokoProjTemplateAdminPrepareHead()` — admin tab headers + - `projtemplatePrepareHead()` — card page tab headers +- **Translation file** (`langs/en_US/mokoprojtemplate.lang`) + - Full English translations for all UI strings +- **Pages** + - `index.php` — module home with recent templates widget + - `projtemplate_list.php` — sortable, paginated list of templates + - `projtemplate_card.php` — create / view / edit a template with inline task line management +- **Admin pages** + - `admin/setup.php` — module settings page + - `admin/about.php` — about page showing module descriptor info +- **Documentation** + - `README.md` — project overview, features, installation quick-start + - `src/README.md` — module-specific readme for Dolibarr Dolistore style + - `docs/README.md` — documentation index + - `docs/installation.md` — full installation guide + - `docs/development.md` — developer reference (schema, classes, extension guide) + - `docs/changelog.md` — this file + +--- + +[Unreleased]: https://github.com/mokoconsulting-tech/MokoDoliProjTemplate/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/mokoconsulting-tech/MokoDoliProjTemplate/releases/tag/v1.0.0 diff --git a/MokoConsulting/MokoDoliProjTemplate/development.md b/MokoConsulting/MokoDoliProjTemplate/development.md new file mode 100644 index 0000000..106a307 --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/development.md @@ -0,0 +1,237 @@ +← [Home](Home) + +# Development Guide — MokoProjTemplate + +This guide describes the internal structure of the MokoProjTemplate module and how to extend or customise it. + +## Module Structure + +``` +mokoprojtemplate/ +├── core/modules/ +│ └── modMokoProjTemplate.class.php # Module descriptor +├── class/ +│ ├── projtemplate.class.php # ProjTemplate business class +│ └── projtemplatedet.class.php # ProjTemplateDet line class +├── sql/ +│ ├── llx_mokoprojtemplate.sql +│ ├── llx_mokoprojtemplate.key.sql +│ ├── llx_mokoprojtemplate_det.sql +│ └── llx_mokoprojtemplate_det.key.sql +├── lib/ +│ └── mokoprojtemplate.lib.php # Helper functions (head tabs, etc.) +├── langs/ +│ └── en_US/ +│ └── mokoprojtemplate.lang +├── admin/ +│ ├── setup.php # Admin setup page +│ └── about.php # Admin about page +├── index.php # Module home +├── projtemplate_list.php # List page +└── projtemplate_card.php # Card page (view/create/edit) +``` + +## Database Schema + +### `llx_mokoprojtemplate` — Project Templates + +| Column | Type | Description | +|--------|------|-------------| +| `rowid` | int (PK) | Auto-increment primary key | +| `ref` | varchar(30) | Unique template reference | +| `entity` | int | Dolibarr entity (multi-company) | +| `label` | varchar(255) | Template name | +| `description` | text | Long description | +| `status` | smallint | 0 = Draft, 1 = Active | +| `fk_product` | int (nullable) | Optional link to a product/service (`llx_product.rowid`) | +| `fk_user_author` | int | Creator user ID | +| `date_creation` | datetime | Creation timestamp | +| `tms` | timestamp | Last modification timestamp | + +### `llx_mokoprojtemplate_det` — Template Task Lines + +| Column | Type | Description | +|--------|------|-------------| +| `rowid` | int (PK) | Auto-increment primary key | +| `fk_template` | int (FK) | Parent template ID | +| `label` | varchar(255) | Task name | +| `description` | text | Task description | +| `duration_planned` | int | Planned duration in **hours** | +| `day_start_relative` | int | Start day offset from project start (0 = same day) | +| `rang` | int | Sort order | + +## Class Overview + +### `ProjTemplate` + +Located in `class/projtemplate.class.php`. + +**Key methods:** + +| Method | Description | +|--------|-------------| +| `create($user)` | Insert a new template into the database | +| `fetch($id, $ref)` | Load a template by ID or reference | +| `fetchLines()` | Load all task lines for this template into `$this->lines` | +| `update($user)` | Update label, description, status, and linked product/service | +| `delete($user)` | Delete the template (cascades to task lines) | +| `fetchAll($sortfield, $sortorder, $limit, $offset, $status)` | List all templates | +| `applyToProject($user, $projectRef, $projectTitle, $dateStart)` | Create a new project with tasks from this template | +| `getLibStatut($mode)` | Return status label / icon | + +**Status constants:** + +```php +ProjTemplate::STATUS_DRAFT = 0 +ProjTemplate::STATUS_ACTIVE = 1 +``` + +### `ProjTemplateDet` + +Located in `class/projtemplatedet.class.php`. + +**Key methods:** + +| Method | Description | +|--------|-------------| +| `create()` | Insert a task line | +| `update()` | Update a task line | +| `delete()` | Delete a task line | + +## Module Descriptor + +The module descriptor is `core/modules/modMokoProjTemplate.class.php`. + +```php +$this->numero = 185064; // Official module ID — DO NOT CHANGE +$this->rights_class = 'mokoprojtemplate'; +$this->family = 'mokoconsulting'; // All Moko Consulting modules use this family +$this->familyinfo = array( + 'mokoconsulting' => array( + 'position' => '01', + 'label' => $langs->trans("Moko Consulting"), + ), +); +$this->depends = array('modProjet'); // Requires core Projects module +$this->langfiles = array('mokoprojtemplate@mokoprojtemplate'); +$this->phpmin = array(7, 4); +$this->need_dolibarr_version = array(17, 0); +$this->editor_name = 'Moko Consulting'; +$this->editor_url = 'https://mokoconsulting.tech'; +$this->editor_squarred_logo = 'object_favicon_256.png@mokoprojtemplate'; +``` + +The module ID **185064** is officially reserved in the +[moko-platform module registry](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md). +The file `src/DOLIBARR_MODULE_ID.txt` records this reservation — **do not change the ID**. + +### Permissions + +The module defines three permissions under the `mokoprojtemplate` / `projtemplate` scope: + +| Code | Description | +|------|-------------| +| `projtemplate` / `read` | View templates and task lines | +| `projtemplate` / `write` | Create and update templates and task lines | +| `projtemplate` / `delete` | Delete templates | + +Check permissions in PHP: + +```php +if (!$user->hasRight('mokoprojtemplate', 'projtemplate', 'read')) { + accessforbidden(); +} +``` + +## Coding Standards + +Follow Dolibarr coding conventions: + +- **Indentation**: Tabs +- **Naming**: camelCase for functions, lowercase for files +- **Security**: Always sanitize inputs with `GETPOST()` filter parameters; escape output with `dol_escape_htmltag()` +- **DB queries**: Use `$this->db->escape()` for string values; cast integers with `(int)` + +Example: + +```php +$id = GETPOSTINT('id'); // sanitized integer +$label = GETPOST('label', 'alphanohtml'); // sanitized string + +$sql = "SELECT rowid FROM ".$this->db->prefix()."mokoprojtemplate"; +$sql .= " WHERE rowid = ".((int) $id); +$sql .= " AND label = '".$this->db->escape($label)."'"; +``` + +## Import / Export + +The module registers its data with Dolibarr's built-in Import/Export framework (available at **Tools → Import wizard** / **Tools → Export wizard**). + +### Import profiles + +| Profile | Label | Table | Required fields | +|---------|-------|-------|----------------| +| `mokoprojtemplate_0` | Project Templates | `llx_mokoprojtemplate` | `ref`, `label` | +| `mokoprojtemplate_1` | Project Template Lines | `llx_mokoprojtemplate_det` | `fk_template`, `label` | + +**Template headers** (`mokoprojtemplate_0`): accepts `ref`, `label`, `description`, `status` (0 or 1), `fk_product` (product rowid, optional), and `date_creation`. The `fk_user_author` field is auto-filled from the current user. The `ref` field is the update key (existing records with the same ref are updated). + +**Template lines** (`mokoprojtemplate_1`): accepts `fk_template` (parent template rowid), `label`, `description`, `duration_planned` (hours), `day_start_relative` (day offset), and `rang` (sort order). Records are matched for update by `fk_template` + `label`. + +### Export profiles + +| Profile | Label | Content | +|---------|-------|---------| +| `mokoprojtemplate_0` | Project Templates | All header columns including `fk_product` | +| `mokoprojtemplate_1` | Project Template Lines | Line columns joined with parent template `ref` | + +Exports require the `projtemplate` / `read` permission. + +## Adding a New Feature + +### Example: Add a "colour" field to templates + +1. **SQL migration** — create `src/sql/update_mokoprojtemplate_colour.sql`: + ```sql + ALTER TABLE llx_mokoprojtemplate ADD COLUMN colour varchar(7) DEFAULT NULL; + ``` + +2. **Update the class** — add a `public $colour = '';` property to `ProjTemplate` and include the column in `create()`, `fetch()`, and `update()`. + +3. **Update the card page** — add an input field in `projtemplate_card.php`. + +4. **Update the language file** — add `TemplateColour = Colour` to `langs/en_US/mokoprojtemplate.lang`. + +## Testing + +### Manual Testing Checklist + +- [ ] Activate and deactivate the module without errors +- [ ] Create a template with several task lines +- [ ] Edit and delete task lines +- [ ] Edit the template header (label, description, status) +- [ ] Delete the template and verify task lines are removed +- [ ] Apply the template to create a new project; verify tasks are created +- [ ] Verify permission enforcement (read-only user cannot create/delete) + +### Debugging + +Enable Dolibarr debug mode in `conf/conf.php`: + +```php +$dolibarr_main_prod = 0; +``` + +Check logs at `/documents/dolibarr.log`. + +## Module ID + +The module uses the officially assigned ID **185064** from the Dolibarr community registry. + +See the [Dolibarr Module ID Registry](https://wiki.dolibarr.org/index.php/List_of_modules_id) for context. + +## Resources + +- [Dolibarr Developer Docs](https://wiki.dolibarr.org/index.php/Developer_documentation) +- [Module Development Guide](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr API Reference](https://www.dolibarr.org/doc/html/) diff --git a/MokoConsulting/MokoDoliProjTemplate/installation.md b/MokoConsulting/MokoDoliProjTemplate/installation.md new file mode 100644 index 0000000..66f9793 --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/installation.md @@ -0,0 +1,136 @@ +← [Home](Home) + +# Installation Guide — MokoProjTemplate + +This guide provides step-by-step instructions for installing and configuring the **MokoProjTemplate** Dolibarr module. + +## Prerequisites + +Before installing the module, ensure you have: + +- **Dolibarr ERP/CRM**: Version **17.0 or higher** +- **PHP**: Version **7.4 or higher** +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **Database**: MySQL 5.7+, MariaDB 10.3+, or PostgreSQL 11+ +- **Dolibarr Projects module** must be enabled (this module depends on it) + +## Installation Steps + +### 1. Download / Clone + +Clone or download this repository: + +```bash +git clone https://github.com/mokoconsulting-tech/MokoDoliProjTemplate.git +``` + +### 2. Copy Module Files + +Copy the `src/` directory to your Dolibarr custom directory, renaming it `mokoprojtemplate`: + +```bash +cp -r src/ /path/to/dolibarr/htdocs/custom/mokoprojtemplate +``` + +Replace `/path/to/dolibarr` with your actual Dolibarr installation path. + +### 3. Set File Permissions + +```bash +# Set ownership (adjust user:group as needed for your web server) +chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/mokoprojtemplate + +# Set directory permissions +find /path/to/dolibarr/htdocs/custom/mokoprojtemplate -type d -exec chmod 755 {} \; + +# Set file permissions +find /path/to/dolibarr/htdocs/custom/mokoprojtemplate -type f -exec chmod 644 {} \; +``` + +### 4. Enable the Module in Dolibarr + +1. Log in to your Dolibarr instance as a **super-administrator** +2. Navigate to **Home → Setup → Modules/Applications** +3. Find **Project Templates** (or search for `MokoProjTemplate`) +4. Click **Activate** + +Dolibarr will automatically run the SQL scripts to create the required database tables: +- `llx_mokoprojtemplate` — stores project templates +- `llx_mokoprojtemplate_det` — stores task lines for each template + +### 5. Assign Permissions + +1. Navigate to **Home → Setup → Users & Groups** +2. Edit the relevant user or group +3. Under the **MokoProjTemplate** section, enable: + - **Read project templates** — view templates and task lists + - **Create or update project templates** — add/edit templates and task lines + - **Delete project templates** — remove templates + +### 6. Access the Module + +After activation, a **Project Templates** menu entry will appear under the **Projects** main menu in Dolibarr's left navigation. + +## Database Setup + +The module creates its tables automatically on activation using the SQL files in `src/sql/`: + +| File | Purpose | +|------|---------| +| `llx_mokoprojtemplate.sql` | Templates table schema | +| `llx_mokoprojtemplate.key.sql` | Indexes and unique constraints | +| `llx_mokoprojtemplate_det.sql` | Template task lines schema | +| `llx_mokoprojtemplate_det.key.sql` | FK constraints and indexes | + +If you need to run the scripts manually: + +```bash +mysql -u username -p database_name < src/sql/llx_mokoprojtemplate.sql +mysql -u username -p database_name < src/sql/llx_mokoprojtemplate.key.sql +mysql -u username -p database_name < src/sql/llx_mokoprojtemplate_det.sql +mysql -u username -p database_name < src/sql/llx_mokoprojtemplate_det.key.sql +``` + +## Troubleshooting + +### Module Not Appearing + +- Clear Dolibarr cache: delete `/documents/install.lock` and refresh the page +- Check file permissions (see Step 3) +- Verify PHP syntax: `php -l /path/to/dolibarr/htdocs/custom/mokoprojtemplate/core/modules/modMokoProjTemplate.class.php` + +### Permission Errors + +- Ensure the web server user has read access to all module files +- Check `conf.php` permissions in the Dolibarr root + +### Database Errors + +- Verify database credentials in Dolibarr's `conf/conf.php` +- Ensure the database user has `CREATE TABLE` and `ALTER TABLE` permissions +- Check Dolibarr logs: `/documents/dolibarr.log` + +### Menu Entry Not Showing + +- Confirm the **Projects** core module is enabled +- Verify the user has at least `read` permission for `mokoprojtemplate` + +## Uninstallation + +1. Navigate to **Home → Setup → Modules/Applications** +2. Find **Project Templates** and click **Deactivate** +3. Optionally remove the module directory: + ```bash + rm -rf /path/to/dolibarr/htdocs/custom/mokoprojtemplate + ``` + +> **Note:** Deactivating the module does **not** remove the database tables or existing template data. To remove all data: +> ```sql +> DROP TABLE llx_mokoprojtemplate_det; +> DROP TABLE llx_mokoprojtemplate; +> ``` + +## Next Steps + +- Read the [Development Guide](development.md) to extend or customise the module +- Check the [Changelog](changelog.md) for version history diff --git a/MokoConsulting/MokoDoliProjTemplate/module-id-policy.-.-.md b/MokoConsulting/MokoDoliProjTemplate/module-id-policy.-.-.md new file mode 100644 index 0000000..30aa4c4 --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/module-id-policy.-.-.md @@ -0,0 +1,77 @@ +← [Home](Home) + +# Module ID Policy + +This document explains the module ID assignment policy for Dolibarr modules developed by +Moko Consulting. + +## Assigned Module ID + +**MokoDoliProjTemplate is assigned module ID 185064.** + +This ID is recorded in `src/DOLIBARR_MODULE_ID.txt` and in the official +[moko-platform module registry](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md). + +> **Do not change the module ID.** Changing it on an installed system will break permissions, +> menu entries, and configuration constants stored in the database. + +## Moko Consulting Reserved Range + +All Moko Consulting Dolibarr modules use IDs from the reserved range **185051–185099**, +which is officially registered with the Dolibarr community. + +| Module Name | Module ID | Status | +|-------------|-----------|--------| +| MokoDoliProjTemplate | **185064** | Active | + +For the full registry see: +[docs/development/crm/module-registry.md](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md) +in the moko-platform repository. + +## Reserving a New Module ID + +All module ID reservations **must** go through the +[Reserve Dolibarr Module ID](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/workflows/reserve-dolibarr-module-id.md) +Gitea Actions workflow in moko-platform. Direct edits to the registry are not permitted. + +## Module ID File + +Every Moko Consulting Dolibarr module must include a `src/DOLIBARR_MODULE_ID.txt` file in +the format shown below: + +``` +DOLIBARR_MODULE_ID=185064 + +Module Name: MokoDoliProjTemplate +Module ID: 185064 +Reserved Range: 185051-185099 (Moko Consulting) +Description: A Dolibarr module designed to provide project templates + +This ID is registered in the moko-platform module registry: +https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md + +DO NOT CHANGE THIS ID! +``` + +## Module Family + +Per moko-platform requirements, all Moko Consulting Dolibarr modules must set: + +```php +$this->family = "mokoconsulting"; +$this->familyinfo = array( + 'mokoconsulting' => array( + 'position' => '01', + 'label' => $langs->trans("Moko Consulting"), + ), +); +``` + +This groups all Moko modules together in the Dolibarr module manager. + +## References + +- [moko-platform Module Registry](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/development/crm/module-registry.md) +- [moko-platform CRM Development Standards](https://github.com/mokoconsulting-tech/moko-platform/blob/main/docs/policy/crm/development-standards.md) +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module ID List](https://wiki.dolibarr.org/index.php/List_of_modules_id) diff --git a/MokoConsulting/MokoDoliProjTemplate/update-server.-.-.md b/MokoConsulting/MokoDoliProjTemplate/update-server.-.-.md new file mode 100644 index 0000000..82c4762 --- /dev/null +++ b/MokoConsulting/MokoDoliProjTemplate/update-server.-.-.md @@ -0,0 +1,56 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliProjTemplate/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* diff --git a/MokoConsulting/MokoDoliRelease/Home.md b/MokoConsulting/MokoDoliRelease/Home.md new file mode 100644 index 0000000..3661220 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/Home.md @@ -0,0 +1,52 @@ +# MokoDoliRelease + +A Dolibarr module for monitoring and managing remote deployments, software releases, and license keys for Dolibarr and Joomla installations. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [configuration](configuration) | ← [Home](Home) | +| [installation](installation) | ← [Home](Home) | +| [quick start](quick-start.-.-) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [README](README) | ← [Home](Home) | +| [api reference](api-reference.-.-) | ← [Home](Home) | +| [architecture](architecture) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [ROADMAP](ROADMAP) | ← [Home](Home) | +| [XML_UPDATE_STREAMS](XML_UPDATE_STREAMS) | ← [Home](Home) | +| [enterprise deployment](enterprise-deployment.-.-) | ← [Home](Home) | +| [faq](faq) | ← [Home](Home) | +| [governance](governance) | ← [Home](Home) | +| [runbook](runbook) | ← [Home](Home) | +| [sla management](sla-management.-.-) | ← [Home](Home) | +| [troubleshooting](troubleshooting) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliRelease/README.md b/MokoConsulting/MokoDoliRelease/README.md new file mode 100644 index 0000000..5ea9407 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/README.md @@ -0,0 +1,74 @@ +← [Home](Home) + +# MokoDoliRelease Documentation + +Comprehensive documentation for the MokoDoliRelease module - a Dolibarr module for managing releases, update streams, and license keys. + +## Documentation Structure + +### Getting Started +- [Installation Guide](installation.md) - Step-by-step installation instructions +- [Quick Start Guide](quick-start.md) - Get up and running quickly +- [Configuration](configuration.md) - Module configuration and settings + +### User Guides +- [User Manual](user-manual.md) - Complete user guide(Coming soon)* +- [Deployment Types](deployment-types.md) - Understanding different deployment types(Coming soon)* +- [Health Monitoring](health-monitoring.md) - Health check system and metrics(Coming soon)* +- [Remote Components](remote-components.md) - Using push-based monitoring(Coming soon)* + +### Technical Documentation +- [Architecture](architecture.md) - System architecture and design +- [API Reference](api-reference.md) - API endpoints and usage +- [XML Update Streams](XML_UPDATE_STREAMS.md) - Multi-platform update streams guide +- [Sample Code & API Usage](SAMPLE_CODE.md) - Complete examples for all features +- [GitHub Copilot Prompts](copilot-prompts.md) - Prompts for implementing update streams and license validation +- [Database Schema](database-schema.md) - Database structure and tables(Coming soon)* +- [Development Guide](development.md) - Extending and customizing the module(Coming soon)* + +### Advanced Topics +- [Security](security.md) - Security features and best practices(Coming soon)* +- [Performance](performance.md) - Performance optimization(Coming soon)* +- [Troubleshooting](troubleshooting.md) - Common issues and solutions +- [FAQ](faq.md) - Frequently asked questions + +### Enterprise Documentation +- [Enterprise Deployment](enterprise-deployment.md) - Enterprise-scale deployment strategies +- [Governance & Compliance](governance.md) - Governance framework and compliance requirements +- [SLA Management](sla-management.md) - Service level agreements and monitoring +- [Operations Runbook](runbook.md) - Day-to-day operational procedures + +## Quick Links + +- **Main Repository**: [MokoDoliRelease](https://github.com/mokoconsulting-tech/MokoDoliRelease) +- **Coding Standards**: [moko-platform](https://github.com/mokoconsulting-tech/moko-platform) +- **Module ID**: 185058 +- **Support**: hello@mokoconsulting.tech + +## Module Overview + +MokoDoliRelease is a Dolibarr module for monitoring and managing remote deployments, software releases, and license keys for multiple platforms. Features Akeeba-style XML update streams for automatic extension updates across Joomla, Dolibarr, WordPress, and Drupal. + +## Key Features + +- **Multi-Platform Update Streams** - Joomla, Dolibarr, WordPress, Drupal support +- **Release Management** - Multi-platform support with remote and local hosting +- **License Key Management** - Contract-based licensing with multi-activation support +- **Deployment Monitoring** - Health dashboard for all deployments +- **Secure Downloads** - Files served through authenticated API +- **Multiple Release Channels** - Stable, beta, alpha, LTS, and RC streams +- **Auto-Discovery** - FTP upload scanning with draft status + +--- + +**Version**: 01.00.00 +**Last Updated**: 2025-01-08 +**License**: GPL-3.0-or-later + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/ROADMAP.md b/MokoConsulting/MokoDoliRelease/ROADMAP.md new file mode 100644 index 0000000..2312952 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/ROADMAP.md @@ -0,0 +1,107 @@ +← [Home](Home) + +# MokoDoliRelease Roadmap + +This document outlines the planned features and improvements for MokoDoliRelease. + +## Version Goals + +### development (Current) +**Status:** Active Development +**Focus:** Core features and stability + +- ✅ Health monitoring for Dolibarr and Joomla deployments +- ✅ License key management +- ✅ Release management with XML update streams +- ✅ API endpoints for remote reporting +- ✅ Deployment tracking with health status +- 🔄 License/deployment management UI (license/list.php, license/card.php) +- 🔄 Language translation cleanup (en_US, en_GB) +- 📋 Code quality improvements +- 📋 Documentation enhancements + +### 1.1.0 (Planned - Q2 2026) +**Focus:** Enhanced monitoring and reporting + +- Advanced dashboard analytics +- Custom health check configurations +- Email notifications for health status changes +- Bulk deployment operations +- Enhanced security scanning +- Deployment groups/categories +- Advanced filtering and search + +### 1.2.0 (Planned - Q3 2026) +**Focus:** Automation and integration + +- Automated deployment updates +- Webhook integrations +- Third-party monitoring tool integrations +- Custom API extensions +- Advanced license activation workflows +- Release approval workflows + +### 2.0.0 (Planned - Q4 2026) +**Focus:** Enterprise features + +- Multi-tenancy support +- Advanced role-based access control (RBAC) +- Deployment templates +- Disaster recovery features +- Advanced reporting and analytics dashboard +- SLA monitoring and alerting +- Integration with ticketing systems +- Mobile-responsive UI improvements + +### Future Considerations + +- Docker/Kubernetes deployment monitoring +- WordPress deployment support +- Cloud platform integrations (AWS, Azure, GCP) +- Machine learning-based anomaly detection +- Compliance reporting (GDPR, SOC 2, etc.) +- API rate limiting and throttling +- GraphQL API support + +## Feature Requests + +Feature requests can be submitted via: +- GitHub Issues: https://github.com/mokoconsulting-tech/MokoDoliRelease/issues +- Email: hello@mokoconsulting.tech + +## Contributing + +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING) for guidelines on how to contribute to the project. + +## Release Cycle + +- **Major releases** (x.0.0): Annually, with significant new features +- **Minor releases** (x.x.0): Quarterly, with new features and enhancements +- **Patch releases** (x.x.x): As needed, for bug fixes and security updates + +## Versioning + +This project follows [Semantic Versioning](https://semver.org/): +- **MAJOR** version for incompatible API changes +- **MINOR** version for backwards-compatible functionality additions +- **PATCH** version for backwards-compatible bug fixes +- **development** version for active development work + +## Support + +- **development**: Active development, breaking changes may occur +- **1.x**: Full support with security and bug fixes +- **0.x**: Legacy, security fixes only + +--- + +*Last updated: 2026-01-17* +*This roadmap is subject to change based on user feedback and project priorities.* + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/XML_UPDATE_STREAMS.md b/MokoConsulting/MokoDoliRelease/XML_UPDATE_STREAMS.md new file mode 100644 index 0000000..14f5942 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/XML_UPDATE_STREAMS.md @@ -0,0 +1,589 @@ +← [Home](Home) + +# Multi-Platform Update Streams + +This document explains how to use the update stream system for managing extension updates across multiple platforms: Joomla, Dolibarr, WordPress, and Drupal. + +## Overview + +The MokoDoliRelease system provides **fully compliant** update streams compatible with: +- **Joomla's native update mechanism** - One-click updates from Joomla backend (all extension types) +- **WordPress plugin/theme updates** - Native WordPress update API integration +- **Drupal module/theme updates** - Drupal's update XML format +- **Dolibarr module updates** - Automatic module update detection +- **Multiple formats** - XML, JSON, and HTML output + +## Key Features + +✅ **Multi-Platform** - WordPress, Drupal, Joomla, Dolibarr support +✅ **Multi-Format** - XML (platform-specific), JSON (universal), HTML (human-readable) +✅ **Remote Hosting** - GitHub releases, CDN, external URLs +✅ **Secure Downloads** - Files served through authenticated API +✅ **Type-Compatible** - Supports all extension types per platform +✅ **Checksums** - MD5 and SHA256 hashes for integrity verification +✅ **Multiple Release Channels** - Stable, beta, alpha, LTS, and RC streams +✅ **Auto-Discovery** - FTP upload scanning with draft status + +## Folder Structure + +Releases are organized in a hierarchical structure: + +``` +documents/mokodolirelease/ +└── releases/ + ├── wordpress/ + │ ├── stable/ + │ │ ├── myplugin-1.0.0.zip + │ │ └── myplugin-1.1.0.zip + │ ├── beta/ + │ └── draft/ # FTP auto-discovered + ├── drupal/ + │ ├── stable/ + │ │ └── mymodule-8.x-1.0.zip + │ └── beta/ + ├── dolibarr/ + │ ├── stable/ + │ │ ├── dolibarr-19.0.1.zip + │ │ └── dolibarr-19.0.2.zip + │ ├── beta/ + │ │ └── dolibarr-20.0.0-beta.zip + │ ├── alpha/ + │ ├── rc/ + │ └── lts/ + │ └── dolibarr-18.0.5-lts.zip + └── joomla/ + ├── stable/ + │ ├── joomla-5.1.0.zip + │ └── joomla-5.1.1.zip + ├── beta/ + ├── alpha/ + └── lts/ +``` + +## API Endpoints + +### 1. Multi-Format Update Streams + +Get update streams in multiple formats: + +```bash +# WordPress - XML (native format) +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=wordpress&type=stable&format=xml + +# Drupal - XML (native format) +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=drupal&type=beta&format=xml + +# Joomla - XML (native format) +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable&format=xml + +# Dolibarr - XML (native format) +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=dolibarr&type=stable&format=xml + +# Any platform - JSON (universal format) +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=wordpress&type=stable&format=json + +# Any platform - HTML (human-readable) +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable&format=html + +# Dolibarr LTS releases +GET https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=dolibarr&type=lts +``` + +### 2. Download Release + +Secure download with optional authentication: + +```bash +# Public download (no authentication) +GET https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=123 + +# Download by product and version +GET https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?product=joomla&version=5.1.0 + +# Authenticated download with license key +GET https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=123&key=YOUR-LICENSE-KEY + +# Force authentication required +GET https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=123&auth=1&key=YOUR-LICENSE-KEY +``` + +### 3. Upload Release (Local File) + +Upload a new release with automatic update stream generation: + +```bash +# Upload local file +curl -X POST \ + -H "DOLAPIKEY: your_api_key" \ + -F "release_file=@wordpress-myplugin-1.0.0.zip" \ + -F "is_latest=1" \ + -F "changelog=Bug fixes and improvements" \ + -F "security_fixes=Fixed XSS vulnerability" \ + https://your-dolibarr.com/custom/mokodolirelease/api/upload_release.php +``` + +### 3b. Create Release (Remote URL) + +Create release pointing to external hosting (GitHub, CDN): + +```bash +# Point to GitHub release +curl -X POST \ + -H "DOLAPIKEY: your_api_key" \ + -F "remote_url=https://github.com/user/repo/releases/download/v1.0.0/plugin.zip" \ + -F "product_type=wordpress" \ + -F "version_number=1.0.0" \ + -F "is_latest=1" \ + -F "changelog=See GitHub release notes" \ + https://your-dolibarr.com/custom/mokodolirelease/api/upload_release.php +``` + +Response includes update stream URL: +```json +{ + "success": true, + "message": "Release uploaded successfully", + "data": { + "release_id": 42, + "ref": "REL-000042", + "product_type": "wordpress", + "version_number": "1.0.0", + "release_type": "stable", + "filename": "myplugin-1.0.0.zip", + "download_url": "/mokodolirelease/releases/wordpress/stable/myplugin-1.0.0.zip", + "remote_url": "https://github.com/user/repo/releases/download/v1.0.0/plugin.zip", + "is_remote": 1, + "is_latest": 1, + "update_stream_url": "https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=wordpress&type=stable" + } +} +``` + +### 4. FTP Auto-Discovery + +Scan FTP-uploaded files and create draft releases: + +```bash +# List files without creating releases +GET https://your-dolibarr.com/custom/mokodolirelease/api/scan_ftp_releases.php?product=wordpress&type=stable + +# Auto-create draft releases from FTP uploads +POST https://your-dolibarr.com/custom/mokodolirelease/api/scan_ftp_releases.php?product=drupal&type=beta&auto_create=1 +``` + +Response: +```json +{ + "success": true, + "product_type": "wordpress", + "release_type": "stable", + "scan_directory": "/path/to/documents/mokodolirelease/releases/wordpress/stable", + "found_files": 2, + "files": [ + { + "filename": "myplugin-1.2.0.zip", + "filepath": "/full/path/myplugin-1.2.0.zip", + "version": "1.2.0", + "detected_type": "stable", + "is_lts": 0, + "filesize": 2048576, + "modified": "2025-01-22 10:30:00" + } + ], + "created_releases": [ + { + "filename": "myplugin-1.2.0.zip", + "version": "1.2.0", + "release_id": 45, + "ref": "WORDPRESS-1.2.0" + } + ], + "created_count": 1, + "skipped_files": [], + "errors": [] +} +``` + +### 5. Traditional Folder Scan + +Scan filesystem for release files: + +```bash +# Scan all joomla releases +GET https://your-dolibarr.com/custom/mokodolirelease/api/scan_releases.php?product=joomla + +# Scan specific type +GET https://your-dolibarr.com/custom/mokodolirelease/api/scan_releases.php?product=dolibarr&type=stable +``` + +Response: +```json +{ + "success": true, + "message": "Found 3 release file(s)", + "data": { + "product_type": "joomla", + "release_type": "stable", + "files": [ + { + "filename": "joomla-5.1.1.zip", + "path": "/path/to/dokuments/mokodolirelease/releases/joomla/stable/joomla-5.1.1.zip", + "relative_path": "joomla/stable/joomla-5.1.1.zip", + "version": "5.1.1", + "size": 12534567, + "modified": 1704835200, + "in_database": true, + "formatted_size": "11.96 MB", + "formatted_date": "2025-01-09 14:00" + } + ], + "total_files": 3, + "new_files": 1, + "existing_files": 2 + } +} +``` + +## Joomla Integration + +### Step 1: Configure Your Extension Manifest + +Add update server to your Joomla extension's XML manifest: + +```xml + + COM_YOUREXTENSION + 5.1.0 + + + + https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable + + + +``` + +### Step 2: Joomla XML Update Stream Format + +The system generates*fully compliant** Joomla XML with all required fields: + +```xml + + + + Joomla 5.1.0 + Update to 5.1.0 + com_joomla + component + 5.1.0 + + + https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?product=joomla&version=5.1.0 + + + site + + Moko Consulting + https://www.mokoconsulting.com + https://your-dolibarr.com/custom/mokodolirelease/releases_list.php + + + + stable + + + +``` + +**Key Features:** +- ✅ Secure download URL (via API, not direct file access) +- ✅ All required Joomla fields included +- ✅ Checksums (MD5/SHA256) automatically added when available +- ✅ Proper CDATA sections for changelog and security notes +- ✅ Tags for release classification + +### Step 2b: Configuring Extension Type + +By default, the system assumes `component` type. To specify a different extension type (module, plugin, template, etc.), add metadata to the release*notes** field: + +``` +type: module +element: mod_mymodule +``` + +Or for a plugin: +``` +type: plugin +element: plg_system_myplugin +``` + +**Supported Joomla Extension Types:** +- `component` (e.g., com_example) +- `module` (e.g., mod_example) +- `plugin` (e.g., plg_group_example) +- `template` +- `library` (e.g., lib_example) +- `package` +- `file` + +The system will parse the notes field and use the specified values in the XML output. + +### Step 3: Test Updates in Joomla + +1. Go to*System → Update → Extensions** +2. Click*Find Updates** +3. Your extension should appear if a newer version is available +4. Click*Update** to install automatically + +## Dolibarr Integration + +### Dolibarr XML Update Stream Format + +The system generates*type-compatible** Dolibarr module update XML: + +```xml + + + + Dolibarr 19.0.1 + Update to version 19.0.1 + dolibarr + module + 19.0.1 + 2025-01-09 + https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?product=dolibarr&version=19.0.1 + https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?product=dolibarr&version=19.0.1 + 15728640 + a1b2c3d4e5f6g7h8i9j0 + 1234567890abcdef... + + + stable + + +``` + +**Key Features:** +- ✅ Secure download URL (via API) +- ✅ Multiple hash algorithms (MD5 and SHA256) +- ✅ File size information +- ✅ Type and element fields for module identification +- ✅ Status field (stable, beta, alpha) + +### Configuring Dolibarr Module Type + +By default, the system assumes `module` type. To specify different metadata, add to the release*notes** field: + +``` +module: mymodulename +moduletype: external +``` + +**Supported Dolibarr Module Types:** +- `module` - Standard Dolibarr module (default) +- `external` - External module +- `core` - Core Dolibarr component + +The `element` field will be set to the module name, which is used for module identification. + +## Release Types + +The system automatically classifies releases into types based on filename: + +- **stable** - Standard releases (e.g., `joomla-5.1.0.zip`) +- **beta** - Beta releases (e.g., `joomla-5.2.0-beta.zip`) +- **alpha** - Alpha releases (e.g., `joomla-5.3.0-alpha.zip`) +- **rc** - Release candidates (e.g., `joomla-5.1.0-rc1.zip`) +- **lts** - Long-term support (marked with `is_lts=1` flag) + +## Security Features + +### Files Outside Public Filesystem + +Release files are stored in the Dolibarr documents directory (outside web root) and served through PHP: + +- **Storage**: `/var/www/dolibarr/documents/mokodolirelease/releases/` +- **Access**: Only through `download_release.php` API +- **Benefits**: + - Cannot be accessed directly via URL + - Enables access control and authentication + - Track downloads and usage + +### Optional License Authentication + +Downloads can require license key validation: + +```bash +# Download requires valid license key +curl "https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=123&auth=1&key=VALID-LICENSE-KEY" +``` + +The system checks: +1. License key validity +2. License expiry date +3. Service contract status +4. Maximum activations limit + +### Public Downloads + +For open-source releases, authentication can be disabled: + +```bash +# No authentication required +curl "https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=123" +``` + +## Workflow Examples + +### Example 1: Release a New Joomla Version + +```bash +# 1. Upload the release +curl -X POST \ + -H "DOLAPIKEY: your_api_key" \ + -F "release_file=@joomla-5.1.0.zip" \ + -F "is_latest=1" \ + -F "changelog=Major new features" \ + https://your-dolibarr.com/custom/mokodolirelease/api/upload_release.php + +# 2. XML stream is automatically generated +# Users with Joomla extensions pointing to the update stream will see the update + +# 3. Users click "Update" in Joomla backend +# Joomla downloads from: /api/download_release.php?product=joomla&version=5.1.0 +``` + +### Example 2: Private Release with License + +```bash +# 1. Upload private release +curl -X POST \ + -H "DOLAPIKEY: your_api_key" \ + -F "release_file=@yourextension-pro-2.0.0.zip" \ + -F "is_latest=1" \ + https://your-dolibarr.com/custom/mokodolirelease/api/upload_release.php + +# 2. Create license key for customer +# (via Dolibarr UI or API) + +# 3. Customer downloads with license +curl "https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=456&key=CUSTOMER-LICENSE-KEY" \ + -o yourextension-pro-2.0.0.zip +``` + +### Example 3: Scan and Import Existing Releases + +```bash +# 1. Copy existing release files to folder structure +mkdir -p /var/www/dolibarr/documents/mokodolirelease/releases/joomla/stable/ +cp joomla-*.zip /var/www/dolibarr/documents/mokodolirelease/releases/joomla/stable/ + +# 2. Scan the folder +curl "https://your-dolibarr.com/custom/mokodolirelease/api/scan_releases.php?product=joomla&type=stable" + +# 3. Review found files and import to database via UI +# (future feature: auto-import API) +``` + +## Best Practices + +1.*Use version tags consistently** - Stick to semantic versioning (e.g., 1.2.3) +2.*Separate release types** - Use different streams for stable, beta, and alpha +3.*Include changelogs** - Always provide changelog and security fix information +4.*Test update streams** - Verify XML is valid before releasing +5.*Monitor downloads** - Track which versions are being downloaded +6.*License management** - Use license keys for commercial/private releases +7.*Regular updates** - Keep update streams fresh with security patches + +## Troubleshooting + +### Update Stream Not Showing in Joomla + +1. Check XML is valid: `curl https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable` +2. Verify extension manifest has correct `` URL +3. Clear Joomla cache: System → Cache → Clear All +4. Check Joomla error logs + +### Download Fails + +1. Check file exists on server +2. Verify file permissions (should be readable) +3. Check license key if authentication required +4. Review Dolibarr error logs + +### Version Not Detected + +1. Filename must match pattern: `product-version.zip` +2. Version format: `1.2.3` or `1.2.3-beta` +3. Product name must be exact: `joomla` or `dolibarr` + +## Advanced Configuration + +### Custom Update Servers + +You can create custom update streams for specific customers: + +```php +// Custom stream for specific client +$stream = new ReleaseStream($db); +$custom_releases = $stream->getReleasesForCustomer($customer_id); +$xml = $stream->generateCustomStream($custom_releases); +``` + +### Multiple Products + +Manage different products with separate streams: + +``` +releases/ +├── com_yourcomponent/ +│ └── stable/ +├── plg_yourplugin/ +│ └── stable/ +└── mod_yourmodule/ + └── stable/ +``` + +## API Reference + +All API endpoints return JSON (except `update_stream.php` which returns XML). + +### Response Format + +Success: +```json +{ + "success": true, + "message": "Operation completed", + "data": { ... } +} +``` + +Error: +```json +{ + "success": false, + "message": "Error description", + "data": {} +} +``` + +### HTTP Status Codes + +- `200` - Success +- `201` - Created (upload) +- `400` - Bad request (invalid parameters) +- `401` - Unauthorized (missing auth) +- `403` - Forbidden (invalid license) +- `404` - Not found +- `405` - Method not allowed +- `409` - Conflict (duplicate) +- `500` - Server error + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/api-reference.-.-.md b/MokoConsulting/MokoDoliRelease/api-reference.-.-.md new file mode 100644 index 0000000..98b3a8c --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/api-reference.-.-.md @@ -0,0 +1,282 @@ +← [Home](Home) + +# API Reference + +Complete API documentation for MokoDoliDeploy module. + +## Report Status API + +### Endpoint + +``` +POST /custom/mokodolideploy/api/report_status.php +``` + +### Description + +Allows remote systems to push their health status to MokoDoliDeploy. + +### Authentication + +**Method**: API Key in header + +```http +DOLAPIKEY: your-api-key-here +``` + +### Request + +**Content-Type**: `application/json` + +**Parameters**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| ref | string | Yes | Deployment reference code | +| status | string | Yes | Health status (healthy, warning, critical) | +| version | string | No | Application version | +| database_status | string | No | Database status | +| database_size | string | No | Database size | +| server_load | string | No | Server load average | +| disk_free | string | No | Free disk space | +| ssl_valid | boolean | No | SSL certificate valid | +| updates_available | boolean | No | Updates available | +| security_issues | integer | No | Number of security issues | + +**Example Request**: + +```json +{ + "ref": "DEPLOY-000001", + "status": "healthy", + "version": "1.2.3", + "database_status": "connected", + "database_size": "2.5GB", + "server_load": "0.45", + "disk_free": "45.2GB", + "ssl_valid": true, + "updates_available": false, + "security_issues": 0 +} +``` + +### Response + +**Success (200 OK)**: + +```json +{ + "success": true, + "message": "Health status updated successfully", + "deployment_id": 123, + "timestamp": "2025-01-08T12:34:56Z" +} +``` + +**Error (400 Bad Request)**: + +```json +{ + "success": false, + "error": "Invalid deployment reference", + "code": "INVALID_REF" +} +``` + +**Error (401 Unauthorized)**: + +```json +{ + "success": false, + "error": "Invalid API key", + "code": "UNAUTHORIZED" +} +``` + +### Error Codes + +| Code | HTTP Status | Description | +|------|-------------|-------------| +| INVALID_REF | 400 | Deployment reference not found | +| MISSING_PARAM | 400 | Required parameter missing | +| UNAUTHORIZED | 401 | Invalid or missing API key | +| FORBIDDEN | 403 | API access not enabled | +| SERVER_ERROR | 500 | Internal server error | + +### Example Usage + +**cURL**: + +```bash +curl -X POST \ + https://your-dolibarr.com/custom/mokodolideploy/api/report_status.php \ + -H 'DOLAPIKEY: your-api-key-here' \ + -H 'Content-Type: application/json' \ + -d '{ + "ref": "DEPLOY-000001", + "status": "healthy", + "version": "1.2.3", + "database_status": "connected" + }' +``` + +**PHP**: + +```php + 'DEPLOY-000001', + 'status' => 'healthy', + 'version' => '1.2.3', + 'database_status' => 'connected' +); + +$ch = curl_init('https://your-dolibarr.com/custom/mokodolideploy/api/report_status.php'); +curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); +curl_setopt($ch, CURLOPT_POST, true); +curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); +curl_setopt($ch, CURLOPT_HTTPHEADER, array( + 'Content-Type: application/json', + 'DOLAPIKEY: your-api-key-here' +)); + +$response = curl_exec($ch); +curl_close($ch); + +$result = json_decode($response, true); +print_r($result); +``` + +**Python**: + +```python +import requests +import json + +url = 'https://your-dolibarr.com/custom/mokodolideploy/api/report_status.php' +headers = { + 'Content-Type': 'application/json', + 'DOLAPIKEY': 'your-api-key-here' +} +data = { + 'ref': 'DEPLOY-000001', + 'status': 'healthy', + 'version': '1.2.3', + 'database_status': 'connected' +} + +response = requests.post(url, headers=headers, json=data) +result = response.json() +print(result) +``` + +## Health Check Metrics + +### Standard Metrics + +All deployment types return these standard metrics: + +```json +{ + "version": "string", + "database_status": "connected|disconnected|error", + "database_size": "string (e.g., '2.5GB')", + "server_load": "string (e.g., '0.45')", + "disk_free": "string (e.g., '45.2GB')", + "ssl_valid": boolean, + "ssl_expires": "date (ISO 8601)", + "updates_available": boolean, + "security_issues": integer, + "last_check": "datetime (ISO 8601)" +} +``` + +### Live Chat Helper Metrics + +Additional metrics for Live Chat Helper deployments: + +```json +{ + "chat_sessions_active": integer, + "chat_sessions_queued": integer, + "agents_online": integer, + "average_response_time": integer (seconds) +} +``` + +### Joomla Specific Metrics + +Additional metrics for Joomla/Panopticon: + +```json +{ + "joomla_version": "string", + "extensions_outdated": integer, + "vulnerabilities": integer, + "php_version": "string", + "panopticon_version": "string" +} +``` + +## Rate Limiting + +**Limit**: 60 requests per hour per deployment +**Header**: `X-RateLimit-Remaining` + +When limit exceeded: + +```json +{ + "success": false, + "error": "Rate limit exceeded", + "code": "RATE_LIMIT", + "retry_after": 3600 +} +``` + +## Webhooks (Future Feature) + +*Planned for version 2.0* + +Configure webhooks to receive notifications: + +```json +{ + "webhook_url": "https://your-system.com/webhook", + "events": ["status_change", "critical_alert"], + "secret": "webhook-secret-key" +} +``` + +## API Versioning + +Current API Version:*v1** + +Version specified in:*URL path** (future) or*Accept header** + +```http +Accept: application/vnd.mokodolideploy.v1+json +``` + +## Best Practices + +1.*Use HTTPS**: Always use encrypted connections +2.*Secure API Keys**: Rotate keys regularly +3.*Handle Errors**: Implement retry logic with exponential backoff +4.*Validate Data**: Ensure data format matches expected structure +5.*Monitor Rate Limits**: Track remaining requests +6.*Log Responses**: Keep audit trail of API calls + +## Next Steps + +- [Remote Components Guide](remote-components.md) +- [Security Best Practices](security.md) +- [Development Guide](development.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/architecture.md b/MokoConsulting/MokoDoliRelease/architecture.md new file mode 100644 index 0000000..df6a5cf --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/architecture.md @@ -0,0 +1,125 @@ +← [Home](Home) + +# Architecture + +System architecture and design documentation for MokoDoliDeploy. + +## Overview + +MokoDoliDeploy follows a modular, extensible architecture designed for monitoring diverse remote systems while maintaining simplicity and performance. + +## Architecture Diagram + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Dolibarr Instance │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ MokoDoliDeploy Module │ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ +│ │ │ Dashboard │ │ Deployments │ │ Deployment │ │ │ +│ │ │ (UI) │ │ List (UI) │ │ Card (UI) │ │ │ +│ │ └──────┬───────┘ └──────┬───────┘ └───────┬───────┘ │ │ +│ │ │ │ │ │ │ +│ │ └─────────────────┴───────────────────┘ │ │ +│ │ │ │ │ +│ │ ┌─────────▼─────────┐ │ │ +│ │ │ Deployment │ │ │ +│ │ │ Class (Model) │ │ │ +│ │ │ - CRUD Operations│ │ │ +│ │ │ - Health Checks │ │ │ +│ │ │ - Status Updates │ │ │ +│ │ └─────────┬─────────┘ │ │ +│ │ │ │ │ +│ │ ┌─────────────────┼─────────────────┐ │ │ +│ │ │ │ │ │ │ +│ │ ┌─────▼─────┐ ┌────────▼────────┐ ┌────▼────────┐ │ │ +│ │ │ Dolibarr │ │ Joomla │ │ Live Chat │ │ │ +│ │ │ Health │ │ Health │ │ Helper │ │ │ +│ │ │ Checker │ │ Checker │ │ Checker │ │ │ +│ │ └───────────┘ └─────────────────┘ └─────────────┘ │ │ +│ │ │ │ +│ │ ┌────────────────────────────────────────────────────┐ │ │ +│ │ │ Database (llx_mokodolideploy_*) │ │ │ +│ │ │ - deployment table │ │ │ +│ │ │ - health_data (JSON) │ │ │ +│ │ └────────────────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + │ + ┌──────────┼──────────┐ + │ │ │ + ┌─────▼────┐ ┌───▼────┐ ┌──▼──────┐ + │ Remote │ │ Remote │ │ Remote │ + │ Dolibarr │ │ Joomla │ │ Chat │ + └──────────┘ └────────┘ └─────────┘ +``` + +## Design Patterns + +### MVC Pattern (Adapted for Dolibarr) + +**Model**: `src/class/deployment.class.php` +- Business logic +- Data access layer +- Health check orchestration + +**View**: UI files (`*.php`) +- `dashboard.php` - Overview of all deployments +- `deployments_list.php` - Tabular list view +- `deployment_card.php` - Detail view + +**Controller**: Embedded in view files +- Request handling +- User input validation +- Response generation + +### Repository Pattern + +The `Deployment` class acts as a repository for deployment entities: + +```php +class Deployment extends CommonObject +{ + // CRUD operations + public function create($user) + public function fetch($id) + public function update($user) + public function delete($user) + + // Business logic + public function checkHealth() + public function suspend() + public function resume() +} +``` + +### Strategy Pattern + +Health checking uses strategy pattern for different deployment types: + +```php +// Strategy interface +interface HealthChecker { + public function check($endpoint, $apiKey); +} + +// Concrete strategies +class DolibarrHealthChecker implements HealthChecker { } +class JoomlaHealthChecker implements HealthChecker { } +class LiveChatHealthChecker implements HealthChecker { } +``` + +## Component Architecture + +### Core Components + +#### 1. Deployment Manager + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/configuration.md b/MokoConsulting/MokoDoliRelease/configuration.md new file mode 100644 index 0000000..c930f9a --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/configuration.md @@ -0,0 +1,641 @@ +← [Home](Home) + +# Configuration Guide + +Complete configuration reference for MokoDoliRelease module. + +## Table of Contents + +1. [Module Configuration](#module-configuration) +2. [Release Endpoint Configuration](#release-endpoint-configuration) +3. [Deployment Configuration](#deployment-configuration) +4. [Client and Contract Integration](#client-and-contract-integration) +5. [Cron Configuration](#cron-configuration) +6. [Advanced Configuration](#advanced-configuration) + +## Module Configuration + +Access module settings:*MokoDoliRelease → Setup** + +### Health Check Settings + +#### Check Interval + +**Setting**: `MOKODOLIDEPLOY_HEALTH_CHECK_INTERVAL` +**Default**: 60 minutes +**Range**: 15-1440 minutes + +Controls how often automated health checks run. + +**Recommendations**: +- **Critical systems**: 15-30 minutes +- **Production systems**: 60 minutes +- **Development systems**: 120-240 minutes + +#### Automatic Checks + +**Setting**: `MOKODOLIDEPLOY_AUTO_HEALTH_CHECK` +**Default**: Enabled + +When enabled, health checks run automatically based on the interval. + +**Note**: Requires cron job configuration for truly automated checks. + +### Notification Settings + +#### Email Notifications + +**Setting**: `MOKODOLIDEPLOY_EMAIL_NOTIFICATIONS` +**Default**: Disabled + +Enable email alerts for status changes. + +**Configuration**: +1. Enable notifications in module settings +2. Configure recipient email addresses +3. Set notification triggers (Critical, Warning, or both) + +#### Notification Triggers + +- **Critical Only**: Email on critical status +- **Warning and Critical**: Email on any issue +- **All Changes**: Email on any status change + +### Security Settings + +#### SSL Verification + +**Setting**: `MOKODOLIRELEASE_SSL_VERIFY` +**Default**: Enabled + +Verify SSL/TLS certificates when connecting to remote systems. + +**Disable only for**: +- Development environments with self-signed certificates +- Internal systems behind firewalls + +#### API Timeout + +**Setting**: `MOKODOLIRELEASE_API_TIMEOUT` +**Default**: 30 seconds +**Range**: 5-120 seconds + +Maximum time to wait for API responses. + +## Release Endpoint Configuration + +### Overview + +The release endpoint is the core API interface for uploading, downloading, and distributing software releases. Proper configuration ensures secure and reliable release management. + +### Base URL Structure + +Your release API endpoints follow this pattern: + +``` +https://[your-dolibarr-domain]/custom/mokodolirelease/api/[endpoint].php +``` + +**Examples**: +- Upload: `https://erp.company.com/custom/mokodolirelease/api/upload_release.php` +- Download: `https://erp.company.com/custom/mokodolirelease/api/download_release.php` +- Update Stream: `https://erp.company.com/custom/mokodolirelease/api/update_stream.php` + +### Step 1: Verify Module Installation + +Ensure the module is correctly installed: + +```bash +# Check module directory exists +ls -la /path/to/dolibarr/htdocs/custom/mokodolirelease/ + +# Verify API files are present +ls -la /path/to/dolibarr/htdocs/custom/mokodolirelease/api/ +# Should show: upload_release.php, download_release.php, update_stream.php, etc. +``` + +### Step 2: Configure File Storage + +Set up the releases directory with proper permissions: + +```bash +# Create releases directory structure +mkdir -p /path/to/documents/mokodolirelease/releases + +# Create product-specific directories +mkdir -p /path/to/documents/mokodolirelease/releases/dolibarr/stable +mkdir -p /path/to/documents/mokodolirelease/releases/dolibarr/beta +mkdir -p /path/to/documents/mokodolirelease/releases/dolibarr/alpha +mkdir -p /path/to/documents/mokodolirelease/releases/dolibarr/rc +mkdir -p /path/to/documents/mokodolirelease/releases/dolibarr/lts +mkdir -p /path/to/documents/mokodolirelease/releases/joomla/stable +mkdir -p /path/to/documents/mokodolirelease/releases/joomla/beta +mkdir -p /path/to/documents/mokodolirelease/releases/joomla/alpha +mkdir -p /path/to/documents/mokodolirelease/releases/joomla/rc +mkdir -p /path/to/documents/mokodolirelease/releases/joomla/lts + +# Set ownership (replace www-data with your web server user) +chown -R www-data:www-data /path/to/documents/mokodolirelease + +# Set permissions +chmod -R 755 /path/to/documents/mokodolirelease +``` + +**Directory Structure**: +``` +documents/mokodolirelease/ +└── releases/ + ├── dolibarr/ + │ ├── stable/ + │ │ └── dolibarr-19.0.1.zip + │ ├── beta/ + │ ├── alpha/ + │ ├── rc/ + │ └── lts/ + └── joomla/ + ├── stable/ + │ └── joomla-5.1.0.zip + ├── beta/ + ├── alpha/ + ├── rc/ + └── lts/ +``` + +### Step 3: Configure API Access + +#### Generate API Key + +1. Log into Dolibarr as administrator +2. Go to*Home → Setup → Modules/Applications** +3. Find and enable*API/Web Services** module +4. Go to*Home → Users & Groups** → Select your user +5. Click*Token** tab +6. Generate a new API key +7. Copy the generated key (DOLAPIKEY) + +**Security Note**: Keep API keys secure and rotate them regularly. + +#### Test API Access + +Test that the API is accessible: + +```bash +# Test basic connectivity +curl -I https://your-dolibarr.com/custom/mokodolirelease/api/get_latest_release.php + +# Expected: HTTP/1.1 200 OK or 401 Unauthorized + +# Test with authentication +curl -H "DOLAPIKEY: your_api_key" \ + https://your-dolibarr.com/custom/mokodolirelease/api/get_latest_release.php?product_type=dolibarr + +# Expected: JSON response with release data or error message +``` + +### Step 4: Configure Web Server + +#### Apache Configuration + +The module includes `.htaccess` for Apache. Verify it's enabled: + +```apache +# In your Dolibarr VirtualHost or .htaccess + + AllowOverride All + Require all granted + + +# Enable mod_rewrite if needed + + RewriteEngine On + +``` + +#### Nginx Configuration + +For Nginx, add this to your server block: + +```nginx +# Nginx configuration for MokoDoliRelease +location /custom/mokodolirelease/ { + # Allow API access + location ~ \.php$ { + try_files $uri =404; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + fastcgi_index index.php; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + include fastcgi_params; + } + + # Protect sensitive files + location ~ /documents/ { + deny all; + return 403; + } +} + +# Serve update streams +location ~ /custom/mokodolirelease/api/update_stream\.php$ { + try_files $uri =404; + fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; + include fastcgi_params; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; +} +``` + +### Step 5: Configure HTTPS/SSL + +**IMPORTANT**: Release endpoints should always use HTTPS for security. + +```bash +# Verify SSL certificate is valid +openssl s_client -connect your-dolibarr.com:443 -servername your-dolibarr.com + +# Check certificate expiry +echo | openssl s_client -connect your-dolibarr.com:443 2>/dev/null | openssl x509 -noout -dates +``` + +If you need to obtain an SSL certificate: + +```bash +# Using Let's Encrypt (free) +certbot --apache -d your-dolibarr.com +# or +certbot --nginx -d your-dolibarr.com +``` + +### Step 6: Test Upload Endpoint + +Upload a test release: + +```bash +# Create a test zip file +echo "test" > test.txt +zip test-release.zip test.txt + +# Upload via API +curl -X POST \ + -H "DOLAPIKEY: your_api_key" \ + -F "release_file=@test-release.zip" \ + -F "is_latest=0" \ + -F "changelog=Test release" \ + https://your-dolibarr.com/custom/mokodolirelease/api/upload_release.php + +# Expected response: +# {"success":true,"message":"Release uploaded successfully","data":{...}} +``` + +### Step 7: Configure Update Streams + +#### For Joomla Extensions + +Add the update stream URL to your Joomla extension's XML manifest: + +```xml + + + https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable + + +``` + +Test the update stream: + +```bash +curl "https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable" + +# Expected: XML response with extension update information +``` + +#### For Dolibarr Modules + +Configure module descriptor to check for updates: + +```php +// In your module's descriptor class +public function getUpdateUrl() +{ + return 'https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=dolibarr&type=stable'; +} +``` + +### Step 8: Configure Download Authentication (Optional) + +If you want to require license keys for downloads: + +**In MokoDoliRelease settings**: +1. Go to*MokoDoliRelease → Setup** +2. Enable*Require License for Downloads** +3. Save configuration + +**Testing with license**: + +```bash +# Download with license key +curl -O "https://your-dolibarr.com/custom/mokodolirelease/api/download_release.php?id=123&key=LICENSE-KEY-HERE" + +# Without valid license (if required): +# HTTP 403 Forbidden - "Valid license key required" +``` + +### Troubleshooting Release Endpoints + +#### Issue: API returns 404 Not Found + +**Solution**: +```bash +# Check module is installed +ls /path/to/dolibarr/htdocs/custom/mokodolirelease/api/ + +# Check file permissions +chmod 644 /path/to/dolibarr/htdocs/custom/mokodolirelease/api/*.php + +# Check web server configuration +# Ensure directory access is allowed +``` + +#### Issue: Upload fails with "Permission denied" + +**Solution**: +```bash +# Check directory ownership +chown -R www-data:www-data /path/to/documents/mokodolirelease/ + +# Check directory permissions +chmod -R 755 /path/to/documents/mokodolirelease/ + +# Check PHP upload limits +php -i | grep upload_max_filesize +php -i | grep post_max_size + +# Increase if needed in php.ini: +# upload_max_filesize = 100M +# post_max_size = 100M +``` + +#### Issue: Authentication fails + +**Solution**: +```bash +# Verify API key is correct +# Check user has API permissions in Dolibarr + +# Test with curl verbose mode +curl -v -H "DOLAPIKEY: your_api_key" \ + https://your-dolibarr.com/custom/mokodolirelease/api/get_latest_release.php?product_type=dolibarr + +# Check error logs +tail -f /var/log/apache2/error.log +# or +tail -f /var/log/nginx/error.log +``` + +#### Issue: Update stream returns empty XML + +**Solution**: +```bash +# Check if releases exist in database +# Log into Dolibarr → MokoDoliRelease → Releases + +# Verify product and type parameters +curl "https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=dolibarr&type=stable" + +# Check for releases with matching product/type +``` + +## Deployment Configuration + +### Creating a Deployment + +**Required Fields**: +- **Label**: Descriptive name (e.g., "Production Dolibarr") +- **Type**: Dolibarr, Joomla, Live Chat Helper, or Generic +- **Endpoint URL**: Full API endpoint URL + +**Optional Fields**: +- **API Key**: Authentication token (required for most types) +- **Client**: Link to a Dolibarr third-party (client) +- **Service Contract**: Link to a service contract +- **Notes**: Internal notes about the deployment + +### Setting the Endpoint URL + +The endpoint URL is the most critical configuration for a deployment. It determines how MokoDoliRelease connects to and monitors your remote system. + +#### General Rules for Endpoint URLs + +1.*Always use HTTPS** for production systems +2.*Use full URL** including protocol (https://) +3.*Do not include trailing slash** unless required by the API +4.*Verify the endpoint is accessible** from your Dolibarr server + +**Testing Endpoint Accessibility**: +```bash +# From your Dolibarr server, test the endpoint +curl -I https://remote-system.com/api/endpoint + +# Expected: HTTP 200 or 401 (authentication required) +# Failure: Connection timeout, DNS errors, SSL errors +``` + +### Deployment Types + +#### Dolibarr + +**Endpoint Format**: `https://domain.com/api/index.php` + +**Authentication**: DOLAPIKEY header +- Generate in Dolibarr:*Home → Setup → Modules → API/Web Services** +- Format: `DOLAPIKEY: your-api-key-here` + +**Required Permissions**: +- Read access to status endpoints +- No write permissions needed + +#### Joomla (Panopticon) + +**Endpoint Format**: `https://domain.com/api/panopticon/v1/info` + +**Prerequisites**: +1. Install Akeeba Panopticon plugin on Joomla site +2. Generate API token in Panopticon settings +3. Enable remote monitoring + +**Authentication**: Bearer token +- Format: `Authorization: Bearer your-token-here` + +#### Live Chat Helper + +**Endpoint Format**: `https://domain.com/api/health` + +**Authentication**: Bearer token or API key +- Refer to Live Chat Helper documentation for token generation + +**Special Features**: +- Real-time chat session monitoring +- Agent availability tracking +- Queue depth monitoring +- Response time metrics + +#### Generic + +**Endpoint Format**: Any HTTPS URL + +**Expected Response**: JSON format +```json +{ + "status": "ok", + "version": "1.0.0", + "database": { + "status": "connected", + "size": "500MB" + }, + "server": { + "load": "0.5", + "disk_free": "50GB" + } +} +``` + +## Client and Contract Integration + +### Linking to a Client + +1. Edit deployment +2. Select from*Client** dropdown +3. Save + +**Benefits**: +- Group deployments by client +- Generate client-specific reports +- Track service levels per client + +### Linking to a Service Contract + +1. Ensure deployment is linked to a client +2. Select from*Service Contract** dropdown +3. Save + +**Benefits**: +- Track SLA compliance +- Associate monitoring with billing +- Generate contract reports + +## Cron Configuration + +### Setting Up Cron + +Create a cron job to run automated health checks: + +```bash +# Edit crontab +crontab -e + +# Add line for hourly checks +0 php /path/to/dolibarr/htdocs/custom/mokodolirelease/scripts/cron/health_check.php +``` + +### Cron Frequency Recommendations + +| Environment | Frequency | Cron Expression | +|-------------|-----------|-----------------| +| Critical | Every 15 min | `*/15` | +| Production | Every hour | `0` | +| Staging | Every 4 hours | `0/4` | +| Development | Twice daily | `0 8,17` | + +### Verifying Cron + +Check cron execution: +```bash +# View cron logs +grep CRON /var/log/syslog + +# Test manual execution +php /path/to/dolibarr/htdocs/custom/mokodolirelease/scripts/cron/health_check.php +``` + +## Advanced Configuration + +### Custom Health Check Logic + +Edit `src/class/deployment.class.php` to add custom checks: + +```php +// Add custom validation +public function checkCustomHealth() { + // Your custom logic here + return array('status' => 'ok', 'message' => 'Custom check passed'); +} +``` + +### Database Optimization + +For large deployments (100+), optimize database: + +```sql +-- Add indexes for better performance +ALTER TABLE llx_mokodolirelease_deployment +ADD INDEX idx_health_status (health_status); + +ALTER TABLE llx_mokodolirelease_deployment +ADD INDEX idx_last_check (last_health_check); +``` + +### Custom Metrics + +Add custom metrics to health data: + +```php +$healthData = array( + 'custom_metric' => $value, + 'custom_status' => $status +); +$deployment->setHealthData(json_encode($healthData)); +``` + +## Configuration Files + +### Module Descriptor + +Location: `src/core/modules/modMokoDoliRelease.class.php` + +Contains: +- Module ID: 185058 +- Version information +- Dependencies +- Database schema definitions + +**Do not modify unless extending the module.** + +### Language Files + +Location: `src/langs/en_US/mokodolirelease.lang` + +Customize labels and messages: +```php +$langs->trans("MyCustomLabel") = "My Custom Text"; +``` + +## Best Practices + +1.*Start with defaults**: Use recommended settings initially +2.*Test in development**: Verify configuration before production +3.*Monitor performance**: Watch for API timeouts +4.*Secure API keys**: Never commit keys to version control +5.*Regular backups**: Backup configuration and data +6.*Document changes**: Keep notes on custom configurations + +## Next Steps + +- [Health Monitoring Guide](health-monitoring.md) +- [Remote Components Setup](remote-components.md) +- [Performance Optimization](performance.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/enterprise-deployment.-.-.md b/MokoConsulting/MokoDoliRelease/enterprise-deployment.-.-.md new file mode 100644 index 0000000..e1f2ec9 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/enterprise-deployment.-.-.md @@ -0,0 +1,586 @@ +← [Home](Home) + +# Enterprise Deployment Guide + +Comprehensive guide for deploying MokoDoliDeploy at enterprise scale. + +## Enterprise Architecture + +### Multi-Tier Deployment + +``` +┌─────────────────────────────────────────────────────────┐ +│ Enterprise Monitoring Infrastructure │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Load Balancer (HAProxy/Nginx) │ +│ ├─ Primary Monitoring Server (Active) │ +│ └─ Secondary Monitoring Server (Standby) │ +│ │ +│ Database Cluster (MySQL/MariaDB) │ +│ ├─ Primary DB (Write) │ +│ ├─ Replica 1 (Read) │ +│ └─ Replica 2 (Read) │ +│ │ +│ Message Queue (Redis/RabbitMQ) │ +│ └─ Health Check Job Queue │ +│ │ +│ Monitoring & Logging │ +│ ├─ Prometheus │ +│ ├─ Grafana │ +│ └─ ELK Stack │ +└─────────────────────────────────────────────────────────┘ +``` + +### Scalability Considerations + +#### Horizontal Scaling + +**Supported**: Yes, with load balancing + +**Configuration**: +1. Deploy multiple Dolibarr instances +2. Share database (primary + replicas) +3. Use Redis for session storage +4. Implement sticky sessions or session replication + +**Capacity Planning**: +- **Small Enterprise**: 1-100 deployments, 1 server +- **Medium Enterprise**: 100-500 deployments, 2-3 servers +- **Large Enterprise**: 500-2000 deployments, 5+ servers +- **Extra Large**: 2000+ deployments, 10+ servers with clustering + +#### Vertical Scaling + +**Resource Requirements per 100 Deployments**: +- CPU: 2 cores +- RAM: 4 GB +- Storage: 10 GB +- Network: 100 Mbps + +### High Availability Setup + +#### Active-Passive Configuration + +**Components**: +1.*Primary Server**: Handles all monitoring +2.*Secondary Server**: Standby mode +3.*Shared Storage**: NFS or SAN +4.*Keepalived/Pacemaker**: Automatic failover + +**Setup Steps**: + +```bash +# Primary Server +sudo apt install keepalived +sudo vi /etc/keepalived/keepalived.conf + +# Configure virtual IP +vrrp_instance VI_1 { + state MASTER + interface eth0 + virtual_router_id 51 + priority 100 + virtual_ipaddress { + 192.168.1.100 + } +} + +# Secondary Server +# Same config but priority 90 and state BACKUP +``` + +#### Active-Active Configuration + +**Requirements**: +- Load balancer (HAProxy/Nginx) +- Shared database cluster +- Session replication via Redis +- Synchronized file storage + +**HAProxy Configuration**: + +``` +frontend http_front + bind:80 + bind:443 ssl crt /etc/ssl/certs/domain.pem + default_backend http_back + +backend http_back + balance roundrobin + option httpchk GET /custom/mokodolideploy/api/health + server server1 192.168.1.10:80 check + server server2 192.168.1.11:80 check + server server3 192.168.1.12:80 check +``` + +### Database Clustering + +#### Master-Slave Replication + +**Configuration**: + +```sql +-- Master Configuration (my.cnf) +[mysqld] +server-id = 1 +log_bin = /var/log/mysql/mysql-bin.log +binlog_do_db = dolibarr_production + +-- Slave Configuration (my.cnf) +[mysqld] +server-id = 2 +relay-log = /var/log/mysql/mysql-relay-bin +log_bin = /var/log/mysql/mysql-bin.log +read_only = 1 +``` + +**Setup Replication**: + +```sql +-- On Master +CREATE USER 'replication'@'%' IDENTIFIED BY 'password'; +GRANT REPLICATION SLAVE ON.* TO 'replication'@'%'; +FLUSH PRIVILEGES; +SHOW MASTER STATUS; + +-- On Slave +CHANGE MASTER TO + MASTER_HOST='master-ip', + MASTER_USER='replication', + MASTER_PASSWORD='password', + MASTER_LOG_FILE='mysql-bin.000001', + MASTER_LOG_POS=107; +START SLAVE; +SHOW SLAVE STATUS\G +``` + +#### Multi-Master Setup + +For active-active configurations with write load distribution. + +**Considerations**: +- Conflict resolution strategy +- Auto-increment offset configuration +- Careful table design to avoid conflicts + +### Caching Strategy + +#### Redis Configuration + +```bash +# Install Redis +sudo apt install redis-server + +# Configure Redis +sudo vi /etc/redis/redis.conf + +# Enable persistence +appendonly yes +appendfsync everysec + +# Set memory limits +maxmemory 2gb +maxmemory-policy allkeys-lru +``` + +**Cache Implementation**: + +```php +// Enable caching in deployment checks +$redis = new Redis(); +$redis->connect('127.0.0.1', 6379); + +$cacheKey = "deployment_health_{$deployment->id}"; +$cached = $redis->get($cacheKey); + +if ($cached) { + return json_decode($cached, true); +} + +$health = $deployment->checkHealth(); +$redis->setex($cacheKey, 300, json_encode($health)); // 5 min TTL +return $health; +``` + +### Load Distribution + +#### Health Check Distribution + +**Strategy**: Distribute checks across time to avoid load spikes + +```php +// Stagger health checks +$deployments = getAllDeployments(); +$interval = 3600 / count($deployments); // 1 hour spread + +foreach ($deployments as $index => $deployment) { + $offset = $index $interval; + schedule_health_check($deployment, time() + $offset); +} +``` + +#### Geographic Distribution + +**Multi-Region Setup**: +- Deploy monitoring servers in multiple regions +- Monitor local deployments from nearest server +- Centralize reporting and dashboards +- Use geo-DNS for regional routing + +### Security at Scale + +#### Network Segmentation + +``` +┌─────────────────────────────────────────┐ +│ DMZ (Public-Facing) │ +│ ├─ Load Balancer │ +│ └─ Reverse Proxy │ +├─────────────────────────────────────────┤ +│ Application Tier (Private) │ +│ ├─ Monitoring Servers │ +│ └─ Web Application Servers │ +├─────────────────────────────────────────┤ +│ Database Tier (Isolated) │ +│ ├─ Database Cluster │ +│ └─ Redis Cache │ +├─────────────────────────────────────────┤ +│ Management Network │ +│ ├─ Monitoring (Prometheus/Grafana) │ +│ └─ Logging (ELK) │ +└─────────────────────────────────────────┘ +``` + +#### Firewall Rules + +```bash +# Application servers +iptables -A INPUT -p tcp --dport 443 -j ACCEPT # HTTPS +iptables -A INPUT -p tcp --dport 80 -j ACCEPT # HTTP +iptables -A INPUT -s 10.0.0.0/8 -p tcp --dport 3306 -j ACCEPT # MySQL + +# Database servers +iptables -A INPUT -s 10.0.1.0/24 -p tcp --dport 3306 -j ACCEPT +iptables -A INPUT -j DROP # Drop all other +``` + +### Monitoring the Monitor + +#### Health Checks for Monitoring System + +**Uptime Monitoring**: +- External service (UptimeRobot, Pingdom) +- Monitor /api/health endpoint +- Alert on downtime + +**Performance Metrics**: +- Dashboard load time +- API response time +- Health check completion rate +- Database query performance + +**Prometheus Configuration**: + +```yaml +scrape_configs: + - job_name: 'mokodolideploy' + static_configs: + - targets: ['localhost:9090'] + metrics_path: '/custom/mokodolideploy/metrics' + scrape_interval: 30s +``` + +### Disaster Recovery + +#### Backup Strategy + +**What to Backup**: +1. Database (deployments, configurations, health history) +2. Configuration files +3. Custom scripts and modifications +4. SSL certificates and keys + +**Backup Schedule**: +- **Full Backup**: Daily at 2 AM +- **Incremental**: Every 6 hours +- **Transaction Logs**: Continuous +- **Retention**: 30 days daily, 12 months monthly + +**Automated Backup Script**: + +```bash +#!/bin/bash +# backup-mokodolideploy.sh + +DATE=$(date +%Y%m%d_%H%M%S) +BACKUP_DIR="/backups/mokodolideploy" +DB_NAME="dolibarr_production" + +# Database backup +mysqldump -u backup_user -p'password' \ + $DB_NAME \ + --single-transaction \ + --routines \ + --triggers \ + | gzip > $BACKUP_DIR/db_$DATE.sql.gz + +# File backup +tar -czf $BACKUP_DIR/files_$DATE.tar.gz \ + */var/www/dolibarr/htdocs/custom/mokodolideploy \ + */etc/ssl/certs/domain.pem + +# Upload to S3 +aws s3 cp $BACKUP_DIR/db_$DATE.sql.gz s3://backups/mokodolideploy/ +aws s3 cp $BACKUP_DIR/files_$DATE.tar.gz s3://backups/mokodolideploy/ + +# Clean old backups (keep 30 days) +find $BACKUP_DIR -mtime +30 -delete +``` + +#### Recovery Procedures + +**RTO (Recovery Time Objective)**: < 4 hours +**RPO (Recovery Point Objective)**: < 15 minutes + +**Recovery Steps**: + +1.*Restore Database**: +```bash +# Stop application +systemctl stop apache2 + +# Restore database +gunzip < db_backup.sql.gz | mysql -u root -p dolibarr_production + +# Verify data integrity +mysql -u root -p -e "SELECT COUNT(*) FROM dolibarr_production.llx_mokodolideploy_deployment;" +``` + +2.*Restore Files**: +```bash +cd /var/www/dolibarr/htdocs/custom/ +rm -rf mokodolideploy +tar -xzf files_backup.tar.gz +chown -R www-data:www-data mokodolideploy +``` + +3.*Start Services**: +```bash +systemctl start mysql +systemctl start redis +systemctl start apache2 +``` + +4.*Verify Operation**: +```bash +curl -I https://your-domain.com/custom/mokodolideploy/api/health +``` + +### Performance Optimization + +#### Database Optimization + +```sql +-- Add indexes for large deployments +ALTER TABLE llx_mokodolideploy_deployment +ADD INDEX idx_health_last_check (health_status, last_health_check); + +ALTER TABLE llx_mokodolideploy_deployment +ADD INDEX idx_client (fk_soc); + +-- Partition by date for historical data +ALTER TABLE llx_mokodolideploy_deployment +PARTITION BY RANGE (YEAR(date_creation)) ( + PARTITION p2024 VALUES LESS THAN (2025), + PARTITION p2025 VALUES LESS THAN (2026), + PARTITION p_future VALUES LESS THAN MAXVALUE +); + +-- Regular maintenance +OPTIMIZE TABLE llx_mokodolideploy_deployment; +ANALYZE TABLE llx_mokodolideploy_deployment; +``` + +#### Application Optimization + +**PHP Configuration** (`php.ini`): + +```ini +; Memory +memory_limit = 512M +max_execution_time = 300 + +; OPcache +opcache.enable = 1 +opcache.memory_consumption = 256 +opcache.interned_strings_buffer = 16 +opcache.max_accelerated_files = 10000 +opcache.revalidate_freq = 2 + +; Realpath cache +realpath_cache_size = 4M +realpath_cache_ttl = 600 +``` + +**Apache Configuration**: + +```apache +# Enable compression + + AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript application/json + + +# Enable caching + + ExpiresActive On + ExpiresByType text/css "access plus 1 month" + ExpiresByType application/javascript "access plus 1 month" + ExpiresByType image/png "access plus 1 year" + + +# Connection pooling +MaxKeepAliveRequests 1000 +KeepAliveTimeout 5 +``` + +### Compliance and Auditing + +#### Audit Logging + +Enable comprehensive audit trail: + +```php +// Log all health check operations +function logHealthCheck($deployment_id, $status, $details) { + $log = array( + 'timestamp' => date('Y-m-d H:i:s'), + 'deployment_id' => $deployment_id, + 'status' => $status, + 'details' => $details, + 'user' => getCurrentUser(), + 'ip' => $_SERVER['REMOTE_ADDR'] + ); + + // Log to file + file_put_contents( + '/var/log/mokodolideploy/audit.log', + json_encode($log) . PHP_EOL, + FILE_APPEND + ); + + // Log to SIEM + syslog(LOG_INFO, json_encode($log)); +} +``` + +#### Retention Policies + +**Data Retention**: +- **Health Check Results**: 90 days detailed, 2 years aggregated +- **Audit Logs**: 7 years +- **Performance Metrics**: 30 days detailed, 1 year aggregated +- **Backup Files**: 30 days daily, 12 months monthly, 7 years annual + +**Implementation**: + +```sql +-- Archive old health data +CREATE TABLE llx_mokodolideploy_deployment_archive LIKE llx_mokodolideploy_deployment; + +INSERT INTO llx_mokodolideploy_deployment_archive +SELECT FROM llx_mokodolideploy_deployment +WHERE last_health_check < DATE_SUB(NOW(), INTERVAL 90 DAY); + +DELETE FROM llx_mokodolideploy_deployment +WHERE last_health_check < DATE_SUB(NOW(), INTERVAL 90 DAY); +``` + +### Cost Optimization + +#### Resource Management + +**Compute Optimization**: +- Use spot instances for non-critical processing +- Schedule health checks during off-peak hours +- Implement auto-scaling based on load +- Use reserved instances for predictable workloads + +**Storage Optimization**: +- Compress old health check data +- Archive to cheaper storage tiers (S3 Glacier) +- Implement data lifecycle policies +- Use thin provisioning for databases + +#### Monitoring Costs + +**AWS Cost Breakdown** (Example for 500 deployments): +- EC2 Instances (3x t3.medium): $90/month +- RDS (db.t3.large): $145/month +- ElastiCache Redis: $35/month +- S3 Storage (backups): $15/month +- Data Transfer: $20/month +- **Total**: ~$305/month + +### Integration with Enterprise Systems + +#### Active Directory Integration + +```php +// LDAP authentication +$ldap = ldap_connect("ldap://ad.company.com"); +ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3); +ldap_bind($ldap, $username . "@company.com", $password); +``` + +#### SIEM Integration + +Send logs to enterprise SIEM: + +```bash +# rsyslog configuration +*.* @@siem.company.com:514 + +# Forward to Splunk +*/var/log/mokodolideploy/*.log { + postrotate + */opt/splunkforwarder/bin/splunk add oneshot /var/log/mokodolideploy/audit.log -sourcetype mokodolideploy + endscript +} +``` + +#### Ticketing System Integration + +```php +// Create ticket on critical status +function createIncident($deployment, $health_data) { + $jira_api = "https://jira.company.com/rest/api/2/issue"; + $ticket = array( + 'fields' => array( + 'project' => array('key' => 'OPS'), + 'summary' => "Critical: {$deployment->label} health check failed", + 'description' => json_encode($health_data), + 'issuetype' => array('name' => 'Incident'), + 'priority' => array('name' => 'High') + ) + ); + + // POST to JIRA API + // ... +} +``` + +## Next Steps + +- [Governance & Compliance](governance.md) +- [Security Policies](security-policies.md) +- [SLA Management](sla-management.md) +- [Runbook](runbook.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/faq.md b/MokoConsulting/MokoDoliRelease/faq.md new file mode 100644 index 0000000..d79e9f6 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/faq.md @@ -0,0 +1,279 @@ +← [Home](Home) + +# Frequently Asked Questions (FAQ) + +Common questions about MokoDoliDeploy module. + +## General Questions + +### What is MokoDoliDeploy? + +MokoDoliDeploy is a Dolibarr module that monitors the health and status of remote deployments including Dolibarr instances, Joomla sites, Live Chat Helper systems, and generic API endpoints. + +### What is the Module ID? + +**Module ID**: 185058 + +### What license is it under? + +GPL-3.0-or-later (GNU General Public License version 3 or later) + +### Is it free? + +Yes, MokoDoliDeploy is open source and free to use under the GPL-3.0-or-later license. + +## Installation & Setup + +### What are the requirements? + +- Dolibarr 14.0+ +- PHP 7.4+ (8.0+ recommended) +- MySQL/MariaDB 5.7+ +- HTTPS connection for remote monitoring + +### Why must the directory be named "mokodolideploy"? + +Dolibarr's module system expects specific directory names. The internal module code references the `mokodolideploy` directory name for proper functionality. + +### Can I rename the module? + +No. The directory must be named `mokodolideploy` for the module to work correctly. + +### How do I upgrade to a new version? + +1. Backup your database +2. Deactivate the module +3. Replace the module files +4. Reactivate the module +5. Check for any database migrations + +## Features & Functionality + +### What systems can I monitor? + +- **Dolibarr** instances (via Dolibarr API) +- **Joomla** sites (via Akeeba Panopticon) +- **Live Chat Helper** systems +- **Generic** endpoints (any JSON API) + +### How often are health checks performed? + +Default: Every 60 minutes (configurable from 15-1440 minutes) + +### Can I monitor systems behind firewalls? + +Yes, using push-based monitoring with remote reporter scripts. The remote system pushes status to MokoDoliDeploy instead of pulling. + +### Does it support multiple Dolibarr instances? + +Yes, you can monitor unlimited Dolibarr instances from one central monitoring installation. + +### Can I link deployments to clients? + +Yes, deployments can be linked to Dolibarr third-parties (clients) and service contracts. + +## Monitoring & Health Checks + +### What does each health status mean? + +- **Healthy** (Green): All checks passed, system operating normally +- **Warning** (Yellow): Minor issues detected, attention recommended +- **Critical** (Red): Serious problems, immediate action required +- **Unknown** (Gray): Cannot connect or determine status + +### How are health statuses determined? + +Based on multiple factors: +- Response time +- Database connectivity +- Server load +- Disk space +- SSL certificate validity +- Security vulnerabilities +- Update availability + +### Can I customize health check logic? + +Yes, by extending the `Deployment` class and implementing custom check methods. + +### Why does a deployment show "Unknown"? + +Common reasons: +- Cannot connect to endpoint (firewall, network) +- Invalid credentials +- Endpoint not responding +- SSL certificate issues +- Incorrect endpoint URL + +## Security & Privacy + +### Is data encrypted? + +- **In Transit**: HTTPS required for all connections +- **At Rest**: API keys encrypted in database +- **Passwords**: Never stored, only API tokens + +### What permissions does the module need? + +- Read/write access to Dolibarr database +- Outbound HTTPS connections to remote systems +- No special server privileges required + +### Can I use self-signed certificates? + +Yes, but you must disable SSL verification in module settings. Not recommended for production. + +### How are API keys stored? + +API keys are encrypted in the database using Dolibarr's encryption system. + +## Technical Questions + +### What database tables does it create? + +- `llx_mokodolideploy_deployment` - Main deployment table + +### Can I monitor systems on different networks? + +Yes, as long as they're accessible via HTTPS from your Dolibarr server. + +### Does it work with Docker? + +Yes, works with both dockerized and traditional Dolibarr installations. + +### Can I use it with Dolibarr SaaS? + +Depends on your SaaS provider's policies regarding custom modules. Check with your provider. + +### What's the performance impact? + +Minimal. Health checks run asynchronously and don't impact user experience. Typical overhead: < 5% CPU during checks. + +## Troubleshooting + +### Health checks are always timing out + +- Increase timeout in module settings (try 60 seconds) +- Check network connectivity to remote systems +- Verify remote systems are responding quickly + +### Cron jobs aren't running + +- Verify cron job is set up correctly +- Check cron logs: `grep CRON /var/log/syslog` +- Test manual execution of cron script + +### Dashboard loads slowly + +- Optimize database tables +- Add database indexes +- Reduce number of monitored deployments +- Increase health check interval + +### Cannot connect to remote system + +- Test connectivity: `curl -I https://remote-url` +- Verify firewall rules +- Check API credentials +- Ensure remote API is enabled + +## Best Practices + +### How many deployments can I monitor? + +Tested with 500+ deployments. Performance depends on: +- Server resources +- Check frequency +- Network latency to remote systems + +### What's the recommended check interval? + +- **Critical systems**: 15-30 minutes +- **Production systems**: 60 minutes (default) +- **Development systems**: 120-240 minutes + +### Should I use pull or push monitoring? + +- **Pull**: Simpler, better for systems you control +- **Push**: Better for firewalled systems, real-time updates + +### How should I organize deployments? + +- Link to clients for client-specific grouping +- Use clear, descriptive labels +- Associate with service contracts when applicable +- Add notes for special configurations + +## Support & Development + +### Where can I get help? + +- **Documentation**: [docs/](.) +- **Email**: hello@mokoconsulting.tech +- **Issues**: [GitHub Issues](https://github.com/mokoconsulting-tech/MokoDoliDeploy/issues) + +### Can I contribute? + +Yes! Contributions welcome: +1. Fork the repository +2. Make your changes +3. Submit a pull request + +Follow the existing code formatting conventions. + +### How do I report a bug? + +1. Check if it's already reported on GitHub +2. Collect: Version info, error messages, steps to reproduce +3. Submit issue on GitHub or email support + +### Is commercial support available? + +Contact hello@mokoconsulting.tech for commercial support options. + +## Future Features + +### What's planned for future versions? + +- Webhook notifications +- Advanced reporting +- More deployment types +- Mobile app +- Export/import configurations +- Historical trending +- Alert escalation + +### Can I request features? + +Yes! Submit feature requests: +- GitHub Issues (preferred) +- Email: hello@mokoconsulting.tech + +## Licensing + +### Can I use this commercially? + +Yes, under GPL-3.0-or-later license terms. + +### Can I modify the code? + +Yes, modifications allowed under GPL-3.0-or-later. Share improvements back to the community! + +### Do I need to release my modifications? + +Only if you distribute the modified version. Internal use doesn't require sharing changes. + +## Next Steps + +- [Installation Guide](installation.md) +- [Quick Start Guide](quick-start.md) +- [Troubleshooting](troubleshooting.md) +- [Full Documentation](README.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/governance.md b/MokoConsulting/MokoDoliRelease/governance.md new file mode 100644 index 0000000..b5637f7 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/governance.md @@ -0,0 +1,523 @@ +← [Home](Home) + +# Governance & Compliance + +Enterprise governance framework for MokoDoliDeploy deployment and operations. + +## Governance Framework + +### Roles and Responsibilities + +#### Executive Sponsor +- **Accountability**: Overall program success +- **Responsibilities**: + - Budget approval + - Strategic alignment + - Executive escalation point + +#### Platform Owner +- **Accountability**: Platform operations and availability +- **Responsibilities**: + - Service level agreement (SLA) management + - Capacity planning + - Vendor management + - Budget management + +#### Security Officer +- **Accountability**: Security and compliance +- **Responsibilities**: + - Security assessments + - Vulnerability management + - Compliance audits + - Incident response + +#### Operations Team +- **Accountability**: Day-to-day operations +- **Responsibilities**: + - Monitoring configuration + - Health check management + - Incident response + - User support + +#### Development Team +- **Accountability**: Customization and enhancement +- **Responsibilities**: + - Module customization + - Integration development + - Bug fixes + - Feature development + +### Decision Authority Matrix (RACI) + +| Decision | Executive | Platform Owner | Security | Operations | Development | +|----------|-----------|----------------|----------|------------|-------------| +| Budget Approval | A | R | C | I | I | +| Architecture Changes | I | A | C | R | R | +| Security Policies | C | C | A | I | R | +| Deployment Changes | I | A | C | R | R | +| Incident Response | I | A | C | R | I | +| User Access | I | A | R | C | I | + +**Legend**: R = Responsible, A = Accountable, C = Consulted, I = Informed + +### Change Management + +#### Change Types + +**Standard Changes**: +- Pre-approved, low-risk +- Examples: Adding new deployments, adjusting check intervals +- Approval: Operations Manager +- Lead Time: Same day + +**Normal Changes**: +- Moderate risk, requires review +- Examples: Configuration changes, minor upgrades +- Approval: Change Advisory Board (CAB) +- Lead Time: 5 business days + +**Emergency Changes**: +- Critical, security or availability impact +- Examples: Security patches, system outages +- Approval: Emergency CAB +- Lead Time: < 4 hours + +#### Change Process + +``` +1. Request Submission + ↓ +2. Impact Assessment + ↓ +3. CAB Review (if required) + ↓ +4. Approval/Rejection + ↓ +5. Implementation + ↓ +6. Verification + ↓ +7. Documentation + ↓ +8. Post-Implementation Review +``` + +**Change Request Template**: + +```markdown +## Change Request: CR-2025-001 + +**Type**: Normal Change +**Submitted By**: John Doe +**Date**: 2025-01-08 +**Priority**: Medium + +### Description +Increase health check interval from 60 to 90 minutes to reduce load + +### Business Justification +Current monitoring load is impacting application performance during peak hours + +### Impact Assessment +- Systems Affected: All monitored deployments +- Downtime Required: None +- Rollback Plan: Revert configuration change + +### Risk Assessment +- Probability: Low +- Impact: Low +- Risk Level: Low + +### Implementation Plan +1. Update module configuration +2. Verify cron job schedule +3. Monitor first 24 hours +4. Document changes + +### Approval +- [ ] Operations Manager +- [ ] Platform Owner +``` + +## Compliance Requirements + +### Regulatory Compliance + +#### GDPR (General Data Protection Regulation) + +**Applicability**: If monitoring EU-based systems or EU citizen data + +**Requirements**: +1.*Data Protection**: + - Encrypt personal data at rest and in transit + - Implement access controls + - Log access to personal data + +2.*Right to Access**: + - Provide data export functionality + - Document data flows + - Maintain data inventory + +3.*Right to Erasure**: + - Implement data deletion procedures + - Remove from backups after retention period + - Document deletion process + +4.*Data Breach Notification**: + - Notify within 72 hours + - Document breach response plan + - Maintain incident log + +**Implementation**: + +```php +// GDPR-compliant data export +function exportUserData($user_id) { + $data = array( + 'deployments' => getDeploymentsForUser($user_id), + 'audit_logs' => getAuditLogsForUser($user_id), + 'health_checks' => getHealthChecksForUser($user_id) + ); + + // Anonymize sensitive data + foreach ($data['deployments'] as &$deployment) { + unset($deployment['api_key']); + } + + return json_encode($data, JSON_PRETTY_PRINT); +} + +// Data deletion +function deleteUserData($user_id) { + // Log deletion request + logDataDeletion($user_id, 'User requested data deletion'); + + // Anonymize instead of delete for audit trail + anonymizeDeployments($user_id); + anonymizeAuditLogs($user_id); + + // Mark for deletion from backups + scheduleBackupDeletion($user_id, '+30 days'); +} +``` + +#### HIPAA (Health Insurance Portability and Accountability Act) + +**Applicability**: If monitoring healthcare-related systems + +**Requirements**: +1.*Access Controls**: Role-based access, unique user IDs +2.*Audit Controls**: Comprehensive logging +3.*Transmission Security**: TLS 1.2+ +4.*Integrity Controls**: Checksums, version control + +#### SOC 2 (Service Organization Control) + +**Applicable Trust Services Criteria**: + +1.*Security**: Access controls, encryption, monitoring +2.*Availability**: 99.9% uptime SLA +3.*Processing Integrity**: Accurate health checks +4.*Confidentiality**: API key encryption +5.*Privacy**: GDPR-compliant data handling + +**Evidence Requirements**: +- System documentation +- Access control logs +- Incident response records +- Change management records +- Vendor assessments + +### Industry Standards + +#### ISO 27001 (Information Security Management) + +**Control Domains**: + +**A.9 - Access Control**: +- User access management +- Privileged access rights +- User access provisioning +- User access reviews + +**A.12 - Operations Security**: +- Change management +- Capacity management +- Malware protection +- Backup procedures + +**A.14 - System Acquisition, Development and Maintenance**: +- Secure development lifecycle +- Security testing +- Test data management + +**Implementation Checklist**: +- [ ] Access control policy documented +- [ ] User access reviews quarterly +- [ ] Change management process +- [ ] Security testing in CI/CD +- [ ] Backup and recovery tested +- [ ] Security awareness training +- [ ] Incident response plan +- [ ] Business continuity plan + +#### PCI DSS (Payment Card Industry Data Security Standard) + +**Applicability**: If monitoring payment processing systems + +**Relevant Requirements**: +- Requirement 2: Don't use vendor defaults +- Requirement 4: Encrypt transmission +- Requirement 6: Develop secure systems +- Requirement 10: Track and monitor access +- Requirement 11: Regular security testing + +### Audit and Certification + +#### Internal Audits + +**Frequency**: Quarterly + +**Scope**: +- Access control effectiveness +- Configuration management +- Change management compliance +- Incident response procedures +- Backup and recovery processes + +**Audit Checklist**: + +```markdown +## Q1 2025 Internal Audit + +### Access Control +- [ ] Review user access list +- [ ] Verify least privilege implementation +- [ ] Check for orphaned accounts +- [ ] Review privileged access logs + +### Configuration Management +- [ ] Verify configuration documentation +- [ ] Check configuration backup +- [ ] Review configuration changes +- [ ] Verify change approval + +### Incident Management +- [ ] Review incident logs +- [ ] Verify response times +- [ ] Check escalation procedures +- [ ] Review post-incident reports + +### Findings +1. Issue: 3 orphaned accounts found + Action: Disable accounts by 2025-02-01 + Owner: Operations Manager +``` + +#### External Audits + +**Frequency**: Annually + +**Auditor**: Independent third-party + +**Deliverables**: +- Audit report +- Findings and recommendations +- Remediation plan +- Certification (if applicable) + +### Data Classification + +#### Classification Levels + +**Public**: +- Description: Information intended for public distribution +- Examples: Marketing materials, public documentation +- Controls: None required + +**Internal**: +- Description: Information for internal use only +- Examples: Deployment configurations, health metrics +- Controls: Authentication required + +**Confidential**: +- Description: Sensitive business information +- Examples: API keys, client contracts +- Controls: Encryption, access logging, need-to-know + +**Restricted**: +- Description: Highly sensitive information +- Examples: Security credentials, PII +- Controls: Encryption, MFA, audit logging, data loss prevention + +#### Data Handling Requirements + +| Classification | Storage | Transmission | Retention | Disposal | +|----------------|---------|--------------|-----------|----------| +| Public | Any | Any | As needed | Standard | +| Internal | Secure servers | TLS | Per policy | Standard | +| Confidential | Encrypted | TLS 1.2+ | Per policy | Secure wipe | +| Restricted | Encrypted + MFA | TLS 1.3 | Minimum | Certified destruction | + +### Privacy Impact Assessment + +**When Required**: +- New deployment type monitoring +- Integration with new systems +- Processing new data types +- Significant architecture changes + +**Assessment Template**: + +```markdown +## Privacy Impact Assessment + +**Project**: Live Chat Helper Monitoring +**Date**: 2025-01-08 +**Assessor**: Privacy Officer + +### Data Collection +- What data: Chat session metadata, agent IDs, response times +- Why collected: Performance monitoring +- Legal basis: Legitimate interest +- Data subjects: Support agents, customers + +### Data Processing +- Processing activities: Aggregation, analysis, reporting +- Automated decisions: None +- Profiling: None +- Third parties: None + +### Data Storage +- Location: EU datacenter +- Duration: 90 days detailed, 2 years aggregated +- Security: Encrypted at rest and in transit + +### Privacy Risks +1. Risk: Identification of individuals from metadata + Mitigation: Anonymize agent IDs, aggregate data + Residual Risk: Low + +### Conclusion +- [ ] Privacy risks acceptable +- [ ] Recommendations implemented +- [ ] DPO approval obtained +``` + +### Compliance Monitoring + +#### Continuous Monitoring + +**Automated Checks**: +```bash +# Daily compliance check script +#!/bin/bash + +# Check encryption +check_encryption() { + # Verify database encryption + # Verify TLS configuration + # Verify API key encryption +} + +# Check access controls +check_access() { + # Verify RBAC implementation + # Check for unauthorized access + # Review privileged accounts +} + +# Check audit logging +check_logging() { + # Verify log collection + # Check log integrity + # Confirm log retention +} + +# Generate compliance report +generate_report() { + echo "Compliance Check - $(date)" + echo "Encryption: PASS" + echo "Access Control: PASS" + echo "Audit Logging: PASS" +} +``` + +#### Compliance Dashboard + +**Metrics to Track**: +- Compliance score (%) +- Open findings +- Overdue remediations +- Audit schedule status +- Training completion rate +- Policy acknowledgment rate + +### Policy Management + +#### Required Policies + +1.*Information Security Policy** +2.*Access Control Policy** +3.*Data Retention Policy** +4.*Incident Response Policy** +5.*Business Continuity Policy** +6.*Acceptable Use Policy** +7.*Change Management Policy** + +#### Policy Lifecycle + +``` +Draft → Review → Approval → Publication → +Implementation → Training → Audit → Review (annual) +``` + +#### Policy Template + +```markdown +## [Policy Name] + +**Policy Number**: POL-2025-001 +**Version**: 1.0 +**Effective Date**: 2025-01-08 +**Review Date**: 2026-01-08 +**Owner**: [Role] +**Approved By**: [Name, Title] + +### Purpose +[Why this policy exists] + +### Scope +[Who/what this applies to] + +### Policy Statement +[The actual policy requirements] + +### Responsibilities +[Who is responsible for what] + +### Enforcement +[Consequences of non-compliance] + +### Related Documents +[Links to related policies, procedures] + +### Revision History +| Version | Date | Changes | Author | +|---------|------|---------|--------| +| 1.0 | 2025-01-08 | Initial version | [Name] | +``` + +## Next Steps + +- [Security Policies](security-policies.md) +- [SLA Management](sla-management.md) +- [Compliance Checklist](compliance-checklist.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/installation.md b/MokoConsulting/MokoDoliRelease/installation.md new file mode 100644 index 0000000..3f9e504 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/installation.md @@ -0,0 +1,166 @@ +← [Home](Home) + +# Installation Guide + +Complete installation instructions for MokoDoliDeploy module. + +## Prerequisites + +### System Requirements + +- **Dolibarr**: Version 14.0 or higher +- **PHP**: Version 7.4 or higher (8.0+ recommended) +- **MySQL/MariaDB**: Version 5.7 or higher +- **Web Server**: Apache 2.4+ or Nginx 1.18+ +- **PHP Extensions**: curl, json, openssl, pdo_mysql + +### Permissions + +- Write access to Dolibarr's `htdocs/custom/` directory +- Database privileges to create tables +- Dolibarr administrator account + +## Installation Steps + +### Step 1: Download the Module + +Clone or download the repository: + +```bash +git clone https://github.com/mokoconsulting-tech/MokoDoliDeploy.git +cd MokoDoliDeploy +``` + +### Step 2: Copy to Dolibarr + +Copy the `src` directory to your Dolibarr installation: + +```bash +cp -r src /path/to/dolibarr/htdocs/custom/mokodolideploy +``` + +**Important**: The directory MUST be named `mokodolideploy` in the `htdocs/custom/` directory. + +**Installation Path**: `/path/to/dolibarr/htdocs/custom/mokodolideploy/` + +### Step 3: Set Permissions + +Ensure proper file permissions: + +```bash +cd /path/to/dolibarr/htdocs/custom/ +chown -R www-data:www-data mokodolideploy +chmod -R 755 mokodolideploy +``` + +Replace `www-data` with your web server user if different. + +### Step 4: Activate the Module + +1. Log in to Dolibarr as an administrator +2. Navigate to*Home → Setup → Modules/Applications** +3. Search for "MokoDoliDeploy" +4. Click the*Activate** button + +The module will automatically: +- Create the required database tables +- Set up default configuration +- Add menu entries + +### Step 5: Verify Installation + +1. Check that a new "MokoDoliDeploy" menu appears in the navigation +2. Navigate to*MokoDoliDeploy → Dashboard** +3. Verify the dashboard loads successfully + +## Post-Installation + +### Configure the Module + +1. Go to*MokoDoliDeploy → Setup** +2. Configure health check settings: + - Health check interval (default: 60 minutes) + - Enable/disable automatic checks + - Set notification preferences + +### Set Up Cron Job (Optional) + +For automated health checks, add a cron job: + +```bash +# Run health checks every hour +0 php /path/to/dolibarr/htdocs/custom/mokodolideploy/scripts/cron/health_check.php +``` + +## Upgrading + +### From Previous Version + +1. Backup your database: +```bash +mysqldump -u user -p database_name > backup.sql +``` + +2. Deactivate the old module in Dolibarr + +3. Replace the module files: +```bash +cd /path/to/dolibarr/htdocs/custom/ +rm -rf mokodolideploy +cp -r /path/to/new/src mokodolideploy +``` + +4. Reactivate the module in Dolibarr + +5. Check for database migrations in*Setup → Modules** + +## Troubleshooting Installation + +### Module Not Appearing + +- Verify the directory name is exactly `mokodolideploy` +- Check file permissions (should be readable by web server) +- Clear Dolibarr cache: Delete `documents/install.lock` + +### Database Errors + +- Ensure database user has CREATE TABLE privileges +- Check MySQL/MariaDB version compatibility +- Review Dolibarr error logs in `documents/dolibarr.log` + +### Permission Errors + +```bash +# Fix permissions +cd /path/to/dolibarr/htdocs/custom/mokodolideploy +find . -type d -exec chmod 755 {} \; +find . -type f -exec chmod 644 {} \; +``` + +## Uninstallation + +1. Navigate to*Home → Setup → Modules/Applications** +2. Find "MokoDoliDeploy" and click*Deactivate** +3. (Optional) Remove module files: +```bash +rm -rf /path/to/dolibarr/htdocs/custom/mokodolideploy +``` + +4. (Optional) Remove database tables: +```sql +DROP TABLE llx_mokodolideploy_deployment; +``` + +## Next Steps + +- [Configuration Guide](configuration.md) +- [Quick Start Guide](quick-start.md) +- [User Manual](user-manual.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/quick-start.-.-.md b/MokoConsulting/MokoDoliRelease/quick-start.-.-.md new file mode 100644 index 0000000..0f14d04 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/quick-start.-.-.md @@ -0,0 +1,305 @@ +← [Home](Home) + +# Quick Start Guide + +Get up and running with MokoDoliRelease in minutes. + +## Prerequisites + +- MokoDoliRelease module installed and activated +- Administrator access to Dolibarr +- At least one remote system to monitor OR releases to manage + +## Quick Setup: Choose Your Path + +### Path A: Release Management (Upload & Distribute Software) +Follow this if you want to distribute software releases with update streams. + +### Path B: Deployment Monitoring (Monitor Remote Systems) +Follow this if you want to monitor remote Dolibarr/Joomla/Chat systems. + +--- + +## Path A: Release Management Setup + +### Step 1: Configure Release Storage + +```bash +# Create release directories +mkdir -p /path/to/documents/mokodolirelease/releases/dolibarr/stable +mkdir -p /path/to/documents/mokodolirelease/releases/joomla/stable + +# Set permissions +chown -R www-data:www-data /path/to/documents/mokodolirelease +chmod -R 755 /path/to/documents/mokodolirelease +``` + +### Step 2: Get Your API Key + +1. Log into Dolibarr as administrator +2. Go to*Home → Users & Groups** → Select your user +3. Click*Token** tab +4. Generate a new API key +5. Copy the key (you'll need it for uploads) + +### Step 3: Upload Your First Release + +**Using cURL**: +```bash +curl -X POST \ + -H "DOLAPIKEY: your_api_key_here" \ + -F "release_file=@dolibarr-19.0.1.zip" \ + -F "is_latest=1" \ + -F "changelog=Bug fixes and improvements" \ + https://your-dolibarr.com/custom/mokodolirelease/api/upload_release.php +``` + +**Expected Response**: +```json +{ + "success": true, + "message": "Release uploaded successfully", + "data": { + "release_id": 1, + "ref": "REL-000001", + "version_number": "19.0.1", + "download_url": "/mokodolirelease/releases/dolibarr/dolibarr-19.0.1.zip" + } +} +``` + +### Step 4: Configure Update Stream + +**For Joomla Extensions**, add this to your extension's XML manifest: + +```xml + + + https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable + + +``` + +**Test the update stream**: +```bash +curl "https://your-dolibarr.com/custom/mokodolirelease/api/update_stream.php?product=joomla&type=stable" +``` + +### Step 5: Verify in Dolibarr + +1. Go to*MokoDoliRelease → Releases** +2. You should see your uploaded release +3. Click on it to view details + +✅*Release Management Setup Complete!** + +--- + +## Path B: Deployment Monitoring Setup + +### Step 1: Access the Module + +1. Log in to Dolibarr +2. Click*MokoDoliRelease** in the main menu +3. You'll see the Dashboard (initially empty) + +### Step 2: Prepare Your Remote System + +Before creating a deployment, you need to set up the endpoint on your remote system. + +#### For Dolibarr Instances + +On the*remote Dolibarr** you want to monitor: + +1. Enable API:*Home → Setup → Modules → API/Web Services** (Activate) +2. Generate API key:*Home → Users & Groups → [User] → Token** (Generate) +3. Copy the generated DOLAPIKEY +4. Note the API endpoint URL: `https://remote-dolibarr.com/api/index.php` + +**Test the endpoint**: +```bash +curl -H "DOLAPIKEY: your_copied_key" https://remote-dolibarr.com/api/index.php/status +``` + +#### For Joomla Sites + +On the*Joomla site** you want to monitor: + +1. Install Akeeba Panopticon plugin +2. Enable plugin:*System → Plugins → Akeeba Panopticon** +3. Generate API secret key in plugin settings +4. Note the endpoint URL: `https://joomla-site.com/api/panopticon/v1/info` + +**Test the endpoint**: +```bash +curl -H "Authorization: Bearer your_secret_key" https://joomla-site.com/api/panopticon/v1/info +``` + +### Step 3: Create Your First Deployment + +### For Dolibarr Instance + +1. Click*MokoDoliRelease → Deployments → New Deployment** +2. Fill in the form: + -*Label**: My Production Dolibarr + -*Type**: Dolibarr + -*Endpoint URL**: `https://remote-dolibarr.com/api/index.php` + -*API Key**: [paste the DOLAPIKEY from Step 2] +3. Click*Create** + +**Verify**: +```bash +# Test that MokoDoliRelease can reach your endpoint +curl -H "DOLAPIKEY: your_api_key" https://remote-dolibarr.com/api/index.php/status +``` + +### For Joomla Site + +1. Click*MokoDoliRelease → Deployments → New Deployment** +2. Fill in the form: + -*Label**: Company Website + -*Type**: Joomla + -*Endpoint URL**: `https://joomla-site.com/api/panopticon/v1/info` + -*API Key**: `Bearer [your-secret-key]` +3. Click*Create** + +**Verify**: +```bash +curl -H "Authorization: Bearer your_secret_key" https://joomla-site.com/api/panopticon/v1/info +``` + +### For Live Chat Helper + +1. Click*MokoDoliRelease → Deployments → New Deployment** +2. Fill in the form: + -*Label**: Support Chat System + -*Type**: Live Chat Helper + -*Endpoint URL**: `https://chat-system.com/api/health` + -*API Key**: [your API token] +3. Click*Create** + +### For Generic/Custom Endpoints + +1.*First**, create a health endpoint on your system (see [SAMPLE_CODE.md](SAMPLE_CODE.md#generic-deployment-endpoint)) +2. Click*MokoDoliRelease → Deployments → New Deployment** +3. Fill in: + -*Label**: Custom Application + -*Type**: Generic + -*Endpoint URL**: `https://your-app.com/api/health` + -*API Key**: [your API key] +4. Click*Create** + +### Step 4: Run Your First Health Check + +1. Go to*MokoDoliRelease → Dashboard** +2. Click*Check Health (All)** button +3. Wait a few seconds for results + +You'll see: +- ✅*Healthy** - Green indicator, all checks passed +- ⚠️*Warning** - Yellow indicator, minor issues detected +- ❌*Critical** - Red indicator, serious problems +- ❓*Unknown** - Gray indicator, unable to connect + +**If you see "Unknown"**: Check your endpoint URL and API key are correct. + +### Step 5: View Deployment Details + +1. Click on any deployment card +2. Review health metrics: + - Version information + - Database status and size + - Server load and disk space + - Security status (SSL/TLS) + - Last check timestamp + +### Step 6: Configure Automated Checks + +1. Go to*MokoDoliRelease → Setup** +2. Set*Health Check Interval**: 60 minutes (recommended) +3. Enable*Automatic Health Checks** +4. Click*Save** + +✅*Deployment Monitoring Setup Complete!** + +--- + +## Common Tasks Across Both Paths + +### Create a License Key + +1. Go to*MokoDoliRelease → Licenses → New License** +2. Fill in: + -*Label**: Customer Name - Product + -*License Key**: Auto-generated or custom + -*Product Type**: Dolibarr or Joomla + -*Contract Line**: Select from customer's service contract + -*Max Activations**: 3 (or as needed) + -*Expiry Date**: Based on contract duration +3. Click*Create** + +### Test License Authentication + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{"license_key":"YOUR-KEY","product_type":"dolibarr"}' \ + https://your-dolibarr.com/custom/mokodolirelease/api/authenticate_license.php +``` + +### Link to a Client + +1. Edit a deployment +2. Select a*Client** from the dropdown +3. Optionally link to a*Service Contract** +4. Save + +### Suspend a Service + +1. Open the deployment card +2. Click*Suspend Service** +3. Health checks will be disabled until resumed + +### Resume a Service + +1. Open the suspended deployment +2. Click*Resume Service** +3. Health checks resume immediately + +## Understanding Health Status + +| Status | Meaning | Action Required | +|--------|---------|-----------------| +| Healthy | All checks passed | None - monitor regularly | +| Warning | Minor issues detected | Review and plan maintenance | +| Critical | Serious problems | Immediate attention needed | +| Unknown | Cannot connect or check | Verify endpoint and credentials | + +## Next Steps + +- [Configure automated monitoring](configuration.md) +- [Set up push-based monitoring](remote-components.md) +- [Understand health metrics](health-monitoring.md) +- [Learn about deployment types](deployment-types.md) + +## Tips + +- **Start small**: Monitor 1-2 systems first +- **Test endpoints**: Verify API access before adding +- **Regular checks**: Run manual checks to validate configuration +- **Monitor dashboard**: Check daily for status changes +- **Use automation**: Enable cron for hands-free monitoring + +## Getting Help + +- **Documentation**: [Full User Manual](user-manual.md) +- **Troubleshooting**: [Common Issues](troubleshooting.md) +- **Support**: hello@mokoconsulting.tech + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/runbook.md b/MokoConsulting/MokoDoliRelease/runbook.md new file mode 100644 index 0000000..b2ac1a5 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/runbook.md @@ -0,0 +1,563 @@ +← [Home](Home) + +# Operations Runbook + +Comprehensive operational procedures for MokoDoliDeploy platform. + +## Daily Operations + +### Morning Checks (9:00 AM) + +**System Health Verification**: + +```bash +#!/bin/bash +# daily-health-check.sh + +echo "=== Daily Health Check: $(date) ===" + +# 1. Check system services +echo "\n1. Service Status:" +systemctl status apache2 | grep "Active:" +systemctl status mysql | grep "Active:" +systemctl status redis | grep "Active:" + +# 2. Check disk space +echo "\n2. Disk Space:" +df -h / | tail -1 +df -h /var | tail -1 + +# 3. Check database +echo "\n3. Database Status:" +mysql -e "SHOW SLAVE STATUS\G" | grep "Seconds_Behind_Master" +mysql -e "SELECT COUNT(*) as deployments FROM dolibarr.llx_mokodolideploy_deployment;" + +# 4. Check recent health checks +echo "\n4. Recent Health Checks:" +mysql -e "SELECT health_status, COUNT(*) as count FROM dolibarr.llx_mokodolideploy_deployment GROUP BY health_status;" + +# 5. Check error logs +echo "\n5. Recent Errors:" +tail -20 /var/log/apache2/error.log | grep -i "error\|critical" + +# 6. Check SLA compliance +echo "\n6. SLA Status:" +echo "Availability this month: $(calculate_availability)%" +echo "Downtime budget remaining: $(calculate_downtime_budget) minutes" +``` + +**Review Dashboards**: +1. Grafana: System metrics +2. Prometheus: Alerts +3. Application: Health summary +4. Support: Open tickets + +### Evening Checks (6:00 PM) + +```bash +# evening-check.sh + +# 1. Verify backups completed +ls -lh /backups/mokodolideploy/ | tail -5 + +# 2. Review day's incidents +cat /var/log/mokodolideploy/incidents-$(date +%Y-%m-%d).log + +# 3. Check scheduled maintenance +crontab -l | grep mokodolideploy + +# 4. Verify monitoring alerts +curl -s http://prometheus:9090/api/v1/alerts | jq '.data.alerts[] | select(.state=="firing")' +``` + +## Weekly Operations + +### Monday: Planning + +- Review last week's metrics +- Plan week's changes +- Schedule maintenance windows +- Update on-call calendar + +### Wednesday: Maintenance + +**Patch Management**: + +```bash +# Check for updates +apt update +apt list --upgradable | grep -i "php\|apache\|mysql" + +# Test in staging first +ssh staging-server << 'EOF' + apt upgrade -y + systemctl restart apache2 + systemctl restart mysql + # Run smoke tests + curl -f https://staging/custom/mokodolideploy/ +EOF + +# Apply to production (off-hours) +# Document in change log +``` + +### Friday: Review + +- Review week's incidents +- Update documentation +- Plan next week +- Generate weekly report + +## Monthly Operations + +### First Week: Performance Review + +```bash +# Generate monthly performance report +./scripts/generate-monthly-report.sh + +# Review metrics: +# - Availability % +# - Performance trends +# - Error rates +# - Capacity utilization +``` + +### Second Week: Security Review + +- Review access logs +- Check for security updates +- Run vulnerability scans +- Update security documentation + +### Third Week: Capacity Planning + +- Analyze growth trends +- Forecast resource needs +- Plan capacity additions +- Update capacity plan + +### Fourth Week: DR Testing + +- Test backup restoration +- Verify failover procedures +- Update DR documentation +- Conduct tabletop exercise + +## Incident Response Procedures + +### P1 - Critical Incident + +**Immediate Actions** (0-15 minutes): + +```bash +# 1. Acknowledge incident +echo "P1 Incident acknowledged at $(date)" >> /var/log/incidents.log + +# 2. Notify stakeholders +./scripts/notify-incident.sh --severity P1 --message "System outage detected" + +# 3. Start war room +# Conference bridge: +1-XXX-XXX-XXXX, PIN: XXXX + +# 4. Collect initial data +./scripts/collect-diagnostics.sh + +# 5. Begin investigation +tail -f /var/log/apache2/error.log & +tail -f /var/log/mysql/error.log & +top -b -n 1 +``` + +**Investigation** (15-60 minutes): + +```bash +# Check common issues + +# 1. Database connectivity +mysql -e "SELECT 1" || echo "Database connection failed!" + +# 2. Disk space +df -h | grep -E "9[0-9]%|100%" + +# 3. Memory +free -m + +# 4. CPU load +uptime + +# 5. Network +ping -c 3 8.8.8.8 + +# 6. Application logs +grep -i "error\|exception\|fatal" /var/log/apache2/error.log | tail -50 +``` + +**Resolution Actions**: + +```bash +# Common fixes + +# Restart services +systemctl restart apache2 +systemctl restart mysql + +# Clear cache +rm -rf /var/www/dolibarr/documents/install.lock +redis-cli FLUSHALL + +# Fix disk space +./scripts/cleanup-logs.sh +./scripts/archive-old-data.sh + +# Database recovery +mysql < /backups/latest/database.sql +``` + +**Post-Resolution** (Within 2 hours): + +```bash +# 1. Verify resolution +curl -f https://monitoring.company.com/custom/mokodolideploy/ + +# 2. Update status page +./scripts/update-status.sh --status "Resolved" + +# 3. Send all-clear notification +./scripts/notify-incident.sh --severity P1 --message "Incident resolved" + +# 4. Schedule post-mortem +calendar add --title "Post-Mortem: INC-$(date +%Y%m%d)" --date "+1 day" + +# 5. Document incident +./scripts/create-incident-report.sh --id "INC-$(date +%Y%m%d)" +``` + +### P2 - High Priority Incident + +**Response Timeline**: Within 1 hour + +**Actions**: +1. Acknowledge and assign +2. Investigate root cause +3. Implement workaround if available +4. Develop permanent fix +5. Test and deploy fix +6. Verify resolution +7. Document incident + +### Rollback Procedures + +**Application Rollback**: + +```bash +# 1. Identify last known good version +git log --oneline -10 + +# 2. Backup current state +tar -czf /backups/rollback-$(date +%Y%m%d-%H%M%S).tar.gz \ + */var/www/dolibarr/htdocs/custom/mokodolideploy + +# 3. Checkout previous version +cd /var/www/dolibarr/htdocs/custom/mokodolideploy +git checkout + +# 4. Clear cache +rm -rf /var/www/dolibarr/documents/install.lock + +# 5. Restart services +systemctl restart apache2 + +# 6. Verify rollback +curl -f https://monitoring.company.com/custom/mokodolideploy/ +``` + +**Database Rollback**: + +```bash +# 1. Stop application +systemctl stop apache2 + +# 2. Backup current database +mysqldump dolibarr > /backups/pre-rollback-$(date +%Y%m%d).sql + +# 3. Restore from backup +mysql dolibarr < /backups/last-known-good.sql + +# 4. Verify restoration +mysql -e "SELECT COUNT(*) FROM dolibarr.llx_mokodolideploy_deployment;" + +# 5. Start application +systemctl start apache2 +``` + +## Maintenance Procedures + +### Planned Maintenance + +**Pre-Maintenance** (T-48 hours): + +```bash +# 1. Create maintenance announcement +cat > maintenance-notice.txt << 'EOF' +Scheduled Maintenance Notice + +Start: 2025-01-15 02:00 AM UTC +End: 2025-01-15 06:00 AM UTC +Duration: 4 hours +Impact: Brief service interruption (< 5 minutes) + +Activities: +- Database optimization +- Security updates +- Performance improvements + +Status updates: https://status.company.com +EOF + +# 2. Send notification +./scripts/send-maintenance-notice.sh maintenance-notice.txt + +# 3. Update status page +./scripts/update-status.sh --status "Scheduled Maintenance" \ + --start "2025-01-15 02:00 UTC" \ + --end "2025-01-15 06:00 UTC" +``` + +**During Maintenance**: + +```bash +#!/bin/bash +# maintenance-script.sh + +# 1. Enable maintenance mode +touch /var/www/dolibarr/documents/maintenance.lock + +# 2. Backup current state +./scripts/backup-all.sh + +# 3. Perform maintenance tasks +apt update && apt upgrade -y +./scripts/optimize-database.sh +./scripts/cleanup-old-data.sh + +# 4. Test functionality +./scripts/smoke-tests.sh + +# 5. Disable maintenance mode +rm /var/www/dolibarr/documents/maintenance.lock + +# 6. Verify services +curl -f https://monitoring.company.com/custom/mokodolideploy/ +``` + +**Post-Maintenance**: + +```bash +# 1. Send completion notice +./scripts/send-maintenance-notice.sh --status complete + +# 2. Monitor for issues +./scripts/monitor-post-maintenance.sh --duration 2h + +# 3. Document changes +git commit -m "Maintenance: $(date +%Y-%m-%d) - Security updates and optimization" +``` + +### Emergency Maintenance + +**When Required**: +- Critical security vulnerability +- Data corruption risk +- System instability + +**Procedure**: +1. Emergency CAB approval +2. Immediate stakeholder notification +3. Expedited change process +4. Rollback plan ready +5. Enhanced monitoring post-change + +## Backup and Recovery + +### Backup Procedures + +**Daily Full Backup**: + +```bash +#!/bin/bash +# daily-backup.sh + +DATE=$(date +%Y%m%d_%H%M%S) +BACKUP_DIR="/backups/mokodolideploy" + +# 1. Database backup +mysqldump --single-transaction \ + --routines --triggers \ + --databases dolibarr \ + | gzip > $BACKUP_DIR/db_$DATE.sql.gz + +# 2. Files backup +tar -czf $BACKUP_DIR/files_$DATE.tar.gz \ + */var/www/dolibarr/htdocs/custom/mokodolideploy \ + */etc/apache2/sites-available/ \ + */etc/mysql/my.cnf + +# 3. Verify backups +gunzip -t $BACKUP_DIR/db_$DATE.sql.gz || echo "Database backup corrupt!" +tar -tzf $BACKUP_DIR/files_$DATE.tar.gz > /dev/null || echo "Files backup corrupt!" + +# 4. Upload to remote storage +aws s3 sync $BACKUP_DIR/ s3://backups/mokodolideploy/ + +# 5. Clean old local backups (keep 7 days) +find $BACKUP_DIR -name "*.gz" -mtime +7 -delete + +# 6. Log backup status +echo "$(date): Backup completed successfully" >> /var/log/backup.log +``` + +### Recovery Procedures + +**Full System Recovery**: + +```bash +#!/bin/bash +# full-recovery.sh + +# 1. Install base system +apt update +apt install -y apache2 mysql-server php php-mysql redis-server + +# 2. Restore database +gunzip < /backups/latest/db.sql.gz | mysql + +# 3. Restore files +cd /var/www/dolibarr/htdocs/custom/ +tar -xzf /backups/latest/files.tar.gz + +# 4. Set permissions +chown -R www-data:www-data mokodolideploy +chmod -R 755 mokodolideploy + +# 5. Restore configuration +cp /backups/latest/apache-config /etc/apache2/sites-available/ +cp /backups/latest/my.cnf /etc/mysql/ + +# 6. Start services +systemctl start mysql +systemctl start apache2 +systemctl start redis + +# 7. Verify recovery +./scripts/verify-system.sh + +# 8. Resume monitoring +./scripts/enable-monitoring.sh +``` + +**Point-in-Time Recovery**: + +```bash +# Restore database to specific point +# Requires transaction logs + +mysql stop +rm -rf /var/lib/mysql/dolibarr/ +mysql start + +# Restore base backup +mysql < /backups/full-backup-20250108.sql + +# Apply transaction logs +for log in /backups/binlogs/mysql-bin.*; do + mysqlbinlog $log | mysql +done + +# Stop at specific timestamp +mysqlbinlog --stop-datetime="2025-01-08 14:30:00" \ + */backups/binlogs/mysql-bin.000042 | mysql +``` + +## Monitoring and Alerting + +### Alert Response Procedures + +**Critical Alerts**: +- **Disk space > 90%**: Clear logs, archive data +- **Database down**: Restart MySQL, check logs +- **High CPU**: Identify process, optimize or scale +- **Memory exhausted**: Restart services, increase RAM + +**Alert Acknowledgment**: + +```bash +# Acknowledge alert in monitoring system +curl -X POST http://prometheus:9090/api/v1/alerts/silence \ + -d '{"matchers":[{"name":"alertname","value":"HighCPU"}],"startsAt":"2025-01-08T14:00:00Z","endsAt":"2025-01-08T16:00:00Z","comment":"Investigating"}' +``` + +### Health Check Troubleshooting + +**Health Check Failures**: + +```bash +# Diagnose failed health checks + +# 1. Test endpoint manually +curl -v https://remote-system.com/api/health + +# 2. Check DNS resolution +nslookup remote-system.com + +# 3. Check network connectivity +traceroute remote-system.com + +# 4. Verify SSL certificate +openssl s_client -connect remote-system.com:443 -showcerts + +# 5. Check API credentials +# Verify API key is valid and not expired + +# 6. Review logs +grep "remote-system.com" /var/log/mokodolideploy/*.log +``` + +## On-Call Procedures + +### On-Call Rotation + +- **Primary**: Responds to all alerts +- **Secondary**: Backup for primary +- **Escalation**: Management + +### On-Call Responsibilities + +- Monitor alerts 24/7 +- Respond within SLA (15 min for P1) +- Escalate if needed +- Document all actions +- Hand off to next shift + +### Escalation Matrix + +| Level | Role | Contact | When to Escalate | +|-------|------|---------|------------------| +| L1 | On-Call Engineer | +1-XXX-XXX-XXXX | Initial response | +| L2 | Senior Engineer | +1-XXX-XXX-XXXX | Complex issues | +| L3 | Engineering Manager | +1-XXX-XXX-XXXX | Major incidents | +| L4 | CTO | +1-XXX-XXX-XXXX | Business impact | + +## Next Steps + +- [Enterprise Deployment](enterprise-deployment.md) +- [SLA Management](sla-management.md) +- [Disaster Recovery Plan](disaster-recovery.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/sla-management.-.-.md b/MokoConsulting/MokoDoliRelease/sla-management.-.-.md new file mode 100644 index 0000000..bb20f86 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/sla-management.-.-.md @@ -0,0 +1,456 @@ +← [Home](Home) + +# SLA Management + +Service Level Agreement management and monitoring for MokoDoliDeploy. + +## Service Level Agreements + +### Availability SLA + +**Target**: 99.9% uptime (monthly) + +**Measurement Period**: Calendar month + +**Downtime Budget**: +- Monthly: 43.2 minutes +- Quarterly: 129.6 minutes +- Annually: 8.76 hours + +**Exclusions**: +- Planned maintenance (with 48-hour notice) +- Force majeure events +- Third-party service failures +- Customer-caused incidents + +**Calculation**: +``` +Availability % = (Total Minutes - Downtime Minutes) / Total Minutes × 100 +``` + +**SLA Credits**: +| Availability | Service Credit | +|--------------|----------------| +| 99.9% - 99.0% | 10% | +| 99.0% - 98.0% | 25% | +| < 98.0% | 50% | + +### Performance SLA + +**Dashboard Load Time**: < 2 seconds (95th percentile) + +**API Response Time**: < 500ms (95th percentile) + +**Health Check Completion**: < 5 seconds per deployment + +**Measurement**: Synthetic monitoring + RUM (Real User Monitoring) + +**Performance Tiers**: +| Metric | Target | Warning | Critical | +|--------|--------|---------|----------| +| Dashboard | < 2s | 2-3s | > 3s | +| API | < 500ms | 500ms-1s | > 1s | +| Health Check | < 5s | 5-10s | > 10s | + +### Support SLA + +**Response Time Targets**: + +| Severity | Description | Response Time | Resolution Time | +|----------|-------------|---------------|-----------------| +| P1 - Critical | System down, data loss | 15 minutes | 4 hours | +| P2 - High | Major function unavailable | 1 hour | 8 hours | +| P3 - Medium | Function degraded | 4 hours | 2 business days | +| P4 - Low | Minor issue, question | 1 business day | 5 business days | + +**Support Hours**: +- **Business Hours**: Mon-Fri, 8 AM - 6 PM (Local Time) +- **After Hours**: Emergency P1/P2 only +- **Holidays**: Emergency P1 only + +**Support Channels**: +- Email: support@mokoconsulting.tech +- Phone: +1-XXX-XXX-XXXX (P1/P2) +- Portal: https://support.mokoconsulting.tech + +### Data Retention SLA + +**Backup Frequency**: +- Full backup: Daily +- Incremental: Every 6 hours +- Transaction logs: Continuous + +**Backup Retention**: +- Daily backups: 30 days +- Weekly backups: 12 weeks +- Monthly backups: 12 months +- Yearly backups: 7 years + +**Recovery Time Objective (RTO)**: 4 hours + +**Recovery Point Objective (RPO)**: 15 minutes + +## SLA Monitoring + +### Availability Monitoring + +**Uptime Checks**: +```bash +# External monitoring (every minute) +curl -f https://monitoring.company.com/custom/mokodolideploy/api/health || alert_downtime + +# Internal health check +#!/bin/bash +check_service() { + systemctl is-active apache2 || return 1 + systemctl is-active mysql || return 1 + curl -sf http://localhost/custom/mokodolideploy/ || return 1 + return 0 +} + +if ! check_service; then + echo "Service degraded at $(date)" >> /var/log/sla-violations.log + send_alert "SLA: Service degraded" +fi +``` + +**Availability Dashboard**: +``` +Current Month Availability: 99.95% +Downtime This Month: 21.6 minutes +Remaining Budget: 21.6 minutes +Status: ✓ Meeting SLA + +Last 3 Months: +- December: 99.98% ✓ +- November: 99.91% ✓ +- October: 99.85% ⚠ (SLA Credit: 10%) +``` + +### Performance Monitoring + +**Application Performance Monitoring (APM)**: + +```php +// Track performance metrics +function trackPerformance($operation, $duration) { + global $redis; + + $key = "perf:$operation:" . date('Y-m-d-H'); + $redis->rPush($key, $duration); + $redis->expire($key, 86400 30); // 30 days + + // Calculate percentiles + $values = $redis->lRange($key, 0, -1); + sort($values); + $p95 = $values[floor(count($values) 0.95)]; + + // Alert if exceeding SLA + if ($operation === 'dashboard_load' && $p95 > 2000) { + alert_sla_breach('dashboard_load', $p95, 2000); + } +} +``` + +**Synthetic Monitoring**: + +```javascript +// Selenium test for dashboard load time +describe('Dashboard Performance', function() { + it('should load within 2 seconds', async function() { + const startTime = Date.now(); + await browser.get('https://monitoring.company.com/custom/mokodolideploy/'); + await browser.wait(EC.presenceOf(element(by.id('dashboard'))), 10000); + const loadTime = Date.now() - startTime; + + expect(loadTime).toBeLessThan(2000); + + // Log for SLA tracking + logMetric('dashboard_load_time', loadTime); + }); +}); +``` + +### SLA Reporting + +**Monthly SLA Report Template**: + +```markdown +## Monthly SLA Report: January 2025 + +### Executive Summary +- Overall SLA Compliance: 99.95% +- All performance targets met +- Zero P1 incidents +- Customer satisfaction: 4.8/5 + +### Availability +- Target: 99.9% +- Actual: 99.95% +- Status: ✓ Met +- Downtime: 21.6 minutes +- Budget Remaining: 21.6 minutes + +### Performance +- Dashboard Load: 1.2s (target: <2s) ✓ +- API Response: 245ms (target: <500ms) ✓ +- Health Check: 3.1s (target: <5s) ✓ + +### Support +- P1 Incidents: 0 +- P2 Incidents: 2 (both resolved within SLA) +- P3 Incidents: 15 (14 within SLA) +- P4 Requests: 45 (all within SLA) +- Average Resolution Time: P2: 4.5h, P3: 1.2d + +### Incidents +1. INC-2025-001 (P2): Database connection pool exhaustion + - Impact: 15 minutes degraded performance + - Root Cause: Sudden traffic spike + - Resolution: Increased pool size + - Prevention: Added auto-scaling + +2. INC-2025-002 (P2): Monitoring server disk full + - Impact: 30 minutes health checks paused + - Root Cause: Log rotation failure + - Resolution: Cleared logs, fixed rotation + - Prevention: Added disk space monitoring + +### Improvements +- Implemented auto-scaling for traffic spikes +- Enhanced monitoring for disk space +- Updated runbook procedures + +### Next Month Focus +- Reduce P3 incident count +- Improve dashboard load time to <1.5s +- Implement predictive monitoring +``` + +### Automated SLA Tracking + +**Prometheus Queries**: + +```yaml +# Availability tracking +- record: sla:availability:monthly + expr: | + ( + (count(up{job="mokodolideploy"} == 1) 60) + */ + (count(up{job="mokodolideploy"}) 60) + ) 100 + +# Performance tracking +- record: sla:dashboard_load:p95 + expr: | + histogram_quantile(0.95, + rate(http_request_duration_seconds_bucket{endpoint="/dashboard"}[5m]) + ) + +# Alert on SLA breach +- alert: SLAAvailabilityBreach + expr: sla:availability:monthly < 99.9 + for: 1m + labels: + severity: critical + annotations: + summary: "Monthly availability below SLA target" + description: "Current: {{ $value }}%, Target: 99.9%" +``` + +## Incident Management + +### Incident Severity Classification + +**P1 - Critical**: +- Complete service outage +- Data loss or corruption +- Security breach +- **Response**: Immediate, 24/7 +- **Communication**: Every 30 minutes + +**P2 - High**: +- Major feature unavailable +- Significant performance degradation +- Multiple deployments failing +- **Response**: 1 hour, business hours extended +- **Communication**: Every 2 hours + +**P3 - Medium**: +- Minor feature degraded +- Single deployment failing +- Workaround available +- **Response**: 4 hours, business hours +- **Communication**: Daily updates + +**P4 - Low**: +- Cosmetic issues +- Feature requests +- Questions +- **Response**: 1 business day +- **Communication**: As needed + +### Incident Response Process + +``` +1. Detection + ↓ +2. Triage (Severity Classification) + ↓ +3. Notification (Stakeholders) + ↓ +4. Investigation (Root Cause Analysis) + ↓ +5. Resolution (Fix Applied) + ↓ +6. Verification (Testing) + ↓ +7. Communication (Status Update) + ↓ +8. Post-Mortem (Lessons Learned) +``` + +### Incident Communication + +**Status Page Template**: + +```markdown +## Incident: Database Performance Degradation + +**Status**: Investigating +**Severity**: P2 +**Started**: 2025-01-08 14:32 UTC +**Last Updated**: 2025-01-08 15:15 UTC + +### Current Status +We are investigating reports of slow dashboard loading times. Health checks are functioning but with elevated response times. + +### Impact +- Dashboard load times: 5-8 seconds (normally <2s) +- Health check delays: 3-5 minutes +- Affected users: All users +- Deployments monitored: Not affected + +### Updates +**15:15 UTC**: Root cause identified - database query optimization needed. Implementing fix. + +**14:45 UTC**: Investigation ongoing. Database server CPU at 85%. + +**14:32 UTC**: Initial report received. Starting investigation. + +### Next Update +Expected at 15:45 UTC or when resolved. +``` + +### Post-Incident Review + +**Template**: + +```markdown +## Post-Incident Review: INC-2025-003 + +**Incident**: Database Performance Degradation +**Date**: 2025-01-08 +**Duration**: 2 hours 15 minutes +**Severity**: P2 +**Impact**: Dashboard load times increased to 5-8 seconds + +### Timeline +- 14:32: Alert triggered - slow dashboard response +- 14:45: Investigation begun +- 15:15: Root cause identified +- 16:20: Fix deployed +- 16:47: Verified resolved + +### Root Cause +Health data table grew to 500K rows without proper indexing. Full table scans caused query slowdowns. + +### Resolution +1. Added composite index on (last_health_check, health_status) +2. Implemented data archival for records > 90 days +3. Optimized slow queries + +### What Went Well +- Quick detection via automated monitoring +- Clear incident communication +- Effective collaboration between teams + +### What Went Wrong +- No alerting on table size growth +- Missing index identified earlier in development +- Data retention policy not enforced + +### Action Items +- [ ] Implement table size monitoring (Owner: DevOps, Due: 2025-01-15) +- [ ] Add database performance tests to CI/CD (Owner: Dev, Due: 2025-01-22) +- [ ] Automate data archival (Owner: Dev, Due: 2025-01-29) +- [ ] Review all database indexes (Owner: DBA, Due: 2025-02-05) +- [ ] Update runbook with archival procedures (Owner: Ops, Due: 2025-01-12) + +### Lessons Learned +1. Proactive monitoring of database metrics critical +2. Data retention policies must be automated +3. Performance testing should include large datasets +``` + +## Service Improvement + +### Continuous Improvement Process + +**Monthly Review Cycle**: +1. Collect metrics and feedback +2. Identify improvement opportunities +3. Prioritize initiatives +4. Implement changes +5. Measure impact +6. Document lessons learned + +### Key Performance Indicators (KPIs) + +**Service KPIs**: +- Availability % +- Performance metrics (p50, p95, p99) +- Error rate +- Mean Time To Detect (MTTD) +- Mean Time To Resolve (MTTR) + +**Business KPIs**: +- Number of deployments monitored +- Health check success rate +- Customer satisfaction score +- SLA compliance rate +- Cost per deployment + +**Operational KPIs**: +- Incident count by severity +- Change success rate +- Backup success rate +- Security vulnerability count +- Technical debt ratio + +### SLA Improvement Targets + +**Year-over-Year Goals**: + +| Metric | 2024 Baseline | 2025 Target | 2026 Target | +|--------|---------------|-------------|-------------| +| Availability | 99.5% | 99.9% | 99.95% | +| Dashboard Load | 2.5s | 2.0s | 1.5s | +| MTTR (P1) | 6h | 4h | 2h | +| MTTR (P2) | 12h | 8h | 6h | +| Customer Sat | 4.2/5 | 4.5/5 | 4.8/5 | + +## Next Steps + +- [Incident Response Runbook](runbook.md) +- [Performance Tuning](performance-tuning.md) +- [Capacity Planning](capacity-planning.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/troubleshooting.md b/MokoConsulting/MokoDoliRelease/troubleshooting.md new file mode 100644 index 0000000..09abe9e --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/troubleshooting.md @@ -0,0 +1,299 @@ +← [Home](Home) + +# Troubleshooting Guide + +Common issues and solutions for MokoDoliDeploy module. + +## Installation Issues + +### Module Not Appearing in Module List + +**Problem**: Module doesn't show up after installation. + +**Solutions**: +1. Verify directory name is exactly `mokodolideploy` +2. Check file permissions: `chmod -R 755 mokodolideploy` +3. Clear Dolibarr cache: Delete `documents/install.lock` +4. Refresh browser cache: Ctrl+F5 + +### Database Error During Activation + +**Problem**: SQL error when activating module. + +**Solutions**: +1. Verify database user has CREATE TABLE privileges +2. Check MySQL/MariaDB version (5.7+ required) +3. Review error in `documents/dolibarr.log` +4. Manually run SQL: `src/sql/llx_mokodolideploy_deployment.sql` + +### Permission Denied Errors + +**Problem**: Can't write files or access directories. + +**Solution**: +```bash +cd /path/to/dolibarr/htdocs/custom/mokodolideploy +chown -R www-data:www-data . +find . -type d -exec chmod 755 {} \; +find . -type f -exec chmod 644 {} \; +``` + +## Health Check Issues + +### Always Shows "Unknown" Status + +**Problem**: Deployments never get proper health status. + +**Causes & Solutions**: + +1.*Firewall blocking outbound connections** + - Check firewall rules + - Allow HTTPS traffic (port 443) + +2.*Invalid API endpoint** + - Test endpoint manually: `curl -I https://endpoint-url` + - Verify URL format matches deployment type + +3.*Authentication failure** + - Verify API key is correct + - Check API permissions on remote system + - Regenerate API key if needed + +4.*SSL certificate issues** + - For self-signed certs, disable SSL verification in setup + - Install proper certificate on remote system + +### Health Check Times Out + +**Problem**: Health checks never complete, timeout errors. + +**Solutions**: +1. Increase timeout:*Setup → API Timeout** (try 60 seconds) +2. Check remote system performance +3. Verify network latency: `ping remote-host` +4. Review remote system logs for slow responses + +### Cron Jobs Not Running + +**Problem**: Automated health checks don't execute. + +**Diagnosis**: +```bash +# Check if cron job exists +crontab -l | grep mokodolideploy + +# Check cron logs +grep CRON /var/log/syslog + +# Test manual execution +php /path/to/mokodolideploy/scripts/cron/health_check.php +``` + +**Solutions**: +1. Verify cron job is added to correct user's crontab +2. Check PHP CLI path: `which php` +3. Ensure script has execute permissions +4. Review script output for errors + +## Connection Issues + +### Cannot Connect to Remote Dolibarr + +**Problem**: Dolibarr health checks fail. + +**Checklist**: +- [ ] API module enabled on remote Dolibarr +- [ ] DOLAPIKEY generated and active +- [ ] Endpoint URL correct: `/api/index.php` +- [ ] API key has required permissions +- [ ] Remote Dolibarr accessible from monitoring server + +**Test Connection**: +```bash +curl -H "DOLAPIKEY: your-key" \ + https://remote-dolibarr.com/api/index.php/status +``` + +### Cannot Connect to Joomla/Panopticon + +**Problem**: Joomla health checks fail. + +**Checklist**: +- [ ] Akeeba Panopticon plugin installed +- [ ] Panopticon API enabled +- [ ] Bearer token generated +- [ ] Endpoint URL correct: `/api/panopticon/v1/info` +- [ ] Remote site allows API connections + +**Test Connection**: +```bash +curl -H "Authorization: Bearer your-token" \ + https://joomla-site.com/api/panopticon/v1/info +``` + +### Cannot Connect to Live Chat Helper + +**Problem**: Chat system health checks fail. + +**Solutions**: +1. Verify API endpoint URL +2. Check authentication token +3. Confirm API is enabled on chat system +4. Test with: `curl -H "Authorization: Bearer token" endpoint-url` + +## Performance Issues + +### Dashboard Loads Slowly + +**Problem**: Dashboard takes > 5 seconds to load. + +**Solutions**: +1.*Optimize database**: +```sql +OPTIMIZE TABLE llx_mokodolideploy_deployment; +``` + +2.*Add indexes**: +```sql +ALTER TABLE llx_mokodolideploy_deployment +ADD INDEX idx_status (health_status); +``` + +3.*Reduce check frequency** for less critical systems + +4.*Enable caching** in Dolibarr configuration + +### High Server Load During Health Checks + +**Problem**: Server load spikes during automated checks. + +**Solutions**: +1. Stagger health checks: Don't check all at once +2. Reduce concurrent checks: Limit to 5-10 parallel +3. Increase check interval: 120-240 minutes +4. Optimize remote system response time + +## API Issues + +### API Returns 401 Unauthorized + +**Problem**: Push API rejects requests. + +**Solutions**: +1. Verify DOLAPIKEY in request header +2. Check API key is active in Dolibarr +3. Ensure API module is enabled +4. Regenerate API key if needed + +### API Rate Limit Exceeded + +**Problem**: 429 Too Many Requests error. + +**Solution**: +``` +Rate limit: 60 requests/hour per deployment +Wait for limit reset (check X-RateLimit-Reset header) +Reduce report frequency from remote systems +``` + +### JSON Parse Error + +**Problem**: Invalid JSON in API response. + +**Solutions**: +1. Validate JSON format: Use JSONLint +2. Check for special characters in data +3. Ensure UTF-8 encoding +4. Review API documentation for expected format + +## Data Issues + +### Health Data Not Saving + +**Problem**: Health checks run but data not stored. + +**Diagnosis**: +```php +// Check PHP error log +tail -f /var/log/php-errors.log + +// Enable Dolibarr debug mode +// In conf.php: +$dolibarr_main_prod = 0; +``` + +**Solutions**: +1. Verify database write permissions +2. Check disk space: `df -h` +3. Review error logs for database issues +4. Test manual save operation + +### Old Deployments Not Cleaning Up + +**Problem**: Deleted deployments still appear. + +**Solution**: +```sql +-- Clean up orphaned records +DELETE FROM llx_mokodolideploy_deployment +WHERE date_creation < DATE_SUB(NOW(), INTERVAL 6 MONTH) +AND status = 'deleted'; +``` + +## UI Issues + +### Dashboard Not Updating + +**Problem**: Dashboard shows stale data. + +**Solutions**: +1. Clear browser cache: Ctrl+F5 +2. Check browser console for JavaScript errors +3. Disable browser extensions +4. Try different browser + +### Buttons Not Working + +**Problem**: Click events not responding. + +**Solutions**: +1. Check JavaScript console for errors +2. Verify jQuery is loaded +3. Clear browser cache +4. Disable conflicting browser extensions + +## Getting Help + +If issues persist: + +1.*Check logs**: + - Dolibarr: `documents/dolibarr.log` + - PHP: `/var/log/php-errors.log` + - Web server: `/var/log/apache2/error.log` or `/var/log/nginx/error.log` + +2.*Enable debug mode** in Dolibarr + +3.*Collect information**: + - Dolibarr version + - PHP version + - Module version + - Error messages + - Steps to reproduce + +4.*Contact support**: + - Email: hello@mokoconsulting.tech + - Include: Version info, logs, error messages + +## Next Steps + +- [FAQ](faq.md) +- [Configuration Guide](configuration.md) +- [API Reference](api-reference.md) + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliRelease/update-server.-.-.md b/MokoConsulting/MokoDoliRelease/update-server.-.-.md new file mode 100644 index 0000000..5c3b695 --- /dev/null +++ b/MokoConsulting/MokoDoliRelease/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliRelease/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliRelease](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliRelease) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/ADMIN_GUIDE.md b/MokoConsulting/MokoDoliSign/ADMIN_GUIDE.md new file mode 100644 index 0000000..5995c2f --- /dev/null +++ b/MokoConsulting/MokoDoliSign/ADMIN_GUIDE.md @@ -0,0 +1,673 @@ +← [Home](Home) + +# MokoDoliSign Administrator Guide + +## Table of Contents + +1. [Installation & Setup](#installation--setup) +2. [Configuration](#configuration) +3. [User Management](#user-management) +4. [Monitoring](#monitoring) +5. [Maintenance](#maintenance) +6. [Backup & Recovery](#backup--recovery) +7. [Security](#security) +8. [Performance Tuning](#performance-tuning) + +## Installation & Setup + +### Pre-Installation Checklist + +- [ ] Dolibarr 14.0+ installed +- [ ] PHP 7.4+ with required extensions +- [ ] MySQL 5.7+ or MariaDB 10.3+ +- [ ] SSL/TLS certificate installed +- [ ] Email (SMTP) configured +- [ ] Sufficient disk space (1GB minimum) +- [ ] Cron access available + +### Installation Steps + +1. **Download Module** + ```bash + cd /path/to/dolibarr/htdocs/custom/ + git clone https://github.com/mokoconsulting-tech/MokoDoliSign.git mokodolisign + # or upload ZIP and extract + ``` + +2. **Set Permissions** + ```bash + chown -R www-data:www-data mokodolisign/ + chmod -R 755 mokodolisign/ + ``` + +3. **Enable Module** + - Log in as administrator + - Navigate to Home → Setup → Modules/Applications + - Search for "MokoDoliSign" + - Click "Activate" + - Database tables created automatically + +4. **Verify Installation** + - Check for "MokoDoliSign" in main menu + - Verify database tables exist: + - llx_mokodolisign_request + - llx_mokodolisign_signer + - llx_mokodolisign_event + +### Post-Installation + +1. **Configure Permissions** (see User Management) +2. **Set Up Cron Jobs** (see Maintenance) +3. **Configure Email** (see Configuration) +4. **Test System** (create test request) + +## Configuration + +### Module Settings + +Access: Home → MokoDoliSign → Setup + +### Core Settings + +#### Document Certification Mode (DCM) +``` +MOKODOLISIGN_REQUIRE_DCM = 1 +``` +- Enforces document certification +- Required for legal compliance +- **Recommendation**: Keep enabled + +#### Certificate QR Verification +``` +MOKODOLISIGN_CERT_QR_VERIFY = 1 +``` +- Adds QR code to certificates +- Enables quick verification +- **Recommendation**: Enable for public documents + +#### Consent Mode +``` +MOKODOLISIGN_CONSENT_MODE = implicit|explicit +``` +- **implicit**: Consent implied by signing +- **explicit**: Requires separate consent checkbox +- **Recommendation**: Use explicit for GDPR compliance + +#### OTP Mode +``` +MOKODOLISIGN_OTP_DEFAULT_MODE = smart|always|never +``` +- **smart**: OTP for high-value requests +- **always**: OTP required for all +- **never**: No OTP +- **Recommendation**: Use smart for balance + +### Default Verification Settings + +``` +MOKODOLISIGN_DEFAULT_REQUIRE_SELFIE = 0 +MOKODOLISIGN_DEFAULT_REQUIRE_ID = 0 +MOKODOLISIGN_DEFAULT_REQUIRE_INITIALS_EACH_PAGE = 0 +``` + +Set defaults for new requests. Can be overridden per request. + +### Email Settings + +``` +MOKODOLISIGN_EMAIL_ATTACH_LIMIT_MB = 15 +``` + +Maximum attachment size for email notifications. + +### File Storage + +Documents stored in: +``` +/dolibarr/documents/mokodolisign/ +``` + +Structure: +``` +mokodolisign/ +├── SIG-000001/ +│ ├── agreement.pdf +│ └── verification/ +│ ├── selfie_123.png +│ └── id_456.png +├── SIG-000002/ +└── ... +``` + +### Email Templates + +Customize email templates: + +1. Navigate to email configuration +2. Locate MokoDoliSign templates +3. Edit subject and body +4. Use variables: + - `__SIGNER_FIRSTNAME__` + - `__SIGNER_LASTNAME__` + - `__DOCUMENT_TITLE__` + - `__SIGNING_URL__` + - `__EXPIRY_DATE__` + +## User Management + +### Permission Levels + +| Permission | Description | Typical Users | +|------------|-------------|---------------| +| Read | View requests and history | All users | +| Create | Create new requests | Managers, HR | +| Write | Modify existing requests | Managers | +| Delete | Delete draft requests | Managers | +| Admin | Full configuration access | Administrators | + +### Assigning Permissions + +1. Home → Setup → Users & Groups +2. Select user or group +3. Navigate to "Permissions" tab +4. Find "MokoDoliSign" section +5. Check appropriate permissions +6. Save + +### User Groups + +Recommended groups: + +**Signature Managers** +- Read, Create, Write +- Can manage signature workflows + +**Signature Administrators** +- All permissions including Admin +- Can configure module settings + +**Auditors** +- Read only +- Can view audit trails + +### Best Practices + +1. **Principle of Least Privilege**: Only grant necessary permissions +2. **Regular Audits**: Review user access quarterly +3. **Deactivate Promptly**: Remove access when users leave +4. **Use Groups**: Manage permissions via groups +5. **Document Policies**: Maintain access control documentation + +## Monitoring + +### Dashboard Metrics + +Access: MokoDoliSign → Requests → List + +Monitor: +- Total requests +- Pending signatures +- Completion rate +- Average time to completion +- Decline rate + +### Event Log + +Access: Individual request → Events tab + +Review: +- All actions and timestamps +- IP addresses +- Geolocation data +- User agents +- Verification photos + +### Email Delivery + +Monitor: +- Dolibarr email logs +- SMTP server logs +- Bounce messages +- Spam reports + +### System Health + +Check regularly: +- Database size +- File storage usage +- Cron job execution +- Error logs +- Performance metrics + +### Alerts to Monitor + +Set up alerts for: +- Failed email deliveries +- High decline rates +- Expired requests +- Cron job failures +- Storage space warnings + +## Maintenance + +### Cron Jobs + +#### Setup + +Add to system crontab: + +```bash +# As www-data or appropriate user +crontab -e +``` + +Add lines: + +```bash +# MokoDoliSign - Expire old requests +0 2 * * * cd /var/www/dolibarr/htdocs && php custom/mokodolisign/src/cron/expire.php >> /var/log/mokodolisign_expire.log 2>&1 + +# MokoDoliSign - Send reminders +0 8 * * * cd /var/www/dolibarr/htdocs && php custom/mokodolisign/src/cron/remind.php >> /var/log/mokodolisign_remind.log 2>&1 + +# MokoDoliSign - Purge old data +0 3 * * 0 cd /var/www/dolibarr/htdocs && php custom/mokodolisign/src/cron/purge.php >> /var/log/mokodolisign_purge.log 2>&1 +``` + +#### Monitoring Cron + +Check logs: +```bash +tail -f /var/log/mokodolisign_*.log +``` + +Verify execution: +```bash +grep "mokodolisign" /var/log/syslog +``` + +### Database Maintenance + +#### Regular Tasks + +```sql +-- Optimize tables monthly +OPTIMIZE TABLE llx_mokodolisign_request; +OPTIMIZE TABLE llx_mokodolisign_signer; +OPTIMIZE TABLE llx_mokodolisign_event; + +-- Check table integrity +CHECK TABLE llx_mokodolisign_request; + +-- Analyze tables for query optimization +ANALYZE TABLE llx_mokodolisign_request; +``` + +#### Index Maintenance + +Indexes are created automatically. Monitor performance and add indexes if needed: + +```sql +-- Check index usage +SHOW INDEX FROM llx_mokodolisign_request; + +-- Add custom index if needed +CREATE INDEX idx_custom ON llx_mokodolisign_request(field_name); +``` + +### Storage Cleanup + +#### Manual Cleanup + +```bash +# Find old verification photos +find /var/www/dolibarr/documents/mokodolisign/ -name "*.png" -mtime +365 + +# Archive old completed requests +tar -czf archive_2024.tar.gz SIG-2024* +``` + +#### Automated Cleanup + +Configure in `cron/purge.php`: + +```php +$purgeThreshold = $now - (365 * 24 * 3600); // 1 year +``` + +### Log Rotation + +Configure logrotate: + +```bash +# /etc/logrotate.d/mokodolisign +/var/log/mokodolisign_*.log { + daily + rotate 30 + compress + delaycompress + notifempty + create 0644 www-data www-data +} +``` + +## Backup & Recovery + +### Backup Strategy + +#### Daily Backups + +1. **Database** + ```bash + mysqldump -u user -p dolibarr_db \ + llx_mokodolisign_request \ + llx_mokodolisign_signer \ + llx_mokodolisign_event \ + > mokodolisign_$(date +%Y%m%d).sql + ``` + +2. **Files** + ```bash + tar -czf mokodolisign_files_$(date +%Y%m%d).tar.gz \ + /var/www/dolibarr/documents/mokodolisign/ + ``` + +#### Weekly Full Backup + +```bash +#!/bin/bash +# Full MokoDoliSign backup script + +DATE=$(date +%Y%m%d) +BACKUP_DIR="/backups/mokodolisign" + +# Database +mysqldump -u user -p dolibarr_db \ + llx_mokodolisign_request \ + llx_mokodolisign_signer \ + llx_mokodolisign_event \ + > $BACKUP_DIR/db_$DATE.sql + +# Files +tar -czf $BACKUP_DIR/files_$DATE.tar.gz \ + /var/www/dolibarr/documents/mokodolisign/ + +# Code (optional) +tar -czf $BACKUP_DIR/code_$DATE.tar.gz \ + /var/www/dolibarr/htdocs/custom/mokodolisign/src/ + +# Compress +gzip $BACKUP_DIR/db_$DATE.sql + +# Clean old backups (keep 30 days) +find $BACKUP_DIR -name "*.gz" -mtime +30 -delete + +echo "Backup completed: $DATE" +``` + +### Recovery Procedures + +#### Database Recovery + +```bash +# Restore database +mysql -u user -p dolibarr_db < mokodolisign_20240115.sql +``` + +#### File Recovery + +```bash +# Restore files +cd /var/www/dolibarr/documents/ +tar -xzf /backups/mokodolisign/files_20240115.tar.gz +``` + +#### Point-in-Time Recovery + +For MySQL with binary logs enabled: + +```bash +# Restore base backup +mysql -u user -p dolibarr_db < base_backup.sql + +# Apply binary logs +mysqlbinlog binlog.000001 | mysql -u user -p dolibarr_db +``` + +### Disaster Recovery + +1. **Document Recovery Plan** + - Define RTO (Recovery Time Objective) + - Define RPO (Recovery Point Objective) + - Test recovery procedures quarterly + +2. **Emergency Contacts** + - System administrators + - Database administrators + - Hosting provider support + - Module developer (Moko Consulting) + +3. **Recovery Steps** + 1. Assess damage extent + 2. Restore from last known good backup + 3. Verify data integrity + 4. Test system functionality + 5. Resume operations + 6. Post-mortem analysis + +## Security + +### Security Checklist + +- [ ] HTTPS/SSL enabled +- [ ] Strong passwords enforced +- [ ] Two-factor authentication enabled +- [ ] File permissions correct (755/644) +- [ ] Database access restricted +- [ ] Regular updates applied +- [ ] Firewall configured +- [ ] Intrusion detection active +- [ ] Regular security audits +- [ ] Incident response plan + +### Hardening + +#### Web Server + +```apache +# Apache .htaccess in documents/mokodolisign/ + + Require all denied + + +# Disable directory listing +Options -Indexes + +# Prevent hotlinking +RewriteEngine on +RewriteCond %{HTTP_REFERER} !^$ +RewriteCond %{HTTP_REFERER} !^https://(www\.)?yourdomain\.com [NC] +RewriteRule \.(png|jpg|pdf)$ - [F] +``` + +#### PHP Configuration + +```ini +; php.ini recommendations +upload_max_filesize = 20M +post_max_size = 25M +max_execution_time = 300 +memory_limit = 256M +display_errors = Off +log_errors = On +``` + +#### Database Security + +```sql +-- Create dedicated database user +CREATE USER 'mokodolisign'@'localhost' IDENTIFIED BY 'strong_password'; +GRANT SELECT, INSERT, UPDATE, DELETE ON dolibarr_db.llx_mokodolisign_* TO 'mokodolisign'@'localhost'; +FLUSH PRIVILEGES; +``` + +### Security Monitoring + +#### Log Analysis + +Monitor for: +- Failed login attempts +- Unusual IP addresses +- High volume requests +- SQL injection attempts +- File upload anomalies + +#### Tools + +- **fail2ban**: Ban IPs with failed attempts +- **ModSecurity**: Web application firewall +- **OSSEC**: Intrusion detection +- **Logwatch**: Log analysis +- **Tripwire**: File integrity monitoring + +### Compliance + +#### GDPR + +- Document data processing activities +- Implement right to erasure +- Data minimization +- Consent management +- Breach notification procedures + +#### Industry Standards + +- **ISO 27001**: Information security +- **SOC 2**: Service organization controls +- **HIPAA**: Healthcare (if applicable) +- **PCI DSS**: Payment cards (if applicable) + +## Performance Tuning + +### Database Optimization + +#### Indexes + +Verify critical indexes exist: + +```sql +SHOW INDEX FROM llx_mokodolisign_request; +``` + +Should include: +- entity +- status +- ref +- date_creation + +#### Query Optimization + +Use EXPLAIN to analyze slow queries: + +```sql +EXPLAIN SELECT * FROM llx_mokodolisign_request WHERE status = 1; +``` + +#### Connection Pooling + +Configure MySQL: + +```ini +max_connections = 200 +thread_cache_size = 100 +``` + +### Web Server + +#### Apache + +```apache +# Enable compression + + AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript + + +# Enable caching + + ExpiresActive On + ExpiresByType image/png "access plus 1 year" + ExpiresByType image/jpeg "access plus 1 year" + ExpiresByType text/css "access plus 1 month" + ExpiresByType application/javascript "access plus 1 month" + +``` + +#### Nginx + +```nginx +# Compression +gzip on; +gzip_types text/plain text/css application/json application/javascript text/xml application/xml; + +# Caching +location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { + expires 1y; + add_header Cache-Control "public, immutable"; +} +``` + +### PHP + +#### OPcache + +```ini +opcache.enable=1 +opcache.memory_consumption=256 +opcache.max_accelerated_files=10000 +opcache.revalidate_freq=60 +``` + +#### APCu + +```ini +apc.enabled=1 +apc.shm_size=128M +apc.ttl=7200 +``` + +### Monitoring Tools + +- **New Relic**: Application performance monitoring +- **Datadog**: Infrastructure monitoring +- **Grafana**: Metrics visualization +- **Prometheus**: Time series database +- **Nagios**: System monitoring + +### Performance Metrics + +Monitor: +- Response time (target: <2s) +- Database query time (target: <100ms) +- Email delivery time (target: <5s) +- PDF generation time (target: <3s) +- File upload time (target: <10s) + +--- + +## Need Help? + +**Technical Support**: hello@mokoconsulting.tech +**Documentation**: https://github.com/mokoconsulting-tech/MokoDoliSign +**Community Forum**: https://www.dolibarr.org/forum/ + +--- + +© 2025 Moko Consulting. All rights reserved. + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/API.md b/MokoConsulting/MokoDoliSign/API.md new file mode 100644 index 0000000..e7100ab --- /dev/null +++ b/MokoConsulting/MokoDoliSign/API.md @@ -0,0 +1,697 @@ +← [Home](Home) + +# MokoDoliSign API Reference + +## Overview + +MokoDoliSign provides both REST-like AJAX endpoints and PHP class APIs for integration. + +## Table of Contents + +1. [AJAX Endpoints](#ajax-endpoints) +2. [PHP Class API](#php-class-api) +3. [Webhooks](#webhooks) +4. [Authentication](#authentication) +5. [Error Handling](#error-handling) +6. [Rate Limiting](#rate-limiting) +7. [Examples](#examples) + +## AJAX Endpoints + +Base URL: `/custom/mokodolisign/src/ajax/` + +### POST /sign.php + +Submit a signature for a document. + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| token | string | Yes | Signer's unique token (64 chars) | +| signature | string | Yes | Base64-encoded PNG signature image | +| selfie | string | No | Base64-encoded PNG selfie image | +| id_photo | string | No | Base64-encoded PNG ID photo | +| geo_lat | float | No | GPS latitude (-90 to 90) | +| geo_lon | float | No | GPS longitude (-180 to 180) | +| geo_accuracy | float | No | GPS accuracy in meters | + +#### Response + +**Success (200)** +```json +{ + "ok": true, + "message": "Signature saved successfully" +} +``` + +**Error (200)** +```json +{ + "ok": false, + "error": "Error message" +} +``` + +#### Example + +```javascript +fetch('/custom/mokodolisign/src/ajax/sign.php', { + method: 'POST', + headers: { + 'Content-Type': 'application/x-www-form-urlencoded' + }, + body: new URLSearchParams({ + token: 'abc123...', + signature: 'data:image/png;base64,...', + geo_lat: '40.7128', + geo_lon: '-74.0060' + }) +}) +.then(response => response.json()) +.then(data => console.log(data)); +``` + +--- + +### POST /decline.php + +Decline a signature request. + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| token | string | Yes | Signer's unique token | +| reason | string | No | Reason for declining (max 500 chars) | + +#### Response + +**Success** +```json +{ + "ok": true, + "message": "Document declined and notifications sent" +} +``` + +#### Example + +```javascript +fetch('/custom/mokodolisign/src/ajax/decline.php', { + method: 'POST', + headers: { + 'Content-Type': 'application/x-www-form-urlencoded' + }, + body: new URLSearchParams({ + token: 'abc123...', + reason: 'Terms not acceptable' + }) +}) +.then(response => response.json()) +.then(data => console.log(data)); +``` + +--- + +### GET /preview.php + +Get preview information about a request. + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| id | int | No* | Request ID | +| token | string | No* | Signer token | + +*One of id or token required + +#### Response + +```json +{ + "ok": true, + "ref": "SIG-000001", + "label": "Employment Agreement", + "description": "Full text...", + "document_path": "SIG-000001/agreement.pdf", + "status": 1, + "date_creation": 1704067200, + "date_expiry": 1706659200, + "require_selfie": 1, + "require_id": 1 +} +``` + +--- + +### POST /camera.php + +Upload camera capture (placeholder for future enhancement). + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| token | string | Yes | Signer's token | +| imageData | string | Yes | Base64-encoded image | + +--- + +### POST /placement.php + +Store signature placement on PDF (placeholder). + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| token | string | Yes | Signer's token | +| page | int | Yes | PDF page number | +| x | int | Yes | X coordinate | +| y | int | Yes | Y coordinate | + +--- + +### POST /merge.php + +Generate final signed PDF (placeholder). + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| id | int | Yes | Request ID | + +--- + +## PHP Class API + +### MokoDoliSignRequest Class + +#### Properties + +```php +public $rowid; // int - Primary key +public $ref; // string - Reference (SIG-000001) +public $label; // string - Document title +public $description; // string - Document description/content +public $status; // int - Status code +public $document_path; // string - Path to document +public $date_creation; // int - Timestamp +public $date_sent; // int - Timestamp +public $date_signature; // int - Timestamp +public $date_expiry; // int - Timestamp +public $require_selfie; // int - 0 or 1 +public $require_id; // int - 0 or 1 +``` + +#### Status Constants + +```php +const STATUS_DRAFT = 0; +const STATUS_PENDING = 1; +const STATUS_INPROGRESS = 2; +const STATUS_COMPLETED = 3; +const STATUS_DECLINED = 4; +const STATUS_EXPIRED = 5; +const STATUS_CANCELLED = 9; +``` + +#### Methods + +##### create($user) + +Create a new request. + +```php +$request = new MokoDoliSignRequest($db); +$request->ref = $request->getNextNumRef(); +$request->label = "Contract"; +$request->description = "Terms..."; +$request->status = MokoDoliSignRequest::STATUS_DRAFT; +$request->date_expiry = strtotime('+30 days'); + +$result = $request->create($user); +if ($result > 0) { + echo "Request created: " . $request->rowid; +} +``` + +##### fetch($id, $ref = '') + +Fetch a request by ID or reference. + +```php +$request = new MokoDoliSignRequest($db); +$result = $request->fetch(0, 'SIG-000001'); +if ($result > 0) { + echo $request->label; +} +``` + +##### update($user) + +Update an existing request. + +```php +$request->fetch($id); +$request->label = "Updated Title"; +$request->update($user); +``` + +##### delete($user) + +Delete a draft request. + +```php +$request->fetch($id); +if ($request->status == MokoDoliSignRequest::STATUS_DRAFT) { + $request->delete($user); +} +``` + +##### getNextNumRef() + +Get next reference number. + +```php +$ref = $request->getNextNumRef(); // Returns "SIG-000123" +``` + +##### setStatus($status, $user) + +Change request status. + +```php +$request->setStatus(MokoDoliSignRequest::STATUS_PENDING, $user); +``` + +--- + +### MokoDoliSignSigner Class + +#### Properties + +```php +public $rowid; // int - Primary key +public $fk_request; // int - Request ID +public $email; // string - Email address +public $firstname; // string - First name +public $lastname; // string - Last name +public $role; // string - Role description +public $token; // string - Unique token +public $status; // int - Status code +public $signature_data; // string - Base64 signature +public $date_sent; // int - Timestamp +public $date_viewed; // int - Timestamp +public $date_signed; // int - Timestamp +``` + +#### Status Constants + +```php +const STATUS_PENDING = 0; +const STATUS_VIEWED = 1; +const STATUS_SIGNED = 2; +const STATUS_DECLINED = 3; +const STATUS_CANCELLED = 9; +``` + +#### Methods + +##### create() + +Create a new signer. + +```php +$signer = new MokoDoliSignSigner($db); +$signer->fk_request = $request_id; +$signer->email = "john@example.com"; +$signer->firstname = "John"; +$signer->lastname = "Doe"; +$signer->role = "Client"; + +$result = $signer->create(); +if ($result > 0) { + echo "Token: " . $signer->token; +} +``` + +##### fetch($id, $token = '') + +Fetch a signer by ID or token. + +```php +$signer = new MokoDoliSignSigner($db); +$result = $signer->fetch(0, $token); +``` + +##### fetchByRequest($fk_request) + +Get all signers for a request. + +```php +$signer = new MokoDoliSignSigner($db); +$signers = $signer->fetchByRequest($request_id); +foreach ($signers as $s) { + echo $s->email . " - " . $s->status; +} +``` + +##### sign($signature_data, $type) + +Record a signature. + +```php +$signer->sign($signature_data, 'draw'); +``` + +##### markAsViewed() + +Mark signer as viewed. + +```php +$signer->markAsViewed(); +``` + +##### update() + +Update signer record. + +```php +$signer->selfie_path = "path/to/selfie.png"; +$signer->update(); +``` + +--- + +### MokoDoliSignEvent Class + +#### Properties + +```php +public $rowid; // int - Primary key +public $fk_request; // int - Request ID +public $fk_signer; // int - Signer ID (optional) +public $code; // string - Event code +public $label; // string - Event description +public $dateevent; // int - Timestamp +public $ip; // string - IP address +public $user_agent; // string - Browser user agent +``` + +#### Static Method: log() + +Log an event. + +```php +MokoDoliSignEvent::log( + $db, + $request_id, + 'SIGNED', + 'Document signed by user', + '', // description + $signer_id, + $user +); +``` + +#### Methods + +##### fetch($id) + +Fetch an event. + +```php +$event = new MokoDoliSignEvent($db); +$event->fetch($event_id); +``` + +##### fetchByRequest($fk_request) + +Get all events for a request. + +```php +$event = new MokoDoliSignEvent($db); +$events = $event->fetchByRequest($request_id); +foreach ($events as $e) { + echo $e->label . " - " . dol_print_date($e->dateevent); +} +``` + +--- + +## Webhooks + +Currently, MokoDoliSign does not provide webhook functionality. Events are handled via email notifications. Future versions may include webhooks for: + +- Request created +- Request sent +- Document viewed +- Document signed +- Document declined +- Document completed +- Request expired + +--- + +## Authentication + +### Token-Based Authentication + +All signer-facing operations use token-based authentication: + +1. Token generated when signer added +2. Token sent via email +3. Token validates access to signing page +4. Token is single-use per signer per request + +### Session-Based Authentication + +Admin operations use Dolibarr's session management: + +1. User logs into Dolibarr +2. Session maintained across requests +3. Permissions checked for each operation + +--- + +## Error Handling + +### Standard Error Response + +```json +{ + "ok": false, + "error": "Error message describing the issue" +} +``` + +### Common Error Codes + +| Error | Description | +|-------|-------------| +| Missing token | Token parameter not provided | +| Invalid token | Token not found or expired | +| Already signed | Signer has already signed | +| Already declined | Document was declined | +| Missing signature | Signature data not provided | +| Request not found | Request ID invalid | +| Permission denied | User lacks permission | + +### PHP Exceptions + +```php +try { + $request = new MokoDoliSignRequest($db); + $result = $request->create($user); + if ($result < 0) { + throw new Exception($request->error); + } +} catch (Exception $e) { + error_log($e->getMessage()); +} +``` + +--- + +## Rate Limiting + +Currently no rate limiting is enforced. For production deployments, consider: + +### Web Server Level + +**Nginx:** +```nginx +limit_req_zone $binary_remote_addr zone=signing:10m rate=10r/s; + +location /custom/mokodolisign/src/ajax/ { + limit_req zone=signing burst=20; +} +``` + +**Apache:** +```apache + + SetOutputFilter RATE_LIMIT + SetEnv rate-limit 400 + +``` + +### Application Level + +Implement in your integration: + +```php +// Check rate limit before processing +$ip = getUserRemoteIP(); +$key = "ratelimit_" . $ip; +$count = $cache->get($key); + +if ($count > 100) { + http_response_code(429); + die(json_encode(['ok' => false, 'error' => 'Rate limit exceeded'])); +} + +$cache->set($key, $count + 1, 3600); +``` + +--- + +## Examples + +### Complete Workflow Example + +```php +ref = $request->getNextNumRef(); +$request->label = "Employment Agreement - John Doe"; +$request->description = "

Employment Terms

...

"; +$request->status = MokoDoliSignRequest::STATUS_DRAFT; +$request->require_selfie = 1; +$request->require_id = 1; +$request->date_expiry = strtotime('+30 days'); +$request->create($user); + +// 2. Add signers +$signers_data = [ + ['email' => 'employee@example.com', 'firstname' => 'John', 'lastname' => 'Doe', 'role' => 'Employee'], + ['email' => 'hr@example.com', 'firstname' => 'Jane', 'lastname' => 'Smith', 'role' => 'HR Manager'] +]; + +foreach ($signers_data as $data) { + $signer = new MokoDoliSignSigner($db); + $signer->fk_request = $request->rowid; + $signer->email = $data['email']; + $signer->firstname = $data['firstname']; + $signer->lastname = $data['lastname']; + $signer->role = $data['role']; + $signer->create(); +} + +// 3. Send request +$request->status = MokoDoliSignRequest::STATUS_PENDING; +$request->date_sent = dol_now(); +$request->update($user); + +// 4. Send emails (in real implementation, see request/card.php) +// ... + +echo "Request created: " . $request->ref; +``` + +### JavaScript Integration + +```javascript +class MokoDoliSignAPI { + constructor(baseUrl) { + this.baseUrl = baseUrl; + } + + async sign(token, signatureData, options = {}) { + const params = new URLSearchParams({ + token: token, + signature: signatureData, + ...options + }); + + const response = await fetch(`${this.baseUrl}/ajax/sign.php`, { + method: 'POST', + headers: { + 'Content-Type': 'application/x-www-form-urlencoded' + }, + body: params + }); + + return response.json(); + } + + async decline(token, reason) { + const params = new URLSearchParams({ + token: token, + reason: reason || '' + }); + + const response = await fetch(`${this.baseUrl}/ajax/decline.php`, { + method: 'POST', + headers: { + 'Content-Type': 'application/x-www-form-urlencoded' + }, + body: params + }); + + return response.json(); + } + + async preview(token) { + const response = await fetch(`${this.baseUrl}/ajax/preview.php?token=${token}`); + return response.json(); + } +} + +// Usage +const api = new MokoDoliSignAPI('/custom/mokodolisign'); + +// Sign document +const result = await api.sign(token, signatureData, { + geo_lat: position.coords.latitude, + geo_lon: position.coords.longitude, + selfie: selfieData, + id_photo: idData +}); + +if (result.ok) { + alert('Signature submitted successfully'); +} +``` + +--- + +## Support + +For API support and custom integration: + +**Email**: hello@mokoconsulting.tech +**GitHub**: https://github.com/mokoconsulting-tech/MokoDoliSign +**Documentation**: https://github.com/mokoconsulting-tech/MokoDoliSign/docs + +--- + +© 2025 Moko Consulting. All rights reserved. + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/BUILD.md b/MokoConsulting/MokoDoliSign/BUILD.md new file mode 100644 index 0000000..3c98ea2 --- /dev/null +++ b/MokoConsulting/MokoDoliSign/BUILD.md @@ -0,0 +1,200 @@ +← [Home](Home) + +# Build and Development Tools + +This document describes the build and CI tools available for MokoDoliSign development. + +## Overview + +Build and CI tools have been pulled from the [moko-platform](https://github.com/mokoconsulting-tech/moko-platform) repository to provide standardized development workflows for Dolibarr modules. + +## Makefile + +The project includes a comprehensive Makefile for common development tasks. + +### Quick Start + +```bash +# Show all available commands +make help + +# Check PHP syntax +make check-syntax + +# Run linter +make lint + +# Build the module package +make build + +# Display module version +make version +``` + +### Available Commands + +- **Development** + - `make help` - Show all available commands + - `make version` - Display module name, version, and number + - `make check-syntax` - Check PHP syntax for all files + +- **Code Quality** + - `make lint` - Run PHP linter on src/ directory + - `make phpcs` - Run PHP CodeSniffer (PSR-12 standard) + - `make phpcbf` - Fix coding standards automatically + - `make phpstan` - Run PHPStan static analysis + - `make validate` - Run all validation checks (lint + phpcs + phpstan) + +- **Testing** + - `make test` - Run PHPUnit tests (if configured) + - `make test-coverage` - Run tests with coverage report + +- **Building** + - `make clean` - Clean build artifacts (build/, dist/) + - `make build` - Build the module package (runs clean + validate first) + - `make release` - Create a release package (runs validate + test + build) + +- **Deployment** + - `make install-local` - Install module to local Dolibarr instance + - `make uninstall-local` - Uninstall module from local Dolibarr + - `make dev-install` - Create symlink for development + +- **Dependencies** + - `make install-deps` - Install development dependencies via Composer + - `make update-deps` - Update dependencies + - `make security-check` - Run Composer security audit + +- **Database** + - `make db-install` - Install database tables + - `make db-uninstall` - Remove database tables + +- **Utilities** + - `make docs` - Generate documentation + - `make format` - Format code (runs phpcbf) + - `make watch` - Watch for changes and run validation + - `make tail-logs` - Tail Dolibarr error logs + - `make clear-cache` - Clear Dolibarr cache + +### Module Configuration + +The Makefile is pre-configured for MokoDoliSign: + +- **Module Name**: mokodolisign +- **Version**: 0.1.0 +- **Module Number**: 185050 (moko-platform reserved range) +- **Source Directory**: src/ + +## Gitea Actions Workflows + +Two CI workflows are configured to run automatically on push and pull requests: + +### Continuous Integration (ci.yml) + +Runs on: `main`, `dev/**`, `rc/**`, `version/**` branches + +**Jobs:** +1. **Module Validation** (PHP 7.4, 8.0, 8.1, 8.2 × Dolibarr 16.0, 17.0, 18.0) + - Validates module structure (checks for src/core/modules/modMokoDoliSign.class.php) + - PHP syntax validation + - Checks for deprecated Dolibarr API usage + - Validates module descriptor + - Checks database schema files + - Validates GPL license headers + +2. **Code Quality** (PHP 8.1) + - PHP_CodeSniffer (PSR-12 standard) + - PHPStan static analysis (level 5) + +3. **Security Checks** + - Scans for hardcoded credentials + - Checks for SQL injection vulnerabilities + - Checks for XSS vulnerabilities + +4. **Summary** + - Generates execution summary + +### Test Suite (test.yml) + +Runs on: `main`, `dev/**`, `rc/**` branches and `workflow_dispatch` + +**Jobs:** +1. **PHPUnit Tests** (PHP 7.4, 8.0, 8.1, 8.2 × Dolibarr 17.0, 18.0) + - Sets up MySQL database + - Downloads and configures Dolibarr + - Links module to Dolibarr + - Runs PHPUnit tests (if configured) + - Uploads coverage to Codecov (PHP 8.1 + Dolibarr 18.0) + +2. **Integration Tests** (Dolibarr 17.0, 18.0) + - Sets up complete Dolibarr environment + - Runs integration test suite (if available) + +3. **Summary** + - Reports test execution summary + +## Build Artifacts + +Build artifacts are automatically excluded from version control: + +- `/build/` - Temporary build directory +- `/dist/` - Distribution packages +- `/vendor/` - Composer dependencies +- `.phpunit.result.cache` - PHPUnit cache + +## Source Structure + +The MokoDoliSign module uses a `src/` directory structure: + +``` +mokodolisign/ +├── src/ # All deployable module code +│ ├── admin/ # Admin pages +│ ├── ajax/ # AJAX endpoints +│ ├── class/ # PHP classes +│ ├── core/ # Module descriptor and triggers +│ ├── public/ # Public pages (sign, verify, portal) +│ ├── sql/ # Database schema +│ └── ... +├── docs/ # Documentation +├── Makefile # Build automation +├── .github/ +│ └── workflows/ # CI workflows +└── README.md +``` + +All build and CI tools are configured to work with this structure. + +## Requirements + +### For Local Development + +- PHP 7.4+ (for validation) +- Composer (for dependencies, optional) +- Make (for running Makefile commands) +- rsync (for building packages) +- zip (for creating distribution archives) + +### For CI Workflows + +- Gitea Actions (runs automatically) +- No local configuration required + +## References + +- **moko-platform**: https://github.com/mokoconsulting-tech/moko-platform +- **Dolibarr**: https://www.dolibarr.org +- **moko-platform**: Module ID reserved range 185050-185099 + +## Support + +For issues with build tools or CI workflows, see: +- [moko-platform Documentation](https://github.com/mokoconsulting-tech/moko-platform) +- [MokoDoliSign Issues](https://github.com/mokoconsulting-tech/MokoDoliSign/issues) + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/Home.md b/MokoConsulting/MokoDoliSign/Home.md new file mode 100644 index 0000000..353417f --- /dev/null +++ b/MokoConsulting/MokoDoliSign/Home.md @@ -0,0 +1,50 @@ +# MokoDoliSign + +MokoDoliSign is a Dolibarr module that adds secure electronic signature functionality into your + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [INSTALL](INSTALL) | ← [Home](Home) | +| [MIGRATION_GUIDE](MIGRATION_GUIDE) | ← [Home](Home) | +| [QUICK_START](QUICK_START) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [API](API) | ← [Home](Home) | +| [README](README) | ← [Home](Home) | +| [STRUCTURE](STRUCTURE) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [ADMIN_GUIDE](ADMIN_GUIDE) | ← [Home](Home) | +| [BUILD](BUILD) | ← [Home](Home) | +| [IMPLEMENTATION_SUMMARY](IMPLEMENTATION_SUMMARY) | ← [Home](Home) | +| [MODULE_ID](MODULE_ID) | ← [Home](Home) | +| [ROADMAP](ROADMAP) | ← [Home](Home) | +| [USER_GUIDE](USER_GUIDE) | ← [Home](Home) | +| [update server](update-server.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliSign/IMPLEMENTATION_SUMMARY.md b/MokoConsulting/MokoDoliSign/IMPLEMENTATION_SUMMARY.md new file mode 100644 index 0000000..15594be --- /dev/null +++ b/MokoConsulting/MokoDoliSign/IMPLEMENTATION_SUMMARY.md @@ -0,0 +1,125 @@ +← [Home](Home) + +# MokoDoliSign Implementation Summary + +## Overview +Successfully implemented a complete Dolibarr extension for managing electronic signatures and agreements (e-signatures). + +## Changes Made + +### Database Schema (6 SQL files) +- **llx_mokodolisign_request.sql** - Main signature request table +- **llx_mokodolisign_signer.sql** - Signers associated with requests +- **llx_mokodolisign_event.sql** - Audit log and event tracking +- Corresponding .key.sql files with foreign keys and unique constraints + +### Core Classes (3 files enhanced) +- **MokoDoliSignRequest** - Full CRUD operations, status management, reference generation +- **MokoDoliSignSigner** - Signer management, token generation, signature capture +- **MokoDoliSignEvent** - Audit logging with static helper method + +### Admin Interface (2 files) +- **request/list.php** - List all signature requests with search/filter +- **request/card.php** - Create/edit requests, add signers, view history + +### Public Interfaces (2 files) +- **public/sign.php** - Token-based signature capture with HTML5 canvas +- **public/verify.php** - Public verification page with audit trail + +### AJAX Endpoints (6 files) +- **ajax/sign.php** - Process signature submission +- **ajax/decline.php** - Handle signature declination +- **ajax/preview.php** - Preview document details +- **ajax/camera.php** - Camera/selfie capture (placeholder) +- **ajax/placement.php** - Signature placement (placeholder) +- **ajax/merge.php** - PDF merging (placeholder) + +### Cron Jobs (3 files) +- **cron/expire.php** - Automatically expire old requests +- **cron/remind.php** - Send reminders to pending signers +- **cron/purge.php** - Archive old completed requests + +### Module Configuration +- **modMokoDoliSign.class.php** - Updated with menu structure, database initialization +- **langs/en_US/mokodolisign.lang** - Language translations + +### Documentation +- **INSTALL.md** - Complete installation and usage guide + +## Key Features Implemented + +### 1. Complete Workflow +- Draft → Pending → InProgress → Completed/Declined/Expired/Cancelled +- Multi-signer support with independent tokens +- Automatic status progression based on signer actions + +### 2. Security +- Token-based authentication for signers +- SQL injection prevention with proper escaping +- XSS prevention with output encoding +- Input validation using GETPOST filters + +### 3. Audit Trail +- Complete event logging for compliance +- IP address and user agent tracking +- Timestamp for all actions +- Public verification page + +### 4. Integration +- Full Dolibarr CommonObject inheritance +- Menu integration +- Rights and permissions system +- Multi-entity support + +### 5. User Experience +- Responsive HTML5 canvas for signatures +- Touch-friendly interface +- Real-time status updates +- Clean, professional UI + +## Technical Statistics +- **25 files** modified/created +- **2,215 lines** of code added +- **33 lines** removed (stubs replaced) +- **3 database tables** with proper indexes +- **6 AJAX endpoints** implemented +- **3 cron jobs** for automation + +## Code Quality +- ✓ No SQL injection vulnerabilities +- ✓ Proper output escaping +- ✓ Input validation throughout +- ✓ Null-safe parameter handling +- ✓ Error handling in all operations +- ✓ Follows Dolibarr coding standards + +## Testing Checklist +- [x] Module activation/deactivation +- [x] Database tables creation +- [x] Signature request CRUD operations +- [x] Signer management +- [x] Token-based signing flow +- [x] Status transitions +- [x] Audit logging +- [x] Verification page +- [x] Cron job execution + +## Future Enhancements +- PDF generation with embedded signatures +- Email notifications to signers +- Facial recognition for selfie verification +- OTP authentication +- Advanced document placement +- Multiple signature types (draw/upload/text) +- Certificate generation with QR codes + +## Conclusion +The MokoDoliSign extension is now fully functional with all core features implemented. It provides a complete, secure, and user-friendly solution for managing electronic signatures within Dolibarr. + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/INSTALL.md b/MokoConsulting/MokoDoliSign/INSTALL.md new file mode 100644 index 0000000..5a29e50 --- /dev/null +++ b/MokoConsulting/MokoDoliSign/INSTALL.md @@ -0,0 +1,74 @@ +← [Home](Home) + +# MokoDoliSign Installation & User Guide + +## Installation Steps + +1. **Copy module to Dolibarr** + - Copy the entire `mokodolisign` directory to your Dolibarr's custom modules directory: + ``` + /path/to/dolibarr/htdocs/custom/mokodolisign/ + ``` + - The module structure includes a `src/` directory containing all deployable code (classes, views, scripts), with documentation and configuration files at the root level. + +2. **Enable the module** + - Log in to Dolibarr as an administrator + - Go to: Home → Setup → Modules/Applications + - Search for "MokoDoliSign" + - Click "Activate" to enable the module + +3. **Database tables** + - The module will automatically create the necessary database tables on first activation + +4. **Configure permissions** + - Go to: Home → Setup → Users & Groups + - Assign appropriate permissions to users + +## Features + +### Document Management +- WYSIWYG rich text editor for creating agreements +- Upload PDF, DOC, DOCX files +- Auto-generate PDF from description text +- Store documents securely + +### Identity Verification +- Optional signer selfie capture via camera +- Optional ID document photo capture +- Photos stored per signer +- Configurable per-request + +### Geolocation & Tracking +- GPS coordinates captured during signing +- IP address tracking +- User agent recording +- Complete audit trail + +### Email Integration +- Automatic notifications to signers +- Unique secure links per signer +- Email tracking + +### Mobile Responsive +- Works on phones, tablets, and desktops +- Touch-friendly signature canvas +- Camera integration on mobile devices +- Adaptive layouts + +### Customer Portal +- Self-service portal for signers +- Email-based request lookup +- View all pending signatures +- Direct access to sign + +## Usage + +See complete user guide at: https://github.com/mokoconsulting-tech/MokoDoliSign + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/MIGRATION_GUIDE.md b/MokoConsulting/MokoDoliSign/MIGRATION_GUIDE.md new file mode 100644 index 0000000..08c6bcc --- /dev/null +++ b/MokoConsulting/MokoDoliSign/MIGRATION_GUIDE.md @@ -0,0 +1,369 @@ +← [Home](Home) + +# MokoDoliSign Migration Guide + +## Module ID Update - User Guide + +**Version**: 0.1.0+ +**Effective Date**: January 2026 + +## Overview + +MokoDoliSign has migrated to use the official moko-platform module ID (185050). This guide explains what users and administrators need to know about this change. + +## Table of Contents + +1. [Who Is Affected](#who-is-affected) +2. [What Changed](#what-changed) +3. [Impact on Users](#impact-on-users) +4. [Impact on Administrators](#impact-on-administrators) +5. [Migration Steps](#migration-steps) +6. [Troubleshooting](#troubleshooting) +7. [FAQ](#faq) + +## Who Is Affected + +### New Installations + +**No action required.** If you're installing MokoDoliSign for the first time, the module will use the correct ID automatically. + +### Development Installations + +If you installed MokoDoliSign during early development (before v0.1.0), you may have the old module ID (104000) and will need to follow the migration steps. + +### Production Installations + +The module was never released with the old ID, so production installations are not affected. + +## What Changed + +### Technical Changes + +- **Module ID**: Changed from development placeholder (104000) to official moko-platform ID (185050) +- **Permission IDs**: Updated from 104000X pattern to 185050X pattern +- **Database**: Module registration and permissions automatically updated + +### What Stayed the Same + +✅ All features work identically +✅ No data loss +✅ No configuration changes needed +✅ URLs and access remain the same +✅ Existing signature requests preserved +✅ All audit trails maintained + +## Impact on Users + +### For End Users (Signers) + +**No impact.** The signing process, email notifications, and customer portal remain unchanged. + +### For Internal Users (Dolibarr Users) + +**Minimal impact.** After the update: + +1. Module continues to work normally +2. All existing signature requests accessible +3. Permissions remain assigned to your user account +4. No re-training required + +**What You Might Notice:** + +- During module upgrade, there may be a brief "module disabled" message +- After re-enabling, everything works as before + +## Impact on Administrators + +### Permissions + +User permissions are automatically migrated during the module upgrade. However, administrators should verify: + +1. **Verify User Permissions** (after upgrade): + - Home → Setup → Users + - Select a user + - Check MokoDoliSign permissions are still assigned + - Permissions should include: + - ✓ Read MokoDoliSign + - ✓ Create/Send requests + - ✓ View captured media (optional) + - ✓ Admin MokoDoliSign (for admins) + +2. **Test Module Access**: + - Log in as a regular user + - Navigate to MokoDoliSign menu + - Verify access to signature requests + - Test creating a new request + +### Database + +The module upgrade automatically handles database updates: + +``` +Module ID: 104000 → 185050 +Rights IDs: + - 1040001 → 1850501 (Read) + - 1040002 → 1850502 (Create) + - 1040003 → 1850503 (Media view) + - 1040004 → 1850504 (Admin) +``` + +These updates occur in: +- `llx_const` table (module registration) +- `llx_rights_def` table (permission definitions) +- `llx_user_rights` table (user permission assignments) + +## Migration Steps + +### For New Installations + +1. Install MokoDoliSign as normal +2. Enable module in Dolibarr admin +3. Configure permissions +4. No additional steps needed + +### For Development Installations + +If you have an early development version: + +#### Step 1: Backup + +```bash +# Backup database +mysqldump -u user -p database > backup_before_update.sql + +# Backup module files (optional) +cp -r /path/to/dolibarr/htdocs/custom/mokodolisign ~/mokodolisign_backup +``` + +#### Step 2: Update Module + +```bash +cd /path/to/dolibarr/htdocs/custom/mokodolisign +git pull origin main +# or download and extract new version +``` + +#### Step 3: Disable and Re-enable Module + +1. Log in to Dolibarr as administrator +2. Navigate to: **Home → Setup → Modules/Applications** +3. Find "MokoDoliSign" in the list +4. Click "Disable" button +5. Wait for confirmation +6. Click "Enable" button +7. Wait for module to activate + +**Note**: Dolibarr automatically runs upgrade scripts during re-enable. + +#### Step 4: Verify Migration + +1. **Check Module Status**: + - Module should show as "Active" with no errors + - Check for any error messages + +2. **Verify Permissions**: + - Home → Setup → Users → Select user + - Check MokoDoliSign permissions are assigned + - Permissions should show with new IDs (185050X) + +3. **Test Functionality**: + - Navigate to MokoDoliSign + - Access existing signature requests + - Create a test request + - Verify everything works normally + +4. **Check Audit Log**: + - Open any completed signature request + - Verify audit trail is intact + - Confirm all historical data preserved + +#### Step 5: Inform Users + +Send a brief notification to users: + +``` +Subject: MokoDoliSign Module Update + +Dear Users, + +We have updated MokoDoliSign to comply with moko-platform. + +What you need to know: +- No action required from you +- All features work the same +- All existing signature requests are preserved +- No retraining needed + +If you experience any issues, please contact IT support. +``` + +## Troubleshooting + +### Issue: Module Won't Enable + +**Symptoms**: Error message when trying to enable module + +**Solution**: +1. Check Dolibarr logs: `documents/dolibarr.log` +2. Verify database connection +3. Ensure database user has UPDATE permissions +4. Try disabling and re-enabling +5. Check for conflicting modules + +### Issue: Permissions Not Working + +**Symptoms**: Users can't access MokoDoliSign after update + +**Solution**: +1. **Verify permissions assigned**: + - Home → Setup → Users → [Select user] + - Modify → Permissions tab + - Ensure MokoDoliSign permissions checked + +2. **Re-assign permissions if needed**: + - Uncheck all MokoDoliSign permissions + - Click "Save" + - Check permissions again + - Click "Save" + +3. **User logs out and back in**: + - Permission changes require new session + +### Issue: Can't Access Old Requests + +**Symptoms**: Previous signature requests not visible + +**Solution**: +1. Check if module is enabled +2. Verify user has "Read" permission +3. Check entity filter (if multi-entity) +4. Review database migration: + ```sql + -- Check if old rights still exist + SELECT * FROM llx_rights_def + WHERE module = 'mokodolisign'; + + -- Should show IDs starting with 185050X + ``` + +### Issue: Database Migration Failed + +**Symptoms**: Errors during module enable, permissions show old IDs + +**Solution**: +1. **Restore backup**: + ```bash + mysql -u user -p database < backup_before_update.sql + ``` + +2. **Contact support**: + - Email: hello@mokoconsulting.tech + - Include: Error logs, Dolibarr version, database type + +3. **Manual verification** (for advanced users only): + ```sql + -- Check module registration + SELECT * FROM llx_const + WHERE name = 'MAIN_MODULE_MOKODOLISIGN'; + -- Should show value = '185050' + + -- Check rights definitions + SELECT * FROM llx_rights_def + WHERE module = 'mokodolisign'; + -- IDs should be 1850501, 1850502, 1850503, 1850504 + + -- Check user rights + SELECT * FROM llx_user_rights + WHERE fk_id IN (1850501, 1850502, 1850503, 1850504); + -- Should see user permission assignments + ``` + +## FAQ + +### Q: Will I lose any signature requests? + +**A**: No. All signature requests, signers, and audit logs are preserved. The migration only updates internal module IDs, not your data. + +### Q: Do I need to inform signers? + +**A**: No. Signers are not affected. Email links, signing pages, and verification all work the same. + +### Q: Can I roll back if something goes wrong? + +**A**: Yes. Restore your database backup taken before the update: +```bash +mysql -u user -p database < backup_before_update.sql +``` +Then reinstall the previous version of the module. + +### Q: How long does the migration take? + +**A**: The migration is instant (< 1 second). The disable/enable process takes about 10-30 seconds total. + +### Q: Will my cron jobs still work? + +**A**: Yes. Cron jobs are not affected by module ID changes. They will continue to work without modification. + +### Q: Do I need to update any configuration? + +**A**: No. All configuration settings are preserved and work without changes. + +### Q: What if I have custom integrations? + +**A**: Custom integrations using the API or database should continue to work. However, if you have hardcoded permission IDs (104000X), you'll need to update them to the new IDs (185050X). + +### Q: Why did the module ID change? + +**A**: To comply with moko-platform and use our officially reserved module ID range (185050-185099). This ensures no conflicts with other modules and aligns with Dolibarr best practices. + +### Q: Where can I find more technical details? + +**A**: See [MODULE_ID.md](MODULE_ID.md) for complete technical documentation about module IDs, the registry system, and developer information. + +## Support + +### Before Contacting Support + +1. Review this migration guide completely +2. Check the [Troubleshooting](#troubleshooting) section +3. Verify your backup is current +4. Collect relevant information: + - Dolibarr version + - PHP version + - Database type and version + - Error messages from logs + - Steps that led to the issue + +### Getting Help + +#### Community Support + +- **GitHub Issues**: https://github.com/mokoconsulting-tech/MokoDoliSign/issues +- **Discussions**: https://github.com/mokoconsulting-tech/MokoDoliSign/discussions + +#### Commercial Support + +**Moko Consulting** +Email: hello@mokoconsulting.tech +Website: https://mokoconsulting.tech + +## Related Documentation + +- [User Guide](USER_GUIDE.md) - How to use MokoDoliSign +- [Administrator Guide](ADMIN_GUIDE.md) - Installation and configuration +- [Module ID Documentation](MODULE_ID.md) - Technical details about module IDs +- [API Reference](API.md) - API endpoints and integration + +--- + +**Document Version**: 1.0 +**Last Updated**: 2026-01-07 +**License**: GPL-3.0-or-later + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/MODULE_ID.md b/MokoConsulting/MokoDoliSign/MODULE_ID.md new file mode 100644 index 0000000..d3f84c9 --- /dev/null +++ b/MokoConsulting/MokoDoliSign/MODULE_ID.md @@ -0,0 +1,316 @@ +← [Home](Home) + +# MokoDoliSign Module ID Documentation + +## Overview + +This document provides comprehensive information about the MokoDoliSign module ID, including its purpose, the moko-platform registry system, and important considerations for module upgrades. + +## Table of Contents + +1. [Module ID Basics](#module-id-basics) +2. [moko-platform Registry](#mokostandards-registry) +3. [Current Module ID](#current-module-id) +4. [Module Rights IDs](#module-rights-ids) +5. [Migration from Previous IDs](#migration-from-previous-ids) +6. [Developer Notes](#developer-notes) +7. [References](#references) + +## Module ID Basics + +### What is a Module ID? + +In Dolibarr, every module requires a unique numerical identifier called the "numero" (module ID). This ID is used throughout the system to: + +- **Uniquely identify the module** in the database and across installations +- **Define permission namespaces** for user access control +- **Prevent conflicts** between different modules +- **Enable module tracking** in the Dolibarr ecosystem + +### Why Module IDs Matter + +Module IDs are critical for: + +1. **Namespace Isolation**: Prevents conflicts between modules from different vendors +2. **Permission Management**: Forms the basis for unique permission IDs (module ID + sequence) +3. **Database Integrity**: Ensures proper foreign key relationships and data isolation +4. **Marketplace Compatibility**: Required for listing in official Dolibarr marketplaces +5. **Upgrade Stability**: Maintains consistency across module versions + +## moko-platform Registry + +### Reserved Range + +Moko Consulting maintains a reserved block of module IDs as part of the moko-platform coding conventions: + +``` +Reserved Range: 185050 - 185099 +Total Available: 50 module IDs +``` + +This range is officially registered in: +- [Dolibarr Wiki - List of Module IDs](https://wiki.dolibarr.org/index.php/List_of_modules_id) +- [moko-platform Repository](https://github.com/mokoconsulting-tech/moko-platform) + +### Allocation Within Range + +The moko-platform range is allocated to various Moko Consulting modules: + +| Module ID | Module Name | Status | +|-----------|-------------|--------| +| 185050 | MokoDoliSign | **Active** (this module) | +| 185051 | Reserved | Future use | +| 185052 | Reserved | Future use | +| ... | ... | ... | +| 185099 | Reserved | Future use | + +### Why Use moko-platform Range? + +Using the official moko-platform range provides: + +1. **Official Registration**: Module ID is registered with Dolibarr Foundation +2. **No Conflicts**: Guaranteed no conflicts with other vendors or community modules +3. **Professional Identity**: Clearly identifies module as a Moko Consulting product +4. **Future Compatibility**: Ensures compatibility with future Moko modules +5. **Standards Compliance**: Aligns with Moko's quality and governance standards + +## Current Module ID + +### Primary Module ID + +```php +$this->numero = 185050; +``` + + +### Module Descriptor Details + +```php +class modMokoDoliSign extends DolibarrModules +{ + public function __construct($db) + { + // ... + $this->numero = 185050; // moko-platform reserved range: 185050-185099 + $this->rights_class = 'mokodolisign'; + $this->family = "crm"; + $this->module_position = '80'; + $this->name = 'MokoDoliSign'; + // ... + } +} +``` + +## Module Rights IDs + +### Rights ID Structure + +Permission IDs follow the pattern: `[Module ID][Sequence]` + +For MokoDoliSign (module ID 185050): + +``` +Base ID: 185050 +Rights IDs: 1850501, 1850502, 1850503, 1850504, ... +``` + +### Current Rights Definitions + +| Right ID | Permission Name | Type | Description | +|----------|----------------|------|-------------| +| 1850501 | Read MokoDoliSign | Read (r) | View signature requests and history | +| 1850502 | Create/Send requests | Write (w) | Create and send new signature requests | +| 1850503 | View captured media | Read (r) | Access selfies and ID photos | +| 1850504 | Admin MokoDoliSign | Admin (a) | Access module configuration | + +### Rights ID Format + +```php +$this->rights[0][0] = 1850501; // Read permission +$this->rights[1][0] = 1850502; // Create permission +$this->rights[2][0] = 1850503; // Media view permission +$this->rights[3][0] = 1850504; // Admin permission +``` + +**Pattern Breakdown**: +- `185050` - Module ID +- `1` - Permission sequence number (1-9) + +## Migration from Previous IDs + +### Version History + +#### Pre-moko-platform (Development) + +**Module ID**: `104000` (placeholder) +**Rights IDs**: `1040001`, `1040002`, `1040003`, `1040004` +**Status**: Development/testing only +**Note**: Never used in production + +#### moko-platform Compliant (Current) + +**Module ID**: `185050` (official) +**Rights IDs**: `1850501`, `1850502`, `1850503`, `1850504` +**Status**: Production +**Effective**: Version 0.1.0+ + +### Impact on Existing Installations + +#### For New Installations + +**No action required**. The module will install with the correct ID (185050) from the start. + +#### For Development Installations + +If you installed the module during development with the old ID (104000): + +1. **Database Migration**: Dolibarr's module upgrade system automatically handles: + - Module ID updates in `llx_const` table + - Permission ID updates in `llx_rights_def` table + - User permission mappings in `llx_user_rights` table + +2. **Recommended Actions**: + ```bash + # Backup database before upgrade + mysqldump -u user -p database > backup_before_id_change.sql + + # Disable and re-enable module in Dolibarr admin + # Home → Setup → Modules → MokoDoliSign → Disable + # Home → Setup → Modules → MokoDoliSign → Enable + ``` + +3. **Verify Migration**: + - Check module shows as "Active" with no errors + - Test user permissions still work correctly + - Verify existing signature requests are accessible + +#### Database Changes + +The module ID change affects these tables: + +```sql +-- Module registration +UPDATE llx_const +SET value = '185050' +WHERE name = 'MAIN_MODULE_MOKODOLISIGN'; + +-- Rights definitions +UPDATE llx_rights_def +SET id = id + 810500 +WHERE module = 'mokodolisign'; + +-- User permissions +UPDATE llx_user_rights +SET fk_id = fk_id + 810500 +WHERE fk_id IN (1040001, 1040002, 1040003, 1040004); +``` + +**Note**: These updates are handled automatically by Dolibarr. Manual SQL execution is NOT recommended. + +### No Production Impact + +Since the module was not released with the placeholder ID (104000), no production installations require migration. All production deployments use the official moko-platform ID (185050). + +## Developer Notes + +### Module Descriptor Location + +**File**: `src/core/modules/modMokoDoliSign.class.php` + +### Modifying Module ID + +**⚠️ WARNING**: Do NOT change the module ID after release to production. Changing module IDs in production can cause: + +- Loss of user permissions +- Database integrity issues +- Broken module dependencies +- Orphaned data records + +### Adding New Rights + +When adding new permissions, follow the sequence pattern: + +```php +// Next available right ID: 1850505 +$r = 4; // Next sequence number +$this->rights[$r][0] = 1850505; +$this->rights[$r][1] = 'New Permission Name'; +$this->rights[$r][2] = 'r'; // r=read, w=write, d=delete, a=admin +$this->rights[$r][3] = 0; // 0=optional, 1=enabled by default +$this->rights[$r][4] = 'new_permission'; // Internal key +$r++; +``` + +### Best Practices + +1. **Never Change Module ID**: Once set, the module ID is permanent +2. **Sequential Rights IDs**: Add new permissions in sequence (1850505, 1850506, etc.) +3. **Document Changes**: Update this documentation when adding rights +4. **Test Migrations**: Test module enable/disable cycles during development +5. **Backup Before Upgrades**: Always backup before module version changes + +### Reserved Rights Range + +MokoDoliSign uses rights IDs: `1850501` - `1850599` + +Available range: 99 unique permission IDs (more than sufficient for module needs) + +## Dolibarr Module ID Registry + +### Official Registry + +Module IDs are registered in the official Dolibarr Wiki: +https://wiki.dolibarr.org/index.php/List_of_modules_id + +### ID Ranges + +| Range | Purpose | Example | +|-------|---------|---------| +| 0 - 94,999 | Dolibarr core modules | 1 = Module Third Parties | +| 95,000 - 99,999 | Community modules | 95001 = Community Module X | +| 100,000 - 499,999 | Third-party vendors | 185050 = MokoDoliSign | +| 500,000+ | Extended use | Reserved for future | + +### Moko Consulting Block + +**Vendor**: Moko Consulting +**Block**: 185050 - 185099 +**Contact**: hello@mokoconsulting.tech +**Website**: https://mokoconsulting.tech +**Standards**: https://github.com/mokoconsulting-tech/moko-platform + +## References + +### Documentation + +- [Dolibarr Module Development](https://wiki.dolibarr.org/index.php/Module_development) +- [Dolibarr Module Structure](https://wiki.dolibarr.org/index.php/Module_structure) +- [moko-platform Repository](https://github.com/mokoconsulting-tech/moko-platform) + +### Related Files + +- Module descriptor: `src/core/modules/modMokoDoliSign.class.php` +- Database schema: `src/sql/llx_mokodolisign_*.sql` +- Rights usage: Throughout `src/` directory in permission checks + +### Support + +For questions about module IDs or moko-platform: + +- **Email**: hello@mokoconsulting.tech +- **Issues**: https://github.com/mokoconsulting-tech/MokoDoliSign/issues +- **Discussions**: https://github.com/mokoconsulting-tech/MokoDoliSign/discussions + +--- + +**Document Version**: 1.0 +**Last Updated**: 2026-01-07 +**License**: GPL-3.0-or-later + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/QUICK_START.md b/MokoConsulting/MokoDoliSign/QUICK_START.md new file mode 100644 index 0000000..8b3436c --- /dev/null +++ b/MokoConsulting/MokoDoliSign/QUICK_START.md @@ -0,0 +1,279 @@ +← [Home](Home) + +# MokoDoliSign Quick Start Guide + +## 5-Minute Quick Start + +Get up and running with MokoDoliSign in minutes. + +## Table of Contents + +1. [Creating Your First Request](#creating-your-first-request) +2. [Adding Signers](#adding-signers) +3. [Sending for Signature](#sending-for-signature) +4. [Signing a Document](#signing-a-document) +5. [Quick Reference](#quick-reference) + +## Creating Your First Request + +### Basic Steps + +1. **Navigate**: Click **MokoDoliSign** → **Requests** → **New** + +2. **Enter Details**: + ``` + Label: Employment Agreement - John Doe + Description: [Type or paste your agreement text] + OR + Upload Document: [Choose PDF/DOC file] + ``` + +3. **Set Verification** (optional): + - ☐ Require selfie photo + - ☐ Require ID photo + +4. **Click Save** + +**Time**: 2 minutes + +## Adding Signers + +1. **Fill in Signer Details**: + ``` + Email: john.doe@example.com + First Name: John + Last Name: Doe + Role: Employee + ``` + +2. **Click "Add Signer"** + +3. **Repeat** for additional signers + +4. **Click Save** + +**Time**: 1 minute per signer + +## Sending for Signature + +1. **Review** your request: + - ✓ Document/description present + - ✓ All signers added + - ✓ Settings correct + +2. **Click "Send"** + +3. **Confirmation**: Signers receive email with unique link + +**Time**: 30 seconds + +## Signing a Document + +### For Signers + +1. **Open Email**: Click link in "Signature Request" email + +2. **Review Document**: Read carefully + +3. **Verify Identity** (if required): + - Click "Start Camera" for selfie + - Click "Start Camera" for ID photo + - Capture and confirm + +4. **Sign**: + - Draw signature with mouse/finger + - Click "Sign Document" + +5. **Confirmation**: "Successfully signed" message appears + +**Time**: 2-3 minutes + +## Quick Reference + +### Status Colors + +| Status | Meaning | Action | +|--------|---------|--------| +| Draft (Blue) | Being prepared | Edit, Add signers, Send | +| Pending (Yellow) | Awaiting signatures | Monitor, Send reminder | +| Completed (Green) | All signed | Download, Archive | +| Declined (Red) | Someone declined | Review, Resend | + +### Common Actions + +#### View All Requests +``` +MokoDoliSign → Requests → List +``` + +#### Create New Request +``` +MokoDoliSign → Requests → New +``` + +#### Track Request Status +``` +MokoDoliSign → Requests → List → Click request +``` + +#### Download Signed Document +``` +Open completed request → Download button +``` + +#### Send Reminder +``` +Open pending request → Send Reminder button +``` + +### Keyboard Shortcuts + +| Action | Shortcut | +|--------|----------| +| Save request | Ctrl+S | +| Clear signature | Escape | +| Submit signature | Enter | + +### Email Templates + +#### Request Email (Sent to Signers) +``` +Subject: Signature Request: [Document Title] + +Hello [Name], + +You have been requested to sign: [Document Title] + +Click to review and sign: +[Unique Link] + +This link is for you only. Do not share. +``` + +#### Completion Email (All Signers) +``` +Subject: Document Signed: [Document Title] + +The document "[Document Title]" has been signed by all parties. + +Reference: [Request ID] +Date: [Completion Date] +``` + +#### Decline Email (All Signers) +``` +Subject: Document Declined: [Document Title] + +[Signer Name] has declined to sign "[Document Title]" + +Reason: [Decline reason if provided] +``` + +### Tips & Best Practices + +#### ✅ Do + +- **Use clear labels**: "Employment Contract - John Smith" not just "Contract" +- **Set expiry dates**: Default 30 days is usually appropriate +- **Add all signers before sending**: Avoids confusion +- **Test with yourself first**: Create a test request to see signer experience +- **Use verification for important docs**: Selfie/ID for legal or high-value agreements + +#### ❌ Don't + +- **Don't share signing links**: Each link is unique and traceable +- **Don't rush signers**: Give adequate time to review +- **Don't forget expiry dates**: Expired requests must be resent +- **Don't use generic descriptions**: Be specific about what's being signed + +### Common Questions + +**Q: How do I know when someone signs?** +A: You receive an email notification for each signature. + +**Q: Can I cancel a request?** +A: Yes, open the request and click "Cancel" (if pending). + +**Q: What if the link expires?** +A: Open the request and click "Resend" to generate new links. + +**Q: Can signers see each other's info?** +A: No, each signer only sees their own signing page. + +**Q: Is the signature legally binding?** +A: Yes, includes complete audit trail for legal compliance. + +### Troubleshooting + +#### Problem: Signer didn't receive email + +**Solutions**: +1. Check spam/junk folder +2. Verify email address is correct +3. Resend from request page +4. Use customer portal as backup (enter email) + +#### Problem: Camera not working + +**Solutions**: +1. Use HTTPS (required for camera) +2. Grant browser camera permission +3. Try different browser +4. Check camera not in use elsewhere + +#### Problem: Can't draw signature + +**Solutions**: +1. Try mouse instead of trackpad +2. Clear browser cache +3. Try different browser +4. Use mobile device (touch-friendly) + +### Getting More Help + +#### Documentation + +- **Full User Guide**: [USER_GUIDE.md](USER_GUIDE.md) +- **Admin Guide**: [ADMIN_GUIDE.md](ADMIN_GUIDE.md) +- **API Reference**: [API.md](API.md) + +#### Support + +- **GitHub**: https://github.com/mokoconsulting-tech/MokoDoliSign/issues +- **Email**: hello@mokoconsulting.tech + +--- + +## Next Steps + +### For New Users + +1. ✅ Complete this quick start +2. ⬜ Read full [User Guide](USER_GUIDE.md) +3. ⬜ Create a test request +4. ⬜ Sign as a test signer +5. ⬜ Review audit trail + +### For Administrators + +1. ✅ Complete quick start +2. ⬜ Read [Administrator Guide](ADMIN_GUIDE.md) +3. ⬜ Configure module settings +4. ⬜ Set up user permissions +5. ⬜ Configure cron jobs +6. ⬜ Test email notifications + +--- + +**Document Version**: 1.0 +**Last Updated**: 2026-01-07 +**For**: MokoDoliSign 0.1.0+ +**License**: GPL-3.0-or-later + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/README.md b/MokoConsulting/MokoDoliSign/README.md new file mode 100644 index 0000000..fd70fba --- /dev/null +++ b/MokoConsulting/MokoDoliSign/README.md @@ -0,0 +1,491 @@ +← [Home](Home) + +# MokoDoliSign Enterprise Documentation + +## Table of Contents + +1. [Overview](#overview) +2. [Architecture](#architecture) +3. [Installation](#installation) +4. [Configuration](#configuration) +5. [User Guide](#user-guide) +6. [API Reference](#api-reference) +7. [Security](#security) +8. [Compliance](#compliance) +9. [Troubleshooting](#troubleshooting) +10. [Support](#support) +11. [Module ID & Registry](MODULE_ID.md) +12. [Quick Start Guide](QUICK_START.md) +13. [Migration Guide](MIGRATION_GUIDE.md) + +## Overview + +MokoDoliSign is an enterprise-grade electronic signature management system for Dolibarr ERP/CRM. It provides legally binding digital signatures with complete audit trails, identity verification, and compliance features. + +### Key Features + +- **Document Management**: WYSIWYG editor, document upload, PDF generation +- **Multi-Party Signing**: Support for multiple signers with independent workflows +- **Identity Verification**: Selfie and ID photo capture with camera integration +- **Geolocation Tracking**: GPS coordinates, IP address, and user-agent recording +- **Email Notifications**: Automatic notifications for all workflow events +- **Customer Portal**: Self-service portal for signers +- **Mobile Responsive**: Optimized for all devices +- **Audit Trail**: Complete compliance logging with verification reports + +### Enterprise Benefits + +- **Scalability**: Handles thousands of concurrent signature requests +- **Security**: Bank-grade encryption and token-based authentication +- **Compliance**: Meets e-signature regulations (eIDAS, ESIGN Act) +- **Integration**: Seamless Dolibarr integration with existing workflows +- **Customization**: Configurable verification requirements per request +- **Multi-Entity**: Full support for Dolibarr multi-company setups + +## Architecture + +### System Components + +``` +┌─────────────────────────────────────────────────────┐ +│ Dolibarr Core │ +└─────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────┐ +│ MokoDoliSign Module │ +├─────────────────────────────────────────────────────┤ +│ Admin Interface │ Public Interface │ AJAX API │ +├─────────────────────────────────────────────────────┤ +│ Core Classes │ Email Service │ Cron Jobs │ +├─────────────────────────────────────────────────────┤ +│ Database Layer (MySQL/MariaDB) │ +└─────────────────────────────────────────────────────┘ +``` + +### Database Schema + +#### Tables + +1. **llx_mokodolisign_request** - Signature requests + - Primary workflow state management + - Document references and metadata + - Status tracking and dates + - Verification requirements + +2. **llx_mokodolisign_signer** - Signers + - Individual signer records + - Token-based authentication + - Signature and verification data + - Status and timestamps + +3. **llx_mokodolisign_event** - Audit log + - Complete event history + - IP and geolocation data + - User agent tracking + - Compliance records + +### Security Architecture + +- **Token Authentication**: 64-character unique tokens per signer +- **SQL Injection Prevention**: Parameterized queries and escaping +- **XSS Protection**: Output encoding and input sanitization +- **File Security**: Isolated storage directories with restricted access +- **Session Management**: Dolibarr's built-in session handling +- **HTTPS Required**: All signing operations require secure connection + +## Installation + +See [INSTALL.md](INSTALL.md) for detailed installation instructions. + +### Quick Start + +1. Copy module to `/custom/mokodolisign/` +2. Enable in Dolibarr admin +3. Configure permissions +4. Set up cron jobs +5. Configure email settings + +### System Requirements + +- Dolibarr 14.0 or higher +- PHP 7.4 or higher +- MySQL 5.7+ or MariaDB 10.3+ +- HTTPS/SSL certificate (required for production) +- Camera access for identity verification +- Geolocation API support in browsers + +### Dependencies + +- Dolibarr Core (included) +- TCPDF (included in Dolibarr) +- DolEditor (included in Dolibarr) +- CMailFile (included in Dolibarr) + +## Configuration + +### Module Settings + +Access: Home → MokoDoliSign → Setup + +#### Available Settings + +| Setting | Description | Default | +|---------|-------------|---------| +| MOKODOLISIGN_REQUIRE_DCM | Require Document Certification Mode | 1 | +| MOKODOLISIGN_CERT_QR_VERIFY | Enable QR code verification | 1 | +| MOKODOLISIGN_CONSENT_MODE | Consent mode (implicit/explicit) | implicit | +| MOKODOLISIGN_OTP_DEFAULT_MODE | OTP mode (smart/always/never) | smart | +| MOKODOLISIGN_DEFAULT_REQUIRE_SELFIE | Default selfie requirement | 0 | +| MOKODOLISIGN_DEFAULT_REQUIRE_ID | Default ID requirement | 0 | +| MOKODOLISIGN_DEFAULT_REQUIRE_INITIALS_EACH_PAGE | Require initials per page | 0 | +| MOKODOLISIGN_EMAIL_ATTACH_LIMIT_MB | Email attachment size limit | 15 | + +### Email Configuration + +Ensure Dolibarr email settings are configured: + +1. Home → Setup → Email +2. Configure SMTP settings +3. Set FROM email address +4. Test email delivery + +### Cron Jobs + +Add to system crontab: + +```bash +# Expire old requests (daily at 2 AM) +0 2 * * * cd /path/to/dolibarr/htdocs && php custom/mokodolisign/src/cron/expire.php + +# Send reminders (daily at 8 AM) +0 8 * * * cd /path/to/dolibarr/htdocs && php custom/mokodolisign/src/cron/remind.php + +# Purge old data (weekly on Sunday at 3 AM) +0 3 * * 0 cd /path/to/dolibarr/htdocs && php custom/mokodolisign/src/cron/purge.php +``` + +### Permissions + +Configure user permissions: + +- **Read**: View signature requests and history +- **Create**: Create new signature requests +- **Write**: Modify existing requests +- **Delete**: Delete draft requests +- **Admin**: Access setup and configuration + +## User Guide + +See detailed guides in: +- [Quick Start Guide](QUICK_START.md) - Get started in 5 minutes +- [User Guide](USER_GUIDE.md) - Complete user documentation +- [Administrator Guide](ADMIN_GUIDE.md) - Installation and configuration +- [Migration Guide](MIGRATION_GUIDE.md) - Module ID update guide +- [Integration Guide](INTEGRATION_GUIDE.md) + +## API Reference + +### AJAX Endpoints + +#### POST /custom/mokodolisign/src/ajax/sign.php + +Submit a signature. + +**Parameters:** +- `token` (required): Signer's unique token +- `signature` (required): Base64-encoded signature image +- `selfie` (optional): Base64-encoded selfie image +- `id_photo` (optional): Base64-encoded ID photo +- `geo_lat` (optional): GPS latitude +- `geo_lon` (optional): GPS longitude +- `geo_accuracy` (optional): GPS accuracy in meters + +**Response:** +```json +{ + "ok": true, + "message": "Signature saved successfully" +} +``` + +#### POST /custom/mokodolisign/src/ajax/decline.php + +Decline a signature request. + +**Parameters:** +- `token` (required): Signer's unique token +- `reason` (optional): Decline reason + +**Response:** +```json +{ + "ok": true, + "message": "Document declined and notifications sent" +} +``` + +#### GET /custom/mokodolisign/src/ajax/preview.php + +Preview request details. + +**Parameters:** +- `id` or `token`: Request ID or signer token + +**Response:** +```json +{ + "ok": true, + "ref": "SIG-000001", + "label": "Employment Agreement", + "description": "...", + "document_path": "SIG-000001/agreement.pdf", + "status": 1 +} +``` + +### PHP API + +#### MokoDoliSignRequest Class + +```php +// Create a new request +$request = new MokoDoliSignRequest($db); +$request->ref = $request->getNextNumRef(); +$request->label = "Contract Agreement"; +$request->description = "Terms and conditions..."; +$request->status = MokoDoliSignRequest::STATUS_DRAFT; +$request->require_selfie = 1; +$request->require_id = 1; +$request->date_expiry = strtotime('+30 days'); +$request->create($user); + +// Add a signer +$signer = new MokoDoliSignSigner($db); +$signer->fk_request = $request->rowid; +$signer->email = "john.doe@example.com"; +$signer->firstname = "John"; +$signer->lastname = "Doe"; +$signer->role = "Client"; +$signer->create(); + +// Send the request +$request->status = MokoDoliSignRequest::STATUS_PENDING; +$request->date_sent = dol_now(); +$request->update($user); + +// Send emails to signers (handled automatically) +``` + +## Security + +### Authentication + +- **Token-Based**: Each signer receives a unique 64-character token +- **Time-Limited**: Requests can expire automatically +- **Single-Use**: Tokens are tied to specific signers and requests +- **Secure Storage**: Tokens stored hashed in database + +### Data Protection + +- **Encryption in Transit**: HTTPS/TLS required for all operations +- **Encryption at Rest**: Database-level encryption recommended +- **File Storage**: Secure directories with restricted access +- **Photo Storage**: Separate verification directory +- **Audit Logging**: All actions logged with IP and timestamp + +### Input Validation + +- **SQL Injection**: All queries use parameterized statements +- **XSS Prevention**: Output encoding on all user content +- **File Upload**: Type and size validation +- **CSRF Protection**: Token validation on all forms + +### Best Practices + +1. **Use HTTPS**: Always use SSL/TLS certificates +2. **Regular Backups**: Daily database and file backups +3. **Update Regularly**: Keep Dolibarr and module updated +4. **Strong Passwords**: Enforce strong password policies +5. **Access Control**: Limit permissions to necessary users +6. **Monitor Logs**: Regular audit log review +7. **Secure Hosting**: Use reputable hosting providers +8. **Firewall Rules**: Restrict database access + +## Compliance + +### Legal Framework + +MokoDoliSign is designed to comply with: + +- **eIDAS** (EU Electronic Identification and Trust Services) +- **ESIGN Act** (US Electronic Signatures in Global and National Commerce Act) +- **UETA** (Uniform Electronic Transactions Act) +- **GDPR** (General Data Protection Regulation) + +### Audit Requirements + +The system provides: + +1. **Complete Audit Trail** + - All actions logged with timestamp + - IP address and geolocation data + - User agent information + - Verification photos + +2. **Non-Repudiation** + - Unique tokens per signer + - Cryptographic verification + - Immutable event log + - Timestamped signatures + +3. **Identity Verification** + - Optional selfie capture + - Optional ID document photo + - Email verification + - Multi-factor authentication support + +4. **Document Integrity** + - Original document preserved + - Signed copy generated + - Version control + - Tamper detection + +### Data Retention + +Configure retention policies in cron/purge.php: + +- **Active Requests**: Kept indefinitely +- **Completed Requests**: Configurable (default: 7 years) +- **Declined Requests**: Configurable (default: 1 year) +- **Audit Logs**: Kept with associated request + +### GDPR Compliance + +- **Right to Access**: Users can view their signature history +- **Right to Erasure**: Completed requests can be anonymized +- **Data Minimization**: Only necessary data collected +- **Consent**: Clear consent required for photo capture +- **Transparency**: Complete audit trail available + +## Troubleshooting + +### Common Issues + +#### Email Not Sending + +**Problem**: Signers not receiving email notifications + +**Solution**: +1. Check Dolibarr email configuration +2. Verify SMTP settings are correct +3. Check spam folders +4. Test email with Dolibarr's email test tool +5. Review email logs in Dolibarr + +#### Camera Not Working + +**Problem**: Camera doesn't start for selfie/ID capture + +**Solution**: +1. Ensure HTTPS is being used (required for camera access) +2. Grant camera permissions in browser +3. Check browser compatibility (modern browsers required) +4. Try different browser +5. Check camera is not in use by another app + +#### Signature Canvas Not Working on Mobile + +**Problem**: Can't draw signature on mobile device + +**Solution**: +1. Ensure touch events are enabled +2. Clear browser cache +3. Try in private/incognito mode +4. Update browser to latest version +5. Check screen orientation (portrait works best) + +#### Geolocation Not Captured + +**Problem**: GPS coordinates not being recorded + +**Solution**: +1. Grant location permissions in browser +2. Ensure device has GPS enabled +3. HTTPS required for geolocation API +4. Check browser compatibility +5. Note: User can deny location access + +#### Request Not Sending + +**Problem**: Can't send signature request to signers + +**Solution**: +1. Ensure at least one signer added +2. Check signer email addresses are valid +3. Verify request has document or description +4. Check user has 'create' permission +5. Review error messages in Dolibarr logs + +### Debug Mode + +Enable debug mode in Dolibarr: +1. Home → Setup → Other +2. Enable debug mode +3. Check logs in `documents/dolibarr.log` + +### Log Locations + +- **Dolibarr logs**: `documents/dolibarr.log` +- **Apache/nginx logs**: Check server configuration +- **PHP errors**: Check php error log +- **Cron output**: Check cron logs or redirect to file + +## Support + +### Documentation + +- [Quick Start Guide](QUICK_START.md) +- [User Guide](USER_GUIDE.md) +- [Administrator Guide](ADMIN_GUIDE.md) +- [Migration Guide](MIGRATION_GUIDE.md) +- [Integration Guide](INTEGRATION_GUIDE.md) +- [API Reference](API.md) +- [Module ID & Registry](MODULE_ID.md) +- [Installation Guide](INSTALL.md) + +### Community Support + +- **GitHub Issues**: https://github.com/mokoconsulting-tech/MokoDoliSign/issues +- **Discussions**: https://github.com/mokoconsulting-tech/MokoDoliSign/discussions +- **Dolibarr Forum**: https://www.dolibarr.org/forum/ + +### Commercial Support + +For enterprise support, custom development, or consulting: + +**Moko Consulting** +Email: hello@mokoconsulting.tech +Website: https://mokoconsulting.tech + +### Contributing + +We welcome contributions! Please see: +- [CONTRIBUTING.md](CONTRIBUTING) +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT) + +### License + +MokoDoliSign is licensed under GPL-3.0-or-later. +See [LICENSE](../LICENSE) for details. + +--- + +© 2025 Moko Consulting. All rights reserved. + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/ROADMAP.md b/MokoConsulting/MokoDoliSign/ROADMAP.md new file mode 100644 index 0000000..de84777 --- /dev/null +++ b/MokoConsulting/MokoDoliSign/ROADMAP.md @@ -0,0 +1,400 @@ +← [Home](Home) + +# MokoDoliSign 5-Year Product Roadmap + +**Last Updated:** January 2026 +**Vision:** Become the premier open-source e-signature solution for ERP/CRM platforms worldwide + +--- + +## Overview + +This roadmap outlines MokoDoliSign's evolution from an enterprise-ready Dolibarr e-signature module to a global leader in open-source digital signature solutions. Each year brings a major version release with significant new capabilities while maintaining our commitment to security, compliance, and user experience. + +### Release Cadence +- **Major Versions:** One per year (January) +- **Minor Updates:** Quarterly feature releases +- **Patch Releases:** Monthly security and bug fixes +- **LTS Support:** 2 years for each major version + +--- + +## Version 1.0.0 - Enterprise Ready (2026) + +**Release Date:** January 2026 (Planned) +**Theme:** Production-Ready Core Platform + +### Status: 🚧 In Development + +MokoDoliSign reaches enterprise readiness with battle-tested features and comprehensive compliance capabilities. + +### Key Features +- ✅ Complete e-signature workflow engine +- ✅ Multi-party signature support +- ✅ Identity verification (selfie + ID capture) +- ✅ Geolocation tracking +- ✅ Complete audit trails +- ✅ Email notifications system +- ✅ Customer portal +- ✅ Public verification portal +- ✅ PDF generation and management +- ✅ GDPR, eIDAS, ESIGN Act compliance + +### Technical Highlights +- Dolibarr 14+ compatibility +- PHP 7.4+ support +- Responsive mobile interface +- Touch-optimized signature canvas +- Cron automation (expire, remind, purge) + +### Goals for 2026 +- **Q1:** Production release and documentation +- **Q2:** Community building and adoption +- **Q3:** Performance optimization +- **Q4:** Security hardening and penetration testing + +--- + +## Version 2.0.0 - Advanced Integrations (2027) + +**Release Date:** January 2027 +**Theme:** Ecosystem Expansion + +### Vision +Expand beyond Dolibarr with deep integrations into the broader open-source ecosystem and enhanced API capabilities. + +### Planned Features + +#### API & Integrations +- 🔄 RESTful API for third-party integrations +- 🔄 Webhook system for real-time events +- 🔄 OAuth2 authentication support +- 🔄 Zapier/Make.com integration +- 🔄 WordPress plugin +- 🔄 Nextcloud integration +- 🔄 ERPNext compatibility layer + +#### Enhanced Signing +- 🔄 Bulk signing operations +- 🔄 Template library system +- 🔄 Advanced signature placement (drag-and-drop) +- 🔄 Multiple signature types (initial, stamp, full signature) +- 🔄 Form field support (text boxes, checkboxes, dates) + +#### Document Management +- 🔄 Version control for documents +- 🔄 Document templates with variables +- 🔄 Multi-language document support +- 🔄 Document merging and splitting +- 🔄 Cloud storage integration (S3, MinIO) + +#### User Experience +- 🔄 Progressive Web App (PWA) for mobile +- 🔄 Dark mode support +- 🔄 Accessibility improvements (WCAG 2.1 AA) +- 🔄 Multi-language interface (20+ languages) + +### Technical Goals +- Microservices architecture option +- PostgreSQL support +- Docker containerization +- Kubernetes deployment templates +- GraphQL API alongside REST + +--- + +## Version 3.0.0 - AI & Automation (2028) + +**Release Date:** January 2028 +**Theme:** Intelligent Document Processing + +### Vision +Leverage artificial intelligence to automate document preparation, reduce signing friction, and enhance security. + +### Planned Features + +#### AI-Powered Features +- 🤖 Automatic signature field detection +- 🤖 Document classification and routing +- 🤖 Smart template suggestions +- 🤖 Natural language processing for contract analysis +- 🤖 Anomaly detection in signing patterns +- 🤖 Predictive analytics for signing behavior + +#### Advanced Identity Verification +- 🔐 Biometric authentication (fingerprint, face ID) +- 🔐 ID document OCR and validation +- 🔐 Liveness detection for selfies +- 🔐 Government ID verification services integration +- 🔐 Blockchain-based identity verification + +#### Workflow Automation +- ⚙️ Visual workflow builder +- ⚙️ Conditional routing based on document content +- ⚙️ Auto-reminders with ML-optimized timing +- ⚙️ Smart document expiration management +- ⚙️ Automated compliance checking + +#### Security Enhancements +- 🛡️ Advanced fraud detection +- 🛡️ Machine learning for anomaly detection +- 🛡️ Encrypted blockchain anchoring +- 🛡️ Zero-knowledge proof signatures +- 🛡️ Quantum-resistant cryptography research + +### Technical Goals +- Python ML microservices +- TensorFlow/PyTorch models +- Redis caching layer +- ElasticSearch for advanced search +- Real-time analytics dashboard + +--- + +## Version 4.0.0 - Global Compliance & Scale (2029) + +**Release Date:** January 2029 +**Theme:** Worldwide Enterprise Deployment + +### Vision +Support global enterprises with region-specific compliance, massive scale, and advanced governance features. + +### Planned Features + +#### Global Compliance +- 🌍 EU Digital Identity Wallet support +- 🌍 Country-specific e-signature regulations (100+ countries) +- 🌍 Qualified electronic signatures (QES) +- 🌍 Time-stamping authority integration +- 🌍 Industry-specific compliance (HIPAA, SOX, etc.) +- 🌍 Long-term archival (10+ years) + +#### Enterprise Features +- 🏢 Multi-tenant architecture +- 🏢 Role-based access control (RBAC) +- 🏢 Single Sign-On (SSO) - SAML, LDAP, Active Directory +- 🏢 Enterprise reporting and dashboards +- 🏢 SLA management and monitoring +- 🏢 White-label capabilities +- 🏢 Custom branding per entity + +#### Scale & Performance +- 📈 Horizontal scaling support +- 📈 Load balancing and high availability +- 📈 Database sharding +- 📈 CDN integration for global delivery +- 📈 Support for 1M+ concurrent users +- 📈 99.99% uptime SLA + +#### Advanced Features +- 📝 Video-based signature capture +- 📝 Voice signature authentication +- 📝 Smart contracts integration +- 📝 Digital asset signing (NFTs, crypto wallets) +- 📝 IoT device signatures + +### Technical Goals +- Multi-region deployment +- Global CDN integration +- Advanced monitoring (Prometheus, Grafana) +- Distributed tracing (Jaeger) +- Cloud-native architecture (AWS, Azure, GCP) + +--- + +## Version 5.0.0 - Next Generation Platform (2030) + +**Release Date:** January 2030 +**Theme:** Future of Digital Trust + +### Vision +Pioneer the future of digital signatures with cutting-edge technology, decentralization, and universal interoperability. + +### Planned Features + +#### Decentralized Architecture +- ⛓️ Full blockchain integration +- ⛓️ Decentralized identity (DID) support +- ⛓️ Self-sovereign identity (SSI) +- ⛓️ Distributed ledger for audit trails +- ⛓️ Smart contract-based signatures +- ⛓️ Cross-chain signature verification + +#### Universal Interoperability +- 🔗 Universal signature format (pan-industry standard) +- 🔗 Cross-platform signature verification +- 🔗 Integration with all major ERP/CRM systems +- 🔗 Document portability and migration tools +- 🔗 Standards-based APIs (OpenAPI 4.0+) + +#### Next-Gen User Experience +- 🚀 AR/VR signing interfaces +- 🚀 Voice-controlled workflows +- 🚀 Neural interface research +- 🚀 Holographic signature capture +- 🚀 Quantum-secure signatures +- 🚀 Real-time collaborative signing + +#### Environmental & Social +- 🌱 Carbon-neutral operations +- 🌱 Green hosting initiatives +- 🌱 Accessibility for all (universal design) +- 🌱 Education and training programs +- 🌱 Open-source ecosystem fund + +#### Advanced Security +- 🔒 Post-quantum cryptography +- 🔒 Homomorphic encryption for privacy +- 🔒 Zero-trust architecture +- 🔒 AI-powered threat detection +- 🔒 Autonomous security responses + +### Technical Goals +- Serverless architecture options +- Edge computing support +- Quantum computing readiness +- Web3 integration +- Metaverse presence + +--- + +## Cross-Cutting Initiatives (2026-2030) + +These initiatives span multiple versions and continue throughout the roadmap: + +### Security & Compliance +- Continuous security audits +- Penetration testing (quarterly) +- Bug bounty program +- SOC 2 Type II certification +- ISO 27001 compliance +- Regular compliance updates + +### Community & Ecosystem +- Monthly webinars and training +- Annual conference (MokoSign Summit) +- Developer certification program +- Partner ecosystem development +- Open-source contributions +- Documentation in 30+ languages + +### Performance & Reliability +- 99.9% → 99.99% uptime progression +- Response time < 200ms (p95) +- Continuous performance optimization +- Automated testing (unit, integration, e2e) +- Chaos engineering practices + +### User Experience +- User research and testing programs +- Quarterly UX improvements +- Mobile-first design evolution +- Progressive enhancement +- Accessibility improvements + +--- + +## Technology Stack Evolution + +### Current (v1.0) +- PHP 7.4+, MySQL/MariaDB +- Dolibarr framework +- TCPDF, jQuery +- HTML5 Canvas + +### Near Future (v2.0-3.0) +- PHP 8.2+, PostgreSQL support +- Modern JavaScript (Vue.js/React) +- Docker, Kubernetes +- GraphQL, WebSockets +- Python ML services + +### Long Term (v4.0-5.0) +- Microservices architecture +- Blockchain integration +- Edge computing +- AI/ML at scale +- Quantum-resistant crypto + +--- + +## Success Metrics + +### Adoption Targets +- **2026:** 1,000 active installations +- **2027:** 5,000 active installations +- **2028:** 25,000 active installations +- **2029:** 100,000 active installations +- **2030:** 500,000 active installations + +### Community Growth +- **2026:** 100 GitHub stars, 10 contributors +- **2027:** 500 GitHub stars, 50 contributors +- **2028:** 2,000 GitHub stars, 200 contributors +- **2029:** 5,000 GitHub stars, 500 contributors +- **2030:** 10,000 GitHub stars, 1,000+ contributors + +### Document Volume +- **2026:** 100K documents signed +- **2027:** 1M documents signed +- **2028:** 10M documents signed +- **2029:** 100M documents signed +- **2030:** 1B+ documents signed + +--- + +## Contributing to the Roadmap + +This roadmap is a living document. We welcome community input and contributions. + +### How to Contribute +1. **Feature Requests:** Open an issue on GitHub +2. **Discussions:** Join our community forums +3. **Voting:** Participate in quarterly priority voting +4. **Code:** Submit PRs for roadmap features +5. **Feedback:** Share your use cases and needs + +### Contact +- 📧 Email: hello@mokoconsulting.tech +- 💬 GitHub Discussions: [mokoconsulting-tech/MokoDoliSign](https://github.com/mokoconsulting-tech/MokoDoliSign/discussions) +- 🌐 Website: https://mokoconsulting.tech + +--- + +## Legal & Licensing + +MokoDoliSign remains committed to open source: +- **License:** GPL-3.0-or-later +- **Commercial Support:** Available through Moko Consulting +- **Enterprise Edition:** Optional paid features (2028+) +- **Community Edition:** Always free and open source + +--- + +## Revision History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | January 2026 | Initial 5-year roadmap created | + +--- + +**Note:** This roadmap represents our current vision and is subject to change based on community feedback, market conditions, and technological advances. Features and timelines may be adjusted as we progress. + +--- + +
+ +**Made with ❤️ by [Moko Consulting](https://mokoconsulting.tech)** + +*Building the future of digital trust, one signature at a time.* + +
+ +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/STRUCTURE.md b/MokoConsulting/MokoDoliSign/STRUCTURE.md new file mode 100644 index 0000000..290905c --- /dev/null +++ b/MokoConsulting/MokoDoliSign/STRUCTURE.md @@ -0,0 +1,113 @@ +← [Home](Home) + +# Repository Structure + +This document describes the organization of the MokoDoliSign repository. + +## Overview + +The repository is structured to separate deployable code from documentation and configuration: + +``` +mokodolisign/ +├── src/ # All deployable code for the Dolibarr module +├── docs/ # Documentation files +├── README.md # Main project documentation +├── INSTALL.md # Installation instructions +├── CONTRIBUTING.md # Contribution guidelines +├── CODE_OF_CONDUCT.md # Code of conduct +├── CHANGELOG.md # Version history +├── LICENSE # License information +└── [configuration files] # .gitignore, .editorconfig, etc. +``` + +## Deployable Code (`src/`) + +The `src/` directory contains all code that is deployed as part of the Dolibarr module: + +``` +src/ +├── admin/ # Admin interface pages (setup, configuration) +├── ajax/ # AJAX endpoints for client-side interactions +├── class/ # PHP classes (Request, Signer, Event) +├── core/ # Core module files +│ ├── modules/ # Module descriptor (modMokoDoliSign.class.php) +│ └── triggers/ # Dolibarr triggers +├── cron/ # Cron job scripts (expire, remind, purge) +├── css/ # Stylesheets +├── js/ # JavaScript files +├── langs/ # Language translation files +├── lib/ # Library files +├── public/ # Public-facing pages (sign, verify, portal) +├── request/ # Request management pages (list, card) +└── sql/ # Database schema files +``` + +## Documentation (`docs/`) + +The `docs/` directory contains comprehensive documentation: + +- `README.md` - Enterprise documentation overview +- `USER_GUIDE.md` - End-user documentation +- `ADMIN_GUIDE.md` - Administrator guide +- `API.md` - API reference for developers + +## Path References + +### In PHP Code + +All path references in the PHP code have been updated to include `/src`: + +```php +// Absolute paths (Dolibarr paths) +'/mokodolisign/src/public/sign.php' +'/mokodolisign/src/ajax/sign.php' +'/mokodolisign/src/admin/setup.php' + +// Relative paths (still work within src/) +__DIR__.'/../class/mokodolisignrequest.class.php' +``` + +### In Documentation + +All documentation references have been updated: + +``` +# Cron jobs +php custom/mokodolisign/src/cron/expire.php + +# URLs +https://example.com/custom/mokodolisign/src/public/sign.php?token=... + +# File paths +require_once __DIR__.'/custom/mokodolisign/src/class/mokodolisignrequest.class.php'; +``` + +## Why This Structure? + +This structure provides several benefits: + +1. **Clear Separation**: Deployable code is clearly separated from documentation and configuration +2. **Better Organization**: Documentation and scripts are easily accessible at the root level +3. **Standard Practice**: Follows common open-source repository patterns +4. **Maintainability**: Easier to navigate and maintain the codebase +5. **Deployment**: Clear understanding of what needs to be deployed vs. what is for reference + +## Migration Notes + +If you have an existing installation, note that: + +1. All module files are now in the `src/` subdirectory +2. URLs to public pages need to include `/src` in the path +3. Cron job paths need to be updated to include `/src` +4. Any custom integrations should update their paths accordingly + +The module itself handles path resolution internally, so most users will only need to update external references (cron jobs, direct URL bookmarks, etc.). + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/USER_GUIDE.md b/MokoConsulting/MokoDoliSign/USER_GUIDE.md new file mode 100644 index 0000000..247b616 --- /dev/null +++ b/MokoConsulting/MokoDoliSign/USER_GUIDE.md @@ -0,0 +1,378 @@ +← [Home](Home) + +# MokoDoliSign User Guide + +## Getting Started + +This guide will help you create, send, and manage electronic signature requests. + +## Table of Contents + +1. [Creating a Signature Request](#creating-a-signature-request) +2. [Adding Signers](#adding-signers) +3. [Sending for Signature](#sending-for-signature) +4. [Tracking Status](#tracking-status) +5. [Signing Documents](#signing-documents) +6. [Verification](#verification) +7. [Customer Portal](#customer-portal) + +## Creating a Signature Request + +### Step 1: Access MokoDoliSign + +1. Log in to Dolibarr +2. Navigate to **MokoDoliSign** in the main menu +3. Click **Requests → New** + +### Step 2: Fill in Request Details + +#### Required Fields + +- **Label**: Title of the document (e.g., "Employment Agreement - John Doe") + +#### Optional Fields + +- **Description / Agreement Text**: Use the rich text editor to create your agreement + - Format text with bold, italic, lists + - Add links and images + - Create professional-looking agreements + +- **Upload Document**: Alternative to typing agreement + - Supported formats: PDF, DOC, DOCX + - Max size: Configurable (default 15MB) + - Click "Choose File" and select your document + +- **Document Path**: If document already exists in Dolibarr + - Enter relative path to existing document + - Example: `produit/document/contract.pdf` + +- **Expiry Date**: When the request should expire + - Default: 30 days from creation + - Expired requests automatically marked as expired + +#### Verification Options + +Choose identity verification requirements: + +- ☑ **Require signer photo (selfie)** + - Signer must take selfie using camera + - Photo stored with signature + - Recommended for high-value agreements + +- ☑ **Require ID photo** + - Signer must photograph ID document + - Both sides can be captured + - Recommended for legal compliance + +### Step 3: Save Request + +Click **Save** to create the request in draft mode. + +## Adding Signers + +### Required Information + +For each signer, provide: + +- **Email** (required): Where signing link will be sent +- **First Name**: Signer's first name +- **Last Name**: Signer's last name +- **Role**: Their role (e.g., "Employee", "Witness", "Manager") + +### Adding Multiple Signers + +1. Fill in signer information +2. Click **Add Signer** +3. Repeat for additional signers +4. Each signer gets a unique secure token + +### Signer Order + +Signers are listed in the order added. While all receive emails simultaneously, you can track who signed first in the audit log. + +## Sending for Signature + +### Before Sending + +Verify: +- ✓ All required fields completed +- ✓ Document or description provided +- ✓ All signers added +- ✓ Verification options set correctly +- ✓ Expiry date appropriate + +### Send Process + +1. Click **Send** button +2. System will: + - Generate PDF if only description provided + - Change status to "Pending" + - Send email to each signer + - Log event in audit trail + +### What Signers Receive + +Each signer receives an email containing: +- Request title and description +- Unique signing link +- Expiry date (if set) +- Instructions for signing + +**Example Email:** +``` +Subject: [Your Company] Signature Request: Employment Agreement + +Hello John Doe, + +You have been requested to sign the following document: +Employment Agreement + +[Description if provided] + +Please click the following link to review and sign: +https://your-dolibarr.com/custom/mokodolisign/src/public/sign.php?token=abc123... + +This link is unique to you and should not be shared. + +Best regards, +Your Company +``` + +## Tracking Status + +### Request Statuses + +| Status | Description | Actions Available | +|--------|-------------|-------------------| +| Draft | Being prepared | Edit, Add Signers, Send, Delete | +| Pending | Sent, awaiting signatures | View, Cancel | +| In Progress | Some signers have signed | View, Send Reminders | +| Completed | All signers have signed | View, Download | +| Declined | A signer declined | View | +| Expired | Past expiry date | View, Resend | +| Cancelled | Manually cancelled | View | + +### Signer Statuses + +| Status | Description | +|--------|-------------| +| Pending | Email sent, not yet viewed | +| Viewed | Opened signing page | +| Signed | Completed signature | +| Declined | Refused to sign | + +### Viewing Request Details + +Click on any request to see: +- Current status +- Document information +- List of signers and their status +- Complete event history +- Verification photos (if captured) + +## Signing Documents + +### Accessing the Signing Page + +Signers can access via: +1. **Email link**: Click link in email notification +2. **Customer portal**: Enter email at portal page +3. **Direct link**: If token is known + +### Signing Process + +#### Step 1: Review Document + +- Read the document carefully +- View any descriptions or terms +- Check expiry date + +#### Step 2: Identity Verification (if required) + +**For Selfie:** +1. Click "Start Camera" +2. Allow camera access when prompted +3. Position face in frame +4. Click "Capture" +5. Review photo, click "Retake" if needed + +**For ID Photo:** +1. Click "Start Camera" +2. Allow camera access +3. Position ID document in frame +4. Ensure text is readable +5. Click "Capture" +6. Review photo, click "Retake" if needed + +#### Step 3: Draw Signature + +1. Use mouse or finger to draw signature +2. Signature appears in canvas +3. Click "Clear" to start over if needed +4. Make signature clear and legible + +#### Step 4: Submit + +1. Click "Sign Document" +2. Browser may request location access (optional) +3. System captures: + - Signature + - Verification photos (if required) + - IP address + - GPS coordinates (if allowed) + - Timestamp +4. Confirmation message appears +5. Email sent to all signers when completed + +### Declining to Sign + +If you need to decline: + +1. Click "Decline" button +2. Confirm you want to decline +3. Optionally provide reason +4. System will: + - Mark request as declined + - Notify all other signers + - Include your reason in notification + - Log event in audit trail + +## Verification + +Anyone can verify a signed document using the verification page. + +### Verification URL + +``` +https://your-dolibarr.com/custom/mokodolisign/src/public/verify.php?d=REF +``` + +Replace `REF` with the request reference (e.g., SIG-000001) + +### Verification Page Shows + +1. **Document Status** + - Current status + - Completion date + +2. **Signer Information** + - All signers listed + - Status of each signer + - Date signed + - Verification photos (if captured) + +3. **Audit Trail** + - Complete event history + - Timestamps for all actions + - IP addresses + - Geolocation data (if captured) + - Who performed each action + +### Public Verification + +The verification page is public, allowing: +- Third parties to verify authenticity +- Legal compliance verification +- Dispute resolution +- Audit purposes + +## Customer Portal + +### Accessing the Portal + +Visit: +``` +https://your-dolibarr.com/custom/mokodolisign/src/public/portal.php +``` + +### Using the Portal + +1. Enter your email address +2. Click "Search" +3. View all signature requests for your email +4. See status of each request +5. Click "Sign Now" for pending requests +6. Click "View" for completed requests + +### Portal Features + +- **No Login Required**: Just need email address +- **All Requests**: See complete history +- **Direct Access**: Quick links to sign or view +- **Mobile Friendly**: Works on all devices +- **Status Indicators**: Clear visual status + +## Tips for Success + +### For Request Creators + +1. **Clear Titles**: Use descriptive labels +2. **Complete Information**: Provide full context in description +3. **Appropriate Expiry**: Give signers enough time +4. **Right Verification**: Choose verification level appropriately +5. **Test First**: Try the process yourself with a test request +6. **Monitor Status**: Check regularly for completion + +### For Signers + +1. **Read Carefully**: Review entire document before signing +2. **Good Lighting**: Ensure good lighting for photos +3. **Clear Signature**: Make signature legible +4. **Allow Location**: Helps with legal compliance +5. **Save Confirmation**: Keep confirmation email +6. **Verify Completion**: Use verification page to confirm + +### Best Practices + +1. **Professional Language**: Use business-appropriate tone +2. **Mobile Testing**: Test on mobile devices +3. **Email Deliverability**: Check spam folders +4. **Backup Documents**: Keep copies of signed documents +5. **Regular Audits**: Review audit trails periodically + +## Troubleshooting + +### Can't Send Email + +- Check email address is valid +- Verify SMTP configuration +- Check spam folder +- Contact administrator + +### Camera Not Working + +- Ensure HTTPS is used +- Grant camera permissions +- Try different browser +- Check camera isn't in use + +### Signature Not Saving + +- Ensure signature is drawn +- Check internet connection +- Try refreshing page +- Contact support if persists + +### Request Expired + +- Contact request creator +- Request may need to be resent +- Check expiry date settings + +## Need Help? + +- **Documentation**: See [Enterprise Documentation](README.md) +- **Administrator**: Contact your Dolibarr administrator +- **Support**: hello@mokoconsulting.tech + +--- + +© 2025 Moko Consulting + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliSign/update-server.-.-.md b/MokoConsulting/MokoDoliSign/update-server.-.-.md new file mode 100644 index 0000000..99b1fd9 --- /dev/null +++ b/MokoConsulting/MokoDoliSign/update-server.-.-.md @@ -0,0 +1,64 @@ +← [Home](Home) + +# Dolibarr Update Server + +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +This document explains how `update.txt` is automatically managed for this Dolibarr module. + +## How It Works + +Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline. + +### Automatic Generation + +| Event | Workflow | `update.txt` Content | `$this->version` | +|-------|----------|---------------------|-------------------| +| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version | +| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` | +| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version | + +### Module Descriptor + +The `url_last_version` in your module descriptor should point to: + +``` +https://raw.githubusercontent.com/mokoconsulting-tech/MokoDoliSign/main/update.txt +``` + +This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it. + +### Branch Lifecycle + +``` +dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX +(development) (release candidate) (stable release) (frozen snapshot) +``` + +1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development` +2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC +3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch +4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed + +### Health Checks + +The `repo_health.yml` workflow verifies on every commit: + +- `update.txt` exists in the repository root +- Module descriptor (`mod*.class.php`) exists in `src/core/modules/` +- `$this->numero` is set and non-zero +- `$this->version` is not hardcoded (should be set by workflow) +- `url_last_version` points to `update.txt` (not `update.json`) +- `url_last_version` references `/main/` branch on the main branch + +--- + +*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.* + +--- + +*Repo: [MokoDoliSign](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliSign) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/Home.md b/MokoConsulting/MokoDoliTraining/Home.md new file mode 100644 index 0000000..d14c86b --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/Home.md @@ -0,0 +1,44 @@ +# MokoDoliTraining + +A deployable module to install training data into Dolibarr and reset on command. + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [guide installation](guide-installation.-.-) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [api manifest](api-manifest.-.-) | ← [Home](Home) | +| [api module class](api-module-class.-.-) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [guide backup recovery](guide-backup-recovery.-.-) | ← [Home](Home) | +| [guide seed reset](guide-seed-reset.-.-) | ← [Home](Home) | +| [policy enforcement levels](policy-enforcement-levels.-.-) | ← [Home](Home) | +| [policy file header standards](policy-file-header-standards.-.-) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoDoliTraining/api-manifest.-.-.md b/MokoConsulting/MokoDoliTraining/api-manifest.-.-.md new file mode 100644 index 0000000..f006202 --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/api-manifest.-.-.md @@ -0,0 +1,81 @@ +← [Home](Home) + +## `manifest.json` — Schema and Usage + +**File:** `src/sql/manifest.json` + +### Purpose + +`manifest.json` is the authoritative record of every row inserted by `mokotraining.sql`. It is used by: + +- `mokotraining_reset.sql` — to target exact rowids in DELETE statements +- `modMokoDoliTraining::getManifest()` — to expose the index to the admin UI +- The admin page manifest table — so facilitators can audit what is loaded + +### Schema + +```json +{ + "module": "MokoDoliTraining", + "id": 185068, + "tables": { + "llx_table_name": [50, 51, 52], + "llx_another_table": [60, 61] + } +} +``` + +| Field | Type | Description | +|---|---|---| +| `module` | string | Module name | +| `id` | int | Dolibarr module ID | +| `tables` | object | Keys are table names; values are sorted int arrays of rowids | + +### Stats (current seed) + +- Tables tracked: 49 +- Total rows: 740 + +### Regeneration + +After any change to `mokotraining.sql`, regenerate the manifest: + +```bash +python3 docs/scripts/gen_manifest.py src/sql/mokotraining.sql > src/sql/manifest.json +``` + +Then update `mokotraining_reset.sql` to include any new rowids, and document the change in `CHANGELOG.md`. + +### Junction tables + +`llx_categorie_societe` and `llx_categorie_product` have no `rowid` column. Their manifest entries list `fk_categorie` values rather than rowids. The reset script handles these with `DELETE WHERE fk_categorie IN (...)`. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | API Reference | +| Domain | Dolibarr Module | +| Applies To | MokoDoliTraining v1.x | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/api/manifest.md | +| Version | 01.00.00 | +| Status | Draft | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | — | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/api-module-class.-.-.md b/MokoConsulting/MokoDoliTraining/api-module-class.-.-.md new file mode 100644 index 0000000..20fa461 --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/api-module-class.-.-.md @@ -0,0 +1,87 @@ +← [Home](Home) + +## `modMokoDoliTraining` — API Reference + +**File:** `src/core/modules/modMokoDoliTraining.class.php` +**Extends:** `DolibarrModules` +**Module ID:** `185068` + +### Constructor properties + +| Property | Type | Value | +|---|---|---| +| `numero` | int | 185068 | +| `rights_class` | string | `mokodolitraining` | +| `family` | string | `mokoconsulting` | +| `module_position` | int | 2 | +| `version` | string | `development` | +| `depends` | array | `['modMokoCRM']` | +| `picto` | string | `technic` | +| `editor_squarred_logo` | string | `favicon_256@mokodolitraining` | + +### Constants registered (`$this->const`) + +| Constant | Type | Default | Description | +|---|---|---|---| +| `MOKODOLITRAINING_VERSION` | chaine | `1.0.0` | Dataset version | +| `MOKODOLITRAINING_SEEDED` | chaine | `0` | `1` if seed has been run | +| `MOKODOLITRAINING_SEED_DATE` | chaine | `` | Timestamp of last seed | +| `MOKODOLITRAINING_RESET_DATE` | chaine | `` | Timestamp of last reset | + +### Static methods + +#### `getManifest(): array` + +Reads `src/sql/manifest.json` and returns the `tables` key as an associative array of `table_name => int[]` rowid lists. Returns `[]` if the file does not exist. + +#### `getSeedSqlPath(): string` + +Returns the absolute filesystem path to `src/sql/mokotraining.sql`. + +#### `getResetSqlPath(): string` + +Returns the absolute filesystem path to `src/sql/mokotraining_reset.sql`. + +#### `getManifestSummary(): array` + +Returns `['tables' => int, 'rows' => int]` — a count of tracked tables and total tracked rows. + +### Instance methods + +#### `init(string $options = ''): int` + +Called by Dolibarr when the module is enabled. Loads tables via `_load_tables()` and seeds the `MOKODOLITRAINING_SEEDED` constant. Returns `1` on success, `0` on failure. + +#### `remove(string $options = ''): int` + +Called by Dolibarr when the module is disabled. Always returns `1`. Training data is not auto-deleted on disable — use the Reset action from the admin page. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | API Reference | +| Domain | Dolibarr Module | +| Applies To | MokoDoliTraining v1.x | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/api/module-class.md | +| Version | 01.00.00 | +| Status | Draft | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | — | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/guide-backup-recovery.-.-.md b/MokoConsulting/MokoDoliTraining/guide-backup-recovery.-.-.md new file mode 100644 index 0000000..5aa026b --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/guide-backup-recovery.-.-.md @@ -0,0 +1,237 @@ +← [Home](Home) + +## Backup and Recovery + +### Backup types + +MokoDoliTraining maintains two categories of backup file. + +**Rollback backup** (`rollback_*.php`) is a full-database dump. It is created in two situations: + +- Automatically when the module activates (before the activation snapshot). +- When the facilitator clicks **Install Training Records** (before the seed runs). + +A rollback backup contains every table and every row in the Dolibarr database at the moment it was taken. It is the authoritative recovery point for returning the environment to a pre-training state. The dump is produced by Dolibarr's own `Utils::dumpDatabase()` with `type=mysqlnobin` (PHP-based, no `mysqldump` binary required), which outputs `DROP TABLE IF EXISTS` + `CREATE TABLE` + batched `INSERT INTO` per table. + +**Snapshot backup** (`snapshot_*.php`) is a manifest-scoped dump. It is created when **Install Training Records** completes. A snapshot contains only the rows defined in `manifest.json` -- the exact training dataset in its freshly seeded state, using `INSERT ... ON DUPLICATE KEY UPDATE`. It does not include DDL. It is used by **Reset to Snapshot** to quickly restore training data between sessions without touching any other tables. + +### File layout + +All backup files are stored in `src/backup/`: + +``` +src/backup/ + .htaccess Apache deny-all (HTTP access blocked) + index.php Directory stub (returns 403) + .lock Created during operations; auto-deleted on completion + rollback_20260313_120000.php Full-database backup (PHP-wrapped) + rollback_20260313_120000.php.sha256 + snapshot_20260313_120100.php Manifest-scoped backup (PHP-wrapped) + snapshot_20260313_120100.php.sha256 +``` + +The filename format is `{type}_{YYYYMMDD}_{HHMMSS}.php`. The `.php.sha256` sidecar holds the SHA-256 hash of the complete file content (including the PHP guard line) and is used to verify file integrity before any restore. + +### HTTP access protection (PHP wrapper) + +Every backup file opens with a PHP die guard: + +```php + +-- MokoDoliTraining FULL backup: rollback | 2026-03-13T12:00:00+00:00 +... +``` + +If a backup file is accessed via HTTP (for example by a misconfigured web server that ignores `.htaccess`), PHP executes the file and terminates immediately with no output. The SQL content is never sent to the browser. + +This is a defence-in-depth measure. The `.htaccess` deny-all rule is the primary control; the PHP guard is the fallback. Together they ensure backup files are not accessible over HTTP under any normal web server configuration. + +When the backup class reads a file internally (via `file()` or `file_get_contents()`), the PHP guard line is skipped. In `execSqlFile()`, any line starting with ` Settings > Maximum backups per type**. The minimum enforced value is 2. + +### Recovery procedures + +#### Procedure 1: Restore training data between sessions + +1. Navigate to **Setup > MokoDoliTraining**. +2. Click **Reset to Snapshot**. +3. Confirm the prompt. +4. Wait for the success messages: reset OK + restore OK. +5. Verify the dashboard **Status** badge shows *Seeded*. + +#### Procedure 2: Full environment rollback + +1. Navigate to **Setup > MokoDoliTraining**. +2. Click **Rollback to Pre-Install State**. +3. Confirm the prompt. +4. Wait for the success messages. +5. Verify the dashboard **Status** badge shows *Not Seeded*. +6. Run **Install Training Records** again to reload the training dataset. + +#### Procedure 3: Restore from a specific backup file + +1. Navigate to the **Backups** tab. +2. Locate the target backup in the list. +3. Click the verify icon (checkmark) to confirm integrity. +4. If integrity passes, click the restore icon (refresh). +5. Confirm the prompt. + +#### Procedure 4: CLI recovery (admin UI unavailable) + +Backup files contain a PHP guard line that must be stripped before piping to MySQL: + +```bash +cd /path/to/dolibarr/htdocs/custom/mokodolitraining + +# Strip PHP guard and restore +tail -n +2 backup/rollback_20260313_120000.php \ + | mysql -u root -p dolibarr + +# Or reset training rows first, then restore snapshot +mysql -u root -p dolibarr < sql/mokotraining_reset.sql +tail -n +2 backup/snapshot_20260313_120100.php \ + | mysql -u root -p dolibarr +``` + +After CLI recovery, update the seeded state constant: + +```sql +UPDATE llx_const SET value = '0' +WHERE name = 'MOKODOLITRAINING_SEEDED' AND entity = 1; + +UPDATE llx_const SET value = NOW() +WHERE name = 'MOKODOLITRAINING_RESET_DATE' AND entity = 1; +``` + +### Downloading backups + +The **Backups** tab provides a download button for each file. The download handler (`admin/download.php`): + +1. Validates the filename against the expected pattern (`rollback_` or `snapshot_` + timestamp + `.php`). +2. Runs an integrity check before serving. +3. Strips the PHP guard line from the file content. +4. Renames the download from `.php` to `.sql` so it opens correctly in SQL editors. + +The file delivered to the browser is clean SQL with no PHP wrapper. + +### Locking + +The module uses a `.lock` file to prevent concurrent operations. A lock older than 300 seconds is considered stale and broken automatically. + +To clear a stale lock manually: + +```bash +rm htdocs/custom/mokodolitraining/backup/.lock +``` + +After clearing the lock, verify the database is in a consistent state before running another operation. Check the **Audit Log** tab for the interrupted operation's partial log entry. + +### Security + +Backup files contain full database content including user credentials (hashed), contact records, and configuration values. + +Three layers of access control protect them: + +1. **PHP guard** -- `` at the top of every backup file. Terminates execution if accessed via HTTP. +2. **`.htaccess`** -- Apache deny-all rule blocks direct HTTP access to the `backup/` directory. +3. **`index.php` stub** -- Returns 403 for any directory listing attempt. + +For Nginx, add an equivalent location block since Nginx does not process `.htaccess` files: + +```nginx +location ~* /mokodolitraining/backup/ { + deny all; + return 403; +} +``` + +## Metadata + +| Field | Value | +|---|---| +| Document Type | Guide | +| Domain | Dolibarr Module | +| Applies To | MokoDoliTraining v1.x | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/guide/backup-recovery.md | +| Version | 01.01.00 | +| Status | Active | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | -- | +| 2026-03-13 | jmiller | v01.01.00 | PHP wrapper pattern; .php extension; CLI tail -n +2 strip; download handler docs; Nginx note | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/guide-installation.-.-.md b/MokoConsulting/MokoDoliTraining/guide-installation.-.-.md new file mode 100644 index 0000000..41904d5 --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/guide-installation.-.-.md @@ -0,0 +1,67 @@ +← [Home](Home) + +## Installation + +### Requirements + +- Dolibarr v23+ +- MokoCRM module active +- MySQL 8.0+ or MariaDB 10.5+ +- Dolibarr admin access + +### Deploy + +Copy `src/` into `htdocs/custom/` and rename the folder to `mokodolitraining`: + +```bash +cp -r src/ /path/to/dolibarr/htdocs/custom/mokodolitraining +``` + +For development, use a symlink instead: + +```bash +ln -s "$(pwd)/src" /path/to/dolibarr/htdocs/custom/mokodolitraining +``` + +### Enable in Dolibarr + +1. Log in as an administrator. +2. Go to **Setup > Modules/Applications**. +3. Locate **MokoDoliTraining** under the *Moko Consulting* family. +4. Click **Enable**. + +Dolibarr will refuse to enable the module if MokoCRM is not already active. + +### Verify + +After enabling, navigate to **Setup > MokoDoliTraining**. The admin page should load with the manifest table visible and the Seed / Reset buttons present. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | Guide | +| Domain | Dolibarr Module | +| Applies To | MokoDoliTraining v1.x | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/guide/installation.md | +| Version | 01.00.00 | +| Status | Draft | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | — | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/guide-seed-reset.-.-.md b/MokoConsulting/MokoDoliTraining/guide-seed-reset.-.-.md new file mode 100644 index 0000000..d63e801 --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/guide-seed-reset.-.-.md @@ -0,0 +1,65 @@ +← [Home](Home) + +## Seed and Reset + +### Seeding + +Go to **Setup > MokoDoliTraining** and click **Seed Training Data**. + +The seed operation executes `src/sql/mokotraining.sql` against the active database. Every statement uses `ON DUPLICATE KEY UPDATE`, so running the seed more than once is safe — existing rows are refreshed, not duplicated. + +On success, the page reports the number of statements executed and sets the `MOKODOLITRAINING_SEEDED` constant to `1` and records the timestamp in `MOKODOLITRAINING_SEED_DATE`. + +### Resetting + +Click **Reset Training Data** on the same page. + +The reset operation executes `src/sql/mokotraining_reset.sql`, which contains 49 `DELETE` statements ordered from child tables to parent tables with `FOREIGN_KEY_CHECKS = 0` wrapping the block. All rowids listed in `manifest.json` are targeted. + +On success, `MOKODOLITRAINING_SEEDED` is set to `0` and `MOKODOLITRAINING_RESET_DATE` is updated. + +### CLI alternative + +Both operations can be run directly via the MySQL CLI: + +```bash +# Seed +mysql -u root -p dolibarr < src/sql/mokotraining.sql + +# Reset +mysql -u root -p dolibarr < src/sql/mokotraining_reset.sql +``` + +### Manifest + +`src/sql/manifest.json` lists every table and rowid inserted by the seed. It is used by the reset script and by the admin page manifest viewer. Regenerate it whenever `mokotraining.sql` changes. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | Guide | +| Domain | Dolibarr Module | +| Applies To | MokoDoliTraining v1.x | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/guide/seed-reset.md | +| Version | 01.00.00 | +| Status | Draft | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | — | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/policy-enforcement-levels.-.-.md b/MokoConsulting/MokoDoliTraining/policy-enforcement-levels.-.-.md new file mode 100644 index 0000000..761684e --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/policy-enforcement-levels.-.-.md @@ -0,0 +1,73 @@ +← [Home](Home) + +## Enforcement Levels + +moko-platform uses six enforcement tiers. Apply these when reviewing or generating any file in this repository. + +| Level | Name | Behaviour | +|---|---|---| +| 6 | NOT_ALLOWED | Blocked — never permitted in any file | +| 5 | NOT_SUGGESTED | Discouraged — warn if present, do not introduce | +| 4 | FORCED | Must always be present — never remove or omit | +| 3 | REQUIRED | Must exist — treat absence as an error | +| 2 | SUGGESTED | Should exist — warn if absent | +| 1 | OPTIONAL | Include when useful | + +### Applied to this repository + +| Rule | Level | +|---|---| +| Copyright line + SPDX identifier | 4 — FORCED | +| FILE INFORMATION block (all fields) | 3 — REQUIRED | +| `## Metadata` table in every `.md` | 3 — REQUIRED | +| `## Revision History` table in every `.md` | 3 — REQUIRED | +| GPL warranty text in Full-tier files | 3 — REQUIRED | +| `ON DUPLICATE KEY UPDATE` on all INSERTs | 3 — REQUIRED | +| Rowids within reserved training ranges | 3 — REQUIRED | +| Em dashes (`--` in prose) | 6 — NOT_ALLOWED | +| Bare `except:` / `catch` blocks | 6 — NOT_ALLOWED | +| SQL string concatenation | 6 — NOT_ALLOWED | +| Real client data in demo files | 6 — NOT_ALLOWED | +| Hardcoded credentials or tokens | 6 — NOT_ALLOWED | +| Google-style docstrings (Python) | 2 — SUGGESTED | +| Type hints (Python) | 3 — REQUIRED | + +## Metadata + +| Field | Value | +|---|---| +| Document Type | Policy | +| Domain | moko-platform | +| Applies To | MokoDoliTraining — all files | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/policy/enforcement-levels.md | +| Version | 01.00.00 | +| Status | Active | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | — | + +### Backup system + +| Rule | Level | +|---|---| +| Rollback backup must exist before any seed operation | 3 — REQUIRED | +| Snapshot backup must be created immediately after seed | 3 — REQUIRED | +| Backup files stored in `src/backup/` with .htaccess + index.php | 3 — REQUIRED | +| Backup files must never contain real client data | 6 — NOT_ALLOWED | +| Backup SQL must use `ON DUPLICATE KEY UPDATE` (not bare INSERT) | 4 — FORCED | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDoliTraining/policy-file-header-standards.-.-.md b/MokoConsulting/MokoDoliTraining/policy-file-header-standards.-.-.md new file mode 100644 index 0000000..6289627 --- /dev/null +++ b/MokoConsulting/MokoDoliTraining/policy-file-header-standards.-.-.md @@ -0,0 +1,95 @@ +← [Home](Home) + +## File Header Standards + +Every file in this repository must open with a copyright header. Two tiers apply. + +### Minimal header + +For config, language files, simple utilities, and files under ~100 lines: + +``` +Copyright (C) 2026 Moko Consulting +This file is part of a Moko Consulting project. +SPDX-License-Identifier: GPL-3.0-or-later +``` + +### Full header + +For complex code, admin pages, and all files listed below. Append the GPL warranty disclaimer after the SPDX identifier: + +``` +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. +``` + +Always use Full for: + +- All `index.php` directory protection files +- All `README.md` files (warranty text in body, not comment) +- `core/modules/mod*.class.php` + +### FILE INFORMATION block + +Append after the copyright text in every header: + +``` +DEFGROUP: MokoDoliTraining.[Subgroup] +INGROUP: MokoDoliTraining[.Parent] +REPO: https://github.com/mokoconsulting-tech/MokoDoliTraining +PATH: /path/to/file.ext +VERSION: XX.YY.ZZ +BRIEF: One-line description (max 80 chars) +``` + +Optional fields: `NOTE`, `AUTHOR`, `DEPRECATED`. + +### Per-language comment syntax + +| Language | Style | +|---|---| +| PHP | `/* ... */` block comment | +| SQL | `-- ` line comments | +| INI / lang | `; ` line comments | + +### Enforcement + +See `docs/policy/enforcement-levels.md`. FILE INFORMATION block fields are REQUIRED (level 3). +SPDX identifier and copyright line are FORCED (level 4) — never remove. + +## Metadata + +| Field | Value | +|---|---| +| Document Type | Policy | +| Domain | moko-platform | +| Applies To | MokoDoliTraining — all files | +| Jurisdiction | Internal | +| Owner | Moko Consulting | +| Repo | https://github.com/mokoconsulting-tech/MokoDoliTraining | +| Path | /docs/policy/file-header-standards.md | +| Version | 01.00.00 | +| Status | Active | +| Last Reviewed | 2026-03-13 | +| Reviewed By | jmiller | + +## Revision History + +| Date | Author | Change | Notes | +|---|---|---|---| +| 2026-03-13 | jmiller | Initial draft | — | + +--- + +*Repo: [MokoDoliTraining](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliTraining) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDolibarr/Custom-Modules.-.md b/MokoConsulting/MokoDolibarr/Custom-Modules.-.md new file mode 100644 index 0000000..64ebe88 --- /dev/null +++ b/MokoConsulting/MokoDolibarr/Custom-Modules.-.md @@ -0,0 +1,116 @@ +[← Back to Home](Home) + +# Custom Modules + +Custom modules are managed in the [MokoDoliMods](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMods) submodule and symlinked into `htdocs/custom/` at deploy time. + +## Key Modules + +| Module | Description | Version | +|--------|-------------|---------| +| **dbadmin** | Database admin suite -- Adminer 5.4.2, dashboard, backup, integrity checker | 2.0.0 | +| **timesheet** | Time tracking with multi-level approval workflows | 5.0.0 | +| **preopportunity** | Pre-opportunity / lead management CRM (suspect tracking) | 1.2 | +| **internalnotification** | Email notifications on business events | 2.3.0 | +| **invoicingorientedorders** | Invoice-oriented order workflow | 3.0 | +| **kawagencytodolistforcustomer** | Customer-facing todo lists | 1.0 | +| **permissionattachedfiles** | File download access control by permission | 1.0 | + +The full module collection contains 50+ modules. See the [MokoDoliMods documentation](https://git.mokoconsulting.tech/MokoConsulting/MokoDoliMods/src/branch/dev/24.00.01/docs/modules) for individual module details. + +## Module Installation + +### Via Symlink (Recommended) + +All modules are available automatically once the symlink is created: + +```bash +# Linux/macOS +ln -s $(pwd)/MokoDoliMods/htdocs htdocs/custom + +# Windows (PowerShell as Administrator) +New-Item -ItemType SymbolicLink -Path htdocs\custom -Target MokoDoliMods\htdocs +``` + +### Enabling Modules + +1. Log in to Dolibarr as admin +2. Navigate to **Home > Setup > Modules/Applications** +3. Find the module in the list +4. Click the toggle to enable it +5. Follow any module-specific setup instructions + +### Module Updates + +Since modules are in a Git submodule, update them by pulling the latest submodule: + +```bash +cd MokoDoliMods +git pull origin dev/24.00.01 +cd .. +git add MokoDoliMods +git commit -m "chore: update MokoDoliMods submodule" +``` + +## Module Development + +### Where to Put New Modules + +All custom module work goes in the **MokoDoliMods** repository, not in the main MokoDolibarr repo. The main repo is reserved for core Dolibarr modifications only. + +### Module Structure + +Each module follows the standard Dolibarr module layout: + +``` +htdocs/custom/mymodule/ +├── core/ +│ ├── modules/ +│ │ └── modMyModule.class.php # Module descriptor +│ └── triggers/ +│ └── interface_99_modMyModule.class.php # Event triggers +├── class/ # PHP classes +├── sql/ # Database scripts +│ ├── llx_mymodule_table.sql # Table creation +│ └── llx_mymodule_table.key.sql # Index creation +├── lib/ # Library functions +├── langs/ # Language files +│ └── en_US/ # English translations +├── admin/ # Admin configuration pages +├── css/ # Module CSS +├── js/ # Module JavaScript +└── img/ # Module icons/images +``` + +### Module Descriptor + +The module descriptor class (`modMyModule.class.php`) defines: + +- Module number, name, and description +- Required Dolibarr version +- Module dependencies +- Permissions +- Menu entries +- Database tables +- Configuration pages + +## Core vs Custom + +| Change Type | Repository | +|-------------|-----------| +| New modules | MokoDoliMods | +| Third-party modules | MokoDoliMods | +| Core Dolibarr patches | MokoDolibarr | +| Upstream sync/merge | MokoDolibarr | + +--- + +*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)* + +--- + +*Repo: [MokoDolibarr](https://git.mokoconsulting.tech/MokoConsulting/MokoDolibarr) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDolibarr/Development.md b/MokoConsulting/MokoDolibarr/Development.md new file mode 100644 index 0000000..61c91a1 --- /dev/null +++ b/MokoConsulting/MokoDolibarr/Development.md @@ -0,0 +1,135 @@ +[← Back to Home](Home) + +# Development + +Guidelines for contributing to MokoDolibarr and MokoDoliMods. + +## Branch Strategy + +| Branch | Purpose | +|--------|---------| +| `main` | Bleeding edge -- default branch, receives all changes | +| `dev/24.00.01` | Active development for version 24.00.01 | +| `version/24` | Frozen snapshot of version 24 release (read-only) | +| `dolibarr/develop` | Mirror of upstream Dolibarr develop branch | + +### Working Branches + +Create feature branches from `dev/24.00.01`: + +```bash +git checkout dev/24.00.01 +git checkout -b feat/my-feature +``` + +## Contributing + +### Workflow + +1. Fork the repository +2. Create a feature branch from `dev/24.00.01` +3. **Custom module work** goes in the **MokoDoliMods** submodule (not this repo) +4. **Core Dolibarr modifications** go in this repo +5. Set up pre-commit hooks before committing +6. Open a PR against `dev/24.00.01` + +### Pre-Commit Hooks + +Pre-commit hooks are required. Install them before making any commits: + +```bash +pip install pre-commit +pre-commit install +``` + +The `.pre-commit-config.yaml` defines checks for: + +- Code formatting and linting +- Security scanning (Gitleaks for secret detection) +- File header validation + +### Code Standards + +MokoDolibarr follows [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) governance: + +- All files must include MokoStandards-compliant copyright headers +- PHP code must pass PHPStan Level 5+ static analysis +- Code must follow Dolibarr coding standards + +## Syncing with Upstream Dolibarr + +The `dolibarr/develop` branch tracks upstream Dolibarr automatically. To merge upstream changes: + +```bash +git fetch upstream +git merge upstream/develop --no-commit +# Resolve any conflicts +git commit -m "chore: merge upstream Dolibarr develop" +``` + +## CI/CD Workflows + +All workflows are governed by MokoStandards: + +| Workflow | File | Purpose | +|----------|------|---------| +| **CI** | `ci-dolibarr.yml` | PHP 8.1-8.3 test matrix | +| **CodeQL** | `codeql-analysis.yml` | Security scanning (JS/YAML) | +| **Standards** | `standards-compliance.yml` | File headers, docs, license validation | +| **Deploy** | `deploy-dev.yml` | Automated SFTP deployment to dev server | + +## Static Analysis + +PHPStan is configured in `phpstan.neon` at Level 5+: + +```bash +# Run PHPStan analysis +vendor/bin/phpstan analyse +``` + +The configuration in `phpstan.neon.dist` provides the baseline settings. + +## Testing + +Dolibarr's core test suite is in the `test/` directory: + +```bash +# Run the test suite +cd test +php -f run_tests.php +``` + +## Makefile Targets + +The `Makefile` provides build automation: + +```bash +# View available targets +make help +``` + +## Deployment + +Deployment to the dev server is automated via the `deploy-dev.yml` GitHub Actions workflow, which uses SFTP to push changes. + +## Version Numbering + +MokoDolibarr follows the pattern `XX.YY.ZZ` where: + +- `XX` = Major version (aligned with upstream Dolibarr major) +- `YY` = Minor version +- `ZZ` = Patch version + +The MokoDoliMods submodule has its own independent versioning. + +--- + +*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)* + +--- + +*Repo: [MokoDolibarr](https://git.mokoconsulting.tech/MokoConsulting/MokoDolibarr) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDolibarr/Getting-Started.-.md b/MokoConsulting/MokoDolibarr/Getting-Started.-.md new file mode 100644 index 0000000..7d6c2d1 --- /dev/null +++ b/MokoConsulting/MokoDolibarr/Getting-Started.-.md @@ -0,0 +1,125 @@ +[← Back to Home](Home) + +# Getting Started + +MokoDolibarr is Moko Consulting's enterprise fork of Dolibarr ERP & CRM, enhanced with 50+ custom modules via the MokoDoliMods submodule. + +## Prerequisites + +| Requirement | Minimum | +|---|---| +| **PHP** | 8.1+ | +| **Database** | MariaDB 10.6+ / MySQL 8.0+ / PostgreSQL 14+ | +| **Composer** | 2.x | +| **Git** | Required for submodule support | +| **Python** | 3.x (for pre-commit hooks) | + +## Clone the Repository + +Clone with submodules to include the MokoDoliMods custom module collection: + +```bash +git clone --recurse-submodules https://git.mokoconsulting.tech/MokoConsulting/MokoDolibarr.git +cd MokoDolibarr +``` + +If you already cloned without `--recurse-submodules`: + +```bash +git submodule update --init --recursive +``` + +## Set Up Custom Modules + +Link the MokoDoliMods submodule as Dolibarr's custom directory: + +```bash +# Linux/macOS +ln -s $(pwd)/MokoDoliMods/htdocs htdocs/custom + +# Windows (PowerShell as Administrator) +New-Item -ItemType SymbolicLink -Path htdocs\custom -Target MokoDoliMods\htdocs +``` + +This symlink makes all custom modules available to Dolibarr at runtime. + +## Install Dependencies + +```bash +composer install +``` + +## Set Up Pre-Commit Hooks (Recommended) + +Pre-commit hooks enforce code quality before each commit: + +```bash +pip install pre-commit +pre-commit install +``` + +The hooks are defined in `.pre-commit-config.yaml` and include linting, formatting, and security checks. + +## Database Setup + +1. Create a database for Dolibarr: + +```sql +CREATE DATABASE dolibarr CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +CREATE USER 'dolibarr'@'localhost' IDENTIFIED BY 'your_password'; +GRANT ALL PRIVILEGES ON dolibarr.* TO 'dolibarr'@'localhost'; +FLUSH PRIVILEGES; +``` + +2. Point your web server at `htdocs/` as the document root +3. Navigate to the Dolibarr web installer and complete setup + +## Verify Custom Modules + +After installation: + +1. Log in to Dolibarr admin +2. Go to **Home > Setup > Modules/Applications** +3. Custom modules from MokoDoliMods should appear in the list +4. Enable the modules you need + +## What's Different from Upstream + +| Area | Upstream Dolibarr | MokoDolibarr | +|------|-------------------|--------------| +| **Custom Modules** | None | 50+ via MokoDoliMods submodule | +| **PHP Minimum** | 7.2 | 8.1 | +| **CI/CD** | Travis CI | GitHub Actions (MokoStandards-governed) | +| **Static Analysis** | Optional | PHPStan Level 5+, CodeQL, Gitleaks | +| **Security Scanning** | Basic | CodeQL + Dependabot + pre-commit hooks | +| **Deployment** | Manual | Automated SFTP via GitHub Actions | + +## Directory Layout + +``` +MokoDolibarr/ +├── htdocs/ # Dolibarr core (synced from upstream) +│ └── custom/ # → symlink to MokoDoliMods/htdocs +├── MokoDoliMods/ # Submodule: custom + third-party modules +│ └── htdocs/ # Module source files +├── test/ # Dolibarr core test suite +├── dev/ # Development utilities +├── doc/ # Dolibarr documentation +├── scripts/ # Build and utility scripts +├── .github/ # CI/CD workflows +├── .pre-commit-config.yaml # Pre-commit hook definitions +├── phpstan.neon # Static analysis configuration +└── Makefile # Build automation +``` + +--- + +*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)* + +--- + +*Repo: [MokoDolibarr](https://git.mokoconsulting.tech/MokoConsulting/MokoDolibarr) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoDolibarr/Home.md b/MokoConsulting/MokoDolibarr/Home.md new file mode 100644 index 0000000..3a41e7f --- /dev/null +++ b/MokoConsulting/MokoDolibarr/Home.md @@ -0,0 +1,91 @@ +# MokoDolibarr + +Moko Consulting's enterprise fork of Dolibarr ERP & CRM + +--- + +## Overview + +MokoDolibarr is an enhanced fork of [Dolibarr ERP & CRM](https://www.dolibarr.org/), extended with 50+ custom modules, security hardening, and CI/CD governance via MokoStandards. It serves as the primary business management platform for Moko Consulting operations. + +## What's Different from Upstream + +| Area | Upstream Dolibarr | MokoDolibarr | +|------|-------------------|--------------| +| **Custom Modules** | None | 50+ via MokoDoliMods submodule | +| **PHP Minimum** | 7.2 | 8.1 | +| **CI/CD** | Travis CI | Gitea Actions (MokoStandards-governed) | +| **Static Analysis** | Optional | PHPStan Level 5+, CodeQL, Gitleaks | +| **Security Scanning** | Basic | CodeQL + Dependabot + pre-commit hooks | +| **Deployment** | Manual | Automated SFTP via CI/CD | + +## Architecture + +``` +MokoDolibarr/ + htdocs/ # Dolibarr core (synced from upstream) + MokoDoliMods/ # Submodule: custom + third-party modules + htdocs/ # Symlinked to htdocs/custom/ at deploy time + test/ # Dolibarr core test suite + .gitea/ # CI/CD workflows +``` + +## Key Modules (MokoDoliMods) + +| Module | Description | +|--------|-------------| +| **dbadmin** | Database admin suite (Adminer 5.4.2) | +| **timesheet** | Time tracking with multi-level approval | +| **preopportunity** | Pre-opportunity / lead management | +| **internalnotification** | Email notifications on business events | +| **invoicingoriented orders** | Invoice-oriented order workflow | + +## Getting Started + +### Prerequisites + +- PHP 8.1+, MariaDB 10.6+ / MySQL 8.0+ / PostgreSQL 14+, Composer 2.x, Git + +### Clone & Setup + +```bash +git clone --recurse-submodules +cd MokoDolibarr +ln -s $(pwd)/MokoDoliMods/htdocs htdocs/custom +composer install +``` + +## Branches + +| Branch | Purpose | +|--------|---------| +| `main` | Bleeding edge -- default branch | +| `dev/24.00.01` | Active development | +| `version/24` | Frozen release snapshot | +| `dolibarr/develop` | Mirror of upstream Dolibarr | + +## Details + +| Field | Value | +|-------|-------| +| **Language** | PHP | +| **License** | GPL-3.0 | +| **Visibility** | Private | + +## Related Repositories + +| Repository | Description | +|------------|-------------| +| [MokoCRM](https://git.mokoconsulting.tech/MokoConsulting/MokoCRM) | Dolibarr CRM customization module | + +--- + +**Category:** ERP/CRM | **Platform:** [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API/wiki) + +--- + +*Repo: [MokoDolibarr](https://git.mokoconsulting.tech/MokoConsulting/MokoDolibarr) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoGalleryCalendar/Home.md b/MokoConsulting/MokoGalleryCalendar/Home.md new file mode 100644 index 0000000..8c43d68 --- /dev/null +++ b/MokoConsulting/MokoGalleryCalendar/Home.md @@ -0,0 +1,42 @@ +# MokoGalleryCalendar + +JoomGallery and DPCalendar integration — link photo galleries to calendar events + +| Field | Value | +|---|---| +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) | + +--- + +## Guides + +| Page | Description | +|---|---| +| [configuration](configuration) | ← [Home](Home) | +| [installation](installation) | ← [Home](Home) | + +## Reference + +| Page | Description | +|---|---| +| [architecture](architecture) | ← [Home](Home) | + +## Documentation + +| Page | Description | +|---|---| +| [development](development) | ← [Home](Home) | +| [troubleshooting](troubleshooting) | ← [Home](Home) | + +--- + +> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) + +--- + +*Repo: [MokoGalleryCalendar](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoGalleryCalendar/architecture.md b/MokoConsulting/MokoGalleryCalendar/architecture.md new file mode 100644 index 0000000..40f2099 --- /dev/null +++ b/MokoConsulting/MokoGalleryCalendar/architecture.md @@ -0,0 +1,153 @@ +← [Home](Home) + +# Architecture + +## File Structure + +``` +src/ +├── mokojgdpc.xml # Joomla manifest (config fields, metadata, update server) +├── script.php # Install/update/uninstall script +├── services/ +│ └── provider.php # DI service provider (wires the plugin class) +├── src/ +│ └── Extension/ +│ └── MokoJGDPC.php # Main plugin class (all business logic) +└── language/ + ├── en-GB/ + │ ├── plg_system_mokojgdpc.ini # Backend language strings + │ └── plg_system_mokojgdpc.sys.ini # System language strings + └── en-US/ + ├── plg_system_mokojgdpc.ini + └── plg_system_mokojgdpc.sys.ini +``` + +## Plugin Class + +`MokoConsulting\Plugin\System\MokoJGDPC\Extension\MokoJGDPC` + +Extends `CMSPlugin`, implements `SubscriberInterface`, uses: +- `DatabaseAwareTrait` — database access via `$this->getDatabase()` +- `TaskPluginTrait` — Joomla Task Scheduler integration + +### Subscribed Events + +| Event | Method | Purpose | +|-------|--------|---------| +| `onContentAfterSave` | `onContentAfterSave()` | React to DPCalendar event saves | +| `onContentAfterDelete` | `onContentAfterDelete()` | React to DPCalendar event deletions | +| `onAfterRoute` | `onAfterRoute()` | 7-day fallback for pending processing | +| `onTaskOptionsList` | `advertiseRoutines()` | Register task type with scheduler (via trait) | +| `onExecuteTask` | `standardRoutineHandler()` | Route task execution (via trait) | + +### Constants + +| Constant | Value | Purpose | +|----------|-------|---------| +| `DPCALENDAR_CONTEXT` | `com_dpcalendar.event` | Content context filter | +| `ALIAS_MAX_ATTEMPTS` | `100` | Max alias dedup iterations before timestamp fallback | +| `FALLBACK_STALE_DAYS` | `7` | Days before `onAfterRoute` fallback triggers | +| `TASKS_MAP` | Task type map | Maps task IDs to handler methods for `TaskPluginTrait` | + +## Data Flow + +### Event Creation + +``` +DPCalendar event saved + → onContentAfterSave + → Filter: context == com_dpcalendar.event + → Filter: not a recurring instance (original_id == 0) + → Filter: JoomGallery tables exist + → Extract event start date + → Check for existing mapping + → Exists with category: sync title if configured, update event_date if changed + → Exists pending: update event_date if changed + → Not exists: + → event_date <= today? Create category immediately + → event_date > today? Store pending mapping (category_id = 0) +``` + +### Deferred Category Creation + +``` +Task Scheduler (daily at 2:00 AM) + OR +Frontend fallback (if task stale > 7 days) + → Query: category_id = 0 AND event_date <= today + → For each pending mapping: + → Fetch event title from #__dpcalendar_events + → Title empty? Delete orphaned mapping, skip + → createGalleryCategory() + → Generate unique alias + → Resolve access level + permission rules + → Insert into nested set (shift lft/rgt, insert row) + → Create #__assets record + → Update mapping with real category_id + → Touch lastrun cache file +``` + +### Event Deletion + +``` +DPCalendar event deleted + → onContentAfterDelete + → Look up mapped category_id + → If category exists AND delete_on_remove enabled: + → Delete from nested set (remove row, close gap) + → Delete asset record from #__assets + → Always delete mapping row (pending or created) +``` + +## Database Schema + +### `#__mokojgdpc_map` + +| Column | Type | Nullable | Default | Index | Description | +|--------|------|----------|---------|-------|-------------| +| `id` | INT UNSIGNED | No | AUTO_INCREMENT | PRIMARY | Row ID | +| `event_id` | INT UNSIGNED | No | — | UNIQUE (`idx_event`) | DPCalendar event ID | +| `category_id` | INT UNSIGNED | No | `0` | `idx_category`, `idx_pending` | JoomGallery category ID. `0` = pending | +| `event_date` | DATE | Yes | NULL | `idx_pending` (composite) | Event start date. Category created when this date arrives | +| `created` | DATETIME | No | CURRENT_TIMESTAMP | — | Row creation time | + +**`idx_pending`** is a composite index on `(category_id, event_date)` — optimizes the daily pending query. + +## Nested Set Operations + +JoomGallery categories use a nested set model (lft/rgt columns). The plugin manipulates this directly: + +**Insert:** Shift `rgt >= parent.rgt` by +2, shift `lft > parent.rgt` by +2, insert with `lft = old_parent_rgt`, `rgt = old_parent_rgt + 1`. + +**Delete:** Remove rows where `lft >= node.lft AND rgt <= node.rgt`, then close the gap by shifting `rgt > node.rgt` by `-width` and `lft > node.rgt` by `-width`. + +Both operations run inside database transactions. + +## Asset Records + +Joomla enforces ACL permissions through the `#__assets` table (also a nested set). Each gallery category gets: + +- An asset named `com_joomgallery.category.{id}` +- Positioned as a child of the parent category's asset (falls back to `com_joomgallery` component root) +- Rules copied from the permissions template category (if configured) +- Linked to the category row via `asset_id` column + +Asset creation runs **outside** the category transaction to avoid nested set conflicts between the two tables. + +## Throttle Mechanism + +The `onAfterRoute` fallback uses a file-based throttle: + +- **File:** `{tmp_path}/mokojgdpc_lastrun` +- **Content:** Timestamp of last run +- **Check:** `filemtime()` compared against `time() - (7 * 86400)` +- Both the scheduled task and the fallback call `touchLastRun()` so they share the same staleness window +- File is deleted on plugin uninstall + +--- + +*Repo: [MokoGalleryCalendar](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGalleryCalendar/configuration.md b/MokoConsulting/MokoGalleryCalendar/configuration.md new file mode 100644 index 0000000..4a1108f --- /dev/null +++ b/MokoConsulting/MokoGalleryCalendar/configuration.md @@ -0,0 +1,91 @@ +← [Home](Home) + +# Configuration Guide + +All settings are in **System > Manage > Plugins > MokoJGDPC**. + +## Parameters + +### Parent Gallery Category + +- **Field:** `parent_category` +- **Type:** Number +- **Default:** `1` (JoomGallery root) + +The JoomGallery category ID under which all event gallery categories are created. All auto-generated categories become children of this category. + +To find a category's ID: go to **Components > JoomGallery > Categories**, the ID column is on the right. + +### Delete on Event Remove + +- **Field:** `delete_on_remove` +- **Type:** Yes/No toggle +- **Default:** No + +When enabled, deleting a DPCalendar event also deletes its linked JoomGallery category and the associated Joomla asset record. + +When disabled, deleting an event only removes the mapping row. The gallery category remains in JoomGallery as a standalone category. + +**Note:** The mapping row is always removed on event deletion regardless of this setting. + +### Sync Title Changes + +- **Field:** `sync_title` +- **Type:** Yes/No toggle +- **Default:** Yes + +When enabled, saving a DPCalendar event with a changed title also renames the linked JoomGallery category and updates its alias. + +### Default Access Level + +- **Field:** `default_access` +- **Type:** Access Level dropdown +- **Default:** Public + +The Joomla viewing access level assigned to newly created gallery categories. This controls who can see the category in JoomGallery. + +Standard Joomla access levels: +- **Public** (1) — visible to everyone +- **Registered** (2) — logged-in users only +- **Special** (3) — users in the Special access group + +Custom access levels defined in **Users > Access Levels** also appear here. + +### Permissions Template Category + +- **Field:** `permissions_template_category` +- **Type:** Number +- **Default:** `0` (inherit from parent) + +A JoomGallery category ID whose ACL permission rules are copied to every newly created gallery category. This controls who can create, edit, and delete **images** within the category. + +#### How to set up + +1. Create a category in JoomGallery (e.g., "Event Gallery Permissions Template") +2. Open it and go to the **Permissions** tab +3. Configure the actions for each user group: + - `core.create` — who can upload images + - `core.edit` — who can edit image metadata + - `core.delete` — who can delete images + - `core.edit.state` — who can publish/unpublish images +4. Save the category and note its ID +5. Enter that ID in the **Permissions Template Category** field + +Set to `0` to inherit permissions from the parent category (no explicit rules). + +#### Where rules are read from + +The plugin checks two locations in order: + +1. The `rules` column on `#__joomgallery_categories` for the template category +2. The `rules` column on `#__assets` for `com_joomgallery.category.{id}` + +If neither has rules, an empty ruleset (`{}`) is used and a log warning is written. + +--- + +*Repo: [MokoGalleryCalendar](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGalleryCalendar/development.md b/MokoConsulting/MokoGalleryCalendar/development.md new file mode 100644 index 0000000..5321654 --- /dev/null +++ b/MokoConsulting/MokoGalleryCalendar/development.md @@ -0,0 +1,108 @@ +← [Home](Home) + +# Development Guide + +## Local Setup + +```bash +git clone https://git.mokoconsulting.tech/MokoConsulting/MokoJGDPC.git +cd MokoJGDPC +``` + +The installable plugin source lives in `src/`. Everything outside `src/` (workflows, docs, README) is repo-level infrastructure. + +## Building a ZIP + +```bash +cd src +zip -r ../mokojgdpc.zip . \ + -x ".ftpignore" "sftp-config*" "*.ppk" "*.pem" "*.key" ".env*" +``` + +Or trigger the release workflow via Gitea Actions (see CI/CD below). + +## Testing Locally + +1. Symlink or copy `src/` into your Joomla installation: + ``` + plugins/system/mokojgdpc/ → src/ + ``` +2. Discover and enable the plugin via **System > Manage > Extensions > Discover** +3. The install script will create the mapping table and seed existing events + +## Key Methods + +### `MokoJGDPC.php` + +| Method | Visibility | Purpose | +|--------|-----------|---------| +| `onContentAfterSave()` | public | Entry point for event creation/update | +| `onContentAfterDelete()` | public | Entry point for event deletion | +| `onAfterRoute()` | public | 7-day fallback for pending processing | +| `processTask()` | private | Task Scheduler entry point | +| `processPendingMappings()` | private | Core logic: find and create overdue categories | +| `createGalleryCategory()` | private | Nested set insert + access/rules | +| `createCategoryAsset()` | private | ACL asset record creation | +| `deleteGalleryCategory()` | private | Nested set delete + gap close | +| `deleteCategoryAsset()` | private | ACL asset cleanup | +| `resolvePermissionRules()` | private | Load rules from template category | +| `uniqueAlias()` | private | Deduplicate URL aliases | +| `extractEventDate()` | private | Parse event start date (site timezone) | + +### `script.php` + +| Method | Purpose | +|--------|---------| +| `install()` | Create table, seed events, register scheduled task | +| `update()` | Ensure table, migrate schema, ensure task | +| `uninstall()` | Drop table, remove task, clean cache file | +| `seedExistingEvents()` | Map all unmapped DPCalendar events on first install | +| `migrateSchema()` | Add `event_date` column if upgrading from pre-01.00.01 | +| `ensureScheduledTask()` | Idempotent task registration in `#__scheduler_tasks` | + +## Branching & Releases + +| Branch | Purpose | +|--------|---------| +| `main` | Stable releases | +| `dev` | Development (PRs target here) | + +Releases are triggered via the `release.yml` workflow (workflow_dispatch). Dev releases use stability `development`; stable releases use `stable`. + +## CI/CD Workflows + +### `release.yml` + +- Triggered by tag push (`XX.YY.ZZ`) or manual dispatch +- Auto-bumps patch version in README.md, manifest, and updates.xml +- Builds ZIP from `src/`, creates Gitea release, uploads asset +- Updates `updates.xml` with SHA-256 hash + +### `update-server.yml` + +- Triggered on push to `dev`/`alpha`/`beta`/`rc` branches (when `src/` changes) +- Builds ZIP + tar.gz packages +- Creates/updates Gitea releases per stability channel +- Generates `updates.xml` entries for Joomla's update system +- Optionally deploys to dev server via SFTP + +## Adding a New Config Field + +1. Add the `` element to `src/mokojgdpc.xml` inside `
` +2. Add label and description language strings to both `en-GB` and `en-US` `.ini` files +3. Read the value in PHP via `$this->params->get('field_name', 'default')` +4. If the field affects seeding, also read it in `script.php` from `$pluginParams` + +## Modifying the Database Schema + +1. Update the `CREATE TABLE` statement in `script.php::createTable()` +2. Add an `ALTER TABLE` in `script.php::migrateSchema()` for upgrades +3. The migration checks `$db->getTableColumns()` — only runs if the column doesn't exist yet + +--- + +*Repo: [MokoGalleryCalendar](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGalleryCalendar/installation.md b/MokoConsulting/MokoGalleryCalendar/installation.md new file mode 100644 index 0000000..011349f --- /dev/null +++ b/MokoConsulting/MokoGalleryCalendar/installation.md @@ -0,0 +1,65 @@ +← [Home](Home) + +# Installation Guide + +## Requirements + +| Requirement | Version | +|-------------|---------| +| Joomla | 5.x or 6.x | +| PHP | 8.1+ | +| DPCalendar | Any current version | +| JoomGallery | 4.x | + +Both DPCalendar and JoomGallery must be installed and enabled before installing MokoJGDPC. + +## Install + +1. Download the latest ZIP from the [releases page](https://git.mokoconsulting.tech/MokoConsulting/MokoJGDPC/releases) +2. In Joomla admin, go to **System > Install > Extensions** +3. Upload the ZIP and install +4. Go to **System > Manage > Plugins**, search for "MokoJGDPC", and enable it + +## What Happens on Install + +The install script automatically: + +1. Creates the `#__mokojgdpc_map` mapping table +2. Scans all existing published DPCalendar events and creates mappings for them (categories are created only for events whose date has already passed; future events get pending mappings) +3. Registers a daily scheduled task in **System > Scheduled Tasks** + +## Update + +Upload the new ZIP through the same installer. The update script: + +- Runs `CREATE TABLE IF NOT EXISTS` (safe for existing tables) +- Adds new columns via `migrateSchema()` if upgrading from an older version +- Ensures the scheduled task exists + +## Uninstall + +Uninstalling the plugin: + +- Drops the `#__mokojgdpc_map` table and all mapping data +- Removes the scheduled task from `#__scheduler_tasks` +- Deletes the `/tmp/mokojgdpc_lastrun` cache file + +**Gallery categories are not removed.** They become standalone JoomGallery categories. Delete them manually if needed. + +## Auto-Update Server + +The plugin manifest includes an update server pointing to: + +``` +https://git.mokoconsulting.tech/MokoConsulting/MokoJGDPC/raw/branch/main/updates.xml +``` + +Joomla will check for new versions automatically via **System > Update > Extensions**. + +--- + +*Repo: [MokoGalleryCalendar](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGalleryCalendar/troubleshooting.md b/MokoConsulting/MokoGalleryCalendar/troubleshooting.md new file mode 100644 index 0000000..fe18027 --- /dev/null +++ b/MokoConsulting/MokoGalleryCalendar/troubleshooting.md @@ -0,0 +1,116 @@ +← [Home](Home) + +# Troubleshooting + +## Categories not being created + +### Event is in the future + +Categories are only created when the event's start date arrives. Check `#__mokojgdpc_map` for a row with `category_id = 0` — that means it's pending and waiting for the date. + +### Scheduled task not running + +1. Go to **System > Scheduled Tasks** +2. Look for "MokoJGDPC: Process pending gallery categories" +3. Verify it shows **Enabled** and has a reasonable **Next Execution** date +4. If missing, re-save the plugin (disable/enable) or reinstall to trigger `ensureScheduledTask()` + +Joomla's Task Scheduler requires either: +- A server cron job hitting `cli/joomla.php scheduler:run` regularly, or +- The "Lazy Scheduling" (Web Cron) option enabled in **System > Scheduled Tasks > Options** + +### JoomGallery not detected + +The plugin checks for the `#__joomgallery_categories` table. If JoomGallery was installed after MokoJGDPC, the cached check (`$jgAvailable`) may need a fresh page load to detect it. + +### Parent category doesn't exist + +Check the Joomla log for: `MokoJGDPC: Parent category #X not found in JoomGallery` + +Verify the configured parent category ID exists in **Components > JoomGallery > Categories**. + +## Permissions not applied + +### Template category has no rules + +Check the Joomla log for: `MokoJGDPC: Permissions template category #X has no rules` + +This means the template category exists but has an empty `rules` column in both `#__joomgallery_categories` and `#__assets`. Open the template category in JoomGallery, go to the Permissions tab, explicitly set at least one action, and save. + +### Template category doesn't exist + +Check the Joomla log for: `MokoJGDPC: Permissions template category #X not found` + +The configured ID doesn't match any JoomGallery category. Update the plugin setting. + +### Categories created before template was configured + +Existing categories are not retroactively updated. Only new categories get the template rules. To apply rules to existing categories, edit them directly in JoomGallery. + +## Duplicate categories + +### Same event title + +The plugin generates unique aliases by appending `-2`, `-3`, etc. But the categories themselves can have identical titles (only aliases must be unique in the URL). This is by design. + +### Recurring events + +Recurring event instances (where `original_id > 0`) are skipped. Only the original/parent event gets a gallery category. If you're seeing duplicates, verify the DPCalendar events aren't separate standalone events with the same name. + +## Log locations + +All plugin log messages use the category `plg_system_mokojgdpc`. To view them: + +1. Go to **System > Global Configuration > Logging** +2. Ensure logging is enabled +3. Check `administrator/logs/joomla_*.log` for entries containing `MokoJGDPC:` + +Log levels used: +- **ERROR** — category creation failed, mapping insert failed +- **WARNING** — parent not found, template not found, asset creation failed, deferred creation failed +- **NOTICE** — template has no rules +- **INFO** — seed results, deferred creation counts, migration applied + +## Database inspection + +### Check pending mappings + +```sql +SELECT * FROM #__mokojgdpc_map WHERE category_id = 0; +``` + +### Check all mappings with event titles + +```sql +SELECT m.*, e.title, e.start_date +FROM #__mokojgdpc_map m +LEFT JOIN #__dpcalendar_events e ON e.id = m.event_id +ORDER BY m.event_date; +``` + +### Find orphaned mappings (event deleted but mapping remains) + +```sql +SELECT m.* +FROM #__mokojgdpc_map m +LEFT JOIN #__dpcalendar_events e ON e.id = m.event_id +WHERE e.id IS NULL; +``` + +These are cleaned up automatically during the next scheduled task run. + +### Check the scheduled task status + +```sql +SELECT id, title, state, last_execution, next_execution, times_executed, times_failed +FROM #__scheduler_tasks +WHERE type = 'plg_system_mokojgdpc.process_pending'; +``` + +--- + +*Repo: [MokoGalleryCalendar](https://git.mokoconsulting.tech/MokoConsulting/MokoGalleryCalendar) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGitea/Branding.md b/MokoConsulting/MokoGitea/Branding.md new file mode 100644 index 0000000..cc0a15a --- /dev/null +++ b/MokoConsulting/MokoGitea/Branding.md @@ -0,0 +1,32 @@ +# Custom Branding + +## Logo & Favicon + +Located in the container at `/var/lib/gitea/custom/public/assets/img/`: +- `logo.svg` — Navbar logo +- `logo.png` — Fallback logo +- `favicon.png` — Browser tab icon +- `favicon.svg` — SVG favicon + +Source: Moko Consulting CRM favicon + +## Landing Page + +- `LANDING_PAGE = organizations` in `app.ini` +- Custom JS redirects home/logo clicks to `/explore/organizations` +- After login, users see the organizations list + +## Themes + +Custom CSS themes at `/var/lib/gitea/custom/public/assets/css/`: +- `theme-moko-dark.css` +- `theme-moko-light.css` +- `theme-moko-auto.css` + +--- + +*Repo: [MokoGitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGitea/Deployment.md b/MokoConsulting/MokoGitea/Deployment.md new file mode 100644 index 0000000..c4db1f4 --- /dev/null +++ b/MokoConsulting/MokoGitea/Deployment.md @@ -0,0 +1,48 @@ +# Deployment + +## Docker Image + +MokoGitea runs as a custom Docker image built from the `moko/1.25.5-project-api` branch. + +### Build +```bash +cd /opt/MokoGitea +git pull +docker build -t mokogitea:1.25.5-project-api -f Dockerfile.rootless . +``` + +### Deploy +The docker-compose at `/opt/gitea/docker-compose.yml` references the image: +```yaml +services: + gitea: + image: mokogitea:1.25.5-project-api +``` + +### Update Process +1. Pull latest from `moko/1.25.5-project-api` +2. Rebuild Docker image +3. `docker compose down gitea && docker compose up -d gitea` + +## Volumes + +| Path | Purpose | +|------|---------| +| `./gitea/data` | Repository data, LFS, avatars | +| `./gitea/conf` | `app.ini` configuration | + +## Custom Files + +Located at `/var/lib/gitea/custom/`: +- `templates/custom/header.tmpl` — Branding, logo redirect +- `public/assets/img/logo.svg` — Moko logo +- `public/assets/img/favicon.png` — Moko favicon +- `public/assets/css/theme-moko-*.css` — Custom themes + +--- + +*Repo: [MokoGitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGitea/Home.md b/MokoConsulting/MokoGitea/Home.md new file mode 100644 index 0000000..70b482a --- /dev/null +++ b/MokoConsulting/MokoGitea/Home.md @@ -0,0 +1,24 @@ +# MokoGitea + +Custom Gitea fork with Project Board API + +--- + +## Pages + +- [Branding](Branding) +- [Deployment](Deployment) +- [Project API](Project API) +- [roadmap](roadmap) + +--- + +**Category:** Infrastructure | **Platform:** [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki) + +--- + +*Repo: [MokoGitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | \ No newline at end of file diff --git a/MokoConsulting/MokoGitea/Project-API.md b/MokoConsulting/MokoGitea/Project-API.md new file mode 100644 index 0000000..fb9db8d --- /dev/null +++ b/MokoConsulting/MokoGitea/Project-API.md @@ -0,0 +1,202 @@ +# Project Board API Reference + +Complete REST API for managing Gitea project boards, columns, and issue cards. This API was added by MokoGitea and is not available in upstream Gitea. + +## Authentication + +All write endpoints require a token with `issue` scope: +``` +Authorization: token YOUR_TOKEN +``` + +## Projects + +### List Projects +``` +GET /api/v1/repos/{owner}/{repo}/projects +``` +Query parameters: +- `state` — `open` (default), `closed`, or `all` +- `page` — page number (1-based) +- `limit` — results per page + +Response: Array of Project objects + +### Create Project +``` +POST /api/v1/repos/{owner}/{repo}/projects +``` +Body: +```json +{ + "title": "Sprint Q2 2026", + "description": "Second quarter sprint", + "board_type": 1, + "card_type": 0 +} +``` +- `board_type`: 0=none, 1=basic kanban, 2=bug triage +- `card_type`: 0=text only, 1=images and text + +### Get Project +``` +GET /api/v1/repos/{owner}/{repo}/projects/{id} +``` + +### Update Project +``` +PATCH /api/v1/repos/{owner}/{repo}/projects/{id} +``` +Body: +```json +{ + "title": "Updated Title", + "description": "Updated description" +} +``` + +### Delete Project +``` +DELETE /api/v1/repos/{owner}/{repo}/projects/{id} +``` + +### Close/Reopen Project +``` +POST /api/v1/repos/{owner}/{repo}/projects/{id}/close +POST /api/v1/repos/{owner}/{repo}/projects/{id}/reopen +``` + +## Columns + +### List Columns +``` +GET /api/v1/repos/{owner}/{repo}/projects/{id}/columns +``` + +### Create Column +``` +POST /api/v1/repos/{owner}/{repo}/projects/{id}/columns +``` +Body: +```json +{ + "title": "Backlog", + "color": "#0075ca" +} +``` + +### Delete Column +``` +DELETE /api/v1/repos/{owner}/{repo}/projects/{id}/columns/{columnId} +``` + +## Issue Cards + +### List Issues in Column +``` +GET /api/v1/repos/{owner}/{repo}/projects/{id}/columns/{columnId}/issues +``` + +Response: Array of ProjectColumnIssue objects with `issue_id`, `project_id`, `column_id`, `sorting` + +### Add Issue to Column +``` +POST /api/v1/repos/{owner}/{repo}/projects/{id}/columns/{columnId}/issues +``` +Body: +```json +{ + "issue_id": 42 +} +``` + +### Move Issue Between Columns +``` +PATCH /api/v1/repos/{owner}/{repo}/projects/{id}/issues/{issueId}/move +``` +Body: +```json +{ + "column_id": 5, + "sorting": 0 +} +``` + +### Remove Issue from Project +``` +DELETE /api/v1/repos/{owner}/{repo}/projects/{id}/issues/{issueId} +``` + +## Data Types + +### Project +```json +{ + "id": 1, + "title": "Roadmap", + "description": "Development roadmap", + "owner_id": 2, + "repo_id": 68, + "creator_id": 1, + "is_closed": false, + "created_at": "2026-05-08T00:06:45Z", + "updated_at": "2026-05-08T00:06:45Z", + "closed_at": null +} +``` + +### ProjectColumn +```json +{ + "id": 7, + "title": "Backlog", + "sorting": 0, + "color": "#0075ca", + "project_id": 1, + "default": false, + "created_at": "2026-05-08T00:06:58Z", + "updated_at": "2026-05-08T00:06:58Z" +} +``` + +### ProjectColumnIssue +```json +{ + "id": 1, + "issue_id": 42, + "project_id": 1, + "column_id": 7, + "sorting": 0 +} +``` + +## MCP Integration + +The `project-mcp` server wraps this API. Key tool: `project_setup_roadmap` creates a full project board with columns and loads all open issues in one call. + +## Quick Start + +```bash +# Create a project +curl -X POST -H "Authorization: token TOKEN" \ + https://git.mokoconsulting.tech/api/v1/repos/MokoConsulting/MokoCRM/projects \ + -d '{"title":"Roadmap","board_type":1}' + +# Add columns +curl -X POST -H "Authorization: token TOKEN" \ + https://git.mokoconsulting.tech/api/v1/repos/MokoConsulting/MokoCRM/projects/1/columns \ + -d '{"title":"Backlog"}' + +# Add an issue +curl -X POST -H "Authorization: token TOKEN" \ + https://git.mokoconsulting.tech/api/v1/repos/MokoConsulting/MokoCRM/projects/1/columns/1/issues \ + -d '{"issue_id":42}' +``` + +--- + +*Repo: [MokoGitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoGitea/roadmap.md b/MokoConsulting/MokoGitea/roadmap.md new file mode 100644 index 0000000..0be4336 --- /dev/null +++ b/MokoConsulting/MokoGitea/roadmap.md @@ -0,0 +1,88 @@ +# Roadmap for 2024 + +## Instant ability + +* Don't reload the page when changing something in the page. i.e. changing the label in the issue view page. +* Display instant changes in issue/pull request view page when another person updates/adds something. +* Display outdated information on pull request files review page + +## CI/CD + +* Better compatible with Github Actions +* Runner for more platforms and architectures +* Marketplace for Actions + +## Code Review + +* Possibility to do the whole life cycle of a pull request online for small changes. (Online add files/rename files/delete files for pull requests and etc.) +* Path tree for commit view on the left side. +* Suggestion for code review + +## Projects + +* Automation for projects +* Column mode for projects + +## Packages + +* Fix the parallel problems +* Improve permissions check + +## Buildability + +* Reduce CI build times +* Provide an LTS where security patches and some bug fixes may be backported on a longer schedule than before +* A more consistent release cadence to allow users to more effectively manage their updates and upgrades + +## Readability + +* Refactor UI to allow for the reuse of modern frontend tech and improve usability and accessibility + +## Scalability + +* Implement a high-availability concept +* Prepare for dynamic themes + +## Documentations + +* Improve documentations + +# Roadmap for 2023 + +## Buildability + +* ~Reduce CI build times~ +* ~Allow for auto-updating/auto-merging PRs when they are ready~ +* Provide an LTS where security patches and some bug-fixes may be backported on a longer schedule than before +* A more consistent release cadence to allow users to more effectively manage their updates and upgrades + +## Readability + +* ~Introduce an RFC process to be discussed with appropriate working groups and the TOC for large features~ +* Refactor UI to allow for improved accessiblity and usability (On the progress) +* ~Provide versioned documentation~ + +## Scalability + +* ~Continue to work on performance improvements to ensure Gitea performs even better on low-powered hardware~ +* Implement a high-availability concept (On the progress) +* Prepare for dynamic themes + +## CI/CD + +* ~Polish and introduce/promote [Actions](https://blog.gitea.io/2022/12/feature-preview-gitea-actions/) to help ease migrations to Gitea and provide a small (but powerful!) optional CI~ +* Work on a better UX for third-party CI to be able to upload and view build logs in a unified interface + +## Instant ability + +* Don't reload page when changing something in the page. i.e. changing label in issue view page. (On the progress) +* ~Display instant time on feed or commits pages~ +* Display instant changes in issue/pull request view page + +--- + +*Repo: [MokoGitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoISOUpdatePortable/ARCHITECTURE.md b/MokoConsulting/MokoISOUpdatePortable/ARCHITECTURE.md new file mode 100644 index 0000000..848fb74 --- /dev/null +++ b/MokoConsulting/MokoISOUpdatePortable/ARCHITECTURE.md @@ -0,0 +1,629 @@ +← [Home](Home) + +# Architecture Documentation + +## Overview + +MokoISOUpdatePortable is a dual-platform ISO management system with both PowerShell and C# implementations, designed for enterprise use in managing Linux distribution and system tool ISOs. + +## System Architecture + +### High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MokoISOUpdatePortable │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ PowerShell v1.x │ │ C# Standalone │ │ +│ │ (Legacy/Pro) │ │ v2.0 (Modern) │ │ +│ └──────────────────┘ └──────────────────┘ │ +│ │ │ │ +│ ├─────────────────────────────┤ │ +│ │ │ │ +│ v v │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ Core Functionality Layer │ │ +│ ├──────────────────────────────────────────────┤ │ +│ │ • Distribution Services (16 distributions) │ │ +│ │ • Download Management (retry, proxy) │ │ +│ │ • File Organization (smart sorting) │ │ +│ │ • Configuration Management │ │ +│ │ • Logging & Error Handling │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ │ │ +│ v v │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ External Services Layer │ │ +│ ├──────────────────────────────────────────────┤ │ +│ │ • Distribution APIs (Ubuntu, Debian, etc.) │ │ +│ │ • GitHub Releases (Ventoy, HBCD) │ │ +│ │ • SourceForge (GParted, SystemRescue, etc.) │ │ +│ │ • Mirror Networks │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Component Architecture + +### PowerShell Version (v1.x) + +**File:** `src/App/ISOUpdater/MokoISOUpdaterPortable.ps1` + +**Architecture:** +``` +┌──────────────────────────────────────┐ +│ PowerShell Main Script │ +├──────────────────────────────────────┤ +│ │ +│ 1. Bootstrap & Initialization │ +│ ├─ Parameter validation │ +│ ├─ Path setup │ +│ └─ Configuration loading │ +│ │ +│ 2. Utility Functions │ +│ ├─ Write-Log │ +│ ├─ Read-Ini / Write-Ini │ +│ ├─ Download-File (with retry) │ +│ └─ Parse-Version │ +│ │ +│ 3. Distribution Fetchers │ +│ ├─ Get-Ubuntu-Releases │ +│ ├─ Get-Debian-Netinst │ +│ ├─ Get-Fedora │ +│ ├─ Get-CentOS │ +│ └─ ... (11 more services) │ +│ │ +│ 4. File Management │ +│ ├─ Resort-Files │ +│ ├─ Cleanup-Prompt │ +│ └─ Ensure-PlatformFolders │ +│ │ +│ 5. GUI Layer (Windows Forms) │ +│ ├─ Form creation │ +│ ├─ Event handlers │ +│ ├─ Settings management │ +│ └─ Update execution │ +│ │ +└──────────────────────────────────────┘ +``` + +**Key Features:** +- Single-file monolithic design (~1400 lines) +- Windows Forms GUI +- Direct API/HTTP calls +- INI-based configuration +- Structured logging with rotation + +### C# Version (v2.0) + +**Location:** `src/app/` + +**Architecture:** +``` +┌──────────────────────────────────────────────────────────┐ +│ C# Application Architecture │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ MokoISOUpdater (GUI Project) │ │ +│ │ ├─ Program.cs (Entry point) │ │ +│ │ ├─ MainForm.cs (Main window) │ │ +│ │ └─ MainForm.Designer.cs (UI layout) │ │ +│ └────────────────────────────────────────────┘ │ +│ │ uses │ +│ v │ +│ ┌────────────────────────────────────────────┐ │ +│ │ MokoISOUpdater.Core (Business Logic) │ │ +│ │ │ │ +│ │ Models/ │ │ +│ │ ├─ Configuration.cs │ │ +│ │ ├─ IsoInfo.cs │ │ +│ │ └─ DownloadProgress.cs │ │ +│ │ │ │ +│ │ Services/ │ │ +│ │ ├─ IDistributionService (interface) │ │ +│ │ ├─ BaseDistributionService (abstract) │ │ +│ │ ├─ DownloadService │ │ +│ │ ├─ ConfigService │ │ +│ │ ├─ FileSortingService │ │ +│ │ └─ Distribution Services (16 impl.) │ │ +│ │ ├─ UbuntuService │ │ +│ │ ├─ DebianService │ │ +│ │ └─ ... (14 more) │ │ +│ │ │ │ +│ │ Utilities/ │ │ +│ │ └─ Logger.cs (NLog wrapper) │ │ +│ │ │ │ +│ └────────────────────────────────────────────┘ │ +│ │ tested by │ +│ v │ +│ ┌────────────────────────────────────────────┐ │ +│ │ MokoISOUpdater.Tests (Unit Tests) │ │ +│ │ ├─ BasicModelTests.cs │ │ +│ │ └─ ... (future service tests) │ │ +│ └────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +**Design Principles:** +- **Separation of Concerns:** UI, business logic, and data models separated +- **Dependency Injection Ready:** Interface-based services +- **Testability:** Core logic testable without UI +- **Extensibility:** Easy to add new distributions +- **Maintainability:** Modular, well-documented code + +## Data Flow + +### ISO Download Flow + +``` +User Action (GUI) + │ + v +┌──────────────────┐ +│ Get Distribution │ ← User selects distribution +│ Releases │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Distribution │ ← Service fetches latest ISOs +│ Service │ from API/mirror +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Filter by │ ← Apply stream/version filter +│ Configuration │ (stable, LTS, etc.) +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Display in GUI │ ← Show available ISOs +│ ListView │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ User Selects │ ← User checks ISOs to download +│ ISOs │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Download Service │ ← Downloads with: +│ │ • Retry logic (3 attempts) +│ │ • Progress reporting +│ │ • Proxy support +│ │ • Checksum validation +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Save to Disk │ ← Store in IsoRoot directory +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Update Log │ ← Record success/failure +└──────────────────┘ +``` + +### File Sorting Flow + +``` +User Action + │ + v +┌──────────────────┐ +│ Scan IsoRoot │ ← Find all .iso and .zip files +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Pattern Matching │ ← Regex patterns from isos.json +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Keyword Fallback │ ← If regex fails, use keywords +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Group by │ ← Organize by distribution +│ Destination │ (linux/, tools/, etc.) +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Show Preview │ ← Display proposed moves +└──────────────────┘ + │ + v +┌──────────────────┐ +│ User Confirms │ ← User reviews and confirms +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Execute Moves │ ← Move files to subdirectories +└──────────────────┘ +``` + +## Distribution Services + +### Service Interface + +All distribution services implement `IDistributionService`: + +```csharp +public interface IDistributionService +{ + string Name { get; } + bool SupportsStreams { get; } + List AvailableStreams { get; } + Task> GetLatestReleasesAsync(string stream = null); +} +``` + +### Service Types + +**API-Based Services:** +- Ubuntu: Launchpad API +- Ventoy: GitHub Releases API +- HBCD: GitHub Releases API + +**Mirror-Based Services:** +- Debian: Debian CD mirrors +- Fedora: Fedora mirrors +- CentOS: CentOS mirrors +- Rocky Linux: Rocky mirrors +- AlmaLinux: Alma mirrors + +**SourceForge Services:** +- GParted: SourceForge API +- SystemRescue: SourceForge API +- Clonezilla: SourceForge API + +**Web Scraping Services:** +- Kali Linux: Downloads page parsing +- Linux Mint: Mirror page parsing +- Memtest86+: Website parsing + +**Information Only:** +- Windows: Links to Microsoft download pages (no automated download) + +## Configuration Management + +### Configuration Storage + +**Format:** INI file +**Location:** `Data/settings/MokoISOUpdater.ini` + +**Structure:** +```ini +[Updater] +IsoRoot=D:\ISOs +KeepVersions=2 +LogRetentionDays=30 + +# Distribution flags +Ubuntu=true +Debian=true +Fedora=false +... + +# Proxy configuration +ProxyServer=http://proxy.company.com:8080 +ProxyUsername=user +ProxyPassword=encrypted + +[Streams] +Ubuntu=stable,lts +Fedora=40,41 +CentOS=9,10 +``` + +### Configuration Loading Priority + +1. **Command-line parameters** (highest priority) +2. **INI file configuration** +3. **Default values** (fallback) + +## Logging Architecture + +### Log Structure + +**Format:** Structured text with severity levels +**Location:** `Data/logs/moko-iso-update-YYYYMMDD.log` + +**Log Levels:** +- INFO: Normal operations +- WARN: Warnings, recoverable issues +- ERROR: Errors, failed operations + +**Log Rotation:** +- Daily log files +- Retention based on `LogRetentionDays` setting +- Automatic cleanup of old logs + +### Logging Flow + +``` +Operation + │ + v +┌─────────────┐ +│ Write-Log() │ ← PowerShell +│ or │ +│ Logger.Log()│ ← C# +└─────────────┘ + │ + v +┌─────────────┐ +│ Format │ ← [YYYY-MM-DD HH:MM:SS] [LEVEL] Message +│ Message │ +└─────────────┘ + │ + v +┌─────────────┐ +│ Write to │ ← Append to daily log file +│ Log File │ +└─────────────┘ + │ + v +┌─────────────┐ +│ Rotate if │ ← Check if new day +│ Needed │ +└─────────────┘ +``` + +## Network Architecture + +### Proxy Support + +**Configuration Methods:** +1. INI file (ProxyServer, ProxyUsername, ProxyPassword) +2. Environment variables (HTTP_PROXY, http_proxy) +3. Command-line parameters + +**Proxy Flow:** +``` +HTTP Request + │ + v +┌──────────────┐ +│ Check Proxy │ ← Get proxy from config/env +│ Config │ +└──────────────┘ + │ + v +┌──────────────┐ +│ Configure │ ← Set WebProxy on HttpClient +│ HttpClient │ or WebClient +└──────────────┘ + │ + v +┌──────────────┐ +│ Make Request │ ← Request goes through proxy +└──────────────┘ +``` + +### Retry Logic + +**Strategy:** Exponential backoff with 3 attempts + +``` +Attempt 1 + │ Fail + v +Wait 1 second + │ + v +Attempt 2 + │ Fail + v +Wait 2 seconds + │ + v +Attempt 3 + │ Fail + v +Report Error +``` + +## Security Architecture + +### Security Layers + +**1. Input Validation:** +- Path validation (no path traversal) +- Configuration validation +- URL validation + +**2. Secure Communication:** +- HTTPS for all downloads +- Certificate validation +- Proxy authentication support + +**3. File Security:** +- Checksum verification (SHA256) +- Safe file handling +- Cleanup of partial downloads + +**4. Error Handling:** +- No sensitive data in logs +- Secure credential storage +- Error messages don't expose system details + +### Threat Mitigation + +**Path Traversal:** Validate all file paths +**Code Injection:** No dynamic code execution +**MITM Attacks:** HTTPS enforced +**Credential Exposure:** Credentials not logged + +## Deployment Architecture + +### Repository Structure + +``` +/ +├── src/ # Source code +│ └── csharp/ # C# projects +├── build/ # Build artifacts (gitignored) +│ ├── standalone/ # Executables +│ ├── framework-dependent/ +│ └── test-results/ +├── scripts/ # Build scripts +├── tests/ # Test files +├── docs/ # Documentation +└── .github/ # CI/CD workflows +``` + +### Build Pipeline + +**Trigger:** Push to main, develop, or release branches + +``` +Code Push + │ + v +┌──────────────────┐ +│ Validate │ ← PSScriptAnalyzer, syntax +│ PowerShell │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Build C# │ ← dotnet build +│ │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Run Tests │ ← xUnit + Pester +│ │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Security Scan │ ← CodeQL, Trivy +│ │ +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Generate │ ← Create standalone exe +│ Artifacts │ and packages +└──────────────────┘ + │ + v +┌──────────────────┐ +│ Publish to │ ← If release tag +│ GitHub Release │ +└──────────────────┘ +``` + +## Performance Considerations + +### Optimization Strategies + +**1. Parallel Downloads:** (Future enhancement) +- Multiple ISOs downloaded concurrently +- Configurable concurrency limit + +**2. Caching:** +- Cache API responses (short TTL) +- Avoid redundant requests + +**3. Efficient Sorting:** +- Regex compilation +- Single-pass file scanning + +**4. Async Operations:** +- C# version uses async/await throughout +- Non-blocking UI operations + +### Resource Management + +**Memory:** +- Stream large downloads (don't load entirely in memory) +- Dispose resources properly (using statements) + +**Disk:** +- Clean up failed downloads +- Log rotation to prevent disk fill + +**Network:** +- Retry with backoff to avoid overwhelming servers +- Respect rate limits + +## Future Architecture Enhancements + +### Planned Improvements + +1. **Plugin System:** Allow third-party distribution plugins +2. **API Server:** REST API for programmatic access +3. **Database:** SQLite for better metadata management +4. **Parallel Downloads:** Concurrent ISO downloads +5. **Differential Updates:** Only download changed portions +6. **Mirror Selection:** Automatic best mirror selection +7. **Torrent Support:** BitTorrent for popular ISOs + +### Scalability Considerations + +**Current:** Single-user, single-machine +**Future:** Support for: +- Multiple concurrent users +- Network share deployment +- Centralized management console +- Usage analytics and reporting + +## Technology Stack + +### PowerShell Version +- **Language:** PowerShell 5.1+ +- **UI:** Windows Forms (.NET) +- **HTTP:** Invoke-WebRequest +- **Config:** Custom INI parser + +### C# Version +- **Language:** C# 10.0 +- **Framework:** .NET 8.0 +- **UI:** Windows Forms +- **HTTP:** HttpClient +- **Logging:** NLog +- **Testing:** xUnit, FluentAssertions, Moq +- **Build:** MSBuild, dotnet CLI + +### Infrastructure +- **CI/CD:** Gitea Actions +- **Security:** CodeQL, Trivy, Dependabot +- **Version Control:** Git +- **Hosting:** GitHub + +## References + +- [BUILD.md](BUILD.md) - Build instructions +- [CSHARP.md](CSHARP.md) - C# project documentation +- [GOVERNANCE.md](GOVERNANCE.md) - Development governance +- [SECURITY.md](SECURITY.md) - Security policy + +--- + +**Last Updated:** 2026-02-08 +**Version:** 1.0.0 + +--- + +*Repo: [MokoISOUpdatePortable](https://git.mokoconsulting.tech/MokoConsulting/MokoISOUpdatePortable) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoISOUpdatePortable/BUILD-DIRECTORY.-.-.md b/MokoConsulting/MokoISOUpdatePortable/BUILD-DIRECTORY.-.-.md new file mode 100644 index 0000000..7ebacb8 --- /dev/null +++ b/MokoConsulting/MokoISOUpdatePortable/BUILD-DIRECTORY.-.-.md @@ -0,0 +1,39 @@ +← [Home](Home) + +# Build Directory + +This directory contains the built artifacts of MokoISOUpdatePortable. + +## Structure + +- `standalone/` - Self-contained executables (no .NET runtime required) +- `framework-dependent/` - Framework-dependent builds (requires .NET runtime) +- `test-results/` - Test execution results and coverage reports + +## Building + +To build the software, run the build scripts from the project root: + +```powershell +# Windows PowerShell +./scripts/build-standalone.ps1 +``` + +```bash +# Linux/Mac +./scripts/build-standalone.sh +``` + +The build output will be placed in the appropriate subdirectory based on the build configuration. + +## Note + +All contents of this directory (except this README and .gitignore) are excluded from version control as they are generated artifacts. + +--- + +*Repo: [MokoISOUpdatePortable](https://git.mokoconsulting.tech/MokoConsulting/MokoISOUpdatePortable) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoISOUpdatePortable/BUILD.md b/MokoConsulting/MokoISOUpdatePortable/BUILD.md new file mode 100644 index 0000000..0869d15 --- /dev/null +++ b/MokoConsulting/MokoISOUpdatePortable/BUILD.md @@ -0,0 +1,1033 @@ +← [Home](Home) + +# MokoISOUpdater - Comprehensive Build Guide + +> **Complete build instructions for developers, contributors, and CI/CD pipelines** + +**VERSION:** 02.00.00 +**LAST UPDATED:** 2026-02-08 +**BUILD TARGET:** Windows x64 +**FRAMEWORK:** .NET 8.0 + +--- + +## Table of Contents + +1. [Prerequisites](#prerequisites) +2. [Environment Setup](#environment-setup) +3. [Quick Start](#quick-start) +4. [Building Components](#building-components) +5. [Build Configurations](#build-configurations) +6. [Build Scripts](#build-scripts) +7. [Installer Creation](#installer-creation) +8. [Troubleshooting](#troubleshooting) +9. [CI/CD Integration](#cicd-integration) +10. [Verification](#verification) + +--- + +## Prerequisites + +### Required Software + +#### 1. .NET SDK 8.0 or Later + +**Download:** https://dotnet.microsoft.com/download/dotnet/8.0 + +**Minimum Version:** 8.0.100 +**Recommended Version:** 8.0.x (latest patch) +**Platform:** Windows x64 + +**Installation Steps:** +```bash +# Download the installer +# Run: dotnet-sdk-8.0.xxx-win-x64.exe + +# Verify installation +dotnet --version +# Expected output: 8.0.xxx or later +``` + +**Verification:** +```bash +dotnet --list-sdks +# Should show: 8.0.xxx [C:\Program Files\dotnet\sdk] + +dotnet --list-runtimes +# Should include: Microsoft.NETCore.App 8.0.x +# Microsoft.WindowsDesktop.App 8.0.x +``` + +#### 2. Git for Windows + +**Download:** https://git-scm.com/download/win + +**Minimum Version:** 2.30.0 +**Recommended Version:** Latest stable + +**Installation Options:** +- Default editor: Visual Studio Code (recommended) or your preference +- PATH environment: "Git from the command line and also from 3rd-party software" +- HTTPS transport backend: OpenSSL +- Line ending conversion: "Checkout Windows-style, commit Unix-style" + +**Verification:** +```bash +git --version +# Expected: git version 2.x.x or later +``` + +#### 3. Build Tools (Choose One) + +**Option A: Visual Studio 2022** + +**Download:** https://visualstudio.microsoft.com/downloads/ + +**Edition:** Community (free), Professional, or Enterprise +**Workloads Required:** +- ".NET desktop development" +- ".NET Multi-platform App UI development" (optional, for MAUI) + +**Components:** +- .NET 8.0 Runtime +- .NET SDK +- MSBuild +- NuGet Package Manager + +**Verification:** +- Open Visual Studio +- Help → About Microsoft Visual Studio +- Check for ".NET 8.0 SDK" in installed components + +**Option B: Visual Studio Code** + +**Download:** https://code.visualstudio.com/ + +**Extensions Required:** +- C# (ms-dotnettools.csharp) +- C# Dev Kit (ms-dotnettools.csdevkit) +- .NET Install Tool (ms-dotnettools.vscode-dotnet-runtime) + +**Installation:** +```bash +# Install via command line +code --install-extension ms-dotnettools.csharp +code --install-extension ms-dotnettools.csdevkit +``` + +**Option C: Command Line Only (Minimal)** + +Just install .NET SDK - no IDE required for command-line builds. + +### Optional Software + +#### 4. Inno Setup (For Installer Creation) + +**Download:** https://jrsoftware.org/isdl.php + +**Version:** 6.2.0 or later +**Purpose:** Creating Windows installer (.exe) + +**Installation:** +- Download: innosetup-6.x.x.exe +- Run installer with default options +- Add to PATH (optional): `C:\Program Files (x86)\Inno Setup 6\` + +**Verification:** +```bash +iscc.exe /? +# Should display Inno Setup Compiler help +``` + +#### 5. PowerShell 7+ (For Build Scripts) + +**Download:** https://github.com/PowerShell/PowerShell/releases + +**Purpose:** Running PowerShell build scripts +**Note:** Windows PowerShell 5.1 (built-in) also works + +**Installation:** +```bash +# Via winget +winget install Microsoft.PowerShell + +# Via MSI +# Download and run PowerShell-7.x.x-win-x64.msi +``` + +**Verification:** +```bash +pwsh --version +# Expected: PowerShell 7.x.x or later +``` + +--- + +## Environment Setup + +### 1. Clone the Repository + +```bash +# HTTPS (recommended for most users) +git clone https://github.com/mokoconsulting-tech/MokoISOUpdatePortable.git + +# SSH (for contributors with SSH keys) +git clone git@github.com:mokoconsulting-tech/MokoISOUpdatePortable.git + +# Navigate to repository +cd MokoISOUpdatePortable +``` + +### 2. Verify Directory Structure + +```bash +ls -la +# Should show: +# - App/ (PortableApps structure) +# - Data/ (User data directory) +# - Other/ (Source code) +# - build/ (Build outputs) +# - docs/ (Documentation) +# - installer/ (Inno Setup config) +# - scripts/ (Build scripts) +# - CHANGELOG.md +# - LICENSE +# - README.md +``` + +### 3. Configure Build Environment + +**Set Environment Variables (Optional):** + +```bash +# Windows Command Prompt +set DOTNET_CLI_TELEMETRY_OPTOUT=1 +set DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1 + +# PowerShell +$env:DOTNET_CLI_TELEMETRY_OPTOUT=1 +$env:DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1 + +# Permanently (System Settings → Environment Variables) +``` + +**Configure NuGet Sources:** + +```bash +# Verify NuGet sources +dotnet nuget list source + +# Default should include: +# - nuget.org [Enabled] +# https://api.nuget.org/v3/index.json + +# Add corporate NuGet source (if needed) +dotnet nuget add source https://your-nuget-server/v3/index.json \ + --name Corporate \ + --username your-username \ + --password your-password \ + --store-password-in-clear-text +``` + +### 4. Restore Dependencies + +```bash +# Restore all project dependencies +cd Other/Source/csharp +dotnet restore MokoISOUpdater.slnx + +# Expected output: +# Determining projects to restore... +# Restored /path/to/MokoISOUpdater.Core/MokoISOUpdater.Core.csproj +# Restored /path/to/MokoISOUpdater/MokoISOUpdater.csproj +# Restored /path/to/MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj +``` + +--- + +## Quick Start + +### One-Command Build (Recommended) + +```bash +# From repository root +dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj \ + -c Release \ + -r win-x64 \ + --self-contained true \ + -p:PublishSingleFile=true \ + -o App/MokoISOUpdater +``` + +**Output:** `App/MokoISOUpdater/MokoISOUpdater.exe` (~149 MB) + +**Verification:** +```bash +ls -lh App/MokoISOUpdater/MokoISOUpdater.exe +# Should show: ~149 MB executable +``` + +**Test Run:** +```bash +./App/MokoISOUpdater/MokoISOUpdater.exe +# Application should launch +``` + +--- + +## Building Components + +### Component 1: Core Library (MokoISOUpdater.Core) + +**Purpose:** Business logic, models, services + +**Build Command:** +```bash +cd Other/Source/csharp +dotnet build MokoISOUpdater.Core/MokoISOUpdater.Core.csproj -c Release +``` + +**Output Location:** +``` +Other/Source/csharp/MokoISOUpdater.Core/bin/Release/net8.0/ +├── MokoISOUpdater.Core.dll +├── MokoISOUpdater.Core.pdb +├── MokoISOUpdater.Core.deps.json +└── NLog.dll (dependency) +``` + +**Verification:** +```bash +# Check assembly info +dotnet --info Other/Source/csharp/MokoISOUpdater.Core/bin/Release/net8.0/MokoISOUpdater.Core.dll + +# Check file size +ls -lh Other/Source/csharp/MokoISOUpdater.Core/bin/Release/net8.0/MokoISOUpdater.Core.dll +# Expected: ~50-80 KB +``` + +### Component 2: Main Application (MokoISOUpdater) + +**Purpose:** Windows Forms GUI, application entry point + +**Build Command:** +```bash +cd Other/Source/csharp +dotnet build MokoISOUpdater/MokoISOUpdater.csproj -c Release +``` + +**Output Location:** +``` +Other/Source/csharp/MokoISOUpdater/bin/Release/net8.0-windows/ +├── MokoISOUpdater.exe +├── MokoISOUpdater.dll +├── MokoISOUpdater.pdb +├── MokoISOUpdater.Core.dll +├── MokoISOUpdater.deps.json +├── MokoISOUpdater.runtimeconfig.json +└── [Windows Forms dependencies] +``` + +**Warnings (Normal):** +``` +warning CS8600: Converting null literal or possible null value to non-nullable type +warning CS8602: Dereference of a possibly null reference +warning CS0219: The variable 'xxx' is assigned but its value is never used +``` + +**These are non-critical and can be ignored for Release builds.** + +### Component 3: Portable Launcher (MokoISOUpdaterPortable) + +**Purpose:** PortableApps.com launcher wrapper + +**Build Command:** +```bash +cd Other/Source/Launcher + +# Note: This requires building on Windows or with EnableWindowsTargeting=true +dotnet build MokoISOUpdaterPortable.csproj -c Release -r win-x64 --self-contained +``` + +**Cross-Platform Build (Linux/macOS):** +```bash +dotnet build MokoISOUpdaterPortable.csproj \ + -c Release \ + -r win-x64 \ + --self-contained \ + -p:EnableWindowsTargeting=true +``` + +**Output Location:** +``` +Other/Source/Launcher/bin/Release/net8.0-windows/win-x64/ +└── MokoISOUpdaterPortable.exe +``` + +### Component 4: Test Suite + +**Purpose:** Unit tests and integration tests + +**Build Command:** +```bash +cd Other/Source/csharp +dotnet build MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj -c Release +``` + +**Run Tests:** +```bash +dotnet test MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj \ + --configuration Release \ + --logger "console;verbosity=detailed" +``` + +**Expected Output:** +``` +Passed! - Failed: 0, Passed: 12, Skipped: 0, Total: 12 +Test Run Successful. +Total tests: 12 + Passed: 12 +``` + +**With Code Coverage:** +```bash +dotnet test MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj \ + --configuration Release \ + --collect:"XPlat Code Coverage" \ + --results-directory ./TestResults +``` + +--- + +## Build Configurations + +### Configuration 1: Debug Build (Development) + +**Purpose:** Local development, debugging + +```bash +dotnet build Other/Source/csharp/MokoISOUpdater.slnx -c Debug +``` + +**Characteristics:** +- No optimizations +- Full debug symbols (.pdb) +- Larger file size +- Slower execution +- Better stack traces +- Debugger support + +**Output Size:** ~150 MB (unoptimized) + +### Configuration 2: Release Build (Production) + +**Purpose:** Production deployment + +```bash +dotnet build Other/Source/csharp/MokoISOUpdater.slnx -c Release +``` + +**Characteristics:** +- Full optimizations +- Minimal debug symbols +- Smaller file size +- Faster execution +- Release-ready + +**Output Size:** ~149 MB (optimized) + +### Configuration 3: Self-Contained Publish + +**Purpose:** Standalone executable with bundled runtime + +```bash +dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj \ + -c Release \ + -r win-x64 \ + --self-contained true \ + -p:PublishSingleFile=true \ + -o App/MokoISOUpdater +``` + +**Characteristics:** +- Single .exe file (with supporting DLLs) +- No .NET runtime required +- Portable +- Larger file size + +**Output Files:** +``` +App/MokoISOUpdater/ +├── MokoISOUpdater.exe (149 MB - main executable) +├── D3DCompiler_47_cor3.dll (4.7 MB - DirectX) +├── PenImc_cor3.dll (155 KB - Pen input) +├── PresentationNative_cor3.dll (1.2 MB - WPF) +├── wpfgfx_cor3.dll (1.9 MB - WPF graphics) +├── vcruntime140_cor3.dll (122 KB - VC++ runtime) +└── [.pdb debug symbols] +``` + +**Total Size:** ~157 MB + +### Configuration 4: Framework-Dependent Publish + +**Purpose:** Smaller deployment when .NET is already installed + +```bash +dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj \ + -c Release \ + -r win-x64 \ + --self-contained false \ + -o build/framework-dependent +``` + +**Characteristics:** +- Requires .NET 8.0 runtime on target +- Much smaller (~2 MB) +- Faster updates + +**Output Size:** ~2-5 MB + dependencies + +### Configuration 5: ReadyToRun (AOT) + +**Purpose:** Faster startup time + +```bash +dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj \ + -c Release \ + -r win-x64 \ + --self-contained true \ + -p:PublishSingleFile=true \ + -p:PublishReadyToRun=true \ + -o build/ready-to-run +``` + +**Characteristics:** +- Ahead-of-time compiled +- Faster startup (~30% improvement) +- Larger file size (+10-20 MB) + +**Output Size:** ~165 MB + +--- + +## Build Scripts + +### Script 1: Build All (Bash - Linux/macOS/WSL) + +**Location:** `scripts/build-standalone.sh` + +```bash +#!/bin/bash +# Build MokoISOUpdater standalone executable + +set -e + +echo "Building MokoISOUpdater..." + +# Navigate to project +cd "$(dirname "$0")/.." + +# Clean previous build +rm -rf App/MokoISOUpdater/* + +# Restore dependencies +echo "Restoring dependencies..." +dotnet restore Other/Source/csharp/MokoISOUpdater.slnx + +# Build and publish +echo "Publishing..." +dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj \ + -c Release \ + -r win-x64 \ + --self-contained true \ + -p:PublishSingleFile=true \ + -o App/MokoISOUpdater + +echo "✓ Build complete!" +echo "Output: App/MokoISOUpdater/MokoISOUpdater.exe" +ls -lh App/MokoISOUpdater/MokoISOUpdater.exe +``` + +**Usage:** +```bash +chmod +x scripts/build-standalone.sh +./scripts/build-standalone.sh +``` + +### Script 2: Build and Test (Complete) + +**Create:** `scripts/build-all.sh` + +```bash +#!/bin/bash +set -e + +echo "=== MokoISOUpdater Complete Build ===" + +# 1. Clean +echo "→ Cleaning..." +rm -rf App/MokoISOUpdater/* +rm -rf build/test-results/* + +# 2. Restore +echo "→ Restoring dependencies..." +dotnet restore Other/Source/csharp/MokoISOUpdater.slnx + +# 3. Build +echo "→ Building solution..." +dotnet build Other/Source/csharp/MokoISOUpdater.slnx -c Release + +# 4. Test +echo "→ Running tests..." +dotnet test Other/Source/csharp/MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj \ + -c Release \ + --no-build \ + --logger "console;verbosity=normal" + +# 5. Publish +echo "→ Publishing standalone executable..." +dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj \ + -c Release \ + -r win-x64 \ + --self-contained true \ + -p:PublishSingleFile=true \ + --no-build \ + -o App/MokoISOUpdater + +echo "✓ Build complete!" +echo "Output: App/MokoISOUpdater/MokoISOUpdater.exe" +``` + +--- + +## Installer Creation + +### Prerequisites + +- Inno Setup 6.2.0+ installed +- Application built to `App/MokoISOUpdater/` + +### Build Installer + +**Method 1: Inno Setup GUI** + +1. Open Inno Setup Compiler +2. File → Open: `installer/setup.iss` +3. Build → Compile +4. Output: `build/installer/MokoISOUpdater-Setup-2.0.0.exe` + +**Method 2: Command Line** + +```bash +# Windows Command Prompt +"C:\Program Files (x86)\Inno Setup 6\iscc.exe" installer\setup.iss + +# PowerShell +& "C:\Program Files (x86)\Inno Setup 6\iscc.exe" installer\setup.iss + +# If in PATH +iscc.exe installer\setup.iss +``` + +**Expected Output:** +``` +Inno Setup Compiler +Version 6.x.x + +Compiling... +Processing: [Setup] +Processing: [Files] +Processing: [Icons] +Processing: [Run] + +Successful compile (0.xxx sec) + +Output file: + C:\...\build\installer\MokoISOUpdater-Setup-2.0.0.exe +``` + +**Installer Size:** ~150 MB (compressed with LZMA2) + +### Test Installer + +```bash +# Run installer in silent mode (for testing) +build\installer\MokoISOUpdater-Setup-2.0.0.exe /SILENT + +# Run installer in very silent mode (no UI) +build\installer\MokoISOUpdater-Setup-2.0.0.exe /VERYSILENT + +# Extract files without installing (for inspection) +build\installer\MokoISOUpdater-Setup-2.0.0.exe /EXTRACT:"C:\temp\extracted" +``` + +--- + +## Troubleshooting + +### Problem 1: SDK Not Found + +**Error:** +``` +The command could not be loaded, possibly because: +* You intended to execute a .NET application: + The application 'dotnet' does not exist. +``` + +**Solutions:** +```bash +# 1. Verify .NET SDK is installed +dotnet --version + +# 2. Reinstall .NET SDK +# Download from: https://dotnet.microsoft.com/download/dotnet/8.0 + +# 3. Check PATH environment variable +echo $env:PATH # PowerShell +echo %PATH% # Command Prompt + +# Should include: C:\Program Files\dotnet\ +``` + +### Problem 2: Project Not Found + +**Error:** +``` +MSBUILD : error MSB1009: Project file does not exist. +``` + +**Solutions:** +```bash +# 1. Verify you're in the correct directory +pwd # or cd + +# 2. Check file exists +ls Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj + +# 3. Use absolute path +dotnet build "C:\full\path\to\MokoISOUpdater.csproj" +``` + +### Problem 3: Restore Failed + +**Error:** +``` +error NU1301: Unable to load the service index for source https://api.nuget.org/v3/index.json +``` + +**Solutions:** +```bash +# 1. Check internet connection +ping api.nuget.org + +# 2. Clear NuGet cache +dotnet nuget locals all --clear + +# 3. Configure proxy (if behind corporate firewall) +$env:HTTP_PROXY="http://proxy.company.com:8080" +$env:HTTPS_PROXY="http://proxy.company.com:8080" + +# 4. Retry restore +dotnet restore --force +``` + +### Problem 4: Build Warnings + +**Warning:** +``` +warning CS8600: Converting null literal or possible null value to non-nullable type +``` + +**This is normal and can be ignored for Release builds.** + +To suppress: +```bash +dotnet build -c Release -p:NoWarn=CS8600,CS8602,CS0219 +``` + +### Problem 5: Insufficient Disk Space + +**Error:** +``` +error MSB3021: Unable to copy file ... The disk is full +``` + +**Solutions:** +```bash +# 1. Check available space +df -h # Linux/macOS +Get-PSDrive C | Select-Object Used,Free # PowerShell + +# 2. Clean build artifacts +dotnet clean Other/Source/csharp/MokoISOUpdater.slnx +rm -rf Other/Source/csharp/**/bin +rm -rf Other/Source/csharp/**/obj + +# 3. Clean NuGet cache +dotnet nuget locals all --clear +``` + +### Problem 6: Permission Denied + +**Error:** +``` +Access to the path '...' is denied +``` + +**Solutions:** +```bash +# 1. Run as administrator (Windows) +# Right-click Terminal → Run as administrator + +# 2. Check file locks +# Close Visual Studio, VS Code, and any processes using the files + +# 3. Check file permissions +icacls App\MokoISOUpdater # Windows + +# 4. Disable antivirus temporarily (may block build) +``` + +### Problem 7: Windows Forms Error on Linux + +**Error:** +``` +error NETSDK1100: To build a project targeting Windows on this operating system, +set the EnableWindowsTargeting property to true +``` + +**Solution:** +```bash +dotnet build -p:EnableWindowsTargeting=true +``` + +--- + +## CI/CD Integration + +### Gitea Actions Workflow + +**File:** `.gitea/workflows/build.yml` + +```yaml +name: Build and Test + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + build: + runs-on: windows-latest + + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '8.0.x' + + - name: Restore dependencies + run: dotnet restore Other/Source/csharp/MokoISOUpdater.slnx + + - name: Build + run: dotnet build Other/Source/csharp/MokoISOUpdater.slnx -c Release --no-restore + + - name: Test + run: dotnet test Other/Source/csharp/MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj -c Release --no-build --verbosity normal + + - name: Publish + run: dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o App/MokoISOUpdater + + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: MokoISOUpdater + path: App/MokoISOUpdater/MokoISOUpdater.exe +``` + +### Azure DevOps Pipeline + +**File:** `azure-pipelines.yml` + +```yaml +trigger: + branches: + include: + - main + - develop + +pool: + vmImage: 'windows-latest' + +steps: +- task: UseDotNet@2 + inputs: + version: '8.0.x' + +- script: dotnet restore Other/Source/csharp/MokoISOUpdater.slnx + displayName: 'Restore dependencies' + +- script: dotnet build Other/Source/csharp/MokoISOUpdater.slnx -c Release + displayName: 'Build solution' + +- script: dotnet test Other/Source/csharp/MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj -c Release + displayName: 'Run tests' + +- script: dotnet publish Other/Source/csharp/MokoISOUpdater/MokoISOUpdater.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o App/MokoISOUpdater + displayName: 'Publish executable' + +- task: PublishBuildArtifacts@1 + inputs: + pathToPublish: 'App/MokoISOUpdater/MokoISOUpdater.exe' + artifactName: 'MokoISOUpdater' +``` + +--- + +## Verification + +### Verify Build Success + +**1. Check File Exists:** +```bash +ls -lh App/MokoISOUpdater/MokoISOUpdater.exe +# Should show: ~149 MB file +``` + +**2. Check File Properties:** +```bash +# Windows +Get-FileHash App\MokoISOUpdater\MokoISOUpdater.exe -Algorithm SHA256 + +# Linux/macOS +sha256sum App/MokoISOUpdater/MokoISOUpdater.exe +``` + +**3. Verify Executable:** +```bash +# Check if it's a valid PE executable +file App/MokoISOUpdater/MokoISOUpdater.exe +# Expected: PE32+ executable (GUI) x86-64, for MS Windows +``` + +**4. Test Launch:** +```bash +# Run application (should open GUI) +./App/MokoISOUpdater/MokoISOUpdater.exe + +# Run with error checking +if (./App/MokoISOUpdater/MokoISOUpdater.exe) { + Write-Host "✓ Application launched successfully" +} else { + Write-Host "✗ Application failed to launch" +} +``` + +**5. Check Dependencies:** +```bash +# List all files in output directory +ls -la App/MokoISOUpdater/ + +# Should include: +# - MokoISOUpdater.exe (main) +# - D3DCompiler_47_cor3.dll +# - wpfgfx_cor3.dll +# - PresentationNative_cor3.dll +# - vcruntime140_cor3.dll +# - PenImc_cor3.dll +``` + +### Verify Tests Pass + +```bash +dotnet test Other/Source/csharp/MokoISOUpdater.Tests/MokoISOUpdater.Tests.csproj \ + -c Release \ + --logger "console;verbosity=detailed" + +# Expected output: +# Passed! - Failed: 0, Passed: 12, Skipped: 0, Total: 12 +``` + +### Verify Installer + +```bash +# 1. Check installer exists +ls -lh build/installer/MokoISOUpdater-Setup-2.0.0.exe + +# 2. Get file hash +Get-FileHash build\installer\MokoISOUpdater-Setup-2.0.0.exe -Algorithm SHA256 + +# 3. Test silent install (as admin) +build\installer\MokoISOUpdater-Setup-2.0.0.exe /SILENT /LOG="install.log" + +# 4. Verify installation +Test-Path "C:\Program Files\Moko Consulting\MokoISOUpdater\MokoISOUpdater.exe" +# Should return: True + +# 5. Test uninstall +& "C:\Program Files\Moko Consulting\MokoISOUpdater\unins000.exe" /SILENT +``` + +--- + +## Performance Benchmarks + +### Build Times (Typical) + +| Configuration | Cold Build | Incremental | Full Rebuild | +|---------------|------------|-------------|--------------| +| Debug | ~30s | ~5s | ~25s | +| Release | ~60s | ~10s | ~50s | +| Publish | ~90s | N/A | ~90s | + +**Hardware:** Intel i7, 16GB RAM, SSD + +### Output Sizes + +| Build Type | Executable | Total | Runtime Required | +|------------|------------|-------|------------------| +| Debug | ~150 MB | ~155 MB | No | +| Release | ~149 MB | ~157 MB | No | +| Framework-Dependent | ~2 MB | ~5 MB | Yes (.NET 8.0) | +| ReadyToRun | ~165 MB | ~173 MB | No | + +--- + +## Additional Resources + +- **Official .NET Documentation:** https://docs.microsoft.com/dotnet/ +- **Inno Setup Documentation:** https://jrsoftware.org/ishelp/ +- **Windows Forms Guide:** https://docs.microsoft.com/dotnet/desktop/winforms/ +- **NuGet Package Manager:** https://www.nuget.org/ +- **MSBuild Reference:** https://docs.microsoft.com/visualstudio/msbuild/ + +--- + +## Support + +For build-related issues: + +1. Check [Troubleshooting](#troubleshooting) section +2. Review [GitHub Issues](https://github.com/mokoconsulting-tech/MokoISOUpdatePortable/issues) +3. Join [Discussions](https://github.com/mokoconsulting-tech/MokoISOUpdatePortable/discussions) +4. Contact: hello@mokoconsulting.tech + +--- + +**Last Updated:** 2026-02-08 +**Build System:** .NET 8.0 + Inno Setup 6.2 +**Target Platform:** Windows 7+ (x64) +**Maintained By:** Moko Consulting + +--- + +*Repo: [MokoISOUpdatePortable](https://git.mokoconsulting.tech/MokoConsulting/MokoISOUpdatePortable) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoISOUpdatePortable/CODE_OF_CONDUCT.md b/MokoConsulting/MokoISOUpdatePortable/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..69e9b56 --- /dev/null +++ b/MokoConsulting/MokoISOUpdatePortable/CODE_OF_CONDUCT.md @@ -0,0 +1,59 @@ +← [Home](Home) + +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at hello@mokoconsulting.tech. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.3.0, available at [http://contributor-covenant.org/version/1/3/0/](http://contributor-covenant.org/version/1/3/0/) + +## Revision History + +| Date | Version | Author | Notes | +| --- | --- | --- | --- | +| 2026-01-16 | 1.3.0 | Copilot | Contributor Covenant v1.3.0 | + +--- + +*Repo: [MokoISOUpdatePortable](https://git.mokoconsulting.tech/MokoConsulting/MokoISOUpdatePortable) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/MokoConsulting/MokoISOUpdatePortable/CONTRIBUTING.md b/MokoConsulting/MokoISOUpdatePortable/CONTRIBUTING.md new file mode 100644 index 0000000..255028d --- /dev/null +++ b/MokoConsulting/MokoISOUpdatePortable/CONTRIBUTING.md @@ -0,0 +1,116 @@ +← [Home](Home) + +# Contributing to moko-platform-Template-Generic + +We appreciate your interest in contributing to this project! This document provides guidelines for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [How to Contribute](#how-to-contribute) +- [Development Workflow](#development-workflow) +- [Commit Messages](#commit-messages) +- [Pull Request Process](#pull-request-process) + +## Code of Conduct + +This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to hello@mokoconsulting.tech. + +## Getting Started + +1. Fork the repository +2. Clone your fork locally +3. Set up the development environment +4. Create a new branch for your work + +## How to Contribute + +### Reporting Bugs + +- Use the GitHub issue tracker +- Describe the bug clearly with steps to reproduce +- Include relevant logs, screenshots, or error messages +- Specify your environment (OS, version, etc.) + +### Suggesting Enhancements + +- Use the GitHub issue tracker +- Clearly describe the enhancement and its benefits +- Provide examples of how it would work + +### Contributing Code + +- Pick an issue or create one +- Fork the repository and create a branch +- Make your changes following the project conventions +- Write or update tests as needed +- Submit a pull request + +## Development Workflow + +1. Ensure your fork is up to date with the main repository +2. Create a feature branch from `main` +3. Make your changes +4. Test your changes thoroughly +5. Commit your changes with clear messages +6. Push to your fork +7. Create a pull request + +## Commit Messages + +Follow the conventional commit format: + +``` +(): + + + +