OctoHz 我的项目 API

接口一览

Method	Route	说明
GET	`/api/my/projects`	列表（摘要）
POST	`/api/my/projects`	新建
GET	`/api/my/projects/:id`	获取完整数据
PATCH	`/api/my/projects/:id`	部分更新
DELETE	`/api/my/projects/:id`	删除

重要： project ID 只能放 URL，不能放 body。

顶层结构

{
  "id": 1,
  "name": "项目名称",
  "definition": {},
  "decisions": [],
  "pitfalls": [],
  "status": {},
  "ops": {},
  "design": {},
  "dataModels": []
}

POST 支持字段： name、definition、decisions、pitfalls、status、ops

PATCH 额外支持： design、data_models（POST 不接受这两个字段）

definition

{
  "oneliner": "一句话描述",
  "stage": "production",
  "tech_stack": [
    {
      "tech": "Next.js",
      "layer": "frontend",
      "version": "16.2.1",
      "framework": "App Router"
    }
  ],
  "conventions": {
    "styling": "Tailwind v4 utility classes",
    "forbidden": ["禁止事项1", "禁止事项2"]
  },
  "estimated_completion": "2026-06"
}

oneliner：注意不是 one_liner
stage 枚举：development / production / maintenance / running / archived
tech_stack 每项：tech（必填）、layer（必填）、version（选填）、framework（选填）、note（选填）、port（选填）
layer 常用值：frontend / backend / database / deployment / runtime / plugin / service / proxy / control_plane / vpn_client
conventions：key-value 对象，不是字符串数组，key 自定义
estimated_completion：选填，"YYYY-MM" 或 null

decisions

[
  {
    "id": "D001",
    "date": "2026-04",
    "title": "决策标题",
    "impact": "影响的文件或模块",
    "status": "active",
    "context": "做这个决策的背景",
    "decision": "具体做了什么决定",
    "rationale": "（选填）更详细的理由"
  }
]

id 格式：D001、D002 递增
date 格式："YYYY-MM" 或 "YYYY-MM-DD"
status 枚举：active / implemented / superseded
context 和 decision 分开写，不要合并
PATCH 行为：按 id upsert——发送的条目与现有数据按 id 合并，字段值为 null 时该字段被删除，不存在的 id 则新增

pitfalls

[
  {
    "id": "P001",
    "date": "2026-04-24",
    "title": "坑的标题",
    "status": "mitigated",
    "severity": "high",
    "condition": "在什么情况下触发",
    "consequence": "触发后会发生什么",
    "solution": "怎么解决或规避",
    "mitigation": "（选填）已采取的缓解措施",
    "description": "（选填）更详细说明"
  }
]

id 格式：P001、P002 递增
status 枚举：resolved / mitigated / active / identified
severity 枚举：high / medium / low
condition、consequence、solution 是必填核心三件套
PATCH 行为：按 id upsert——同 decisions，按 id 合并，null 值删字段

status

{
  "completed": ["已完成项"],
  "in_progress": ["进行中"],
  "pending": ["待办"],
  "known_issues": ["已知轻量问题"]
}

所有字段都是字符串数组，空时写 []，不能写 null。

ops

{
  "repo": "https://github.com/xxx/yyy",
  "servers": [
    {
      "address": "67.230.160.74 / octohz.com",
      "purpose": "生产环境",
      "services": ["Next.js 16", "PostgreSQL"]
    }
  ],
  "env_vars": [
    {
      "key": "DATABASE_URL",
      "hint": "postgresql://user:<pw>@host:5432/db，密码见服务器 .env"
    }
  ],
  "cron_jobs": [],
  "databases": [
    {
      "name": "mydb",
      "type": "PostgreSQL",
      "address": "172.18.0.3:5432",
      "notes": "容器间通信用内网地址"
    }
  ],
  "local_dev": ["Node.js 20+", "npm install", "npm run dev"],
  "onboarding": {
    "summary": "项目一句话介绍",
    "key_files": ["path/to/file — 说明"],
    "first_steps": ["1. 第一步", "2. 第二步"],
    "forbidden_zones": ["禁止做的事"]
  },
  "deploy_flow": ["Step 1: ...", "Step 2: ..."],
  "third_party": [
    {"name": "Resend", "status": "normal", "purpose": "邮件发送"}
  ],
  "dir_structure": {
    "root": "/opt/project",
    "notes": "补充说明",
    "key_paths": [
      {"path": "src/app", "desc": "Next.js 路由"}
    ]
  }
}

env_vars 每项用 hint 字段（不是 note / value / scope），不写明文密码
onboarding 是对象，不是字符串
servers[].address 多个地址用 / 分隔
不涉及的字段（cron_jobs、databases 等）填 []，不要省略

design（选填，仅 PATCH）

{
  "notes": "整体风格说明",
  "colors": {
    "primary": "#e64831",
    "bg": {"page": "#f4f4f4", "card": "#ffffff"}
  },
  "buttons": [
    {"name": "主操作按钮", "style": "CSS 字符串", "usage": "使用场景"}
  ],
  "card": "卡片的 Tailwind class 字符串"
}

无 UI 的项目留 {}。POST 新建时不支持此字段，需建好后再 PATCH。

dataModels（选填，仅 PATCH）

PATCH body 中字段名为 data_models（snake_case），服务端存储为 dataModels。

[
  {
    "name": "User",
    "table": "users",
    "desc": "用户账号",
    "key_fields": ["id", "email", "password"]
  }
]

无数据库的项目留 []。POST 新建时不支持此字段。

常见错误速查

错误写法	正确写法
`one_liner`	`oneliner`
`conventions: ["字符串"]`	`conventions: {"key": "value"}`
`env_vars[].note`	`env_vars[].hint`
`onboarding: "字符串"`	`onboarding: {summary, key_files, ...}`
`tech_stack: ["Next.js"]`	`tech_stack: [{tech, layer}]`
空字段写 `null`	空字段写 `[]` 或 `{}`
body 里传 `id`	ID 只放 URL
PATCH body 用 `dataModels`	PATCH body 用 `data_models`
decisions/pitfalls 全量覆盖	按 `id` upsert，`null` 值删字段
POST 传 `design` / `data_models`	这两个字段只在 PATCH 生效