feat(lyra): 搭建基础骨架与配置响应组件

- 使用 Viper 加载 TOML 配置
- 定义统一响应、业务错误码及响应辅助函数
- 添加分层职责约束并同步架构文档

go/projects/lyra/docs/architecture.md

@@ -2,11 +2,19 @@
 
 日期：2026-10-16
 
-本文记录已确认的目标目录结构与职责边界。Lyra 当前仅有 go.mod 和文档，代码尚未实施；以下文件为计划形态，不代表已存在。选型与讨论过程见 [plans/2026-10-16-lyra-architecture.md](plans/2026-10-16-lyra-architecture.md)。
+本文记录已确认的目标目录结构与职责边界，并与当前真实实现同步。目录树是**目标结构**，并非全部已存在：当前只有 `cmd/lyra/main.go`、`internal/config/config.go`、`internal/api/{code,response}.go`、`internal/httpx/response.go` 是 Go 代码；`internal/{handler,model,postgres,router,service}` 仅含 `AGENTS.md`（记录职责与依赖约束），暂不构成 Go 包。选型与讨论过程见 [plans/2026-10-16-lyra-architecture.md](plans/2026-10-16-lyra-architecture.md)。
 
 ## 已确认技术栈
 
-Gin（HTTP 路由）、PostgreSQL、Squirrel + sqlx（数据访问，pgx stdlib 驱动）、Goose（数据库迁移）。
+- 已引入：Gin v1.12.0（HTTP 路由）、Viper v1.21.0（配置读取，TOML）。`go.sum` 已由 Go 工具生成。
+- 目标选型（选型已确认，尚未作为代码依赖引入）：PostgreSQL、Squirrel + sqlx（pgx stdlib 驱动）、Goose（数据库迁移）。
+
+## 当前进度
+
+- 程序入口按相对工作目录的 `etc/config.toml` 加载配置（Viper，`mapstructure` 标签），打印结果后退出；不启动 HTTP 服务，也不连接数据库。
+- 已定义公共响应契约：`api.Response`（success/data/error）、`api.ErrorInfo`（code/message/debug）与错误码类型 `api.ErrorCode` 及其默认文案 `Message()`。
+- 已实现响应输出辅助 `httpx.OK`、`httpx.Fail`。
+- 尚未实现：业务逻辑、路由注册、数据库访问与迁移 SQL；配置校验、环境变量覆盖与默认值；`ErrorInfo.Debug` 的填充与按环境开关。日志方案未定。
 
 ## 目录结构
 
@@ -14,38 +22,42 @@ Gin（HTTP 路由）、PostgreSQL、Squirrel + sqlx（数据访问，pgx stdlib
 lyra/
 ├── cmd/lyra/main.go                  # 启动、依赖组装、退出清理
 ├── internal/
-│   ├── api/                          # HTTP 请求/响应 DTO，按资源分文件
-│   │   ├── links.go                  # links 资源示例（下同）
-│   │   ├── categories.go
-│   │   └── settings.go
+│   ├── api/                          # HTTP 请求/响应 DTO、错误码与响应契约
+│   │   ├── response.go               # Response/ErrorInfo 结构
+│   │   ├── code.go                   # ErrorCode 与错误码常量、默认文案
+│   │   ├── links.go                  # links 资源 DTO 示例（待新增）
+│   │   ├── categories.go             # 待新增
+│   │   └── settings.go               # 待新增
 │   ├── config/
 │   │   └── config.go                 # 配置定义与加载
 │   ├── postgres/
-│   │   └── postgres.go               # 数据库连接
+│   │   └── postgres.go               # 数据库连接（待新增）
 │   ├── router/
-│   │   └── router.go                 # 路由注册、项目路径前缀
+│   │   └── router.go                 # 路由注册、项目路径前缀（待新增）
 │   ├── handler/
-│   │   └── links.go                  # 参数绑定、DTO 转换、响应输出
+│   │   └── links.go                  # 参数绑定、DTO 转换、响应输出（待新增）
 │   ├── service/
-│   │   ├── links.go                  # 业务规则、事务协调
-│   │   └── links_test.go             # 测试与源文件同目录
+│   │   ├── links.go                  # 业务规则、事务协调（待新增）
+│   │   └── links_test.go             # 测试与源文件同目录（待新增）
 │   ├── model/
