docs(wiki): replace 3 archived design docs with new wiki contents

1# API 用户关联 UUID 改造计划

3## 1. 背景

5当前项目的多个 API 响应 DTO 直接暴露用户关联 UUID，例如 `author_id`、`user_id`、`creator_id`、`owner_id`、`actor_id`、`publisher_id` 等。不同领域还存在多套重复且字段不一致的用户投影：

7- profile 领域的 `UserPublic`；

8- auth 领域的 `UserPublic`；

9- repo 领域的 `UserMini` 与多个 `UserSummary`；

10- issues 领域的 `IssueUserView`；

11- post、project、space 等领域直接返回裸 UUID。

13这会导致以下问题：

15- 公开 API 泄露裸用户标识，调用方无法直接获得展示所需的基础信息；

16- 用户投影的字段命名不一致，例如 `uid`/`id`、`avatar`/`avatar_url`；

17- 部分投影可能携带 email 等不应默认公开的字段；

18- DTO 直接从数据库模型转换，批量关联用户时容易产生 N+1 查询；

19- OpenAPI schema、handler、usecase 和测试之间的响应契约不统一。

21## 2. 核心目标

231. 所有公开 API 响应中，用户关系不再以裸用户 UID 或用户关联 UUID 返回。

242. 用户关系统一返回类似以下结构的公开基础信息：

26 ```rust

27 UserBasicInfo {

28 uid,

29 username,

30 display_name,

31 avatar_url,

32 ...

33 }

34 ```

363. 用户已确认采用直接迁移：删除旧的响应字段，不同时保留 `*_id` 和嵌套用户对象。

374. 通过共享批量加载逻辑避免逐条查询用户，防止引入 N+1 查询。

385. 统一更新 DTO、mapper、usecase、handler、OpenAPI schema 和测试。

40## 3. 范围边界

42### 3.1 领域覆盖清单

44本次改造是跨领域的 API 响应契约迁移，不是只修改 `user` 模块。以下领域均属于一等范围：

46| 领域 | 重点用户关系响应 |

47| --- | --- |

48| `user` / `auth` / profile / social | 公开用户、登录用户、本人信息、关注/屏蔽关系、通知 actor |

49| `project` | creator、lead、activity actor、project member |

50| `issues` / `issue` | issue author、member、watcher、event actor、mention/user 关系 |

51| `space` | owner、member、invited_by、invite user、ban user/banned_by |

52| `repo` / pull request | PR author、comment/review/event user、collaborator、publisher、assignee、reviewer、commit author/committer、fork owner |

53| `post` | post/reply author、last reply、reaction/mention/watch user |

55每个领域都必须从 response DTO、mapper、usecase、handler、OpenAPI schema 和测试链路完整迁移；不能只新增 `UserBasicInfo` 而遗漏某个领域的裸用户关系。

57### 3.2 需要迁移

59- 已确认属于 HTTP 公开响应的用户关系字段；

60- 各领域 response view 中的用户作者、所有者、创建者、操作者、发布者、成员、审核者等关系；

61- 负责构造这些响应的 usecase、mapper 和 handler；

62- 对应的 serde/OpenAPI schema、fixtures 和行为测试。

64### 3.3 明确保留不变

66- request body DTO 中的用户 UUID；

67- path、query、分页过滤器中的用户 UUID；

68- 领域实体 ID，例如 `issue_id`、`project_id`、`space_id`、`repo_id`、`channel_id`、`message_id`、`comment_id`、`review_id`、`role_id` 等；

69- JWT、session、数据库模型、存储映射和其他未确认处于 HTTP 序列化边界的内部结构；

70- `AppResponseData<T>` 信封及其通用 `IntoResponse` 序列化逻辑。

72### 3.4 需要单独评估

74- 本人/鉴权响应中的特权字段；

75- 管理员、审计、举报和安全相关响应；

76- 有隐私规则的 profile-detail 响应；

77- chat 等看似 API view、但需要确认 handler/OpenAPI 暴露边界的结构。

79## 4. 已确认的代码边界

