baiyue-firstleg/auth/AGENTS.md

Auth Service 模块指引

职责与边界

• 负责登录、注册、账号凭据、Access/Refresh Token、退出、密码和账号归属范围。
• 客户主档、成员、角色权限归 iam/；Auth 通过 IAM 客户端获取授权快照，不跨库写 IAM。
• tenant_id=0 为平台作用域，tenant_id>0 为客户 ID；不得引入租户管理或切换。

模块入口

目标	入口
登录/刷新/退出/改密	src/main/java/com/baiyue/auth/controller/AuthController.java
内部账号管理与 scope	controller/InternalAccountController.java、service/AccountManagementService.java
Token 与会话	service/AuthService.java、service/TokenSessionStore.java
注册协作	service/MerchantRegistrationService.java
IAM 授权客户端	client/IamAuthorizationClient.java、client/IamOnboardingClient.java
DTO/持久化	dto/AccountManagementDtos.java、entity/、mapper/、repository/
SQL/OpenAPI	src/main/resources/db/、src/main/resources/openapi/
测试/验证	src/test/java/com/baiyue/auth/；mvn -pl auth -am test

修改约束

• 密码、Token、敏感 Claim 不得写日志；修改 Claim、Redis Key 或过期策略时联查 common-security/、gateway/、iam/。
• 注册跨 Auth/IAM 必须保持幂等和失败补偿；内部接口仅接受服务令牌。
• 业务错误保持 HTTP 200 + body code；Security 认证失败保留真实 401/403。

分期导航

• 一期：登录、注册、账号状态和 Token；先读 ../../docs/一期/README.md。
• 二期：无独立登录流程，仅保障入库/计费沿用 JWT、应用域和客户隔离；先读 ../../docs/二期/README.md。
• 三期：没有独立账号或角色模型；认证与会话仅在 IAM 三期权限契约需要时保持兼容。先读 ../../docs/三期/三期开工门禁.md，不得借三期新增租户层级或绕过服务端授权。