102 lines
5.6 KiB
Markdown
102 lines
5.6 KiB
Markdown
# 技术栈（Tech Stack）
|
||
|
||
> 本文是“用什么”的权威来源。系统如何分层见 [`04-architecture.md`](04-architecture.md)。
|
||
|
||
## 一、技术栈一览
|
||
|
||
| 维度 | 选型 | 状态 | 理由 |
|
||
| --- | --- | --- | --- |
|
||
| 操作系统 | Windows 10/11 x64 | 已定 | 首发围绕本地 Chrome、profile 和 Windows 文件系统 |
|
||
| 语言 | Go；本机基线 `go1.23.0` | 临时已定 | 用户选定 Go；T-001 验证 Gio 兼容性，公开发布前升级到受支持版本 |
|
||
| 桌面 UI | Gio `gioui.org` | 已定，版本待 T-001 锁定 | 单语言、本地可控；接受自行封装管理台组件 |
|
||
| UI 组件 | Gio Material + 项目内组件 | 已定 | 只建设 ShopHelm 需要的表格、表单、弹窗和预览画布 |
|
||
| 扩展组件 | `gioui.org/x/component` | 待原型确认 | API 稳定性较弱；只有 T-101 证明有价值后才引入并锁 commit |
|
||
| 状态管理 | 页面状态结构体 + application event channel | 已定 | 匹配 Gio immediate-mode，避免额外状态框架 |
|
||
| 持久化 | SQLite + `database/sql` | 已定 | 本地单用户、备份简单 |
|
||
| SQLite 驱动 | `modernc.org/sqlite` | 已定 | 避免 Windows CGO 工具链依赖 |
|
||
| Migration | `embed` 嵌入顺序 SQL + `schema_migrations` | 已定 | 依赖少、版本可审计、离线可用 |
|
||
| 图片预览 | Gio 画布，必要时 CPU 生成预览帧 | 已定 | 负责交互反馈，不作为正式导出结果 |
|
||
| 图片导出 | `image`、`image/draw`、`image/png`、`image/jpeg`，缩放用 `golang.org/x/image/draw` | 已定 | 预览和导出解耦，输出分辨率可控 |
|
||
| 表格文件 | `encoding/csv` + `github.com/xuri/excelize/v2` | 已定 | 满足 CSV/XLSX 人工交换 |
|
||
| Chrome | `os/exec` 启动系统 Chrome | 已定 | 平台页面不嵌入 Gio，不依赖 WebView |
|
||
| 密码 | 首发不保存 | 已定 | Chrome profile 保留会话，避免凭证落库 |
|
||
| 日志 | `log/slog` + 本地文件 sink | 已定 | 结构化、标准库优先；不得记录秘密 |
|
||
| 配置 | SQLite `settings` + 固定的本地数据目录 | 已定 | 统一备份和恢复 |
|
||
| 测试 | `go test`、临时 SQLite、fake process/file adapters、Windows 手工 smoke | 已定 | 隔离系统副作用并验证真实集成 |
|
||
| 发布 | 单机 Windows 构建；安装包形式待 T-503 | 部分待定 | 先保证二进制可运行，再选 ZIP 或安装器 |
|
||
|
||
## 二、版本策略
|
||
|
||
- 当前机器只有 Go 1.23.0，因此文档基线如实记录该版本，不声称它是最新或仍受支持。
|
||
- T-001 必须实际运行最小 Gio 窗口并锁定兼容的 Go/Gio 版本，随后同步本文、`go.mod` 和 `current-state.md`。
|
||
- 依赖首次加入后必须由 `go.mod` / `go.sum` 固定；后续任务不得直接使用浮动 `@latest`。
|
||
- Go、Gio 或 SQLite 驱动升级必须单独成任务，先跑完整测试和三个高风险 smoke。
|
||
- 若目标 Gio 版本不支持 Go 1.23.0，优先升级 Go 工具链，不为保留旧版本降级架构或复制旧依赖。
|
||
|
||
## 三、关键技术决策
|
||
|
||
- **选择 Gio**：保持 Go 单语言和本地部署，但接受 CRUD UI 需要项目内组件建设。
|
||
- **不选择 Wails**：当前产品方向已选 Gio；只有 T-101 证明核心管理台交互无法达到可用标准时才重新评估。
|
||
- **外部 Chrome**：真实店铺后台始终由独立 Chrome 进程打开，Gio 只做控制台。
|
||
- **无远程后端**：首发没有 REST 服务、云账号和同步服务。
|
||
- **不存平台密码**：账号字段只是用户识别信息；登录由 Chrome profile 会话和用户手工操作承担。
|
||
- **预览/导出分离**：Gio 显示交互预览，CPU 合成器生成正式 PNG/JPG。
|
||
- **RPA 后置**：官方 API、CSV/XLSX 和人工操作无法满足且平台允许时，才建立辅助自动化任务。
|
||
|
||
## 四、计划依赖
|
||
|
||
| 依赖 | 用途 | 引入任务 |
|
||
| --- | --- | --- |
|
||
| `gioui.org` | 窗口、布局、输入、Material 组件 | T-001 |
|
||
| `modernc.org/sqlite` | CGO-free SQLite 驱动 | T-003 |
|
||
| `golang.org/x/image` | 高质量图片缩放 | T-103 |
|
||
| `github.com/xuri/excelize/v2` | XLSX 导入导出 | T-304 |
|
||
|
||
`gioui.org/x/component`、Windows 专用系统库和日志轮转库均不是预先批准依赖；使用前必须由对应任务验证并更新本文。
|
||
|
||
## 五、构建与运行
|
||
|
||
当前在 T-001 前没有 `go.mod`，以下命令是初始化后的标准接口：
|
||
|
||
| 用途 | 命令 |
|
||
| --- | --- |
|
||
| 同步依赖 | `go mod download` |
|
||
| 本地开发 | `go run ./cmd/shophelm` |
|
||
| 单元/集成测试 | `go test ./...` |
|
||
| 竞态检查 | `go test -race ./...` |
|
||
| 静态检查 | `go vet ./...` |
|
||
| 格式检查 | `gofmt -l .`，输出必须为空 |
|
||
| Windows 构建 | `go build -o build/shophelm.exe ./cmd/shophelm` |
|
||
| 标准入口 | `./init.ps1` |
|
||
|
||
是否使用 `-race` 和 Windows GUI linker flags，以 T-001 在目标工具链上的实际结果为准。
|
||
|
||
## 六、本地目录约定
|
||
|
||
默认运行数据位于：
|
||
|
||
```text
|
||
%LOCALAPPDATA%\ShopHelm\
|
||
├── data\shophelm.db
|
||
├── profiles\<store-id>\
|
||
├── assets\
|
||
├── backups\
|
||
└── logs\
|
||
```
|
||
|
||
默认图片导出目录：
|
||
|
||
```text
|
||
%USERPROFILE%\Pictures\ShopHelm\Exports\
|
||
```
|
||
|
||
用户可以在设置中改 profile 根目录、备份目录和导出目录，但迁移或切换目录必须显式确认。
|
||
|
||
## 七、依赖纪律
|
||
|
||
- 标准库可解决时不加依赖。
|
||
- 新依赖必须记录用途、许可证、维护状态、替代方案和测试范围。
|
||
- 同一职责不得并存两套数据库驱动、图片库、日志框架或状态管理方式。
|
||
- 不因示例代码方便而加入 Web 框架、嵌入浏览器、ORM 或依赖注入框架。
|
||
- 依赖变更后运行 `go mod tidy`，审查 `go.mod` / `go.sum` 差异并记录验证结果。
|