# Enterprise Monorepo / Multi-Repo Reference Architecture Template 版本：v1.3 定位：国际通用企业级参考模型 适用：中大型工程组织、Platform Engineering、Internal Developer Platform (IDP)、Platform Services、 多产品线、AI / Data / Cloud Native systems --- ##### 1. 总体原则 企业级项目架构不应只按“frontend / backend / infrastructure / docs”粗分，而应按长期稳定的 enterprise truth sources 与 operating surfaces 划分： | 顶层目录 | International description | Truth / boundary type | | -------------------- | ------------------------------------------------- | --------------------------------- | | `governance/` | Engineering Governance: standards, owners, ADRs, SLOs, risks, reviews, gates | Engineering governance truth | | `contracts/` | Interface Contract Registry: APIs, events, schemas, datasets, resources, policies | Machine-readable contract truth | | `catalog/` | Software Catalog / Asset Inventory: systems, components, resources, owners, lifecycle | Software asset ownership truth | | `infra/` | Infrastructure and Operations: infrastructure, runtime, delivery, observability, security, cost | Operational foundation truth | | `internal-platform/` | Internal Developer Platform (IDP): paved roads, templates, self-service, portal | Developer experience truth | | `middle-platform/` | Platform Services / Shared Capabilities: data, API, compute, AI, messaging, identity | Reusable platform capability truth | | `services/` | Deployable Service Runtime: APIs, workers, jobs, bots, publishers, service-owned adapters | Runtime service boundary truth | | `products/` | Product Surfaces: web, mobile, bot, admin, reporting, user/operator workflows | Product delivery truth | | `shared/` | Thin Shared Libraries / SDKs: low-level libraries, SDKs, fixtures | Thin reuse boundary | > 最终模型： > **governance + contracts + catalog + infra + internal-platform + middle-platform + services + products** > `shared/` 是辅助层，不应膨胀成新的 platform service 或 product backend。 --- ##### 2. 推荐目录结构 ```text repo/ ├── governance/ # Engineering Governance: standards, owners, ADRs, SLOs, risks, reviews, gates │ ├── standards/ # Engineering, security, coding, architecture standards │ ├── decisions/ # ADR: Architecture Decision Records │ ├── ownership/ # Owners, RACI, on-call, escalation paths │ ├── slo/ # SLI, SLO, error budget, service level objectives │ ├── risks/ # Risk register, threat model, compliance risks │ ├── gates/ # Release, security, quality, architecture gates │ ├── change-records/ # Task trees, migration evidence, rollback runbooks │ └── postmortems/ # Incident reviews, action items, long-term fixes │ ├── contracts/ # Interface Contract Registry: the machine-readable truth across boundaries │ ├── apis/ # OpenAPI, GraphQL schema, RPC IDL │ ├── events/ # AsyncAPI, event definitions, topics, subscription contracts │ ├── schemas/ # JSON Schema, Proto, Avro, Parquet schema │ ├── datasets/ # Dataset contracts, data products, quality rules, lineage │ ├── resources/ # Cloud resources, K8s CRDs, Terraform module interfaces │ └── policies/ # OPA, Rego, IAM policies, data access policies │ ├── catalog/ # Software Catalog / Asset Inventory: systems, components, resources, APIs, owners, lifecycle │ ├── systems/ # System definitions: product domains, platform domains, business systems │ ├── components/ # Component definitions: services, libraries, jobs, frontend apps │ ├── resources/ # Resource definitions: DB, queue, bucket, cache, cluster │ ├── domains/ # Domain definitions: business, technology, platform domains │ └── scorecards/ # Health, maturity, security, reliability scorecards │ ├── infra/ # Infrastructure and Operations │ ├── control-plane/ # Topology, lifecycle, state control, cluster management │ ├── resource-plane/ # Compute, network, storage, database, queue │ ├── runtime-plane/ # Worker, daemon, job, scheduler, queue consumer │ ├── delivery-plane/ # CI/CD, artifacts, release, rollback, environment promotion │ ├── observability/ # Logs, metrics, traces, health, alerts, dashboards │ ├── security/ # Secrets, IAM, policy enforcement, audit │ ├── container/ # Docker image matrix, Compose entry points, registry policy │ ├── kubernetes/ # K8s base, workloads, policies, networking, operations │ ├── gitops/ # Argo CD / Flux desired state, promotion, rollback │ ├── environments/ # Local, dev, staging, production, DR │ ├── disaster-recovery/ # Backup, restore, runbook, game day │ └── cost/ # FinOps, budget, resource ownership, cost attribution │ ├── internal-platform/ # Internal Developer Platform (IDP), not a business capability platform │ ├── portal/ # Backstage-style developer portal │ ├── templates/ # Golden paths, scaffolding, service templates │ ├── orchestration/ # Provisioning, workflow, automation │ ├── developer-tools/ # CLI, SDK, diagnostics, local development tools │ ├── scorecards/ # Service health, quality, security, maturity scorecards │ └── docs/ # Platform user docs, onboarding guides, FAQ │ ├── middle-platform/ # Platform Services / Shared Capabilities for multiple product surfaces │ ├── data-platform/ # Ingestion, quality, lineage, catalog, serving │ ├── api-platform/ # Gateway, query, auth, rate limit, schema │ ├── compute-platform/ # Batch, stream, derived jobs, task execution │ ├── ai-platform/ # LLM, prompt, tool, context, eval, agent runtime │ ├── messaging-platform/ # Notification, event, subscription, push │ ├── integration-platform/ # External APIs, webhooks, provider adapters │ ├── identity-platform/ # Account, AuthN, AuthZ, tenant │ ├── search-platform/ # Indexing, retrieval, ranking │ └── experimentation-platform/ # A/B testing, feature flags, experiment metrics │ ├── services/ # Deployable Service Runtime, grouped by domain and deployable boundary │ ├── query/ # Query/API services and read facades │ │ └── query-api/ │ ├── data/ # Data ingestion workers, sync jobs, source adapters │ │ └── source-worker/ │ ├── compute/ # Derived compute, batch jobs, stream processors │ │ └── derived-worker/ │ ├── channels/ # Bot, chat, webhook or notification channel services │ │ └── chat-bot/ │ ├── publishing/ # External publishing and export services │ │ └── report-publisher/ │ └── domain-specific/ # Optional business or technical domain service group │ └── domain-service/ │ ├── products/ # Product Surfaces for users, operators, or business workflows │ ├── web/ # Web product surface │ ├── mobile/ # Mobile product surface │ ├── bot/ # Bot, agent, chat surface │ ├── admin/ # Admin and operations console │ └── reporting/ # Reporting, BI, business analytics surface │ ├── shared/ # Thin Shared Libraries / SDKs; only stable low-level reuse belongs here │ ├── libraries/ # General-purpose low-level libraries │ ├── sdks/ # External or internal SDKs │ └── test-fixtures/ # Cross-domain test fixtures │ ├── tools/ # Developer Tooling: codegen, lint, verify, migration helpers ├── scripts/ # Repo automation entry points │ └── gates/ # Executable repo gates for structure, contracts, runtime readiness ├── tests/ # Cross-cutting tests that do not belong to one service │ └── repo-gates/ # Repository structure and architecture guard tests ├── docs/ # Documentation Hub; does not replace governance/contracts/catalog └── ci/ or .github/ # CI workflow entry points ``` --- ##### 3. 顶层目录职责说明 ##### 3.1 `governance/`: Engineering Governance 用于承载组织级 Engineering Governance，不放业务代码。 应包含： ```text governance/ ├── standards/ │ ├── engineering-standard.md │ ├── security-standard.md │ ├── data-standard.md │ └── api-standard.md ├── decisions/ │ └── adr-0001-record-template.md ├── ownership/ │ ├── owners.yaml │ └── escalation-policy.md ├── slo/ │ ├── slo-template.yaml │ └── error-budget-policy.md ├── risks/ │ └── risk-register.yaml ├── gates/ │ ├── release-gate.yaml │ ├── security-gate.yaml │ └── architecture-gate.yaml ├── change-records/ │ └── migration-record-template.md └── postmortems/ └── postmortem-template.md ``` 核心规则： * 架构决策必须进入 `decisions/`，以 ADR 形式长期留痕 * Owner、RACI、on-call 与 escalation path 必须进入 `ownership/` * 生产系统必须定义 SLO * 架构迁移、服务化拆分、运行时接入必须留下 task tree、evidence report 和 rollback runbook * 事故必须有复盘和行动项 * 发布、安全、质量、架构门禁应尽量机器可执行 --- ##### 3.2 `contracts/`: Interface Contract Registry 用于放置 machine-readable interface contracts，避免 API、events、schemas、datasets、 resources、policies 散落在代码注释或普通文档里。 推荐结构： ```text contracts/ ├── apis/ │ ├── public/ │ ├── internal/ │ └── partner/ ├── events/ │ ├── topics/ │ └── schemas/ ├── schemas/ │ ├── json/ │ ├── proto/ │ └── avro/ ├── datasets/ │ ├── data-products/ │ ├── quality-rules/ │ └── lineage/ ├── resources/ │ ├── terraform-modules/ │ ├── kubernetes-crds/ │ └── cloud-resources/ └── policies/ ├── iam/ ├── opa/ └── data-access/ ``` 核心规则： * API 变更必须先更新契约 * 事件字段变更必须兼容旧消费者 * Dataset contract 必须声明 owner、schema、quality rules、lifecycle * Policy 应尽量以 policy-as-code 形式机器可执行 * Contract change 必须进入 CI 校验 --- ##### 3.3 `catalog/`: Software Catalog / Asset Inventory 用于记录 systems、components、resources、APIs、domains、owners、lifecycle。 推荐结构： ```text catalog/ ├── systems/ │ └── payment-system.yaml ├── components/ │ └── payment-api.yaml ├── resources/ │ └── payment-db.yaml ├── domains/ │ └── finance-domain.yaml └── scorecards/ ├── production-readiness.yaml ├── security-scorecard.yaml └── reliability-scorecard.yaml ``` 每个资产建议至少包含： ```yaml name: payment-api type: service system: payment-system domain: finance owner: team-payment lifecycle: production tier: tier-1 dependsOn: - resource:payment-db - api:identity-api providesApis: - payment-public-api consumesApis: - identity-internal-api slo: availability: 99.9 latency_p95_ms: 300 ``` 核心规则： * 没有 owner 的 system 不允许进入 production * 没有 catalog entry 的 service 不应接入 release pipeline * Resource 必须能追溯到 system、team、cost center * Lifecycle 必须明确：experimental、development、production、deprecated、retired --- ##### 3.4 `infra/`: Infrastructure and Operations `infra/` 负责 Infrastructure and Operations：运行、交付、安全、观测、灾备和成本， 不承载业务逻辑。 推荐结构： ```text infra/ ├── control-plane/ ├── resource-plane/ ├── runtime-plane/ ├── delivery-plane/ ├── observability/ ├── security/ ├── container/ │ ├── image-matrix.yaml # image name、build context、platform、owner、runtime │ ├── compose.yaml # local / integration orchestration entry point │ └── registries.yaml # registry、tag policy、retention、signing policy ├── kubernetes/ │ ├── base/ # namespace、RBAC、quota、limit range、storage class │ ├── workloads/ # shared workload conventions and reusable manifests │ ├── networking/ # ingress、gateway、service mesh、network policy │ ├── policies/ # admission, security, resource and deployment policies │ └── operations/ # cluster runbooks, upgrade, backup, recovery, diagnostics ├── gitops/ │ ├── apps/ # Argo CD / Flux application definitions │ ├── environments/ # env overlays and promotion targets │ └── sync-waves/ # dependency order and rollout sequencing ├── environments/ │ ├── local/ │ ├── dev/ │ ├── staging/ │ ├── production/ │ └── dr/ ├── disaster-recovery/ └── cost/ ``` 核心规则： * Environment configuration 必须显式分离 * Production change 必须可审计、可回滚 * Tier-1 resources 必须有 backup、restore plan、game day 记录 * Observability 应覆盖 logs、metrics、traces、alerts、dashboards * Cost 必须能归因到 owner、system、environment * `infra/container/` 管镜像矩阵、Compose 总入口和 registry policy；每个服务仍保留自己的 `Dockerfile` * `infra/kubernetes/` 管集群级 K8s 基线、策略、网络和运维；服务级 workload intent 留在各自 `services///deploy/` * `infra/gitops/` 管 desired state、environment promotion、sync order 和 rollback，不应放业务逻辑 * 生产环境检查必须区分 read-only inspection 与 deployment/change；没有明确授权时只允许只读取证，不做远端变更 --- ##### 3.5 `internal-platform/`: Internal Developer Platform (IDP) 这是 Internal Developer Platform (IDP)，不是 business domain platform，也不是某个 product backend。 它服务的是内部开发者，目标是用 paved roads、self-service 和 automation 降低交付复杂度。 推荐结构： ```text internal-platform/ ├── portal/ ├── templates/ ├── orchestration/ ├── developer-tools/ ├── scorecards/ └── docs/ ``` 典型能力： * Service scaffolding templates * Golden paths / paved roads * Self-service resource provisioning * Service registration * CI/CD onboarding * Release operation entry points * Service health scorecards * Diagnostics tooling * Developer documentation 核心规则： * 不能把业务能力塞进 `internal-platform/` * 模板应默认符合治理、安全、观测、发布标准 * 平台能力要以产品方式运营，有 adoption、usage、feedback、SLO --- ##### 3.6 `middle-platform/`: Platform Services / Shared Capabilities `middle-platform/` 对应国际语境中的 Platform Services / Shared Capabilities。 它提供多个 product surfaces 可复用的平台能力，不直接承载最终用户工作流，也不服务某一个单一产品。 推荐结构： ```text middle-platform/ ├── data-platform/ ├── api-platform/ ├── compute-platform/ ├── ai-platform/ ├── messaging-platform/ ├── integration-platform/ ├── identity-platform/ ├── search-platform/ └── experimentation-platform/ ``` 各平台职责： | 子平台 | 职责 | | --------------------------- | ------------------------------------------ | | `data-platform/` | Ingestion、quality、lineage、catalog、serving | | `api-platform/` | Gateway、auth、rate limit、schema、query layer | | `compute-platform/` | Batch、stream、job orchestration、derived compute | | `ai-platform/` | LLM、prompt、tool、context、eval、agent runtime | | `messaging-platform/` | Notification、events、subscriptions、push | | `integration-platform/` | External APIs、webhooks、provider adapters | | `identity-platform/` | Account、AuthN、AuthZ、tenant | | `search-platform/` | Indexing、retrieval、ranking、search | | `experimentation-platform/` | A/B testing、feature flags、experiment metrics | 核心规则： * 可以依赖 `infra/` * 可以通过 contracts 暴露能力给 `products/` * 不应依赖 `products/` * 不应承载某个单一 product surface 的专属业务逻辑 * Platform capability 必须产品化：contract、docs、SLO、owner、onboarding path 都要明确 --- ##### 3.7 `services/`: Deployable Service Runtime `services/` 承载可以独立运行、测试、部署、扩缩容和回滚的 runtime units。 它回答“系统里到底有哪些服务，以及每个服务的责任、入口、数据边界、依赖和部署形态是什么”。 推荐结构： ```text services/ ├── query/ │ └── query-api/ ├── data/ │ └── source-worker/ ├── compute/ │ └── derived-worker/ ├── channels/ │ └── chat-bot/ ├── publishing/ │ └── report-publisher/ └── domain-specific/ └── domain-service/ ``` 每个 service root 建议至少包含： ```text service-name/ ├── src/ ├── tests/ ├── deploy/ │ ├── compose.yaml # service-level local/integration runtime intent │ └── k8s.yaml # service-level simple workload intent; larger setups may use helm/kustomize ├── docs/ ├── service.yaml # owner、lifecycle、entrypoints、data access、dependencies、runtime ├── Dockerfile ├── entrypoint.sh ├── README.md └── AGENTS.md ``` 核心规则： * 一个 service root 必须对应一个清晰的 runtime boundary * API、worker、cronjob、daemon、bot、publisher 都可以是 service，但 library / SDK / template 不应伪装成 service * `services///service.yaml` 应声明 owner、lifecycle、entrypoints、ports、data access、dependencies、SLO、deploy、rollback * `services///deploy/compose.yaml` 和 `services///deploy/k8s.yaml` 用于声明服务级 runtime intent * 每个 service root 应至少能提供 start、stop、health、test、verify、build image 和 deploy dry-run 的标准入口 * `services/` 可以实现 `middle-platform/` 暴露的能力，也可以支撑 `products/` 的交付面，但不能绕过 `contracts/` 和 `catalog/` * 容器化、Compose、Kubernetes 或 systemd 只应作用在边界清楚的 service root 上 --- ##### 3.8 `products/`: Product Surfaces Product Surfaces 直接面向 end users、operators 或具体 business workflows。 推荐结构： ```text products/ ├── web/ ├── mobile/ ├── bot/ ├── admin/ └── reporting/ ``` 核心规则： * Product surface 可以消费 `services/` 或 `middle-platform/` 暴露的 capabilities * Product team 可以使用 `internal-platform/` 提供的开发、发布、自助能力 * Product surface 不应直接绕过 contracts 访问底层 resources * Product-specific logic 留在产品内，不要污染 Platform Services * 多产品复用前，先证明确实跨 product surfaces 稳定复用 --- ##### 3.9 `shared/`: Thin Shared Libraries / SDKs `shared/` 是最容易变成 `common` 垃圾桶的目录，必须严格限制。 允许放： ```text shared/ ├── libraries/ ├── sdks/ └── test-fixtures/ ``` 适合放： * 无业务语义的 low-level libraries * SDK * 类型工具 * 通用测试夹具 * Codegen runtime * 跨域稳定 protocol adapters 不适合放： * 业务规则 * 产品流程 * 领域模型 * 随手抽出来的 common helper * 只有两个调用方的临时共享逻辑 核心规则： > `shared/` 必须是 thin shared layer。 > 一旦它开始承载业务语义，就说明边界设计已经失控。 --- ##### 4. 跨层依赖规则 推荐依赖方向： ```text products / product surfaces ↓ services / deployable runtime services ↓ middle-platform / platform services ↓ infra internal-platform / IDP ↓ infra contracts ← referenced by all layers catalog ← registered by all layers governance ← constrains all layers shared ← provides only thin low-level reuse ``` ##### 强制边界规则 | 规则 | 说明 | | --- | --- | | `products` 只能消费 `services` / `middle-platform` / `internal-platform` 暴露的接口 | 不直接绕过 contracts 访问底层 resources | | `services` 是 deployable runtime boundary | 每个服务必须声明 owner、entrypoints、dependencies、data access、deploy、rollback | | `middle-platform` 可以依赖 `infra` | 但不能依赖 `products` | | `internal-platform` 服务内部开发者 | 不承载 business domain capabilities | | `infra` 不写业务逻辑 | 只负责 runtime、delivery、security、observability、cost | | `contracts` 是 Interface Contract Registry | API、event、schema、dataset、resource、policy 都应机器可读 | | `catalog` 是 Software Catalog / Asset Inventory | System、component、resource、owner、lifecycle 必须可查 | | `governance` 是 Engineering Governance truth | Standard、ADR、SLO、postmortem、gate 不可散落 | | `shared` 必须是 thin shared layer | 不允许变成 `common` 垃圾桶 | --- ##### 5. 推荐门禁 ##### 5.1 架构门禁 进入生产前必须满足： ```text - 已登记 catalog - 已指定 owner - 已定义 lifecycle - 已声明 service boundary 和依赖关系 - 已定义 API / event / dataset / resource 契约 - 已有最小 SLO - 已有日志、指标、追踪或健康检查 - 已有发布与回滚方案 - 已通过安全基线检查 ``` ##### 5.2 契约门禁 ```text - API schema 校验 - Event schema 兼容性校验 - Dataset schema 兼容性校验 - Policy 语法校验 - Breaking change 检测 - Consumer impact 分析 ``` ##### 5.3 运行门禁 ```text - Health check - Readiness check - Alert rule - Dashboard - Error budget - Runbook - Backup policy - Rollback policy ``` --- ##### 6. 每个服务的推荐最小结构 适用于 `services///` 下的 deployable service。 `products/` 或 `middle-platform/` 内部若仍直接承载可部署服务，也应先迁入或映射到同等 service root contract。 ```text service-name/ ├── src/ ├── tests/ ├── configs/ │ ├── local/ │ ├── dev/ │ ├── staging/ │ └── production/ ├── docs/ │ ├── README.md │ ├── runbook.md │ └── troubleshooting.md ├── deploy/ │ ├── compose.yaml │ ├── k8s.yaml │ ├── helm/ │ ├── kustomize/ │ └── terraform/ ├── contracts/ │ └── README.md # 本服务私有契约说明；正式契约仍进入 repo/contracts ├── service.yaml # 服务运行契约：owner、entrypoints、data access、dependencies、deploy、rollback ├── catalog-info.yaml ├── CODEOWNERS └── README.md ``` 服务级 README 建议包含： ```text #### Service Name ##### Purpose 这个 service / component 解决什么问题。 ##### Owner Team、owner、on-call 与 escalation path。 ##### Runtime Runtime、dependencies、ports、environment variables。 ##### Contracts 提供哪些 APIs、events、datasets 或 resources。 ##### Dependencies 依赖哪些 services、resources、external systems。 ##### SLO Availability、latency、error rate、throughput 等目标。 ##### Observability Logs、metrics、traces、dashboards、alerts。 ##### Deployment Release、rollback、environment promotion rules。 ##### Runbook Common failures、diagnosis steps、recovery steps。 ##### Lifecycle experimental / development / production / deprecated / retired。 ``` --- ##### 7. 成熟度分阶段落地 不建议一开始就把所有目录做满。更现实的落地方式是分阶段推进。 ##### Phase 1：Minimum Enterprise Baseline 先落地： ```text governance/ contracts/ catalog/ infra/ services/ products/ shared/ ``` 必须具备： ```text - Owner - Catalog entry - API / Event / Schema contracts - Service runtime contracts - Per-service Dockerfile, entrypoint and deploy skeleton - Container image matrix and Compose aggregate entry point - Kubernetes and GitOps skeleton, before production rollout - CI - Base environments - Base observability - Release and rollback ``` ##### Phase 2：Platform Engineering 增加： ```text internal-platform/ middle-platform/ ``` 重点建设： ```text - Golden paths / paved roads - Service templates - Self-service provisioning - Developer portal - Data platform - API platform - Identity platform - Messaging platform - Service catalog / service scorecards - Runtime readiness scorecards ``` ##### Phase 3：Governance Automation 强化： ```text - Scorecard - Policy as Code - Contract testing - SLO automation - Cost attribution - Security posture management - Incident review automation ``` --- ##### 8. 常见反模式 | 反模式 | 问题 | | --- | --- | | 把所有公共代码放进 `shared/common` | 很快变成无法治理的 common dumping ground | | `infra` 里写业务逻辑 | Infrastructure 与 Product Surfaces 边界失控 | | `middle-platform` 服务某一个产品 | Platform Services 退化成 product backend | | 把 library、template 或脚本目录伪装成 `services` | Runtime boundary 虚假，后续 Docker/Kubernetes 只会放大耦合 | | 还没确认服务边界就先上容器编排 | 只是把耦合系统搬进更复杂的运行环境 | | 只有 Dockerfile，没有 service contract | 镜像能构建，但没人知道 owner、入口、依赖、数据权限和回滚方式 | | 每个服务各写一套 Kubernetes 规则 | 集群策略、资源限制、探针、网络和安全基线会漂移 | | GitOps 里混入手工补丁和业务逻辑 | desired state 失真，回滚和审计都不可靠 | | 生产检查和生产变更没有分开 | 只读巡检可能误变成部署动作，风险不可审计 | | 没有 `contracts` | 跨团队协作靠口头约定和代码注释 | | 没有 `catalog` | 系统多了以后找不到 owner、dependency、lifecycle | | 没有 `governance` | 目录结构会慢慢腐烂 | | 只有 Portal，没有 platform capability | 只是入口，不是 IDP | | 只有文档，没有 machine-readable contracts | 无法自动校验和治理 | | 所有团队直接操作底层 resources | 平台无法形成抽象和复用 | | SLO 只写在 PPT 里 | 不能参与 release gate、alerting、incident review | --- ##### 9. 推荐判定标准 一个目录是否应该存在，按以下问题判断： ##### 是否进入 `governance/` ```text 它是否定义 organization-level standards、decisions、gates、risks、SLO、postmortems？ ``` 是，则进入 `governance/`。 ##### 是否进入 `contracts/` ```text 它是否是跨 team、layer、system 的 machine-readable interface contract？ ``` 是，则进入 `contracts/`。 ##### 是否进入 `catalog/` ```text 它是否描述 systems、components、resources、owners、lifecycle？ ``` 是，则进入 `catalog/`。 ##### 是否进入 `infra/` ```text 它是否负责 runtime、delivery、environments、resources、security、observability、cost？ ``` 是，则进入 `infra/`。 ##### 是否进入 `internal-platform/` ```text 它是否服务 internal developers，提供 paved roads、self-service、developer experience？ ``` 是，则进入 `internal-platform/`。 ##### 是否进入 `middle-platform/` ```text 它是否是多个 product surfaces 可复用的 platform capability，而不是某个产品的业务逻辑？ ``` 是，则进入 `middle-platform/`。 ##### 是否进入 `services/` ```text 它是否是可以独立启动、停止、健康检查、测试、部署、扩缩容、回滚的 runtime unit？ ``` 是，则进入 `services///`。 ##### 是否进入 `infra/container/` ```text 它是否定义跨服务复用的 image matrix、Compose aggregate、registry、tag、retention 或 signing policy？ ``` 是，则进入 `infra/container/`。 ##### 是否进入 `infra/kubernetes/` ```text 它是否定义 cluster-level Kubernetes baseline、namespace、RBAC、quota、networking、policy、shared workload convention 或 operations runbook？ ``` 是，则进入 `infra/kubernetes/`。单个服务自己的 workload intent 仍优先放在 `services///deploy/`。 ##### 是否进入 `infra/gitops/` ```text 它是否定义 desired state、environment overlay、promotion、sync order、rollback 或 Argo CD / Flux application？ ``` 是，则进入 `infra/gitops/`。 ##### 是否进入 `products/` ```text 它是否直接面向 users、operators、channels、business workflows？ ``` 是，则进入 `products/`。 ##### 是否进入 `shared/` ```text 它是否是无 business semantics、low-level、stable、cross-domain 的 thin reuse？ ``` 是，才进入 `shared/`。 --- ##### 10. 最终判断 这个模型的关键不是目录多，而是把企业软件系统中不同类型的“真相”分开： ```text governance = Engineering Governance truth contracts = Interface Contract truth catalog = Software Catalog / Asset Inventory truth infra = Infrastructure and Operations truth internal-platform = Internal Developer Platform (IDP) truth middle-platform = Platform Services / Shared Capabilities truth services = Deployable Service Runtime truth products = Product Surfaces truth ``` 所以，较完善的企业级项目架构不应只是“四层架构”，而应是： ```text governance + contracts + catalog + infra + internal-platform + middle-platform + services + products ``` 再配一个严格受控、极薄的： ```text shared ``` 这是一套更接近现代 Platform Engineering、SRE、GitOps、Software Catalog、Data Governance、 Security Governance 与 IDP 共识的参考模型。实际落地时可以裁剪，但不建议混淆这些边界。