46 lines
1.9 KiB
Markdown
46 lines
1.9 KiB
Markdown
# WOV API
|
|
|
|
本仓库是 WOV 平台后端，负责节点注册、工作流编排、任务调度和用户 API。
|
|
|
|
## 职责
|
|
|
|
- 维护 SQLite 节点注册表和节点实例状态。
|
|
- 通过 `NodeManager` 启动、复用和回收独立节点进程。
|
|
- 提供管理端 API：注册节点、查看实例、停止实例。
|
|
- 后续增加工作流 DAG、WorkflowRun、用户上传和产物下载。
|
|
|
|
## 运行
|
|
|
|
```powershell
|
|
uv sync
|
|
uv run uvicorn app.main:app --reload
|
|
```
|
|
|
|
`uv sync` 默认会安装 `[dependency-groups] dev`，包括 pytest、pytest-cov 和 httpx。
|
|
|
|
如果 8000 端口被占用或 Windows 提示 `WinError 10013`，先检查监听端口，然后改用其他端口：
|
|
|
|
```powershell
|
|
Get-NetTCPConnection -LocalPort 8000 -State Listen
|
|
uv run uvicorn app.main:app --reload --port 8001
|
|
```
|
|
|
|
## 不变量
|
|
|
|
- 节点生命周期只能由 `NodeManager` 管理，API 不直接启动或杀死节点。
|
|
- 节点进程不共享 API 内存，中间产物通过 URI 落盘。
|
|
- 后续切换 PostgreSQL、对象存储和分布式队列时，不能破坏这些边界。
|
|
|
|
## 环境
|
|
|
|
- Python 环境统一使用 uv 管理，不直接使用 pip 修改依赖。
|
|
- 测试必须达到 100% 行覆盖率，且只能通过调用真实代码路径覆盖。
|
|
- 行覆盖率不包含外部端口占用/权限问题；真实网络启动由 uvicorn 冒烟测试单独覆盖。
|
|
|
|
## 代码注释规范
|
|
|
|
- 本仓库所有源码（Python、TOML 等支持注释的文件）必须配有详细中文注释，说明模块职责、类与函数的作用以及关键逻辑，确保后续维护人员可以快速理解代码工作原理。
|
|
- 新增或修改代码时，必须同步补充或更新对应注释；不得删除已有注释。
|
|
- 测试代码同样必须配有中文注释，说明每条测试验证的行为。
|
|
- JSON 数据文件不支持注释，字段语义以 `wov-sdk` 的 `NodeManifest` 模型注释为准；修改 JSON 字段时须同步更新文档。
|