# 技术栈（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` 差异并记录验证结果。