docs: references - update enterprise architecture template

2026-08-01 13:17:45 +00:00 · 2026-06-01 00:34:38 +08:00
parent bb11623a6d
commit 93d9507a27
1 changed files with 370 additions and 213 deletions
@@ -16,7 +16,7 @@
 |:---|:---|
 | 新项目结构怎么搭 | [项目架构模板](#reference-engineering-practice-1-项目架构模板) |
 | Python 项目骨架怎么搭 | [通用 Python 项目骨架](#reference-engineering-practice-通用-python-项目骨架) |
-| 企业级项目架构怎么搭 | [企业级 Monorepo / Multi-repo 项目架构标准模板](#reference-engineering-practice-企业级-monorepo-multi-repo-项目架构标准模板) |
+| 企业级项目架构怎么搭 | [Enterprise Monorepo / Multi-Repo Reference Architecture Template](#reference-engineering-practice-enterprise-monorepo-multi-repo-reference-architecture-template) |
 | AI 代码质量怎么卡住 | [AI 编程质量门禁与常见坑](#quality-gates) |
 | 系统提示词怎么写 | [系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则) |
 | 强前置条件怎么约束 | [强前置条件约束](#reference-engineering-practice-2-强前置条件约束) |
@@ -42,7 +42,7 @@
    - [3. Python Web/API 项目结构](#reference-engineering-practice-3-python-webapi-项目结构)
    - [4. 数据科学 / 量化项目结构](#reference-engineering-practice-4-数据科学-量化项目结构)
    - [5. Monorepo 项目结构](#reference-engineering-practice-5-monorepo-项目结构)
-    - [企业级 monorepo / multi-repo 项目架构标准模板](#reference-engineering-practice-企业级-monorepo-multi-repo-项目架构标准模板)
+    - [Enterprise Monorepo / Multi-Repo Reference Architecture Template](#reference-engineering-practice-enterprise-monorepo-multi-repo-reference-architecture-template)
    - [6. Full-Stack Web 应用结构](#reference-engineering-practice-6-full-stack-web-应用结构)
    - [7. Dataset First 数据服务结构](#reference-engineering-practice-7-dataset-first-数据服务结构)
      - [一句话](#reference-engineering-practice-一句话)
@@ -1291,33 +1291,36 @@ project-monorepo/
 - `contracts/` 存 API schema、事件 schema、数据契约，作为跨服务真相源。
 - 顶层脚本只做编排，不隐藏服务内部逻辑。

-<a id="reference-engineering-practice-企业级-monorepo-multi-repo-项目架构标准模板"></a>
-#### 企业级 monorepo / multi-repo 项目架构标准模板
+<a id="reference-engineering-practice-enterprise-monorepo-multi-repo-reference-architecture-template"></a>
+#### Enterprise Monorepo / Multi-Repo Reference Architecture Template

-版本：v1.0
-定位：共识级企业参考模型
-适用：中大型工程组织、平台工程、技术中台、多产品线、AI / 数据 / 云原生系统
+版本：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 划分：

-| 顶层目录                 | 核心职责                                 | 真相类型    |
-| -------------------- | ------------------------------------ | ------- |
-| `governance/`        | 标准、Owner、ADR、SLO、风险、复盘、门禁            | 规则与演进真相 |
-| `contracts/`         | API、事件、Schema、数据集、资源、策略              | 跨层契约真相  |
-| `catalog/`           | 系统、组件、资源、Owner、生命周期                  | 软件资产真相  |
-| `infra/`             | 基础设施、运行、交付、观测、安全、成本                  | 运行底座真相  |
-| `internal-platform/` | 内部开发者平台、模板、自助化、门户                    | 开发者体验真相 |
-| `middle-platform/`   | 数据、API、计算、AI、消息、身份等复用能力              | 技术中台能力  |
-| `products/`          | Web、Mobile、Bot、Admin、Reporting 等产品入口 | 用户价值交付  |
-| `shared/`            | 极薄共享库、SDK、测试夹具                       | 低层复用能力  |
+| 顶层目录                 | 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 + products**
-> `shared/` 是辅助层，不应膨胀成新的业务中台。
+> **governance + contracts + catalog + infra + internal-platform + middle-platform + services + products**
+> `shared/` 是辅助层，不应膨胀成新的 platform service 或 product backend。

 ---

@@ -1325,84 +1328,106 @@ project-monorepo/

 ```text
 repo/
-├── governance/                         # 治理真相：标准、owner、ADR、SLO、风险、复盘、门禁
-│   ├── standards/                      # 工程标准、安全标准、代码规范、架构原则
-│   ├── decisions/                      # ADR：Architecture Decision Records
-│   ├── ownership/                      # Owner、RACI、值班、升级路径
-│   ├── slo/                            # SLI、SLO、error budget、服务等级目标
-│   ├── risks/                          # 风险登记、威胁模型、合规风险
-│   ├── gates/                          # 发布门禁、安全门禁、质量门禁
-│   └── postmortems/                    # 事故复盘、行动项、长期修复
+├── 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/                          # 机器可读契约：跨层边界的唯一真相
-│   ├── apis/                           # OpenAPI、GraphQL schema、RPC IDL
-│   ├── events/                         # AsyncAPI、事件定义、topic、订阅约定
-│   ├── schemas/                        # JSON Schema、Proto、Avro、Parquet schema
-│   ├── datasets/                       # 数据集契约、数据产品、质量规则、血缘
-│   ├── resources/                      # 云资源、K8s CRD、Terraform module interface
-│   └── policies/                       # OPA、Rego、IAM policy、数据访问策略
+├── 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/                            # 软件资产目录：系统、组件、资源、API、owner、生命周期
-│   ├── systems/                        # System 定义：产品域、平台域、业务系统
-│   ├── components/                     # Component 定义：服务、库、任务、前端应用
-│   ├── resources/                      # Resource 定义：DB、queue、bucket、cache、cluster
-│   ├── domains/                        # Domain 定义：业务域、技术域、平台域
-│   └── scorecards/                     # 健康度、成熟度、安全、可靠性评分
+├── 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/                              # 基础设施与运行底座
-│   ├── control-plane/                  # 拓扑、生命周期、状态控制、cluster management
-│   ├── resource-plane/                 # compute、network、storage、database、queue
-│   ├── runtime-plane/                  # worker、daemon、job、scheduler、queue consumer
-│   ├── delivery-plane/                 # CI/CD、制品、发布、回滚、环境提升
-│   ├── observability/                  # logs、metrics、traces、health、alerts、dashboards
-│   ├── security/                       # secrets、IAM、policy enforcement、audit
-│   ├── environments/                   # local、dev、staging、production、dr
-│   ├── disaster-recovery/              # backup、restore、runbook、演练
-│   └── cost/                           # FinOps、预算、资源归属、成本归因
+├── 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/                  # 内部开发者平台 IDP，不等于业务中台
-│   ├── portal/                         # Backstage 类开发者入口
-│   ├── templates/                      # golden paths、脚手架、服务模板
-│   ├── orchestration/                  # provision、workflow、automation
-│   ├── developer-tools/                # CLI、SDK、诊断工具、本地开发工具
-│   ├── scorecards/                     # 服务健康、质量、安全、成熟度评分
-│   └── docs/                           # 平台用户文档、接入指南、FAQ
+├── 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/                    # 技术中台：业务无关、产品复用的公共能力
-│   ├── 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 API、webhook、provider adapter
-│   ├── identity-platform/              # account、authn、authz、tenant
-│   ├── search-platform/                # indexing、retrieval、ranking
-│   └── experimentation-platform/       # A/B、feature flag、experiment metrics
+├── 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
 │
-├── products/                           # 产品与渠道，直接面向用户或业务场景
-│   ├── web/                            # Web 产品
-│   ├── mobile/                         # 移动端产品
-│   ├── bot/                            # Bot、Agent、Chat 入口
-│   ├── admin/                          # 管理后台、运营后台
-│   └── reporting/                      # 报表、BI、经营分析入口
+├── 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/
 │
-├── shared/                             # 极薄共享库，只放真正跨域复用的低层代码
-│   ├── libraries/                      # 通用基础库
-│   ├── sdks/                           # 对外或内部 SDK
-│   └── test-fixtures/                  # 跨域测试夹具
+├── 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
 │
-├── tools/                              # 仓库级工具：codegen、lint、verify、migration helpers
-├── docs/                               # 文档入口，不替代 governance/contracts/catalog
-└── ci/ 或 .github/                     # CI workflow 入口
+├── 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/`：规则与演进真相
+##### 3.1 `governance/`: Engineering Governance

-用于承载组织级工程治理，不放业务代码。
+用于承载组织级 Engineering Governance，不放业务代码。

 应包含：

@@ -1427,23 +1452,27 @@ governance/
 │   ├── release-gate.yaml
 │   ├── security-gate.yaml
 │   └── architecture-gate.yaml
+├── change-records/
+│   └── migration-record-template.md
 └── postmortems/
    └── postmortem-template.md
 ```

 核心规则：

-* 架构决策必须进入 `decisions/`
-* Owner 与升级路径必须进入 `ownership/`
+* 架构决策必须进入 `decisions/`，以 ADR 形式长期留痕
+* Owner、RACI、on-call 与 escalation path 必须进入 `ownership/`
 * 生产系统必须定义 SLO
+* 架构迁移、服务化拆分、运行时接入必须留下 task tree、evidence report 和 rollback runbook
 * 事故必须有复盘和行动项
-* 发布、安全、质量门禁应机器可执行
+* 发布、安全、质量、架构门禁应尽量机器可执行

 ---

-##### 3.2 `contracts/`：跨层契约真相
+##### 3.2 `contracts/`: Interface Contract Registry

-用于放置机器可读契约，避免接口、事件、数据模型散落在代码注释或文档里。
+用于放置 machine-readable interface contracts，避免 API、events、schemas、datasets、
+resources、policies 散落在代码注释或普通文档里。

 推荐结构：

@@ -1478,15 +1507,15 @@ contracts/

 * API 变更必须先更新契约
 * 事件字段变更必须兼容旧消费者
-* Dataset 必须声明 owner、schema、质量规则、生命周期
-* Policy 应尽量机器可执行
-* 契约变更必须进入 CI 校验
+* Dataset contract 必须声明 owner、schema、quality rules、lifecycle
+* Policy 应尽量以 policy-as-code 形式机器可执行
+* Contract change 必须进入 CI 校验

 ---

-##### 3.3 `catalog/`：软件资产真相
+##### 3.3 `catalog/`: Software Catalog / Asset Inventory

-用于记录系统、组件、资源、API、Domain、Owner、Lifecycle。
+用于记录 systems、components、resources、APIs、domains、owners、lifecycle。

 推荐结构：

@@ -1530,16 +1559,17 @@ slo:

 核心规则：

-* 没有 owner 的系统不允许进入生产
-* 没有 catalog 的服务不应接入发布流水线
-* 资源必须能追溯到系统、团队和成本中心
+* 没有 owner 的 system 不允许进入 production
+* 没有 catalog entry 的 service 不应接入 release pipeline
+* Resource 必须能追溯到 system、team、cost center
 * Lifecycle 必须明确：experimental、development、production、deprecated、retired

 ---

-##### 3.4 `infra/`：基础设施与运行底座
+##### 3.4 `infra/`: Infrastructure and Operations

-`infra/` 负责运行、交付、安全、观测、灾备和成本，不承载业务逻辑。
+`infra/` 负责 Infrastructure and Operations：运行、交付、安全、观测、灾备和成本，
+不承载业务逻辑。

 推荐结构：

@@ -1551,6 +1581,20 @@ infra/
 ├── 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/
@@ -1563,17 +1607,22 @@ infra/

 核心规则：

-* 环境配置必须显式分离
-* 生产变更必须可审计、可回滚
-* 关键资源必须有备份、恢复方案和演练记录
-* 观测能力应覆盖 logs、metrics、traces、alerts、dashboards
-* 成本必须能归因到 owner、system、environment
+* 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/<domain>/<service>/deploy/`
+* `infra/gitops/` 管 desired state、environment promotion、sync order 和 rollback，不应放业务逻辑
+* 生产环境检查必须区分 read-only inspection 与 deployment/change；没有明确授权时只允许只读取证，不做远端变更

 ---

-##### 3.5 `internal-platform/`：内部开发者平台
+##### 3.5 `internal-platform/`: Internal Developer Platform (IDP)

-这是 IDP，不是业务中台。它服务的是内部开发者，目标是降低交付复杂度。
+这是 Internal Developer Platform (IDP)，不是 business domain platform，也不是某个 product backend。
+它服务的是内部开发者，目标是用 paved roads、self-service 和 automation 降低交付复杂度。

 推荐结构：

@@ -1589,15 +1638,15 @@ internal-platform/

 典型能力：

-* 服务创建模板
-* Golden path
-* 自助资源申请
-* 服务注册
-* CI/CD 接入
-* 发布操作入口
-* 服务健康评分
-* 诊断工具
-* 开发者文档
+* 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

 核心规则：

@@ -1607,9 +1656,10 @@ internal-platform/

 ---

-##### 3.6 `middle-platform/`：技术中台
+##### 3.6 `middle-platform/`: Platform Services / Shared Capabilities

-技术中台是可被多个产品复用的公共技术能力，不直接面向最终业务场景交付。
+`middle-platform/` 对应国际语境中的 Platform Services / Shared Capabilities。
+它提供多个 product surfaces 可复用的平台能力，不直接承载最终用户工作流，也不服务某一个单一产品。

 推荐结构：

@@ -1630,29 +1680,81 @@ middle-platform/

 | 子平台                         | 职责                                         |
 | --------------------------- | ------------------------------------------ |
-| `data-platform/`            | 数据采集、质量、血缘、目录、服务化                          |
-| `api-platform/`             | Gateway、认证、限流、Schema、查询层                   |
-| `compute-platform/`         | Batch、Stream、任务调度、派生计算                     |
-| `ai-platform/`              | LLM、Prompt、Tool、Context、Eval、Agent Runtime |
-| `messaging-platform/`       | 通知、事件、订阅、Push                              |
-| `integration-platform/`     | 外部 API、Webhook、Provider Adapter            |
-| `identity-platform/`        | Account、AuthN、AuthZ、Tenant                 |
-| `search-platform/`          | 索引、召回、排序、检索                                |
-| `experimentation-platform/` | A/B、Feature Flag、实验指标                      |
+| `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/`
-* 可以暴露能力给 `products/`
+* 可以通过 contracts 暴露能力给 `products/`
 * 不应依赖 `products/`
-* 不应承载某个单一产品的专属业务逻辑
-* 能力必须产品化：契约、文档、SLO、Owner、接入方式都要明确
+* 不应承载某个单一 product surface 的专属业务逻辑
+* Platform capability 必须产品化：contract、docs、SLO、owner、onboarding path 都要明确

 ---

-##### 3.7 `products/`：产品与渠道
+##### 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/<domain>/<service>/service.yaml` 应声明 owner、lifecycle、entrypoints、ports、data access、dependencies、SLO、deploy、rollback
+* `services/<domain>/<service>/deploy/compose.yaml` 和 `services/<domain>/<service>/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。

 推荐结构：

@@ -1667,17 +1769,17 @@ products/

 核心规则：

-* 产品可以消费 `middle-platform/` 暴露的能力
-* 产品可以使用 `internal-platform/` 提供的开发、发布、自助能力
-* 产品不应直接绕过契约访问底层资源
-* 产品特有逻辑留在产品内，不要污染中台
-* 多产品复用前，先证明确实跨产品稳定复用
+* Product surface 可以消费 `services/` 或 `middle-platform/` 暴露的 capabilities
+* Product team 可以使用 `internal-platform/` 提供的开发、发布、自助能力
+* Product surface 不应直接绕过 contracts 访问底层 resources
+* Product-specific logic 留在产品内，不要污染 Platform Services
+* 多产品复用前，先证明确实跨 product surfaces 稳定复用

 ---

-##### 3.8 `shared/`：极薄共享层
+##### 3.9 `shared/`: Thin Shared Libraries / SDKs

-`shared/` 是最容易变成垃圾桶的目录，必须严格限制。
+`shared/` 是最容易变成 `common` 垃圾桶的目录，必须严格限制。

 允许放：

@@ -1690,12 +1792,12 @@ shared/

 适合放：

-* 无业务语义的基础库
+* 无业务语义的 low-level libraries
 * SDK
 * 类型工具
 * 通用测试夹具
 * Codegen runtime
-* 跨域稳定协议适配
+* 跨域稳定 protocol adapters

 不适合放：

@@ -1707,7 +1809,7 @@ shared/

 核心规则：

-> `shared/` 必须薄。
+> `shared/` 必须是 thin shared layer。
 > 一旦它开始承载业务语义，就说明边界设计已经失控。

 ---
@@ -1717,34 +1819,37 @@ shared/
 推荐依赖方向：

 ```text
-products
+products / product surfaces
   ↓
-middle-platform
+services / deployable runtime services
+   ↓
+middle-platform / platform services
   ↓
 infra

-internal-platform
+internal-platform / IDP
   ↓
 infra

-contracts  ← 被所有层引用
-catalog    ← 被所有层注册
-governance ← 约束所有层
-shared     ← 仅提供极薄低层复用
+contracts  ← referenced by all layers
+catalog    ← registered by all layers
+governance ← constrains all layers
+shared     ← provides only thin low-level reuse
 ```

 ##### 强制边界规则

-| 规则                                                            | 说明                                              |
-| ------------------------------------------------------------- | ----------------------------------------------- |
-| `products` 只能消费 `middle-platform` / `internal-platform` 暴露的接口 | 不直接绕过契约访问底层资源                                   |
-| `middle-platform` 可以依赖 `infra`                                | 但不能依赖 `products`                                |
-| `internal-platform` 服务开发者                                     | 不承载业务领域能力                                       |
-| `infra` 不写业务逻辑                                                | 只负责运行、交付、安全、观测、成本                               |
-| `contracts` 是跨层接口真相                                           | API、event、schema、dataset、resource、policy 都应机器可读 |
-| `catalog` 是资产和 owner 真相                                       | 系统、组件、资源、Owner、Lifecycle 必须可查                   |
-| `governance` 是规则和演进真相                                         | 标准、ADR、SLO、复盘、门禁不可散落                            |
-| `shared` 必须极薄                                                 | 不允许变成 `common` 垃圾桶                              |
+| 规则 | 说明 |
+| --- | --- |
+| `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` 垃圾桶 |

 ---

@@ -1758,7 +1863,7 @@ shared     ← 仅提供极薄低层复用
 - 已登记 catalog
 - 已指定 owner
 - 已定义 lifecycle
- 已声明依赖关系
+- 已声明 service boundary 和依赖关系
 - 已定义 API / event / dataset / resource 契约
 - 已有最小 SLO
 - 已有日志、指标、追踪或健康检查
@@ -1794,7 +1899,8 @@ shared     ← 仅提供极薄低层复用

 ##### 6. 每个服务的推荐最小结构

-适用于 `products/` 或 `middle-platform/` 下的具体服务。
+适用于 `services/<domain>/<service>/` 下的 deployable service。
+`products/` 或 `middle-platform/` 内部若仍直接承载可部署服务，也应先迁入或映射到同等 service root contract。

 ```text
 service-name/
@@ -1810,11 +1916,14 @@ service-name/
 │   ├── runbook.md
 │   └── troubleshooting.md
 ├── deploy/
+│   ├── compose.yaml
+│   ├── k8s.yaml
 │   ├── helm/
 │   ├── kustomize/
 │   └── terraform/
 ├── contracts/
-│   └── README.md                      # 本服务私有契约说明，正式契约仍进入 repo/contracts
+│   └── README.md                      # 本服务私有契约说明；正式契约仍进入 repo/contracts
+├── service.yaml                       # 服务运行契约：owner、entrypoints、data access、dependencies、deploy、rollback
 ├── catalog-info.yaml
 ├── CODEOWNERS
 └── README.md
@@ -1826,31 +1935,31 @@ service-name/
 #### Service Name

 ##### Purpose
-这个服务解决什么问题。
+这个 service / component 解决什么问题。

 ##### Owner
-团队、负责人、值班与升级路径。
+Team、owner、on-call 与 escalation path。

 ##### Runtime
-运行方式、依赖、端口、环境变量。
+Runtime、dependencies、ports、environment variables。

 ##### Contracts
-提供哪些 API、事件、数据集或资源。
+提供哪些 APIs、events、datasets 或 resources。

 ##### Dependencies
-依赖哪些服务、资源、外部系统。
+依赖哪些 services、resources、external systems。

 ##### SLO
-可用性、延迟、错误率、吞吐等目标。
+Availability、latency、error rate、throughput 等目标。

 ##### Observability
-日志、指标、追踪、Dashboard、告警。
+Logs、metrics、traces、dashboards、alerts。

 ##### Deployment
-发布方式、回滚方式、环境提升规则。
+Release、rollback、environment promotion rules。

 ##### Runbook
-常见故障、排查步骤、恢复步骤。
+Common failures、diagnosis steps、recovery steps。

 ##### Lifecycle
 experimental / development / production / deprecated / retired。
@@ -1862,7 +1971,7 @@ experimental / development / production / deprecated / retired。

 不建议一开始就把所有目录做满。更现实的落地方式是分阶段推进。

-##### Phase 1：最小企业可用
+##### Phase 1：Minimum Enterprise Baseline

 先落地：

@@ -1871,6 +1980,7 @@ governance/
 contracts/
 catalog/
 infra/
+services/
 products/
 shared/
 ```
@@ -1879,15 +1989,19 @@ shared/

 ```text
 - Owner
- Catalog
- API / Event / Schema 契约
+- 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：平台化
+##### Phase 2：Platform Engineering

 增加：

@@ -1899,17 +2013,19 @@ middle-platform/
 重点建设：

 ```text
- Golden path
- 服务模板
- 自助资源申请
- 平台门户
- 数据平台
- API 平台
- 身份平台
- 消息平台
+- 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：治理自动化
+##### Phase 3：Governance Automation

 强化：

@@ -1927,18 +2043,24 @@ middle-platform/

 ##### 8. 常见反模式

-| 反模式                       | 问题                      |
-| ------------------------- | ----------------------- |
-| 把所有公共代码放进 `shared/common` | 很快变成无法治理的垃圾桶            |
-| `infra` 里写业务逻辑            | 基础设施和产品边界失控             |
-| `middle-platform` 服务某一个产品 | 中台退化成产品后端               |
-| 没有 `contracts`            | 跨团队协作靠口头约定和代码注释         |
-| 没有 `catalog`              | 系统多了以后找不到 owner、依赖和生命周期 |
-| 没有 `governance`           | 目录结构会慢慢腐烂               |
-| 只有 Portal，没有平台能力          | 只是入口，不是 IDP             |
-| 只有文档，没有机器可读契约             | 无法自动校验和治理               |
-| 所有团队直接操作底层资源              | 平台无法形成抽象和复用             |
-| SLO 只写在 PPT 里             | 不能参与发布、告警和复盘            |
+| 反模式 | 问题 |
+| --- | --- |
+| 把所有公共代码放进 `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 |

 ---

@@ -1949,7 +2071,7 @@ middle-platform/
 ##### 是否进入 `governance/`

 ```text
-它是否定义组织级规则、决策、门禁、风险、SLO、复盘？
+它是否定义 organization-level standards、decisions、gates、risks、SLO、postmortems？
 ```

 是，则进入 `governance/`。
@@ -1957,7 +2079,7 @@ middle-platform/
 ##### 是否进入 `contracts/`

 ```text
-它是否是跨团队、跨层、跨系统的机器可读接口？
+它是否是跨 team、layer、system 的 machine-readable interface contract？
 ```

 是，则进入 `contracts/`。
@@ -1965,7 +2087,7 @@ middle-platform/
 ##### 是否进入 `catalog/`

 ```text
-它是否描述系统、组件、资源、Owner、生命周期？
+它是否描述 systems、components、resources、owners、lifecycle？
 ```

 是，则进入 `catalog/`。
@@ -1973,7 +2095,7 @@ middle-platform/
 ##### 是否进入 `infra/`

 ```text
-它是否负责运行、交付、环境、资源、安全、观测、成本？
+它是否负责 runtime、delivery、environments、resources、security、observability、cost？
 ```

 是，则进入 `infra/`。
@@ -1981,7 +2103,7 @@ middle-platform/
 ##### 是否进入 `internal-platform/`

 ```text
-它是否服务内部开发者，提高开发、交付、运维效率？
+它是否服务 internal developers，提供 paved roads、self-service、developer experience？
 ```

 是，则进入 `internal-platform/`。
@@ -1989,15 +2111,47 @@ middle-platform/
 ##### 是否进入 `middle-platform/`

 ```text
-它是否是多个产品可复用的技术能力，而不是某个产品的业务逻辑？
+它是否是多个 product surfaces 可复用的 platform capability，而不是某个产品的业务逻辑？
 ```

 是，则进入 `middle-platform/`。

+##### 是否进入 `services/`
+
+```text
+它是否是可以独立启动、停止、健康检查、测试、部署、扩缩容、回滚的 runtime unit？
+```
+
+是，则进入 `services/<domain>/<service>/`。
+
+##### 是否进入 `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/<domain>/<service>/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/`。
@@ -2005,7 +2159,7 @@ middle-platform/
 ##### 是否进入 `shared/`

 ```text
-它是否是无业务语义、低层、稳定、跨域复用的薄能力？
+它是否是无 business semantics、low-level、stable、cross-domain 的 thin reuse？
 ```

 是，才进入 `shared/`。
@@ -2017,13 +2171,14 @@ middle-platform/
 这个模型的关键不是目录多，而是把企业软件系统中不同类型的“真相”分开：

 ```text
-governance  = 规则和演进真相
-contracts   = 跨层契约真相
-catalog     = 资产和 owner 真相
-infra       = 运行底座真相
-internal-platform = 开发者体验真相
-middle-platform   = 可复用技术能力真相
-products    = 用户价值交付真相
+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
 ```

 所以，较完善的企业级项目架构不应只是“四层架构”，而应是：
@@ -2035,6 +2190,7 @@ governance
 + infra
 + internal-platform
 + middle-platform
+ services
 + products
 ```

@@ -2044,7 +2200,8 @@ governance
 shared
 ```

-这是一套更接近现代平台工程、SRE、GitOps、软件资产目录、数据治理和企业级安全治理共识的参考模型。实际落地时可以裁剪，但不建议混淆这些边界。
+这是一套更接近现代 Platform Engineering、SRE、GitOps、Software Catalog、Data Governance、
+Security Governance 与 IDP 共识的参考模型。实际落地时可以裁剪，但不建议混淆这些边界。

 <a id="reference-engineering-practice-6-full-stack-web-应用结构"></a>
 #### 6. Full-Stack Web 应用结构