Merge pull request #6: 冻结 GoAdmin 技术基线

用户于 2026-08-12 明确验收 #5。
2026-08-12 16:32:44 +08:00
parent 2285fb0a6d 7dac43436a
commit 8486d90001
8 changed files with 288 additions and 6 deletions
@@ -190,6 +190,16 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才
 - 不为单个页面直接改变底层公共组件的全局行为。确需全局修改或同时影响 Sense、Bell 时，必须单独建单并明确受影响页面、兼容方式和回归验证；跨产品影响按协同工单处理。
 - UI 验收至少检查：没有多余入口、没有可见但不可用的失效入口、没有重复实现已有组件，并且视觉与交互保持一致。

+### Sense/Bell GoAdmin 技术基线
+
+- `goadmin-baseline.json` 是 Sense、Bell 共用的 GoAdmin 上游与工具链版本事实来源；上游 URL 加完整 commit 是可复现标识，tag、`package.json` version、本机目录内容或本机已安装版本都不能替代 commit。
+- `D:\github\goadmin\go-admin`、`go-admin-ui`、`go-admin-doc` 是当前机器的只读参考副本。Agent 可以读取和验证，不得在这些目录开发、修改或提交 yovision 产品代码。
+- Sense、Bell 必须从同一冻结基线分别初始化，保留独立代码、配置、构建、测试、版本和发布；不得通过共同修改参考仓库形成隐藏的共享实现。
+- 复制或派生上游代码时必须保留对应 MIT 许可证和版权声明，并记录实际复制来源的 commit。
+- `go-admin-doc` 只用于理解上游框架用法；yovision 的 Gitea Wiki、`AGENTS.md` 和 `goadmin-baseline.json` 仍是本项目事实来源。
+- 变更任一上游 commit、Go、Node 或 pnpm 版本必须建立 Sense/Bell 协同升级工单，验证两个产品后再更新基线；不得在单端业务工单中静默升级。
+- 当前冻结后端要求 Go 1.26.5；本机 Go 1.23.0 不满足要求，安装隔离的正确工具链并完成构建验证前，不得声称后端基线可构建。
+
 ### 三项目并行建单顺序

 客户交付需要 Sense、Brain、Bell 并行推进时，固定使用以下顺序：
@@ -22,3 +22,10 @@
 - 新页面优先复用 Bell/go-admin-ui 已有的布局、表格、表单、弹窗、上传、权限控制和请求封装；新增组件前在工单中说明现有组件为何不能满足需求。
 - 新增组件沿用 Bell 现有颜色、字号、间距、状态反馈、交互方式、命名和目录结构，并验证没有多余入口、失效入口或重复组件。
 - 修改底层公共组件的全局行为时，必须单独建单并列出所有受影响页面；同时影响 Sense 或共享基线时升级为协同工单。
+
+## GoAdmin 技术基线
+
+- 初始化或升级 Bell 前必须读取根 `goadmin-baseline.json`，按其中的 go-admin、go-admin-ui commit 和 Go/Node/pnpm 精确版本实施。
+- `D:\github\goadmin` 下的仓库仅可只读参考；Bell 产品代码只能写入 `Bell/` 或工单授权路径，不得在参考仓库原地开发。
+- 派生上游代码必须保留 MIT 许可证和版权声明；上游 `go-admin-doc` 只作框架用法参考，不覆盖 yovision Wiki 和本目录规则。
+- 变更冻结基线必须升级为 Sense/Bell 协同工单；Bell 可以独立发布，但不得单独漂移上游或工具链版本。
@@ -22,3 +22,10 @@
 - 新页面优先复用 Sense/go-admin-ui 已有的布局、表格、表单、弹窗、上传、权限控制和请求封装；新增组件前在工单中说明现有组件为何不能满足需求。
 - 新增组件沿用 Sense 现有颜色、字号、间距、状态反馈、交互方式、命名和目录结构，并验证没有多余入口、失效入口或重复组件。
 - 修改底层公共组件的全局行为时，必须单独建单并列出所有受影响页面；同时影响 Bell 或共享基线时升级为协同工单。
