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

docs: record profile serializer parity checkpoint

Browse Source
This commit is contained in:
rogee
2026-06-05 01:09:53 +08:00
parent 56a8c5b806
commit c1fd56eb40
1 changed files with 17 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md
+17 -21
View File
@@ -16,7 +16,7 @@ Build GoChat as a Go backend that can directly reuse the frontend from `referenc
## Current Baseline
- Latest implementation checkpoint: `ebd8f08 feat(webhook): finalize provider ingress parity`.
- Latest implementation checkpoint: `56a8c5b feat(profile): align chatwoot user serializer`.
- Worktree status at this planning checkpoint: clean.
- `go test ./...` passes.
- Route dump succeeds with `TOTAL: 801` after Chatwoot webhook ingress routes were added.
@@ -68,33 +68,29 @@ This ledger records the committed parity checkpoints that future slices should b
| `0439f3b feat(webhook): require line ingress signatures` | Tightened LINE webhook signature parity so configured `channel_secret` requires a present and valid `X-Line-Signature`, with missing-signature rejection coverage. | Focused webhook tests passed; full `go test ./...` passed. | Continue P6.7 review with WhatsApp missing-signature edge fixtures and Shopify/Twitter final classification. |
| `1c30933 test(webhook): cover whatsapp ingress verification` | Added WhatsApp route-level verification coverage for verify-token challenge echo, signed Cloud API POST persistence, and missing Meta signature rejection without persistence. | Focused webhook tests passed; full `go test ./...` passed. | Continue P6.7 review with Shopify/Twitter final classification. |
| `ebd8f08 feat(webhook): finalize provider ingress parity` | Finalized P6.7 provider classification with Twitter CRC prefix parity, Twitter route-level webhook tests, Instagram missing-signature rejection coverage, and Shopify real-handler classification. | Focused webhook/API tests passed; full `go test ./...` passed. | Move next to serializer/API parity queue. |
| `56a8c5b feat(profile): align chatwoot user serializer` | Aligned `/api/v1/profile`, profile update, avatar delete/update, availability, auto-offline, and reset-access-token responses to Chatwoot's raw `api/v1/models/_user.json.jbuilder` shape. Added user/account/account_user fields and personal access-token persistence needed by the serializer. | Focused profile/API tests passed; sandboxed `go test ./...` hit socket restrictions; escalated full `go test ./...` passed; `git diff --check` passed. | Continue B2 with `/auth/sign_in`, `/auth/validate_token`, auth headers/cookie contract, and current-user payload fixtures. |
## Next Slice Contract
Completed implementation slice: B1/P6.7 webhook ingress replaced provider parse/log boundaries with verified, persistent, idempotent dispatch paths.
Completed implementation slice: B2 profile-side serializer parity now returns the Chatwoot raw user payload for profile reads and mutations.
Next implementation slice: continue Q4/B2 serializer parity fixtures for auth/profile and other frontend-critical API families.
Next implementation slice: continue Q4/B2 serializer parity fixtures for auth/session and current-user validation, then move to conversations/messages.
| Step | Required result | Reference source | Verification |
| --- | --- | --- | --- |
| N1 | Establish one persistence boundary for provider `IncomingMessage` objects. It must find or create contact, contact inbox, open conversation, and incoming message records. | Chatwoot channel webhook controllers and conversation/message builders. | Unit tests covering create, reuse, and duplicate source ID behavior. |
| N2 | Wire Telegram, LINE, SMS/Twilio, WhatsApp, Instagram, TikTok, and supported Meta/Shopify message-producing paths through the boundary where the provider yields customer messages. | `reference/chatwoot/app/controllers/webhooks/*` and channel provider services. | Focused provider webhook tests assert persisted message/conversation records, not only `200 OK`. |
| N3 | Keep provider verification rules intact while making invalid external payloads provider-safe where Chatwoot acknowledges to avoid retries. | Provider-specific Chatwoot controllers. | Tests cover valid signature/token, invalid signature/token, and safe ack cases. |
| N4 | Regenerate route artifacts only if routes change; otherwise preserve `TOTAL: 801` and `251 exact, 0 missing`. | `cmd/dump_routes`, `cmd/route_parity`. | Route commands run when applicable. |
| N5 | Update this tracker in the same commit with P6.7 provider statuses and a progress-log entry. | This document. | `git diff --check`; `go test ./...` for Go changes. |
| N1 | Add Chatwoot auth route aliases and response fixtures for `/auth/sign_in`, `/auth/sign_out`, `/auth/validate_token`, and password routes used by the reused frontend. | `reference/chatwoot/app/controllers/devise_overrides/*`, `reference/chatwoot/app/views/devise/_auth.json.jbuilder`, frontend `api/auth.js`. | Handler tests assert token headers, body shape, and current-user validation payloads. |
| N2 | Preserve profile raw user serializer behavior for `/api/v1/profile`, update, availability, auto-offline, avatar, and reset access token. | `reference/chatwoot/app/controllers/api/v1/profiles_controller.rb`, `reference/chatwoot/app/views/api/v1/models/_user.json.jbuilder`. | Existing profile fixtures remain green. |
| N3 | Move next serializer fixtures to conversations/messages once auth/session is compatible with the frontend cookie/header contract. | Chatwoot conversation/message Jbuilder views and frontend stores. | Fixture tests for list/show/create/status/assignment payloads. |
| N4 | Regenerate route artifacts only if routes change; otherwise preserve `TOTAL: 801` and tracked route zero-missing status. | `cmd/dump_routes`, `cmd/route_parity`. | Route commands run when applicable. |
| N5 | Update this tracker after every implementation checkpoint. | This document. | `git diff --check`; `go test ./...` for Go changes. |
Current N1/N2 implementation checkpoint:
Current B2 profile checkpoint:
- Added `IncomingPersister` as the shared durable webhook boundary. It dedupes messages by `inbox_id + source_id`, resolves or creates `ContactInbox` by `inbox_id + sender source_id`, reuses the latest open conversation for the contact/inbox, and creates incoming `Message` records with content attributes and provider metadata.
- Wired parsed incoming messages from Telegram, LINE, Twilio SMS, WhatsApp, Facebook/Instagram, and TikTok into the persister. Provider verification and provider-safe acknowledgement behavior remain in their existing handlers.
- Added regression coverage for direct persistence, duplicate suppression, and Telegram webhook-to-message persistence. Broader provider-specific persistence assertions remain required before P6.7 is `Done`.
- Added receipt persistence for status-only webhook events. Twilio delivery callbacks, WhatsApp statuses, Facebook/Instagram delivery/read receipts, and TikTok read receipts now update existing message statuses through the same boundary. Async event fan-out remains the next dispatch gap.
- Wired the same boundary into `channel.Dispatcher` so incoming webhooks emit `contact.created`, `conversation.created/opened/updated`, `message.created/incoming`, and `message.status_updated` events for automation, CSAT, bot rules, notifications, and future async workers.
- Added provider-specific persistence fixtures for Telegram, LINE, Twilio SMS, WhatsApp, Instagram, and TikTok. These tests assert durable `messages` rows by provider source ID instead of only checking webhook `200 OK` acknowledgements.
- Added TikTok webhook signature verification to match `reference/chatwoot/app/controllers/webhooks/tiktok_controller.rb`: `Tiktok-Signature` must include `t=<unix>,s=<hmac>`, the HMAC is `sha256(TIKTOK_APP_SECRET, "<timestamp>.<raw_body>")`, and stale signatures older than five seconds are rejected.
- Tightened LINE webhook signature verification to match `reference/chatwoot/app/jobs/webhooks/line_events_job.rb`: when `channel_secret` is configured, `X-Line-Signature` must be present and equal `base64(hmac_sha256(channel_secret, raw_body))` before parsing or persistence.
- Added WhatsApp route-level fixtures matching `reference/chatwoot/app/controllers/webhooks/whatsapp_controller.rb` and `MetaTokenVerifyConcern`: verify-token requests echo `hub.challenge`, Cloud API posts require `X-Hub-Signature-256` when an app secret is configured, and signed payloads persist incoming messages by provider source ID.
- Added Twitter CRC route tests and fixed CRC responses to include the Chatwoot/Twitter `sha256=` prefix. Added Instagram missing-signature rejection coverage. Shopify remains a real verified handler with HMAC rejection and `shop/redact` cleanup coverage.
- Added a `ProfileUserResponse` matching Chatwoot's `api/v1/models/_user.json.jbuilder`, including `access_token`, `available_name`, `message_signature`, `pubsub_token`, `ui_settings`, and nested account membership fields.
- Profile handlers now return raw Chatwoot user JSON instead of the Go API `{success,data}` envelope for frontend-consumed profile endpoints.
- Availability and auto-offline endpoints now return the full current-user serializer, matching frontend store expectations.
- User creation now assigns a `pubsub_token` like Chatwoot's `Pubsubable` concern, avoiding duplicate empty token rows and enabling ActionCable-compatible profile payloads.
- Added migration `000017_add_profile_serializer_fields` for profile serializer fields on users, accounts, and account_users.
## Immediate Execution Queue
@@ -132,7 +128,7 @@ These milestones are the tracking spine for the remaining Chatwoot frontend reus
| M0 | Test, route, and documentation baseline. | Clean worktree, `go test ./...`, route dump/parity artifacts current. | Done |
| M1 | Meilisearch-first search foundation. | Config, engine, indexing hooks, reindex command, mocked tests, and live-shape review tracked. | Review |
| M2 | Route parity expansion for frontend-critical routes. | Tracked route set has zero missing routes and every new route group has router boot coverage. | Doing |
| M3 | Serializer parity for frontend API families. | Fixture tests cover auth/profile, accounts/users, inboxes, conversations/messages, contacts/companies, notifications, reports, widget/public, and search. | Todo |
| M3 | Serializer parity for frontend API families. | Fixture tests cover auth/profile, accounts/users, inboxes, conversations/messages, contacts/companies, notifications, reports, widget/public, and search. | Doing |
| M4 | Core handler placeholder burn-down. | Account/contact/conversation/message/inbox/webhook handlers are repository-backed and no frontend-critical route returns placeholder JSON. | Doing |
| M5 | Paid feature parity excluding SSO family. | SLA, Audit, CustomRole, AgentCapacity, Captain/Copilot, CSAT, InboxLimit, automation/macros, and assignment policies pass route, persistence, auth, side-effect, serializer, and tests. | Todo |
| M6 | Durable jobs and external integrations. | Search indexing, CSAT send, automation actions, notifications, webhooks, and external deliveries are queued, retryable, logged, and idempotent. | Todo |
@@ -145,7 +141,7 @@ Work proceeds top-down unless a failing test or frontend blocker forces a narrow
| Slice | Work | Reference source | Verification | Status |
| --- | --- | --- | --- | --- |
| B1 | Webhook ingress route and handler parity. | `reference/chatwoot/config/routes.rb:614-624`, `reference/chatwoot/app/controllers/webhooks/*`, `reference/chatwoot/app/controllers/api/v1/webhooks_controller.rb` | Provider lookup tests, router route dump, `go test ./...`. | Done |
| B2 | Auth/profile serializer fixtures. | `reference/chatwoot/app/controllers/api/v1/profile*`, frontend auth client. | Fixture tests for login/current user/profile/availability/settings. | Todo |
| B2 | Auth/profile serializer fixtures. | `reference/chatwoot/app/controllers/api/v1/profile*`, frontend auth client. | Fixture tests for login/current user/profile/availability/settings. | Doing: profile serializer fixtures done; auth/session aliases and validate-token remain. |
| B3 | Conversation/message serializer and behavior fixtures. | Chatwoot conversation/message controllers, entities, jobs. | Fixture tests for list/show/create/update/private notes/attachments/status/assignment. | Todo |
| B4 | Contact/company behavior fixtures. | Chatwoot contact/company controllers, merge/import/export/notes/labels. | Fixture tests for CRUD/search/merge/relation/import-export shells. | Todo |
| B5 | Inbox/channel behavior fixtures. | Chatwoot inbox/channel controllers and channel models. | Fixture tests for inbox CRUD, settings, business hours, members, avatar, channel config. | Todo |