──────

### Summary of Changes 1. Documentation Consolidation: • Relocated the docs/ folder and all repository .md files (README.md, DEPLOYMENT.md, DOCKER_README.md, DOMAINS_README.md, GETTING_STARTED.md, CI_CD_PORTAINER_GUIDE.md, ADMIN_DEPLOYMENT_SUMMARY.md, SECURITY_PRIVATE_FILES.md, handoff.md, azure-project-plan.md, plus service-specific READMEs) into . • Updated document links in README.md. 2. AI Agent Project Map: • Created PROJECT_MAP.md in the project root containing complete architecture diagrams, service specs, ports, DB schemas, environment variables, and developer workflows. • Added PROJECT_MAP.md to .gitignore. 3. Monitoring UI & Infrastructure Integration: • Added monitoring_ui service to docker-compose.yml (port 5175). • Configured Gitea workflow docker-build.yml for monitoring_ui builds. • Added CORS middleware headers in index.js. • Added nginx.conf copy step in Dockerfile. ────── ### Recommended Commit Message docs: consolidate project documentation into monitoring_ui and add agent project map - Move all markdown documentation files and docs/ folder into monitoring_ui/docs/ - Update documentation hub index (monitoring_ui/docs/README.md) with relative paths - Generate comprehensive AI agent reference map (PROJECT_MAP.md) in repository root - Add PROJECT_MAP.md and monitoring_ui build output/env overrides to .gitignore - Integrate monitoring_ui service into docker-compose.yml and Gitea CI workflow - Configure CORS handling in employee_api for monitoring dashboard access ────── ### Alternative Short Commit Message refactor(docs): move docs to monitoring_ui and create AI agent PROJECT_MAP.md
2026-09-20 23:33:55 +02:00
parent f935bbeb8c
commit 635a130f0b
195 changed files with 28309 additions and 957 deletions
@@ -0,0 +1,201 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See LICENSE.md in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/**
+ * Prepare artifact schema — prepare-plan.json.
+ * Read by prepare instructions.md Step 9 (write prepare-plan.json).
+ */
+
+// ─── Shared type (inlined from session-schemas.ts to avoid cross-ref) ────────
+
+export interface PostDeployRecommendation {
+  title: string;
+  reason: string;
+  effort: "low" | "medium" | "high";
+  services?: string[];
+}
+
+// ─── Healing types (prepare phase) ───────────────────────────────────────────
+
+export type PrepareHealingTrigger = "quota" | "policy" | "rubric" | "region";
+export type PrepareIssueClassification = "AUTO_FIXABLE" | "NEEDS_USER_INPUT";
+export type PrepareHealingResult = "fixed" | "needs-input" | "still-failing";
+
+export interface PrepareHealingIssue {
+  dimension: string;
+  detail: string;
+  classification: PrepareIssueClassification;
+}
+
+export interface PrepareHealingFix {
+  service: string;
+  change: string;
+  reason: string;
+}
+
+export interface PrepareHealingAttempt {
+  attempt: number;
+  trigger: PrepareHealingTrigger;
+  issues: PrepareHealingIssue[];
+  fixes: PrepareHealingFix[];
+  result: PrepareHealingResult;
+}
+
+// ─── prepare-plan.json ───────────────────────────────────────────────────────
+
+export interface PlannedService {
+  name: string;
+  sku: string;
+  purpose: string;
+  component: string;
+  region: string;
+  resourceName: string;
+  /** Exact engine version for managed database services (MySQL/PostgreSQL Flexible Server),
+   *  sourced from the provider capabilities API during quota validation — NOT guessed.
+   *  ARM rejects major-only strings (e.g. MySQL '8.0'); use the exact supported patch
+   *  (e.g. '8.0.21'). Omit for non-DB services. */
+  version?: string;
+}
+
+export interface CostBreakdownItem {
+  service: string;
+  sku: string;
+  monthlyUsd: number;
+  note?: string;
+}
+
+export interface CostEstimate {
+  monthlyUsd: number;
+  currency: "USD";
+  breakdown: CostBreakdownItem[];
+  disclaimer: string;
+}
+
+export interface RejectedAlternative {
+  service: string;
+  reason: string;
+}
+
+export interface NamingResource {
+  type: string;
+  name: string;
+}
+
+export interface NamingConfig {
+  pattern: string;
+  /** The computed prefix used for all resource names: {project}-{env}-{suffix}.
+   *  deploymentVariables.environmentName MUST equal this value. */
+  resourcePrefix: string;
+  resources: NamingResource[];
+}
+
+export type QuotaSource = "cli" | "fallback";
+
+export interface QuotaCheck {
+  resource: string;
+  region: string;
+  required: number;
+  available: number;
+  sufficient: boolean;
+  provider: string;
+  currentUsage: number;
+  currentLimit: number;
+  adjustable: boolean;
+  source: QuotaSource;
+}
+
+export interface DeployStrategy {
+  /** Deploy pattern — see deploy-strategy.md for the three patterns.
+   *  "oryx-auto": Oryx handles build + run (Pattern A — default for most apps).
+   *  "startup-install": native module compilation at startup (Pattern B).
+   *  "container-only": Dockerfile-based deploy via ACR (Pattern C).
+   *  Omit when Oryx auto-build is sufficient and no special startup is needed. */
+  codeDeployPattern?: "oryx-auto" | "startup-install" | "container-only";
+  /** Startup command for native module compilation (goes into appCommandLine) */
+  startupCommand?: string;
+  /** Required app settings for the deploy strategy (e.g., SCM_DO_BUILD_DURING_DEPLOYMENT) */
+  requiredAppSettings?: Record<string, string>;
+  /** Human-readable reason for choosing this strategy */
+  reason: string;
+}
+
+export interface InstrumentationConfig {
+  appInsightsEnabled: boolean;
+  reason: string;
+}
+
+export interface DeploymentVariables {
+  /** MUST equal naming.resourcePrefix (e.g., "myapp-dev-a1d5"), NOT the env label ("dev") */
+  environmentName: string;
+  location: string;
+  sessionId: string;
+  deployedBy: string;
+  /** Variable names that could not be resolved at prepare time — deploy reads, not asks */
+  deferred?: string[];
+}
+
+export interface OfferRestriction {
+  /** Azure provider namespace (e.g., "Microsoft.DBforPostgreSQL") */
+  provider: string;
+  /** Region checked */
+  region: string;
+  /** Whether the offer is restricted in this region */
+  restricted: boolean;
+  /** Reason string from capabilities API, if any */
+  reason?: string;
+}
+
+export interface QuotaValidation {
+  /** True when all planned services had quota confirmed */
+  verified: boolean;
+  /** How quota was verified — persists in session artifact, survives context compaction */
+  method?: "cli" | "what-if" | "unverifiable";
+  /** The specific region that passed validation */
+  verifiedRegion?: string;
+  /** The specific SKU that was validated (e.g., "B1", "S1") */
+  verifiedSku?: string;
+  /** Regions checked during validation */
+  checkedRegions?: string[];
+  /** Resources that failed quota checks */
+  failedResources?: string[];
+  /** Reason when verified is false (e.g., "quota CLI unavailable", "all regions zero") */
+  reason?: string;
+  /** Offer restriction results for database services (PostgreSQL, MySQL).
+   *  Populated by prepare Step 5 when database services are in the plan.
+   *  `LocationIsOfferRestricted` is NOT caught by what-if — this is the only pre-deploy check. */
+  offerRestrictions?: readonly OfferRestriction[];
+  /** Derived from offerRestrictions[]: true when every database service in services[]
+   *  has at least one entry in offerRestrictions[]. Set this based on the array contents,
+   *  not independently. Deploy gate halts if false/missing when services include PostgreSQL/MySQL. */
+  offerRestrictionsVerified?: boolean;
+}
+
+export interface PreparePlan {
+  services: PlannedService[];
+  costEstimate: CostEstimate;
+  rejectedAlternatives: RejectedAlternative[];
+  naming: NamingConfig;
+  quotas: readonly QuotaCheck[];
+  assumptions: string[];
+  /** IaC format for scaffold — "bicep" (default) or "terraform" */
+  iacFormat: "bicep" | "terraform";
+  /** Application database name the app expects to exist (from compose env such as
+   *  MYSQL_DATABASE / MYSQLDB_DATABASE / POSTGRES_DB, a connection string, or ORM config).
+   *  Scaffold emits a `flexibleServers/databases` child resource for this so the schema DB
+   *  exists in IaC before the container starts; the conformance gate's DB-NAME-PRESENT check
+   *  asserts it. Omit only when no managed database is in the plan. */
+  appDbName?: string;
+  postDeployRecommendations?: PostDeployRecommendation[];
+  /** Instrumentation decision — object with boolean + reason, NOT a bare boolean */
+  instrumentation?: InstrumentationConfig;
+  /** Deployment variables resolved at prepare time — scaffold/deploy read, not re-ask */
+  deploymentVariables?: DeploymentVariables;
+  /** Quota validation result from proactive capacity check */
+  quotaValidation?: QuotaValidation;
+  /** Code deploy strategy for native module apps — see deploy-strategy.md.
+   *  Only populated when Pattern B (startup-install) is needed. */
+  deployStrategy?: DeployStrategy;
+  healingAttempts?: readonly PrepareHealingAttempt[];
+}