docs: chart SaaS production readiness

2026-07-10 02:34:30 +08:00
parent b0eedfab05
commit 2dc125aec1
9 changed files with 134 additions and 0 deletions
@@ -0,0 +1,11 @@
+# Audit the clean-host deployment and rollback contract
+
+Type: research
+Status: open
+
+## Question
+
+What concrete defects prevent a clean, supported Linux host from installing,
+starting, health-checking, upgrading, and rolling back the current Hub without
+manual repository knowledge or unsafe partial deployment?
+
@@ -0,0 +1,12 @@
+# Audit tenant, authentication, and request security boundaries
+
+Type: research
+Status: open
+
+## Question
+
+Can any current HTTP, Feishu, filesystem, agent, or database path cross an
+Organization boundary, bypass the intended platform/org/project authorization
+seams, expose secrets, or accept unbounded hostile input in the initial
+production topology?
+
@@ -0,0 +1,12 @@
+# Audit run lifecycle and data integrity under failure
+
+Type: research
+Status: open
+
+## Question
+
+Under process termination, restart, timeout, duplicate Feishu delivery,
+database failure, or concurrent requests, which AgentRun, lock, session,
+workspace, audit, and outbound-message invariants can be violated or leave work
+lost, duplicated, or permanently stuck?
+
@@ -0,0 +1,12 @@
+# Define production observability and incident recovery
+
+Type: research
+Status: open
+Blocked by: 01, 02, 03
+
+## Question
+
+Which logs, metrics, readiness signals, audit correlations, alerts, and operator
+recovery actions are missing for a production operator to detect and diagnose
+failures across HTTP, Feishu, PostgreSQL, agent execution, cph builds, and
+workspace storage?
@@ -0,0 +1,11 @@
+# Define initial abuse and capacity controls
+
+Type: grilling
+Status: open
+Blocked by: 02, 03
+
+## Question
+
+Which request limits, file limits, concurrency limits, agent budgets, tenant
+quotas, and backpressure policies are mandatory for the accepted initial
+production boundary, and which values or behaviors remain product decisions?
@@ -0,0 +1,11 @@
+# Audit backup, migration, and disaster recovery safety
+
+Type: research
+Status: open
+
+## Question
+
+What backup, restore, workspace/database consistency, migration compatibility,
+and disaster-recovery guarantees are needed to deploy current persistent data
+safely, and what evidence or tooling is missing to prove them?
+
@@ -0,0 +1,12 @@
+# Audit the accepted product surface for production completeness
+
+Type: research
+Status: open
+
+## Question
+
+Against ADR-0020 and ADR-0021, which required platform-admin, org-admin,
+project-onboarding, team/access, session, usage, and Feishu flows are absent,
+unreachable, or only test-facing rather than usable in the initial production
+service?
+
@@ -0,0 +1,12 @@
+# Prove the production release gate
+
+Type: task
+Status: open
+Blocked by: 01, 02, 03, 04, 05, 06, 07
+
+## Question
+
+After the readiness investigations and resulting fixes are resolved, can one
+repeatable release procedure prove build/test/spec health, deploy a clean
+production-like environment, exercise critical tenant and agent journeys,
+verify observability and recovery, and either roll forward or roll back safely?
@@ -0,0 +1,41 @@
+# Initial Production SaaS Readiness
+
+Label: wayfinder:map
+
+## Destination
+
+The repository can be deployed from a clean checkout as the initial production
+multi-tenant Curriculum Project Hub, operated safely on the ADR-0018/0020/0021
+single-host Linux topology, with repeatable release evidence, rollback and
+recovery procedures, and no known critical security or data-integrity gaps.
+
+## Notes
+
+- `spec/` remains the semantic source of truth; implementation drift must be
+  surfaced rather than silently resolved.
+- The initial product boundary follows the accepted ADRs: Organization is the
+  tenant root, customer onboarding may be manual, and full billing, limits,
+  tenant suspension, and self-service platform administration remain deferred
+  unless a readiness investigation proves they are required for safe operation.
+- Use the `diagnosing-bugs` loop for every reproduced defect. Prefer explicit
+  failures and observable critical paths over fallback behavior.
+- Work on `saas-production-readiness`; make small conventional commits after
+  verified, independently reversible milestones. Do not push without explicit
+  authorization.
+- Local `lake build` currently requires a configured elan toolchain; CI remains
+  the authoritative configured Lean build environment until that local toolchain
+  is available.
+
+## Decisions so far
+
+## Fog
+
+- The production topology after the initial single-host pilot (HA, horizontal
+  workers, multi-region, or managed container orchestration) depends on measured
+  demand and failure experience.
+- Commercial self-service concerns such as billing plans and automated tenant
+  provisioning remain beyond the accepted ADR boundary; revisit after the
+  initial safety and operability route is clear.
+- Regulatory retention, residency, and customer-specific compliance controls
+  require product/legal inputs that the repository does not currently contain.
+