Merge remote-tracking branch 'origin/server_node'

2026-04-08 19:16:55 +08:00
parent a02f7b6414 a83841ff2d
commit 323aa94c87
69 changed files with 8262 additions and 81 deletions
--- a/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md
+++ b/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md
@@ -0,0 +1,194 @@
+# Node 后端知识图谱
+
+日期：`2026-04-08`
+
+## 1. 当前定位
+
+当前运行时后端以 `server-node/` 为唯一有效服务端实现。
+
+当前职责：
+
+- 承接运行时鉴权
+- 承接运行时持久化
+- 承接运行时 AI 接口
+- 为 Vite 前端提供开发期代理目标
+
+当前不再使用：
+
+- Vite 本地 API 插件 `scripts/dev-server/`
+
+## 2. 技术栈
+
+- HTTP 框架：`Express`
+- 语言与构建：`TypeScript` + `tsx` + `esbuild`
+- 数据库：`better-sqlite3`
+- JWT：`jose`
+- 密码哈希：`@node-rs/argon2`
+- 日志：`pino` + `pino-http` + `pino-roll`
+
+## 3. 运行入口
+
+推荐命令：
+
+```bash
+npm run dev:node
+```
+
+相关脚本：
+
+- 根目录联调：`npm run dev:node`
+- 单独启动后端开发模式：`npm run server-node:dev`
+- 构建后端：`npm run server-node:build`
+- 运行后端测试：`npm run server-node:test`
+
+默认监听：
+
+- 前端：`3000`
+- Node 后端：`8081`
+
+## 4. 目录与主入口
+
+服务端主入口：
+
+- `server-node/src/server.ts`
+- `server-node/src/app.ts`
+
+路由入口：
+
+- `server-node/src/routes/authRoutes.ts`
+- `server-node/src/routes/runtimeRoutes.ts`
+
+基础设施：
+
+- `server-node/src/config.ts`
+- `server-node/src/logging.ts`
+- `server-node/src/db.ts`
+- `server-node/src/context.ts`
+
+数据访问：
+
+- `server-node/src/repositories/userRepository.ts`
+- `server-node/src/repositories/runtimeRepository.ts`
+
+鉴权相关：
+
+- `server-node/src/auth/authService.ts`
+- `server-node/src/auth/token.ts`
+- `server-node/src/auth/password.ts`
+- `server-node/src/middleware/auth.ts`
+
+## 5. 鉴权模型
+
+当前采用：
+
+- 前端本地保存 `JWT + 自动生成的用户名密码`
+- 请求头使用 `Authorization: Bearer <token>`
+- 后端 middleware 统一解析出 `UserID`
+- handler 不直接解析 token
+
+当前账号策略：
+
+- 默认自动匿名账号启动
+- 本地无 JWT 时，前端会自动生成随机用户名密码并调用 `POST /api/auth/entry`
+- 本地 JWT 失效但仍保留随机凭据时，前端自动重新调用 `auth/entry` 恢复同一账号
+
+JWT 现状：
+
+- 当前为永久签发
+- claim 仍保留：`sub`、`iat`、`iss`、`ver`
+- `logout` 通过递增 `token_version` 立即失效旧 token
+
+## 6. 数据存储
+
+当前数据库：
+
+- 默认 SQLite 文件：`server-node/data/genarrative.sqlite`
+- 可通过 `SQLITE_PATH` 覆盖
+
+当前核心表：
+
+- `users`
+- `save_snapshots`
+- `runtime_settings`
+- `custom_world_profiles`
+
+当前隔离原则：
+
+- 所有运行时数据按用户隔离
+
+## 7. 已承接接口
+
+鉴权：
+
+- `POST /api/auth/entry`
+- `GET /api/auth/me`
+- `POST /api/auth/logout`
+
+运行时持久化：
+
+- `GET /api/runtime/save/snapshot`
+- `PUT /api/runtime/save/snapshot`
+- `DELETE /api/runtime/save/snapshot`
+- `GET /api/runtime/settings`
+- `PUT /api/runtime/settings`
+- `GET /api/runtime/custom-world-library`
+- `PUT /api/runtime/custom-world-library/:profileId`
+- `DELETE /api/runtime/custom-world-library/:profileId`
+
+运行时 AI：
+
+- `POST /api/llm/chat/completions`
+- `POST /api/custom-world/scene-image`
+- `POST /api/runtime/story/initial`
+- `POST /api/runtime/story/continue`
+- `POST /api/runtime/custom-world/sessions`
+- `GET /api/runtime/custom-world/sessions/:sessionId`
+- `POST /api/runtime/custom-world/sessions/:sessionId/answers`
+- `GET /api/runtime/custom-world/sessions/:sessionId/generate/stream`
+- `POST /api/runtime/chat/character/suggestions`
+- `POST /api/runtime/chat/character/summary`
+- `POST /api/runtime/chat/character/reply/stream`
+- `POST /api/runtime/chat/npc/dialogue/stream`
+- `POST /api/runtime/chat/npc/recruit/stream`
+- `POST /api/runtime/items/runtime-intent`
+- `POST /api/runtime/quests/generate`
+
+## 8. Story 与 Custom World 现状
+
+Story：
+
+- Node 后端直接复用前端成熟 prompt 与归一化逻辑
+- 服务端走 `src/services/ai.ts` 中的严格版 story 生成链
+
+Custom World：
+
+- Node 后端直接复用前端现有多阶段生成编排
+- 当前保留 `session + answers + SSE progress/result/error` 协议
+- 前端已支持接收真实阶段进度对象
+
+## 9. 前端接入点
+
+鉴权与请求：
+
+- `src/services/apiClient.ts`
+- `src/services/authService.ts`
+- `src/components/auth/AuthGate.tsx`
+
+运行时服务层：
+
+- `src/services/storageService.ts`
+- `src/services/aiService.ts`
+
+## 10. 当前 Vite 角色
+
+Vite 当前只负责代理，不再提供本地 API 插件。
+
+当前代理目标：
+
+- `/api/auth`
+- `/api/runtime`
+- `/api/llm`
+- `/api/custom-world/scene-image`
+- `/api/ws`
+
+全部转发到 Node 后端。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,6 +4,9 @@

 ## 文档列表

+- [NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md](./NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md)：当前 Node 运行时后端的技术栈、入口、鉴权、存储与接口知识图谱。
+- [GO_SERVER_RUNTIME_INTEGRATION_2026-04-07.md](./GO_SERVER_RUNTIME_INTEGRATION_2026-04-07.md)：Go 服务端接入、运行时持久化迁移与当前进展记录。
+- [GO_SERVER_TASKLIST_2026-04-08.md](./GO_SERVER_TASKLIST_2026-04-08.md)：Go 服务端已完成与未完成事项的执行清单。
 - [AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md](./AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md)：AI 生成角色形象与角色动画的技术路线。
 - [ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md](./ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md)：面向编辑器的阿里云 NPC 形象与动作实验方案，按 4 条生成链路对比。
 - [PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md](./PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md)：PixelMotion 产品形态与能力拆解。