diff --git a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md index 6ee807f7..8047bd96 100644 --- a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md +++ b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md @@ -17,7 +17,7 @@ Build GoChat as a Go backend that can directly reuse the frontend from `referenc ## Current Baseline - Latest implementation checkpoint: `feat(custom-roles): align chatwoot permissions`. -- Latest documentation checkpoint: this checkpoint, recorded with the B10.3 CustomRole implementation. +- Latest documentation checkpoint: this checkpoint, recorded with the B10.4 account inbox-limit handoff contract. - Worktree status at this implementation checkpoint: B10.3 aligns CustomRole API payloads, Chatwoot permission arrays, AccountUser custom-role resolution, delete nullification, and admin gates; next active slice is B10.4 InboxLimit/account-limit create-path enforcement. - `go test ./...` passes. - Route dump succeeds with `TOTAL: 830` after adding the Chatwoot-compatible applied-SLA index route. @@ -145,6 +145,7 @@ This ledger records the committed parity checkpoints that future slices should b | `feat(audit): cover operational mutations` | Completed B10.2b audit writer coverage for the remaining named operational mutations: inbox create/update, conversation update/delete/assign/status, SLA policy create/update/delete, AgentCapacityPolicy create/update/delete, inbox capacity limit create/update/delete, and capacity-policy user assignment/removal now call the shared audit writer. | `go test ./internal/handler/api/v1 -run 'SlaPolicy\|AgentCapacity\|Inbox\|Conversation' -count=1`; `go test ./internal/service -run Audit -count=1`; `go test ./internal/handler/api/v1 -count=1`; `go test ./...`; `git diff --check`. No route changes; route dump remains `TOTAL: 830`. | Continue B10.3 CustomRole permission-key/account-user parity and B10.4 remaining InboxLimit create-path enforcement. | | `docs: land remaining parity tracker` | Converted the immediate remaining plan into executable tracking contracts: B10.3 now lists CustomRole reference files, permission-array migration, AccountUser role resolution, delete nullification, admin gates, and test exits; B10.4 records InboxLimit create-path enforcement; B11/B12 now have route/persistence/feature-gate and smoke-report landing rules. | Documentation-only checkpoint; `git diff --check` passed. | Start B10.3 implementation from the recorded CustomRole contract. | | `feat(custom-roles): align chatwoot permissions` | Completed B10.3 CustomRole parity: custom roles now accept and serialize Chatwoot permission arrays, raw list/show/create/update/delete payloads match the enterprise Jbuilder views, admin gates are enforced, `AccountUser.role` stays `agent` while `custom_role_id` drives custom permissions, profile account payloads include `custom_role_id/custom_role/permissions`, and delete clears related account users. | `go test ./internal/handler/api/v1 -run CustomRole -count=1`; `go test ./internal/service -run 'CustomRole\|RBAC' -count=1`; `go test ./internal/model -run 'CustomRole\|AccountUser' -count=1`; `go test ./internal/middleware -run AccountScope -count=1`; handler/service/model packages passed; full verification recorded below. No route changes; route dump remains `TOTAL: 830`. | Continue B10.4 remaining InboxLimit/account-limit create-path enforcement. | +| `docs: land inbox limit handoff tracker` | Landed the B10.4 reference findings and implementation contract: Chatwoot account inbox limits come from `Current.account.usage_limits[:inboxes]`, over-limit create returns `402 { error: "Account limit exceeded. Upgrade to a higher plan" }`, and capacity-policy `InboxCapacityLimit` is explicitly separate assignment-capacity data. | Documentation-only checkpoint; `git diff --check` passed. | Start B10.4 implementation from the recorded guard, migration, handler, and test plan. | ## Next Slice Contract @@ -726,10 +727,11 @@ B10.4 InboxLimit landing contract: | Area | Chatwoot reference contract | Current Go gap to close | Required landing work | | --- | --- | --- | --- | -| Limit source of truth | Enterprise inbox/account limits decide whether new inbox/channel creation is allowed. Capacity-policy inbox limits are separate assignment-capacity data. | Go has AgentCapacityPolicy/InboxCapacityLimit parity, but remaining account-limit create-path behavior is still under review. | Re-audit `reference/chatwoot` enterprise account/inbox limit code and identify the exact plan/limit model used by create flows before implementation. | -| Generic inbox create | Frontend generic inbox create must fail before persistence when the account is over limit, with a frontend-readable error shape. | Current create paths may rely on capacity-policy limits or skip account-limit checks. | Add a shared account-limit guard before generic inbox persistence and prove no inbox/channel rows are created on failure. | -| Dedicated channel create | Email, Twilio, LINE, WhatsApp, API, WebWidget, and similar dedicated channel creates must use the same guard. | Dedicated channel routes were aligned for payload shape but not fully audited for account limit enforcement. | Call the guard in dedicated channel handlers/services and preserve raw Chatwoot-compatible success payloads. | -| Tests and docs | Under-limit and over-limit paths must be covered for at least generic inbox and one dedicated channel path. | No focused B10.4 tests yet. | Add create-path tests, record exact reference files, update this tracker, and run full tests before commit. | +| Limit source of truth | `reference/chatwoot/app/controllers/api/v1/accounts/inboxes_controller.rb` calls `validate_limit` before `create`; `app/helpers/api/v1/inboxes_helper.rb` compares `Current.account.inboxes.count` with `Current.account.usage_limits[:inboxes]`; enterprise `account/plan_usage_and_limits.rb` resolves `limits['inboxes']`, `ACCOUNT_INBOXES_LIMIT`, then `ChatwootApp.max_limit`. Capacity-policy `InboxCapacityLimit` is separate assignment-capacity data. | Go has AgentCapacityPolicy/InboxCapacityLimit parity, but `model.Account` has only `AgentLimit` and create paths do not yet have an account-level inbox limit guard. | Add account-level inbox limit persistence, using local `0` as unlimited; do not reuse capacity-policy inbox limits for account create limits. | +| Generic inbox create | Over-limit create fails before persistence with HTTP `402` and body `{ "error": "Account limit exceeded. Upgrade to a higher plan" }`. | `InboxService.Create` creates generic/channel-backed inboxes without an account-limit check. | Add a shared service guard at the start of inbox creation, backed by `InboxRepo.CountByAccount`, and map the sentinel error to the exact Chatwoot `402` JSON body. | +| Dedicated channel create | Channel-specific create actions must not leave orphan channel rows when the account is already over limit. | Email/Twilio handlers roll back after service failure; LINE and other dedicated paths need pre-persistence enforcement reviewed. | Call the shared guard before channel row creation in dedicated channel handlers, then keep the service guard as a second boundary. | +| Schema and compatibility | Community Chatwoot defaults effectively allow a large maximum; enterprise can lower limits through account/global config. | Existing Go schema lacks an account inbox-limit column or JSON limits equivalent. | Add `accounts.inbox_limit` migration and `model.Account.InboxLimit`; preserve local compatibility with unlimited default. | +| Tests and docs | Under-limit and over-limit paths must be covered for generic inbox and at least one dedicated channel path, including no-persistence assertions. | No focused B10.4 tests yet. | Add service and handler tests for unlimited, under-limit, over-limit, exact error body, and no orphan channel/inbox rows; update this tracker and run full tests before commit. | B10.4 exit commands: @@ -1141,15 +1143,15 @@ Excluded: 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. +- [x] SLA policies and SLA event tracking. +- [x] Audit logs and admin-readable audit endpoints. +- [x] Custom roles and permission checks. +- [x] 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. +- [x] 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. +- [x] Automation rules, macros, execution logs, and action side effects. Acceptance: @@ -1162,9 +1164,9 @@ Enterprise tracking table: | --- | --- | --- | --- | --- | | P4.1 | SLA policies/events | `internal/model/sla_policy.go`, `internal/model/sla_event.go`, `internal/service/sla_policy_service.go`, `internal/service/applied_sla_service.go`, `internal/service/sla_event_service.go`, `internal/handler/api/v1/sla_policy_handler.go` | SLA policy CRUD, applied-SLA conversation attach, idempotent core breach lifecycle, applied-SLA reports, current reference timing review, and SLA miss notifications are implemented; durable job scheduling remains Phase 5. | Review | | 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` | Audit list payload, admin access, associated-account scoping, fixed pagination, shared audit writer boundary, and named representative writer coverage are implemented; deeper resource-specific `auditable.push_event_data` remains future serializer depth if frontend requires it. | Review | -| 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.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` | Permission arrays, raw admin payloads, administrator gates, account-user resolution, profile permissions, and delete nullification are implemented; keep in Review until frontend smoke covers enterprise settings. | Review | | 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/*` | First align AgentCapacityPolicy API, serializers, nested users, and `InboxCapacityLimit` data contracts; then enforce capacity in manual/auto assignment. | Review | -| P4.5 | Inbox limits | `internal/model/agent_capacity_policy.go` `InboxCapacityLimit`, plus legacy `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` | Chatwoot enterprise nested `agent_capacity_policies/:policy_id/inbox_limits` and assignment-path enforcement are covered; next review account-level create-limit behavior and legacy route compatibility. | Review | +| P4.5 | Inbox limits | `internal/model/agent_capacity_policy.go` `InboxCapacityLimit`, plus legacy `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` | Chatwoot enterprise nested `agent_capacity_policies/:policy_id/inbox_limits` and assignment-path enforcement are covered; B10.4 now owns account-level `usage_limits[:inboxes]` create-path enforcement. | Doing | | 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` | Account-side list/metrics/review-note payloads, public update depth, resolve-triggered generic survey send, and download CSV are aligned; channel-specific template send hooks remain Phase 5 integration work. | Review | | P4.8 | Automation and macros | `internal/automation/*`, `internal/handler/api/v1/automation_rule_handler.go`, `internal/handler/api/v1/macro_handler.go` | Automation-rule CRUD/listener/log/external-action delivery and macro CRUD/display-ID execution parity are implemented; durable delayed actions and deeper macro attachment/file parity remain B9.3/B9.4 follow-ups. | Review | @@ -1180,8 +1182,8 @@ Enterprise work package breakdown: | Automation rules | CRUD payload parity, condition/action parity, event listener coverage, delayed actions, execution logs, no-stop-on-match behavior, webhook and transcript actions. | B9.1a CRUD, B9.1b listener coverage, B9.1c execution outcome logging, and B9.1d retryable webhook/email transcript delivery are covered. Durable delayed actions remain B9.3/Phase 5. | Review | | Macros | Macro CRUD, availability by account/user, execute side effects, validation, audit/log output. | CRUD payloads, visibility/authorization, display-ID execution, labels/status/messages/private notes, and empty execute/delete responses are covered by `feat(macros): align chatwoot macro payloads`; deeper attachment files and durable queue remain follow-ups. | Review | | Audit | Audit model parity, mutating action coverage, request metadata, filters/pagination, admin endpoint payloads. | List/admin payload parity is covered by `feat(audit): align chatwoot audit log payloads`; named representative writer coverage is covered by `feat(audit): record enterprise mutations` and `feat(audit): cover operational mutations`. | Review | -| Custom roles | Permission-key parity, account-user role resolution, policy middleware, create/update/delete behavior. | Permission matrix tests and frontend admin payload fixtures. | Todo | -| Inbox limits | Account/inbox limit models, create/update enforcement, UI-readable limit responses, admin overrides. | Chatwoot nested capacity-limit API and assignment-path enforcement are covered; account-level create limits remain for later review. | Review | +| Custom roles | Permission-key parity, account-user role resolution, policy middleware, create/update/delete behavior. | Permission arrays, raw admin payloads, admin gates, RBAC/account-scope/profile resolution, and delete nullification are covered by `feat(custom-roles): align chatwoot permissions`. | Review | +| Inbox limits | Account/inbox limit models, create/update enforcement, UI-readable limit responses, admin overrides. | Chatwoot nested capacity-limit API and assignment-path enforcement are covered; B10.4 account-level create limits are the active implementation slice. | Doing | | Captain/Copilot | Assistants, inbox bindings, scenarios, responses, documents, tools, copilot threads/messages, tasks, streaming/tool-call behavior. | Route fixtures, persistence tests, feature gates for external LLM dependencies, frontend smoke screens. | Todo | Enterprise acceptance gates: @@ -1415,3 +1417,4 @@ Verification milestone gates: - 2026-06-05: B10.2b operational audit checkpoint prepared as `feat(audit): cover operational mutations`; inbox create/update, conversation update/delete/assignment/status, SLA policy CRUD, AgentCapacityPolicy CRUD, nested inbox capacity limits, and capacity-policy users now call the shared audit writer. Focused SLA/capacity/inbox/conversation handler tests, audit service tests, handler package tests, full `go test ./...`, and `git diff --check` passed. B10.2 moves to Review; next slice is B10.3 CustomRole permission parity. - 2026-06-05: Remaining parity tracker checkpoint prepared as `docs: land remaining parity tracker`; the document now carries executable landing contracts for B10.3 CustomRole permission arrays/account-user resolution/delete nullification, B10.4 account/inbox limit create-path enforcement, B11 Captain/Copilot persistence and feature gates, and B12 reused Chatwoot frontend smoke reporting. Documentation-only checkpoint; `git diff --check` passed. - 2026-06-05: B10.3 CustomRole checkpoint prepared as `feat(custom-roles): align chatwoot permissions`; custom roles now accept/serialize Chatwoot permission arrays, return raw enterprise Jbuilder payloads, enforce administrator-only access, keep custom-role account users as `role=agent` with `custom_role_id`, load custom-role permissions through RBAC/AccountScope, expose profile account `custom_role_id/custom_role/permissions`, and nullify account users on role delete. Focused CustomRole/RBAC/model/AccountScope tests, handler/service/model package tests, and full verification were run before commit; sandboxed middleware package tests still require socket-capable execution for miniredis. Next slice is B10.4 InboxLimit create-path enforcement. +- 2026-06-05: B10.4 handoff tracker prepared as `docs: land inbox limit handoff tracker`; the active plan now records the exact Chatwoot account inbox-limit source (`usage_limits[:inboxes]`), the `402 { error: "Account limit exceeded. Upgrade to a higher plan" }` response contract, the separation from capacity-policy `InboxCapacityLimit`, the required account schema guard, dedicated-channel precheck, no-orphan persistence tests, and updated enterprise status rows. Documentation-only checkpoint; `git diff --check` passed.