Merge branch 'dev'

Author: windbytes

.cursor/rules/core.mdc

@@ -0,0 +1,13 @@
+---
+description: syndra-admin 全局工程约定（工具链、仓库边界、协作）
+alwaysApply: true
+---
+
+# syndra-admin 核心约定
+
+- **定位**：Syndra 管理后台 SPA，配套后端仓库为 **syndra**（独立仓库）；改接口路径时须与后端 Controller 保持一致。
+- **运行时**：Node ≥ 22.12（见 `package.json` engines）；包管理器与锁文件以仓库已有为准，勿混用。
+- **格式化与 Lint**：以 **Biome** 为准（`biome.json`）。提交前执行 `npm run check` 或 `npm run check:fix`；风格冲突时服从 Biome，不手写与 Biome 矛盾的规范。
+- **构建**：Vite 8 + TypeScript project references（`npm run build`）；开发 `npm run dev`。
+- **变更原则**：最小必要改动；不无关重构；与用户可见文案、权限、路由变更同步考虑 i18n 与路由配置。
+- **安全**：不在前端硬编码密钥；敏感配置走环境变量；请求经统一封装（如 `HttpRequest`），错误信息对用户友好、对日志可诊断。

.cursor/rules/react.mdc

@@ -0,0 +1,14 @@
+---
+description: TypeScript + React 19 组件、数据获取与状态（对齐本仓库依赖）
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# TypeScript / React
+
+- **栈**：React 19、Vite 8、**react-router**（v7，RouterProvider 模式）、**@tanstack/react-query**、**zustand**、**ahooks**；路由与数据请求优先用上述库而非自造轮子。
+- **类型**：导出组件 props 与公共 API 显式标注；避免滥用 `any`（Biome 对 `any` 为 warn）；`import type` 用于仅类型导入。
+- **组件**：函数组件；可复用逻辑抽到 **hooks** 或小组件；与现有 `views/**` 目录结构一致（页面、hooks、components 分层）。
+- **性能**：非关键路径用 `React.lazy` / 动态 import；列表注意 key 稳定；谨慎使用 `useEffect`，优先事件驱动与 Query 缓存。
+- **错误边界**：关键路由可使用 `react-error-boundary` 等既有模式，避免静默吞错。
+- **请求**：API 路径、方法必须与后端一致；在 `src/services/**` 集中定义，注释中标注对应 Controller（参考现有 `engine`、`system` 服务写法）。

.cursor/rules/typescript-react.mdc

@@ -0,0 +1,14 @@
+---
+description: Ant Design 6、Tailwind 4 与可访问性
+globs: "**/*.{tsx,css,scss}"
+alwaysApply: false
+---
+
+# UI / 样式
+
+- **组件库**：**Ant Design v6**（`antd`）；优先使用官方布局、表单、表格、Modal 等，保持后台一致视觉与交互。
+- **样式**：**Tailwind CSS v4** + 必要时 CSS；类名合并可用 `tailwind-merge`、`clsx`（与现有一致）。
+- **图标**：`@ant-design/icons`、**unplugin-icons**（Iconify）；优先本地化图标配置，避免无端增大包体。
+- **国际化**：`i18next` / `react-i18next`；用户可见字符串走词条，勿硬编码中文（除非产品明确要求仅中文）。
+- **a11y**：Biome a11y 规则已部分开启；交互组件需键盘可操作、合理 `aria-*`；勿用 div 冒充 button。
+- **图表 / 编辑器**：ECharts、Monaco、**@xyflow/react** 等按现有模块模式扩展，注意懒加载与大包体拆分。

.cursor/rules/ui-antd-tailwind.mdc

@@ -0,0 +1,27 @@
+---
+name: syndra-admin-feature-workflow
+description: 在 syndra-admin 中实现或修改功能页面、服务层与路由，并与 syndra 后端 API 对齐。适用于新增/改版 views、hooks、services、权限与接口联调。
+---
+
+# syndra-admin 功能开发工作流
+
+## 开始前
+
+1. 确认需求涉及的 **后端路径与方法**（对照 syndra 仓库对应 `*Controller`）。
+2. 在 `src/services/**` 查找是否已有 API 封装；优先扩展而非重复新建客户端。
+
+## 推荐步骤
+
+1. **服务层**：在对应 `api.ts` 中增加常量路径与类型安全的请求函数；注释写明后端 Controller 与映射关系（与现有 engine/system 模块一致）。
+2. **类型**：DTO 与列表项类型放在模块 `types.ts` 或并列类型文件，与后端字段名一致，避免前端私自改名。
+3. **数据获取**：列表/详情用 **TanStack Query**（`useQuery` / `useMutation`），缓存 key 包含业务主键与查询参数摘要。
+4. **页面结构**：在 `src/views/` 下按领域建目录：`index.tsx`、 `hooks/`、`components/`、`constants.ts` 等与现有一致。
+5. **权限**：沿用项目内权限 hook / 常量模式（参考同模块其它页面）。
+6. **路由**：在 React Router 路由树中注册（RouterProvider 模式），保持 lazy 与布局嵌套与现有约定一致。
+
+## 自检
+
+- [ ] `npm run check` 无 error
+- [ ] 新增 API 与后端路径、HTTP 方法一致
+- [ ] 加载/错误/空状态有明确 UI 或 message
+- [ ] 无敏感信息进仓库

