# 开发规范

## 1. 技术栈
- **前端**：Vue 3 + Arco Design + TypeScript
- **后端**：Go + Wails
- **远程数据库**：MySQL（历史数据源）
- **本地存储**：SQLite（本地缓存）+ 文件存储（配置/离线数据包）

## 2. 代码风格
- 统一使用 UTF-8 编码
- 前端遵循 ESLint 规则
- Go 代码遵循 `gofmt` 格式化

## 3. 命名规范

### 3.1 Go 后端
- 类型/结构体：大驼峰 `XxxService`
- 方法/变量：小驼峰 `GetList()`
- 常量：全大写下划线 `DEFAULT_PAGE_SIZE`

### 3.2 前端
- 组件：大驼峰 `XxxList.vue`
- 方法/变量：小驼峰 `getList()`
- 常量：全大写下划线 `DEFAULT_PAGE_SIZE`

## 4. Wails 绑定规范
- Go 结构体导出方法供前端调用
- 方法参数不超过3个，超过时封装为结构体
- 方法名使用动词开头：`GetXxx`、`SaveXxx`、`DeleteXxx`

## 5. Arco Design 使用规范
- 优先使用 Arco 提供的组件和样式
- 避免过度自定义样式，保持主题兼容性
- 不使用 title 属性（如 `<a-card>`）
- 颜色规范：
  - 红球数字：`#F53F3F`（Arco 红色）
  - 蓝球数字：`#165DFF`（Arco 蓝色）
  - 未匹配数字：默认黑色

## 6. 代码质量要求
- 架构优良、性能良好、结构简单
- 方便维护，减少 AI 味
- 新增文件代码签名：`JueChen`

### 6.1 精准控制原则
- **精准定位问题**：找到问题的根本原因，而非到处添加防御性代码
- **精准设置样式**：只针对真正需要控制的元素设置样式，避免大量重复的 `overflow-x: hidden` 等防御性样式
- **可维护性优先**：代码改动时能明确知道哪个地方控制了什么，避免维护困难

### 6.2 主动性编程原则
- **主动解决问题**：找到问题的根源并修复，而不是用 `!important` 或大量覆盖样式来掩盖问题
- **主动思考设计**：考虑布局和样式设计的合理性，而非被动地添加防御性代码
- **主动优化代码**：定期审查代码，移除不必要的防御性代码，保持代码简洁

### 6.3 避免过度防御
- **不滥用 `!important`**：只在必要时使用，优先通过提高选择器优先级解决问题
- **不大量使用 `overflow-x: hidden`**：只在真正需要的地方使用，通常是 `body` 级别作为最后防线
- **不过度设置 `width: 100%`**：只在需要明确控制宽度的元素上设置
- **不重复设置相同样式**：避免在多个层级重复设置相同的样式属性

## 7. 版本控制
- Commit message：`<type>：<subject>`，使用中文
- 提交前自检（lint、功能测试）

---

> 文档维护者：JueChen  
> 创建时间：2026-01-07