89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
|
---
|
|||
|
|
tags: []
|
|||
|
|
aliases:
|
|||
|
|
- 04_ 业务逻辑功能清单
|
|||
|
|
date created: 星期三, 十二月 10日 2025, 12:04:34 凌晨
|
|||
|
|
date modified: 星期三, 十二月 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 并回写）。
|