# 开发工作流

> 用途：给本地 Hermes 和开发人员提供统一的开发、测试、提交流程。具体命令以 `package.json`、`server-rs/Cargo.toml`、`AGENTS.md` 和相关 `docs/` 最新文档为准。

## 标准任务流程

```text
同步代码 → 读取 AGENTS.md → 读取 .hermes/shared-memory → 查找/完善 docs → 制定计划 → 小步实现 → 本地验证 → 更新文档/记忆 → 提交
```

## 建议启动方式

在项目根目录启动 Hermes：

```bash
cd /path/to/Genarrative
hermes
```

在本机当前常见路径为：

```bash
/home/dsk/workspace/Genarrative
```

其他开发者以自己本地实际路径为准，不要把个人绝对路径写入共享文档作为通用规则。

## 开发前检查清单

- [ ] 当前分支是否正确
- [ ] 是否已拉取最新代码
- [ ] 是否阅读 `AGENTS.md`
- [ ] 是否阅读 `.hermes/shared-memory/` 相关文件
- [ ] 是否阅读 `README.md` 中的运行和检查命令
- [ ] 是否阅读 `docs/README.md` 及任务相关分类 README
- [ ] 是否存在足够具体的 PRD / 设计 / 技术文档
- [ ] 是否明确测试、验收和文档更新方式

## 本地运行命令

安装依赖：

```bash
npm install
```

完整联调开发环境：

```bash
npm run dev
```

该命令会启动：

- SpacetimeDB standalone
- Rust `api-server`
- 主站 Vite
- 后台 Vite

单独启动前端：

```bash
npm run dev:web
```

单独启动 Rust API server：

```bash
npm run api-server
```

查看本地 Rust/SpacetimeDB 日志：

```bash
npm run dev:rust:logs
```

后台管理前端：

```bash
npm run admin-web:dev
npm run admin-web:build
npm run admin-web:typecheck
```

SpacetimeDB bindings 生成：

```bash
npm run spacetime:generate
```

## 常用检查命令

- 后端通用用户行为埋点统一通过 `record_tracking_event_and_return` procedure、`SpacetimeRuntimeClient::record_tracking_event(...)` 与 api-server `tracking` 中间件写入 `tracking_event` / `tracking_daily_stat`；后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 默认排除；作品级游玩埋点统一使用 `work_play_start`，详细事件清单见 `docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md`。

编码检查：

```bash
npm run check:encoding
```

ESLint：

```bash
npm run lint:eslint
```

类型检查：

```bash
npm run typecheck
```

综合 lint：

```bash
npm run lint
```

测试：

```bash
npm run test
```

生产构建：

```bash
npm run build
```

内容检查：

```bash
npm run check:data
npm run check:overrides
npm run check:smoke
npm run check:content
```

全量检查：

```bash
npm run check
```

DDD 边界检查：

```bash
npm run check:server-rs-ddd
```

## 后端相关默认验证

后端修改后，按 DDD 文档中的验收命令执行。涉及 API smoke 时：

- 使用 `npm run api-server` 重新拉起后端。
- 禁止使用 `npm run api-server:maincloud`、`npm.cmd run api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径；这些只属于历史残留。
- 检查 `/healthz`。
- 执行对应自动测试。
- 涉及 SpacetimeDB 表、reducer、procedure、row shape 或绑定变化时，同步更新 `migration.rs`、表目录和生成绑定。

关键文档：

- `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
- `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
- `docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
- `docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
- `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
- `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
- `docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`

## 前端相关默认验证

前端修改后，应根据修改范围选择：

- `npm run check:encoding`
- `npm run lint:eslint`
- `npm run typecheck`
- `npm run test`
- 页面交互 smoke
- 移动端视口检查

前端原则：

- 移动端优先，再兼容网页端。
- 页面只展示后端返回的状态，不自行计算结论型业务状态。
- 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
- 不在 UI 中默认写功能说明类文本。
- 弹出独立面板的交互不要实现成在当前面板下方追加内容。

## 文档更新规则

- 工程修改要同步更新对应文档。
- 如果没有现成文档，新文档统一放入 `docs/` 下合适分类。
- `.hermes/shared-memory/` 只记录高频、长期、团队共享的摘要和索引，不替代完整 PRD/技术文档。
- 如果 `.hermes/shared-memory/` 与代码或 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正共享记忆。

## 提交前建议让 Hermes 执行

```text
请检查当前 git diff，指出：
1. 是否违反 AGENTS.md 或 .hermes/shared-memory 约定；
2. 是否需要补充 docs；
3. 是否有长期知识需要写入 .hermes/shared-memory；
4. 建议的测试命令和提交信息。
```