adi_dev_workflow 1.1.1 → 1.3.0

package/frameworks/skills/sdd-task-plan-expert-workspace/iteration-2/eval-2-spec-simples/without_skill/outputs/response.md

@@ -1,458 +1,458 @@
-# TASK PLAN — Adicionar Telefone ao Usuario v1
-
-## 1. Identificacao
-
-| Campo | Valor |
-|-------|-------|
-| **Feature** | Adicionar Telefone ao Modulo de Usuario |
-| **Versao** | v1 |
-| **Data** | 2026-03-08 |
-| **SPEC_TECH** | docs/feature-telefone-usuario/v1/spec_tech.md |
-| **Total de Tasks** | 7 |
-| **Estimativa Total** | ~2h |
-
-## 2. Resumo
-
-Adicionar campo opcional `telefone` a tabela `usuarios` e expor via gRPC em CreateUser, UpdateUser, GetUserLogged e na mensagem User. Inclui migracao de banco, atualizacao de queries SQLC, repository, service (com validacao), handler gRPC e proto.
-
----
-
-## 3. Tasks
-
-### TASK-1: Criar migracao de banco de dados
-
-**Camada:** Database
-**Arquivo a criar:**
-- `internal/db/migrations/003_add_telefone_usuarios.sql`
-
-**Descricao:**
-Criar nova migracao para adicionar a coluna `telefone` (TEXT, opcional/nullable) a tabela `usuarios`.
-
-**Conteudo:**
-```sql
-ALTER TABLE usuarios ADD COLUMN telefone TEXT;
-```
-
-**Observacoes:**
-- A coluna e opcional (sem NOT NULL), conforme SPEC_TECH
-- Seguir o padrao de numeracao sequencial (proxima e 003)
-- NAO editar migracoes existentes (001, 002)
-- Sem migracao down pois o SQLite nao suporta DROP COLUMN de forma nativa em versoes antigas
-
-**Criterio de aceite:**
-- Arquivo `003_add_telefone_usuarios.sql` criado
-- Migracao executa sem erro na inicializacao da aplicacao
-- Coluna `telefone` existe na tabela `usuarios` apos boot
-
-**Dependencias:** Nenhuma
-
----
-
-### TASK-2: Atualizar queries SQLC
-
-**Camada:** SQLC Queries
-**Arquivo a editar:**
-- `internal/db/sqlc/queries/user.sql`
-
-**Descricao:**
-Atualizar as queries `CreateUser` e `UpdateUser` para incluir a coluna `telefone`.
-
-**Alteracoes:**
-
-Na query `CreateUser`, adicionar `telefone` na lista de colunas e valores:
-```sql
--- name: CreateUser :one
-INSERT INTO usuarios (id, nome, email, senha_hash, endereco, telefone, data_criacao, data_atualizacao)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-RETURNING *;
-```
-
-Na query `UpdateUser`, adicionar `telefone` no SET:
-```sql
--- name: UpdateUser :one
-UPDATE usuarios
-SET nome             = ?,
-    email            = ?,
-    senha_hash       = ?,
-    endereco         = ?,
-    telefone         = ?,
-    data_atualizacao = ?
-WHERE id = ?
-RETURNING *;
-```
-
-**Observacoes:**
-- As queries `GetUserByID` e `GetUserByEmail` usam `SELECT *`, entao ja retornarao o campo `telefone` automaticamente
-- Apos editar, executar `make sqlc` para regenerar codigo em `internal/db/sqlc/`
-
-**Criterio de aceite:**
-- Queries atualizadas com coluna `telefone`
-- `make sqlc` executa sem erros
-- Codigo gerado em `internal/db/sqlc/` reflete o novo campo `Telefone`
-
-**Dependencias:** TASK-1
-
----
-
-### TASK-3: Atualizar Repository
-
-**Camada:** Repository
-**Arquivo a editar:**
-- `internal/repository/user_repository.go`
-
-**Descricao:**
-Adicionar campo `Phone` ao modelo `User` e atualizar mapeamentos entre SQLC e dominio.
-
-**Alteracoes:**
-
-1. Adicionar campo `Phone` na struct `User`:
-```go
-type User struct {
-    ID           string
-    Name         string
-    Email        string
-    PasswordHash string
-    Address      string
-    Phone        string    // novo campo
-    CreatedAt    time.Time
-    UpdatedAt    time.Time
-}
-```
-
-2. Atualizar metodo `Create` para mapear `Phone` -> `Telefone` nos params SQLC:
-```go
-params := sqlc.CreateUserParams{
-    ID:              user.ID,
-    Nome:            user.Name,
-    Email:           user.Email,
-    SenhaHash:       user.PasswordHash,
-    Endereco:        user.Address,
-    Telefone:        sql.NullString{String: user.Phone, Valid: user.Phone != ""},
-    DataCriacao:     user.CreatedAt,
-    DataAtualizacao: user.UpdatedAt,
-}
-```
-
-3. Atualizar metodo `Update` da mesma forma, adicionando `Telefone` nos params.
-
-4. Atualizar funcao `toUser` para mapear `Telefone` -> `Phone`:
-```go
-func toUser(u sqlc.Usuario) *User {
-    return &User{
-        ID:           u.ID,
-        Name:         u.Nome,
-        Email:        u.Email,
-        PasswordHash: u.SenhaHash,
-        Address:      u.Endereco,
-        Phone:        u.Telefone.String,  // NullString -> string
-        CreatedAt:    u.DataCriacao,
-        UpdatedAt:    u.DataAtualizacao,
-    }
-}
-```
-
-**Observacoes:**
-- O tipo SQLC gerado para `telefone` sera `sql.NullString` pois a coluna e nullable
-- Verificar o tipo exato apos `make sqlc` e ajustar o mapeamento se necessario
-
-**Criterio de aceite:**
-- Struct `User` possui campo `Phone string`
-- Create e Update mapeiam `Phone` corretamente para `Telefone` do SQLC
-- `toUser` mapeia `Telefone` de volta para `Phone`
-- Compilacao sem erros
-
-**Dependencias:** TASK-2
-
----
-
-### TASK-4: Atualizar Service
-
-**Camada:** Service
-**Arquivo a editar:**
-- `internal/service/user_service.go`
-
-**Descricao:**
-Adicionar campo `Phone` nos inputs e incluir validacao de tamanho (10-15 caracteres quando informado).
-
-**Alteracoes:**
-
-1. Adicionar nova variavel de erro:
-```go
-ErrInvalidPhone = errors.New("telefone deve ter entre 10 e 15 caracteres")
-```
-
-2. Adicionar campo `Phone` em `CreateUserInput`:
-```go
-type CreateUserInput struct {
-    Name     string
-    Email    string
-    Password string
-    Address  string
-    Phone    string  // novo, opcional
-}
-```
-
-3. Adicionar campo `Phone` em `UpdateUserInput`:
-```go
-type UpdateUserInput struct {
-    Name            *string
-    Email           *string
-    Address         *string
-    Phone           *string  // novo, opcional
-    NewPassword     *string
-    CurrentPassword *string
-}
-```
-
-4. Em `CreateUser`, adicionar validacao antes de criar o usuario:
-```go
-if input.Phone != "" {
-    if len(input.Phone) < 10 || len(input.Phone) > 15 {
-        return nil, ErrInvalidPhone
-    }
-}
-```
-E incluir `Phone: input.Phone` ao criar `repository.User`.
-
-5. Em `UpdateUser`:
-- Adicionar `input.Phone` na verificacao de "nenhum campo" (linha 171)
-- Adicionar bloco para processar phone:
-```go
-if input.Phone != nil {
-    if *input.Phone != "" && (len(*input.Phone) < 10 || len(*input.Phone) > 15) {
-        return nil, ErrInvalidPhone
-    }
-    currentUser.Phone = *input.Phone
-}
-```
-
-**Criterio de aceite:**
-- `CreateUserInput` e `UpdateUserInput` possuem campo Phone
-- Validacao de telefone (10-15 chars) funciona para CreateUser e UpdateUser
-- Telefone vazio e aceito (campo opcional)
-- `ErrInvalidPhone` definido e exportado
-
-**Dependencias:** TASK-3
-
----
-
-### TASK-5: Atualizar Proto (user.proto)
-
-**Camada:** Proto/gRPC
-**Arquivo a editar:**
-- `api/proto/v1/user.proto`
-
-**Descricao:**
-Adicionar campo `phone` nas mensagens proto relevantes.
-
-**Alteracoes:**
-
-1. Mensagem `User` — adicionar campo `phone` (field number 7):
-```proto
-message User {
-  string id         = 1;
-  string name       = 2;
-  string email      = 3;
-  string address    = 4;
-  string created_at = 5;
-  string updated_at = 6;
-  string phone      = 7;
-}
-```
-
-2. Mensagem `CreateUserRequest` — adicionar campo `phone` (field number 5):
-```proto
-message CreateUserRequest {
-  string name     = 1;
-  string email    = 2;
-  string password = 3;
-  string address  = 4;
-  string phone    = 5;
-}
-```
-
-3. Mensagem `UpdateUserRequest` — adicionar campo `phone` (field number 6):
-```proto
-message UpdateUserRequest {
-  optional string name             = 1;
-  optional string email            = 2;
-  optional string address          = 3;
-  optional string new_password     = 4;
-  optional string current_password = 5;
-  optional string phone            = 6;
-}
-```
-
-**Observacoes:**
-- Apos editar, executar `make proto` (ou `buf generate`) para regenerar codigo em `gen/`
-- NAO editar arquivos em `gen/` manualmente
-- `CreateUserResponse` e `LoginResponse` NAO precisam do campo phone (seguem o formato atual que retorna campos selecionados)
-
-**Criterio de aceite:**
-- `user.proto` atualizado com campo `phone` nas 3 mensagens
-- `make proto` executa sem erros
-- Codigo gerado em `gen/` reflete os novos campos
-
-**Dependencias:** Nenhuma (pode ser feita em paralelo com TASK-1 a TASK-4)
-
----
-
-### TASK-6: Atualizar Handler gRPC
-
-**Camada:** Handler
-**Arquivo a editar:**
-- `internal/handler/grpc/user_handler.go`
-
-**Descricao:**
-Atualizar os handlers para passar o campo `phone` entre proto e service, e incluir na conversao dominio->proto.
-
-**Alteracoes:**
-
-1. Em `CreateUser`, adicionar `Phone` ao input:
-```go
-user, err := h.userService.CreateUser(ctx, service.CreateUserInput{
-    Name:     req.GetName(),
-    Email:    req.GetEmail(),
-    Password: req.GetPassword(),
-    Address:  req.GetAddress(),
-    Phone:    req.GetPhone(),
-})
-```
-
-2. Em `UpdateUser`, adicionar bloco para phone:
-```go
-if req.Phone != nil {
-    input.Phone = req.Phone
-}
-```
-
-3. Em `domainUserToProto`, adicionar mapeamento de `Phone`:
-```go
-func domainUserToProto(user *repository.User) *pb.User {
-    return &pb.User{
-        Id:        user.ID,
-        Name:      user.Name,
-        Email:     user.Email,
-        Address:   user.Address,
-        Phone:     user.Phone,
-        CreatedAt: user.CreatedAt.Format(time.RFC3339),
-        UpdatedAt: user.UpdatedAt.Format(time.RFC3339),
-    }
-}
-```
-
-4. Em `mapServiceError`, adicionar mapeamento para `ErrInvalidPhone`:
-```go
-case errors.Is(err, service.ErrInvalidPhone):
-    return status.Errorf(codes.InvalidArgument, "%v", err)
-```
-
-**Criterio de aceite:**
-- CreateUser passa `Phone` do request para o service
-- UpdateUser passa `Phone` do request para o service
-- `domainUserToProto` inclui `Phone`
-- `mapServiceError` trata `ErrInvalidPhone`
-- Compilacao sem erros
-
-**Dependencias:** TASK-4, TASK-5
-
----
-
-### TASK-7: Atualizar Testes
-
-**Camada:** Testes
-**Arquivos a editar:**
-- `internal/service/user_service_test.go`
-- `internal/handler/grpc/user_handler_test.go`
-
-**Descricao:**
-Adicionar testes para o novo campo `phone` e atualizar testes existentes que precisam refletir a presenca do campo.
-
-**Alteracoes em `user_service_test.go`:**
-
-1. Adicionar teste `TestCreateUser_WithPhone_Success` — cria usuario com telefone valido
-2. Adicionar teste `TestCreateUser_PhoneTooShort` — telefone com menos de 10 caracteres deve retornar `ErrInvalidPhone`
-3. Adicionar teste `TestCreateUser_PhoneTooLong` — telefone com mais de 15 caracteres deve retornar `ErrInvalidPhone`
-4. Adicionar teste `TestCreateUser_PhoneEmpty_Success` — telefone vazio e aceito (opcional)
-5. Adicionar teste `TestUpdateUser_PhoneOnly` — atualiza somente telefone
-6. Adicionar teste `TestUpdateUser_PhoneInvalid` — telefone invalido no update retorna `ErrInvalidPhone`
-7. Adicionar caso `"telefone invalido"` na table-driven `TestCreateUser_ValidationTableDriven`
-
-**Alteracoes em `user_handler_test.go`:**
-
-1. Adicionar teste `TestUserHandler_CreateUser_WithPhone` — verifica passagem do phone do proto para o service
-2. Adicionar teste `TestUserHandler_UpdateUser_PhoneOnly` — verifica atualizacao de phone
-3. Atualizar `TestDomainUserToProto` para incluir e validar campo `Phone`
-4. Adicionar `ErrInvalidPhone` ao `TestMapServiceError_AllErrors` com codigo `InvalidArgument`
-5. Atualizar testes existentes que criam `repository.User` para incluir campo `Phone` onde relevante (evitar warnings de campos faltantes)
-
-**Criterio de aceite:**
-- Todos os testes novos passam
-- Testes existentes continuam passando
-- Cobertura de: phone valido, phone vazio (opcional), phone curto demais, phone longo demais
-- `make test` passa sem erros
-
-**Dependencias:** TASK-4, TASK-6
-
----
-
-## 4. Ordem de Execucao
-
-```
-TASK-1 (migracao) ──> TASK-2 (sqlc queries) ──> TASK-3 (repository) ──> TASK-4 (service) ──┐
-                                                                                             ├──> TASK-6 (handler) ──> TASK-7 (testes)
-TASK-5 (proto) ─────────────────────────────────────────────────────────────────────────────┘
-```
-
-**Caminho critico:** TASK-1 -> TASK-2 -> TASK-3 -> TASK-4 -> TASK-6 -> TASK-7
-
-**Paralelismo possivel:** TASK-5 pode ser executada em paralelo com TASK-1 a TASK-4.
-
----
-
-## 5. Comandos de Geracao/Verificacao
-
-Apos as alteracoes, executar na seguinte ordem:
-
-```bash
-# 1. Gerar codigo proto (apos TASK-5)
-make proto
-
-# 2. Gerar codigo SQLC (apos TASK-2)
-make sqlc
-
-# 3. Compilar para verificar erros
-make build
-
-# 4. Rodar todos os testes
-make test
-
-# 5. Lint dos protobufs
-make lint
-```
-
----
-
-## 6. Arquivos Impactados (Resumo)
-
-| Arquivo | Acao |
-|---------|------|
-| `internal/db/migrations/003_add_telefone_usuarios.sql` | Criar |
-| `internal/db/sqlc/queries/user.sql` | Editar |
-| `internal/db/sqlc/` (gerado) | Regenerar via `make sqlc` |
-| `api/proto/v1/user.proto` | Editar |
-| `gen/proto/v1/` (gerado) | Regenerar via `make proto` |
-| `internal/repository/user_repository.go` | Editar |
-| `internal/service/user_service.go` | Editar |
-| `internal/handler/grpc/user_handler.go` | Editar |
-| `internal/service/user_service_test.go` | Editar |
-| `internal/handler/grpc/user_handler_test.go` | Editar |
-
----
-
-## 7. Riscos e Observacoes
-
-1. **Tipo SQLC para coluna nullable:** A coluna `telefone` e nullable (sem NOT NULL), entao o SQLC gerara `sql.NullString`. O mapeamento no repository precisa tratar isso corretamente (NullString <-> string).
-2. **Migracao automatica:** A migracao executa no boot da aplicacao. Verificar que o numero sequencial 003 esta correto e nao conflita com outras migracoes em desenvolvimento.
-3. **Compatibilidade retroativa do proto:** Adicionar campos com novos field numbers (7, 5, 6) e retrocompativel com clientes existentes. Clientes antigos simplesmente ignorarao o campo `phone`.
-4. **Testes de integracao:** O arquivo `internal/e2e/user_e2e_test.go` pode precisar de atualizacao, mas nao foi incluido no escopo da SPEC_TECH. Avaliar se e necessario.
+# TASK PLAN — Adicionar Telefone ao Usuario v1
+
+## 1. Identificacao
+
+| Campo | Valor |
+|-------|-------|
+| **Feature** | Adicionar Telefone ao Modulo de Usuario |
+| **Versao** | v1 |
+| **Data** | 2026-03-08 |
+| **SPEC_TECH** | docs/feature-telefone-usuario/v1/spec_tech.md |
+| **Total de Tasks** | 7 |
+| **Estimativa Total** | ~2h |
+
+## 2. Resumo
+
+Adicionar campo opcional `telefone` a tabela `usuarios` e expor via gRPC em CreateUser, UpdateUser, GetUserLogged e na mensagem User. Inclui migracao de banco, atualizacao de queries SQLC, repository, service (com validacao), handler gRPC e proto.
+
+---
+
+## 3. Tasks
+
+### TASK-1: Criar migracao de banco de dados
+
+**Camada:** Database
+**Arquivo a criar:**
+- `internal/db/migrations/003_add_telefone_usuarios.sql`
+
+**Descricao:**
+Criar nova migracao para adicionar a coluna `telefone` (TEXT, opcional/nullable) a tabela `usuarios`.
+
+**Conteudo:**
+```sql
+ALTER TABLE usuarios ADD COLUMN telefone TEXT;
+```
+
+**Observacoes:**
+- A coluna e opcional (sem NOT NULL), conforme SPEC_TECH
+- Seguir o padrao de numeracao sequencial (proxima e 003)
+- NAO editar migracoes existentes (001, 002)
+- Sem migracao down pois o SQLite nao suporta DROP COLUMN de forma nativa em versoes antigas
+
+**Criterio de aceite:**
+- Arquivo `003_add_telefone_usuarios.sql` criado
+- Migracao executa sem erro na inicializacao da aplicacao
+- Coluna `telefone` existe na tabela `usuarios` apos boot
+
+**Dependencias:** Nenhuma
+
+---
+
+### TASK-2: Atualizar queries SQLC
+
+**Camada:** SQLC Queries
+**Arquivo a editar:**
+- `internal/db/sqlc/queries/user.sql`
+
+**Descricao:**
+Atualizar as queries `CreateUser` e `UpdateUser` para incluir a coluna `telefone`.
+
+**Alteracoes:**
+
+Na query `CreateUser`, adicionar `telefone` na lista de colunas e valores:
+```sql
+-- name: CreateUser :one
+INSERT INTO usuarios (id, nome, email, senha_hash, endereco, telefone, data_criacao, data_atualizacao)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+RETURNING *;
+```
+
+Na query `UpdateUser`, adicionar `telefone` no SET:
+```sql
+-- name: UpdateUser :one
+UPDATE usuarios
+SET nome             = ?,
+    email            = ?,
+    senha_hash       = ?,
+    endereco         = ?,
+    telefone         = ?,
+    data_atualizacao = ?
+WHERE id = ?
+RETURNING *;
+```
+
+**Observacoes:**
+- As queries `GetUserByID` e `GetUserByEmail` usam `SELECT *`, entao ja retornarao o campo `telefone` automaticamente
+- Apos editar, executar `make sqlc` para regenerar codigo em `internal/db/sqlc/`
+
+**Criterio de aceite:**
+- Queries atualizadas com coluna `telefone`
+- `make sqlc` executa sem erros
+- Codigo gerado em `internal/db/sqlc/` reflete o novo campo `Telefone`
+
+**Dependencias:** TASK-1
+
+---
+
+### TASK-3: Atualizar Repository
+
+**Camada:** Repository
+**Arquivo a editar:**
+- `internal/repository/user_repository.go`
+
+**Descricao:**
+Adicionar campo `Phone` ao modelo `User` e atualizar mapeamentos entre SQLC e dominio.
+
+**Alteracoes:**
+
+1. Adicionar campo `Phone` na struct `User`:
+```go
+type User struct {
+    ID           string
+    Name         string
+    Email        string
+    PasswordHash string
+    Address      string
+    Phone        string    // novo campo
+    CreatedAt    time.Time
+    UpdatedAt    time.Time
+}
+```
+
+2. Atualizar metodo `Create` para mapear `Phone` -> `Telefone` nos params SQLC:
+```go
+params := sqlc.CreateUserParams{
+    ID:              user.ID,
+    Nome:            user.Name,
+    Email:           user.Email,
+    SenhaHash:       user.PasswordHash,
+    Endereco:        user.Address,
+    Telefone:        sql.NullString{String: user.Phone, Valid: user.Phone != ""},
+    DataCriacao:     user.CreatedAt,
+    DataAtualizacao: user.UpdatedAt,
+}
+```
+
+3. Atualizar metodo `Update` da mesma forma, adicionando `Telefone` nos params.
+
+4. Atualizar funcao `toUser` para mapear `Telefone` -> `Phone`:
+```go
+func toUser(u sqlc.Usuario) *User {
+    return &User{
+        ID:           u.ID,
+        Name:         u.Nome,
+        Email:        u.Email,
+        PasswordHash: u.SenhaHash,
+        Address:      u.Endereco,
+        Phone:        u.Telefone.String,  // NullString -> string
+        CreatedAt:    u.DataCriacao,
+        UpdatedAt:    u.DataAtualizacao,
+    }
+}
+```
+
+**Observacoes:**
+- O tipo SQLC gerado para `telefone` sera `sql.NullString` pois a coluna e nullable
+- Verificar o tipo exato apos `make sqlc` e ajustar o mapeamento se necessario
+
+**Criterio de aceite:**
+- Struct `User` possui campo `Phone string`
+- Create e Update mapeiam `Phone` corretamente para `Telefone` do SQLC
+- `toUser` mapeia `Telefone` de volta para `Phone`
+- Compilacao sem erros
+
+**Dependencias:** TASK-2
+
+---
+
+### TASK-4: Atualizar Service
+
+**Camada:** Service
+**Arquivo a editar:**
+- `internal/service/user_service.go`
+
+**Descricao:**
+Adicionar campo `Phone` nos inputs e incluir validacao de tamanho (10-15 caracteres quando informado).
+
+**Alteracoes:**
+
+1. Adicionar nova variavel de erro:
+```go
+ErrInvalidPhone = errors.New("telefone deve ter entre 10 e 15 caracteres")
+```
+
+2. Adicionar campo `Phone` em `CreateUserInput`:
+```go
+type CreateUserInput struct {
+    Name     string
+    Email    string
+    Password string
+    Address  string
+    Phone    string  // novo, opcional
+}
+```
+
+3. Adicionar campo `Phone` em `UpdateUserInput`:
+```go
+type UpdateUserInput struct {
+    Name            *string
+    Email           *string
+    Address         *string
+    Phone           *string  // novo, opcional
+    NewPassword     *string
+    CurrentPassword *string
+}
+```
+
+4. Em `CreateUser`, adicionar validacao antes de criar o usuario:
+```go
+if input.Phone != "" {
+    if len(input.Phone) < 10 || len(input.Phone) > 15 {
+        return nil, ErrInvalidPhone
+    }
+}
+```
+E incluir `Phone: input.Phone` ao criar `repository.User`.
+
+5. Em `UpdateUser`:
+- Adicionar `input.Phone` na verificacao de "nenhum campo" (linha 171)
+- Adicionar bloco para processar phone:
+```go
+if input.Phone != nil {
+    if *input.Phone != "" && (len(*input.Phone) < 10 || len(*input.Phone) > 15) {
+        return nil, ErrInvalidPhone
+    }
+    currentUser.Phone = *input.Phone
+}
+```
+
+**Criterio de aceite:**
+- `CreateUserInput` e `UpdateUserInput` possuem campo Phone
+- Validacao de telefone (10-15 chars) funciona para CreateUser e UpdateUser
+- Telefone vazio e aceito (campo opcional)
+- `ErrInvalidPhone` definido e exportado
+
+**Dependencias:** TASK-3
+
+---
+
+### TASK-5: Atualizar Proto (user.proto)
+
+**Camada:** Proto/gRPC
+**Arquivo a editar:**
+- `api/proto/v1/user.proto`
+
+**Descricao:**
+Adicionar campo `phone` nas mensagens proto relevantes.
+
+**Alteracoes:**
+
+1. Mensagem `User` — adicionar campo `phone` (field number 7):
+```proto
+message User {
+  string id         = 1;
+  string name       = 2;
+  string email      = 3;
+  string address    = 4;
+  string created_at = 5;
+  string updated_at = 6;
+  string phone      = 7;
+}
+```
+
+2. Mensagem `CreateUserRequest` — adicionar campo `phone` (field number 5):
+```proto
+message CreateUserRequest {
+  string name     = 1;
+  string email    = 2;
+  string password = 3;
+  string address  = 4;
+  string phone    = 5;
+}
+```
+
+3. Mensagem `UpdateUserRequest` — adicionar campo `phone` (field number 6):
+```proto
+message UpdateUserRequest {
+  optional string name             = 1;
+  optional string email            = 2;
+  optional string address          = 3;
+  optional string new_password     = 4;
+  optional string current_password = 5;
+  optional string phone            = 6;
+}
+```
+
+**Observacoes:**
+- Apos editar, executar `make proto` (ou `buf generate`) para regenerar codigo em `gen/`
+- NAO editar arquivos em `gen/` manualmente
+- `CreateUserResponse` e `LoginResponse` NAO precisam do campo phone (seguem o formato atual que retorna campos selecionados)
+
+**Criterio de aceite:**
+- `user.proto` atualizado com campo `phone` nas 3 mensagens
+- `make proto` executa sem erros
+- Codigo gerado em `gen/` reflete os novos campos
+
+**Dependencias:** Nenhuma (pode ser feita em paralelo com TASK-1 a TASK-4)
+
+---
+
+### TASK-6: Atualizar Handler gRPC
+
+**Camada:** Handler
+**Arquivo a editar:**
+- `internal/handler/grpc/user_handler.go`
+
+**Descricao:**
+Atualizar os handlers para passar o campo `phone` entre proto e service, e incluir na conversao dominio->proto.
+
+**Alteracoes:**
+
+1. Em `CreateUser`, adicionar `Phone` ao input:
+```go
+user, err := h.userService.CreateUser(ctx, service.CreateUserInput{
+    Name:     req.GetName(),
+    Email:    req.GetEmail(),
+    Password: req.GetPassword(),
+    Address:  req.GetAddress(),
+    Phone:    req.GetPhone(),
+})
+```
+
+2. Em `UpdateUser`, adicionar bloco para phone:
+```go
+if req.Phone != nil {
+    input.Phone = req.Phone
+}
+```
+
+3. Em `domainUserToProto`, adicionar mapeamento de `Phone`:
+```go
+func domainUserToProto(user *repository.User) *pb.User {
+    return &pb.User{
+        Id:        user.ID,
+        Name:      user.Name,
+        Email:     user.Email,
+        Address:   user.Address,
+        Phone:     user.Phone,
+        CreatedAt: user.CreatedAt.Format(time.RFC3339),
+        UpdatedAt: user.UpdatedAt.Format(time.RFC3339),
+    }
+}
+```
+
+4. Em `mapServiceError`, adicionar mapeamento para `ErrInvalidPhone`:
+```go
+case errors.Is(err, service.ErrInvalidPhone):
+    return status.Errorf(codes.InvalidArgument, "%v", err)
+```
+
+**Criterio de aceite:**
+- CreateUser passa `Phone` do request para o service
+- UpdateUser passa `Phone` do request para o service
+- `domainUserToProto` inclui `Phone`
+- `mapServiceError` trata `ErrInvalidPhone`
+- Compilacao sem erros
+
+**Dependencias:** TASK-4, TASK-5
+
+---
+
+### TASK-7: Atualizar Testes
+
+**Camada:** Testes
+**Arquivos a editar:**
+- `internal/service/user_service_test.go`
+- `internal/handler/grpc/user_handler_test.go`
+
+**Descricao:**
+Adicionar testes para o novo campo `phone` e atualizar testes existentes que precisam refletir a presenca do campo.
+
+**Alteracoes em `user_service_test.go`:**
+
+1. Adicionar teste `TestCreateUser_WithPhone_Success` — cria usuario com telefone valido
+2. Adicionar teste `TestCreateUser_PhoneTooShort` — telefone com menos de 10 caracteres deve retornar `ErrInvalidPhone`
+3. Adicionar teste `TestCreateUser_PhoneTooLong` — telefone com mais de 15 caracteres deve retornar `ErrInvalidPhone`
+4. Adicionar teste `TestCreateUser_PhoneEmpty_Success` — telefone vazio e aceito (opcional)
+5. Adicionar teste `TestUpdateUser_PhoneOnly` — atualiza somente telefone
+6. Adicionar teste `TestUpdateUser_PhoneInvalid` — telefone invalido no update retorna `ErrInvalidPhone`
+7. Adicionar caso `"telefone invalido"` na table-driven `TestCreateUser_ValidationTableDriven`
+
+**Alteracoes em `user_handler_test.go`:**
+
+1. Adicionar teste `TestUserHandler_CreateUser_WithPhone` — verifica passagem do phone do proto para o service
+2. Adicionar teste `TestUserHandler_UpdateUser_PhoneOnly` — verifica atualizacao de phone
+3. Atualizar `TestDomainUserToProto` para incluir e validar campo `Phone`
+4. Adicionar `ErrInvalidPhone` ao `TestMapServiceError_AllErrors` com codigo `InvalidArgument`
+5. Atualizar testes existentes que criam `repository.User` para incluir campo `Phone` onde relevante (evitar warnings de campos faltantes)
+
+**Criterio de aceite:**
+- Todos os testes novos passam
+- Testes existentes continuam passando
+- Cobertura de: phone valido, phone vazio (opcional), phone curto demais, phone longo demais
+- `make test` passa sem erros
+
+**Dependencias:** TASK-4, TASK-6
+
+---
+
+## 4. Ordem de Execucao
+
+```
+TASK-1 (migracao) ──> TASK-2 (sqlc queries) ──> TASK-3 (repository) ──> TASK-4 (service) ──┐
+                                                                                             ├──> TASK-6 (handler) ──> TASK-7 (testes)
+TASK-5 (proto) ─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Caminho critico:** TASK-1 -> TASK-2 -> TASK-3 -> TASK-4 -> TASK-6 -> TASK-7
+
+**Paralelismo possivel:** TASK-5 pode ser executada em paralelo com TASK-1 a TASK-4.
+
+---
+
+## 5. Comandos de Geracao/Verificacao
+
+Apos as alteracoes, executar na seguinte ordem:
+
+```bash
+# 1. Gerar codigo proto (apos TASK-5)
+make proto
+
+# 2. Gerar codigo SQLC (apos TASK-2)
+make sqlc
+
+# 3. Compilar para verificar erros
+make build
+
+# 4. Rodar todos os testes
+make test
+
+# 5. Lint dos protobufs
+make lint
+```
+
+---
+
+## 6. Arquivos Impactados (Resumo)
+
+| Arquivo | Acao |
+|---------|------|
+| `internal/db/migrations/003_add_telefone_usuarios.sql` | Criar |
+| `internal/db/sqlc/queries/user.sql` | Editar |
+| `internal/db/sqlc/` (gerado) | Regenerar via `make sqlc` |
+| `api/proto/v1/user.proto` | Editar |
+| `gen/proto/v1/` (gerado) | Regenerar via `make proto` |
+| `internal/repository/user_repository.go` | Editar |
+| `internal/service/user_service.go` | Editar |
+| `internal/handler/grpc/user_handler.go` | Editar |
+| `internal/service/user_service_test.go` | Editar |
+| `internal/handler/grpc/user_handler_test.go` | Editar |
+
+---
+
+## 7. Riscos e Observacoes
+
+1. **Tipo SQLC para coluna nullable:** A coluna `telefone` e nullable (sem NOT NULL), entao o SQLC gerara `sql.NullString`. O mapeamento no repository precisa tratar isso corretamente (NullString <-> string).
+2. **Migracao automatica:** A migracao executa no boot da aplicacao. Verificar que o numero sequencial 003 esta correto e nao conflita com outras migracoes em desenvolvimento.
+3. **Compatibilidade retroativa do proto:** Adicionar campos com novos field numbers (7, 5, 6) e retrocompativel com clientes existentes. Clientes antigos simplesmente ignorarao o campo `phone`.
+4. **Testes de integracao:** O arquivo `internal/e2e/user_e2e_test.go` pode precisar de atualizacao, mas nao foi incluido no escopo da SPEC_TECH. Avaliar se e necessario.