chore: stabilize chatwoot parity baseline
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
# Chatwoot Parity Development Plan
|
||||
|
||||
Updated: 2026-06-04
|
||||
|
||||
## Goal
|
||||
|
||||
Build GoChat as a Go backend that can directly reuse the frontend from `reference/chatwoot`. The backend API, data contracts, side effects, permissions, and runtime behavior must match the local `reference/chatwoot` repository first. Existing docs are secondary when they conflict with the reference implementation.
|
||||
|
||||
## Confirmed Decisions
|
||||
|
||||
- Frontend: reuse Chatwoot frontend directly. Backend compatibility is mandatory.
|
||||
- Baseline: `reference/chatwoot` is the source of truth for routes, controllers, models, serializers, jobs, and service behavior.
|
||||
- Immediate order: keep `go test ./...` green first, then deepen Chatwoot behavior parity.
|
||||
- Search: final implementation must use Meilisearch. DB/LIKE search is not acceptable as the final engine.
|
||||
- Enterprise scope: exclude SSO/SAML/LDAP/OIDC. Include the remaining paid features already present in planning and code: SLA, Audit, CustomRole, AgentCapacity, Captain/Copilot, CSAT, InboxLimit, automation, macros, assignment policies, and related limits/workflows.
|
||||
|
||||
## Current Baseline
|
||||
|
||||
- `go test ./...` passes.
|
||||
- Route dump succeeds with `TOTAL: 704`.
|
||||
- Handler test stability fixes are committed into the baseline before feature parity work continues.
|
||||
- `.codegraph/` is generated indexing output and is not part of tracked product code.
|
||||
|
||||
## Phase 0: Test And Route Baseline
|
||||
|
||||
Status: done.
|
||||
|
||||
Checklist:
|
||||
|
||||
- [x] Fix `internal/handler/api/v1` route param mismatches around `:account_id`, `:id`, and resource IDs.
|
||||
- [x] Fix malformed test routes that conflict with Gin wildcard rules.
|
||||
- [x] Add defensive handling for zero-value services in handler edge tests.
|
||||
- [x] Align handler error responses where tests encode the expected Chatwoot-compatible status category.
|
||||
- [x] Keep platform routes bootable and dumpable.
|
||||
- [x] Verify `go test ./...`.
|
||||
- [x] Verify `go run ./cmd/dump_routes`.
|
||||
|
||||
Verification commands:
|
||||
|
||||
```bash
|
||||
env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go test ./...
|
||||
env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go run ./cmd/dump_routes
|
||||
```
|
||||
|
||||
## Phase 1: Meilisearch Search Engine
|
||||
|
||||
Status: next.
|
||||
|
||||
Source material:
|
||||
|
||||
- `.hermes/plans/2025-05-24-global-search-meilisearch.md`
|
||||
- `reference/chatwoot` search controllers, models, and indexing behavior
|
||||
- Current local packages under `internal/search`, `internal/handler/api/v1/search_handler.go`, and entity repositories
|
||||
|
||||
Checklist:
|
||||
|
||||
- [ ] Define a stable `SearchEngine` interface for Meilisearch-backed search and indexing.
|
||||
- [ ] Add search config for engine, host, API key, and index prefix.
|
||||
- [ ] Implement Meilisearch client wrapper with index bootstrapping and settings.
|
||||
- [ ] Define per-entity documents for conversations, messages, contacts, companies, articles, and help-center content as required by Chatwoot frontend behavior.
|
||||
- [ ] Wire create/update/delete hooks from services into indexing.
|
||||
- [ ] Add batch reindex command for existing data.
|
||||
- [ ] Keep DB search only as explicit development fallback, not as final production mode.
|
||||
- [ ] Add tests with a mocked search engine and integration hooks that can run without a live Meilisearch instance.
|
||||
- [ ] Document required Meilisearch environment variables and local startup flow.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Global search endpoint and entity search endpoints return Chatwoot-compatible payloads.
|
||||
- Search results are account-scoped.
|
||||
- Search indexing survives entity updates and deletes.
|
||||
- `go test ./...` stays green.
|
||||
|
||||
## Phase 2: Route And Controller Parity Audit
|
||||
|
||||
Status: planned.
|
||||
|
||||
Checklist:
|
||||
|
||||
- [ ] Dump Chatwoot routes from `reference/chatwoot`.
|
||||
- [ ] Dump GoChat routes with `cmd/dump_routes`.
|
||||
- [ ] Build a tracked route parity table covering method, path, controller, auth scope, request params, and response serializer.
|
||||
- [ ] Prioritize frontend-critical routes used by the Chatwoot web app.
|
||||
- [ ] Patch route names and wildcard params where Gin constraints require different internal names, while preserving external URLs.
|
||||
- [ ] Add regression tests for route groups that previously conflicted.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Route gap report is generated and checked in.
|
||||
- All currently implemented routes boot without panic.
|
||||
- Missing frontend-critical routes have tickets or implementation tasks.
|
||||
|
||||
## Phase 3: Data And Serializer Parity
|
||||
|
||||
Status: planned.
|
||||
|
||||
Checklist:
|
||||
|
||||
- [ ] Compare key Chatwoot serializers/entities with Go response payloads.
|
||||
- [ ] Align account, user, inbox, conversation, message, contact, company, team, label, canned response, campaign, help center, and notification payload shapes.
|
||||
- [ ] Verify timestamps, IDs, enum strings, nested objects, pagination metadata, and error envelopes.
|
||||
- [ ] Add fixture-driven tests for payload compatibility.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Chatwoot frontend can consume the payloads without adapter code.
|
||||
- Serializer deviations are documented only where GoChat intentionally differs.
|
||||
|
||||
## Phase 4: Enterprise Feature Completion
|
||||
|
||||
Status: planned.
|
||||
|
||||
Excluded:
|
||||
|
||||
- SSO
|
||||
- SAML
|
||||
- LDAP
|
||||
- OIDC
|
||||
|
||||
Included checklist:
|
||||
|
||||
- [ ] SLA policies and SLA event tracking.
|
||||
- [ ] Audit logs and admin-readable audit endpoints.
|
||||
- [ ] Custom roles and permission checks.
|
||||
- [ ] Agent capacity and assignment limits.
|
||||
- [ ] Assignment policies and auto-assignment compatibility.
|
||||
- [ ] Captain/Copilot assistant, custom tools, scenarios, documents, responses, and inbox bindings.
|
||||
- [ ] CSAT survey response flow, metrics, filters, and review notes.
|
||||
- [ ] Inbox limits and account/inbox usage enforcement.
|
||||
- [ ] Automation rules, macros, execution logs, and action side effects.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Each included feature has routes, persistence, authorization, tests, and Chatwoot-compatible response behavior.
|
||||
- Unsupported SSO family features are explicitly disabled or omitted without breaking frontend navigation for enabled features.
|
||||
|
||||
## Phase 5: Background Jobs And Integrations
|
||||
|
||||
Status: planned.
|
||||
|
||||
Known hotspots:
|
||||
|
||||
- `internal/worker/worker.go` is still mostly placeholder.
|
||||
- `internal/automation/action_service.go` has pending webhook/email transcript work.
|
||||
- `internal/automation/csat_survey_listener.go` has pending CSAT enable/send behavior.
|
||||
- `internal/auth/webhook_registry.go` has pending signature verification for Facebook/WhatsApp.
|
||||
- `internal/service/analytics_service.go` has placeholder analytics paths.
|
||||
|
||||
Checklist:
|
||||
|
||||
- [ ] Map Chatwoot jobs/listeners to Go worker responsibilities.
|
||||
- [ ] Implement durable job dispatch for automation, CSAT, notifications, webhooks, and search indexing.
|
||||
- [ ] Add retry and failure logging for external calls.
|
||||
- [ ] Add tests for job enqueueing and idempotency.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- User-visible side effects do not depend on synchronous handler-only execution.
|
||||
- Failed background work is observable and retryable.
|
||||
|
||||
## Ongoing Tracking Rules
|
||||
|
||||
- Every parity task should name the matching file or behavior in `reference/chatwoot`.
|
||||
- Every route change should keep `cmd/dump_routes` passing.
|
||||
- Every phase must keep `go test ./...` green before moving on.
|
||||
- Test-only route fixes should be limited to malformed tests. Production route changes must preserve external Chatwoot-compatible URLs.
|
||||
- New search work must target Meilisearch first.
|
||||
Reference in New Issue
Block a user