范智鹏
effcf30802
- 适配器 i18n 接入（eslint/pmd/sql-lint/stylelint） - Provider 动态注册机制（registry.ts + providers.json + factory 重构） - SetupView 全面重构（setupView.ts 新增 600+ 行） - i18n 消息扩展（messages.ts +210 行） - 规则导入流程优化（import-service / prompt-builder） - 新增 PMD jars 依赖及测试用例
117 lines
4.1 KiB
Markdown
117 lines
4.1 KiB
Markdown
# 规则导入转换器架构设计
|
||
|
||
## 1. 背景
|
||
|
||
当前 `src/views/setupView.ts` 的 `addRule()` 方法（~97 行）将所有文件类型的导入逻辑硬编码在一起：
|
||
|
||
- `.yaml/.yml`：直接复制
|
||
- `.md/.txt`：读取 → AI 转换 → 写入
|
||
|
||
每增加一种文件类型就得修改 `addRule()`，导致方法膨胀、可维护性下降。同时 AI 转换逻辑（system prompt、异常处理、清理）也与 UI 层耦合。
|
||
|
||
## 2. 目标
|
||
|
||
将文件导入逻辑从 UI 层解耦，设计统一的 **Converter 接口 + 注册机制**，使新增文件类型只需添加一个 converter 实现并注册。
|
||
|
||
## 3. 架构
|
||
|
||
```
|
||
setupView.ts (addRule)
|
||
│
|
||
▼
|
||
ImportService.convert(srcPath, yamlPath, context)
|
||
│
|
||
├── 查表: ext → RuleConverter
|
||
│
|
||
▼
|
||
RuleConverter (接口)
|
||
├── YamlConverter (直接复制)
|
||
├── MdConverter (AI 转换)
|
||
└── TxtConverter (AI 转换)
|
||
```
|
||
|
||
### 3.1 RuleConverter 接口
|
||
|
||
```typescript
|
||
// src/rules/converters/converter.ts
|
||
|
||
export interface RuleConverter {
|
||
supportedExtensions: string[];
|
||
convert(srcPath: string, yamlPath: string, context: vscode.ExtensionContext): Promise<boolean>;
|
||
}
|
||
```
|
||
|
||
- `supportedExtensions`：声明支持的扩展名列表（如 `['.yaml', '.yml']`）
|
||
- `convert()`：源文件 → 写 YAML 到 `yamlPath`，返回是否成功；失败时内部可弹错误提示
|
||
- 沿用 `LinterAdapter` 风格的接口约定
|
||
|
||
### 3.2 ImportService
|
||
|
||
```typescript
|
||
// src/rules/import-service.ts
|
||
|
||
class ImportService {
|
||
private converters: Map<string, RuleConverter> = new Map();
|
||
|
||
registerConverter(converter: RuleConverter): void;
|
||
convert(srcPath: string, yamlPath: string, context: vscode.ExtensionContext): Promise<boolean>;
|
||
}
|
||
```
|
||
|
||
- `registerConverter()` 遍历 converter 的 `supportedExtensions`，建立 ext → converter 映射
|
||
- `convert()` 根据 `path.extname(srcPath)` 查找 converter，找不到则返回 false 并弹错误
|
||
- 重复扩展名注册时后者覆盖前者（允许用户自定义覆盖）
|
||
|
||
### 3.3 各 Converter 职责
|
||
|
||
| Converter | 扩展名 | 行为 |
|
||
|-----------|--------|------|
|
||
| `YamlConverter` | `.yaml`, `.yml` | `fs.copyFileSync(srcPath, yamlPath)` |
|
||
| `MdConverter` | `.md` | 读文件 → AI 转换 → 写 YAML（逻辑从 `addRule()` 原样移入） |
|
||
| `TxtConverter` | `.txt` | 同上，共享 AI 转换逻辑 |
|
||
|
||
AI 转换逻辑（system prompt、API 调用、清理）提取到 `md-converter.ts` 和 `txt-converter.ts` 中，不再耦合 UI。
|
||
|
||
### 3.4 setupView.ts 变化
|
||
|
||
`addRule()` 缩减为：
|
||
|
||
```
|
||
1. showOpenDialog（弹窗选文件，保持不变）
|
||
2. 检查 yamlPath 是否已存在（保持不变）
|
||
3. 调用 ImportService.convert(srcPath, yamlPath, context)
|
||
4. refreshRules() 刷新列表（保持不变）
|
||
```
|
||
|
||
AI 转换、文件复制等细节从 `addRule()` 中删除。
|
||
|
||
## 4. 文件变更清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `src/rules/converters/converter.ts` | 新增 | RuleConverter 接口 |
|
||
| `src/rules/converters/yaml-converter.ts` | 新增 | .yaml/.yml 转换器 |
|
||
| `src/rules/converters/md-converter.ts` | 新增 | .md AI 转换器 |
|
||
| `src/rules/converters/txt-converter.ts` | 新增 | .txt AI 转换器 |
|
||
| `src/rules/import-service.ts` | 新增 | ImportService 类 |
|
||
| `src/views/setupView.ts` | 修改 | addRule() 简化，注册 converter |
|
||
| `src/extension.ts` | 无变更（setupView 自行注册 converters） |
|
||
|
||
## 5. 未来扩展（Phase 2 — Excel）
|
||
|
||
Converter 架构天然支持扩展。后续添加 Excel 只需：
|
||
|
||
1. 新增 `src/rules/converters/excel-converter.ts`
|
||
2. 实现 `RuleConverter` 接口（依赖 `xlsx` 库）
|
||
3. 在 `setupView.ts` 或 `extension.ts` 中 `registerConverter(new ExcelConverter())`
|
||
4. `showOpenDialog` 的 filter 中添加 `xlsx`
|
||
|
||
无需修改任何现有 converter 或 import-service 逻辑。
|
||
|
||
## 6. 不涉及变更
|
||
|
||
- 运行时规则加载（`yaml-parser.ts`）不变，仍只读 `.yaml/.yml`
|
||
- 文件选择弹窗的 filter 不变（仍为 yaml/yml/md/txt），等 Excel 阶段再扩展
|
||
- 规则命名逻辑（自动追加 `.yaml`）不变
|
||
- `getApiKey`、`createProvider` 等 AI 基础设施不变
|