help

Overview ¶

Package help is the Hanzo Support product: the Frappe-Helpdesk model rebuilt as DocType fixtures on the native framework engine (clients/framework), plus a thin /v1/help subsystem (subsystem.go) for the one plane the generic, secure-by-default framework surface deliberately cannot serve — the PUBLIC help center.

Two planes, one engine ¶

A ticket IS a framework document in module "help"; its lifecycle IS a status field; an agent / team / SLA / canned response / KB article / conversation message are framework documents. So the AGENT plane — triage a ticket, author an article, read or post a conversation thread — is the framework's generic, already-live, role-gated surface (/v1/framework/hd-*) and the SAME generic @hanzo/ui DocType renderer that draws CMS and ERP. That plane needs ZERO code here beyond the fixtures.

What the generic surface CANNOT do is serve help.hanzo.ai's PUBLIC face: framework is secure-by-default (every read/write needs a validated principal AND a role), so there is no anonymous "read the public knowledge base" or "a customer files a ticket" path. subsystem.go adds exactly that — the public plane — the same way the knowledge lane adds /v1/kb for retrieval the generic surface lacks. It owns NO store: every read/write delegates to the framework in-process API (Ingest/Get/ Search), so there is ONE storage engine and no duplicated CRUD.

Migration ¶

This is the native-Go endgame for the Frappe Helpdesk (Vue frontend + Python Frappe backend on a Werkzeug dev server): the model moves onto the native DocType engine (no Frappe, no Python, no Werkzeug), the product surface is native Go, and the whole desk ships in the ONE cloud binary on Base.

Names are slug-style with an "hd-" prefix, so they never collide with the CMS (Author/Media/Page/…), ERP (erp-*), or KB (kb-*) lanes and never carry a space the console's `/cloud` path filter would reject. Tickets use a monotonic series name ("hd-tkt-.#####"); the masters use a field autoname the console slugifies on write.

subsystem.go mounts the Hanzo Support PUBLIC plane at /v1/help/*. It is the thin surface on top of the framework DocType store (agent CRUD lives at the generic, role-gated /v1/framework/hd-*) for the one thing the secure-by-default engine deliberately cannot do: serve help.hanzo.ai's anonymous face.

• GET /v1/help/articles the public knowledge base (Published + public only)
• GET /v1/help/articles/:slug one public article (re-checked, fail-closed)
• GET /v1/help/categories KB sections that front a public article
• POST /v1/help/tickets a customer files a ticket (bounded intake)

SECURITY — the anonymous org is NEVER client-chosen. Every public endpoint serves exactly ONE org, resolved SERVER-SIDE at mount (publicOrg): an explicit operator override, else the deployment brand (white-label: hanzo/zoo/lux), matching the crm Startup-intake convention. A request's X-Org-Id is IGNORED here, so a caller can never read or write another tenant's help center, and the reads are gated to status=Published AND is_public=1 (re-checked on a direct fetch) so a Draft or an internal article never leaks. Unset (no brand, no override) leaves the plane fail-closed: every endpoint 404s until the operator names the org.

Per-client edge RATE LIMITING is the ingress's job (see routes): behind hanzoai/ ingress the app sees only the ingress as the socket peer, so an app-level per-IP limiter would throttle every customer against ONE shared bucket. This plane bounds each request instead and leaves the edge limit to the layer that knows the client.