81项目是大型 Rust monorepo。主要响应序列化边界如下：

83- `lib/export/data.rs`：`AppResponseData<T>`，负责统一响应 envelope 和 Axum `IntoResponse`；

84- `lib/webapi/openapi.rs`：组合 webapi、auth、issues、post、project、repo、space、user 的 OpenAPI 文档；

85- `lib/export/openapi.rs`：处理 API path 前缀；

86- 各领域 handler/openapi 模块：注册具体 response DTO 和 schema；

87- 各领域 feature usecase：从 DB model 或查询结果构造 response view。

89现有 profile social usecase 已有可复用的批量加载模式：收集 UID，使用 `uid.is_in(...)` 一次查询用户，构造 `HashMap<Uuid, user_model::Model>`，然后映射嵌套用户对象。新实现应抽取或复用这一模式，而不是在每个领域重复实现。

91## 5. 目标公共用户投影

93### 5.1 新增 canonical 类型

95在合适的公共 export/user 模块中新增并导出 `UserBasicInfo`，建议候选位置为：

97- `lib/export/user/basic.rs`；

98- 或项目已有的公共 user/export 模块，避免与 auth/profile feature 形成反向依赖。

100最终位置应遵循 workspace crate 依赖方向，并保证各领域 DTO 可以稳定引用。

102### 5.2 字段策略

104默认只包含公开、低敏感、适合列表和关联展示的字段：

106- `uid`：公开用户标识，类型和序列化形式需统一；

107- `username`；

108- `display_name`；

109- `avatar_url`，或经确认后统一使用现有 avatar 命名；

110- 其他确有公开需求且经过隐私评估的基础字段。

112默认不包含：

114- email；

115- active、admin、restricted 等状态和权限字段；

116- last login；

117- 安全、会话、设备和内部审计字段；

118- profile-detail 中受隐私规则保护的字段。

120需要明确 `uid` 是允许作为嵌套 `UserBasicInfo` 的公开字段返回的用户标识，而不是继续作为 response 顶层裸关联字段返回。

122### 5.3 兼容策略

124用户已确认直接迁移为 breaking change：

126- 删除公开 response 中的 `author_id`、`user_id`、`creator_id`、`owner_id` 等用户关系字段；

127- 不保留旧字段作为兼容字段；

128- 使用语义化嵌套字段，例如 `author`、`user`、`creator`、`owner`、`actor`、`publisher`、`invited_by`；

129- 更新 API 文档和测试中的预期 JSON。

131## 6. 缺失用户策略（已确认）

133已确认：当关联用户已删除、不可见或无法加载时，统一返回 `null`，而不是返回裸 UUID 或伪造用户对象。该规则同时适用于 required 和 optional 用户关系，不因单个关联缺失而让整个响应失败。

135活动、事件、通知等历史响应中的用户关系也必须迁移；历史数据无法解析用户时同样返回 `null`。如未来需要保留历史展示名称，应使用独立的非 UUID 快照字段，不能恢复裸用户关联 UUID。

137## 7. 实施步骤

139### 阶段一：建立公共类型和加载器

1411. 确定 `UserBasicInfo` 的 crate/module 位置和字段 allowlist。

1422. 实现 DB user model 到 `UserBasicInfo` 的显式转换。

1433. 抽取可复用的批量 user loader：

144 - 输入去重后的 `Uuid` 集合；

145 - 空集合不发起数据库查询；

146 - 单次查询并返回 `HashMap<Uuid, UserBasicInfo>` 或带缺失状态的映射；

147 - 明确删除、不可见和不存在用户的处理；

148 - 支持 required/optional 关系的不同映射方式；

149 - 不把 email、权限和安全字段带入公共投影。

1504. 为 loader 增加查询次数、去重和缺失用户测试。

152### 阶段二：迁移现有公共用户投影

1541. 评估 profile `lib/user/features/profile/types.rs::UserPublic` 是否直接改为 canonical 类型，或保留薄 wrapper/re-export。

1552. 评估 auth `lib/auth/features/login/types.rs::UserPublic` 的登录响应是否引用 canonical 类型。

