docs: references - expand architecture kit contracts

2026-07-29 03:37:44 +00:00 · 2026-06-01 23:18:27 +08:00
parent f3d7f8842b
commit 2e2743da34
8 changed files with 30 additions and 18 deletions
@@ -70,7 +70,7 @@ git push origin develop
 | `make check-directory-docs` | 校验仓库自有目录 README/AGENTS 覆盖 | Python 3 |
 | `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 |
 | `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | Python 3 |
-| `make check-modern-architecture-kit` | 校验现代企业数字化平台 starter kit 的 schema 和示例一致性 | Python 3 |
+| `make check-modern-architecture-kit` | 校验现代企业数字化平台 starter kit 的 19 组 schema、示例和跨文件一致性 | Python 3 |
 | `make check-wiki WIKI_DIR=/tmp/vibe-coding-cn.wiki` | 校验 GitHub Wiki 独立仓库本地 checkout 的页面覆盖、内链、旧口径和 Markdown | Python 3、Node.js 22+、本地 Wiki checkout |
 | `make sync-doc-toc` | 兼容旧线性 README 目录生成；当前拆分结构下通常无变更 | Python 3 |
 | `make test` | 执行本地质量门禁 | Node.js 22+、Python 3 |
@@ -233,14 +233,14 @@ git push origin develop
 - `scripts/check-directory-docs.py` - 仓库自有目录 README/AGENTS 覆盖检查脚本，供 `make check-directory-docs` 与 CI 使用
 - `scripts/check-metadata.py` - metadata 路径与锚点检查脚本，供 `make check-metadata` 与 CI 使用
 - `scripts/check-ai-citation.py` - llms 与 AI 引用语料路径和锚点检查脚本，供 `make check-ai-citation` 与 CI 使用
- `scripts/check-modern-architecture-kit.py` - 现代企业数字化平台 starter kit schema 与示例一致性检查脚本，供 `make check-modern-architecture-kit` 与 CI 使用
+- `scripts/check-modern-architecture-kit.py` - 现代企业数字化平台 starter kit 的 19 组 schema、示例和跨文件一致性检查脚本，供 `make check-modern-architecture-kit` 与 CI 使用
 - `scripts/check-wiki.py` - GitHub Wiki 独立仓库本地 checkout 页面覆盖、内链和旧口径检查脚本，供 `make check-wiki` 使用
 - `scripts/sync-doc-toc.py` - docs README 细粒度目录兼容脚本，当前拆分结构下通常无变更，供 `make sync-doc-toc` 使用
 - `tools/prompts-library/main.py` - 提示词转换工具入口
 - `docs/getting-started/README.md` - 从零开始索引入口，正文拆分到学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
 - `docs/concepts/problem-solving.md` - 问题定义与求解路径底层模型
 - `docs/references/project-architecture-template.md` - 常见项目结构、架构设计原则、最低门禁和检查清单
- `docs/references/modern-enterprise-architecture-kit/README.md` - 现代企业数字化平台 V2.1 starter kit、schema、示例和一致性校验入口
+- `docs/references/modern-enterprise-architecture-kit/README.md` - 现代企业数字化平台 V2.2 starter kit、schema、示例和一致性校验入口
 - `docs/references/technology-stack.md` - 常见软件系统技术栈、选型维度、组合案例与初学者学习路径
 - `skills/auto-skill/` - Skills 生成、重构与校验的元技能
 - `skills/auto-tmux/` - tmux 自动化操控、脚本化 pane 巡检、按键注入、日志录制与多终端协作技能
@@ -68,7 +68,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
 - docs/references/python-project-skeleton.md：Python 应用、服务、脚本工具和库项目的通用骨架。
 - docs/references/enterprise-architecture-template.md：中大型工程组织、平台工程和多产品线参考模型。
 - docs/references/modern-enterprise-architecture-template.md：面向领域产品网络、微服务容器 GitOps 边界、AI 原生能力、微调治理、AI 事件响应、内部平台、数据产品、供应链安全、FinOps 成本治理、版本治理、可执行标准、RACI 决策权、可靠性分级、仓库拓扑、迁移弃用、审计证据、联邦治理和行业对标矩阵的完整说明文档。
- docs/references/modern-enterprise-architecture-kit/README.md：现代企业数字化平台 V2.1 的 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。
+- docs/references/modern-enterprise-architecture-kit/README.md：现代企业数字化平台 V2.2 的 19 组 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。
 - docs/references/dataset-first-data-service.md：以 dataset、contract、registry、runtime 为核心的数据服务模板。
 - docs/references/code-organization.md：模块化、命名、注释、格式化、文档和工具。
 - docs/references/development-experience.md：变量名、文件结构、编码规范、架构原则和常见基础设施经验。
