209 lines
5.1 KiB
Markdown
209 lines
5.1 KiB
Markdown
# 开发工作流
|
||
|
||
> 用途：给本地 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
|
||
- 移动端视口检查
|
||
|
||
前端原则：
|
||
|
||
- 移动端优先，再兼容网页端。
|
||
- 页面只展示后端返回的状态，不自行计算结论型业务状态。
|
||
- 创作中心入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；前端只在 `platformEntryCreationTypes.ts` 做展示派生，api-server 路由熔断也使用同一份配置，禁止恢复前端硬编码入口配置文件。
|
||
- 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
|
||
- 不在 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. 建议的测试命令和提交信息。
|
||
```
|