OctoHz 私人功能 API

管理当前用户的私人数据。全部需要 Bearer Token 鉴权，普通用户即可，无需 admin。

密码库和主机信息属于高敏感数据，使用独立私人密钥授权（不是通用 apiToken），支持设置访问次数上限，用完自动失效，见下方「我的密码」和「我的主机」章节。

---

我的待办

GET    /api/my/todos          # 获取列表（按置顶 > 未完成 > 已完成排序）
POST   /api/my/todos          # 新建 { "content": "待办内容" }
PATCH  /api/my/todos/:id      # 更新（isDone / isPinned / content）
DELETE /api/my/todos/:id      # 删除 → {"ok": true}

TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 新建待办
curl -s -X POST https://octohz.com/api/my/todos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "完成项目文档"}'

# 标记完成
curl -s -X PATCH https://octohz.com/api/my/todos/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isDone": true}'

---

我的文档

文档分类

GET    /api/my/doc-categories        # 获取分类列表
POST   /api/my/doc-categories        # 新建 { "name": "分类名", "parentId": 5 }
PATCH  /api/my/doc-categories/:id    # 改名 { "name": "新名称" }
DELETE /api/my/doc-categories/:id    # 删除（文档 categoryId 自动置 null）→ {"ok": true}

文档 CRUD

GET    /api/my/docs           # 列表（按置顶 > 更新时间倒序）
POST   /api/my/docs           # 新建 → {"id": 123}
GET    /api/my/docs/:id       # 详情（isPublic=true 无需鉴权）
PUT    /api/my/docs/:id       # 更新 → {"id": 123}
DELETE /api/my/docs/:id       # 删除 → {"ok": true}

POST/PUT 字段：

字段	必填	说明
title	✓	文档标题
content	✓	正文，支持 GFM Markdown
categoryId		所属分类 ID（传 null 清除分类）
isPinned		是否置顶
isPublic		是否公开（公开后可分享）

文档地址：https://octohz.com/my/docs?doc=123

---

我的导航

导航分类

GET    /api/my/nav-categories        # 获取分类列表
POST   /api/my/nav-categories        # 新建 { "name": "分类名" }
PATCH  /api/my/nav-categories/:id    # 改名
DELETE /api/my/nav-categories/:id    # 删除 → {"ok": true}

导航 CRUD

GET    /api/my/navs           # 列表
POST   /api/my/navs           # 新建 → 返回完整对象
PATCH  /api/my/navs/:id       # 更新
DELETE /api/my/navs/:id       # 删除 → {"ok": true}

POST 字段： title（✓）、url（✓）、description、categoryId

TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/my/navs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "GitHub", "url": "https://github.com", "description": "代码托管", "categoryId": 1}'

---

我的密码

密码库使用独立私人密钥授权，不是通用 apiToken。在 /my/passwords 或 /my/hosts 页面管理密钥。

密钥管理（用通用 apiToken）

GET    /api/my/private-keys          # 列出所有密钥（id/label/maxReads/usedReads/createdAt）
POST   /api/my/private-keys          # 生成新密钥 → token 只返回一次
DELETE /api/my/private-keys/:id      # 删除密钥

POST 字段： label（备注名，可选）、maxReads（✓ 最大读取次数）

TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/my/private-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Claude MCP", "maxReads": 10}'
# 返回 {"id":1,"token":"abc...","label":"Claude MCP","maxReads":10,"usedReads":0}
# token 只在生成时返回一次，请立即保存

调用密码接口（用私人密钥 token）

GET /api/my/passwords              # 浏览密码结构（免费，不消耗次数）
                                   # 返回分组和条目列表，不含密码明文
GET /api/my/passwords/:id          # 读取具体密码（消耗 1 次）
                                   # 返回含解密明文的完整记录

PRIVATE_KEY="你生成的私人密钥token"

# 浏览所有密码（不消耗次数）
curl https://octohz.com/api/my/passwords \
  -H "Authorization: Bearer $PRIVATE_KEY"

# 读取 id=5 的密码明文（消耗 1 次）
curl https://octohz.com/api/my/passwords/5 \
  -H "Authorization: Bearer $PRIVATE_KEY"

当 usedReads >= maxReads 时，密钥自动失效并删除。

---

我的主机

与密码库共用同一套私人密钥（/api/my/private-keys），无需单独生成。

GET /api/my/hosts              # 浏览主机列表（免费，不消耗次数）
                               # 返回分组和主机列表，不含 rootPassword/panelPassword
