qiuer-station README

这是一个为秋而框架提供一站式编程解决方案的 Visual Studio Code 扩展。

📣 您的声音对我们至关重要！

我们在不断进化，而您的反馈是最好的燃料。无论是发现了一个顽固的 Bug，还是脑海中闪现了一个天才般的改进想法，都请务必告诉我们！

💡 >> 点击这里，提交您的宝贵建议与反馈 <<

您的参与，将让 qiuer-station 变得更加卓越。

1. ✨ 功能特性

✅ Skill 助手：内置 Skill 功能，支持通过自然语言获取帮助和指导
✅ 语法高亮：基于语法规范的精确语法高亮显示
✅ 语法检查：实时语法检查，详细的错误报告和修复建议
✅ 代码格式化(试用)：智能代码格式化，支持丰富的自定义选项
✅ 多应用支持：支持多 Station-App 配置，每个应用独立配置和认证
✅ 功能点管理：通过侧边栏浏览、下载、上传和管理 QScript 功能点，支持搜索定位
✅ SQL脚本管理：支持 SQL 脚本的下载和管理
✅ 数据库管理：浏览数据库表结构，并支持直接执行 SQL 语句查看结果集
✅ 定时任务管理(仅浏览)：浏览定时任务(Quartz调度器)列表，查看作业和触发器详情
✅ HTTP连接管理(仅浏览)：浏览HTTP连接列表，查看连接详情和状态
✅ BPMN工作流(仅浏览)：支持 BPMN 工作流的下载和预览
✅ OpenAPI 接口定义(仅浏览)：支持 OpenAPI 3.0.0 文档的编辑和预览

2. 📋 要求

Visual Studio Code 1.75.0 或更高版本

3. 🚀 快速开始

3.1 🎯 打开 QScript 侧边栏

点击 VSCode 左侧活动栏中的 Q 图标，打开 QScript 扩展侧边栏。

3.2 ⚙️ 初始化项目配置

注意： 由于qiuer-station 3.x版本与2.x版本的目录结构不兼容，如果想使用qiuer-station 3.x版本的多app并存功能（推荐），则必须重新配置项目目录；若使用qiuer-station 3.x版本打开2.x版本的项目目录，插件将自动屏蔽多app并存功能。

首次使用时，需要配置服务器连接信息：

方式一：使用初始化向导（推荐）

在侧边栏顶部点击 初始化配置 按钮（齿轮图标）
或者打开命令面板（F1 或 Ctrl+Shift+P），输入 "初始化QScript设置"
按照向导步骤完成配置：
- 系统会检查当前项目是否为 Git 仓库，如果不是会提示是否初始化 Git
- 自动创建或更新 .gitignore 文件，确保密码不会被误提交
- 逐步引导您填写以下配置项：
  - 服务器主机名（默认：station.qiuer.net）
  - 服务器端口（默认：443）
  - 服务器类型（station 或 frame，默认：station）
  - Station-App（服务器类型 station 必填，frame 可选）
  - 用户代码
  - 用户密码
- 配置将自动保存到项目的 .vscode/settings.json 文件中
完成后可选择是否重新加载窗口以应用新设置

注意：使用此方式配置后，.vscode/settings.json 会被自动添加到 .gitignore，确保您的密码等敏感信息不会被提交到 Git 仓库。

方式二：手动配置

您也可以在 VS Code 设置中手动配置以下选项：

qiuer.server_list[].hostname：QScript 服务器主机名
qiuer.server_list[].port：QScript 服务器端口
qiuer.server_list[].type：QScript 服务器类型
qiuer.server_list[].usercode：用户代码用于身份验证
qiuer.server_list[].password：密码用于身份验证

3.3 🎬 开始使用

配置完成后，侧边栏会显示以下功能模块，点击即可展开使用：

📁 功能点管理：浏览、下载、上传 QScript 功能点
📊 BPMN工作流(仅浏览)：管理 BPMN 工作流文件
🗄️ SQL脚本管理：管理 SQL 脚本
🗄️ 数据库管理：浏览表结构及执行 SQL 语句
🖥️ 工作台管理：管理工作台配置

