.
This commit is contained in:
68
docs/01-规范/01-开发规范.md
Normal file
68
docs/01-规范/01-开发规范.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# 开发规范
|
||||
|
||||
## 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
|
||||
53
docs/01-规范/02-接口规范.md
Normal file
53
docs/01-规范/02-接口规范.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Wails 绑定规范
|
||||
|
||||
## 1. 概述
|
||||
Wails 通过 context 绑定 Go 方法供前端调用，无需 HTTP API。
|
||||
|
||||
## 2. Go 后端绑定
|
||||
|
||||
### 2.1 结构体定义
|
||||
```go
|
||||
type App struct {
|
||||
ctx context.Context
|
||||
}
|
||||
|
||||
func NewApp() *App {
|
||||
return &App{}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 方法绑定
|
||||
- 导出方法（首字母大写）自动绑定
|
||||
- 方法参数不超过3个，超过时使用结构体
|
||||
- 返回错误统一使用 `error` 类型
|
||||
|
||||
### 2.3 命名规范
|
||||
- 查询：`GetXxx()`、`ListXxx()`
|
||||
- 新增：`CreateXxx()`、`SaveXxx()`
|
||||
- 更新：`UpdateXxx()`
|
||||
- 删除：`DeleteXxx()`
|
||||
|
||||
## 3. 前端调用
|
||||
|
||||
### 3.1 调用方式
|
||||
```typescript
|
||||
// 导入绑定的方法
|
||||
import { GetXxx, SaveXxx } from '@/wailsjs/go/main/App'
|
||||
|
||||
// 调用
|
||||
const data = await GetXxx()
|
||||
```
|
||||
|
||||
### 3.2 错误处理
|
||||
- 统一使用 try-catch 处理
|
||||
- 错误信息展示给用户
|
||||
|
||||
## 4. 参数规范
|
||||
- 简单参数直接传递
|
||||
- 复杂参数使用结构体/对象
|
||||
- 字段命名使用小驼峰
|
||||
|
||||
---
|
||||
|
||||
> 文档维护者：JueChen
|
||||
> 创建时间：2026-01-07
|
||||
88
docs/01-规范/03-数据库规范.md
Normal file
88
docs/01-规范/03-数据库规范.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 数据存储规范
|
||||
|
||||
## 1. 存储架构
|
||||
|
||||
### 1.1 远程数据库（MySQL）
|
||||
- **用途**：完整历史数据源
|
||||
- **地址**：39.99.243.191:3306
|
||||
- **账号**：u_ssq
|
||||
- **密码**：u_ssq@260106
|
||||
- **连接方式**：需要时连接，支持离线模式
|
||||
|
||||
### 1.2 本地数据库（SQLite）
|
||||
- **用途**：本地数据缓存、离线查询支持
|
||||
- **位置**：应用数据目录
|
||||
- **同步策略**：增量同步，定期更新
|
||||
|
||||
### 1.3 文件存储
|
||||
- **配置文件**：应用配置、用户偏好
|
||||
- **离线数据包**：完整历史数据导出/导入
|
||||
- **缓存文件**：临时数据
|
||||
|
||||
### 1.4 前端存储
|
||||
- **LocalStorage**：临时数据、用户偏好、UI 状态
|
||||
|
||||
## 2. 数据库设计规范
|
||||
|
||||
### 2.1 表名规范
|
||||
- 小写字母，单词间下划线：`ssq_history`、`query_cache`
|
||||
|
||||
### 2.2 字段规范
|
||||
- 小写字母，单词间下划线：`issue_number`、`red_ball_1`、`created_at`
|
||||
- 主键统一使用 `id`（INT 或 BIGINT）
|
||||
- 时间字段：`created_at`、`updated_at`（DATETIME）
|
||||
|
||||
### 2.3 数据类型规范
|
||||
- **期号**：`VARCHAR(20)`，如 "2025145"
|
||||
- **球号**：`TINYINT`，范围 1-33（红球）或 1-16（蓝球）
|
||||
- **日期**：`DATE` 或 `DATETIME`
|
||||
|
||||
### 2.4 索引规范
|
||||
- 主键索引：`PRIMARY KEY (id)`
|
||||
- 查询索引：`INDEX idx_issue_number (issue_number)`
|
||||
- 日期索引：`INDEX idx_open_date (open_date)`
|
||||
|
||||
## 3. 数据同步规范
|
||||
|
||||
### 3.1 同步策略
|
||||
- **增量同步**：基于 `id` 或 `issue_number` 增量更新
|
||||
- **全量同步**：首次安装或数据修复
|
||||
- **同步时机**：应用启动检查、手动触发、定时任务
|
||||
|
||||
### 3.2 数据校验
|
||||
- 期号唯一性校验
|
||||
- 球号范围校验（红球 1-33，蓝球 1-16）
|
||||
- 数据完整性校验
|
||||
|
||||
### 3.3 错误处理
|
||||
- 网络错误：使用本地缓存
|
||||
- 数据冲突：以远程为准或用户选择
|
||||
- 同步失败：记录日志，下次重试
|
||||
|
||||
## 4. Go 结构体映射
|
||||
|
||||
### 4.1 ORM 工具
|
||||
- 使用 `gorm` 进行 ORM 映射
|
||||
- MySQL 和 SQLite 使用相同模型结构
|
||||
|
||||
### 4.2 结构体规范
|
||||
```go
|
||||
type SsqHistory struct {
|
||||
ID int `gorm:"primaryKey" json:"id"`
|
||||
IssueNumber string `gorm:"type:varchar(20);not null;index" json:"issue_number"`
|
||||
OpenDate *time.Time `gorm:"type:date" json:"open_date"`
|
||||
RedBall1 int `gorm:"type:tinyint;not null" json:"red_ball_1"`
|
||||
// ... 其他字段
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 表名映射
|
||||
- 实现 `TableName()` 方法指定表名
|
||||
- 或使用 `gorm` 默认命名规则
|
||||
|
||||
---
|
||||
|
||||
> 文档维护者：JueChen
|
||||
> 创建时间：2026-01-07
|
||||
43
docs/01-规范/05-工作事项推进日志规范.md
Normal file
43
docs/01-规范/05-工作事项推进日志规范.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# 工作事项推进日志规范
|
||||
|
||||
## 1. 日志格式
|
||||
|
||||
### 1.1 基本信息
|
||||
- 事项标题
|
||||
- 创建时间
|
||||
- 状态（待办/进行中/已完成/已取消）
|
||||
- 优先级（高/中/低）
|
||||
|
||||
### 1.2 详细内容
|
||||
- 需求描述
|
||||
- 实现方案
|
||||
- 进展情况
|
||||
- 遇到的问题
|
||||
- 解决方案
|
||||
|
||||
### 1.3 时间记录
|
||||
- 创建时间
|
||||
- 开始时间
|
||||
- 完成时间
|
||||
- 重要节点时间
|
||||
|
||||
## 2. 更新规范
|
||||
|
||||
### 2.1 更新频率
|
||||
- 重要事项每日更新
|
||||
- 普通事项按进度更新
|
||||
- 完成后及时标记
|
||||
|
||||
### 2.2 更新内容
|
||||
- 记录关键进度节点
|
||||
- 记录遇到的问题和解决方案
|
||||
- 记录重要的决策和变更
|
||||
|
||||
## 3. 日志位置
|
||||
- 主要日志：`docs/TODO-LIST.md`
|
||||
- 功能迭代详细日志：`docs/04-功能迭代/{功能名称}/`
|
||||
|
||||
---
|
||||
|
||||
> 文档维护者：JueChen
|
||||
> 创建时间：2026-01-07
|
||||
Reference in New Issue
Block a user