@@ -63,7 +63,7 @@
 - [通用 Python 项目骨架](./references/python-project-skeleton.md) - Python 应用、服务、脚本工具和库项目的通用骨架。
 - [企业级架构模板](./references/enterprise-architecture-template.md) - 中大型工程组织、平台工程和多产品线参考模型。
 - [现代企业数字化平台架构](./references/modern-enterprise-architecture-template.md) - 面向领域产品网络、微服务容器 GitOps 边界、AI 原生能力、微调治理、AI 事件响应、内部平台、数据产品、供应链安全、FinOps 成本治理、版本治理、可执行标准、RACI 决策权、可靠性分级、仓库拓扑、迁移弃用、审计证据、联邦治理和行业对标矩阵的完整说明文档。
- [现代企业数字化平台 Starter Kit](./references/modern-enterprise-architecture-kit/README.md) - 现代企业数字化平台 V2.1 的 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。
+- [现代企业数字化平台 Starter Kit](./references/modern-enterprise-architecture-kit/README.md) - 现代企业数字化平台 V2.2 的 19 组 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。
 - [Dataset First 数据服务](./references/dataset-first-data-service.md) - 数据服务模板。
 - [代码组织](./references/code-organization.md) - 模块化、命名、注释、格式化、文档和工具。
 - [开发经验](./references/development-experience.md) - 编码规范、架构原则和常见基础设施经验。
@@ -20,7 +20,7 @@ references/
 ├── python-project-skeleton.md
 ├── enterprise-architecture-template.md
 ├── modern-enterprise-architecture-template.md  # 现代企业数字化平台、版本治理、可执行标准、RACI、可靠性分级、仓库拓扑、迁移弃用、审计证据、微服务容器 GitOps、AI 原生能力、供应链安全和联邦治理蓝图
-├── modern-enterprise-architecture-kit/  # 现代企业数字化平台 V2.1 starter kit、schema、示例和一致性校验
+├── modern-enterprise-architecture-kit/  # 现代企业数字化平台 V2.2 starter kit、schema、示例和一致性校验
 ├── dataset-first-data-service.md
 ├── code-organization.md
 ├── development-experience.md
@@ -15,7 +15,7 @@
 | <a id="reference-engineering-practice-通用-python-项目骨架"></a>[通用 Python 项目骨架](python-project-skeleton.md) | Python 应用、服务、脚本工具和库项目的通用骨架。 |
 | <a id="reference-engineering-practice-enterprise-monorepo-multi-repo-reference-architecture-template"></a>[企业级 Monorepo / Multi-repo 架构模板](enterprise-architecture-template.md) | 中大型工程组织、平台工程和多产品线参考模型。 |
 | <a id="reference-modern-enterprise-architecture-template"></a>[现代企业数字化平台架构](modern-enterprise-architecture-template.md) | 面向领域产品网络、微服务容器 GitOps 边界、AI 原生能力、微调治理、AI 事件响应、内部平台、数据产品、供应链安全、FinOps 成本治理、版本治理、可执行标准、RACI 决策权、可靠性分级、仓库拓扑、迁移弃用、审计证据、联邦治理和行业对标矩阵的完整说明文档。 |
-| <a id="reference-modern-enterprise-architecture-kit"></a>[现代企业数字化平台 Starter Kit](modern-enterprise-architecture-kit/README.md) | 现代企业数字化平台 V2.1 的 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。 |
+| <a id="reference-modern-enterprise-architecture-kit"></a>[现代企业数字化平台 Starter Kit](modern-enterprise-architecture-kit/README.md) | 现代企业数字化平台 V2.2 的 19 组 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。 |
 | <a id="reference-engineering-practice-7-dataset-first-数据服务结构"></a>[Dataset First 数据服务结构](dataset-first-data-service.md) | 以 dataset、contract、registry、runtime 为核心的数据服务模板。 |
 | <a id="reference-engineering-practice-2-代码组织"></a>[代码组织](code-organization.md) | 模块化、命名、注释、格式化、文档和工具。 |
 | <a id="reference-engineering-practice-3-开发经验"></a>[开发经验](development-experience.md) | 变量名、文件结构、编码规范、架构原则和常见基础设施经验。 |
@@ -35,7 +35,7 @@
 - [通用 Python 项目骨架](python-project-skeleton.md) - Python 应用、服务、脚本工具和库项目的通用骨架。
 - [企业级 Monorepo / Multi-repo 架构模板](enterprise-architecture-template.md) - 中大型工程组织、平台工程和多产品线参考模型。
 - [现代企业数字化平台架构](modern-enterprise-architecture-template.md) - 面向领域产品网络、微服务容器 GitOps 边界、AI 原生能力、微调治理、AI 事件响应、内部平台、数据产品、供应链安全、FinOps 成本治理、版本治理、可执行标准、RACI 决策权、可靠性分级、仓库拓扑、迁移弃用、审计证据、联邦治理和行业对标矩阵的完整说明文档。
