# Lyra

链接、分类、设置等资源的后端服务（实现中）。目标结构与技术选型见
[docs/architecture.md](docs/architecture.md)。

## 当前状态

HTTP 通路已延伸到数据库：启动时加载本地 `.env.local` 与 `etc/lyra.toml`，经
sqlx 连接 PostgreSQL（注册 pgx stdlib 驱动，驱动名取自配置），组装依赖后注册
`GET /test`——由 `handler.TestHandler` 调用 `model.CategoryModel.FindAll` 查询
`public.categories`（当前固定 `sort >= 1`、按 sort/id 排序、limit 10），并经
显式转换为本轮新增的 `api.CategoryResponse` 响应 DTO 后输出。该接口用于验证
handler→model→数据库链路，不是完整业务 API。

数据库连接代码当前在入口 `main` 中，`internal/postgres` 与 `internal/service`
仍是占位（仅 `AGENTS.md`），业务 service 未实现；连接与查询未设置超时，连接
真实数据库的端到端验证本轮也未做。

`internal/model` 已落地 `Category` 结构、`CategoryModel` 接口与 Squirrel +
sqlx 实现。路由与 handler 均有基于替身的 httptest 回归测试（不监听实际端口、
不连接数据库），不证明真实 SQL 可用。各内部目录的职责与依赖约束记录在各目录
`AGENTS.md` 中。数据库迁移 SQL 已就位：`migrations/00001_init.sql`（初始函数
与三张表），通过手工 goose CLI 执行，操作手册见
[docs/goose.md](docs/goose.md)，迁移目录说明见
[migrations/README.md](migrations/README.md)；Goose 的 Go 依赖仍未引入。
架构文档中标注“待新增”的文件（links 等）尚未创建。

## 目录职责

| 路径 | 职责 |
|---|---|
| `cmd/lyra/` | 程序入口：启动、依赖组装、退出清理（数据库连接当前建在此处） |
| `internal/api/` | HTTP 请求/响应 DTO，按资源分文件（平铺） |
| `internal/config/` | 配置定义与加载 |
| `internal/postgres/` | PostgreSQL 连接的目标位置（占位：连接暂在入口 main） |
| `internal/router/` | 路由注册、项目路径前缀（router.go，平铺） |
| `internal/handler/` | 参数绑定、DTO 转换、响应输出；可按业务分包，服务级简单接口平铺在根包 |
| `internal/service/` | 业务规则、事务协调；可按业务分包，服务级简单接口平铺在根包（占位） |
| `internal/model/` | 数据结构定义与数据访问（SQL，平铺） |
| `internal/httpx/` | 公共响应辅助 |
| `migrations/` | Goose SQL 迁移文件（00001 初始迁移已就位） |
| `docs/` | 架构与计划文档 |

## 运行

Go 命令在本目录（module 根）下执行；`.env.local` 与配置路径 `etc/lyra.toml`
均按当前工作目录解析，换目录运行会找不到它们：

```bash
go run ./cmd/lyra   # 启动 HTTP 服务，监听地址与端口见 etc/lyra.toml
go test ./...       # 回归测试（不监听实际端口、不连接数据库）
```

启动前提：本地存在 `.env.local`（提供数据库口令等环境变量，已被 gitignore、
不入库，内容不在文档展开）、`etc/lyra.toml` 配置完整，且其指向的 PostgreSQL
可达；连接失败时启动即退出。

配置中的 `app.env` 直接传给 `gin.SetMode`，仅支持 `debug`/`release`/`test`。
环境变量方面当前仅 `database.password` 绑定了 `PG_PASSWORD`，其余配置项不
支持环境变量覆盖，也没有校验与默认值。

## 技术栈

已引入并使用：Gin（HTTP 路由）、Viper（读取 TOML 配置）、godotenv（加载
`.env.local`）、sqlx + Squirrel（查询构造与执行）、pgx stdlib（PostgreSQL
驱动）。Goose 仅以独立 CLI（v3.29.0）手工执行迁移，Go 依赖尚未引入。