5.6 KiB
5.6 KiB
技术栈（Tech Stack）
本文是“用什么”的权威来源。系统如何分层见
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 在目标工具链上的实际结果为准。
六、本地目录约定
默认运行数据位于：
%LOCALAPPDATA%\ShopHelm\
├── data\shophelm.db
├── profiles\<store-id>\
├── assets\
├── backups\
└── logs\
默认图片导出目录：
%USERPROFILE%\Pictures\ShopHelm\Exports\
用户可以在设置中改 profile 根目录、备份目录和导出目录，但迁移或切换目录必须显式确认。
七、依赖纪律
- 标准库可解决时不加依赖。
- 新依赖必须记录用途、许可证、维护状态、替代方案和测试范围。
- 同一职责不得并存两套数据库驱动、图片库、日志框架或状态管理方式。
- 不因示例代码方便而加入 Web 框架、嵌入浏览器、ORM 或依赖注入框架。
- 依赖变更后运行
go mod tidy，审查go.mod/go.sum差异并记录验证结果。