4. 🏗️ 多 Station-App 支持

扩展支持在同一项目中管理多个 Station-App，每个应用可以拥有独立的配置文件和认证信息。

4.1 📂 项目目录结构

v3.x 版本相比 v2.x 增加了多应用支持，目录结构如下：

project-root/
├── .gitignore                          # 忽略敏感配置文件
├── .vscode/
│   └── settings.json                   # 工作区全局配置
├── <station|frame_app>/                # 应用目录（如：app001、app002）
│   ├── .qiuer.config.json              # 应用级独立配置
│   ├── function/                       # 功能点目录
│   │   └── <funcid>/                   # 功能点ID目录（如：1001）
│   │       └── method/                 # 方法目录
│   │           └── <methid>/           # 方法ID目录（如：1）
│   │               ├── main_<funcid>_<methid>.qs    # QScript主代码
│   │               ├── comm_<funcid>_<methid>.md    # 功能点文档
│   │               ├── meta_<funcid>_<methid>.json  # 元数据
│   │               └── schema_<funcid>_<methid>.json # OpenAPI接口定义
│   ├── sql/                            # SQL脚本管理目录
│   │   └── <sqlid>/                    # SQL ID目录
│   │       ├── sentence_<sqlid>.sql    # SQL语句文件
│   │       └── meta_<sqlid>.json       # SQL元数据
│   ├── process/                        # BPMN工作流目录
│   │   └── <bizkey>/                   # 业务流程键目录
│   │       ├── bpmn_<bizkey>.bpmn      # BPMN流程文件
│   │       └── meta_<bizkey>.json      # BPMN元数据
├── <station|frame_app>/                # 其他应用（可选）
│   └── ...                             # 结构同上
└── <station|frame_app>/                # 其他应用（可选）
│   └── ...                             # 结构同上

目录结构说明：

应用隔离：每个应用拥有独立的目录和 .qiuer.config.json 配置文件
功能点：存储在 function/<funcid>/method/<methid>/ 路径下，包含代码、文档、元数据和 OpenAPI 接口定义
SQL脚本：存储在 sql/<sqlid>/ 路径下，包含SQL语句和元数据
BPMN流程：存储在 process/<bizkey>/ 路径下，包含流程定义和元数据
工作台：存储在 desk/<deskid>/ 路径下，包含工作台配置
向后兼容：支持根目录下直接放置 function/、sql/ 等目录（v2.x格式）

5. ⚙️ 配置选项

5.1 🖥️ 分屏显示配置

qiuer.enableSplitView：是否启用分屏功能（默认：true）
- 当设置为 true 时，打开功能点、编辑文档、编辑元数据、测试功能点等操作会自动在分屏中显示相关内容
- 当设置为 false 时，所有文件将在当前编辑器中直接打开，不会自动分屏
- 分屏功能包括：
  - BPMN流程文件：左侧显示BPMN源码，右侧显示图形化预览
  - 编辑文档：左侧显示Markdown编辑器，右侧显示Markdown预览
  - 编辑元数据：左侧显示元数据JSON编辑器，右侧显示文档预览
  - 编辑接口定义：左侧显示OpenAPI JSON编辑器，右侧显示接口文档预览
  - 测试功能点：左侧显示测试面板，右侧显示文档预览

5.2 🎨 代码格式化配置

注意：由于存在多种不同的代码格式化风格，请谨慎使用该功能

qiuer.formatter.indentSize：每个缩进级别的空格数（默认：2）
qiuer.formatter.preserveEmptyLines：是否保留多个空行（默认：true）
qiuer.formatter.statement.newLineBegin：每个语句是否从新行开始（默认：true）
qiuer.formatter.statement.keywordNewLine：语句中的关键字之间是否换行（默认：false，设为 true 时 if/then/else、set、for/loop 等关键字会各占一行）
qiuer.formatter.object.expandSingleProperty：单属性对象是否展开为多行（默认：false）
qiuer.formatter.array.expandSingleElement：单元素数组是否展开为多行（默认：false）
qiuer.formatter.maxLineLength：尝试换行前的最大行长度（默认：80）
qiuer.formatter.continuationIndent：续行缩进倍数（相对于 indentSize，默认：2）
qiuer.formatter.sql.preserveFormatting：是否保留 SQL 块的原始格式（默认：true）
qiuer.formatter.case.alignColons：switch case 语句中是否对齐冒号（默认：false）
qiuer.formatter.comma.trailingComma：多行结构中是否保留尾随逗号（never 或 always，默认：never）

