kdletters
1a7abfd059
Project CI / AI game creator shell Rust shard 4/4 (push) Has been cancelled
Project CI / AI game creator shell Rust smoke (push) Has been cancelled
Project CI / AI game creator shell Rust crates (push) Has been cancelled
Project CI / Backend tests (push) Has been cancelled
Project CI / Native shell tests (push) Has been cancelled
Project CI / Frontend tests (push) Has been cancelled
Project CI / Repository checks (push) Has been cancelled
Project CI / AI game creator shell web tests (push) Has been cancelled
Project CI / AI game creator shell Rust shard 1/4 (push) Has been cancelled
Project CI / AI game creator shell Rust shard 2/4 (push) Has been cancelled
Project CI / AI game creator shell Rust shard 3/4 (push) Has been cancelled
## 交付内容
- 客户端新增 `project_snapshot` 模块：项目扫描与排除口径、增量索引、差异对比、上传编排、状态查询。
- 触发：工作区窗口存活期间的周期定时器 + 工作区窗口关闭（`CloseRequested`）；应用退出只在有界预算内等待在途同步收尾，不重复发起。
- 服务端新增两条登录态路由 `POST /api/agc/project-snapshots/files` 与 `/manifest`，由 api-server 用服务端凭据写入私有前缀 `agc/project-snapshots/v1/{user}/{project}/`；客户端不持有 OSS 凭据、不直连 OSS。
- `platform-oss` 新增内部对象精确写入与探测、项目快照对象键构造；修复 `head_internal_object` 读 HEAD 响应长度恒为 0（会导致服务端"已存在即跳过"永不生效）。
- `shared-contracts` 新增 `agc_project_snapshots` DTO 与项目 ID、相对路径、摘要校验。
- 真实 OSS 存储层冒烟示例 + 客户端真实链路冒烟用例（`#[ignore]`，env 驱动）。
- 登记 `check-config.mjs` 的 native-only 命令白名单，恢复 `npm run agc` 可启动。
## 验证证据
- 存储层：`cargo run -p platform-oss --example agc_project_snapshot_live_smoke` 对真实 `agc-dev` 完成写入 → 读回（contentLength 32）→ 清单写入 → 探针清理。
- HTTP 层：登录态下 7 项校验（401 无 token、400 路径穿越/长度不一致/非法摘要/空正文/重复路径清单）全部符合预期且不写对象。
- 客户端链路（真实项目 gameagent-033b6cf3…）：第一次 `synced uploaded=6 uploadedBytes=36694 remoteSkipped=6`，紧接着第二次 `no-op uploaded=0`。
- GUI 触发：`trigger=periodic ... uploaded=6`；把周期设为 600 秒排除干扰、改一个文件后关窗得到 `trigger=project-close ... revision=2 uploaded=1`，索引摘要由 `28d837cd84f8ab62` 推进到 `bff34e2e336d901f`（同步在进程退出前完成）。
- 门禁：AGC `project_snapshot` 14 passed（+1 ignored live）、api-server `project_snapshots` 3 passed、platform-oss 39 passed、shared-contracts 87 passed、`cargo fmt --check`（两处）、`check:encoding`、`check:doc-index`、`git diff --check`、`check-config.mjs` 全部通过。
## 已知未决（不阻塞本里程碑）
- 远端对象只增不减：没有删除路径，也没有 bucket 生命周期规则；要收口需要先定保留语义（清单引用 GC 还是 OSS 生命周期）。
- 部署环境需确认 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_*` 或回退的 `ALIYUN_OSS_*` 具备目标 bucket 私有前缀的 `PutObject` 权限；未配置时接口返回 503、客户端失败关闭（不推进索引）。
- 缺少按用户/项目的配额与限流（error_reports 有每小时提交上限的先例，本功能没有）。
- 没有界面入口与状态可见性：`read_local_project_snapshot_state` 已注册但未接 UI，失败只写本机日志。
## 不做
- 不做云端下载/恢复、跨设备合并、版本回滚。
- 不改 `/api/external/v1` 与 External OpenAPI，不新增 SpacetimeDB 表。
---------
Co-authored-by: kdletters <61648117+kdletters@users.noreply.github.com>
Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/400
server-rs 工作区说明
更新时间：2026-05-15
server-rs/ 是当前唯一后端工作区，承载 Rust api-server、SpacetimeDB module、领域模块、平台副作用适配和共享契约。旧 server-node、Express、PostgreSQL、Go 服务端和 maincloud 口径均为历史残留，不再作为当前实现目标。
当前职责
crates/api-server：Axum HTTP / SSE / BFF 门面、鉴权、中间件、外部服务编排和 DTO 映射。crates/spacetime-module：SpacetimeDB 表、reducer、procedure、事务 adapter、row mapper 和迁移。crates/spacetime-client：后端访问 SpacetimeDB 的 typed facade。crates/module-*：领域模型、命令、应用规则、领域事件和领域错误。crates/platform-*：OSS、LLM、语音、认证等外部平台能力。crates/shared-contracts：前后端共享 DTO 与公开契约。crates/shared-kernel、crates/shared-logging、crates/tests-support：跨模块基础能力、日志和测试支撑。
开发规则
server-rs/Cargo.toml是 workspace 成员和依赖版本事实源；第三方依赖和 workspace 内 crate path 优先放在[workspace.dependencies]。module-*不直接依赖 Axum、SpacetimeDB table/reducer/procedure、reqwest、OSS、LLM、spacetime-client、tokio或文件系统。api-server不承接领域真相；发现领域规则时优先沉到对应module-*。- SpacetimeDB schema 变化必须同步
spacetime-module/src/migration.rs、生成绑定和当前后端架构文档的表目录。 - 人工命令、本地联调和文档示例不要使用
spacetime --root-dir。
常用命令
cargo check -p api-server --manifest-path server-rs/Cargo.toml
cargo test -p api-server --manifest-path server-rs/Cargo.toml
npm run check:server-rs-ddd
npm run check:spacetime-schema
npm run spacetime:generate
npm run dev:api-server
涉及 API smoke 时用 npm run dev:api-server 启动后端并检查 /healthz，不要使用旧 api-server:maincloud。
当前文档
- ../docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md：DDD 边界、API 分组、schema 变更规则和表目录。
- ../docs/【开发运维】本地开发验证与生产运维-2026-05-15.md：本地启动、检查、SpacetimeDB 操作和生产运维。