API 变更记录

本文件记录 对外 HTTP API（routes/api.php 等）的变更，便于联调与外部 AI 同步 docs/api/mcp/tools.json。

格式说明：日期下按 工具名 / 路径 列出变动；必要时指向对应 Markdown。

2026-04-05

对外 API Key（实施）

• 新增 api_keys 表、ERP 后台 「API Key」 资源、VerifyApiKey（api.key）中间件；除 GET /api/user（auth:api，仅 Authorization: Bearer）外，routes/api.php 其余路由均要求请求头 X-Api-Key；无 Key、校验失败或已吊销返回 401。
• 吊销：列表「操作」列表单 POST，不再使用 RowAction 追加（避免 Encore 展示器兼容问题）。
• 文档 / MCP：post-orders-import.md 与 mcp/tools.json 已注明 X-Api-Key；get_api_user 仍为 Bearer，其余工具需带 Key。

对外权限设计（文档）

• 新增 external-api-auth-design.md：多 API Key 为主线、路由分级与 X-Api-Key / Authorization 分工；索引见 README.md。

2026-04-04

基础设施

• 新增 docs/api/mcp/tools.json：MCP 风格工具清单（name + description + inputSchema + method + path），供其它系统 AI 调用。
• 新增 docs/api/mcp/README.md：机器消费说明。
• 新增 浏览器可访问 GET /docs/api/mcp-tools.json（内容与仓库 tools.json 一致）。
• 约定：此后每次修改 API，须同步更新 Markdown、tools.json、本 CHANGELOG（见 .cursor/skills/api-docs-sync/SKILL.md）。

post_api_orders_import（POST /api/orders/import）

• 变更：与后台「导入订单」Excel 逻辑对齐；请求体改为 JSON account_id + rows（支持 excel_format）。详见 post-orders-import.md。

全量登记

• 在 tools.json 中登记当前 routes/api.php 内全部端点（含 legos、v1、logistics、etsy/message、统计等）；后续路由增删改须更新该文件。

部署域名

• 站点根与 API 域名：由 .env 的 APP_URL 决定，不在文档中写死。
• ERP 后台：https://tiancase.com/{ADMIN_ROUTE_PREFIX}（默认 /admin）。
• mcp-tools.json：GET https://tiancase.com/docs/api/mcp-tools.json 返回的 JSON 会注入 server.base_url 等；仓库内静态 tools.json 中这些字段可为 null。

ERP 顶部栏

• 入口：app/Admin/bootstrap.php 中 Admin::navbar() 在右上角用户菜单左侧增加「API 文档」，新标签打开 url('/docs/api')，随 APP_URL 变化。
• 侧边栏：已移除仅作文档入口的侧边栏项（迁移 2026_04_05_100000_remove_api_docs_from_admin_sidebar_menu）。若曾执行过 2026_04_04_120000_add_api_docs_menu_to_admin_menu，再执行上述迁移即可删掉侧边栏重复入口。

域名配置

• 修改：文档与 mcp-tools.json 响应不再写死域名；server.* URL 由 config('app.url') 注入。Markdown 中使用 https://tiancase.com、admin，由 ApiDocsController 渲染时替换。