From 6ff12e6a27b3b3a67554a56c63d25143842ab595 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 12 Aug 2026 08:48:07 +0800 Subject: [PATCH] docs: define go-admin UI reuse rules (#3) --- AGENTS.md | 10 +++++++++ Bell/AGENTS.md | 8 +++++++ Sense/AGENTS.md | 8 +++++++ dev_scripts/check_harness.py | 41 ++++++++++++++++++++++++++++++++++++ docs/01-workflow.md | 23 ++++++++++++++++++-- tests/test_harness_docs.py | 28 ++++++++++++++++++++++++ 6 files changed, 116 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cf840ac..6311ae5 100644 --- a/AGENTS.md +++ b/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 并行推进时，固定使用以下顺序： diff --git a/Bell/AGENTS.md b/Bell/AGENTS.md index 284a424..8ce18f0 100644 --- a/Bell/AGENTS.md +++ b/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 或共享基线时升级为协同工单。 diff --git a/Sense/AGENTS.md b/Sense/AGENTS.md index 7f6efa4..347b8d2 100644 --- a/Sense/AGENTS.md +++ b/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 或共享基线时升级为协同工单。 diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index 1ca9b23..5031c02 100644 --- a/dev_scripts/check_harness.py +++ b/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) diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 6fd51b9..fc25f84 100644 --- a/docs/01-workflow.md +++ b/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 # 开发工作流 @@ -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 时按协同工单处理。 + +验收至少检查：没有多余入口、没有可见但不可用的失效入口、没有重复实现已有组件，且新增页面与同类页面的视觉和交互一致。 + +这里的三个处理级别必须明确区分： + +- 隐藏：保留代码与能力，只移除普通用户入口，便于快速交付和以后恢复。 +- 禁用：前端入口与后端访问能力均不可用，适用于权限、安全或明确停用的能力。 +- 删除：清理代码、依赖、数据对象和权限记录，风险较高，必须由独立清理工单实施。 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 2c2e0f9..c8ab0df 100644 --- a/tests/test_harness_docs.py +++ b/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) -- 2.34.1