cmroubao/docs/03-tech-stack.md

技术栈

“用什么”的权威速查表。状态为“待验证”的项不能在代码中当作既成事实。

技术栈一览

维度	选型	状态	说明
Android 基础	Roubao main 的 Kotlin 原生 Android 代码，应用版本 1.4.2	上游已核实，待接入	上游为 Turbo1123/roubao，MIT；接入时固定具体 commit。
Android IDE/JDK	Android Studio Hedgehog 2023.1.1 或更高；JDK 17	上游已核实	首次导入不接受 IDE 自动升级 AGP、Gradle 或 Kotlin。
Android 构建链	Gradle 8.2；AGP 8.2.0；Kotlin 1.9.20；JVM target 17	上游已核实	使用仓库内 Gradle Wrapper，不依赖全局 Gradle。
Android SDK	compileSdk/targetSdk 34；minSdk 26；SDK Build Tools 34.0.0	上游已核实	支持 Android 8.0+；真机自动化优先 Android 11+。
Android UI	Jetpack Compose + Material 3；Compose Compiler 1.5.5	上游已核实	Compose BOM 为 2023.10.01。
Android 自动化	项目目标以 AccessibilityService 为主，Shizuku 为兼容/增强路径	目标已定，待实现	上游 main 使用 Shizuku 13.1.5；无障碍实现位于独立开发分支，不能把它误认为主分支现状。
第一层任务源	UTF-8 四行蝦皮订单文本 + 同订单号 JPEG	首份样例已核实，待实现	使用 Debug/测试专用 TaskSource；原始数据和生成物不得提交。
Android 长任务	前台服务 + 持续通知	计划采用	降低执行中被系统挂起的风险，仍需处理进程死亡恢复。
后端语言	Go 1.23.0	MVP 已定	与现有本机工具链一致；构建测试必须设置 GOTOOLCHAIN=local 防止静默升级。
后端骨架	Go Blueprint v0.10.11 生成的最小 Gin + SQLite 工程	MVP 已定	只作为一次性脚手架输入；生成后立即重写版本约束。
后端框架	Gin v1.11.0	MVP 已定	这是 go.mod 明确支持 Go 1.23.0 的最高已核实 Gin 版本。
数据访问	标准库 database/sql	MVP 已定	领域层通过仓储接口访问，避免先引入 ORM 和代码生成复杂度。
数据迁移	Goose v3，使用 SQL migration	MVP 已定	迁移可审核、可排序并支持 SQLite；版本在 T-201 建立 go.mod 时锁定。
管理 Web	Gin + html/template + embed + 少量原生 JS/CSS	MVP 已定	不单独引入 SPA 工程，模板和静态资源随服务构建。
数据库	SQLite	MVP 已定	单服务、单设备验证足够；多实例或并发提升前迁移 PostgreSQL。
图片/截图	后端受控本地文件目录，数据库存元数据	MVP 已定	禁止把二进制直接塞入日志；生产再评估对象存储。
管理鉴权	单个种子管理账号 + 服务端会话 Cookie	MVP 已定	密码只保存哈希；完整 RBAC 为 V2。
App 鉴权	采购员登录态 + 设备绑定令牌	目标已定，细节待实现	人员身份与设备身份分离；令牌只保存哈希。
VLM 接入	应用内统一适配器，优先兼容 OpenAI 风格多模态接口	接口已定，供应商待定	模型输出必须符合本项目 JSON Schema。
通知	MVP 不使用推送	已定	点击“获取任务”调用原子 claim API；V2 再评估厂商推送/WebSocket。
后端测试	标准库 testing + httptest	MVP 已定	覆盖状态机、权限、幂等、SQLite 事务和输入校验。
Android 测试	JUnit + 现有上游测试工具；真实设备 smoke	待源码核实	UI 自动化核心必须在目标设备验证。
部署	单机局域网 Go 服务；容器化后置	MVP 已定	Android 测试机必须能通过 HTTPS 或受控测试网络访问。

Roubao 上游版本基线

核实日期：2026-07-25。

项目	已核实值
上游仓库	Turbo1123/roubao
许可证	MIT
默认分支	main
核实时 main commit	c8a6d7f03422eb01744b01f3ee77bf7757741f7e
main 应用版本	1.4.2（versionCode 7）
开发 IDE	Android Studio Hedgehog 2023.1.1 或更高
JDK / JVM target	17 / 17
Android SDK	compileSdk 34、targetSdk 34、minSdk 26
SDK Build Tools	34.0.0（AGP 8.2 官方兼容基线）
Gradle / AGP	8.2 / 8.2.0
Kotlin	1.9.20
Compose	Compose BOM 2023.10.01、Compiler 1.5.5、Material 3
自动化依赖	Shizuku API/Provider 13.1.5
无障碍开发分支	roubao2.0+AccessibilityService，核实时 commit 5b114c0a9476c359b27cfe994743fc7beb0a3554

上述值来自上游 README、build.gradle.kts、app/build.gradle.kts 和 gradle/wrapper/gradle-wrapper.properties。它们是接入前的远端核实结果，不代表 本仓库已经构建通过。T-001 接入时必须再次确认远端 commit，并把最终采用的 commit 作为可复现基线。

