js/gojsTODO.md

# Go/JS 底层低代码引擎架构与开发计划

**目标受众**: 负责实现该项目的 AI 开发助手。
**项目背景**: 这是一个用于 Go 应用的低代码框架，其核心目标是提供一个 **极低摩擦、无状态、对 AI 极度友好** 的 Go/JS 桥接层。允许业务系统在不重启、不重新编译的情况下，通过动态执行 JS 代码来扩展能力。
**核心原则**: 性能优先、快速失败 (Fail-Fast)、严格的测试覆盖、彻底解耦底层依赖。

---

## 1. 架构总览

项目分为两个完全解耦的模块：

### 1.1 `go/js/gojs` (注册与标准层)
- **定位**: 轻量级注册中心，**零第三方依赖**。其他 Go 业务模块（如 `go/db`, `go/http`）仅引入此包进行能力暴露，避免污染 `goja` 依赖。
- **核心 API**:
  - `func Register(name string, exports map[string]any)`: 注册全局模块。`exports` 的 value 可以是函数、基本类型或复杂的 Go Struct/Pointer。
  - `func GetModules() map[string]map[string]any`: 获取所有已注册的模块，供引擎层调用。

### 1.2 `go/js` (执行与引擎层)
- **定位**: 核心执行环境，依赖 `github.com/dop251/goja`、`go/cast` 和 `go/js/gojs`。
- **核心职责**: 维护虚拟机对象池 (Pool)、实现 Go-JS 双向数据桥接 (Bridge)、处理无状态调用 (Call)、以及生成 AI 友好的文档 (TS Definition)。

---

## 2. 核心技术规范与难点攻克

### 2.1 模块引入机制 (Import/Require)
- **规范**: JS 侧应该能通过类似 `const db = require('db')` 或 `import db from 'db'` 的方式加载 `gojs.Register` 注册的模块。
- **实现方案**: 优先考虑利用 `goja/require` 扩展，或者在 VM 初始化时，将所有注册的模块作为全局只读对象注入（例如全局暴露 `go.db`, `go.http`，或者直接劫持 require）。**测试阶段需敲定一种对 AI 最直观的引入方式**。

### 2.2 双向桥接与数据保真 (The Bridge)
这是项目的绝对核心，必须用海量的测试用例覆盖。
- **JS 调用 Go (入参)**:
  - 拦截 JS 传入的参数，如果 Go 函数的第一个参数是 `context.Context`，则自动将 `js.Call` 传入的 context 注入。
  - 对于普通的 JS 对象，使用 `goja.Value.Export()` 转为 Go 的原生 `any`，再通过 `go/cast.Convert` 精确投射到 Go 函数要求的 `Struct/Slice/Map` 类型上。
  - **快速失败**: 如果 `cast` 失败或参数个数不匹配，立刻 `panic`，并在桥接层 `recover` 抛出 JS 异常。
- **Go 返回 JS (出参 & Host Object)**:
  - **难点**: Go 返回的复杂对象（特别是带有指针、方法的 Struct）在 JS 中必须保持原样（Host Object）。
  - **验证要求**: 当 JS 收到这个 Go 包装对象后，如果仅仅是做一些传递，再次调用另一个 Go 函数并把该对象传回去，Go 侧接收到时，**必须能够精准还原为原来的指针/类型**，不能发生失真（不能变成普通的 map）。
  - **参考**: 利用 `goja` 的 `Runtime.ToValue(ptr)` 机制，默认情况下 `goja` 会保留底层 Go 类型。需编写严格测试。

### 2.3 无状态与全局池 (Versioned Pool)
- 虚拟机是非线程安全的，必须池化。
- **`js.Define(code string)`**: 定义或覆盖全局业务函数。每次调用时，内部版本号 `version++`，并将新代码追加到全局 Registry。
- **`js.Call(ctx context.Context, funcName string, args ...any) (any, error)`**:
  - 从 Pool 获取一个 `goja.Runtime`。
  - 检查 `vm.version` 是否落后于全局 `version`，若落后，则增量 `RunString` 未同步的代码块，并更新 `vm.version`。
  - 将 Go 的 `args` 转换为 JS arguments。
  - 获取并执行对应的 `funcName`。
  - 执行完毕后，清空 VM 中的临时状态（如果需要），归还 Pool。**确保不同 Call 之间绝对无状态隔离**。

### 2.4 智能文档生成 (TypeScript D.TS)
- **定位**: 为大语言模型 (AI) 生成准确的上下文。
- **`js.Doc() string`**:
  - 遍历 `gojs.GetModules()` 和动态 `Define` 的函数。
  - 利用 Go 的 `reflect` 包解析函数的入参、返回值类型。
  - 输出标准的 TypeScript 声明文件格式 (`.d.ts`)。不需要 100% 完美的泛型支持，但结构体字段、参数名、基础类型必须准确。

---

## 3. 开发执行步骤 (Steps for AI)

### Phase 1: 基础设施建设 (Registry)
- [ ] 初始化 `go/js/gojs` 目录和 `go.mod` (如果需要独立 mod)。
- [ ] 实现 `gojs.Register(name, map[string]any)` 及其内部存储。
- [ ] 编写对应的基础单元测试。

### Phase 2: 核心桥接器与数据保真 (Bridge & Test)
- [ ] 初始化 `go/js` 目录及依赖 (`go get github.com/dop251/goja`)。
- [ ] 实现 `wrapGoFunc`，处理 `context` 自动注入，利用 `cast` 进行参数的强类型转换。
- [ ] **必须编写极其严苛的测试用例 (`bridge_test.go`)**:
  - 测试基础类型双向转换。
  - 测试复杂的 Go Struct (带指针、嵌套) 传入 JS 的读取。
  - **关键测试**: `Go返回对象 -> JS变量 -> 将该变量传给另一个Go函数`，断言 Go 侧拿到的指针地址与原始地址一致。
  - 测试参数不足、类型错乱时的 Panic/Error 捕获机制（验证 AI 容错能力）。

### Phase 3: 对象池与生命周期管理 (Pool)
- [ ] 实现 `js.Define(code)`，管理全局代码片段和版本号。
- [ ] 实现 `js.Call(ctx, name, args...)`。
- [ ] 实现 VM 的获取、版本比对同步、增量编译、执行及回收逻辑。
- [ ] 编写高并发下的 `Call` 测试，确保对象池无锁竞争问题和状态隔离正常。

### Phase 4: AI 智能文档导出 (Doc)
- [ ] 实现反射解析 Go Struct 和 Func 的逻辑。
- [ ] 实现 TypeScript `.d.ts` 字符串的生成。
- [ ] 编写测试，断言生成的 TS 定义字符串符合预期。

---

## 4. 关键提示 (Hints)
- 遇到类型转换阻碍时，优先相信 `go/cast` 的能力，而不是在 bridge 里写大量的反射 if-else。
- 保证 `goja.Value.Export()` 的正确使用。
- 不要尝试在 `go/js` 内实现 HTTP 或服务发现，保持纯粹的计算和桥接引擎定位。