整体架构

                         ┌─────────────────────────────────────┐
                         │         contracts/                  │
                         │  openapi/rbac-api.yaml + sql/       │
                         └──────────────┬──────────────────────┘
                                        │ 契约对齐
              ┌─────────────────────────┼─────────────────────────┐
              ▼                         ▼                         ▼
     packages/server-java        packages/server-python      packages/shared/*
     Spring Boot 单体 :8080       FastAPI :8000/8080          types/api-client/auth/admin
              │                         │                         │
     packages/micro-java                │                         │
     Gateway :8080 → micro              │                         │
              │                         │                         │
              └─────────────┬───────────┘                         │
                            │ HTTP /api/v1                        │ workspace 链接
                            ▼                                     ▼
              ┌─────────────────────────────────────────────────────────┐
              │  web (Vue)  │  desktop (Electron·产品)  │  mobile      │
              └───────────────┬─────────────────────────────────────────┘
                              │ Desktop 可选：业务内嵌仪器页
                              ▼
                    packages/device-agent (C# :19721)
                    Stage / SampleFlow / 插件驱动
                              ▲
                              │ 直连（无 admin / 无业务后端）
              packages/instrument-devtool (Electron·调试框架)
                    + @xichen-full-stack/instrument

设计原则

1. 契约优先：API 与表结构以 contracts/ 为准，多后端对照实现
2. 前端与后端语言解耦：通过 @xichen-full-stack/api-client 统一 HTTP
3. 管理端复用：Web 与 Desktop 共用 @xichen-full-stack/admin
4. 权限双保险：前端按钮隐藏 + 后端接口鉴权
5. 设备控制本地化：实时命令走本机 C# device-agent；RBAC 仍走 Java/Python
6. 产品与调试分离：desktop 做硬件操作产品壳；instrument-devtool 做无后端依赖的联调台
7. Java 双实现：server-java（单体）与 micro-java（微服务，Gateway 仍 :8080）

分层说明

层	目录	职责
契约	contracts/	OpenAPI、SQL schema
后端	packages/server-java、server-python、micro-java	REST API、JWT、RBAC
共享	packages/shared/*	类型、HTTP、权限、Admin UI、instrument 客户端
应用	packages/web、desktop、mobile	各端入口与差异化配置
调试工具	packages/instrument-devtool	硬件联调 Electron 壳（不依赖 admin/后端）
本地 Agent	packages/device-agent	C# 仪器设备驱动（产品与调试共用）
基础设施	docker-compose.yml	MySQL 8

数据模型（RBAC）

User ──(sys_user_role)──> Role ──(sys_role_permission)──> Permission
Menu.permission 字段与 Permission.code 对齐，用于前端菜单与按钮

相关文档

• Monorepo 协作
• RBAC 请求链路
• 包职责对照
• instrument-devtool
• device-agent
• micro-java 微服务