# 转岗计划 · 第 4 周学习计划（注册登录 + JWT + 权限 → 项目一：团队任务看板） > 所属阶段：第 1 个月 Go 全栈基础的收官周。总纲见同目录 `README.md`，上周计划 `week03-postgresql.md`。 目标：做出第一个能写进简历的全栈项目“团队任务看板”：用户注册登录，创建看板、邀请成员，看板里的任务按“待办 / 进行中 / 已完成”分三列，只有看板成员能看和改，只有看板所有者能管理成员。 前置条件：第 3 周的 `todo-api` 已经能用 PostgreSQL 存储，迁移、sqlc、事务都跑通。 做法：新建 `task-board/` 目录，把 `todo-api/backend` 的骨架（`docker-compose.yml`、`Makefile`、`sqlc.yaml`、`internal/config`、`internal/middleware`、`handler/response.go`、`main.go` 的启动和优雅关机代码）复制过去再改，业务部分重新写。 本周比前三周多了一个“service 层”：handler 只负责解析请求和返回响应，权限判断和业务规则放在 service 里，方便测试，也是第 2、3 个月写 Agent 服务时会沿用的分层方式。 参考资料： - bcrypt：https://pkg.go.dev/golang.org/x/crypto/bcrypt - golang-jwt：https://github.com/golang-jwt/jwt - JWT 介绍：https://jwt.io/introduction --- ## 最终项目结构 ``` task-board/ ├── README.md # 项目说明（作品集用） ├── backend/ │ ├── go.mod # module task-board │ ├── main.go │ ├── Makefile │ ├── docker-compose.yml │ ├── .env.example # DATABASE_URL、JWT_SECRET、JWT_TTL │ ├── sqlc.yaml │ ├── api.http │ ├── db/ │ │ ├── migrations/ │ │ │ ├── 000001_init.up.sql │ │ │ └── 000001_init.down.sql │ │ ├── queries/ │ │ │ ├── users.sql │ │ │ ├── boards.sql │ │ │ └── tasks.sql │ │ └── seed.sql # 演示数据 │ └── internal/ │ ├── config/config.go │ ├── db/ # sqlc 生成 │ ├── auth/ │ │ ├── password.go # bcrypt │ │ ├── password_test.go │ │ ├── jwt.go # 签发和解析令牌 │ │ └── jwt_test.go │ ├── service/ │ │ ├── errors.go # 业务错误：未找到、无权限、冲突 │ │ ├── user_service.go │ │ ├── board_service.go │ │ ├── task_service.go │ │ └── task_service_test.go │ ├── handler/ │ │ ├── response.go │ │ ├── errors.go # 业务错误 → HTTP 状态码 │ │ ├── auth_handler.go │ │ ├── board_handler.go │ │ ├── task_handler.go │ │ └── handler_test.go # 权限相关接口测试 │ ├── middleware/ │ │ ├── logger.go │ │ ├── cors.go │ │ ├── recovery.go │ │ └── auth.go # RequireAuth │ └── router/router.go └── frontend/ ├── .env.development └── src/ ├── api/ │ ├── client.ts # 统一请求：带令牌、处理 401 │ ├── auth.ts │ ├── boards.ts │ └── tasks.ts ├── types/index.ts ├── store/auth.ts # 登录状态（React 用 Context 或 zustand，Vue 用 Pinia） ├── router.tsx # 路由和登录守卫 ├── pages/ │ ├── LoginPage.tsx │ ├── RegisterPage.tsx │ ├── BoardsPage.tsx │ └── BoardDetailPage.tsx └── components/ ├── TaskColumn.tsx ├── TaskCard.tsx ├── TaskEditor.tsx └── MemberPanel.tsx ``` Vue 的话把 `.tsx` 换成 `.vue`，`router.tsx` 换成 `router.ts`。 ## 数据库表 ``` users id BIGSERIAL PRIMARY KEY email TEXT NOT NULL UNIQUE name TEXT NOT NULL password_hash TEXT NOT NULL created_at TIMESTAMPTZ NOT NULL DEFAULT now() boards id BIGSERIAL PRIMARY KEY name TEXT NOT NULL owner_id BIGINT NOT NULL REFERENCES users(id) created_at TIMESTAMPTZ NOT NULL DEFAULT now() board_members board_id BIGINT REFERENCES boards(id) ON DELETE CASCADE user_id BIGINT REFERENCES users(id) ON DELETE CASCADE role TEXT NOT NULL CHECK (role IN ('owner', 'member')) joined_at TIMESTAMPTZ NOT NULL DEFAULT now() PRIMARY KEY (board_id, user_id) tasks id BIGSERIAL PRIMARY KEY board_id BIGINT NOT NULL REFERENCES boards(id) ON DELETE CASCADE title TEXT NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100) description TEXT NOT NULL DEFAULT '' status TEXT NOT NULL DEFAULT 'todo' CHECK (status IN ('todo', 'doing', 'done')) position INT NOT NULL DEFAULT 0 -- 同一列里的排序 assignee_id BIGINT REFERENCES users(id) ON DELETE SET NULL created_by BIGINT NOT NULL REFERENCES users(id) created_at TIMESTAMPTZ NOT NULL DEFAULT now() updated_at TIMESTAMPTZ NOT NULL DEFAULT now() 索引：tasks(board_id, status, position)、board_members(user_id) ``` ## 接口设计 除注册和登录外，所有接口都需要请求头 `Authorization: Bearer `。 | 方法 | 路径 | 说明 | 权限 | 成功状态码 | | --- | --- | --- | --- | --- | | POST | `/api/auth/register` | 注册 `{email, name, password}` | 公开 | 201 | | POST | `/api/auth/login` | 登录，返回 `{token, user}` | 公开 | 200 | | GET | `/api/me` | 当前用户 | 登录 | 200 | | GET | `/api/boards` | 我参与的看板 | 登录 | 200 | | POST | `/api/boards` | 新建看板，创建者自动成为 owner | 登录 | 201 | | GET | `/api/boards/:boardId` | 看板详情 + 成员列表 | 成员 | 200 | | POST | `/api/boards/:boardId/members` | 按邮箱添加成员 | owner | 201 | | DELETE | `/api/boards/:boardId/members/:userId` | 移除成员（不能移除 owner） | owner | 204 | | GET | `/api/boards/:boardId/tasks` | 任务列表，按状态分组 | 成员 | 200 | | POST | `/api/boards/:boardId/tasks` | 新建任务 | 成员 | 201 | | PATCH | `/api/boards/:boardId/tasks/:taskId` | 修改标题、描述、负责人 | 成员 | 200 | | POST | `/api/boards/:boardId/tasks/:taskId/move` | 移动到某列某位置 `{status, position}` | 成员 | 200 | | DELETE | `/api/boards/:boardId/tasks/:taskId` | 删除任务 | 创建者或 owner | 204 | 错误约定：未登录或令牌无效 401；登录了但不是成员，统一返回 404（不暴露看板是否存在）；是成员但没有 owner 权限 403；邮箱已注册 409；参数错误 400。 --- ## 第 1 天：项目初始化和表设计 **学习内容** - 从需求推出表结构：先列出“谁、有什么、能做什么”，再画表。 - 权限放在哪张表：用户和看板是多对多，角色存在关联表 `board_members` 上。 - 复习第 3 周的迁移和 sqlc。 **要建的文件** - 复制骨架到 `task-board/backend/`，`go mod init task-board`，改掉 import 路径。 - `docker-compose.yml`：数据库名、用户名改成 `board`；为了不和 `todo-api` 冲突，端口映射用 `5433:5432`。 - `db/migrations/000001_init.up.sql`：按上面“数据库表”建 4 张表和索引。 - `db/migrations/000001_init.down.sql`：按依赖顺序反向删除。 - `db/queries/users.sql`：`CreateUser :one`、`GetUserByEmail :one`、`GetUserByID :one`。 - `db/queries/boards.sql`：`CreateBoard :one`、`AddBoardMember :exec`、`RemoveBoardMember :execrows`、`GetMemberRole :one`（按 `board_id, user_id` 查角色）、`ListBoardsByUser :many`（`JOIN board_members`）、`ListBoardMembers :many`（`JOIN users`）。 - `db/queries/tasks.sql`：`ListTasksByBoard :many`（按 `status, position` 排序）、`GetTask :one`（条件同时带 `board_id`，防止跨看板访问）、`CreateTask :one`、`UpdateTask :one`、`ShiftPositions :exec`、`MoveTask :one`、`DeleteTask :execrows`。 - 画一张 ER 图（mermaid `erDiagram`），先写在 `task-board/README.md` 里。 **运行方式**：`make db-up && make migrate-up && make sqlc && go build ./...` **完成标准**：能说清楚为什么 `GetTask` 的条件里要带 `board_id`，以及为什么角色放在 `board_members` 而不是 `users` 上。 --- ## 第 2 天：密码加密、注册和登录 **学习内容** - 为什么密码只能存哈希，为什么用 bcrypt 这种“故意慢”的算法，而不是 MD5、SHA256。 - JWT 的结构：头部、载荷、签名；载荷只是 Base64 编码，**不加密**，不能放敏感信息。 - 令牌过期时间；签名密钥从环境变量读，不能写在代码里。 - 依赖：`go get golang.org/x/crypto/bcrypt github.com/golang-jwt/jwt/v5`。 **要建的文件** - `internal/auth/password.go`： - `func HashPassword(plain string) (string, error)` - `func CheckPassword(hash, plain string) bool` - `internal/auth/jwt.go`： - ``type Claims struct { UserID int64 `json:"uid"`; jwt.RegisteredClaims }`` - `type TokenManager struct { secret []byte; ttl time.Duration }` - `func NewTokenManager(secret string, ttl time.Duration) *TokenManager` - `func (m *TokenManager) Issue(userID int64) (string, error)`：签发 HS256 令牌，写入过期时间。 - `func (m *TokenManager) Parse(token string) (int64, error)`：校验签名算法、过期时间，返回用户 ID。 - `internal/auth/password_test.go`、`jwt_test.go`：正确密码通过、错误密码失败；过期令牌、被篡改的令牌、用别的密钥签的令牌都解析失败。 - `internal/service/errors.go`：`ErrNotFound`、`ErrForbidden`、`ErrConflict`、`ErrInvalidCredentials`、`ErrValidation`。 - `internal/service/user_service.go`： - `func (s *UserService) Register(ctx, email, name, password string) (User, error)`：邮箱格式和密码长度（至少 8 位）校验，邮箱转小写，唯一约束冲突转成 `ErrConflict`。 - `func (s *UserService) Login(ctx, email, password string) (token string, user User, err error)`：邮箱不存在和密码错误都返回同一个 `ErrInvalidCredentials`，不让人试出哪些邮箱注册过。 - `internal/handler/errors.go`：`func writeError(c *gin.Context, err error)`，用 `errors.Is` 把业务错误映射到 400 / 401 / 403 / 404 / 409。 - `internal/handler/auth_handler.go`：`Register`、`Login`。 - `internal/config/config.go`：新增 `JWTSecret`（必填，少于 32 个字符时启动报错）、`JWTTTL`（默认 2 小时）。 **运行方式**：`go test ./internal/auth -v`；`api.http` 里写好注册、重复注册、登录、错误密码登录四个请求。 **完成标准**：能说清楚 JWT 和服务端 Session 各自的优缺点，以及“JWT 签发后很难提前作废”这个问题一般怎么缓解（短过期时间 + 刷新令牌，本周不实现）。 --- ## 第 3 天：鉴权中间件和当前用户 **学习内容** - Gin 中间件里校验令牌，把用户 ID 放进 `gin.Context`，后面的 handler 直接取。 - 401 和 403 的区别。 - 前端令牌存哪：`localStorage`（简单，但怕 XSS）和 `httpOnly` Cookie（防 XSS，但要处理 CSRF）。本项目用 `Authorization` 请求头 + `localStorage`，在 README 里写清楚这个取舍。 **要建的文件** - `internal/middleware/auth.go`： - `func RequireAuth(tm *auth.TokenManager) gin.HandlerFunc`：没有请求头、格式不对、令牌无效都返回 401 并 `c.Abort()`。 - `func CurrentUserID(c *gin.Context) int64`：从上下文取用户 ID。 - `internal/handler/auth_handler.go`：新增 `Me`，返回当前用户（不返回 `password_hash`，用单独的响应结构体）。 - `internal/router/router.go`： - `/api/auth/*` 不加鉴权。 - 其余接口挂在 `authed := api.Group("", middleware.RequireAuth(tm))` 下。 - 更新 `api.http`：用变量保存登录得到的令牌，后续请求自动带上。 **运行方式**：`go run .`，不带令牌访问 `/api/me` 返回 401，带上令牌返回当前用户。 **完成标准**：能画出“请求 → RequireAuth → handler → service → 数据库”的流程，说清楚每一层负责什么。 --- ## 第 4 天：看板和成员权限 **学习内容** - 权限判断放在 service 层：每个操作先查当前用户在这个看板的角色，再决定能不能做。 - 不是成员时返回 404 而不是 403 的原因：不暴露看板是否存在。 - 创建看板要用事务：插入看板和插入 owner 成员必须一起成功。 **要建的文件** - `internal/service/board_service.go`： - `func (s *BoardService) requireRole(ctx, boardID, userID int64, need string) (role string, err error)`：查不到成员关系返回 `ErrNotFound`；需要 owner 但只是 member 返回 `ErrForbidden`。 - `Create(ctx, userID, name)`：事务里插入看板 + 把自己加为 owner。 - `ListMine(ctx, userID)`、`Get(ctx, userID, boardID)`（含成员列表）。 - `AddMember(ctx, userID, boardID, email)`：仅 owner；邮箱不存在返回 `ErrNotFound`；已是成员返回 `ErrConflict`。 - `RemoveMember(ctx, userID, boardID, targetUserID)`：仅 owner；不能移除 owner 自己。 - `internal/handler/board_handler.go`：对应 5 个接口，路径参数解析失败返回 400。 - 更新 `router.go` 和 `api.http`：准备两个账号 A、B，测“A 建看板 → B 看不到 → A 添加 B → B 能看到 → B 尝试添加成员得到 403”。 **完成标准**：能说清楚“为什么权限判断不能只在前端做”，以及事务在 `Create` 里保证了什么。 --- ## 第 5 天：任务接口和权限测试 **学习内容** - 同一列内排序：`position` 整数，移动时把目标位置之后的任务整体后移一位，放在一个事务里完成。 - 用 `httptest` 测权限，比手动点更可靠。 **要建的文件** - `internal/service/task_service.go`： - `List(ctx, userID, boardID)`：返回 `map[string][]Task`（三列）。 - `Create(ctx, userID, boardID, input)`：负责人必须是看板成员，否则 `ErrValidation`；新任务放在“待办”列末尾。 - `Update(ctx, userID, boardID, taskID, input)`：字段用指针区分“没传”和“传了空值”（和第 2 周一样）。 - `Move(ctx, userID, boardID, taskID, status, position)`：事务里 `ShiftPositions` + `MoveTask`。 - `Delete(ctx, userID, boardID, taskID)`：只有任务创建者或看板 owner 能删，否则 `ErrForbidden`。 - `internal/handler/task_handler.go`：对应 5 个接口。 - `internal/service/task_service_test.go`：连测试数据库（没设 `TEST_DATABASE_URL` 就跳过），测负责人校验、移动后同列 `position` 连续不重复。 - `internal/handler/handler_test.go`： - `setupApp(t)`：连测试库、清表、组装完整路由，返回 `*gin.Engine`。 - `registerAndLogin(t, app, email) string`：辅助函数，返回令牌。 - 测试用例至少包括：未登录 401；非成员访问看板 404；member 添加成员 403；member 删除别人的任务 403；owner 删除任务 204；跨看板用别的看板的 `taskId` 访问返回 404。 **运行方式**：`make test-integration` **完成标准**：权限测试全部通过；能说清楚为什么 `Move` 要放在事务里。 --- ## 第 6 天：前端 **学习内容** - 统一请求封装：每个请求自动带令牌，收到 401 时清掉登录状态并跳到登录页。 - 路由守卫：没登录访问看板页时跳到登录页。 - 乐观更新：拖动任务时先改界面，接口失败再回滚。 **要建的文件** - 用 Vite 新建 `frontend/`（同第 2 周），`.env.development` 写 `VITE_API_BASE=http://localhost:8080/api`。 - `src/types/index.ts`：`User`、`Board`、`Member`、`Task`、`TaskStatus`（`'todo' | 'doing' | 'done'`）。 - `src/api/client.ts`：`request(method, path, body?)`，处理统一响应格式和 401。 - `src/api/auth.ts`、`boards.ts`、`tasks.ts`：一个接口一个函数。 - `src/store/auth.ts`：保存令牌和当前用户，提供 `login`、`logout`，刷新页面后从 `localStorage` 恢复并调用 `/api/me` 校验。 - `src/router.tsx`：`/login`、`/register`、`/boards`、`/boards/:id`，后两个需要登录。 - `src/pages/LoginPage.tsx`、`RegisterPage.tsx`：表单、错误提示。 - `src/pages/BoardsPage.tsx`：我的看板列表 + 新建看板。 - `src/pages/BoardDetailPage.tsx`：三列看板 + 成员面板。 - `src/components/TaskColumn.tsx`、`TaskCard.tsx`：卡片可以拖到别的列（用 HTML5 拖拽或 `@dnd-kit`；时间不够就先做“移到下一列”按钮）。 - `src/components/TaskEditor.tsx`：编辑标题、描述、负责人（下拉选成员）。 - `src/components/MemberPanel.tsx`：成员列表；owner 能看到“按邮箱添加”和“移除”。 **运行方式**：后端 `go run .`，前端 `npm run dev`，开两个浏览器（或一个无痕窗口）登录两个账号测试。 **完成标准**：两个账号完整走一遍：注册 → 建看板 → 加成员 → 两人各自建任务、拖动、指派 → member 删除别人的任务时看到无权限提示。 --- ## 第 7 天：收尾，写成作品 **学习内容** - 作品集 README 怎么写：别人 30 秒内知道它是什么，5 分钟内能跑起来。 - 演示数据：让看的人不用自己注册就能体验。 **要建的文件和修改** - `db/seed.sql`：两个演示账号（密码哈希用 `HashPassword` 生成后写入）、一个看板、十来条任务；`Makefile` 增加 `seed` 目标。 - `task-board/README.md`： - 一句话介绍 + 功能列表 + 截图。 - 技术栈。 - ER 图、接口表（复制上面的表）。 - 架构说明：handler / service / store 分层，权限在哪一层判断。 - 安全说明：密码哈希、JWT 过期、为什么非成员返回 404、令牌存储的取舍。 - 本地运行步骤：`docker compose up -d` → `make migrate-up` → `make seed` → `go run .` → `npm run dev`。 - 已知不足和下一步（刷新令牌、实时同步、部署），诚实写出来。 - 提交并推送到 `zhuangang` 仓库（路径 `task-board/`），确认 `.env` 和密钥没有提交。 **完成标准** - `go vet ./...` 没有警告，`gofmt -l .` 没有输出。 - `go test ./... -race` 和 `make test-integration` 都通过。 - 在一个新目录里 `git clone` 下来，按 README 能从零跑通。 - 能用 3 分钟讲清楚这个项目：做了什么、分层、权限怎么保证、遇到过什么问题。 - 在总纲 `README.md` 的进度记录里勾掉第 4 周和“第 1 个月 Go 全栈基础”。 --- ## 本周自查清单 - [ ] 能说清楚 bcrypt 为什么适合存密码 - [ ] 能说清楚 JWT 的结构、优缺点，以及载荷不加密 - [ ] 会写鉴权中间件，分得清 401 和 403 - [ ] 权限判断放在后端 service 层，并有接口测试覆盖 - [ ] 会用事务处理“多步写入必须一起成功”的场景 - [ ] 前端有统一请求封装、401 处理和路由守卫 - [ ] 项目一 README 完整，别人能从零跑起来 - [ ] 能用 3 分钟讲清楚项目一 下一步：第 5 周进入第 2 个月，先做阶段 0 盘点和阶段 1 读通画图，具体见总纲 `README.md` 第 4 节。第 1 个月学到的分层、事务、`ON CONFLICT` 幂等写入、鉴权，在第 9~11 周的 Agent 项目里都会再用到。