Harness 与 Koa2 登录实践（二）：小步能跑通------从 /health 到会话 Cookie
配套开源仓库 ：harness-login-now-koa2
建议先读系列（一）或直接打开仓库中的
implement guide/NOTES-API-CONTRACT.md作为单一事实来源；本文与implement guide/V1/KOA2登录系统-Harness与Cursor分步指南.md阶段 1～4、5 前半对齐。
这篇在讲什么
（一）里说了：先契约，再写代码 。这一篇用递进 方式走一遍「最小可运行 → 能注册用户 → 能登录并保持会话」------每一步都只加一个能力，避免一次改太多无法归因。
技术栈在仓库里是固定的：Node + Koa 2 、koa-router、koa-bodyparser、bcrypt 、koa-session ，用户开发期落在 data/users.json 。模块格式为 CommonJS （与根目录 package.json 一致）。
阶段 1：把环境钉住（环境即契约）
通俗目标 ：换一台机器也能 npm install 后跑起来，不依赖「我全局装了啥」。
- 用
package.json+ lockfile 锁依赖版本。 - 若
npm install报错，先把终端完整输出贴给助手或自己归类：网络、权限、Node 版本------对应 Harness 里「错误分类再升级策略」，而不是盲改代码。
仓库根目录执行：
bash
npm install
npm start默认端口 3000 ，可用环境变量 PORT 覆盖（细节见仓库 README.md）。
阶段 2：只要一个回声------GET /health
通俗目标：证明「HTTP 层 + 进程监听」已经 OK，再叠业务。
实现一个 GET /health ，返回形如 { "ok": true } 的 JSON。验收一行就够：
bash
curl -sS http://127.0.0.1:3000/health这就是 Harness 里常说的 checkpoint：后面登录出问题，可以先确认 health 仍正常，缩小排查面。
阶段 3：用户与密码------POST /register
通俗目标 ：能把用户存下来，且磁盘上没有明文密码。
- 用户列表存在
data/users.json（数组）；启动时读入，变更后写回。 - 注册接口
POST /register：body 里username/password；成功返回 201 与{ ok, user }，不要返回 password。 - 用户名冲突返回 409 ，字段不合法返回 400 ，错误体统一
{ error, message }（机器可读码 + 人话说明）。
密码用 bcrypt 生成 passwordHash 再写入 JSON。这样即使文件泄露，也不是「一眼能登录」的明文。
小验收 ：同一用户名注册两次，第二次应 409 ；若变成 500，多半是校验或写入逻辑遗漏，对照契约修。
阶段 4：登录与会话------POST /login 与 Cookie
通俗目标 ：登录成功后，浏览器（或 curl 的 cookie 罐）里有一个 httpOnly 的会话 Cookie，服务端能认出「你是谁」。
本仓库契约约定：
- Cookie 名：
app_session - 属性建议：
HttpOnly; Path=/; SameSite=Lax（本地调试用；跨站场景以后要单独设计） - Session 里只放
userId/username等业务需要字段，不要放密码。
curl 技巧 ：用 -c 把 Set-Cookie 写入文件，用 -b 带上文件访问受保护接口。契约里的五条示例在 NOTES-API-CONTRACT.md「验收用 curl 示例」一节。
登录成功应 200 ，响应体带 { ok, user }，响应头带 Set-Cookie 。若登录后访问 /me 仍 401 ，常见原因是：中间件顺序、Cookie 的 Path/域名、或 session 未正确挂载------把 curl -v 的请求与响应头贴出来排错，比猜更快（分步指南阶段 4 也强调了这一点）。
阶段 5（本篇收尾）：GET /me 与中间件顺序
通俗目标 ：未登录统一 401；已登录返回当前用户，且不在每个路由里复制粘贴鉴权代码。
做法是把鉴权抽成 requireAuth 一类中间件，并保证：先 session 解析，再鉴权，再业务 。仓库 HARNESS-SELF-CHECK.md 里用一句话对应了「上下文如何被组织」：错误壳 → 解析 JSON →（开发日志）→ Session → 路由 ，/me 再串 requireAuth。
验收思路：
bash
curl -sS -c cookies.txt -H 'Content-Type: application/json' \
-d '{"username":"alice","password":"secret123"}' \
http://127.0.0.1:3000/login
curl -sS -b cookies.txt http://127.0.0.1:3000/me具体字段名与状态码仍以 implement guide/NOTES-API-CONTRACT.md 为准。
小结
| 阶段 | 你证明的事 |
|---|---|
| health | 进程与 HTTP 通 |
| register | 持久化 + bcrypt + 错误码 |
| login | session + Cookie 链路通 |
| /me | 鉴权与中间件顺序正确 |
每一步都尽量 小 、可 curl ，这和「一次让 AI 生成全部路由」相比，更利于交接和复盘。
下一篇与仓库
- （三） 会讲：
npm run verify脚本闭环 、HARNESS-SELF-CHECK自检 、以及 SESSION_KEYS、CORS、多实例不写同一users.json等运维向边界------也就是「怎么证明整条链路在干净环境里也能绿」。 - 源码、契约全文、分步指南与 Windows 验收脚本 均在：github.com/RonnyJung20... 。欢迎对照
src/index.js、src/userStore.js与scripts/verify-flow.sh阅读。