1

T-267

ila edited this page 2026-08-07 16:37:08 +08:00

Table of Contents

• 问题 / 背景
• 行为契约
• 不变边界
• 方案
• 验收要点
• 执行记录

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-267.md · commit afc651f75a3a

---

id: T-267 title: 将管理 Web Session 固定有效期延长为30天 phase: 2 deps:

• T-204
• T-266 status: DONE created: 2026-08-01 context_ref: 9409b97 work_branch: null write_paths:
• docs/tasks/T-267.md
• docs/current-state.md
• docs/02-requirements.md
• docs/03-tech-stack.md
• docs/04-architecture.md
• docs/api.md
• backend-api/README.md
• backend-api/internal/usecase/**
• backend-api/internal/transport/webui/**

---

问题 / 背景

管理后台当前每次登录创建固定8小时 ADMIN 服务端 session。内部采购管理人员需要减少 重复登录，将网页登录有效期改为1个月。

Go time.Duration 不表达自然月，本任务把“1个月”固定定义为 30天，即720小时、 2,592,000秒，与 T-266 的设备 token 期限表达一致，但两类凭证继续完全隔离。

行为契约

• 新创建 ADMIN Web Session 的绝对有效期固定为 30 * 24 * time.Hour。
• 登录成功时，服务端 session 的 expires_at、浏览器 Cookie 的 Expires 和 Max-Age 必须采用同一个到期时间；Max-Age 约为 2592000 秒，只允许请求执行耗时造成的秒级差异。
• 已有 session 保留数据库中的原 expires_at，不批量延长；部署后管理员需重新登录一次 才能取得30天 session。
• session 不因浏览页面、提交表单或 API 请求滚动续期，不增加 refresh session。
• 退出登录、账号禁用、session 撤销和绝对到期仍在下一次请求立即生效。

不变边界

• BUYER 设备 Bearer token 继续使用 T-266 定义的固定30天有效期，两类凭证不可互换。
• 管理 Cookie 继续使用 HttpOnly、TLS 下 Secure 和 SameSite=Lax。
• CSRF Cookie 的独立1小时 Max-Age 不变；CSRF token 可按既有流程轮换，不影响登录 session。
• 设备 secret、任务 claim token、claim 租约、execution 授权和幂等 key 生命周期均不变。
• 不增加数据库迁移或可配置环境变量。

方案

1. 将 AdminSessionLifetime 改为 30 * 24 * time.Hour。
2. 增加固定期限测试，避免实现常量与测试期望同时漂移。
3. 增加 Web 登录 Cookie 测试，核对 Expires 和 Max-Age 与服务端到期时间一致。
4. 同步需求、技术栈、架构、API、后端说明和当前状态文档。
5. 运行 Go 全量测试和根 init.ps1。

验收要点

• 新登录产生的 expires_at - created_at 严格等于30天。
• 登录 Cookie 的 Expires 与服务端到期时间一致，Max-Age 接近 2592000 秒。
• 已有 session 不被迁移或静默延期。
• 过期、撤销、退出和用户禁用测试继续通过。
• BUYER token、CSRF Cookie 和任务相关生命周期无改动。
• Go 全量测试和根 init.ps1 通过。

执行记录

• 2026-08-01：建立任务契约，明确30天为固定绝对期限，既有 session 不迁移，管理 Session 与 BUYER Bearer token、CSRF Cookie 继续隔离。
• 2026-08-01：将 AdminSessionLifetime 从8小时改为 30 * 24 * time.Hour；新创建 Session 的数据库 expires_at 固定为30天后，既有记录不更新。
• 2026-08-01：Web 登录测试核对 Cookie Expires 与服务端结果一致，Max-Age 在 2592000 秒的请求耗时容差内；CSRF Cookie 的独立1小时配置未修改。
• 2026-08-01：go test ./internal/usecase ./internal/transport/webui、go test ./... 和根 init.ps1 全部通过；根检查覆盖 Android Debug/Release 单测、Debug APK、共享 契约、导入工具和 Go 后端全量测试。