From 2e22252feb6f92913b0a5919bca7edb7017f1ceb Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 12 Aug 2026 16:51:44 +0800 Subject: [PATCH] docs: document Sense product skeleton (#21) --- docs/00-project-profile.md | 10 +++++-- docs/02-architecture-and-code-map.md | 18 +++++++++++-- docs/04-local-development-and-verification.md | 26 +++++++++++++++++-- 3 files changed, 48 insertions(+), 6 deletions(-) diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 26e3d5c..7915e6e 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -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: 5561227400539f0a3ba7713be16c171feb811fcb -synchronized_at: 2026-08-12T01:26:47Z +wiki_revision: 3f5324fdcb32700a628b7434f1d7800e4bb0f64f +synchronized_at: 2026-08-12T08:50:45Z # 项目档案 @@ -92,3 +92,9 @@ Sense、Bell 共用的可复现技术基线记录在仓库根 `goadmin-baseline. 固定工具链为 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 的协同工单。 + + +## Sense 当前实现基线 + +Sense 已从冻结的 GoAdmin 基线初始化为独立产品：后端使用 Go 1.26.5 与 PostgreSQL，管理端使用 Node.js 22.22.1、pnpm 9.15.1、Vue 3.5.41、Element Plus 2.14.4 和 Vue CLI 5.0.9。产品代码只位于 `Sense/`，不依赖 Brain 或 Bell 启动；`D:\github\goadmin` 仍为只读参考。 + diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index c17bb8c..43f6cc7 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.- -wiki_revision: 04b5eaea579729e427f1b2b8962399e861d5eb53 -synchronized_at: 2026-08-11T10:30:34Z +wiki_revision: f16f2956d3d0f260501a356b5fe1087abdc5eaf5 +synchronized_at: 2026-08-12T08:50:52Z # 架构与代码地图 @@ -79,3 +79,17 @@ Sense/Brain 生成事件 - 业务预警与运维告警分开。 - Area/设备/规则在各独立产品内有自己的业务投影，不以共享数据库同步。 - 单项目工单不得顺带修改其他项目；共享契约变更必须由协调工单统筹。 + + +## Sense 代码入口与模块边界 + +- `Sense/server/main.go`：后端进程入口，调用 `cmd/sense` 启动。 +- `Sense/server/cmd/sense/root.go`：配置、数据库、迁移、模块注册和优雅退出编排；后续功能通过独立 `modules_.go` 注册，不反复修改共享入口。 +- `Sense/server/internal/platform/`：PostgreSQL、迁移、HTTP/JSON、健康检查与静态资源宿主。 +- `Sense/ui/src/bootstrap/`：Vue、路由、Vuex、请求封装和功能模块自动发现。 +- `Sense/ui/src/layout/AppLayout.vue`：基于 go-admin-ui 交互约定的侧栏、顶部导航、标签栏和页面容器。 +- `Sense/config/`：无秘密配置模板；真实数据库 URL 和后续签名密钥只能由仓库外环境提供。 +- `Sense/scripts/bootstrap/`：精确工具链检查和无需 Brain/Bell 的内存模式 smoke。 + +默认只注册工作台、健康检查和系统信息；go-admin 演示与代码生成菜单、路由和后端接口均未注册。正式启动默认要求独立 PostgreSQL；`memory` 只用于自动化测试和本地 smoke。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 74d471e..807f673 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -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: 1eb27d082ebf892343c9a5eed6f9363363234903 -synchronized_at: 2026-08-12T01:26:57Z +wiki_revision: 0a0354b0fed4c7edc68a1c6c887a0f2886e47541 +synchronized_at: 2026-08-12T08:50:58Z # 本地开发与验证 @@ -110,3 +110,25 @@ pnpm --version 截至 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` 为准。 + + +## Sense 本地构建与验证 + +使用根 `goadmin-baseline.json` 的精确版本。当前机器可用的隔离 Go 路径为开发机临时工具目录，不应写入部署配置。 + +```powershell +$env:PATH = 'C:\Users\ila20\AppData\Local\Temp\yovision-tools\go1.26.5\go\bin;' + $env:PATH +powershell -ExecutionPolicy Bypass -File .\Sense\scripts\bootstrap\check-toolchain.ps1 +cd Sense\server +go test ./... +go build ./... +cd ..\ui +corepack pnpm@9.15.1 install --frozen-lockfile +corepack pnpm@9.15.1 lint +corepack pnpm@9.15.1 build +cd ..\.. +powershell -ExecutionPolicy Bypass -File .\Sense\scripts\bootstrap\smoke.ps1 +``` + +正式后端启动必须设置 `SENSE_DATABASE_MODE=postgres` 和仓库外提供的 `SENSE_DATABASE_URL`。健康检查为 `GET /healthz`，就绪检查为 `GET /readyz`。本地 smoke 明确设置 `SENSE_DATABASE_MODE=memory`，不能代替 PostgreSQL 部署验证。 +