diff --git a/docs/plans/2026-02-27-phase1-foundation-and-auth.md b/docs/plans/2026-02-27-phase1-foundation-and-auth.md index dbedb9c..1d9789c 100644 --- a/docs/plans/2026-02-27-phase1-foundation-and-auth.md +++ b/docs/plans/2026-02-27-phase1-foundation-and-auth.md @@ -10,6 +10,47 @@ **设计文档:** `docs/plans/2026-02-27-echochat-system-design.md` +**日志系统设计:** `docs/architecture/system-architecture.md` 第八节 + +--- + +## 全局规范(贯穿所有 Task) + +### 代码注释规范 + +以下规范适用于所有 Task 中编写的代码,必须严格遵守: + +**Go 后端注释规范:** +1. **包注释**:每个 package 必须有注释,以包名开头,说明包的用途 +2. **公开函数/方法**:所有大写字母开头的函数/方法必须有注释,格式:`// FuncName 描述功能` +3. **结构体注释**:每个 struct 需要注释说明用途,关键字段需要行内注释 +4. **枚举/常量**:每个常量值必须有注释说明含义 +5. **复杂逻辑**:非显而易见的逻辑段落需要注释说明意图和设计考虑 +6. **DAO 层**:每个数据库操作函数需说明 SQL 查询逻辑和性能考虑 +7. **中间件**:说明中间件的作用、执行顺序依赖和副作用 + +**前端注释规范(Vue/uniapp):** +1. **组件注释**:每个 `.vue` 文件顶部说明组件用途和依赖 +2. **API 函数**:每个 API 调用函数说明对应后端接口 +3. **Store**:state 字段、action 方法需要注释说明 +4. **工具函数**:参数和返回值类型、用途说明 +5. **复杂模板逻辑**:`v-if`/`v-for` 等复杂条件需要注释说明 + +### 日志规范 + +所有 Task 中的 Go 后端代码必须遵守日志规范(详见架构文档第八节): +1. 每个 Service/DAO 函数使用入口/出口日志模式 +2. 所有日志从 context 提取 trace_id +3. 错误必须记录 ERROR 级别日志,包含上下文信息 +4. 敏感信息必须脱敏 + +### Wire 依赖注入 + +从初期就使用 Wire 管理依赖注入: +1. 每个模块在 `provider.go` 中声明 Provider Set +2. 根目录 `app/provider/` 下维护全局 Wire 配置 +3. 新增模块时同步更新 Wire Provider + --- ## Task 1: Docker Compose 开发环境搭建 @@ -115,6 +156,8 @@ git commit -m "infra: Docker Compose 开发环境(PostgreSQL + Redis)" - Create: `backend/go-service/pkg/middleware/recovery.go` - Create: `backend/go-service/pkg/middleware/logger.go` - Create: `backend/go-service/pkg/middleware/trace.go` +- Create: `backend/go-service/app/provider/provider.go` +- Create: `backend/go-service/app/provider/wire.go` > **日志系统详细设计见** `docs/architecture/system-architecture.md` 第八节 @@ -202,18 +245,56 @@ type Response struct { 创建 `pkg/middleware/cors.go` — CORS 跨域中间件。 创建 `pkg/middleware/recovery.go` — Panic 恢复中间件(捕获 panic 后记录 ERROR 日志含堆栈信息)。 -**Step 7: 创建 main.go 入口** +**Step 7: 初始化 Wire 依赖注入** + +创建 `app/provider/provider.go` — 定义基础设施层的 Provider Set: + +```go +// provider.go — 基础设施 Provider Set +package provider + +import "github.com/google/wire" + +// InfraSet 提供所有基础设施组件 +var InfraSet = wire.NewSet( + db.NewPostgres, + db.NewRedis, + logs.NewLogger, +) +``` + +创建 `app/provider/wire.go` — Wire 注入入口: + +```go +//go:build wireinject + +package provider + +// InitializeApp 初始化整个应用(Wire 自动生成实现) +func InitializeApp(cfg *config.Config) (*App, error) { + wire.Build( + InfraSet, + // 后续每增加一个模块,在这里添加对应的 ProviderSet + ) + return nil, nil +} +``` + +安装 Wire 工具:`go install github.com/google/wire/cmd/wire@latest` +生成注入代码:`cd app/provider && wire` + +**Step 8: 创建 main.go 入口** 创建 `cmd/server/main.go`: 1. 加载配置 2. 初始化日志系统(根据配置设置级别和输出格式) -3. 连接数据库和 Redis +3. 通过 Wire 生成的 InitializeApp 初始化所有组件 4. 创建 Gin Engine 5. 注册中间件(顺序:Trace → Logger → CORS → Recovery) 6. 注册路由(暂时只有健康检查 GET /health) 7. 启动 HTTP 服务 -**Step 8: 安装依赖** +**Step 9: 安装依赖** Run: `cd backend/go-service && go mod tidy` @@ -238,6 +319,7 @@ git commit -m "feat(backend): Go 服务骨架(配置、日志、数据库、 - Create: `backend/go-service/app/auth/model/role.go` - Create: `backend/go-service/app/auth/dao/user_dao.go` - Create: `backend/go-service/app/auth/dao/role_dao.go` +- Create: `backend/go-service/app/auth/provider.go` - Create: `backend/go-service/app/constants/user_status.go` - Create: `backend/go-service/app/constants/role_code.go` @@ -287,7 +369,26 @@ const ( - `GetUserRoles(ctx, userID)` — 获取用户角色列表 - `HasRole(ctx, userID, roleCode)` — 检查用户是否拥有指定角色 -**Step 6: Commit** +**Step 6: 创建 Auth 模块 Wire Provider** + +创建 `app/auth/provider.go`: + +```go +// provider.go — Auth 模块依赖注入 Provider Set +package auth + +import "github.com/google/wire" + +// AuthSet 提供 Auth 模块的所有组件 +var AuthSet = wire.NewSet( + dao.NewUserDAO, + dao.NewRoleDAO, +) +``` + +同步更新 `app/provider/wire.go`,在 `wire.Build` 中添加 `auth.AuthSet`。 + +**Step 7: Commit** ```bash git add backend/go-service/app/ @@ -370,7 +471,19 @@ type UserInfo struct { - `RequireRole(roles ...string)` — 角色检查中间件 - 将 UserID 和 Roles 注入 Gin Context -**Step 6: Commit** +**Step 6: 更新 Wire Provider** + +更新 `app/auth/provider.go`,添加 Service 层 Provider: + +```go +var AuthSet = wire.NewSet( + dao.NewUserDAO, + dao.NewRoleDAO, + service.NewAuthService, +) +``` + +**Step 7: Commit** ```bash git add backend/go-service/ @@ -386,6 +499,7 @@ git commit -m "feat(auth): 认证服务层(注册、登录、JWT、密码加 - Create: `backend/go-service/app/auth/controller/admin_auth_controller.go` - Create: `backend/go-service/app/auth/router.go` - Modify: `backend/go-service/cmd/server/main.go` — 注册 auth 路由 +- Modify: `backend/go-service/app/auth/provider.go` — 添加 Controller Provider **Step 1: 创建前台认证 Controller**