1563. 使 social follower/following/blocked 响应使用 canonical 投影。

1574. 处理 `ProfileView` 的 `user_id`：遵循 profile 隐私规则，改为 `user: Option<UserBasicInfo>`，移除裸 `user_id`。

1585. 保留 `UserMe` 的本人/特权字段，但不要把它当作公开 `UserBasicInfo` 使用。

160### 阶段三：迁移 post 和 issues

162涉及主要文件：

164- `lib/export/post/views.rs`；

165- `lib/export/issues/issue.rs`；

166- `lib/export/issues/issue_member.rs`；

167- `lib/export/issues/issue_watch.rs`；

168- `lib/export/issues/issue_event.rs`；

169- `lib/export/issues/issue_user.rs`。

171需要处理的公开关系包括：

173- `PostView.author_id`、`last_reply_by`；

174- `PostReplyView.author_id`、`deleted_by`；

175- post reaction/mention/watch 的 `user_id`；

176- `IssueView.author_id`；

177- issue member/watch/event/user view 的 `user_id`；

178- 删除者、最后回复者等可选关系。

180需要保留的请求字段包括 `ListPostQuery.author_id`、`CreateMentionOption.user_id`、创建/更新 issue/member 等 command 中的用户 UUID。

182各 handler/usecase 应先收集页面内所有用户关系，再批量加载，最后构造 page/list response，避免在 `From<Model>` 中逐条查询。

184### 阶段四：迁移 repo 和 pull request

186涉及主要文件：

188- `lib/export/repo/pull_request.rs`；

189- `lib/export/repo/collab.rs`；

190- `lib/export/repo/release.rs`；

191- `lib/export/repo/extras.rs`；

192- 相关 repo extras、collab、release、pull request usecase/handler。

194需要处理的公开关系包括：

196- `PullRequestView.author_id`；

197- PR comment/review/event 的 `user_id`；

198- `CollaboratorView.user_id`；

199- release publisher；

200- `UserMini`、多个 `UserSummary`；

201- assignee、reviewer、commit author/committer、fork owner 等关联。

203应统一现有 `UserMini`/`UserSummary` 的字段和命名，移除默认 email 暴露。`review_id`、`repo_id` 等 PR/领域 ID 不是用户关系，不能误改。创建、更新、merge、review submit 和 list query 中的请求 ID 保持不变。

205### 阶段五：迁移 project 和 space

207涉及主要文件：

209- `lib/export/project/lifecycle.rs`；

210- `lib/export/project/activities.rs`；

211- project member usecase/handler；

212- `lib/export/space/spaces.rs`；

213- `lib/export/space/members.rs`；

214- `lib/export/space/invites.rs`；

215- `lib/export/space/bans.rs`；

216- 必要时扩展 roles、channels、overwrites 等响应 DTO。

218需要处理的公开关系包括：

220- `ProjectView.creator_id`、`lead_id`；

221- `ActivityView.actor_id`；

222- project member user；

223- `SpaceView.owner_id`；

224- `SpaceMemberView.user_id`、`invited_by`；

225- `SpaceInviteView.user_id`；

226- `SpaceBanView.user_id`、`banned_by`。

228`ActivityView.target_id` 必须根据具体 verb/target 类型判断，不能仅因字段名相近就当作用户关系。`space_id`、`parent_dir`、role/channel/message 等领域 ID，以及 create/add/list command 中的请求用户 UUID 保持不变。

230### 阶段六：迁移 notifications、auth 和管理员响应

2321. `NotificationView.actor_uid` 改为可选嵌套 `actor: Option<UserBasicInfo>`。

2332. auth login/me 继续保留鉴权语义和 `UserMe` 特权字段，但公开登录用户信息应复用 canonical 基础投影，避免同名 DTO 漂移。

2343. `ReportView` 的 `reporter_uid`、`reported_uid`、`resolver_uid` 改为嵌套 `Option<UserBasicInfo>`，并继续执行现有管理员授权检查；不在公开响应中保留裸 UUID。

