# 技术栈（Tech Stack）

> “用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 [架构设计](04-architecture.md)。

## 一、技术栈一览

| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 前端框架 | 无，原生 HTML/CSS/JavaScript | 已定 | 降低构建复杂度，由 Gin 直接托管 |
| UI 样式方案 | 手写 CSS | 已定 | MVP 页面数量少，避免引入组件库 |
| 状态管理 | 浏览器内存状态 + URL 查询参数 | 已定 | 站点、部门、筛选条件简单可控 |
| 后端 | Go + Gin | 已定 | 用户指定；路由、中间件和静态文件托管成熟 |
| 数据库 | SQLite | 已定 | 本地单体应用，无需独立数据库服务 |
| SQLite 驱动 | `modernc.org/sqlite` 优先 | 待验证 | 纯 Go，Windows 构建更简单；如遇兼容问题再评估 `mattn/go-sqlite3` |
| 鉴权方式 | MVP 无账号 | 已定 | 默认本地或受信内网运行 |
| 钉钉 API 客户端 | Go `net/http` | 已定 | 标准库足够，便于测试和超时控制 |
| 部署方式 | 单个 Go 进程 + SQLite 文件 + 静态文件 | 已定 | 简单可复制 |
| 测试 | `go test ./...` | 已定 | 覆盖服务层、数据层、handler |

## 二、决策记录与演进

- 不引入前端框架：当前页面是管理工具界面，原生 DOM 和 fetch 足够完成 MVP。
- 使用 Gin 托管前端：避免前后端两个开发服务器和 CORS 配置。
- SQLite 作为唯一持久化：站点配置、token、部门、人员、同步日志都入库。
- 不引入 ORM：优先使用 `database/sql` 和小型 repository，避免隐藏 SQL 行为。
- 定时任务 V2 再做：MVP 先实现手动同步和 token 按需刷新。

## 三、构建与运行命令

当前尚未初始化代码，以下是目标命令：

| 用途 | 命令 |
| --- | --- |
| 初始化依赖 | `go mod tidy` |
| 本地开发 | `go run .` |
| 构建 | `go build ./...` |
| 测试 | `go test ./...` |
| 格式化 | `gofmt -w .` |

Windows PowerShell：

```powershell
go mod tidy
go run .
go test ./...
go build ./...
```

## 四、依赖纪律

- 新增第三方依赖前，先说明用途、替代方案和维护成本。
- 不允许引入 Vue、React、Element Plus、Vite、Webpack 等前端框架或构建链。
- 不允许同一职责并存两套路由、数据库访问或状态管理方案。
- 钉钉 SDK 不是默认选择；除非标准 HTTP 封装无法满足需求。