safesight-control/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build, Test & Restart Commands

• Build: go build -o managerd ./cmd/managerd 或 pwsh -File scripts/managerd.ps1 build
• Run: ./managerd (uses managerd.json config) or ./managerd <config-path>
• 重启服务（编译+启停+健康检查一站式）：pwsh -File scripts/managerd.ps1 restart
• 查看服务状态：pwsh -File scripts/managerd.ps1 status
• Test all: go test ./...
• Test single package: go test ./internal/service/...
• Test single test: go test ./internal/storage/... -run TestAssetsRepo_SaveTemplate
• Verbose test: go test ./internal/web/... -v -run TestUI_ActionDevicesBatchAction

Codebase Architecture

Layered Structure (no DI framework — manual wiring in main.go)

cmd/managerd/main.go     — Composition root: builds config, services, storage, router
internal/api/            — Thin HTTP handlers that delegate to services (chi router, no framework)
internal/web/            — Embedded HTML UI (Go html/template + layout.html pattern)
internal/service/        — Business logic (discovery, registry, tasks, config assets, preview rendering, template slots)
internal/storage/        — SQLite persistence (raw SQL via database/sql, pure-Go modernc.org/sqlite driver)
internal/config/         — JSON config file loading (managerd.json)
internal/models/         — Core domain types (Device, Task, DeviceTaskStatus, etc.)
templates/               — Local JSON template files loaded at runtime
templates/standard_templates/ — "Standard" templates (std_ prefix) imported into SQLite on startup

Dependency Flow (all wired in main.go)

config → service (agent client, registry, discovery)
config + service → storage (opens SQLite, creates repos)
storage → service (task service, config preview, etc.)
service + storage → api + web (HTTP handlers)
chi.Router → mounts api routes + UI

Device Communication

• AgentClient proxies HTTP requests to device-side rk3588-agent via the device's IP/port.
• Two timeout tiers: 3s for normal requests, 120s for long operations (config apply, media server, model uploads).
• All proxied requests carry X-RK-Token header from config.
• Generic passthrough: r.Handle("/devices/{id}/v1/*", proxyAgentV1) covers agent sub-routes.

Config Asset Management

The system manages four asset types stored as JSON blobs in SQLite:

Asset	Table	Key Concept
Templates	templates	Base config template with bindings/variables
Profiles	profiles	Template-specific configuration (references primary_template_name)
Overlays	overlays	Named config overrides that can be appended to any profile
Integration Services	integration_services	Third-party service definitions (e.g., RTMP, HTTP push)
Video Sources	video_sources	Camera/stream source definitions

Naming convention: names starting with std_ are read-only standard templates, imported on startup from templates/standard_templates/.

The config preview rendering pipeline: merge template + profile + overlays → resolve binding references (video sources, integration services) → expand slot tokens (${slot:name.field}) → compute SHA256 hash.

Background Goroutines

• RegistryService: 2s tick for offline pruning, 30s tick for graph polling
• DiscoveryService: UDP broadcast listener (blocking goroutine per discovery request)
• TaskService: concurrent task execution gated by a semaphore channel

Key Database Tables (SQLite, migrations in storage/migrate.go)

• devices — device registry (device_id PK, ip, port, online status, last_seen)
• templates, profiles, overlays — config assets
• integration_services, video_sources — third-party service and video source definitions
• tasks + task_devices — batch task execution (type, status, per-device status)
• device_config_state — per-device applied config state
• audit_logs — action audit trail (actor, action, target, details)

Test Patterns

• Test files co-located with source: *_test.go
• Services constructed with nil/real dependencies (no mocking framework)
• HTTP tests use httptest.NewRequest + httptest.NewRecorder
• Storage tests use in-memory SQLite (tests seed their own data via repo methods)
• Tests assert on status codes, redirect URLs, and response body content

Coding Rules

• Never use sed on Windows (Git Bash). It produces stray t characters, broken indentation, and corrupted files.
• Use rg and fd for searching (not grep/find). Both are installed.
• File editing: use the write tool for new/rewritten files and edit tool for precise changes. For complex find-and-replace, write a small temporary Go program.
• No tabs: use spaces for indentation in all source files.
• No fetch() in templates for page data — all API calls must go through Go server-side handlers. JS is only for UI interactivity (modals, carousels, confirm dialogs).
• No inline onclick with complex quoting — use data-* attributes + event delegation instead.
• Use pwsh for PowerShell commands (v7.6.1 in PATH, not powershell.exe).
• 重启服务：统一用 pwsh -File scripts/managerd.ps1 restart，它会先编译、停旧进程、再启动新进程并做健康检查。不要手动 kill + build + start。
• 如无必要，不使用数据库事务：SQLite 只允许一个写者，事务会阻塞所有其他写操作。单个 Exec 已是原子操作，绝大多数场景不需要包裹事务。仅模板重命名等必须原子完成的多步操作才用事务。
• 调试时只加日志，不改代码：遇到 bug 先用 fmt.Printf 全量打印关键路径的状态和数据流，定位根因后再动手修。不要猜测、不要加 workaround（重试、超时、锁之类）。

测试设备

• RK3588: orangepi@10.0.0.81 / password: orangepi / key: ~/.ssh/id_ed25519_rk3588
• Agent:9100 / Media:9000 / Token:4fe2d69fda23d0d5d04a1486d4920e68
• 详细命令参考 docs/test-devices.md