+
+## GoAdmin 技术基线
+
+- 初始化或升级 Sense 前必须读取根 `goadmin-baseline.json`，按其中的 go-admin、go-admin-ui commit 和 Go/Node/pnpm 精确版本实施。
+- `D:\github\goadmin` 下的仓库仅可只读参考；Sense 产品代码只能写入 `Sense/` 或工单授权路径，不得在参考仓库原地开发。
+- 派生上游代码必须保留 MIT 许可证和版权声明；上游 `go-admin-doc` 只作框架用法参考，不覆盖 yovision Wiki 和本目录规则。
+- 变更冻结基线必须升级为 Sense/Bell 协同工单；Sense 可以独立发布，但不得单独漂移上游或工具链版本。
@@ -3,6 +3,7 @@
 from __future__ import annotations

 import argparse
+import json
 import re
 from pathlib import Path

@@ -47,6 +48,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
        "## 阅读入口",
        "## 常用命令",
        "## 环境、配置与凭据",
+        "## Sense/Bell GoAdmin 固定技术基线",
    ),
    "docs/01-workflow.md": (
        "## 面向初级维护者的修改边界",
@@ -75,6 +77,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
    ),
    "docs/04-local-development-and-verification.md": (
        "## 环境要求",
+        "## Sense/Bell 固定工具链与只读参考源",
        "## 第一次运行",
        "## 常用调试方式",
        "## 完成修改前",
@@ -140,6 +143,7 @@ REQUIRED_FILES = (
    "docs/templates/task-archive.md",
    *CORE_DOCUMENT_REQUIREMENTS,
    "wiki-docs.json",
+    "goadmin-baseline.json",
    "dev_scripts/wiki_docs.py",
    "dev_scripts/sync_wiki_docs.py",
    ".gitea/issue_template/epic.md",
@@ -326,6 +330,131 @@ def check_go_admin_ui_rules(errors: list[str], root: Path = ROOT) -> None:
            errors.append(f"{relative_path} 缺少 go-admin 规则：{section}")


+GOADMIN_BASELINE_REQUIREMENTS = {
+    "runtimes": {
+        "go": "1.26.5",
+        "node": "22.22.1",
+        "package_manager": "pnpm",
+        "pnpm": "9.15.1",
+    },
+    "sources": {
+        "go-admin": {
+            "commit": "f06540883b41d03782bb6b2c4150f298f328c6b6",
+            "upstream_url": "https://github.com/go-admin-team/go-admin.git",
+            "branch": "master",
+            "describe": "v2.2.0-25-gf065408",
+            "exact_tag": None,
+            "local_reference_path": r"D:\github\goadmin\go-admin",
+            "license": "MIT",
+        },
+        "go-admin-ui": {
+            "commit": "67d393d713877572fab0b897296a4c1d525fc81d",
+            "upstream_url": "https://github.com/go-admin-team/go-admin-ui.git",
+            "branch": "master",
+            "describe": "v2.0.9-170-g67d393d",
+            "exact_tag": None,
+            "local_reference_path": r"D:\github\goadmin\go-admin-ui",
+            "package_version": "2.0.9",
+            "package_version_is_authoritative": False,
+            "license": "MIT",
+        },
+        "go-admin-doc": {
+            "commit": "424855aacf6905f3fde860c3331385cb25529a0d",
+            "upstream_url": "https://github.com/go-admin-team/go-admin-doc.git",
+            "branch": "master",
+            "describe": "424855a",
+            "exact_tag": None,
+            "local_reference_path": r"D:\github\goadmin\go-admin-doc",
+            "package_version_is_authoritative": False,
+            "license": "MIT",
+        },
+    },
+}
+
+
+def check_goadmin_baseline(errors: list[str], root: Path = ROOT) -> None:
+    """检查 Sense/Bell 共用上游和工具链基线可复现且规则完整。"""
+
+    path = root / "goadmin-baseline.json"
+    if not path.is_file():
+        errors.append("缺少 GoAdmin 技术基线：goadmin-baseline.json")
+        return
+    try:
+        baseline = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        errors.append(f"GoAdmin 技术基线不是有效 JSON：{exc}")
+        return
+
+    for group, entries in GOADMIN_BASELINE_REQUIREMENTS.items():
+        actual_group = baseline.get(group)
+        if not isinstance(actual_group, dict):
+            errors.append(f"GoAdmin 技术基线缺少对象：{group}")
+            continue
+        for name, expected in entries.items():
+            actual = actual_group.get(name)
+            if isinstance(expected, dict):
+                if not isinstance(actual, dict):
+                    errors.append(f"GoAdmin 技术基线缺少来源：{name}")
+                    continue
+                for field, value in expected.items():
+                    if actual.get(field) != value:
+                        errors.append(
+                            f"GoAdmin 技术基线不匹配：{name}.{field} 应为 {value}"
+                        )
+            elif actual != expected:
+                errors.append(
+                    f"GoAdmin 技术基线不匹配：{group}.{name} 应为 {expected}"
+                )
+
+    if baseline.get("authority") != "upstream_url_and_commit":
+        errors.append("GoAdmin 技术基线必须以上游 URL 和 commit 为权威标识")
+    rules = baseline.get("rules")
+    required_rules = (
+        "local_repositories_are_read_only",
+        "product_code_must_not_be_developed_in_reference_repositories",
+        "preserve_upstream_license_and_copyright",
+        "upgrades_require_coordination_issue",
+        "sense_and_bell_release_independently",
+    )
+    if not isinstance(rules, dict):
+        errors.append("GoAdmin 技术基线缺少 rules")
+    else:
+        for rule in required_rules:
+            if rules.get(rule) is not True:
+                errors.append(f"GoAdmin 技术基线规则必须为 true：{rule}")
+
+    agent_requirements = {
+        "AGENTS.md": (
+            "### Sense/Bell GoAdmin 技术基线",
+            "`goadmin-baseline.json`",
+            "上游 URL 加完整 commit 是可复现标识",
+            "当前机器的只读参考副本",
+            "必须建立 Sense/Bell 协同升级工单",
+            "本机 Go 1.23.0 不满足要求",
+        ),
+        "Sense/AGENTS.md": (
+            "## GoAdmin 技术基线",
+            "读取根 `goadmin-baseline.json`",
+            "不得在参考仓库原地开发",
+            "不得单独漂移上游或工具链版本",
+        ),
+        "Bell/AGENTS.md": (
+            "## GoAdmin 技术基线",
+            "读取根 `goadmin-baseline.json`",
+            "不得在参考仓库原地开发",
+            "不得单独漂移上游或工具链版本",
+        ),
+    }
+    for relative_path, required in agent_requirements.items():
+        agent_path = root / relative_path
+        if not agent_path.is_file():
+            errors.append(f"缺少 GoAdmin 基线规则文件：{relative_path}")
+            continue
+        content = agent_path.read_text(encoding="utf-8")
+        for section in missing_sections(content, required):
+            errors.append(f"{relative_path} 缺少 GoAdmin 基线规则：{section}")
+
+
 def check_claude_code_entry(errors: list[str], root: Path = ROOT) -> None:
    """检查 Claude Code 入口直接复用共同 Agent 规则。"""

@@ -423,6 +552,7 @@ def main() -> int:
    check_task_template(errors)
    check_agent_efficiency_rules(errors)
    check_go_admin_ui_rules(errors)
+    check_goadmin_baseline(errors)
    check_claude_code_entry(errors)
    check_archives(errors)

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Project-Profile.-
-wiki_revision: 4a78dc8673d88b05f1c62b254242180a68465ccd
-synchronized_at: 2026-08-11T10:30:26Z
+wiki_revision: 5561227400539f0a3ba7713be16c171feb811fcb
+synchronized_at: 2026-08-12T01:26:47Z
 <!-- gitea-wiki-mirror:end -->

 # 项目档案
@@ -42,7 +42,7 @@ synchronized_at: 2026-08-11T10:30:26Z
 - 证据：客户侧 MinIO/S3 兼容对象存储；常态录像优先留在客户已有 NVR。
 - 首期验证平台：NVIDIA x86/Jetson；M1-M3 不承诺 GB/T 28181、信创或原生 App。

-业务代码尚未初始化，具体 Go/Python/Node 版本必须在对应骨架工单中冻结后更新本页。
+业务代码尚未初始化；Sense/Bell 的 Go/Node 基线已冻结并记录于下文，Brain 的 Python/CUDA 版本仍须在对应骨架工单中冻结。

 ## 阅读入口

@@ -78,3 +78,17 @@ Sense、Brain、Bell 的构建、运行和测试命令尚待各自骨架工单
 - 单仓包含 Sense、Brain、Bell 三个开发项目。
 - 计划由三名主 agent 尽量并行处理各自独立工单；需要跨项目协作时再建立协调工单并启用新 agent。
 - 旧仓库在新纵切验收前保留，不删除、不覆盖。
+
+## Sense/Bell GoAdmin 固定技术基线
+
+Sense、Bell 共用的可复现技术基线记录在仓库根 `goadmin-baseline.json`。正式版本标识是上游 URL 与完整 commit 的组合；本机目录、分支名、最近 tag 和 `package.json` version 只作辅助信息。
+
+| 参考源 | 用途 | 冻结提交 | 描述版本 | 本机只读位置 |
+|---|---|---|---|---|
+| go-admin | 后端骨架 | `f06540883b41d03782bb6b2c4150f298f328c6b6` | `v2.2.0-25-gf065408` | `D:\github\goadmin\go-admin` |
+| go-admin-ui | 前端骨架 | `67d393d713877572fab0b897296a4c1d525fc81d` | `v2.0.9-170-g67d393d` | `D:\github\goadmin\go-admin-ui` |
+| go-admin-doc | 只读用法参考 | `424855aacf6905f3fde860c3331385cb25529a0d` | 无精确 tag | `D:\github\goadmin\go-admin-doc` |
+
+固定工具链为 Go 1.26.5、Node.js 22.22.1、pnpm 9.15.1。go-admin-ui 的 `package.json` version 仍为 2.0.9，但冻结提交位于 `v2.0.9` 后 170 个提交，因此不得只用“2.0.9”代表当前基线。
+
+三个上游仓库均使用 MIT 许可证。派生代码必须保留许可证和版权声明。Sense、Bell 使用同一上游基线，但分别维护代码、配置、构建、测试、版本和发布。任何上游或工具链升级必须建立影响 Sense/Bell 的协同工单。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.-
-wiki_revision: be0864a5bdbe06bd8358f2d013aa7313ab13e73b
-synchronized_at: 2026-08-11T10:30:41Z
+wiki_revision: 1eb27d082ebf892343c9a5eed6f9363363234903
+synchronized_at: 2026-08-12T01:26:57Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -17,7 +17,7 @@ synchronized_at: 2026-08-11T10:30:41Z
 | Gitea | 工单与 Wiki | 浏览仓库或调用 MCP |
 | Gitea PAT | Wiki 写入 | 仅由 MCP 或 `GITEA_TOKEN` 提供，不打印 |

-Go、Node、CUDA、PostgreSQL、MediaMTX 的精确要求将在对应项目骨架工单冻结；当前不把旧仓库环境当作新项目事实。
+Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/CUDA 以及 PostgreSQL、MediaMTX 精确版本仍将在对应骨架工单冻结。旧仓库环境不自动成为新项目事实。

 ## 第一次运行

@@ -88,3 +88,25 @@ git status --short
 ```

 业务工单还必须运行其声明的子项目测试；跨契约工单必须运行所有受影响项目的契约测试。未执行部分写入工单。
+
+## Sense/Bell 固定工具链与只读参考源
+
+根 `goadmin-baseline.json` 是机器可读基线。开始 Sense/Bell 骨架或升级工作前，先核对：
+
+```powershell
+Get-Content .\goadmin-baseline.json
+
+git -C D:\github\goadmin\go-admin rev-parse HEAD
+git -C D:\github\goadmin\go-admin-ui rev-parse HEAD
+git -C D:\github\goadmin\go-admin-doc rev-parse HEAD
+
+go version
+node --version
+pnpm --version
+```
+
+`D:\github\goadmin` 下三个仓库只允许读取和核对，不允许在其中开发或提交 yovision 产品代码。本机路径不是跨机器事实；缺少该路径时，应从清单中的上游 URL 检出相同 commit 到仓库外目录。
+
+截至 2026-08-12 的本机核对结果：Go 1.23.0，不满足 go-admin `go.mod` 声明的 Go 1.26.5；Node.js 22.22.1 符合基线；pnpm 尚未安装，Corepack 0.34.6 可用。因此后端构建和 pnpm 前端构建均未完成验证。安装隔离的 Go 1.26.5 并通过 Corepack 启用 pnpm 9.15.1 后，才可执行后续骨架构建验收。
+
+`go-admin-doc` 只用于理解上游框架；项目自己的架构、开发规则和版本事实仍以 yovision Wiki、Agent 规则与 `goadmin-baseline.json` 为准。
@@ -0,0 +1,61 @@
+{
+  "schema_version": 1,
+  "frozen_at": "2026-08-12",
+  "authority": "upstream_url_and_commit",
+  "consumers": [
+    "Sense",
+    "Bell"
+  ],
+  "runtimes": {
+    "go": "1.26.5",
+    "node": "22.22.1",
+    "package_manager": "pnpm",
+    "pnpm": "9.15.1"
+  },
+  "sources": {
+    "go-admin": {
+      "role": "backend_baseline",
+      "local_reference_path": "D:\\github\\goadmin\\go-admin",
+      "upstream_url": "https://github.com/go-admin-team/go-admin.git",
+      "branch": "master",
+      "commit": "f06540883b41d03782bb6b2c4150f298f328c6b6",
+      "describe": "v2.2.0-25-gf065408",
+      "exact_tag": null,
+      "license": "MIT",
+      "license_file": "LICENSE.md"
+    },
+    "go-admin-ui": {
+      "role": "frontend_baseline",
+      "local_reference_path": "D:\\github\\goadmin\\go-admin-ui",
+      "upstream_url": "https://github.com/go-admin-team/go-admin-ui.git",
+      "branch": "master",
+      "commit": "67d393d713877572fab0b897296a4c1d525fc81d",
+      "describe": "v2.0.9-170-g67d393d",
+      "exact_tag": null,
+      "package_version": "2.0.9",
+      "package_version_is_authoritative": false,
+      "license": "MIT",
+      "license_file": "LICENSE"
+    },
+    "go-admin-doc": {
+      "role": "reference_only_documentation",
+      "local_reference_path": "D:\\github\\goadmin\\go-admin-doc",
+      "upstream_url": "https://github.com/go-admin-team/go-admin-doc.git",
+      "branch": "master",
+      "commit": "424855aacf6905f3fde860c3331385cb25529a0d",
+      "describe": "424855a",
+      "exact_tag": null,
+      "package_version": "0.0.1",
+      "package_version_is_authoritative": false,
+      "license": "MIT",
+      "license_file": "LICENSE"
+    }
+  },
+  "rules": {
+    "local_repositories_are_read_only": true,
+    "product_code_must_not_be_developed_in_reference_repositories": true,
+    "preserve_upstream_license_and_copyright": true,
+    "upgrades_require_coordination_issue": true,
+    "sense_and_bell_release_independently": true
+  }
+}
@@ -17,6 +17,7 @@ from check_harness import (  # noqa: E402
    check_core_documents,
    check_agent_efficiency_rules,
    check_go_admin_ui_rules,
+    check_goadmin_baseline,
    check_task_template,
    core_mapping_errors,
    missing_sections,
@@ -213,6 +214,36 @@ class AgentRuleTests(unittest.TestCase):
        self.assertIn("缺少 go-admin 规则文件：Sense/AGENTS.md", errors)
        self.assertIn("缺少 go-admin 规则文件：Bell/AGENTS.md", errors)

+    def test_goadmin_baseline_is_frozen(self) -> None:
+        errors: list[str] = []
+        check_goadmin_baseline(errors)
+        self.assertEqual(errors, [])
+
+    def test_goadmin_baseline_rejects_unpinned_source(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "goadmin-baseline.json").write_text(
+                '{"authority":"tag","runtimes":{},'
+                '"sources":{"go-admin":{}},"rules":{}}',
+                encoding="utf-8",
+            )
+            errors: list[str] = []
+            check_goadmin_baseline(errors, root)
+        self.assertTrue(any("go-admin.commit" in error for error in errors))
+        self.assertIn(
+            "GoAdmin 技术基线必须以上游 URL 和 commit 为权威标识",
+            errors,
+        )
+
+    def test_goadmin_baseline_reports_missing_file(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            errors: list[str] = []
+            check_goadmin_baseline(errors, Path(directory))
+        self.assertEqual(
+            errors,
+            ["缺少 GoAdmin 技术基线：goadmin-baseline.json"],
+        )
+
    def test_claude_code_entry_requires_exact_import_line(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            root = Path(directory)