2354. deletion、suspension、agreement、security 等 account/admin DTO 逐一确认是否为管理员/本人响应；确认属于 HTTP response 的用户关系均改为嵌套公开信息，不能通过全局字段重命名直接迁移。

2365. `chat/storagelayer/mapping.rs`、JWT/session、DB/storage model 只有在确认处于 HTTP response 序列化边界后才纳入迁移。

238### 阶段七：更新 OpenAPI、示例和测试

2401. 为 `UserBasicInfo` 添加 `Serialize`、`Deserialize`、`ToSchema` 以及必要的文档说明。

2412. 更新各领域 response DTO 的 schema 和嵌套关系。

2423. 检查 `lib/webapi/openapi.rs` 的聚合结果和各 handler/openapi 模块注册，确保没有残留旧字段。

2434. 更新 API fixtures、响应 JSON 示例和客户端契约文档。

2445. 不修改 `AppResponseData<T>` 的 envelope 结构。

246## 8. 重点文件清单

248### 公共类型和基础边界

250- `lib/export/data.rs`

251- `lib/export/lib.rs`

252- `lib/export/user/basic.rs`（建议新增）

253- `lib/webapi/openapi.rs`

254- `lib/export/openapi.rs`

256### 用户、鉴权和社交

258- `lib/user/features/profile/types.rs`

259- `lib/user/features/profile/usecase.rs`

260- `lib/user/features/social/types.rs`

261- `lib/user/features/social/usecase.rs`

262- `lib/auth/features/login/types.rs`

263- `lib/auth/features/login/usecase.rs`

264- `lib/auth/handler/me.rs`

265- `lib/export/user/notifications.rs`

267### Post 和 issues

269- `lib/export/post/views.rs`

270- `lib/export/issues/issue.rs`

271- `lib/export/issues/issue_member.rs`

272- `lib/export/issues/issue_watch.rs`

273- `lib/export/issues/issue_event.rs`

274- `lib/export/issues/issue_user.rs`

275- 对应 `lib/post`、`lib/issues` 的 handler/usecase/impls/openapi。

277### Repo 和 pull request

279- `lib/export/repo/pull_request.rs`

280- `lib/export/repo/collab.rs`

281- `lib/export/repo/release.rs`

282- `lib/export/repo/extras.rs`

283- 对应 `lib/repo` 的 usecase/handler/openapi。

285### Project 和 space

287- `lib/export/project/lifecycle.rs`

288- `lib/export/project/activities.rs`

289- `lib/export/space/spaces.rs`

290- `lib/export/space/members.rs`

291- `lib/export/space/invites.rs`

292- `lib/export/space/bans.rs`

293- 对应 `lib/project`、`lib/space` 的 usecase/handler/openapi。

295### CLI/OpenAPI 输出

297- `app/apihost/src/cmd_openapi.rs`

299以上清单是首批重点范围，不代表可以跳过其他公开 response DTO。最终范围必须以序列化边界和 AST 审计结果为准。

301## 9. 测试计划

303### 9.1 类型和序列化测试

305- `UserBasicInfo` 的字段 allowlist 测试；

306- 确认不存在 email、权限、session、安全字段；

307- nested user JSON 使用统一字段名；

308- 所有用户关系（包括 required 和 optional）在用户缺失、删除或不可见时序列化为 `null`；

309- response JSON 中不再出现旧的用户关系 `*_id` 字段。

311### 9.2 loader/usecase 测试

313- 输入 UID 去重；

314- 空 UID 集合不查询；

315- 页面内多个关系只触发一次用户查询；

316- 缺失、删除、不可见用户的处理统一返回 `null`，且不会回退为裸 UUID；

317- required/optional 关系分别覆盖成功和失败分支；

318- 映射结果保持原有列表顺序。

320### 9.3 handler/行为测试

322至少覆盖：

324- post author/reply/reaction/mention/watch；

325- issue author/member/watch/event/user；

326- pull request author/comment/review/event；

327- repo collaborator/release/extras；

328- project creator/lead/activity/member；