- [现代企业数字化平台 Starter Kit](modern-enterprise-architecture-kit/README.md) - 现代企业数字化平台 V2.1 的 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。
+- [现代企业数字化平台 Starter Kit](modern-enterprise-architecture-kit/README.md) - 现代企业数字化平台 V2.2 的 19 组 schema、YAML 示例、嵌套约束和跨文件一致性校验入口。
 - [Dataset First 数据服务结构](dataset-first-data-service.md) - 以 dataset、contract、registry、runtime 为核心的数据服务模板。
 - [代码组织](code-organization.md) - 模块化、命名、注释、格式化、文档和工具。
 - [开发经验](development-experience.md) - 变量名、文件结构、编码规范、架构原则和常见基础设施经验。
@@ -1,10 +1,10 @@
 # 现代企业数字化平台架构说明文档

-**文档版本**：V2.1
+**文档版本**：V2.2
 **适用对象**：企业管理层、产品负责人、架构师、研发负责人、数据负责人、平台团队、安全合规团队
 **适用范围**：中大型企业数字化平台建设、业务系统重构、平台工程建设、数据产品化、组织协同机制设计
 **文档定位**：本文件用于说明现代企业数字化平台的总体架构、核心组成、团队职责、治理机制、技术原则和落地路径。
-**专项修订**：V2.1 在 V2.0 starter kit 基础上增强 schema 嵌套约束、格式校验、跨文件一致性检查和 CI 门禁口径。
+**专项修订**：V2.2 在 V2.1 基础上补齐 API、事件、AI 工具、RAG、微调、GitOps、catalog 和 scorecard 的 starter kit 契约。

 ---

@@ -52,7 +52,7 @@

 | 版本 | 状态 | 说明 |
 | ---- | ---- | ---- |
-| `V2.1` | `Baseline Candidate` | 用作可执行企业标准起点；包含 starter kit、schema、示例、嵌套约束、跨文件一致性和自动化校验入口 |
+| `V2.2` | `Baseline Candidate` | 用作可执行企业标准起点；包含 19 组 starter kit schema/example、跨文件一致性和自动化校验入口 |

 ### 0.3 变更分级

@@ -109,12 +109,13 @@ git diff --check
 | `V1.9` | 2026-06-01 | Major | 增加仓库拓扑剖面、迁移与弃用策略、验证包和审计证据清单 |
 | `V2.0` | 2026-06-01 | Major | 新增可执行 starter kit、JSON Schema、YAML 示例和自动化校验入口 |
 | `V2.1` | 2026-06-01 | Minor | 增强 starter kit schema 嵌套约束、格式校验、跨文件一致性检查和 CI 门禁口径 |
+| `V2.2` | 2026-06-01 | Minor | 补齐 API、事件、AI 工具、RAG、微调、GitOps、catalog 和 scorecard 契约模板 |

-### 0.7 V2.1 可执行企业标准路线图
+### 0.7 V2.2 可执行企业标准路线图

-V2.0 已将 V1.9 的文档化基线转化为第一批可执行资产。V2.1 继续把字段约束、示例一致性和远程 CI 门禁补强为可执行口径。后续 `V2.x` 迭代应继续扩大 schema 覆盖、补充示例仓库，并把平台、catalog、GitOps 和审计系统连接起来。
+V2.0 已将 V1.9 的文档化基线转化为第一批可执行资产。V2.1 继续把字段约束、示例一致性和远程 CI 门禁补强为可执行口径。V2.2 把主文档最小验证包中的 API、事件、AI 工具、RAG、微调、GitOps、catalog 和 scorecard 纳入 schema/example 校验。后续 `V2.x` 迭代应继续补充示例仓库，并把平台、catalog、GitOps 和审计系统连接起来。

-V2.1 起点包括：
+V2.2 起点包括：

 1. 真相源字段矩阵：明确 `domain.yaml`、`service.yaml`、`ai-product.yaml`、`data-product.yaml`、catalog、GitOps 和 runtime 的字段权威。
 2. 契约模板：提供服务、领域、数据产品、AI 产品、Agent 工具、RAG、微调、GitOps 和生产就绪模板。
@@ -124,7 +125,7 @@ V2.1 起点包括：
 6. 可靠性分级：补齐 Tier-1 / Tier-2 / Tier-3、RTO、RPO、灾备演练、错误预算和 on-call 升级路径。
 7. 迁移与弃用：定义旧系统绞杀迁移、API 版本弃用、数据产品兼容、AI 模型退役和平台能力下线流程。
 8. 验证包：提供 `make test`、schema 校验、示例仓库和审计证据清单，证明标准可以落地执行。
