Inbox/Go项目实战/用户模块/04_业务逻辑功能清单.md

tags, aliases, date created, date modified

tags	aliases	date created	date modified
	04_ 业务逻辑功能清单	星期三, 十二月 10日 2025, 12:04:34 凌晨	星期三, 十二月 10日 2025, 12:05:53 凌晨

04_ 业务逻辑功能清单

TL;DR (摘要)

• 基础版 (MVP): 仅满足最基本的“注册 - 登录 - 看自己”流程，适合快速打通前后端联调，但不符合 PRD 的安全标准。
• 完整版 (Enterprise): 严格对应 PRD V1.1，包含双令牌刷新、强制登出、RBAC 提权及管理员封禁功能，符合生产环境安全要求。

---

方案一：基础版 (MVP / Prototype)

适用场景: 项目初期快速搭建原型 (PoC)，验证核心业务流程（如文章发布），暂时忽略复杂的安全合规。

局限性: 仅使用单 Access Token（长效），无刷新机制，无法强制踢人下线，无管理员管理界面。

模块	方法	API 路径	核心功能描述	鉴权要求
Auth	POST	/api/v1/register	用户注册 (仅用户名 + 密码)	无
Auth	POST	/api/v1/login	用户登录 (返回长效 JWT)	无
User	GET	/api/v1/user/profile	获取当前登录用户信息	JWT
User	PUT	/api/v1/user/profile	修改自己的昵称、简介	JWT

自我反驳 (基础版): 此方案虽然简单，但直接违反了 PRD 中 F-AUTH-03 (令牌刷新) 和 F-AUTH-04 (统一登出) 的要求。若项目进入 Alpha 测试阶段，必须立刻废弃此方案，否则存在严重的安全隐患（Token 泄露即完全失控）。

---

方案二：完整版 (Enterprise / PRD Compliant)

适用场景: 正式开发与生产环境交付。严格遵循“银行级 RBAC”和“双令牌”机制。

1. 认证服务 (Auth Service) - 公开/基础域

对应 PRD 章节: 2.1 认证与鉴权模块

需求编号	方法	API 路径	功能描述	输入参数	鉴权
F-AUTH-01	POST	/api/v1/auth/register	用户注册 (密码需 Hash 存储)	username, password	无
F-AUTH-02	POST	/api/v1/auth/login	登录 (颁发 Access + Refresh Token)	username, password	无
F-AUTH-03	POST	/api/v1/auth/refresh	令牌刷新 (旧换新，防复用机制)	refresh_token	无
F-AUTH-04	POST	/api/v1/auth/logout	统一登出 (将 Refresh Token 加入黑名单)	refresh_token	JWT
F-AUTH-05	POST	/api/v1/auth/password	重置密码 (成功后吊销所有 Token)	old_pwd, new_pwd	JWT

2. 用户自服务 (User Self-Service) - 个人域

对应 PRD 章节: 2.2 用户与权限模块 (F-USER-01)

需求编号	方法	API 路径	功能描述	备注	鉴权
F-USER-01	GET	/api/v1/users/me	获取我的详细资料	建议增加 Redis 缓存	JWT
F-USER-01	PUT	/api/v1/users/me	修改资料 (昵称, 头像 URL, 简介)	更新后需清除缓存	JWT

3. 管理员运维 (Admin Dashboard) - 管理域

对应 PRD 章节: 2.2 用户与权限模块 (F-USER-02, F-RBAC-01)

需求编号	方法	API 路径	功能描述	关键逻辑	鉴权
F-USER-02	GET	/api/v1/admin/users	用户列表查询	支持分页、按用户名搜索、按状态筛选	Admin Only
F-USER-02	PATCH	/api/v1/admin/users/:id/status	封禁/解封用户	修改状态为 active/banned，若封禁需强制踢下线	Admin Only
F-RBAC-01	PATCH	/api/v1/admin/users/:id/role	角色变更 (提权)	修改角色为 editor/admin	Admin Only

---

关键设计决策说明 (Technical Decisions)

1. 关于 PATCH vs PUT:

   • 在完整版的管理接口中，我使用了 PATCH 而不是 PUT。
   • 理由: PUT 语义上是全量替换。在修改用户状态（如封禁）或角色时，我们只修改单个字段，使用 PATCH 更符合 RESTful 语义，且能避免管理员无意中覆盖了用户的其他信息（如昵称）。

2. 关于路径设计 (URI Design):

   • 区分了 /users/me (当前用户) 和 /admin/users/:id (管理特定用户)。
   • 理由: 这种分离能清晰地界定权限边界。/me 接口永远不需要传 ID（从 Token 解析），杜绝了普通用户通过遍历 ID 窃取他人信息的越权风险 (IDOR)。

3. 关于缓存 (Cache):

   • 自我反驳: 虽然 PRD 建议对 /profile 进行缓存，但在 API 定义阶段不需要体现在 URL 上。
   • 补充: 但作为后端设计，你需要在 GET /users/me 的 Controller 层实现 Cache-Aside 模式（先查 Redis，无则查 DB 并回写）。