6. 📖 主要功能使用指南

6.1 🔍 语法检查

打开 QScript 文件后，语法错误会在编辑器中以波浪线标注，鼠标悬停可查看详细错误信息和修复建议。

6.2 💅 代码格式化

在 QScript 文件中右键选择 "格式化文档"，或使用快捷键 Shift+Alt+F（Windows）/ Shift+Option+F（macOS）。

6.3 📦 功能点管理

6.3.1 ⬇️ 下载全部功能点

点击侧边栏 Q 图标打开 QScript 面板
在 "功能点管理" 模块中，点击顶部的 下载全部 按钮（下载图标）
系统将获取全部功能点代码保存到本地文件夹中
如果尚未登录，系统会提示您输入凭据

6.3.2 🔎 浏览和下载特定功能点

在侧边栏 "功能点管理" 模块中浏览功能点列表
点击具体的功能点展开，可以看到该功能点的方法列表
点击方法旁的下载按钮
文件将被下载到本地并自动在编辑器中打开

6.3.3 ⬆️ 上传并激活功能点

在编辑器中打开要上传的 QScript 文件
点击编辑器右上角的上传按钮（上传图标）
或在侧边栏功能点列表中，右键点击对应的方法，选择 "上传"
如果代码有语法错误，系统会提示修复后再上传
上传成功后，系统会显示激活结果

6.3.4 🧪 测试功能点

在编辑器中打开要测试的 QScript 文件
点击编辑器右上角的测试按钮（火箭图标）
或在侧边栏功能点列表中，右键点击对应的方法，选择 "测试"
根据屏幕提示，修改认证方式、HTTP方法等请求参数
HTTP请求发送成功后会显示测试结果

6.3.5 📖 编辑接口定义 (OpenAPI)

在编辑器中打开 QScript 文件，点击编辑器右上角的 编辑接口定义 按钮（地球图标）
或在侧边栏功能点列表中，点击方法旁的 编辑接口定义 按钮
如果本地没有 OpenAPI 文件，系统会自动从服务器下载
分屏显示：左侧为 OpenAPI JSON 源码编辑器，右侧为接口文档预览
编辑完成后，保存 JSON 文件即可

6.4 🔄 BPMN工作流管理(仅浏览)

在侧边栏展开 "BPMN 工作流" 模块
浏览工作流列表
点击下载按钮下载工作流文件
支持预览 BPMN 图形界面

6.5 🗃️ SQL脚本管理

在侧边栏展开 "SQL 管理" 模块
浏览 SQL 脚本列表
点击下载按钮下载 SQL 文件到本地
点击 SQL 脚本旁的 编辑元数据 按钮，打开 SQL 元数据编辑面板
在元数据面板中可以：
- 查看 SQL 的基本信息（数据库类型、执行类型、结果类型、状态等）
- 编辑参数列表（名称、类型、值、方向、可为空、为列表）
- 查看列定义信息
- 使用 撤销/重做 功能（支持快捷键 Ctrl+Z / Ctrl+Y）
- 编辑完成后点击保存按钮（或按 Ctrl+S）保存修改

6.6 🗄️ 数据库管理与 SQL 执行

在侧边栏展开 数据库管理 模块
浏览数据库、Schema 及表列表
点击具体的表名，打开表结构查看面板
在左侧 SQL 输入 区域输入 SQL 语句（例如：SELECT * FROM table_name LIMIT 10）
点击 执行 SQL 按钮，执行结果将以表格形式展示在下方

🤝 参与贡献与支持

如果您觉得这个扩展对您有所帮助，欢迎：

💬 点击反馈您的意见和建议
🚀 将它推荐给更多正在使用秋而框架的伙伴们

祝您使用愉快，开发顺利！

qiuer-station

davinwang