diff --git a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md index 09aa73a6..f4cc50e7 100644 --- a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md +++ b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md @@ -71,6 +71,20 @@ Acceptance: - Search indexing survives entity updates and deletes. - `go test ./...` stays green. +Tracking table: + +| ID | Task | Target files | Reference source | Status | +| --- | --- | --- | --- | --- | +| P1.1 | Add `SearchConfig` with engine, host, API key, index prefix, env binding, and defaults. | `internal/config/config.go`, config docs | `.hermes/plans/2025-05-24-global-search-meilisearch.md` | Todo | +| P1.2 | Add stable engine contract for search, indexing, deletes, batch indexing, and close. | `internal/search/engine.go` | Chatwoot global/entity search behavior | Todo | +| P1.3 | Implement Meilisearch engine wrapper, index naming, bootstrap, sortable/filterable/searchable settings. | `internal/search/engine_meili.go` | Chatwoot search models/services | Todo | +| P1.4 | Keep existing DB search as explicit dev fallback only. Production config must prefer Meilisearch. | `internal/search/engine_db.go`, `internal/search/search_service.go` | User decision on Meilisearch | Todo | +| P1.5 | Define documents and serializers for conversations, messages, contacts, companies, articles, and help-center content. | `internal/search/documents.go` | `reference/chatwoot` models/serializers | Todo | +| P1.6 | Wire create/update/delete hooks from entity services into async or synchronous indexing boundary. | `internal/service/*`, `internal/repository/*`, `internal/worker/*` | Chatwoot callbacks/jobs | Todo | +| P1.7 | Add batch reindex command and account/entity filters. | `cmd/reindex_search` or equivalent | Chatwoot reindex/search tasks | Todo | +| P1.8 | Add mocked engine tests and service integration tests without requiring live Meilisearch. | `internal/search/*_test.go`, touched service tests | Existing test style | Todo | +| P1.9 | Document Meilisearch env vars and local startup flow. | this doc, ops docs if needed | Hermes plan | Todo | + ## Phase 2: Route And Controller Parity Audit Status: planned. @@ -90,6 +104,17 @@ Acceptance: - All currently implemented routes boot without panic. - Missing frontend-critical routes have tickets or implementation tasks. +Tracking table: + +| ID | Task | Artifact | Status | +| --- | --- | --- | --- | +| P2.1 | Generate Chatwoot route dump from `reference/chatwoot`. | `docs/parity/chatwoot_routes.*` | Todo | +| P2.2 | Generate GoChat route dump with `cmd/dump_routes`. | `docs/parity/gochat_routes.*` | Todo | +| P2.3 | Produce route parity table: method, path, controller/handler, auth, request params, serializer, status. | `docs/parity/route_parity.md` | Todo | +| P2.4 | Mark frontend-critical gaps from Chatwoot web app route usage. | `docs/parity/route_parity.md` | Todo | +| P2.5 | Convert existing placeholders/stubs into tracked feature tasks instead of hidden debt. | this doc and gap report | Todo | +| P2.6 | Add route boot regression tests for Gin wildcard/param conflicts. | router and handler tests | Todo | + ## Phase 3: Data And Serializer Parity Status: planned. @@ -106,6 +131,24 @@ Acceptance: - Chatwoot frontend can consume the payloads without adapter code. - Serializer deviations are documented only where GoChat intentionally differs. +Frontend-critical API groups to audit first: + +| ID | Area | Scope | Status | +| --- | --- | --- | --- | +| P3.1 | Auth/session/profile | Login, logout, current user, profile, availability, notification settings. | Todo | +| P3.2 | Accounts/users/teams | Account settings, users, agents, teams, invitations, roles, permissions. | Todo | +| P3.3 | Inboxes/channels | Inbox CRUD, assignable agents, avatars, channel config, business hours, widget config. | Todo | +| P3.4 | Conversations/messages | List filters, status changes, assignment, labels, private notes, attachments, drafts, typing/read events. | Todo | +| P3.5 | Contacts/companies | CRUD, merge, labels, notes, custom attributes, import/export, conversations relation. | Todo | +| P3.6 | Labels/custom attributes/custom filters | Create/update/list behavior and exact response shapes. | Todo | +| P3.7 | Notifications/reports/help center/campaigns | Frontend-visible payloads and pagination/error envelopes. | Todo | + +Serializer comparison rules: + +- Compare against `reference/chatwoot` serializers/entities before changing Go responses. +- Prefer fixture-driven tests for exact JSON shape, enum strings, pagination metadata, and error envelopes. +- Preserve Chatwoot field names even if Go internal naming differs. + ## Phase 4: Enterprise Feature Completion Status: planned. @@ -134,6 +177,29 @@ 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. +Enterprise tracking table: + +| ID | Feature | Existing Go surface | Required next work | Status | +| --- | --- | --- | --- | --- | +| P4.1 | SLA policies/events | `internal/model/sla_policy.go`, `internal/model/sla_event.go`, `internal/service/sla_policy_service.go`, `internal/service/sla_event_service.go`, `internal/handler/api/v1/sla_policy_handler.go` | Compare with Chatwoot SLA behavior; wire lifecycle events and breach tracking; add frontend payload tests. | Todo | +| P4.2 | Audit logs | `internal/model/audit.go`, `internal/service/audit_service.go`, `internal/repository/audit_repo.go`, `internal/handler/api/v1/audit_handler.go` | Ensure every mutating enterprise/core action emits audit events and filters match Chatwoot. | Todo | +| P4.3 | Custom roles/permissions | `internal/model/custom_role.go`, `internal/service/custom_role_service.go`, `internal/middleware/role_check.go`, `internal/handler/api/v1/custom_role_handler.go` | Align permission keys, inherited roles, authorization failures, and admin UX payloads. | Todo | +| P4.4 | Agent capacity | `internal/model/agent_capacity_policy.go`, `internal/service/agent_capacity_policy_service.go`, `internal/handler/api/v1/agent_capacity_handler.go`, `internal/autoassignment/*` | Enforce capacity in assignment path and auto-assignment; add limit tests. | Todo | +| P4.5 | Inbox limits | `internal/model/inbox_limit.go`, `internal/service/inbox_limit_service.go`, `internal/repository/inbox_limit_repo.go`, `internal/handler/api/v1/inbox_limit_handler.go` | Enforce account/inbox usage limits and frontend-compatible responses. | Todo | +| P4.6 | Captain/Copilot | `internal/model/captain_models.go`, `internal/model/copilot_models.go`, `internal/service/captain_*`, `internal/service/copilot_*`, `internal/handler/api/v1/captain_*`, `internal/handler/api/v1/copilot_handler.go` | Complete assistant, tools, scenarios, documents, responses, inbox bindings, suggestions, and streaming compatibility. | Todo | +| P4.7 | CSAT | `internal/csat/*`, `internal/automation/csat_survey_*`, `internal/handler/api/v1/csat_*`, `internal/service/csat_metrics_service.go` | Wire resolve-triggered survey send, public update flow, metrics, review notes, filters. | Todo | +| P4.8 | Automation and macros | `internal/automation/*`, `internal/handler/api/v1/automation_rule_handler.go`, `internal/handler/api/v1/macro_handler.go` | Finish action side effects, execution logs, webhook/email transcript delivery, and rule trigger coverage. | Todo | +| P4.9 | Assignment policies | `internal/autoassignment/*`, `internal/automation/agent_bot_rule_listener.go` | Match Chatwoot assignment policy behavior and availability/capacity rules. | Todo | + +Excluded tracking table: + +| Feature | Decision | Required handling | +| --- | --- | --- | +| SSO | Excluded | Do not prioritize implementation. Existing surfaces should not block core frontend use. | +| SAML | Excluded | Do not expand beyond already present code unless needed to disable safely. | +| LDAP | Excluded | Omit from parity scope. | +| OIDC | Excluded | Omit from parity scope. | + ## Phase 5: Background Jobs And Integrations Status: planned. @@ -158,6 +224,63 @@ Acceptance: - User-visible side effects do not depend on synchronous handler-only execution. - Failed background work is observable and retryable. +Tracking table: + +| ID | Task | Current hotspot | Status | +| --- | --- | --- | --- | +| P5.1 | Choose and wire durable job runner compatible with current Go stack. | `internal/worker/worker.go`, `internal/channel/dispatcher.go` | Todo | +| P5.2 | Move search indexing into retryable jobs where Chatwoot uses callbacks/jobs. | search services and worker | Todo | +| P5.3 | Implement automation webhook delivery with retry, timeout, and logs. | `internal/automation/action_service.go` | Todo | +| P5.4 | Implement email transcript delivery once email infrastructure is available. | `internal/automation/action_service.go` | Todo | +| P5.5 | Complete CSAT survey send listener and idempotency. | `internal/automation/csat_survey_listener.go`, `internal/csat/listener.go` | Todo | +| P5.6 | Complete webhook signature verification for Facebook/WhatsApp/Twilio/provider paths. | `internal/auth/webhook_registry.go`, channel providers | Todo | +| P5.7 | Replace placeholder analytics with real report builders/queries. | `internal/service/analytics_service.go`, reporting services | Todo | + +## Phase 6: Core Product Placeholder Burn-down + +Status: planned. + +Purpose: route parity is not enough; existing handlers that return placeholder JSON must be converted into real Chatwoot-compatible behavior before the frontend can be reused directly. + +Tracking table: + +| ID | Area | Known references | Required next work | Status | +| --- | --- | --- | --- | --- | +| P6.1 | Account APIs | `docs/ROUTE_GAP_ANALYSIS.md`, account handlers | Replace placeholder responses with repository-backed behavior and serializer tests. | Todo | +| P6.2 | Contact APIs | `docs/ROUTE_GAP_ANALYSIS.md`, contact handlers/services | Implement show/create/update/list/search relations, labels, notes, merge. | Todo | +| P6.3 | Conversation APIs | `docs/ROUTE_GAP_ANALYSIS.md`, conversation handlers/services | Implement frontend-critical filters, assignment, status, snooze, merge, bulk actions. | Todo | +| P6.4 | Message APIs | `docs/ROUTE_GAP_ANALYSIS.md`, message handlers/services | Implement create/list/delete, private notes, attachments, source attribution, events. | Todo | +| P6.5 | Inbox APIs | `docs/ROUTE_GAP_ANALYSIS.md`, inbox handlers/services | Implement CRUD, assignable agents, avatar, campaigns, channel settings, reset secret. | Todo | +| P6.6 | Widget APIs | `docs/ROUTE_GAP_ANALYSIS.md`, widget/channel provider code | Implement init, contact, conversations, messages, cable token with Chatwoot widget contracts. | Todo | +| P6.7 | Webhook ingress | `internal/router/router.go`, `internal/handler/webhook/*`, channel providers | Replace generic placeholder with provider-specific verified ingestion and dispatch. | Todo | + +## Phase 7: Verification Harness + +Status: planned. + +Checklist: + +- [ ] Add repeatable command to compare Chatwoot and GoChat route dumps. +- [ ] Add fixture-based JSON parity tests for major frontend endpoints. +- [ ] Add Meilisearch mock tests and optional integration test mode gated by env vars. +- [ ] Add frontend smoke path using reused Chatwoot frontend once backend boot flow is ready. +- [ ] Keep a generated gap report in `docs/parity/` with date, reference commit, Go commit, and pass/fail summary. + +Required verification before each feature commit: + +```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 +``` + +## Task Status Legend + +- `Todo`: not started or only skeleton exists. +- `Doing`: implementation is underway in the current working tree. +- `Review`: code is implemented and needs parity/test verification. +- `Done`: committed, tested, and linked to the matching `reference/chatwoot` behavior. +- `Blocked`: needs a decision, missing dependency, or reference behavior cannot yet be reproduced. + ## Ongoing Tracking Rules - Every parity task should name the matching file or behavior in `reference/chatwoot`. @@ -165,3 +288,10 @@ Acceptance: - 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. +- Update this document in the same commit as each completed parity slice: change task status, add verification command output summary, and link the touched `reference/chatwoot` behavior. +- Do not count a feature as done because a model/handler exists; it is done only when route behavior, persistence, authorization, side effects, response shape, and tests are covered. +- Keep `.codegraph/` and other generated local analysis artifacts out of product commits unless explicitly requested. + +## Progress Log + +- 2026-06-04: Baseline stabilized and committed as `42cdab8 chore: stabilize chatwoot parity baseline`; `go test ./...` passed and route dump reported `TOTAL: 704`.