diff --git a/docs/references/README.md b/docs/references/README.md
index e4ff5af..89c7a00 100644
--- a/docs/references/README.md
+++ b/docs/references/README.md
@@ -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、数据契约，作为跨服务真相源。
- 顶层脚本只做编排，不隐藏服务内部逻辑。
-
-#### 企业级 monorepo / multi-repo 项目架构标准模板
+
+#### 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///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///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。
推荐结构：
@@ -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///` 下的 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///`。
+
+##### 是否进入 `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/`。
@@ -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 共识的参考模型。实际落地时可以裁剪，但不建议混淆这些边界。
#### 6. Full-Stack Web 应用结构