优化

auth/AGENTS.md

@@ -1,38 +1,32 @@
 # Auth Service 模块指引
 
-## 职责边界
+## 职责与边界
 
-- 负责账号凭据、登录、Access/Refresh Token 生命周期、退出、密码变更及商户注册协作。
-- 客户主档、成员资料、角色和权限属于 `iam/`；Auth 只通过 IAM 客户端加载授权快照和创建注册结果。现有账号/JWT 中的 `tenant_id > 0` 当前是客户 ID，`tenant_id=0` 是平台技术作用域；字段名保持兼容，不代表已经存在真实租户层。
+- 负责登录、注册、账号凭据、Access/Refresh Token、退出、密码和账号归属范围。
+- 客户主档、成员、角色权限归 `iam/`；Auth 通过 IAM 客户端获取授权快照，不跨库写 IAM。
+- `tenant_id=0` 为平台作用域，`tenant_id>0` 为客户 ID；不得引入租户管理或切换。
 
-## 快速索引
+## 模块入口
 
-| 功能 | 入口 |
+| 目标 | 入口 |
 |---|---|
-| 应用与安全配置 | `src/main/java/com/baiyue/auth/BaiyueAuthApplication.java`、`config/AuthSecurityConfig.java` |
-| 登录、注册、刷新、退出、改密 API | `controller/AuthController.java`（`/api/auth`） |
-| 内部账号管理 API | `controller/InternalAccountController.java`（`/internal/auth/accounts`）；含创建、资料/状态/密码、`PUT /{id}/scope` 账号归属迁移和补偿删除 |
-| 认证与令牌编排 | `service/AuthService.java`、`TokenSessionStore.java` |
-| 账号创建、显示名同步、状态、密码和归属范围 | `service/AccountManagementService.java`；平台账号使用 `default_app_code=PLATFORM`、`tenant_id=0`，范围变更会递增 token version 撤销旧会话 |
-| 商户注册协作 | `service/MerchantRegistrationService.java` |
-| IAM 调用与授权快照 | `client/IamAuthorizationClient.java`、`IamOnboardingClient.java`、`AuthorizationSnapshot.java` |
-| 账号与 Refresh Token 持久化 | `entity/`、`mapper/`、`repository/` |
-| 请求/响应模型 | `dto/AccountManagementDtos.java`；创建可指定初始状态，`AccountSummary` 返回最后登录时间、兼容字段 `tenantId`、成员与应用端 |
-| 表结构与一期账号 | `src/main/resources/db/auth.sql`、`phase1-admin-accounts.sql` |
-| 配置与测试 | `src/main/resources/application.yml`、`src/test/java/com/baiyue/auth/service/` |
+| 登录/刷新/退出/改密 | `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。
-- 修改 Token Claim、会话 Redis Key、过期或撤销逻辑时同步检查 `common-security/`、`gateway/` 和 IAM 授权快照。
-- 注册流程跨 Auth/IAM，失败补偿和幂等必须成对检查；不要跨库写 IAM 表。
-- 内部账号创建允许相同账号 ID 与相同归属幂等重试；不同身份占用同一 ID 必须冲突。内部接口只接收 IAM 的服务令牌，不直接暴露给前端。
-- 平台统一用户管理变更账号客户归属时由 IAM 调用 `PUT /internal/auth/accounts/{id}/scope` 同步 Auth 的客户隔离兼容字段、成员和应用端；修改该历史契约必须同时检查 `iam/client/AuthAccountClient.java` 与 `PlatformUserManagementService.java`。
-- 登录、刷新等业务失败仍是 HTTP 200 + 非 `"200"` body code；Security 入口产生的真实 401 保留给客户端 Token 刷新流程。
-- 从父目录运行 `mvn -pl auth -am test`，认证接口变更再运行相关 `scripts/` 回归。
+- 密码、Token、敏感 Claim 不得写日志；修改 Claim、Redis Key 或过期策略时联查 `common-security/`、`gateway/`、`iam/`。
+- 注册跨 Auth/IAM 必须保持幂等和失败补偿；内部接口仅接受服务令牌。
+- 业务错误保持 HTTP 200 + body code；Security 认证失败保留真实 401/403。
 
-## 分期快速索引
+## 分期导航
 
-- 一期：负责登录、注册、账号状态和 Token；先读 `../../docs/一期/README.md`、`../../docs/一期/一期开发进度表.md`，状态边界是平台账号 `tenant_id=0`、客户账号 `tenant_id>0`，不得把 Auth 变成租户管理入口。
-- 二期：无独立登录流程；仅需保证入库/计费接口沿用现有 JWT、应用域和客户隔离。涉及 `tenant_id`、Claim 或内部令牌时，先读 `../../docs/二期/README.md` 与主流程文档，再联查 `firstleg/`、`iam/`。
-- 三期：当前 NO-GO，不新增出仓账号或角色；待 `../../docs/三期/三期需求确认表.md` 解除阻断后，才评估权限码和 PDA 身份协作。
+- 一期：登录、注册、账号状态和 Token；先读 `../../docs/一期/README.md`。
+- 二期：无独立登录流程，仅保障入库/计费沿用 JWT、应用域和客户隔离；先读 `../../docs/二期/README.md`。
+- 三期：NO-GO，不新增出仓账号或角色；确认表解除阻断后再改权限。