From 25f858667e617352c2d3bd41fe4d6353861c9409 Mon Sep 17 00:00:00 2001 From: lhk Date: Mon, 5 Oct 2026 10:26:29 +0100 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E5=88=9B=E4=BD=9C=E8=80=85?= =?UTF-8?q?=E5=85=B3=E7=B3=BB=E4=B8=8E=E5=85=AC=E5=BC=80=E6=9F=A5=E8=AF=A2?= =?UTF-8?q?=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 明确后端契约、关系事务、接口接入和隔离验证的实施顺序 补充修改边界、验证命令、回滚点与验收证据矩阵 同步主规范、工程设计、里程碑和文档索引入口 --- docs/README.md | 1 + ...施计划】创作者关系与公开查询-2026-10-05.md | 128 ++++++++++++++++++ ...里程碑】创作者关系与公开查询-2026-10-05.md | 2 +- ...案】创作者主页与关注粉丝工程设计-2026-10-05.md | 2 +- ...玩法创作】平台入口与玩法链路-2026-05-15.md | 4 +- 5 files changed, 133 insertions(+), 4 deletions(-) create mode 100644 docs/project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md diff --git a/docs/README.md b/docs/README.md index d3eb0c9fc..e486b628d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ - [网站游戏评分与评价里程碑](./project-memory/plans/【里程碑】网站游戏评分与评价-2026-09-30.md)：唯一评价、编辑预填、4000 字符、公共分页与平均分/人数的验收边界与本地证据。 - [创作者主页与关注粉丝合同](./【玩法创作】平台入口与玩法链路-2026-05-15.md#创作者主页与关注粉丝合同)、[关系与公开查询里程碑](./project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md)和[主页与交互里程碑](./project-memory/plans/【里程碑】创作者主页与关系交互-2026-10-05.md)：产品规则已确认，未实现；第四项默认进入自己主页，他人的关注/粉丝列表统一只读并支持主页跳转。 - [创作者主页与关注粉丝工程设计](./technical/【技术方案】创作者主页与关注粉丝工程设计-2026-10-05.md)：待实现的分层落点、关系表/DTO、授权、关系列表分页、组件状态、深链与验证边界；游戏列表沿用最多 48 项限制，不做额外分页改造。 +- [创作者关系与公开查询实施计划](./project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md)：首阶段开发计划已就绪，明确契约、事务、facade/HTTP、隔离运行时验收顺序与回滚边界；未开始业务实现。 - [后台游戏评价管理合同](./【玩法创作】平台入口与玩法链路-2026-05-15.md#后台游戏评价管理合同)：查找、分页、隐藏/恢复/删除、必填原因、统计与个人状态联动；已实现并通过本地验证，待用户验收，未部署。 - [后台游戏评价管理里程碑](./project-memory/plans/【里程碑】后台游戏评价管理-2026-10-01.md)与[实施计划](./project-memory/plans/【实施计划】后台游戏评价管理-2026-10-01.md)：单里程碑范围、接口/schema 边界及验收要求；本地证据已回写主规范。 - [游戏广场评分展示合同](./【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏广场评分展示合同)、[里程碑](./project-memory/plans/【里程碑】游戏广场评分展示-2026-10-01.md)与[实施计划](./project-memory/plans/【实施计划】游戏广场评分展示-2026-10-01.md)：已实现并通过本地定向验证，待用户验收，未部署；公开列表/详情携带真实摘要，卡片显示一位小数均分与人数，复用有效评价统计。 diff --git a/docs/project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md b/docs/project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md new file mode 100644 index 000000000..03fd65a19 --- /dev/null +++ b/docs/project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md @@ -0,0 +1,128 @@ +# 创作者关系与公开查询实施计划 + +| 字段 | 值 | +| --- | --- | +| Version | 1.0 | +| Status | ready（计划已形成，尚未开始实现） | +| Date | 2026-10-05 | +| Owner | 接手本里程碑的开发者或 Agent | +| Milestone | [创作者关系与公开查询](./【里程碑】创作者关系与公开查询-2026-10-05.md) | +| Parent Spec | [创作者主页与关注粉丝合同](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#创作者主页与关注粉丝合同) | +| Engineering | [创作者主页与关注粉丝工程设计](../../technical/【技术方案】创作者主页与关注粉丝工程设计-2026-10-05.md) | + +## 交付结果与优先级 + +交付可由真实 API 读写、由 SpacetimeDB 持久化的关注关系、公开主页摘要、关注/粉丝分页列表和作者公开游戏查询；以权限、双向关系、幂等、计数、只读列表及游戏过滤的运行时证据验收。 + +必须项：契约与纯规则 → 表与事务 → facade 与 HTTP → 定向测试与隔离环境回读。风险项：服务身份、关系方向、认证快照同步、账号不存在时的统计、生成绑定、作者过滤与 48 项截取顺序。可选的计数缓存、性能专项优化和界面优化不进入本里程碑。 + +开始实施时用约 15 分钟核对分支、最新源文件、工具链和开发环境。按下述四个检查点推进，每个检查点至少输出一次结果；单个阻塞调查超过 30 分钟时记录具体限制并优先完成其余独立必需项，不因调查扩展产品范围。时间盒用于控制调查，不削减验收要求。 + +## 修改边界 + +| 层 | 允许修改的范围 | +| --- | --- | +| 共享契约 | 新增 `server-rs/crates/shared-contracts/src/creator.rs`、`packages/shared/src/contracts/creator.ts` 及导出；对应序列化/契约测试 | +| 领域规则 | `server-rs/crates/module-auth/src/` 新增关系子模块及导出，承载方向、用户对键和输入规则；不依赖数据库或 HTTP | +| 数据与事务 | `server-rs/crates/spacetime-module/src/` 新增 creator 模块、注册入口、`migration.rs`；必要的 `game_distribution.rs` 可选作者过滤 | +| 数据访问 | `server-rs/crates/spacetime-client/src/` 新增 creator facade/mapper、注册入口、内部输入与绑定；game-distribution 输入追加可选作者参数 | +| HTTP | `server-rs/crates/api-server/src/modules/creator.rs`、`modules.rs`、`app.rs`；现有 game-distribution query 与调用透传；对应路由/权限测试 | +| 生成物和文档 | 仓库脚本生成的绑定、现有 schema/DDD/契约守卫所需登记、后端表目录、主规范中的实现证据及本里程碑验收记录 | + +本阶段不修改主站页面、导航、共享 UI、前端服务调用层、nginx/Pingora 路由、AGC 客户端、后台管理、external v1 或正式游戏运行态。这些页面接入工作属于下一里程碑。既有游戏广场与“我的游戏”继续最多读取 48 项；只增加作者查询能力，不增加游戏分页，不重构两张既有列表。 + +## 实现顺序与检查点 + +### 检查点一：冻结契约与纯规则 + +1. 对照主规范的八项接口合同和工程设计 DTO，增加 Rust/TS 同名模型与导出；保留现有响应信封和错误映射。 +2. 在关系领域子模块明确关注、取消关注、移除粉丝三种命令的方向及自关注拒绝规则。用用户 ID 字节长度前缀生成有向用户对键，覆盖中文、多字节和易拼接碰撞 ID。 +3. 校验列表 limit、游标结构、长度边界和排序键，具体长度常量按项目既有输入上限约定固定并写入定向测试；游标绑定主人和列表类型，不承担授权。 +4. 增加共享契约序列化测试：字段名、null、时间格式与响应信封内的数据形状；记录本阶段实际测试名称，避免过滤条件零匹配。 + +退出判据：DTO 与产品合同一致，方向/唯一键/参数规则测试通过；接口中没有可由普通调用者指定的操作者身份。 + +### 检查点二：表、事务和绑定 + +1. 新增私有 `user_follow` 表及双方向索引，字段按工程设计；不修改账号/游戏主键，不新增账号状态或计数表。 +2. 新增事务写路径，先校验受信 API 服务身份，再检查认证操作者和目标账号存在性。关注只建立出边；取消只删除出边；移除粉丝只删除入边。重复相同写操作不重复插行、扣数或改既有时间。 +3. 新增主页、关系和双向列表读取：每次请求内部一次事务读出所需事实，账号不存在时按合同返回/过滤。只有访问者等于列表主人时生成逐行关系；游客、他人关注列表与他人粉丝列表仅读取列表本身和公开资料。 +4. 关系列表先过滤不存在的对端，再统计和分页；按既定时间/主键顺序读取 limit+1。头像昵称直接投影当前账号资料，不保存副本。 +5. game-distribution 查询追加可选作者 ID，按作者与现役公开可见性过滤后排序、截取最多 48 项；不传作者保持当前返回语义，`nextCursor` 仍为 null。 +6. 同步 `migration.rs`、后端数据契约的表目录及必要守卫登记，运行仓库绑定生成和 schema 检查。确认认证全量快照更新不包含或清空新关系表。 + +退出判据：模块可编译、生成物一致、schema 门禁通过；无破坏性 schema 变更。事务的真实执行在检查点四验证，host 测试不能替代。 + +### 检查点三：facade 与 HTTP 接入 + +1. 在 `spacetime-client` 增加 typed 输入、结果、mapper 和调用方法，复用现有连接及服务身份，不建立第二条数据访问链。 +2. 注册 creator 路由，复用现有认证校验、状态码与响应信封；操作者取认证上下文。公开主页无访问者字段，关系 GET 和三个写入口需要登录。 +3. 列表有效认证只用于判断主人身份；认证无效返回 401，无凭据按游客读取。带认证列表与关系接口设置 `private, no-store`。不允许客户端参数强制他人列表返回逐行关系。 +4. 透传游戏查询的可选 `authorId`，显式空值返回 400。回归旧查询，确认没有新增游戏分页或更改原有过滤行为。 +5. 添加路由与 facade 测试：401/403/404/400、幂等回执、输入伪造、公开字段白名单、缓存响应头，以及他人两类列表不触发额外访问者关系投影。 + +退出判据：API 与 DTO 一致，授权和列表只读分支测试通过；本阶段仍不开始前端接线。 + +### 检查点四：隔离运行时验证与证据 + +1. 核实实际开发栈状态和隔离数据库目标，按现有运维脚本构建/发布 module 并启动 API；不使用生产库，不使用删库或 `spacetime --root-dir`。 +2. 以 A/B/C 三个测试账号执行关注、取消、重新关注、互关与移除粉丝；验证 A 移除 B 粉丝后 `A → B` 保留、`B → A` 消失，并从数据库与 API 回读计数。 +3. 验证游客、失效凭据、自操作拒绝、第三方越权及普通身份直接调用 procedure 被拒。测试身份凭据不打印到日志、不写入提交。 +4. 用超过 50 条且含同时间关系的夹具验证分页，覆盖主人/类型不匹配游标、空列表和已不存在对端。验证认证快照刷新后关系仍保留。 +5. 作者游戏夹具混合多个作者、超过 48 个目标作者游戏及非公开/下架/删除作品，确认过滤先于截取且最多 48 项；旧目录查询结果口径保持一致。 +6. 覆盖相同请求重复、相反动作并发和写入结果未知后的回读；最终结果按事务提交顺序解释，不承诺跨请求冻结快照。 + +退出判据：逐条填写下方证据矩阵；环境缺失的项写明原因，不以通过的单测代替未完成运行时证据。完成后停止，待本里程碑验收再制定页面阶段实施计划。 + +## 验证命令 + +以下均为后续工程实现时执行，本次文档任务不构建或发布数据库。`creator` 为新增测试的功能分组，需检查实际匹配数量；相关 game-distribution 模块回归单独运行。 + +```bash +cargo test --locked --manifest-path server-rs/Cargo.toml -p module-auth creator +cargo test --locked --manifest-path server-rs/Cargo.toml -p shared-contracts creator +cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-client 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 +cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-module game_distribution +cargo check --locked --manifest-path server-rs/Cargo.toml -p spacetime-module +npm run spacetime:generate +npm run check:generated-bindings +npm run check:server-rs-ddd +npm run check:game-distribution-dto-parity +npm run typecheck +npm run dev:api-server +``` + +绑定生成需在依赖新绑定的 facade 编译前执行，schema/DDD 门禁在生成后执行；以上清单不是要求按行机械运行。`dev:api-server` 是持续服务命令，启动后根据 `.app/dev-stack.json` 中的实际地址检查 `/healthz` 并执行接口 smoke，不把默认端口当作运行时真相。Rust 格式检查使用当前仓库约定；新增 TS 契约测试按实际文件定向执行，不为占位断言创建无效测试。 + +文档和代码交付均运行： + +```bash +npm run check:encoding +npm run check:doc-index +git diff --check +``` + +## 风险与回滚点 + +- Schema 发布前：可以回退本里程碑代码和生成物；不覆盖他人改动，不修改已有表字段顺序/类型。若出现破坏性迁移需求，先更新主规范和迁移计划，再确认实施。 +- Schema 发布后：保留关系表和已写数据，业务回退使用保留新表兼容 schema 的版本；不通过删除数据库或关系表恢复旧版本。后端和对应 bindings 同步，先确认兼容再重启服务。 +- 认证投影：关系表独立于账号快照，回归同步账号资料不会删除关系；缺失账号过滤与计数同口径。 +- 范围控制：读时精确计数先复用索引；发现规模风险只记录证据，不自行增加缓存、后台任务或账号状态。游戏目录现有 48 项限制保持不变。 +- 交付边界：本计划只授权范围内的开发验证，不等同于生产部署；本次只补文档并本地提交，不推送远程。 + +## 验收证据矩阵 + +| 对照项 | 验证方式 | 当前结果 | +| --- | --- | --- | +| 唯一键、方向、自关注与幂等 | 领域测试 + API/数据库回读 | 未实施 | +| 认证与第三方越权 | HTTP 负向用例 + 普通身份调用 procedure | 未实施 | +| 他人两类列表只读、无访问者关系查询 | 路由/投影定向测试 + API 响应 | 未实施 | +| 公开字段、计数、分页、账号存在性 | 契约测试 + 多页隔离夹具 | 未实施 | +| 作者游戏过滤与原有 48 项边界 | game-distribution 回归 + API 夹具 | 未实施 | +| Schema、迁移、绑定及认证快照兼容 | 生成检查、DDD 门禁 + 实际运行时回读 | 未实施 | +| 重复/并发写与结果未知 | 事务集成用例与写后查询 | 未实施 | + +实际实现时补充命令结果、证据位置和未验证原因。本里程碑与页面阶段全部验收后，将持久结论融合回主规范并删除已完成临时计划。 diff --git a/docs/project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md b/docs/project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md index 5dfeaaebb..14d911c9f 100644 --- a/docs/project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md +++ b/docs/project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md @@ -16,7 +16,7 @@ ## 前置条件 - 主规范的产品规则已确认；账号公开性按现有账号存在性判断，不新增账号状态体系。 -- 开始实现前另建仅覆盖本里程碑的实施计划，明确 schema、DTO、事务、API、测试及回滚边界。 +- 对应[实施计划](./【实施计划】创作者关系与公开查询-2026-10-05.md)已补齐，覆盖 schema、DTO、事务、API、测试及回滚边界；开工时按计划核验当前代码和隔离开发环境。 ## 验收标准 diff --git a/docs/technical/【技术方案】创作者主页与关注粉丝工程设计-2026-10-05.md b/docs/technical/【技术方案】创作者主页与关注粉丝工程设计-2026-10-05.md index f47662d77..380676d60 100644 --- a/docs/technical/【技术方案】创作者主页与关注粉丝工程设计-2026-10-05.md +++ b/docs/technical/【技术方案】创作者主页与关注粉丝工程设计-2026-10-05.md @@ -113,7 +113,7 @@ type CreatorRelationshipResponse = { 新关系表从空数据开始；同步迁移登记、后端表目录和 Rust 生成绑定。新增 procedure 与 facade 同步发布，不手改生成文件；游戏查询新增的 authorId 是可选能力，旧 HTTP 请求继续有效。后端部署先于新前端，回滚前端不删除关系数据；回滚后端必须保留新表的兼容 schema，禁止删库回退。 -实施顺序和验收边界分别见[关系与公开查询里程碑](../project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md)、[主页与关系交互里程碑](../project-memory/plans/【里程碑】创作者主页与关系交互-2026-10-05.md)。每阶段评审后再创建单里程碑实施计划；前阶段验收通过才进入下一阶段。 +实施顺序和验收边界分别见[关系与公开查询里程碑](../project-memory/plans/【里程碑】创作者关系与公开查询-2026-10-05.md)、[主页与关系交互里程碑](../project-memory/plans/【里程碑】创作者主页与关系交互-2026-10-05.md)。首阶段[实施计划](../project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md)已就绪；前阶段验收通过后再制定下一阶段的单里程碑实施计划并进入实现。 实施时按范围执行以下命令；本次文档提交只执行最后三项： diff --git a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md index b706c16ef..2814e0e7d 100644 --- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md +++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md @@ -556,7 +556,7 @@ | 字段 | 值 | | --- | --- | | Version | 1.0 | -| Status | ready（产品规则已确认，未实现；开工前补单里程碑实施计划） | +| Status | ready（产品规则与首阶段实施计划已就绪，未实现） | | Date | 2026-10-05 | | 范围 | 主站导航、公开创作者主页、游戏详情作者入口、关注关系与列表管理 | @@ -657,7 +657,7 @@ - 已确认：第四项默认进入自己主页；他人关注和粉丝列表公开可查看；自己或他人的关注/粉丝列表均可点击任意用户进入其创作者主页；他人的关注、粉丝列表统一只读，无关系操作且不检测访问者与列表用户的关系；本次不额外改造游戏目录分页，保持既有广场和“我的游戏”行为。 - 已确认：移动端采用“游戏 / 创作者主页 / 我的”；自己的主页也只列公开游戏；自己的关注列表取消后当前行暂留以便重新关注；移除粉丝二次确认，取消关注不弹确认。 -- 产品待定项已收口，接口命名、路由和关系列表分页按本文及工程设计落地。开工前补关系与公开查询里程碑的实施计划；前阶段验收后再进入页面阶段。本次只修改文档，不提前编写业务代码。 +- 产品待定项已收口，接口命名、路由和关系列表分页按本文及工程设计落地。[关系与公开查询实施计划](./project-memory/plans/【实施计划】创作者关系与公开查询-2026-10-05.md)已补齐；前阶段验收后再制定页面阶段实施计划。本次只修改文档，不提前编写业务代码。 - 源码核验：现有公开用户查询按账号存在性返回资料，`user_account` 没有独立封禁/公开状态字段。首版复用该存在性口径，关系计数和列表一致排除不存在的账号，不在本功能内增加账号状态体系。 - 本次证据只覆盖源码调研和规划文档检查；业务、数据库迁移与浏览器验收均未执行。