feat: 前台 .shtml 后缀 canonical + strict_types 全量启用 + 对外 API（Sanctum+Scramble 文档）+ pm2 ecosystem + GitHub Actions CI + 插件/主题/架构/API 文档 + REDIS_PREFIX 说明

2026-08-11 19:37:33 +08:00
parent 1c8a801238
commit fc6624cf84
244 changed files with 1902 additions and 97 deletions
@@ -0,0 +1,86 @@
+# API 文档
+
+对外 HTTP API，供小程序 / 第三方平台接入。Base URL：`https://your-domain.com/api`
+
+- **交互式文档**（OpenAPI/Swagger 风格，Scramble 自动生成）：`GET /docs/api`
+- **OpenAPI JSON**：`GET /docs/api.json`
+- 认证：Bearer Token（Laravel Sanctum），仅 `/api/me` 需要
+
+## 认证（可选）
+
+```bash
+# 生成 API Token
+php artisan tinker --execute='$u = App\Models\User::where("email","you@example.com")->first(); dump($u->createToken("mini-program")->plainTextToken);'
+```
+
+请求头：`Authorization: Bearer <token>`
+
+## 端点总览
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| GET | `/api/site` | 站点信息 | 否 |
+| GET | `/api/posts` | 文章列表（分页/筛选/搜索） | 否 |
+| GET | `/api/posts/{slug}` | 文章详情（含渲染后 HTML） | 否 |
+| GET | `/api/categories` | 分类列表 | 否 |
+| GET | `/api/tags` | 标签列表（含文章数） | 否 |
+| POST | `/api/comments` | 提交评论 | 否 |
+| GET | `/api/me` | 当前用户 | 是 |
+
+## 示例
+
+### 站点信息
+
+```bash
+curl http://laralog.test/api/site
+```
+
+```json
+{"name":"旧博客的名字","description":"老博客描述","icp":"京ICP备12345678号","url":"http://laralog.test","rss":"http://laralog.test/rss.xml","api_version":"1.0"}
+```
+
+### 文章列表
+
+```bash
+curl "http://laralog.test/api/posts?page=1&per_page=10&category=tech&tag=laravel&q=关键词"
+```
+
+```json
+{
+  "data": [
+    {
+      "id": 1, "title": "你好，世界", "slug": "post-1",
+      "excerpt": "第一篇博客文章", "category": "生活随笔",
+      "tags": ["随笔"], "views": 100, "comment_count": 2,
+      "published_at": "2020-09-13T12:26:40+00:00",
+      "url": "http://laralog.test/posts/post-1.shtml"
+    }
+  ],
+  "meta": { "current_page": 1, "last_page": 1, "per_page": 10, "total": 1 }
+}
+```
+
+### 文章详情
+
+```bash
+curl http://laralog.test/api/posts/post-1
+```
+
+返回 `content_html`（与前台一致：Markdown 渲染 / [attach] 短代码解析 / 付费内容过滤）。
+
+### 提交评论
+
+```bash
+curl -X POST http://laralog.test/api/comments \
+  -H "Content-Type: application/json" \
+  -d '{"post_id":1,"author_name":"访客","content":"写得很好","website":""}'
+```
+
+- `website` 为蜜罐字段，必须留空
+- 评论审核开关（comment_audit）开启时返回 `pending`，关闭直接发布
+
+### 小程序接入建议
+
+- 启动时请求 `/api/site` + `/api/posts` 缓存首页
+- 文章详情拉取 `content_html` 直接渲染（富文本/图片已含 S3 URL）
+- 评论提交带 `post_id`；如需"我的评论/会员"能力，用 Bearer Token 调 `/api/me`（可扩展）