Merge remote-tracking branch 'origin/master' into feat/pricing-plan
Project CI / AI game creator shell Rust crates (pull_request) Successful in 6m0s
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Successful in 6m43s
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Successful in 7m42s
Project CI / Frontend tests (pull_request) Failing after 1m16s
Project CI / Backend tests (pull_request) Successful in 8m51s
Project CI / AI game creator shell web tests (pull_request) Successful in 3m34s
Project CI / Repository checks (pull_request) Successful in 5m34s
Project CI / Native shell tests (pull_request) Successful in 7m18s
Project CI / AI game creator shell Rust crates (pull_request) Successful in 6m0s
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Successful in 6m43s
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Successful in 7m42s
Project CI / Frontend tests (pull_request) Failing after 1m16s
Project CI / Backend tests (pull_request) Successful in 8m51s
Project CI / AI game creator shell web tests (pull_request) Successful in 3m34s
Project CI / Repository checks (pull_request) Successful in 5m34s
Project CI / Native shell tests (pull_request) Successful in 7m18s
# Conflicts: # docs/project-memory/shared-memory/decision-log.md
This commit is contained in:
@@ -0,0 +1,186 @@
|
||||
# 创作者主页与关注粉丝工程设计
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | implemented（工程验证通过，用户已确认提交交付，未部署） |
|
||||
| Date | 2026-10-05 |
|
||||
| Parent Spec | [创作者主页与关注粉丝合同](../【玩法创作】平台入口与玩法链路-2026-05-15.md#创作者主页与关注粉丝合同) |
|
||||
|
||||
本文明确主站创作者主页、关注关系和列表操作的工程边界。产品行为以父规范为准；后端实现及隔离验证已由用户验收通过，前端已完成工程验证，用户已要求提交并推送。
|
||||
|
||||
## 当前实现与修改边界
|
||||
|
||||
| 层 | 现有入口与修改范围 |
|
||||
| --- | --- |
|
||||
| 主站导航 | `src/components/platform-entry/PlatformEntryActiveFlowShell.tsx`、`platformEntryActiveTypes.ts`、`src/routing/activeAppPageRoutes.ts`；增加创作者主页与关系列表 stage，保持既有创作/项目/游戏/我的入口 |
|
||||
| 详情与公共 UI | `src/components/game-distribution/GameDetailPage.tsx`、`packages/shared/src/components/GameDetailDisplay/`；扩展作者区域插槽，公共关注按钮和用户行放共享组件 |
|
||||
| 新页面与访问层 | 在 `src/components/creator/`、`src/services/creatorProfileClient.ts` 增加主页、关系列表和 HTTP 访问；复用现有认证、响应解包、错误处理和游戏卡表现 |
|
||||
| DTO | `server-rs/crates/shared-contracts/src/creator.rs`、`packages/shared/src/contracts/creator.ts`；分别在现有导出入口注册 |
|
||||
| 领域 | `module-auth` 内新增纯关系规则子模块；不新增账号系统，不把 HTTP、数据库和 UI 状态放入领域规则 |
|
||||
| 持久化 | `spacetime-module` 新增关系模块，复用 `auth/tables.rs` 中的用户身份；同步模块注册、`migration.rs`、表目录和生成绑定 |
|
||||
| Facade | `spacetime-client` 新增 creator typed facade 与 mapper，复用现有连接和受信服务身份 |
|
||||
| HTTP | `api-server/src/modules/creator.rs` 与 `modules`/`app.rs` 注册；认证由现有 access token 校验链提供 |
|
||||
| 作者游戏 | 扩展现有 game-distribution 列表 query、共享内部输入及 facade/procedure，增加可选 `authorId` 精确过滤 |
|
||||
| 深链部署 | 按新增稳定路由同步 nginx SPA 路由及 Pingora 路由对照，覆盖直接访问、刷新与未知路径回退 |
|
||||
|
||||
以上新增文件是拟定落点，实施时可按相邻模块组织拆分，但不得建立第二套身份、作品或数据访问系统。不涉及 AGC 桌面客户端、外部 OpenAPI、后台管理页或游戏运行态。
|
||||
|
||||
源码已确认：公开游戏列表和“我的游戏”一次最多取 48 项，公开列表 `nextCursor` 固定为 null，前端 `listGames` 只返回数组；游戏广场的设备过滤发生在这份数组上。用户明确本次不额外改造这些现状。创作者主页只增加服务端作者过滤，沿用最多 48 项和原排序，不增加游戏分页、加载更多或新的筛选控件。
|
||||
|
||||
## 关系模型和授权
|
||||
|
||||
私有表 `user_follow`：
|
||||
|
||||
| 字段 | 类型与约束 |
|
||||
| --- | --- |
|
||||
| `relationship_id` | String 主键；编码为关注方 ID 的 UTF-8 字节长度、冒号、关注方 ID、被关注方 ID，保证有向用户对无歧义唯一 |
|
||||
| `follower_user_id` | String，关注发起方；建立对应索引 |
|
||||
| `followee_user_id` | String，被关注方；建立对应索引 |
|
||||
| `created_at` | Timestamp，只在关系首次建立时取事务时间；重复关注不改时间 |
|
||||
|
||||
同一用户对最多一行，双方不得相同。删除后重新关注视为新的建立时间。不另存关系计数、昵称、头像或互关布尔值；读时按对应方向索引计算，并以 `user_account` 当前存在性过滤对端。当前账号表和公开查询没有独立的封禁/公开状态，不能凭空增加状态字段。
|
||||
|
||||
`module-auth` 的现有认证服务通过默认启用的 `services` feature 保持原有导出；API 和 facade 显式启用该 feature。数据库仅依赖关闭默认 feature 的纯关系模块，避免将短信、网络和宿主运行时依赖引入 WASM。用户 ID 上限为 256 UTF-8 字节，游标上限为 4096 字节；空值、控制字符及超长输入拒绝，游标未知字段和非规范时间戳拒绝。
|
||||
|
||||
写入沿用项目受信 API 服务身份调用 procedure 的模式：HTTP 从已验证 access token 派生操作者 ID，procedure 先校验调用服务身份，再在事务内检查操作者、目标和方向。普通客户端不能直接传入任意操作者绕过认证。新表不进入认证全量快照替换流程，登录或刷新账号资料不能清空关系。
|
||||
|
||||
关注只插入 `actor → target`；取消只删除同一方向；移除粉丝只删除 `follower → actor`。事务回执返回 actor 相对目标的最新关系，不把移除粉丝误报为 actor 已取消关注。用户不再存在时不暴露其资料，计数和列表同步排除；本次不增加账号注销或清理任务。
|
||||
|
||||
## HTTP 与 DTO
|
||||
|
||||
接口路径、方法和错误状态见父规范，统一复用现有成功/错误响应信封。以下形状是信封内的数据字段，Rust 使用 camelCase 序列化，TS 同名。
|
||||
|
||||
```ts
|
||||
type CreatorUser = {
|
||||
id: string;
|
||||
publicUserCode: string;
|
||||
displayName: string;
|
||||
avatarUrl: string | null;
|
||||
};
|
||||
type CreatorRelationship = {
|
||||
isSelf: boolean;
|
||||
isFollowing: boolean;
|
||||
isFollowedBy: boolean;
|
||||
};
|
||||
type CreatorProfile = {
|
||||
user: CreatorUser;
|
||||
followingCount: number;
|
||||
followerCount: number;
|
||||
};
|
||||
type CreatorConnection = {
|
||||
user: CreatorUser;
|
||||
followedAt: string; // 当前列表所表示方向的建立时间，RFC 3339
|
||||
relationship: CreatorRelationship | null; // 仅本人读取自己的列表时返回，其他情况为 null
|
||||
};
|
||||
type CreatorConnections = {
|
||||
items: CreatorConnection[];
|
||||
nextCursor: string | null;
|
||||
total: number;
|
||||
};
|
||||
type CreatorRelationshipResponse = {
|
||||
userId: string; // 相对当前访问者的目标；移除粉丝时为 followerId
|
||||
relationship: CreatorRelationship;
|
||||
};
|
||||
```
|
||||
|
||||
`CreatorUser` 从现有公开资料投影所需字段，不返回手机号、登录名、钱包或认证数据。主页返回 `CreatorProfile`；关系列表返回 `CreatorConnections`；关系 GET 与三种写操作返回 `CreatorRelationshipResponse`。写请求无需 body，身份只来自认证，路径 ID 按统一规则 trim、校验并安全编码。
|
||||
|
||||
关系写操作成功返回 200，目标存在时重复关注/删除仍成功；对自己操作返回 400，未认证为 401，非受信或越权调用为 403，不存在的用户为 404。有效目标但不存在关系的删除与“目标不存在”明确区分。前端不自动重试结果未知的写请求，先回读关系。
|
||||
|
||||
主页摘要一次事务内完成用户和双向计数读取；关系列表一次事务内读取 `items/total`，仅已认证访问者 ID 等于列表主人时附带逐行关系。游客或访问他人列表时，following 只查询主人出边、followers 只查询主人入边及对应公开用户资料，不额外探测访问者与列表用户的关系，逐行 `relationship` 固定为 null。该条件由后端认证身份与路径主人 ID 决定，不接受客户端开关绕过。不同 HTTP 请求不承诺共享同一事务快照，跨页变化通过写后失效与回读收敛，不能要求两次独立请求永远返回相同计数。
|
||||
|
||||
公开主页不携带访问者状态；`relationship` 端点必须认证。列表无 Authorization 时按游客读取，有 Authorization 时校验并判断是否本人列表；他人的关注、粉丝列表始终跳过访问者关系计算，只有自己的列表批量返回所需关系。无效凭据返回 401，前端经现有认证处理后可回到游客读取。关系端点和带认证列表响应使用 `Cache-Control: private, no-store`，不得进入跨用户缓存。
|
||||
|
||||
## 关系列表分页与作者游戏读取
|
||||
|
||||
关注/粉丝列表的查询参数为 `limit`、`cursor`；默认 20，上限 50，非整数或超范围返回 400。按 `(created_at DESC, relationship_id DESC)` 排序，游标包含版本、列表主人、following/followers 类型与末项排序键；使用有长度上限的 base64url JSON 编码并严格解析，时间戳用十进制字符串避免 JS 精度损失。游标只是分页定位，不作为授权证明。
|
||||
|
||||
先排除不存在的对端，再计算 total 和分页；读取 limit+1 判断是否还有下一页。同时间多行不漏读，游标主人或类型不匹配返回 400。并发增删不保证多页构成冻结快照，按 userId 去重，刷新从首批开始；不引入跨请求数据库快照或游标持久化表。
|
||||
|
||||
作者游戏只扩展现有 `GET /api/game-distribution/games` 的 `authorId`：未传保持原行为，显式空值返回 400；先按稳定 owner ID 和既有公开条件过滤，再排序、截取最多 48 项。现有条件包含 published、未删除及有效公开版本。前端 `GameListQuery` 增加可选 authorId，仍返回现有游戏数组；不修改游戏表结构或引入新的游戏列表系统。
|
||||
|
||||
## 前端状态与组件责任
|
||||
|
||||
- 主页 `/creators` 解析当前账号，`/creators?id=...` 读取指定公开用户；关系列表用 `/creators/connections?id=...&tab=following|followers`，缺主人或非法 tab 展示明确无效链接状态。tab 缺省、空串及其他值均无效，不请求关系列表，并保留返回入口。显式他人 ID 不因登录切换改成自己的主页。
|
||||
- 游戏详情作者昵称只使用 `useGameAuthorDisplayName` 的解析结果，加载中或查询失败时不回退到公开投影的角色占位词；保留头像与可访问的主页链接，关注操作继续按作者 ID 和关系状态控制，不依赖昵称补查成功。
|
||||
- 关系状态按访问者 ID、目标 ID 隔离。业务 hook/client 负责请求、写入单飞、失败回读和失效；共享关注按钮、用户行只接收数据、pending 和回调，不直接持有认证或网络副作用。
|
||||
- 自己/他人的关注列表、粉丝列表四种组合均支持头像/昵称进入任意用户主页；用独立链接和按钮避免嵌套交互。列表用户为自己时隐藏关注按钮，主页仍可访问。
|
||||
- 他人的关注、粉丝列表统一使用只读用户行，不挂载关系动作或触发关系 hook，不调用 relationship 补查接口、不比对访问者自己的关注集合，也不使用预存关系缓存推导按钮。列表切换或账号切换后重新按主人/访问者身份确定模式；进入目标用户主页后，再按主页本身的规则读取关系和提供关注操作。
|
||||
- 取消关注后的行保留集合只属于当前列表生命周期，与服务端成员和 total 分离；成功重新关注后清除暂留标记。刷新、离开列表或账号变化清除暂留集合；正常失效回读时不可把可重新关注的行立即抹掉。
|
||||
- 移除粉丝成功从粉丝列表去行，回关/取消回关不去行。确认弹窗复用公共组件；两个方向的按钮在同一目标写入期间一起禁用，写后刷新摘要和相关列表。
|
||||
- 进入页面、返回和重新聚焦时回读；旧请求通过请求序号/取消机制隔离。认证变化清除私有关系缓存和旧页请求，不让上个账号响应覆盖新账号。
|
||||
- 新主页路由接入页面标题、导航高亮、返回兜底和滚动位置恢复。移动点击区域至少 44px；加载、错误、空态分别呈现，不因关系失败阻断公开游戏阅读。
|
||||
- 返回有应用内历史时使用 `history.back()`；没有时使用 `replaceAppHistoryPath`，关系列表回所属主页，主页回 `/games`，再同步页面状态，禁止通过 `openCreator` 新增兜底历史。主页顶部 `CreatorUserRow` 不传 `href`，渲染无链接、无额外键盘焦点的资料区域；列表和游戏详情继续传入链接与导航回调。
|
||||
|
||||
- 顶层访问层登记到 `vite.config.ts` 的现役模块白名单及 ESLint 范围，开发代理显式转发 `/api/creators`。页面深链同步三份 nginx 模板与 Pingora 路由清单。
|
||||
- 浏览器历史条目仅保存 URL、访问者、已加载页数和滚动位置，不持久化关系列表或暂留行；新导航清除继承的恢复标记。同一舞台切换用户、页签以及返回时，应用重读 URL 并重新渲染。
|
||||
|
||||
## 兼容、验证和交付
|
||||
|
||||
新关系表从空数据开始；同步迁移登记、后端表目录和 Rust 生成绑定。新增 procedure 与 facade 同步发布，不手改生成文件；游戏查询新增的 authorId 是可选能力，旧 HTTP 请求继续有效。后端部署先于新前端，回滚前端不删除关系数据；回滚后端必须保留新表的兼容 schema，禁止删库回退。
|
||||
|
||||
后端已由用户验收通过；页面工程验证完成后，用户要求提交并推送。已将持久结论和验证证据归并到主规范及本文，删除已完成的临时里程碑和实施计划。
|
||||
|
||||
按范围执行以下命令，后端与前端证据见本文对应章节；本文保留逐项验收对照：
|
||||
|
||||
```bash
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p module-auth creator
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server creator
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server game_distribution
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-module creator
|
||||
npm run spacetime:generate
|
||||
npm run check:server-rs-ddd
|
||||
npm run test -- src/components/creator src/routing/activeAppPageRoutes.test.ts src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx src/components/game-distribution/GameDistributionPages.test.tsx
|
||||
npm run typecheck
|
||||
npm run check:nginx-spa-routes
|
||||
npm run check:pingora-route-parity
|
||||
npm run check:encoding
|
||||
npm run check:doc-index
|
||||
git diff --check
|
||||
```
|
||||
|
||||
`creator` 测试组为实施时新增的定向分组，届时核对实际匹配数量，零匹配不算通过；补充共享 DTO/UI 和 facade 的对应测试。host 单测不替代 SpacetimeDB 事务验证，运行时通过 `npm run dev:api-server` 启动并验证实际开发地址 `/healthz`，使用隔离开发库的 A/B/C 三账号完成权限、重复写入、双向关系与未知结果回读。
|
||||
|
||||
浏览器覆盖桌面与 375px 移动，四类列表跳转、返回位置、自己的空游戏主页、互关后移除粉丝和登录切换。他人的关注、粉丝两类列表夹具均包含访问者已关注、未关注及访问者本人，断言一律无关系操作，后端响应 relationship 为 null 且不调用访问者关系投影，前端无补查/写请求；预置关系缓存也不得改变只读表现，点击用户进入主页仍可正常操作。游戏边界夹具包含超过 48 项及其他作者作品，证明作者过滤在截取前，广场原有上限保持不变；关系列表用超过 50 项和同时间关系验证分页。后端可重复运行 `python3 scripts/test-creator-runtime.py --database creator-hub-validation`；执行结果保留在以下证据矩阵中。
|
||||
|
||||
## 后端验证证据
|
||||
|
||||
用户已验收通过关系与公开查询实现，并授权进入页面阶段。
|
||||
|
||||
|
||||
| 对照项 | 验证方式 | 当前结果 |
|
||||
| --- | --- | --- |
|
||||
| 唯一键、方向、自关注与幂等 | 领域测试 + API/数据库回读 | 5 条纯规则测试通过；认证模块完整 45 条通过；运行时重复关注保持原时间、重关更新时间，移除粉丝只删入边 |
|
||||
| 认证与第三方越权 | HTTP 负向用例 + 普通身份调用 procedure | 新增 HTTP 4 条通过；隔离 A/B/C 与普通数据库身份验证 400/401/403/404 和操作者归属 |
|
||||
| 他人两类列表只读、无访问者关系查询 | 路由/投影定向测试 + API 响应 | 模块 1 条测试断言关系查询闭包不执行；facade 2 条通过；游客/他人两类列表运行时 relationship 均为 null，本人列表正常返回 |
|
||||
| 公开字段、计数、分页、账号存在性 | 契约测试 + 多页隔离夹具 | DTO 2 条通过；58 个测试账号、55 个同时间双向关系、失效对端夹具，多页去重与 total/计数一致；错主人/类型游标返回 400 |
|
||||
| 作者游戏过滤与原有 48 项边界 | game-distribution 回归 + API 夹具 | API 44 条与模块 4 条回归通过；55 个目标作者、55 个更晚其它作者、6 个非公开或无有效版本夹具，作者查询与旧广场各返回正确的 48 项 |
|
||||
| Schema、迁移、绑定及认证快照兼容 | 生成检查、DDD 门禁 + 实际运行时回读 | WASM 构建和 CLI 生成通过；schema、DDD、生成绑定、38 组 DTO 对照通过；登录刷新前后关系导出相同 |
|
||||
| 重复/并发写与结果未知 | 事务集成用例与写后查询 | 8 个同向并发只产生一行，相反动作并发后 API 与数据库一致；丢弃写回执后读取正式关系再执行后续意图 |
|
||||
|
||||
2026-10-05 通过仓库启动器启动 `creator-hub-validation`，CLI/standalone 为 2.8.3（固定 commit 核对通过），API `/healthz` 返回 200。可复核运行时证据由 `scripts/test-creator-runtime.py` 的四组 PASS 断言产生，不依赖 host 测试模拟事务。类型、编码、文档索引及 diff 检查通过；本地依赖缺失已按原锁文件恢复，不改依赖版本。
|
||||
|
||||
后端证据边界：不包含生产发布；浏览器与前端交互另见下方前端证据。未知结果用例覆盖丢弃回执后的回读，不冒充真实网络故障注入。游戏夹具只验证公开目录投影，不写对象存储或测试游戏运行态。
|
||||
|
||||
## 前端验证证据
|
||||
|
||||
2026-10-05 工程验证通过，用户确认提交并推送；未部署生产。
|
||||
|
||||
| 合同条款 | 自动化和实际运行证据 |
|
||||
| --- | --- |
|
||||
| 桌面第四入口、移动三入口、标题和深链 | 导航/路由/标题 Vitest；三份 nginx SPA 检查及 Pingora 对照通过；实际浏览器直达与刷新 `/creators`、`/creators/connections`；游客直接访问他人关注/粉丝列表后，返回均落到所属作者主页 |
|
||||
| 本人和他人主页、详情作者和公开游戏 | 主页测试覆盖裸路由登录、显式目标登录后保持、自己无关注按钮、空游戏及独立错误；已关注状态显示“已关注”，可访问名称为“取消关注”；真实 API 页面显示该作者 48 项，详情作者可返回自己主页 |
|
||||
| 四类列表及他人只读 | 前端测试覆盖四类用户链接、预置关系缓存不改变他人只读；实际浏览器验证他人两类列表无按钮、无 relationship 补查请求 |
|
||||
| 暂留、回关及移除方向 | 前端测试和真实浏览器验证取消后原行重新关注、刷新去行、粉丝回关/取消回关、移除确认及取消弹窗；移除后实际 API 确认自己的出边仍在 |
|
||||
| 返回、分页与滚动 | 实际加载 40 行，进入用户主页后返回，重新读取两页并恢复滚动；历史条目只保存位置与页数，新导航不继承暂留行 |
|
||||
| 失效、单飞和身份切换 | 状态测试覆盖重复点击、旧读覆盖保护、退出再登录同账号时丢弃旧写、未知结果只回读、仍未知禁写、回读恢复；页面测试覆盖切账号/目标的迟到响应 |
|
||||
| 桌面和 375px 移动 | Chromium 实际验收无横向溢出、移动三入口、键盘 Enter 进入主页、访客关注仅唤起登录；窄屏按钮移至资料下方，共享组件测试覆盖长昵称和独立交互 |
|
||||
|
||||
定向 Vitest 共 12 个文件、126 项通过；覆盖 creator 页面/状态/访问层、游戏访问层及三个游戏页面、导航、路由、标题、Vite 接入和共享 UI。当前 Node 原生 webstorage 与旧 jsdom 环境冲突，使用 `NODE_OPTIONS=--no-experimental-webstorage npm run test -- ...` 执行；不修改业务存储策略。`npm run typecheck`、`npm run build:raw`、定向 ESLint、Rust 格式检查、编码检查（5319 文件）、文档索引（245 份）及 `git diff --check` 均通过。
|
||||
|
||||
可重复浏览器脚本为 `scripts/test-creator-web.cjs`：先运行隔离后端脚本、再用仓库 `dev:web` 启动同库并把 `RUST_SERVER_TARGET` 指向该隔离 API；脚本从 `.app/dev-stack.json` 读取实际端口，仅接受 `creator-hub-validation` 和 loopback。通过 `CREATOR_PLAYWRIGHT_DIR` 指向临时 Playwright 安装，`PLAYWRIGHT_BROWSERS_PATH` 指向临时浏览器目录。截图输出到临时目录，不提交登录信息、数据库或构建产物。
|
||||
|
||||
返回循环修复的定向验证：共享控件、创作者页面、平台导航与路由共 54 项测试通过，类型、定向 ESLint、编码与文档索引检查通过。真实浏览器确认裸主页点击本人资料不改变地址、返回到游戏广场；直接打开关系列表后连续返回依次到所属主页和广场；加载两页 40 行后进入用户主页，原生返回恢复全部行及滚动位置。
|
||||
|
||||
验证边界：浏览器使用真实 API/SpacetimeDB；超时、旧请求与账号切换由可控前端测试覆盖，没有声称做真实断网注入。游戏夹具无发行包，不验证游玩加载；未部署生产，未用真实用户数据。本次交付按用户指令提交并推送，生产部署另行执行。
|
||||
Reference in New Issue
Block a user