feat(auth): add account access domain and repository

[Alexander-Noah]

关联 Issue

Refs #206

• feat(backend): 完成账户创建、密码登录与统一 JWT 鉴权闭环

变更概述

完成后端认证实施包 B1，建立账户访问领域契约、认证编排、账户仓储及事务边界，并补充对应单元测试和 PostgreSQL 并发测试。

认证领域契约

• backend/src/timeflow/business/auth/contracts.py

  • 定义用户名和密码输入规则。
  • 用户名去除首尾空白，长度限制为 3～64 个 Unicode code point。
  • 密码保留原始内容，长度限制为 8～128 个 Unicode code point。
  • 拒绝全空白密码。
  • 定义稳定的认证错误码和公开错误消息。
  • 定义账户记录、新账户及认证成功结果。
  • 使用 repr=False 避免密码、密码哈希和 Token 出现在对象表示中。
  • 定义账户仓储、事务、密码哈希和访问令牌服务接口。

• backend/src/timeflow/business/auth/service.py

  • 新增统一账户访问服务。
  • 新用户名首次访问时创建账户。
  • 已有用户名访问时验证密码。
  • 密码错误时返回稳定的凭证错误，不签发 Token。
  • 使用 acc_ 加随机 ID 生成账户 ID。
  • 校验生成的账户 ID 不超过数据库字段限制。
  • 处理同用户名并发创建冲突。
  • 冲突后开启新事务读取最终账户并验证当前请求密码。
  • 通过依赖注入隔离密码算法、Token 实现、时钟和 ID 生成器。

• backend/src/timeflow/business/auth/__init__.py

  • 统一导出认证领域类型和服务。

账户持久化与事务

• backend/src/timeflow/data/repositories/account.py

  • 新增 SQLAlchemy 账户仓储。
  • 支持按用户名查询账户。
  • 支持新增账户并执行 flush。
  • 仓储不提交事务，由上层事务单元统一管理。
  • 仅将用户名唯一约束冲突转换为领域冲突异常。
  • 其他数据库完整性错误保持原始异常语义。

• backend/src/timeflow/data/account_uow.py

  • 新增认证事务单元。
  • 每个认证事务使用独立 SQLAlchemy Session。
  • 统一管理提交、回滚和 Session 关闭。
  • 未提交或发生异常时自动回滚。
  • 拒绝重复进入及事务外操作。

• backend/src/timeflow/data/repositories/__init__.py

  • 导出账户仓储实现。

自动化测试

• backend/tests/business/auth/test_credentials.py

  • 验证用户名规范化、长度边界和大小写规则。
  • 验证密码长度及全空白密码处理。
  • 验证 Unicode code point 规则。
  • 验证敏感字段不会出现在对象表示中。

• backend/tests/business/auth/test_service.py

  • 验证新账户创建和 Token 签发。
  • 验证已有账户密码校验。
  • 验证错误密码不会签发 Token。
  • 验证并发冲突后使用新事务读取最终账户。
  • 验证相同密码和不同密码下的冲突结果。
  • 验证账户 ID 长度限制。

• backend/tests/data/repositories/test_account.py

  • 验证账户新增和查询。
  • 验证仓储不会自行提交事务。
  • 验证唯一约束错误转换。
  • 验证事务提交、自动回滚和生命周期约束。

• backend/tests/test_postgres_auth_repository.py

  • 使用真实 PostgreSQL 验证独立事务行为。
  • 验证同用户名、相同密码并发创建。
  • 验证同用户名、不同密码并发创建。
  • 验证最终只保留一条账户记录。
  • 验证只有获胜密码可以完成认证。
  • 验证未提交账户不会持久化。

变更原因

Issue #206 将后端认证拆分为 B1-B5 五个实施包。

本 PR 完成 B1“领域与仓储”，为后续密码安全、JWT、HTTP 认证和 WebSocket 鉴权提供稳定的领域接口与事务基础。

认证服务通过协议依赖密码和 Token 能力，账户仓储只负责持久化操作，事务由统一工作单元管理，从而减少跨层重复逻辑并保持较低的代码冗余。

破坏性变更

无已知破坏性变更。

验证结果

• Ruff 代码检查通过
• Ruff 格式检查通过
• MyPy 类型检查通过
• uv lock --check 通过
• Alembic 单一 head 检查通过
• B1 单元测试和架构测试通过
• PostgreSQL 事务及并发测试：3 个测试通过
• 后端全量测试：336 passed、29 skipped
• backend/scripts/check.sh 通过
• 真实 HTTP 与 WebSocket 认证联调完成

本次不包含

• Argon2id 密码哈希实现
• JWT 签发、验证和运行环境配置
• POST /api/v1/auth/access HTTP 接口
• HTTP Bearer Token 认证上下文
• WebSocket 真实 JWT 验证器接线
• 前端认证功能
• 账户表或现有 Alembic 迁移修改
• Refresh Token、Token 撤销和多设备会话管理

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
timeflow	Ready	Preview	Aug 12, 2026 8:15am

[Alexander-Noah]

/review

[fennoai]

No high-confidence issues found in the changed authentication domain, repository, transaction handling, or tests.

Validation: git diff --check and Python bytecode compilation passed. The full pytest/lint/type-check suite was not run locally because uv, pytest, ruff, and mypy are unavailable in this environment.

View job run

[fennoai]

Found one performance issue in the account-creation path. Other changed authentication contracts, repository error mapping, transaction cleanup, and tests did not reveal additional high-confidence findings.

Validation: git diff --check and Python bytecode compilation passed. The full pytest/lint/type-check suite was not run because the required tools are unavailable in this environment.

View job run

[fennoai]

Review Complete

• Submitted one inline correctness finding on backend/src/timeflow/data/account_uow.py: an escaped accounts repository can reuse the SQLAlchemy session after the unit-of-work context exits, bypassing lifecycle management.
• Reviewed the fixed range 612f622...c09c050 across code quality, performance, security, and documentation.
• Avoided duplicating the existing unresolved password-hashing performance finding.
• Validation: git diff --check passed. Targeted Python tests could not run because uv, pytest, and the project dependencies are unavailable in this environment.

View job run

[fennoai]

Found one additional transaction-lifecycle issue. I did not repeat the existing unresolved password-hashing performance comment.