# 技术栈(Tech Stack)

> "用什么"的统一速查表。选型与理由在此集中维护;"怎么把它们搭起来"见 [架构设计](04-architecture.md)。
> 未定项必须标为待定,不要让 agent 在代码里自行决定。

## 一、技术栈一览

| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 语言 | Go | 已定 | 网络、并发、校验、单二进制交付、可测试性强 |
| UI 框架 | Gio(纯 Go 立即模式 GUI) | 已定 | 无 CGO、单 EXE、跨版本可锁定;仅限 UI 层 |
| 现代版工具链 | Go 1.25(锁定已验证版本) + Gio v0.10.1 | 已定 | 当前受支持工具链;支持 Win10/Win11 x64 |
| Win7 版工具链 | Go 1.20.14(最终补丁) + Gio v0.6.0 | 已定 | Go 1.20 是最后支持 Win7 的版本;Gio v0.6.0 可由 Go 1.20 构建 |
| 模块结构 | go.work + 三个 go.mod(core / app-modern / app-win7) | 已定 | 共享核心,双构建互不污染工具链要求 |
| 依赖管理 | 版本锁定 + vendor(Gio 及相关依赖) | 已定 | 防止 Win7 构建被隐式升级到要求 Go 1.21+ 的依赖 |
| 存储 | JSON 文件 + 临时文件原子替换 | 已定 | 数百款软件规模足够;SQLite 仅在历史/搜索/事务需求出现后评估 |
| 软件包格式 | ZIP(标准软件包协议 v1) | 已定 | 避免 UnRAR.dll;协议见 [api.md](api.md) |
| 清单/许可证签名 | Ed25519(客户端只内置公钥) | 已定 | 离线可验证;私钥不进客户端与仓库 |
| 包完整性 | SHA-256 | 已定 | 下载后、执行前强制校验 |
| 传输 | HTTPS | 已定 | 清单与软件包一律 HTTPS |
| Windows API | golang.org/x/sys/windows + 动态加载(LoadLibrary) | 已定 | Win10 专属 API 动态加载并降级,不进导入表 |
| EXE 签名 | Authenticode | 已定 | 主程序与 Updater 均签名;证书采购待确认 |
| 测试 | go test(core 无头可测) + fake/stub 注入 | 已定 | domain/application 不依赖 Gio 与 Windows API |
| CI | Gitea Actions 模板 + 本地 Phase 0 脚本 | 部分已定 | `.gitea/workflows/phase0-build.yml` 复用本地入口;远端 runner 可用性待确认 |
| 静态检查 | go vet(+ 待定 golangci-lint) | 部分已定 | vet 必跑;lint 工具后续确认 |

## 二、决策记录与演进

- **双版本策略**:不维护两个长期开发分支;一个 main 主分支 + 共享 core + 两个 go.mod + 两个更新通道。仅当 Win7 版冻结、只接受严重修复时,才考虑建立 `release/win7-legacy` 维护分支。
- **core 兼容基线**:core 保持 Go 1.20 语法和依赖兼容,使两个版本复用同一业务实现;现代版可用新 Gio 和现代 Windows 能力,但这些依赖不得反向进入 core。
- **存储**:现在选择 JSON + 原子写入,避免早期引入 SQLite 的复杂度;在出现历史记录、全文搜索、大量事务需求时再评估。
- **软件包**:现在只支持 ZIP;不在 v1 开放任意安装脚本(install.bat/PowerShell 钩子),未来如需运行库安装,走受审核的 prerequisites 声明。
- **授权**:不复用旧盒子的 MD5/SHA-1 隐藏常量注册码设计;采用服务端 Ed25519 签名许可证 + machine_hash 绑定。
- **Win7 x86**:默认不提供;仅在真实用户占比支撑时增加 win7-386 构建目标。

## 三、构建与运行命令

> 工程骨架由 T-001 建立;根目录 `init.sh`/`init.ps1` 统一执行依赖同步与 core 基础验证,并打印双目标构建命令。

| 用途 | 命令 |
| --- | --- |
| Phase 0 完整闸门(Unix) | `bash scripts/verify_phase0.sh` |
| Phase 0 完整闸门(Windows) | `./scripts/verify_phase0.ps1` |
| 同步工作区依赖 | `go work sync` |
| core 测试 | `cd core && go test -count=1 ./...` |
| core 静态检查 | `cd core && go vet ./...` |
| 现代版构建 | `cd app-modern && GOTOOLCHAIN=go1.25.0 CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-H=windowsgui" -o ../dist/SoftBox.exe ./cmd/softbox` |
| Win7 版构建 | `cd app-win7 && GOTOOLCHAIN=go1.20.14 CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-H=windowsgui" -o ../dist/SoftBox-win7.exe ./cmd/softbox` |
| 本地运行(开发) | Windows 下直接 `go run ./cmd/softbox`(WSL 中构建 EXE 后到 Windows 侧运行) |

根 `go.work` 纳入三个模块并使用 modern 所需的 Go 1.25 workspace 版本;`app-win7/go.work` 是就近的 Go 1.20 workspace,只纳入 `app-win7` 与 `core`,确保 Go 1.20.14 不需要解析 modern 模块。

工具链矩阵:

| 构建目标 | 工具链 | Gio | 支持系统 | 维护策略 |
| --- | --- | --- | --- | --- |
| modern-amd64 | Go 1.25(锁定) | v0.10.1 | Win10/Win11 x64 | 正常新增功能 |
| win7-amd64 | Go 1.20.14 | v0.6.0 | Win7 SP1 x64 及更高 | 兼容与严重修复 |
| win7-386 | Go 1.20.14 | v0.6.0 | Win7 SP1 x86 及更高 | 仅真实需求时提供 |

## 四、依赖纪律

- 新增第三方依赖前,先说明用途、替代方案和维护成本,并确认其 go.mod 的 `go` 指令不超过对应模块的工具链基线(core 与 app-win7 为 1.20)。
- core 禁止依赖 Gio、SQLite 驱动、Windows 专属包;平台能力一律接口注入。
- Gio 及 UI 相关依赖锁定版本并 vendor;升级 Gio 只允许在 app-modern,且需单独任务评估。
- 不确定的技术选型先更新本文,再进入代码。
- 不允许同一职责并存两套实现(如两套下载器、两套配置读写)。