feat(docs): API Reference — full REST endpoint docs + AI-readable layer (#1257)

Adds the /docs/api API Reference: an openapi.yaml-driven renderer covering the REST endpoints and WebSocket commands with trilingual (en / zh-CN / zh-HK) content, multi-language raw-HTTP request samples, Try-it, search, and machine-readable .md pages plus llms.txt / llms-full.txt entries.

Also restores six operations that were lost when generated modules shared a path (order_detail, cancel_order, list_watchlist_groups, delete_watchlist_group, list_topic_replies, list_grid_orders), keeps action verbs in endpoint names so endpoints sharing a resource noun stay distinguishable, and ports the time-condition order (#1289), DelayedNotReported (#1263) and attached-order depth level (#1189) docs into the spec.

Author: hogan-yuan

.gitignore

@@ -37,11 +37,10 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 old_docs
 .superpowers
+# superpowers plans/specs are local working artifacts — never version them.
+# (astro-migration files already tracked on main stay tracked; gitignore does
+# not affect already-tracked files.)
 docs/superpowers/*
-!docs/superpowers/specs/
-!docs/superpowers/specs/**
-!docs/superpowers/plans/
-!docs/superpowers/plans/**
 .claude/worktrees
 .worktrees
 

astro.config.ts

@@ -25,6 +25,61 @@ const sitemapLocale = (url: string) =>
 const BUILD_FORMAT = process.env['BUILD_FORMAT'] === 'directory' ? 'directory' : 'file'
 const ASSETS_DIR = process.env['ASSETS_DIR'] === '_docs' ? '_docs' : 'assets'
 
+// Dev-only reverse proxy for the TryIt debugger. Vite's built-in http-proxy
+// returns 502 for these HTTPS upstreams under bun, so forward with fetch (which
+// works). `/api-prod` → production gateway.
+function apiDevProxy() {
+  const TARGETS: Record<string, string> = {
+    '/api-prod': 'https://openapi.longbridge.com',
+    // Legacy default prefix used by <TryIt> when no baseUrl is passed.
+    '/api': 'https://openapi.longbridge.com',
+  }
+  return {
+    name: 'lb-api-dev-proxy',
+    apply: 'serve' as const,
+    configureServer(server: { middlewares: { use: (fn: (req: any, res: any, next: () => void) => void) => void } }) {
+      // Dev only: corporate networks MITM these HTTPS upstreams with a cert the
+      // dev process doesn't trust, so outbound fetch fails. Skip verification —
+      // this never runs in a production build (apply: 'serve').
+      process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = '0'
+      server.middlewares.use(async (req: any, res: any, next: () => void) => {
+        const url: string = req.url ?? ''
+        const prefix = Object.keys(TARGETS).find((p) => url === p || url.startsWith(p + '/'))
+        if (!prefix) return next()
+        const target = TARGETS[prefix]
+        const path = url.slice(prefix.length) || '/'
+        try {
+          const chunks: Buffer[] = []
+          for await (const c of req) chunks.push(c as Buffer)
+          const method: string = (req.method ?? 'GET').toUpperCase()
+          const headers: Record<string, string> = {}
+          for (const [k, v] of Object.entries(req.headers)) {
+            if (k === 'host' || k === 'connection' || k === 'content-length') continue
+            if (typeof v === 'string') headers[k] = v
+          }
+          const upstream = await fetch(target + path, {
+            method,
+            headers,
+            body: method === 'GET' || method === 'HEAD' || chunks.length === 0 ? undefined : Buffer.concat(chunks),
+          })
+          res.statusCode = upstream.status
+          upstream.headers.forEach((value: string, key: string) => {
+            const k = key.toLowerCase()
+            // Body is already decoded by fetch — don't forward encoding/length.
+            if (k === 'content-encoding' || k === 'content-length' || k === 'transfer-encoding') return
+            res.setHeader(key, value)
+          })
+          res.end(Buffer.from(await upstream.arrayBuffer()))
+        } catch (err) {
+          res.statusCode = 502
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.end(JSON.stringify({ code: -1, msg: `dev proxy error: ${err instanceof Error ? err.message : String(err)}`, data: null }))
+        }
+      })
+    },
+  }
+}
+
 export default defineConfig({
   site: SITE,
   // 产物形态按边缘分轨，默认 'file'：
@@ -80,6 +135,11 @@ export default defineConfig({
   ],
   vite: {
     plugins: [
+      // Dev proxy for the API Reference TryIt debugger: one prefix per
+      // environment so the 生产/测试 toggle can hit either backend without CORS.
+      // Implemented with fetch (not Vite's http-proxy, which 502s under bun for
+      // these HTTPS upstreams). Dev only — prod talks to the real domains.
+      apiDevProxy(),
       tailwind(),
       // Rename mdx frontmatter `layout:` → `docs_layout:` so astro-mdx
       // doesn't try to resolve values like "api-reference" as module

bun.lock

@@ -29,7 +29,6 @@ Create and manage price alerts for securities.
 |---|---|
 | [list_alerts](./alert/list-alerts) | List all active price alerts |
 | [create_alert](./alert/create-alert) | Create a new price alert |
-| [update_alert](./alert/update-alert) | Update an existing alert |
 | [delete_alert](./alert/delete-alert) | Delete a price alert |
 
 ## DCAContext