rogee/gochat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record csat report checkpoint

Browse Source
This commit is contained in:
rogee
2026-06-05 08:14:33 +08:00
parent f441680c76
commit fca6838a75
1 changed files with 14 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md
+14 -11
View File
@@ -16,9 +16,9 @@ Build GoChat as a Go backend that can directly reuse the frontend from `referenc
## Current Baseline
- Latest implementation checkpoint: `d23f3f0 feat(sla): notify users on sla misses`.
- Latest documentation checkpoint before this update: `64926db docs: land chatwoot parity tracking plan`.
- Worktree status at this planning checkpoint: clean after `d23f3f0`; next active slice is B8 CSAT account/public/report/send parity.
- Latest implementation checkpoint: `f441680 feat(csat): align account report payloads`.
- Latest documentation checkpoint before this update: `9e0826b docs: record sla notification checkpoint`.
- Worktree status at this planning checkpoint: clean after `f441680`; next active slice is B8 public CSAT submit/update and resolve-triggered send parity.
- `go test ./...` passes.
- Route dump succeeds with `TOTAL: 830` after adding the Chatwoot-compatible applied-SLA index route.
- Route parity artifacts now exist under `docs/parity/` and are generated by `cmd/route_parity`.
@@ -59,7 +59,7 @@ Next ordered checkpoints:
| Phase 1 | Meilisearch search engine | Review | B6 payload parity, optional live gate, and DB-fallback hardening are implemented; an actual live Meilisearch run is optional and environment-dependent |
| Phase 2 | Route and controller parity audit | Doing | Ruby/Bundler unavailable, so Chatwoot route extraction currently uses static `routes.rb` fallback |
| Phase 3 | Data and serializer parity | Doing | JSON fixture coverage is partial and still endpoint-family based |
| Phase 4 | Enterprise feature completion | Doing | B7 assignment capacity, SLA policy CRUD payload parity, applied-SLA conversation persistence, idempotent SLA breach events, applied-SLA reports, and SLA notification fan-out are implemented; B8 CSAT is active next |
| Phase 4 | Enterprise feature completion | Doing | B7 is in Review; B8 account-side CSAT report list/metrics/review-note payload parity is implemented; public CSAT/send/download depth remains active |
| Phase 5 | Background jobs and integrations | Planned | durable worker choice and job parity are open |
| Phase 6 | Core placeholder burn-down | Doing | account/contact/conversation/message/inbox placeholder groups remain broad |
| Phase 7 | Verification harness | Planned | search live gate and reused-frontend smoke harness are not complete |
@@ -127,6 +127,8 @@ This ledger records the committed parity checkpoints that future slices should b
| `330f875 docs: record applied sla reports checkpoint` | Recorded the B7.5 applied-SLA reports checkpoint in this tracker and made B7.6 the active follow-up. | Documentation-only checkpoint after the applied-SLA report/list implementation verification. | Continue B7.6 with business-hours timer math and SLA notification delivery. |
| `64926db docs: land chatwoot parity tracking plan` | Normalized this tracker after B7.5: added the planning control board, mapped Hermes plans into active B8/B9/B6 slices, and made B7.6's investigation/landing contract explicit. | Documentation-only checkpoint; `git diff --check` passed before commit. | Continue B7.6 implementation. |
| `d23f3f0 feat(sla): notify users on sla misses` | Completed B7.6 notification parity and business-hours timing review: new SLA miss events now create Chatwoot notification types for conversation participants, account administrators, and assignee with user de-duplication; repeated SLA evaluation remains event/notification idempotent; the current `reference/chatwoot` service stores `only_during_business_hours` but still calculates thresholds as elapsed seconds, so Go has a regression test for that reference timing. | `go test ./internal/service -run AppliedSlaService -count=1`; `go test ./internal/service -count=1`; `go test ./...`; `git diff --check`. No route changes; route dump remains `TOTAL: 830`. | B7 moves to Review. Next active enterprise slice is B8 CSAT account/public/report/send parity. |
| `9e0826b docs: record sla notification checkpoint` | Recorded the B7.6 SLA notification checkpoint, moved B7 to Review, and set B8 as the next active enterprise slice. | Documentation-only checkpoint after `d23f3f0`; `git diff --check` passed before commit. | Continue B8 CSAT account/public/report/send parity. |
| `f441680 feat(csat): align account report payloads` | Started B8 with account-side CSAT report parity: `GET /csat_survey_responses` now returns the raw Chatwoot array of CSAT response serializers; list and metrics filters accept frontend `since/until`, `user_ids`, `inbox_id`, `team_id`, and `rating`; metrics now returns `total_count`, `ratings_count`, and `total_sent_messages_count`; CSAT update/review-note responses return the Chatwoot CSAT response serializer with nested contact, assigned agent, reviewer, display conversation ID, and Unix timestamps. | `go test ./internal/handler/api/v1 -run CsatSurvey -count=1`; `go test ./internal/automation -run CsatSurveyService -count=1`; `go test ./internal/handler/api/v1 -count=1`; `go test ./internal/automation -count=1`; `go test ./...`; `git diff --check`. No route changes; route dump remains `TOTAL: 830`. | Continue B8 with public CSAT submit/update lock regression, resolve-triggered survey send idempotency, and download CSV parity. |
## Next Slice Contract
@@ -144,7 +146,7 @@ Next implementation slice: start B8 CSAT account/public/report/send parity.
| N6 | Keep SLA timer and breach lifecycle as current SLA lifecycle baseline. | `reference/chatwoot/enterprise/app/services/sla/evaluate_applied_sla_service.rb`, `SlaEvent`, SLA processing jobs. | Done by `213bf2b`; active applied SLAs create idempotent FRT/NRT/RT miss events, transition to `active_with_misses`, `hit`, or `missed`, and preserve status on repeated evaluation. |
| N7 | Keep applied-SLA report/list payload parity as the current SLA reports baseline. | `reference/chatwoot/enterprise/app/controllers/api/v1/accounts/applied_slas_controller.rb`, applied-SLA index/metrics/download views, dashboard SLA reports client. | Done by `4f85ef1`; account-side applied-SLA list/report filters return frontend-compatible payloads and metrics/download shapes. |
| N8 | Keep B7.6 SLA notification and timing review as current SLA closeout baseline. | `Sla::EvaluateAppliedSlaService`, `SlaEvent#create_notifications`, SLA processing jobs. | Done by `d23f3f0`; SLA miss notifications fan out to participants/admins/assignee, repeated evaluation is idempotent, and current reference timing for `only_during_business_hours` is covered. |
| N9 | Start B8 CSAT account/public/report/send parity. | CSAT account/public controllers, response model/services, listener/jobs, dashboard reports client. | First checkpoint aligns account-side CSAT list/metrics/review-note payloads. |
| N9 | Keep B8.1 account-side CSAT report payload parity as the current CSAT baseline. | `CsatSurveyResponsesController`, CSAT response Jbuilder, dashboard `csatReports.js`, CSAT store. | Done by `f441680`; list/metrics/review-note payloads and filters match the reused frontend contract. |
| N10 | Update this tracker after every implementation checkpoint. | This document. | `git diff --check`; `go test ./...` for Go changes. |
Current B2 profile checkpoint:
@@ -362,7 +364,7 @@ Upcoming enterprise task boards:
| Slice | Step | Implementation target | Reference source | Required tests | Status |
| --- | --- | --- | --- | --- | --- |
| B8 | B8.1 | Align account-side CSAT survey response index, metrics, filters, pagination, and review-note payloads. | `reference/chatwoot/app/controllers/api/v1/accounts/csat_survey_responses_controller.rb`, CSAT Jbuilder/views, dashboard reports clients. | Handler/service tests for list, metrics, review note update, date/agent/inbox/team/rating filters. | Todo |
| B8 | B8.1 | Align account-side CSAT survey response index, metrics, filters, pagination, and review-note payloads. | `reference/chatwoot/app/controllers/api/v1/accounts/csat_survey_responses_controller.rb`, CSAT Jbuilder/views, dashboard reports clients. | Handler/service tests for list, metrics, review note update, date/agent/inbox/team/rating filters. | Done by `f441680` |
| B8 | B8.2 | Align public CSAT submit/update flow, lock window, message linkage, and one-response-per-message behavior. | `reference/chatwoot/app/controllers/public/api/v1/csat_survey_controller.rb`, CSAT response model/services. | Public handler tests for submit, update within window, update after lock, duplicate response rejection. | Todo |
| B8 | B8.3 | Wire resolve-triggered CSAT survey send with idempotency and channel-aware message creation. | Chatwoot CSAT listener/jobs and inbox CSAT settings. | Listener tests prove one CSAT message per resolved conversation and no send when disabled. | Todo |
| B8 | B8.4 | Align CSAT downloads/export payloads used by reports screens. | CSAT report/download controller paths and frontend report API. | CSV/download tests cover filters and frontend column names. | Todo |
@@ -466,7 +468,7 @@ Work proceeds top-down unless a failing test or frontend blocker forces a narrow
| B5 | Inbox/channel behavior fixtures. | Chatwoot inbox/channel controllers and channel models. | Fixture tests for inbox CRUD, settings, business hours, members, avatar, channel config. | Done |
| B6 | Meilisearch live-shape review. | Chatwoot frontend search usage and search controllers. | Meilisearch-backed response fixtures plus optional live integration gate. | Review |
| B7 | SLA and assignment capacity. | Chatwoot enterprise SLA and assignment policy behavior. | Unit/integration tests for SLA state, breach, assignment capacity, policy selection. | Review |
| B8 | CSAT account-side completion. | Chatwoot CSAT survey responses, reports, downloads, listeners. | Metrics/list/review/download/send idempotency tests. | Todo |
| B8 | CSAT account-side completion. | Chatwoot CSAT survey responses, reports, downloads, listeners. | Metrics/list/review/download/send idempotency tests. | Doing |
| B9 | Automation/macros durable side effects. | Chatwoot automation/macro services and jobs. | Action execution, logs, webhook/email transcript retry tests. | Todo |
| B10 | Audit, CustomRole, InboxLimit. | Chatwoot enterprise admin behavior and policies. | Authorization, audit emission, limits enforcement, admin payload fixtures. | Todo |
| B11 | Captain/Copilot deep behavior. | Chatwoot Captain/Copilot controllers, services, frontend clients. | Assistant/tool/document/scenario/copilot thread/task tests and feature gates. | Todo |
@@ -478,7 +480,7 @@ Remaining slice landing plan:
| --- | --- | --- | --- |
| B6 | Compare current Meilisearch document fields and global/entity search payloads against Chatwoot frontend consumers. | Add optional live Meilisearch integration gate, tighten account-scoped filters, and document DB fallback as development-only. | Done only after mocked tests and live-shape review prove search payloads work without DB-only assumptions. |
| B7 | Done: assignment capacity enforcement, SLA policy CRUD payload parity, applied-SLA conversation persistence, idempotent SLA breach lifecycle, applied-SLA report/list payload parity, and SLA miss notification fan-out. | Capacity-aware assignment policy binding review and durable SLA job scheduling remain broader Phase 5/P4.9 follow-ups, not hidden SLA gaps. | Review after `d23f3f0`; move to Done only after assignment policy binding review is either implemented or split out of B7. |
| B8 | Account-side CSAT list/metrics/review-note payload parity. | Resolve-triggered survey send idempotency, report/download filters, public/update lock regression, channel-specific send hooks. | Done only after account APIs, public APIs, and resolve listener agree on one message-linked response model. |
| B8 | Done: account-side CSAT list/metrics/review-note payload parity. | Resolve-triggered survey send idempotency, report/download filters, public/update lock regression, channel-specific send hooks. | Done only after account APIs, public APIs, and resolve listener agree on one message-linked response model. |
| B9 | Macro execution side effects for labels, status, assignee/team, priority, private notes, and attachments. | Automation rule condition/action parity, execution logs, webhook delivery retry, email transcript delivery, stop-on-match semantics. | Done only after actions mutate real conversations and async external actions are retryable or explicitly feature-gated. |
| B10 | Audit list payload and audit writer boundary for representative mutating core resources. | CustomRole permission-key parity, AccountUser permission resolution, InboxLimit enforcement in inbox/channel creation paths. | Done only after authorization tests prove admin-only surfaces and non-admin denial shapes match Chatwoot. |
| B11 | Captain Assistant CRUD, inbox binding, responses, documents, and custom tools payload fixtures. | Copilot threads/messages/tasks, playground/tool-call behavior, document sync/embedding feature gates, streaming fallback. | Done only after LLM-dependent behavior is either implemented behind config or safely stubbed with frontend-compatible disabled states. |
@@ -712,7 +714,7 @@ Serializer parity work plan:
| S3 | Contacts and companies | `reference/chatwoot/app/controllers/api/v1/accounts/contacts*`, `companies*` | fixture tests for list/show/search/merge/relation payloads | Doing |
| S4 | Inboxes and channels | `reference/chatwoot/app/controllers/api/v1/accounts/inboxes*`, channel controllers | fixture tests for inbox CRUD, channel settings, widget config | Done |
| S5 | Notifications and settings | `reference/chatwoot/app/controllers/api/v1/accounts/notifications*` | fixture tests for notification list/actions/settings | Todo |
| S6 | Reports and CSAT | `reference/chatwoot/app/controllers/api/v1/accounts/reports*`, `csat_survey_responses*` | fixture tests for report filters and CSAT metrics/list | Todo |
| S6 | Reports and CSAT | `reference/chatwoot/app/controllers/api/v1/accounts/reports*`, `csat_survey_responses*` | fixture tests for report filters and CSAT metrics/list | Doing |
| S7 | Widget/public | `reference/chatwoot/app/controllers/api/v1/widget*`, `public/api/v1*` | widget smoke fixtures and public flow tests | Doing |
| S8 | Search | `reference/chatwoot` search controllers plus frontend search client | Meilisearch-backed search response fixtures | Todo |
@@ -760,7 +762,7 @@ Enterprise tracking table:
| 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.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.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 and filters are aligned; next wire public update depth, resolve-triggered survey send, and download CSV parity. | Doing |
| 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. | Doing |
@@ -770,7 +772,7 @@ Enterprise work package breakdown:
| --- | --- | --- | --- |
| SLA | Policy CRUD parity, conversation SLA assignment, first-response/next-response/resolution timers, business-hours handling, breach events, notifications. | Policy payloads, applied-SLA attach, seconds-based thresholds, core state transitions, breach idempotency, report payloads, reference `only_during_business_hours` timing, and notification fan-out are covered. Durable scheduling remains Phase 5. | Review |
| Assignment and capacity | Assignment policy CRUD, inbox policy binding, round-robin/availability/capacity selection, manual assignment limits, fallback behavior. | Manual and automatic assignment respect policy, availability, team/inbox membership, and limits. | Review |
| CSAT account side | Survey send on resolve, response list, metrics, filters, downloads, review notes, resend/idempotency, public lock already implemented. | Account API payload fixtures, metrics math, 14-day lock, one response per CSAT message. | Todo |
| CSAT account side | Survey send on resolve, response list, metrics, filters, downloads, review notes, resend/idempotency, public lock already implemented. | Account report list/metrics/review-note payload fixtures are covered by `f441680`; send/download/public depth remains. | Doing |
| Automation rules | Condition/action parity, event listener coverage, delayed actions, execution logs, stop-on-match behavior, webhook and transcript actions. | Rule trigger tests for conversation/contact/message events and durable retry for external actions. | Todo |
| Macros | Macro CRUD, availability by account/user, execute side effects, validation, audit/log output. | Execute changes conversation labels/status/assignee/team/notes/custom attributes exactly as frontend expects. | Todo |
| Audit | Audit model parity, mutating action coverage, request metadata, filters/pagination, admin endpoint payloads. | Representative mutations across core and enterprise features emit audit records. | Todo |
@@ -993,3 +995,4 @@ Verification milestone gates:
- 2026-06-05: B7 applied-SLA reports checkpoint committed as `4f85ef1 feat(sla): align applied sla reports`; account applied-SLA index/metrics/download now match Chatwoot's reports controller and frontend SLA reports API, including missed-only table/download semantics, shared filters, `{ payload, meta }` index shape, raw metrics keys, and breached-conversation CSV. Focused applied-SLA service/handler tests, service and handler package tests, full `go test ./...`, route dump `TOTAL: 830`, route parity `270 exact, 7 parameter-compatible, 0 missing`, `go test ./cmd/route_parity -count=1`, and `git diff --check` passed. Next B7 checkpoint is business-hours timer math and SLA notification delivery review.
- 2026-06-05: Development tracker was normalized for handoff continuity after `330f875 docs: record applied sla reports checkpoint`; the current baseline now points at the latest implementation and documentation checkpoints, the planning control board records the next ordered B7-B12 checkpoints, Hermes search/automation/CSAT notes are mapped into active slices, and B7.6 has an explicit investigation/landing contract.
- 2026-06-05: B7 SLA notification checkpoint committed as `d23f3f0 feat(sla): notify users on sla misses`; new FRT/NRT/RT SLA miss events now create Chatwoot notification types for conversation participants, account administrators, and conversation assignee, with de-duplication and account membership filtering. Repeated evaluation stays idempotent. Current `reference/chatwoot` timing was verified to keep `only_during_business_hours` as a stored policy flag without changing elapsed-second thresholds, and a regression test records that behavior. Focused applied-SLA tests, service package tests, full `go test ./...`, and `git diff --check` passed. B7 moves to Review; next slice is B8 CSAT account/public/report/send parity.
- 2026-06-05: B8 account-side CSAT checkpoint committed as `f441680 feat(csat): align account report payloads`; CSAT report list now returns the raw Chatwoot response array with nested contact, assigned agent, reviewer, display conversation ID, Unix timestamps, and message ID. Filters now cover frontend `since/until`, `user_ids`, `inbox_id`, `team_id`, and `rating`; metrics returns `total_count`, `ratings_count`, and `total_sent_messages_count`; update/review-note actions return the Chatwoot CSAT serializer. Focused CSAT handler/service tests, handler and automation package tests, full `go test ./...`, and `git diff --check` passed. Next B8 checkpoint is public CSAT submit/update and resolve-triggered send parity.