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渲染时替换。