329- space owner/member/invite/ban；

330- notification actor；

331- profile public、social、auth login/me；

332- admin/audit response 的权限和脱敏行为。

334现有测试按行为命名，不能只搜索 `*test*.rs`。重点测试目录包括：

336- `lib/issues/tests/`；

337- `lib/post/tests/`；

338- `lib/repo/tests/pull_request/`；

339- 相关 `lib/project`、`lib/space`、`lib/user`、`lib/auth` 测试。

341### 9.4 OpenAPI 测试

343- 更新已有 post、pull request OpenAPI 测试；

344- 为受影响领域补充 schema 断言；

345- 确认生成 schema 使用 `UserBasicInfo`，且旧裸 UUID 用户关系字段已删除；

346- 检查响应中的领域 ID 仍然存在且类型未被误改。

348## 10. 验证和审计

350实现后按受影响 workspace crate 执行：

3521. `cargo fmt`；

3532. 对 `export`、`user`、`auth`、`issues`、`post`、`repo`、`project`、`space`、`webapi`、`apihost` 进行 `cargo check`；

3543. 运行相关领域测试和 OpenAPI 测试；

3554. 必要时运行完整 workspace test；

3565. 生成并检查 OpenAPI 文档；

3576. 使用 grep/AST 审计所有公开 response DTO：

358 - 找出用户关系字段仍为裸 `Uuid` 的响应结构；

359 - 排除 request/path/query、领域 ID、内部结构和经确认的管理员审计例外；

360 - 审查所有 `From<Model>` 直接返回 response 的路径；

3617. 检查查询日志或 mock query 次数，确认没有新增 N+1。

363## 11. 验收标准

365- 公开 response 中的用户关系均为统一的嵌套 `UserBasicInfo` 或明确的受控审计投影；

366- 旧的公开 `author_id`、`user_id`、`creator_id`、`owner_id` 等用户关系字段已按直接迁移决策删除；

367- request、path/query、领域和内部 ID 未被误改；

368- `UserBasicInfo` 不包含 email、权限、session、安全或未授权 profile 字段；

369- optional 关联用户的缺失行为符合最终确认的策略；

370- 批量关系加载无 N+1，空集合和缺失用户行为有测试；

371- OpenAPI schema、示例和实际 JSON 一致；

372- 受影响领域测试、OpenAPI 测试、格式化和编译验证通过；

373- 最终 AST/序列化边界审计有明确的 intentional exceptions 清单。

375## 12. 待审查问题

3771. `UserBasicInfo.uid` 的公开字符串格式是否统一沿用现有 UUID 序列化方式？该细节不影响字段结构和迁移范围。

379本文件只记录改动计划，待审查确认后再实施业务代码变更。

381---

383## 13. 实施状态（2026-08-12 已执行完毕）

385- 共享基础设施：新增 `lib/db/user/users_loader.rs`（`load_users`/`load_user` 批量/单点加载，防 N+1）与 `lib/export/user/basic.rs`（canonical `UserBasicInfo { uid, username, display_name, avatar_url }`）。

386- 全部域迁移完成：user（profile/social）、post、issues、repo（PR/collab/release/extras/subscriber）、project（lifecycle/activities/members/documents/views/favorites）、space（spaces/members/invites/bans/roles/channels/overwrites）、user（notifications/admin reports/suspensions/deletion）。所有响应 DTO 改为嵌套 `Option<UserBasicInfo>`，删除裸用户关系字段与 `From<Model>`，改用公开 `from_model(m, ...)` 构造方法。

387- 请求 DTO、path/query 参数、领域/内部 ID 全部保留；`AppResponseData<T>` 信封未改。

388- 验证：`cargo check --workspace` 通过；`cargo fmt` 通过；裸 UUID 审计通过（残留 17 处均为请求 DTO/查询参数/领域 ID）；`cargo test -p export -p user -p issues -p post -p project -p repo -p space` 全部通过（含 space 4 个 rename 测试，测试辅助已补 space_members 表 DDL）。

389- 未提交，改动保留在工作树中。