-9. Starter Kit：提供 `docs/references/modern-enterprise-architecture-kit/` 下的 schema、示例、嵌套字段校验、格式校验和示例跨文件一致性检查。
+9. Starter Kit：提供 `docs/references/modern-enterprise-architecture-kit/` 下的 19 组 schema/example、嵌套字段校验、格式校验和示例跨文件一致性检查。

 ---

@@ -2517,6 +2518,17 @@ observability:
  replayEnabled: true
 ```

+V2.2 starter kit 还提供以下可执行契约模板：
+
+1. `api-contract.yaml`：API producer、consumer、auth、版本和兼容策略。
+2. `event-contract.yaml`：事件 topic、schema、幂等键、投递语义和消费者。
+3. `ai-tool-contract.yaml`：AI 工具输入输出、风险等级、人工确认、权限、审计和运行限制。
+4. `rag-index-contract.yaml`：RAG 来源、Embedding、切分、访问控制、刷新和删除策略。
+5. `fine-tuning-contract.yaml`：微调数据授权、实验追踪、评估、发布门禁和回滚。
+6. `gitops-deployment.yaml`：环境、namespace、镜像 digest、资源、发布策略和供应链准入。
+7. `catalog-data-product.yaml`、`catalog-ai-product.yaml`：catalog 指针、owner、生命周期和运行索引。
+8. `scorecard.yaml`：生产就绪、供应链、运行证据和复审周期。
+
 ### 10.10.3 自动化门禁映射

 门禁必须尽量前移到提交、构建、发布和运行阶段。人工评审只处理边界争议、风险接受和复杂权衡。
@@ -2658,7 +2670,7 @@ docs/references/modern-enterprise-architecture-kit/
 make check-modern-architecture-kit
 ```

-该命令是仓库内零依赖 starter gate，用于校验本仓库示例的 JSON Schema 子集、YAML 示例、嵌套必填字段、格式约束和示例间一致性。企业生产落地时应优先接入成熟校验器，例如 JSON Schema draft 2020-12 validator、YAML parser、OpenAPI / AsyncAPI checker、OPA / Cedar / Kyverno policy test 和 GitOps diff 工具；本仓库脚本只作为 starter kit 的最小可执行证明。
+该命令是仓库内零依赖 starter gate，用于校验本仓库 19 组示例的 JSON Schema 子集、YAML 示例、嵌套必填字段、格式约束和示例间一致性。企业生产落地时应优先接入成熟校验器，例如 JSON Schema draft 2020-12 validator、YAML parser、OpenAPI / AsyncAPI checker、OPA / Cedar / Kyverno policy test 和 GitOps diff 工具；本仓库脚本只作为 starter kit 的最小可执行证明。

 ```text
 governance/evidence/release-evidence-checklist.md
@@ -144,7 +144,7 @@ documents:
      role: 面向领域产品网络、微服务容器 GitOps 边界、AI 原生能力、微调治理、AI 事件响应、内部平台、数据产品、供应链安全、FinOps 成本治理、版本治理、可执行标准、RACI 决策权、可靠性分级、仓库拓扑、迁移弃用、审计证据、联邦治理和行业对标矩阵的完整说明文档
    - path: docs/references/modern-enterprise-architecture-kit/README.md
      title: 现代企业数字化平台 Starter Kit
-      role: 现代企业数字化平台 V2.1 的 schema、YAML 示例、嵌套约束和跨文件一致性校验入口
+      role: 现代企业数字化平台 V2.2 的 19 组 schema、YAML 示例、嵌套约束和跨文件一致性校验入口
    - path: docs/references/dataset-first-data-service.md
      title: Dataset First 数据服务结构
      role: dataset、contract、registry、runtime 为核心的数据服务模板
@@ -10,6 +10,6 @@
 - `check-directory-docs.py`：仓库自有目录 `README.md` / `AGENTS.md` 覆盖检查脚本；根 `.github/` 仅要求 `AGENTS.md`，避免 GitHub 首页误展示平台配置说明。
 - `check-metadata.py`：`metadata/taxonomy.yml` 与 `metadata/redirects.yml` 路径和锚点检查脚本。
 - `check-ai-citation.py`：`llms.txt`、`assets/ai-citation/llms-full.txt` 与 AI 引用语料路径和锚点检查脚本。
- `check-modern-architecture-kit.py`：现代企业数字化平台 starter kit 的 schema 与示例一致性检查脚本。
+- `check-modern-architecture-kit.py`：现代企业数字化平台 starter kit 的 19 组 schema、示例和跨文件一致性检查脚本。
 - `check-wiki.py`：GitHub Wiki 独立仓库本地 checkout 的页面覆盖、内链和旧口径检查脚本。
 - `sync-doc-toc.py`：兼容旧线性 README 的细粒度目录生成脚本；当前拆分结构下通常无变更。