.cursor/skills/syndra-admin-feature-workflow/SKILL.md

@@ -0,0 +1,7 @@
+node_modules
+dist
+.git
+.gitignore
+.cursor
+.vscode
+*.log

.dockerignore

@@ -0,0 +1,7 @@
+VITE_DEV_SERVER_PORT=8000
+VITE_API_PROXY_TARGET=http://localhost:9527
+# Netty WebSocket 端口（与后端 application.yml websocket.netty.port 一致；/api/ws 会 rewrite 到 /ws）
+VITE_WS_PROXY_TARGET=http://localhost:8891
+# 通过前端开发服务器：/api/ws 由 vite 转发到 Netty，其余 /api 仍走 Spring
+VITE_WS_URL=ws://localhost:8000/api/ws/syndra
+VITE_ENABLE_MONITOR_CONSOLE=true

.env.development

@@ -0,0 +1,8 @@
+VITE_DEV_SERVER_PORT=8000
+# 统一走网关（9527）
+VITE_API_PROXY_TARGET=http://localhost:9527
+# Netty WebSocket（默认 8891，与后端 websocket.netty.port 一致）
+VITE_WS_PROXY_TARGET=http://localhost:8891
+# 开发环境：WS 走 dev server 的 /api/ws，由 vite 转发到 Netty（去掉 /api 前缀）
+VITE_WS_URL=ws://localhost:8000/api/ws/syndra
+VITE_ENABLE_MONITOR_CONSOLE=true

.env.example

@@ -0,0 +1,4 @@
+# 生产环境示例：请替换为你的网关域名。
+# WebSocket 由 Netty 提供（路径无 /api）；网关需将 /api/ws 转发到 Netty 的 /ws 并指向 websocket 端口。
+VITE_WS_URL=wss://your-gateway-domain/api/ws/syndra
+VITE_ENABLE_MONITOR_CONSOLE=true

.env.production

@@ -38,13 +38,13 @@ jobs:
           echo "${{ secrets.ALIYUN_PRIVATE_KEY }}" | tr -d '\r' > private_key.pem
           chmod 600 private_key.pem
           # 清空目标目录
-          ssh -i private_key.pem $USERNAME@$HOST "rm -rf /work/nexus/*"
+          ssh -i private_key.pem $USERNAME@$HOST "rm -rf /home/syndra/web/*"
           # 压缩并上传 当使用 -C dist 时，这里 -C dist . 表示只压缩 dist 文件夹内部的文件，并没有外层 dist 目录
           # tar -zcvf dist.tar.gz -C dist . 表示压缩 dist 文件夹内部的文件，并没有外层 dist 目录
           tar -zcvf dist.tar.gz dist
-          scp -i private_key.pem -C -r dist.tar.gz $USERNAME@$HOST:/work/nexus
+          scp -i private_key.pem -C -r dist.tar.gz $USERNAME@$HOST:/home/syndra/web
           # 解压并替换目标目录 --strip-components=1  表示解压后删除第一层目录（dist）
-          ssh -i private_key.pem $USERNAME@$HOST "tar -zxvf /work/nexus/dist.tar.gz --strip-components=1 -C /work/nexus"
-          ssh -i private_key.pem $USERNAME@$HOST "rm -rf /work/nexus/dist.tar.gz"
+          ssh -i private_key.pem $USERNAME@$HOST "tar -zxvf /home/syndra/web/dist.tar.gz --strip-components=1 -C /home/syndra/web"
+          ssh -i private_key.pem $USERNAME@$HOST "rm -rf /home/syndra/web/dist.tar.gz"
           ssh -i private_key.pem $USERNAME@$HOST "sudo systemctl reload nginx"
           rm private_key.pem