上游启用了 Google Services 4.4.2、Firebase Crashlytics Gradle Plugin 3.0.2 和 Firebase BOM 33.7.0，但 google-services.json 被 .gitignore 排除。干净构建必须 提供本项目自己的 Firebase 配置，或者在不需要遥测时移除相关插件和依赖；不得提交 真实 Firebase 配置。

关键决策

• 统一后端同时服务管理 Web 与 Android App；不是两套业务后端。
• 首版管理页面使用服务端渲染，避免在验证阶段维护独立前端构建链。
• Go Blueprint 只生成起始目录；正式代码必须删除演示逻辑，并按 04-architecture.md 的领域边界重组。
• SQLite 只服务单实例验证；出现多服务实例、并发写或正式备份要求时迁移 PostgreSQL。
• VLM 厂商可替换，领域层只接收结构化请求和结果，不传播供应商 SDK 类型。
• 拼多多自动化是独立工作流模块，不能耦合后端数据库实现或管理页面。

骨架选择记录

• 来源：Melkeydev/go-blueprint
• 固定版本：v0.10.11（MIT）
• 生成目标：Gin + SQLite
• 不启用：React、HTMX、WebSocket、Redis、Docker 等高级特性

计划生成命令：

go install github.com/melkeydev/go-blueprint@v0.10.11
go-blueprint create --name backend-api --framework gin --driver sqlite --git skip

Go Blueprint v0.10.11 当前生成的是 Go 1.25.0 + Gin 1.12.0，不能直接作为本项目 的 go.mod。2026-07-25 已在临时目录将生成结果调整为以下版本，并在 GOTOOLCHAIN=local 下完成 go mod tidy 和 go test ./...：

go 1.23.0
github.com/gin-gonic/gin v1.11.0
github.com/gin-contrib/cors v1.7.6
github.com/joho/godotenv v1.5.1
github.com/mattn/go-sqlite3 v1.14.48

Gin v1.12.0 的 go.mod 要求 Go 1.25.0，因此本项目禁止升级到 Gin 1.12.x，除非先 单独批准升级 Go 工具链。正式接入还必须修正：

• 健康检查不得调用 log.Fatal 终止进程。
• 删除包级数据库单例和包加载阶段读取环境变量的写法。
• 关闭不需要的默认 CORS，不提交生成的 .env。
• 正确关闭数据库和 HTTP Server，注入 config/repository 以便测试。
• mattn/go-sqlite3 需要 CGO 和 GCC；构建环境必须显式验证。

不选择 go-admin-team/go-admin：Vue、多租户、Casbin RBAC、代码生成和定时任务 超出 MVP。不选择 evrone/go-clean-template：当前模板以 Fiber、PostgreSQL、 RabbitMQ、NATS 和 gRPC 为主，不符合最小 Gin + SQLite 边界。

计划目录

android-buyer/      # Kotlin Android App
backend-api/
  cmd/api/                    # 进程入口，只负责装配和生命周期
  internal/domain/            # 实体、状态机和确定性规则
  internal/usecase/           # 创建、领取、执行和结果归档
  internal/transport/http/    # Gin handler、中间件和页面
  internal/repository/sqlite/ # database/sql 仓储
  internal/platform/          # 配置、日志、文件和 VLM 适配器
  migrations/                 # Goose SQL migration
  web/templates/              # html/template
  web/static/                 # 少量 CSS/JS
  var/                        # 本地运行数据，必须忽略
docs/

目录在真实骨架建立后以代码为准并同步本文。

构建与运行命令

当前没有源码，以下是计划形状而非可运行证据：

用途	计划命令	当前状态
Android 构建	android-buyer\gradlew.bat assembleDebug	待 T-001
Android 单元测试	android-buyer\gradlew.bat test	待 T-001
后端依赖	go mod download（在 backend-api/）	待 T-201
后端测试	go test ./...（在 backend-api/）	待 T-201
后端构建	go build -o bin/cmroubao-api.exe ./cmd/api	待 T-201
后端启动	go run ./cmd/api	待 T-201
数据迁移	goose -dir migrations sqlite3 ./var/cmroubao.db up	待 T-201

任何命令只有实际执行成功后才能写入 init.ps1、init.sh 和 current-state.md 的“当前可运行内容”。

依赖纪律

• 接入 Roubao 后优先使用其已有 HTTP、序列化、依赖注入和 UI 方案。
• 扩大 Shizuku 使用范围，或新增 OCR、浏览器自动化和第二套网络库前必须证明已有 能力不足。
• 后端新增库要说明用途；验证版不引入 ORM、消息队列、Redis、微服务或 SPA 框架。
• Go 依赖必须固定到 go.mod/go.sum；构建和 CI 不使用未固定的 @latest。
• go.mod 必须声明 go 1.23.0；验证使用 GOTOOLCHAIN=local go test ./... 或 PowerShell 等价环境变量，确保依赖没有暗中要求更高 Go 版本。
• handler 不直接写 SQL，repository 不依赖 Gin，domain/usecase 不导入具体数据库驱动。
• 密钥和设备令牌通过环境变量或本地忽略配置注入，不进入 Git。