wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-14A User & Account 模块架构设计 #14

New Issue
Open
opened 2026-05-22 21:00:16 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:16 +08:00
Owner
Copy Link

目标

设计知习 C 端用户的注册、登录、账号基础能力，为所有 C 端业务模块（知识库、学习、复习、额度等）提供统一的用户身份底座。

本 Issue 只做模块架构设计，不直接实现代码。需先输出完整设计方案，经审核确认后，再进入后续实现 Issue。

背景说明

知习面向 iOS 和 Web 用户，首选 Apple 登录作为主要登录方式。C 端用户体系需要与 Admin 管理员体系完全隔离——两者的登录入口、token、数据表都是两套独立系统。

User & Account Module 是 M0 基础能力闭环的最后一块拼图。做完这个模块后，后续所有 C 端业务模块才能有统一的身份校验基础。

模块职责

请设计 User & Account Module 的完整职责边界。

本模块负责：

  • C 端用户注册（Apple 登录为主要方式）
  • Apple Sign In 完整流程（验证 identityToken、关联 AuthAccount）
  • 用户基础资料（昵称、头像引用、个人简介）
  • 用户状态管理（正常、禁用、注销申请中、已注销）
  • RefreshToken 签发与轮换
  • 用户设备记录（iOS 设备标识、推送 token）
  • 账号注销申请（软删除 → 冷静期 → 正式删除）
  • C 端身份鉴权 Guard，供所有 /api/* 路由使用

本模块不负责：

  • Admin 管理员登录与权限（走 Admin Auth & RBAC Module）
  • 会员计划与额度扣减（走 Quota Module）
  • 文件上传签名和 COS 管理（走 File Storage Module）
  • AI 调用、内容审核、学习/复习业务逻辑
  • 推送通知发送（走 Notification Module）

与其他模块的边界：

  • Admin Auth & RBAC：Admin 可通过 Admin API 管理 C 端用户（禁用/恢复/查看）
  • Audit & Security：Admin 操作用户状态时触发审计日志
  • File Storage：用户头像上传走 File Storage，本模块只存 objectKey 引用
  • Traffic Protection：登录接口需要限流保护
  • Content Safety：昵称和简介需要敏感词审核
  • Notification：用户注销、状态变更等关键事件通知

候选数据对象

以下对象为候选设计，请根据模块职责判断最终保留哪些、是否需要拆分或合并。

  • User：C 端用户主表。核心字段：唯一标识、昵称、头像引用（File Storage objectKey）、个人简介、状态、注册时间、最近登录时间、软删除标记
  • AuthAccount：第三方登录绑定。核心字段：provider（apple）、providerUserId（Apple user identifier）、关联 User、绑定时间。注意 Apple 的 user identifier 对同一开发者账号是稳定的，可做唯一约束
  • RefreshToken：token 表或 Redis 管理。需考虑：hash 存储、有效期、轮换策略、设备关联、失效机制（用户禁用/注销/主动退出）
  • UserDevice：用户设备记录。核心字段：设备标识、设备名称、操作系统版本、推送 token、首次登录时间、最近活跃时间
  • AccountDeletionRequest：账号注销申请。核心字段：关联用户、申请时间、冷静期截止时间、处理状态（pending/processing/completed/cancelled）、处理人（Admin）

请输出：

  1. 最终建议保留哪些表及其用途
  2. 每张表的字段设计和关键约束
  3. 索引设计和软删除策略
  4. 状态枚举值定义
  5. 表间关联关系

存储与基础设施依赖

请逐项判断本模块是否需要以下基础设施，并说明理由：

  1. MySQL：用户数据必须持久化存储，User/AuthAccount/UserDevice/AccountDeletionRequest 都需要 MySQL 表
  2. Redis：是否需要？用于哪些场景？
    • Apple 登录 nonce 缓存（验证 identityToken 时需要）
    • 登录限流计数
    • RefreshToken 黑名单（用户退出或禁用后立即失效）
    • 短期状态缓存（用户资料、设备列表）
  3. COS：本模块不直接操作 COS。用户头像通过 File Storage Module 处理，本模块只存储 File Storage 返回的 objectKey
  4. BullMQ：是否需要异步任务？
    • 账号注销后的数据清理（关联知识库、学习记录等的异步删除）
    • 注销冷静期到期后的自动处理
  5. Qdrant：不需要。用户模块不涉及向量检索
  6. AI Gateway：不需要。用户模块不涉及 AI 调用
  7. Content Safety：昵称和简介在创建/修改时需要审核，但通过 Content Safety Module 提供的中间件或接口调用，不直接依赖审核 API
  8. Audit & Security：Admin 操作用户状态（禁用/恢复/处理注销）时必须写审计日志，但通过 Audit Module 接口写入，不直接操作审计表

API 设计

请设计本模块的 API 路由。

CAPI /api/*

候选接口（请根据设计判断最终清单和路径）：

  • Apple 登录（接收 identityToken，验证后签发 AccessToken + RefreshToken）
  • 刷新 Token（用 RefreshToken 换新 AccessToken）
  • 退出登录（失效当前 RefreshToken）
  • 获取当前用户资料
  • 修改用户资料（昵称、简介、头像）
  • 获取用户设备列表
  • 绑定/解绑设备
  • 申请账号注销
  • 取消注销申请（冷静期内）

AAPI /admin-api/*

候选接口：

  • C 端用户列表（分页、搜索、筛选状态）
  • C 端用户详情（基础资料、设备列表、登录记录、认证方式、注销申请状态）
  • 禁用/恢复 C 端用户
  • 查看指定用户的设备记录
  • 查看指定用户的登录记录
  • 处理注销申请（确认删除或驳回）

Admin 使用独立的 Admin token 体系，不能复用 C 端用户的 AccessToken。

IAPI /internal/*

是否需要内部接口？如果需要，请设计：

  • 根据 userId 批量查询用户基础信息（供其他模块的 QueryService 使用）

Service 划分

请设计本模块的服务分层。建议按以下维度拆分：

  • UserCommandService：用户写操作（创建、更新资料、状态变更）
  • UserQueryService：用户查询（单个/批量查询、搜索），对外暴露给其他模块
  • AuthCommandService：登录/退出/刷新 token 等认证写操作
  • AuthQueryService：认证相关查询（设备列表、登录记录）
  • UserPolicyService：业务规则判断（注销条件、状态转换合法性）
  • UserEventHandler：用户相关事件的消费和发布

要求：

  • 跨模块读操作必须走 UserQueryService
  • 跨模块写操作必须走 UserCommandService 或通过 Domain Event
  • 禁止其他模块直接访问 User 模块的 Prisma model

安全设计

请重点设计以下安全问题：

  1. Apple 登录流程：

    • 客户端获取 Apple identityToken
    • 服务端向 Apple 验证 identityToken 的有效性
    • 验证通过后，通过 providerUserId 查找或创建 AuthAccount + User
    • 签发 AccessToken + RefreshToken

  2. RefreshToken 安全：

    • 是否 hash 存储
    • 轮换策略（每次刷新是否换新 RefreshToken）
    • 有效期设定
    • 用户禁用/退出/注销后如何立即失效

  3. AccessToken：

    • 有效期（建议 15-30 分钟）
    • 签发方式（JWT 或 opaque token）

  4. 设备管理：

    • 同一设备重复登录如何处理
    • 设备数量是否设上限

  5. 注销流程：

    • 申请注销 → 冷静期 → 正式删除
    • 冷静期内用户可取消
    • 正式删除后关联数据如何处理（异步清理还是标记删除）

  6. 用户状态枚举：

    • NORMAL（正常）
    • DISABLED（已禁用）
    • DELETION_REQUESTED（注销申请中）
    • DELETED（已注销）

Domain Event 设计

请设计本模块需要发布的 Domain Event。

候选事件：

  • UserRegistered：新用户注册完成
  • UserProfileUpdated：用户资料变更
  • UserDisabled：Admin 禁用用户
  • UserEnabled：Admin 恢复用户
  • UserDeletionRequested：用户申请注销
  • UserDeletionCancelled：冷静期内取消注销
  • UserDeleted：用户正式删除
  • UserLoggedIn：用户登录（可用于更新 Growth/每日活跃等统计）
  • UserLoggedOut：用户退出

请说明：

  1. 每个事件的触发时机
  2. 事件 payload 的关键字段
  3. 哪些事件需要可靠持久化（涉及跨模块副作用的，如 UserDeleted 触发数据清理）
  4. 哪些模块可能订阅这些事件

Admin 视图设计

请设计 Admin 中的 C 端用户管理视图。

  1. 用户列表页：

    • 昵称、注册方式（Apple）、状态、注册时间、最近登录时间、设备数
    • 支持搜索（昵称/ID）、筛选（状态）、分页

  2. 用户详情页：

    • 基础资料（昵称、头像、简介、注册时间）
    • 认证信息（Apple 绑定、绑定时间）
    • 设备列表（设备名称、系统版本、首次登录、最近活跃）
    • 登录记录摘要（最近 N 条）
    • 账号状态与操作（禁用/恢复、查看注销申请）

  3. 操作审计：

    • Admin 禁用/恢复用户必须写入 AuditLog
    • 处理注销申请必须写入 AuditLog

交付检查

  • 路由归属：请设计 CAPI / AAPI / IAPI 的完整路由清单
  • 是否需要 Prisma migration：请输出 Prisma schema 草案
  • 是否需要 MySQL：请确认表列表和用途
  • 是否需要 Redis：请判断并说明使用场景
  • 是否需要 COS：请判断（预期不需要直接操作，头像走 File Storage）
  • 是否需要 BullMQ：请判断注销清理等异步任务是否需要
  • 是否需要 Qdrant：请判断（预期不需要）
  • 是否需要 AI Gateway：请判断（预期不需要）
  • 是否需要 Content Safety：请判断昵称/简介审核的接入方式
  • 是否需要 Cost 记录：请判断（预期不需要）
  • 是否需要 AuditLog：请列出需要审计的操作和触发点
  • 是否需要 Domain Event：请列出最终事件清单
  • 是否需要 Admin 视图：请给出页面和接口设计
  • 是否需要 E2E / 集成测试：请列出关键测试场景
  • 是否需要 OpenAPI：请给出 OpenAPI 分组建议

验收标准

本 Issue 完成后，交付一份 User & Account Module 架构设计文档。文档必须包含：

  1. 模块职责边界（明确本模块负责和不负责的内容）
  2. API 路由设计（CAPI/AAPI/IAPI 完整清单和路径）
  3. 基础设施依赖判断（MySQL/Redis/COS/BullMQ 的使用方案）
  4. Prisma schema 草案
  5. CommandService / QueryService 划分方案
  6. Domain Event 清单及触发时机
  7. 安全策略（Apple 登录流程、Token 管理、注销流程）
  8. Admin 视图设计
  9. E2E / 集成测试场景设计
  10. 不建议当前阶段实现的内容
  11. 建议拆分出的后续实现 Issue

审核通过前，禁止直接实现代码。

禁止事项

  • 禁止直接实现代码，本 Issue 只出设计文档
  • 禁止把候选表结构当成最终表结构
  • 禁止 Admin 用户和 C 端用户混用同一套认证体系
  • 禁止 C 端用户 token 访问 /admin-api/*
  • 禁止 Admin token 访问 /api/* 的 C 端接口（Admin 查看 C 端数据走 Admin 专属接口）
  • 禁止 RefreshToken 明文存入数据库
  • 禁止 User 模块直接操作 COS（头像上传走 File Storage Module）
  • 禁止 User 模块直接操作 Quota/Cost 表
  • 禁止跨模块直接访问 Prisma model（必须通过 QueryService/CommandService）
  • 禁止把邮箱密码登录作为默认方案（知习面向 iOS，Apple 登录是首选）
## 目标 设计知习 C 端用户的注册、登录、账号基础能力，为所有 C 端业务模块（知识库、学习、复习、额度等）提供统一的用户身份底座。 本 Issue 只做模块架构设计，不直接实现代码。需先输出完整设计方案，经审核确认后，再进入后续实现 Issue。 --- ## 背景说明 知习面向 iOS 和 Web 用户，首选 Apple 登录作为主要登录方式。C 端用户体系需要与 Admin 管理员体系完全隔离——两者的登录入口、token、数据表都是两套独立系统。 User & Account Module 是 M0 基础能力闭环的最后一块拼图。做完这个模块后，后续所有 C 端业务模块才能有统一的身份校验基础。 --- ## 模块职责 请设计 User & Account Module 的完整职责边界。 本模块负责： - C 端用户注册（Apple 登录为主要方式） - Apple Sign In 完整流程（验证 identityToken、关联 AuthAccount） - 用户基础资料（昵称、头像引用、个人简介） - 用户状态管理（正常、禁用、注销申请中、已注销） - RefreshToken 签发与轮换 - 用户设备记录（iOS 设备标识、推送 token） - 账号注销申请（软删除 → 冷静期 → 正式删除） - C 端身份鉴权 Guard，供所有 `/api/*` 路由使用 本模块不负责： - Admin 管理员登录与权限（走 Admin Auth & RBAC Module） - 会员计划与额度扣减（走 Quota Module） - 文件上传签名和 COS 管理（走 File Storage Module） - AI 调用、内容审核、学习/复习业务逻辑 - 推送通知发送（走 Notification Module） 与其他模块的边界： - Admin Auth & RBAC：Admin 可通过 Admin API 管理 C 端用户（禁用/恢复/查看） - Audit & Security：Admin 操作用户状态时触发审计日志 - File Storage：用户头像上传走 File Storage，本模块只存 objectKey 引用 - Traffic Protection：登录接口需要限流保护 - Content Safety：昵称和简介需要敏感词审核 - Notification：用户注销、状态变更等关键事件通知 --- ## 候选数据对象 以下对象为候选设计，请根据模块职责判断最终保留哪些、是否需要拆分或合并。 - **User**：C 端用户主表。核心字段：唯一标识、昵称、头像引用（File Storage objectKey）、个人简介、状态、注册时间、最近登录时间、软删除标记 - **AuthAccount**：第三方登录绑定。核心字段：provider（apple）、providerUserId（Apple user identifier）、关联 User、绑定时间。注意 Apple 的 user identifier 对同一开发者账号是稳定的，可做唯一约束 - **RefreshToken**：token 表或 Redis 管理。需考虑：hash 存储、有效期、轮换策略、设备关联、失效机制（用户禁用/注销/主动退出） - **UserDevice**：用户设备记录。核心字段：设备标识、设备名称、操作系统版本、推送 token、首次登录时间、最近活跃时间 - **AccountDeletionRequest**：账号注销申请。核心字段：关联用户、申请时间、冷静期截止时间、处理状态（pending/processing/completed/cancelled）、处理人（Admin） 请输出： 1. 最终建议保留哪些表及其用途 2. 每张表的字段设计和关键约束 3. 索引设计和软删除策略 4. 状态枚举值定义 5. 表间关联关系 --- ## 存储与基础设施依赖 请逐项判断本模块是否需要以下基础设施，并说明理由： 1. **MySQL**：用户数据必须持久化存储，User/AuthAccount/UserDevice/AccountDeletionRequest 都需要 MySQL 表 2. **Redis**：是否需要？用于哪些场景？ - Apple 登录 nonce 缓存（验证 identityToken 时需要） - 登录限流计数 - RefreshToken 黑名单（用户退出或禁用后立即失效） - 短期状态缓存（用户资料、设备列表） 3. **COS**：本模块不直接操作 COS。用户头像通过 File Storage Module 处理，本模块只存储 File Storage 返回的 objectKey 4. **BullMQ**：是否需要异步任务？ - 账号注销后的数据清理（关联知识库、学习记录等的异步删除） - 注销冷静期到期后的自动处理 5. **Qdrant**：不需要。用户模块不涉及向量检索 6. **AI Gateway**：不需要。用户模块不涉及 AI 调用 7. **Content Safety**：昵称和简介在创建/修改时需要审核，但通过 Content Safety Module 提供的中间件或接口调用，不直接依赖审核 API 8. **Audit & Security**：Admin 操作用户状态（禁用/恢复/处理注销）时必须写审计日志，但通过 Audit Module 接口写入，不直接操作审计表 --- ## API 设计 请设计本模块的 API 路由。 ### CAPI `/api/*` 候选接口（请根据设计判断最终清单和路径）： - Apple 登录（接收 identityToken，验证后签发 AccessToken + RefreshToken） - 刷新 Token（用 RefreshToken 换新 AccessToken） - 退出登录（失效当前 RefreshToken） - 获取当前用户资料 - 修改用户资料（昵称、简介、头像） - 获取用户设备列表 - 绑定/解绑设备 - 申请账号注销 - 取消注销申请（冷静期内） ### AAPI `/admin-api/*` 候选接口： - C 端用户列表（分页、搜索、筛选状态） - C 端用户详情（基础资料、设备列表、登录记录、认证方式、注销申请状态） - 禁用/恢复 C 端用户 - 查看指定用户的设备记录 - 查看指定用户的登录记录 - 处理注销申请（确认删除或驳回） Admin 使用独立的 Admin token 体系，不能复用 C 端用户的 AccessToken。 ### IAPI `/internal/*` 是否需要内部接口？如果需要，请设计： - 根据 userId 批量查询用户基础信息（供其他模块的 QueryService 使用） --- ## Service 划分 请设计本模块的服务分层。建议按以下维度拆分： - **UserCommandService**：用户写操作（创建、更新资料、状态变更） - **UserQueryService**：用户查询（单个/批量查询、搜索），对外暴露给其他模块 - **AuthCommandService**：登录/退出/刷新 token 等认证写操作 - **AuthQueryService**：认证相关查询（设备列表、登录记录） - **UserPolicyService**：业务规则判断（注销条件、状态转换合法性） - **UserEventHandler**：用户相关事件的消费和发布 要求： - 跨模块读操作必须走 UserQueryService - 跨模块写操作必须走 UserCommandService 或通过 Domain Event - 禁止其他模块直接访问 User 模块的 Prisma model --- ## 安全设计 请重点设计以下安全问题： 1. Apple 登录流程： - 客户端获取 Apple identityToken - 服务端向 Apple 验证 identityToken 的有效性 - 验证通过后，通过 providerUserId 查找或创建 AuthAccount + User - 签发 AccessToken + RefreshToken 2. RefreshToken 安全： - 是否 hash 存储 - 轮换策略（每次刷新是否换新 RefreshToken） - 有效期设定 - 用户禁用/退出/注销后如何立即失效 3. AccessToken： - 有效期（建议 15-30 分钟） - 签发方式（JWT 或 opaque token） 4. 设备管理： - 同一设备重复登录如何处理 - 设备数量是否设上限 5. 注销流程： - 申请注销 → 冷静期 → 正式删除 - 冷静期内用户可取消 - 正式删除后关联数据如何处理（异步清理还是标记删除） 6. 用户状态枚举： - NORMAL（正常） - DISABLED（已禁用） - DELETION_REQUESTED（注销申请中） - DELETED（已注销） --- ## Domain Event 设计 请设计本模块需要发布的 Domain Event。 候选事件： - UserRegistered：新用户注册完成 - UserProfileUpdated：用户资料变更 - UserDisabled：Admin 禁用用户 - UserEnabled：Admin 恢复用户 - UserDeletionRequested：用户申请注销 - UserDeletionCancelled：冷静期内取消注销 - UserDeleted：用户正式删除 - UserLoggedIn：用户登录（可用于更新 Growth/每日活跃等统计） - UserLoggedOut：用户退出 请说明： 1. 每个事件的触发时机 2. 事件 payload 的关键字段 3. 哪些事件需要可靠持久化（涉及跨模块副作用的，如 UserDeleted 触发数据清理） 4. 哪些模块可能订阅这些事件 --- ## Admin 视图设计 请设计 Admin 中的 C 端用户管理视图。 1. 用户列表页： - 昵称、注册方式（Apple）、状态、注册时间、最近登录时间、设备数 - 支持搜索（昵称/ID）、筛选（状态）、分页 2. 用户详情页： - 基础资料（昵称、头像、简介、注册时间） - 认证信息（Apple 绑定、绑定时间） - 设备列表（设备名称、系统版本、首次登录、最近活跃） - 登录记录摘要（最近 N 条） - 账号状态与操作（禁用/恢复、查看注销申请） 3. 操作审计： - Admin 禁用/恢复用户必须写入 AuditLog - 处理注销申请必须写入 AuditLog --- ## 交付检查 - [ ] 路由归属：请设计 CAPI / AAPI / IAPI 的完整路由清单 - [ ] 是否需要 Prisma migration：请输出 Prisma schema 草案 - [ ] 是否需要 MySQL：请确认表列表和用途 - [ ] 是否需要 Redis：请判断并说明使用场景 - [ ] 是否需要 COS：请判断（预期不需要直接操作，头像走 File Storage） - [ ] 是否需要 BullMQ：请判断注销清理等异步任务是否需要 - [ ] 是否需要 Qdrant：请判断（预期不需要） - [ ] 是否需要 AI Gateway：请判断（预期不需要） - [ ] 是否需要 Content Safety：请判断昵称/简介审核的接入方式 - [ ] 是否需要 Cost 记录：请判断（预期不需要） - [ ] 是否需要 AuditLog：请列出需要审计的操作和触发点 - [ ] 是否需要 Domain Event：请列出最终事件清单 - [ ] 是否需要 Admin 视图：请给出页面和接口设计 - [ ] 是否需要 E2E / 集成测试：请列出关键测试场景 - [ ] 是否需要 OpenAPI：请给出 OpenAPI 分组建议 --- ## 验收标准 本 Issue 完成后，交付一份 User & Account Module 架构设计文档。文档必须包含： 1. 模块职责边界（明确本模块负责和不负责的内容） 2. API 路由设计（CAPI/AAPI/IAPI 完整清单和路径） 3. 基础设施依赖判断（MySQL/Redis/COS/BullMQ 的使用方案） 4. Prisma schema 草案 5. CommandService / QueryService 划分方案 6. Domain Event 清单及触发时机 7. 安全策略（Apple 登录流程、Token 管理、注销流程） 8. Admin 视图设计 9. E2E / 集成测试场景设计 10. 不建议当前阶段实现的内容 11. 建议拆分出的后续实现 Issue 审核通过前，禁止直接实现代码。 --- ## 禁止事项 - 禁止直接实现代码，本 Issue 只出设计文档 - 禁止把候选表结构当成最终表结构 - 禁止 Admin 用户和 C 端用户混用同一套认证体系 - 禁止 C 端用户 token 访问 `/admin-api/*` - 禁止 Admin token 访问 `/api/*` 的 C 端接口（Admin 查看 C 端数据走 Admin 专属接口） - 禁止 RefreshToken 明文存入数据库 - 禁止 User 模块直接操作 COS（头像上传走 File Storage Module） - 禁止 User 模块直接操作 Quota/Cost 表 - 禁止跨模块直接访问 Prisma model（必须通过 QueryService/CommandService） - 禁止把邮箱密码登录作为默认方案（知习面向 iOS，Apple 登录是首选）
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:16 +08:00
wangdl self-assigned this 2026-05-22 21:00:16 +08:00
wangdl changed title from M0-14 User & Account 基础身份能力 to M0-14A User & Account 模块架构设计 2026-05-22 21:23:09 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#14
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?