GET /api/my/hosts/:id          # 读取主机凭据（消耗 1 次）
                               # 返回完整信息含解密后的 rootPassword、panelPassword

PRIVATE_KEY="你生成的私人密钥token"

# 浏览所有主机（不消耗次数）
curl https://octohz.com/api/my/hosts \
  -H "Authorization: Bearer $PRIVATE_KEY"

# 读取 id=3 的主机完整凭据（消耗 1 次）
curl https://octohz.com/api/my/hosts/3 \
  -H "Authorization: Bearer $PRIVATE_KEY"

---

我的 API

与密码库、主机共用同一套私人密钥（/api/my/private-keys），无需单独生成。

GET    /api/my/apis           # 浏览 API 列表（免费，不消耗次数）
                              # 返回分组和条目列表，不含 apiKey 明文
GET    /api/my/apis/:id       # 读取具体 API Key（消耗 1 次）
                              # 返回含解密 apiKey 的完整记录
POST   /api/my/apis           # 新建 API 条目 → 返回完整对象含 apiKey 明文
PUT    /api/my/apis/:id       # 更新（传什么改什么，不传保留原值）→ 返回完整对象含 apiKey 明文
DELETE /api/my/apis/:id       # 删除 → {"ok": true}

POST/PUT 字段：

字段	必填	说明
name	✓	API 名称（如 OpenAI GPT-4o）
apiKey	✓（POST）	API Key 明文，加密后存储；PUT 不传时保留原值
groupId		所属分组 ID
siteUrl		平台网站地址
planType		套餐类型（如 Pro、免费）
baseUrl		Base URL（如 https://api.openai.com/v1）
model		默认模型（如 gpt-4o、claude-opus-4-7）
notes		备注

PRIVATE_KEY="你生成的私人密钥token"

# 浏览所有 API 条目（不消耗次数）
curl https://octohz.com/api/my/apis \
  -H "Authorization: Bearer $PRIVATE_KEY"

# 读取 id=1 的 API Key 明文（消耗 1 次）
curl https://octohz.com/api/my/apis/1 \
  -H "Authorization: Bearer $PRIVATE_KEY"

页面入口：/my/apis，在「我的密码」和「我的导航」之间（侧边栏）。

---

我的股票

GET    /api/my/stocks              # 持仓列表
POST   /api/my/stocks              # 添加 → 返回完整对象
PATCH  /api/my/stocks/:id          # 更新字段
DELETE /api/my/stocks/:id          # 删除 → {"ok": true}
GET    /api/my/stocks/search?q=    # 搜索股票（含实时报价）
POST   /api/my/stocks/refresh      # 批量刷新当前价格

POST 字段：

字段	必填	说明
name	✓	股票名称（如 贵州茅台）
code	✓	Yahoo Finance symbol（如 600519.SS、0700.HK、AAPL）
market	✓	A股 / 港股 / 美股 / 日股 / 其他
quantity		持仓数量，默认 1
buyPrice	✓	买入价格
currentPrice	✓	当前价格

POST /api/my/stocks/refresh 请求体：{} 刷新全部，{"ids":[1,2]} 刷新指定。

TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/my/stocks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"贵州茅台","code":"600519.SS","market":"A股","quantity":100,"buyPrice":1580,"currentPrice":1620}'

---

我的八字

GET    /api/my/bazi              # 列表（含日主/调候/刑冲合害/喜用神摘要）
POST   /api/my/bazi              # 新建 → 返回完整对象
PATCH  /api/my/bazi/:id          # 更新（含 xiyong 喜用神）
DELETE /api/my/bazi/:id          # 删除 → {"ok": true}
GET    /api/my/bazi/:id          # 完整排盘

POST 字段： name（✓）、gender（0=男/1=女）、year（✓）、month（✓）、day（✓）、hour、minute、isLunar、note

PATCH 额外支持 xiyong（喜用神手动填写，如 "金水"）。

GET /api/my/bazi/:id 完整排盘返回：

• pillars — 四柱（天干/地支/十神/纳音/空亡）
• daYun — 大运表（9步）
• now — 当下大运/流年/流月/流日干支和神煞

{
  "now": {
    "date": "2026-04-17",
    "daYun":   { "ganZhi": "壬申", "startAge": 20, "shenSha": ["天乙贵人"] },
    "liuNian": { "year": 2026, "ganZhi": "丙午", "shenSha": ["桃花"] },
    "liuYue":  { "ganZhi": "甲辰", "startDate": "2026-04-04" },
    "liuRi":   { "ganZhi": "壬子", "shenSha": ["天乙贵人"] }
  }
}