-│   │   ├── link.go                   # Link 数据结构定义
-│   │   ├── link_model.go             # 数据访问对象：CRUD 与 SQL（示例）
-│   │   └── link_model_test.go        # 查询测试（示例）
+│   │   ├── link.go                   # Link 数据结构定义（待新增）
+│   │   ├── link_model.go             # 数据访问对象：CRUD 与 SQL（待新增）
+│   │   └── link_model_test.go        # 查询测试（待新增）
 │   └── httpx/
-│       └── response.go               # 公共响应辅助，按需实现
-├── migrations/                       # Goose SQL 迁移文件
+│       └── response.go               # 公共响应输出辅助（OK/Fail）
+├── etc/
+│   └── config.toml                   # 运行配置（App/HTTP）
+├── migrations/                       # Goose SQL 迁移文件（暂无）
 ├── docs/
 │   ├── plans/
 │   └── architecture.md               # 本文
 ├── README.md
 ├── go.mod
-└── go.sum                            # 引入依赖后由 Go 工具生成
+└── go.sum                            # 已生成
 ```
 
-- 标注示例的文件展示一个资源在各层的文件分布；分类、设置等资源按同样方式在 api/handler/service/model 新增对应文件。model/link.go 定义 Link 数据结构，model/link_model.go 定义数据访问与 SQL，model/link_model_test.go 测试查询，均为示例，实际文件随实现新增。
-- 只创建实际需要的文件；不预建空目录或空测试文件，具体迁移文件名随首个迁移确定。
+- 标注“待新增”的文件只是职责分布示例，随实现按需新增，不预建空文件或空目录；`internal/` 各目录均以 `AGENTS.md` 记录职责与依赖约束。
+- model 下的 `link*.go` 展示一个资源在各层的文件分布；分类、设置等资源按同样方式在 api/handler/service/model 新增对应文件。具体迁移文件名随首个迁移确定。
 
 ## 组织原则
 
@@ -58,14 +70,19 @@ lyra/
 - 主调用链为 handler→service→model→PostgreSQL；service 负责业务规则及需要的事务协调，model 支持同一事务内的数据库操作，不将跨多次写入各自独立提交当成原子业务。
 - 请求/响应 DTO 集中在 internal/api，与内部模型分开；即使初期字段相近，也不默认把数据库模型直接暴露为响应，接受必要的显式转换代码。
 - handler 引用 API DTO 完成绑定与转换；service/model 不依赖 Gin，也不依赖 internal/api DTO；api 包不反向引用 handler/service/model，避免传输契约与实现耦合或循环引用。
+- internal/api 拥有响应契约与业务错误码（`Response`/`ErrorInfo`/`ErrorCode`）；不依赖 Gin。
+- internal/httpx 负责响应输出：`OK` 固定 HTTP 200；`Fail` 接收 HTTP 状态码与业务错误码，`message` 为空时回退错误码默认文案。HTTP 状态码表示传输/结果类别，`ErrorCode` 表示自定义业务错误，两者分开。
+- 配置由入口 `main` 加载后组装并传递（约定/目标）：`internal/config` 只负责配置定义与加载，运行配置来自 `etc/config.toml`；当前 `main` 仅加载并打印，尚未向其他组件传递。
 - model 承载数据结构定义与数据访问：Squirrel/SQL 构造、sqlx 执行与结果映射，驱动为 pgx stdlib；不是 ORM 自动持久化，也不要求每种类型机械建立一套结构。
 - service/model 使用标准 context.Context，不接收 gin.Context。
 
-## 尚未确定
+## 尚未确定 / 待实现
 
-以下仍为计划中的推荐或待确认项，未定为已决：
+以下均为计划中的推荐或待确认项，尚未实现，也未定为已决：
 
-- 代码尚未实施，也未进行数据库连接或结构修改。
+- 配置校验、环境变量覆盖与默认值：尚未实现（当前无任何校验、覆盖或默认值）。
+- `ErrorInfo.Debug` 的填充与按环境（dev）开关：尚未实现，目前仅有字段。
+- 分页响应约定（如 data/meta 结构）与统一错误处理中间件：尚未引入，仅为历史讨论。
 - Goose 的部署执行入口与并发控制（串行执行或数据库锁）方案。
 - PostgreSQL 按项目划分 schema 的做法（组织边界，不等于权限隔离）。
 - 日志方案（候选标准库 slog）与中间件集成方式。