4.6 KiB
4.6 KiB
tags, aliases, date created, date modified
| tags | aliases | date created | date modified | |
|---|---|---|---|---|
|
星期三, 十二月 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)
-
关于 PATCH vs PUT:
- 在完整版的管理接口中，我使用了
PATCH而不是PUT。 - 理由:
PUT语义上是全量替换。在修改用户状态（如封禁）或角色时，我们只修改单个字段，使用PATCH更符合 RESTful 语义，且能避免管理员无意中覆盖了用户的其他信息（如昵称）。
- 在完整版的管理接口中，我使用了
-
关于路径设计 (URI Design):
- 区分了
/users/me(当前用户) 和/admin/users/:id(管理特定用户)。 - 理由: 这种分离能清晰地界定权限边界。
/me接口永远不需要传 ID（从 Token 解析），杜绝了普通用户通过遍历 ID 窃取他人信息的越权风险 (IDOR)。
- 区分了
-
关于缓存 (Cache):
- 自我反驳: 虽然 PRD 建议对
/profile进行缓存，但在 API 定义阶段不需要体现在 URL 上。 - 补充: 但作为后端设计，你需要在
GET /users/me的 Controller 层实现 Cache-Aside 模式（先查 Redis，无则查 DB 并回写）。
- 自我反驳: 虽然 PRD 建议对