docs: define go-admin UI reuse rules (#3)

已通过用户验收；任务归档完成后关闭 Issue #1。

AGENTS.md

@@ -180,6 +180,16 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才
 - 16 路是默认交付配额，不得成为数据库、数组、循环、分页、批处理或单机容量的硬上限。
 - 开始子项目工作前还必须读取对应目录的 `AGENTS.md`；共享契约工作读取 `contracts/AGENTS.md`。
 
+### go-admin / go-admin-ui 精简与复用
+
+- Sense、Bell 使用 go-admin 和 go-admin-ui 时遵循“最小可见、最小启用”：只呈现当前产品需要的菜单、路由、权限和接口，不把框架演示或无关管理能力暴露给用户。
+- 快速交付阶段优先使用配置、菜单权限或路由开关隐藏不用模块。隐藏只移除用户入口，不等于禁用；权限或安全相关能力必须同时关闭前端入口与后端访问能力。
+- 永久删除默认模块必须单独建立清理工单，先核对代码依赖、数据库对象、权限记录、构建影响、框架升级影响和回退方式，不在业务页面工单中顺手删除。
+- 新页面优先复用现有布局、表格、表单、弹窗、上传、权限控制和请求封装；现有组件无法满足明确需求时才新增组件，并在工单中说明复用缺口。
+- 新组件必须沿用项目现有的颜色、字号、间距、状态反馈、交互方式、命名和目录结构；不得引入与整体风格冲突的独立视觉体系。
+- 不为单个页面直接改变底层公共组件的全局行为。确需全局修改或同时影响 Sense、Bell 时，必须单独建单并明确受影响页面、兼容方式和回归验证；跨产品影响按协同工单处理。
+- UI 验收至少检查：没有多余入口、没有可见但不可用的失效入口、没有重复实现已有组件，并且视觉与交互保持一致。
+
 ### 三项目并行建单顺序
 
 客户交付需要 Sense、Brain、Bell 并行推进时，固定使用以下顺序：

Bell/AGENTS.md

@@ -14,3 +14,11 @@
 - 每个工单必须写明任务类型、主项目 `Bell`、主 agent、精确 `write_paths`、独立运行方式、测试命令和在 Sense/Brain 未启动时使用合成或第三方事件的验收标准。
 - 首轮并行建单只创建 Bell 独立工单；发现需要外部事件/证据契约、producer identity、Sense connector、根级部署或端到端测试时，停止扩写本工单，向主 agent 提交协同需求摘要。
 - 协同需求摘要至少包含生产者、消费者、接口目的、候选事实源、阻塞的 Bell 工单和建议验证；Bell agent 不直接创建契约实现或取得 `contracts/`、`Sense/`、`Brain/` 的写入权。
+
+## go-admin / go-admin-ui 约束
+
+- Bell 管理面只启用事件预警、告警处置和通知运维所需的默认能力；框架演示页和无关管理模块优先通过配置、菜单权限或路由开关隐藏。
+- 涉及权限或安全的不用模块不能只隐藏菜单，必须同时验证前端入口和后端接口均不可访问；永久删除默认模块必须单独建立清理工单。
+- 新页面优先复用 Bell/go-admin-ui 已有的布局、表格、表单、弹窗、上传、权限控制和请求封装；新增组件前在工单中说明现有组件为何不能满足需求。
+- 新增组件沿用 Bell 现有颜色、字号、间距、状态反馈、交互方式、命名和目录结构，并验证没有多余入口、失效入口或重复组件。
+- 修改底层公共组件的全局行为时，必须单独建单并列出所有受影响页面；同时影响 Sense 或共享基线时升级为协同工单。

Sense/AGENTS.md

@@ -14,3 +14,11 @@
 - 每个工单必须写明任务类型、主项目 `Sense`、主 agent、精确 `write_paths`、独立运行方式、测试命令和在 Bell/Brain 未启动时的验收标准。
 - 首轮并行建单只创建 Sense 独立工单；发现需要 Sense→Brain 源/配置契约、Sense/Brain→Bell 事件/证据契约、根级部署或端到端测试时，停止扩写本工单，向主 agent 提交协同需求摘要。
 - 协同需求摘要至少包含生产者、消费者、接口目的、候选事实源、阻塞的 Sense 工单和建议验证；Sense agent 不直接创建契约实现或取得 `contracts/`、`Brain/`、`Bell/` 的写入权。
+
+## go-admin / go-admin-ui 约束
+
+- Sense 管理面只启用智能 NVR、视频感知和本地运维所需的默认能力；框架演示页和无关管理模块优先通过配置、菜单权限或路由开关隐藏。
+- 涉及权限或安全的不用模块不能只隐藏菜单，必须同时验证前端入口和后端接口均不可访问；永久删除默认模块必须单独建立清理工单。
+- 新页面优先复用 Sense/go-admin-ui 已有的布局、表格、表单、弹窗、上传、权限控制和请求封装；新增组件前在工单中说明现有组件为何不能满足需求。
+- 新增组件沿用 Sense 现有颜色、字号、间距、状态反馈、交互方式、命名和目录结构，并验证没有多余入口、失效入口或重复组件。
+- 修改底层公共组件的全局行为时，必须单独建单并列出所有受影响页面；同时影响 Bell 或共享基线时升级为协同工单。

dev_scripts/check_harness.py

@@ -50,6 +50,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
     ),
     "docs/01-workflow.md": (
         "## 面向初级维护者的修改边界",
+        "## go-admin / go-admin-ui 开发约束",
         "## 每个任务的文档影响",
         "## 需求记录与流转",
         "## 稳定文档与任务归档",
@@ -286,6 +287,45 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         errors.append(f"AGENTS.md 缺少：{section}")
 
 
+def check_go_admin_ui_rules(errors: list[str], root: Path = ROOT) -> None:
+    """检查 Sense、Bell 共用的框架精简和组件复用规则。"""
+
+    requirements = {
+        "AGENTS.md": (
+            "### go-admin / go-admin-ui 精简与复用",
+            "最小可见、最小启用",
+            "隐藏只移除用户入口，不等于禁用",
+            "永久删除默认模块必须单独建立清理工单",
+            "新页面优先复用现有布局",
+            "不得引入与整体风格冲突的独立视觉体系",
+            "跨产品影响按协同工单处理",
+            "没有可见但不可用的失效入口",
+        ),
+        "Sense/AGENTS.md": (
+            "## go-admin / go-admin-ui 约束",
+            "菜单权限或路由开关隐藏",
+            "不能只隐藏菜单",
+            "新增组件前在工单中说明",
+            "同时影响 Bell 或共享基线时升级为协同工单",
+        ),
+        "Bell/AGENTS.md": (
+            "## go-admin / go-admin-ui 约束",
+            "菜单权限或路由开关隐藏",
+            "不能只隐藏菜单",
+            "新增组件前在工单中说明",
+            "同时影响 Sense 或共享基线时升级为协同工单",
+        ),
+    }
+    for relative_path, required in requirements.items():
+        path = root / relative_path
+        if not path.is_file():
+            errors.append(f"缺少 go-admin 规则文件：{relative_path}")
+            continue
+        content = path.read_text(encoding="utf-8")
+        for section in missing_sections(content, required):
+            errors.append(f"{relative_path} 缺少 go-admin 规则：{section}")
+
+
 def check_claude_code_entry(errors: list[str], root: Path = ROOT) -> None:
     """检查 Claude Code 入口直接复用共同 Agent 规则。"""
 
@@ -382,6 +422,7 @@ def main() -> int:
     check_core_documents(errors)
     check_task_template(errors)
     check_agent_efficiency_rules(errors)
+    check_go_admin_ui_rules(errors)
     check_claude_code_entry(errors)
     check_archives(errors)
 

docs/01-workflow.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Development-Workflow.-
-wiki_revision: 5bb7c174f711aa5655cb8c9b28afed7cfacd60d5
-synchronized_at: 2026-08-11T10:30:31Z
+wiki_revision: 44720127496ee08289db439268708d6314705faf
+synchronized_at: 2026-08-12T00:46:39Z
 <!-- gitea-wiki-mirror:end -->
 
 # 开发工作流
@@ -238,3 +238,22 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 | 测试结果与未验证内容 | 是 | 任务归档 | 镜像 |
 | 提交哈希 | 是 | 任务归档 | 镜像 |
 | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |
+
+## go-admin / go-admin-ui 开发约束
+
+Sense、Bell 使用 go-admin 和 go-admin-ui 时，采用以下统一流程：
+
+1. 先列出产品实际需要的菜单、路由、权限和接口，只呈现必要能力，框架演示页和无关管理模块不进入产品导航。
+2. 快速交付阶段优先使用配置、菜单权限或路由开关隐藏模块。隐藏只代表用户看不到入口；涉及权限或安全时，还必须禁用对应后端访问能力并验证直接请求不可用。
+3. 永久删除默认模块必须单独建立清理工单，核对代码依赖、数据库对象、权限记录、构建、框架升级和回退方式，不能混入普通业务页面工单。
+4. 新页面先盘点并复用已有布局、表格、表单、弹窗、上传、权限控制和请求封装。只有现有组件无法满足明确需求时才新增组件，并在工单记录复用缺口。
+5. 新组件沿用所属产品现有的颜色、字号、间距、状态反馈、交互方式、命名和目录结构，不建立独立于整体界面的视觉体系。
+6. 单页需求不得直接改变底层公共组件的全局行为。确需全局修改时单独建单，列出受影响页面、兼容方式和回归测试；同时影响 Sense、Bell 时按协同工单处理。
+
+验收至少检查：没有多余入口、没有可见但不可用的失效入口、没有重复实现已有组件，且新增页面与同类页面的视觉和交互一致。
+
+这里的三个处理级别必须明确区分：
+
+- 隐藏：保留代码与能力，只移除普通用户入口，便于快速交付和以后恢复。
+- 禁用：前端入口与后端访问能力均不可用，适用于权限、安全或明确停用的能力。
+- 删除：清理代码、依赖、数据对象和权限记录，风险较高，必须由独立清理工单实施。

docs/task/1-三项目并行建单与协同工单顺序.md

@@ -0,0 +1,82 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-1-三项目并行建单与协同工单顺序
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-1-%E4%B8%89%E9%A1%B9%E7%9B%AE%E5%B9%B6%E8%A1%8C%E5%BB%BA%E5%8D%95%E4%B8%8E%E5%8D%8F%E5%90%8C%E5%B7%A5%E5%8D%95%E9%A1%BA%E5%BA%8F.-
+wiki_revision: 8feb5cc67b3ebd30371250d4ffbd94d00176d347
+synchronized_at: 2026-08-12T00:37:09Z
+<!-- gitea-wiki-mirror:end -->
+
+# 1 三项目并行建单与协同工单顺序
+
+- 类型：需求
+- 所属 Epic：无
+- 所属 MVP / 版本：流程初始化
+- 状态：已完成
+- 日期：2026-08-12
+- 验收日期：2026-08-12
+- 验收结果：用户明确验收通过
+- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/1
+- Pull Request：https://git.ilapage.cn/ila/yovision/pulls/2
+- Wiki 页面：Task-1-三项目并行建单与协同工单顺序
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+客户交期紧，需要 Sense、Brain、Bell 三个项目尽量并行建立和实施独立工单。原规则已经限制各项目默认写路径，但没有固定“先三端独立建单、主 agent 汇总、再建协同工单”的顺序，任务模板也缺少主 agent、精确写路径和生产者/消费者等字段。
+
+本任务把该协作方式固化为仓库规则、Claude 路由、子项目规则、工单模板和 Wiki 长期文档，并增加自动化门禁防止后续回退。
+
+## 最终方案
+
+1. Sense、Brain、Bell 三个项目 agent 首轮并行只读分析并创建各自独立功能工单，每个工单只有一个主项目、一个主 agent 和不重叠的 `write_paths`。
+2. 三个项目 agent 只提交协同需求摘要，不在首轮取得 `contracts/`、根级共享文件或其他项目目录的写入权。
+3. 三端工单返回后，由主 agent / dispatcher 汇总、去重，检查依赖、写路径、事实源和验收闭环。
+4. 汇总完成后再创建契约、根级编排、机器鉴权和端到端验收等协同工单，并指定单一 coordination agent。
+5. 明确建单顺序不等于实施顺序；独立骨架可以先并行，依赖契约的实现必须等待契约版本冻结。
+6. `CLAUDE.md` 只保存 Claude 专用角色路由，共享流程仍以根 `AGENTS.md` 为事实来源。
+7. 任务模板增加任务类型、主项目、主 agent、`write_paths`、生产者、消费者、契约事实源、兼容策略、适配工单和集成顺序。
+8. Harness 严格检查上述关键字段与规则，并新增回归测试。
+
+与建单方案无差异；额外增加 Harness 对 Claude 三项目角色路由的检查，以确保规则不会静默丢失。
+
+## 修改文件
+
+- `AGENTS.md`：固定三项目并行建单和协同工单顺序。
+- `CLAUDE.md`：增加 Sense、Brain、Bell 与 coordination agent 路由。
+- `Sense/AGENTS.md`：定义 Sense 独立建单范围与协同升级条件。
+- `Brain/AGENTS.md`：定义 Brain 独立建单范围与协同升级条件。
+- `Bell/AGENTS.md`：定义 Bell 独立建单范围与协同升级条件。
+- `.gitea/issue_template/task.md`：增加单项目/协同任务必填字段。
+- `dev_scripts/check_harness.py`：增加协作规则和模板字段门禁。
+- `tests/test_harness_docs.py`：增加协同字段回归测试。
+- `docs/11-multi-agent-collaboration.md`：Wiki 长期文档镜像。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 根规则明确建单顺序、dispatcher 汇总责任和实施依赖原则 | 通过 |
+| Claude 入口明确三项目角色与 coordination agent 触发条件 | 通过 |
+| 三个子项目规则明确建单范围、写路径和协同升级条件 | 通过 |
+| 工单模板包含主 agent、写路径、生产者、消费者和兼容字段 | 通过 |
+| Wiki-first 更新并保持镜像一致 | 通过 |
+| 用户明确验收 | 通过（2026-08-12） |
+
+## 测试
+
+- 执行命令：`python dev_scripts/check_harness.py --strict`
+- 结果：通过。
+- 执行命令：`python -m unittest discover -s tests -v`
+- 结果：25 项测试全部通过。
+- 执行命令：`python -m compileall -q dev_scripts tests`
+- 结果：通过。
+- 执行命令：`python dev_scripts/sync_wiki_docs.py --check`
+- 结果：17 个 Wiki 映射全部一致。
+- 执行命令：`git diff --check`
+- 结果：通过。
+- **未验证部分**：尚未用三个真实产品开发 agent 完整演练首轮并行建单与后续协同建单；该演练属于下一阶段产品规划工作，不影响本次规则和模板验收。
+
+## 相关提交
+
+- `579b2ec` docs: define three-project issue planning order (#1)
+- `d5d0c04` Merge pull request 'docs: 规范三项目并行建单与协同工单顺序 (#1)' (#2)

tests/test_harness_docs.py

@@ -16,6 +16,7 @@ from check_harness import (  # noqa: E402
     check_claude_code_entry,
     check_core_documents,
     check_agent_efficiency_rules,
+    check_go_admin_ui_rules,
     check_task_template,
     core_mapping_errors,
     missing_sections,
@@ -185,6 +186,33 @@ class AgentRuleTests(unittest.TestCase):
         check_claude_code_entry(errors)
         self.assertEqual(errors, [])
 
+    def test_go_admin_ui_rules_are_present(self) -> None:
+        errors: list[str] = []
+        check_go_admin_ui_rules(errors)
+        self.assertEqual(errors, [])
+
+    def test_go_admin_ui_rules_require_each_scope(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "Sense").mkdir()
+            (root / "Bell").mkdir()
+            (root / "AGENTS.md").write_text("", encoding="utf-8")
+            (root / "Sense" / "AGENTS.md").write_text("", encoding="utf-8")
+            (root / "Bell" / "AGENTS.md").write_text("", encoding="utf-8")
+            errors: list[str] = []
+            check_go_admin_ui_rules(errors, root)
+        self.assertTrue(any(error.startswith("AGENTS.md ") for error in errors))
+        self.assertTrue(any(error.startswith("Sense/AGENTS.md ") for error in errors))
+        self.assertTrue(any(error.startswith("Bell/AGENTS.md ") for error in errors))
+
+    def test_go_admin_ui_rules_report_missing_scope_file(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            errors: list[str] = []
+            check_go_admin_ui_rules(errors, Path(directory))
+        self.assertIn("缺少 go-admin 规则文件：AGENTS.md", errors)
+        self.assertIn("缺少 go-admin 规则文件：Sense/AGENTS.md", errors)
+        self.assertIn("缺少 go-admin 规则文件：Bell/AGENTS.md", errors)
+
     def test_claude_code_entry_requires_exact_import_line(self) -> None:
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)

wiki-docs.json

@@ -4,22 +4,77 @@
   "owner": "ila",
   "repository": "yovision",
   "mappings": [
-    { "page": "Home", "path": "docs/README.md" },
-    { "page": "Project-Profile", "path": "docs/00-project-profile.md" },
-    { "page": "Development-Workflow", "path": "docs/01-workflow.md" },
-    { "page": "Architecture-and-Code-Map", "path": "docs/02-architecture-and-code-map.md" },
-    { "page": "Business-Rules-and-Glossary", "path": "docs/03-business-rules-and-glossary.md" },
-    { "page": "Local-Development-and-Verification", "path": "docs/04-local-development-and-verification.md" },
-    { "page": "Common-Changes", "path": "docs/05-common-changes.md" },
-    { "page": "Troubleshooting", "path": "docs/06-troubleshooting.md" },
-    { "page": "New-Project-Documentation-Setup", "path": "docs/07-new-project-documentation-setup.md" },
-    { "page": "Existing-Project-Adoption-Guide", "path": "docs/08-existing-project-adoption.md" },
-    { "page": "Product-Requirements", "path": "docs/09-product-requirements.md" },
-    { "page": "Requirements-Migration-Matrix", "path": "docs/10-requirements-migration-matrix.md" },
-    { "page": "Multi-Agent-Collaboration", "path": "docs/11-multi-agent-collaboration.md" },
-    { "page": "Product-Roadmap", "path": "docs/12-product-roadmap.md" },
-    { "page": "Delivery-Documentation-Guide", "path": "docs/delivery/README.md" },
-    { "page": "Audience-Document-Template", "path": "docs/delivery/audience-document-template.md" },
-    { "page": "Task-Archive-Template", "path": "docs/templates/task-archive.md" }
+    {
+      "page": "Home",
+      "path": "docs/README.md"
+    },
+    {
+      "page": "Project-Profile",
+      "path": "docs/00-project-profile.md"
+    },
+    {
+      "page": "Development-Workflow",
+      "path": "docs/01-workflow.md"
+    },
+    {
+      "page": "Architecture-and-Code-Map",
+      "path": "docs/02-architecture-and-code-map.md"
+    },
+    {
+      "page": "Business-Rules-and-Glossary",
+      "path": "docs/03-business-rules-and-glossary.md"
+    },
+    {
+      "page": "Local-Development-and-Verification",
+      "path": "docs/04-local-development-and-verification.md"
+    },
+    {
+      "page": "Common-Changes",
+      "path": "docs/05-common-changes.md"
+    },
+    {
+      "page": "Troubleshooting",
+      "path": "docs/06-troubleshooting.md"
+    },
+    {
+      "page": "New-Project-Documentation-Setup",
+      "path": "docs/07-new-project-documentation-setup.md"
+    },
+    {
+      "page": "Existing-Project-Adoption-Guide",
+      "path": "docs/08-existing-project-adoption.md"
+    },
+    {
+      "page": "Product-Requirements",
+      "path": "docs/09-product-requirements.md"
+    },
+    {
+      "page": "Requirements-Migration-Matrix",
+      "path": "docs/10-requirements-migration-matrix.md"
+    },
+    {
+      "page": "Multi-Agent-Collaboration",
+      "path": "docs/11-multi-agent-collaboration.md"
+    },
+    {
+      "page": "Product-Roadmap",
+      "path": "docs/12-product-roadmap.md"
+    },
+    {
+      "page": "Delivery-Documentation-Guide",
+      "path": "docs/delivery/README.md"
+    },
+    {
+      "page": "Audience-Document-Template",
+      "path": "docs/delivery/audience-document-template.md"
+    },
+    {
+      "page": "Task-Archive-Template",
+      "path": "docs/templates/task-archive.md"
+    },
+    {
+      "page": "Task-1-三项目并行建单与协同工单顺序",
+      "path": "docs/task/1-三项目并行建单与协同工单顺序.md"
+    }
   ]
 }