前台 API v1 接口（/api/v1）

在线接口文档（Apifox，可在线调试）：https://s.apifox.cn/beffd1da-1021-434c-8f13-8cbf50a3f406

1. 用户认证与账户

方法	路径	说明
POST	`/api/v1/auth/login`	用户登录（密码/手机验证码/微信/Apple）
POST	`/api/v1/auth/register`	用户注册（手机/邮箱）
POST	`/api/v1/auth/logout`	退出登录
GET	`/api/v1/auth/info`	当前用户信息

2. 公共接口

方法	路径	说明
GET	`/api/v1/common/*`	公共接口（短信/邮件验证码、地区等）
POST	`/api/v1/common/sms-captcha`	发送短信验证码
POST	`/api/v1/common/mail-captcha`	发送邮件验证码

3. 应用版本

方法	路径	说明
POST	`/api/v1/apps/check-update`	App 版本检查更新（传 slug/platform/build，返回是否有更新、是否强制、最新版本信息）

4. 用户个人中心

方法	路径	说明
GET	`/api/v1/user/*`	用户个人中心（资料、密码、通知、积分、金币、登录历史等）
GET	`/api/v1/user`	获取基本资料
POST	`/api/v1/user/profile`	修改个人资料
POST	`/api/v1/user/avatar`	修改头像（multipart/form-data，字段 `avatar`，自动转 WebP）
POST	`/api/v1/user/username`	修改用户名
POST	`/api/v1/user/password`	修改密码
POST	`/api/v1/user/phone`	修改手机号
POST	`/api/v1/user/email`	修改邮箱
POST	`/api/v1/user/verification-mail`	发送验证邮件
DELETE	`/api/v1/user`	注销并删除自己的账户
GET	`/api/v1/user/notifications`	通知列表
GET	`/api/v1/user/login-histories`	登录历史
GET	`/api/v1/user/socials`	当前用户绑定的第三方账号列表（分页，可按 `provider` 过滤；openid/unionid 脱敏）
GET	`/api/v1/user/identity`	当前用户最新一条实名认证记录
GET	`/api/v1/user/identity/status`	简要实名认证状态
POST	`/api/v1/user/identity`	提交/重新提交实名认证（personal 个人 / enterprise 企业）
GET	`/api/v1/user/addresses`	收货地址列表
POST	`/api/v1/user/addresses`	新增收货地址
PUT	`/api/v1/user/addresses/{id}`	更新收货地址
DELETE	`/api/v1/user/addresses/{id}`	删除收货地址

4.1 修改头像（POST `/api/v1/user/avatar`）

需 Sanctum 登录认证，请求格式为 multipart/form-data

表单字段	类型	必填	说明
`avatar`	file	是	头像图片，支持 jpg/jpeg/png/gif

服务端处理：图片经 Intervention 统一转换为 WebP（质量 60），以用户 ID 命名（{id}.webp），按 ID 补零 9 位分两级目录存储（avatar/000/0000/{id}.webp），重复上传直接覆盖旧头像；上传结果写入附件台账，更新资料后派发 UserProfileUpdated 事件（驱动完善资料任务进度）。

成功响应 200：

json

{
  "message": "头像修改完成",
  "path": "avatar/000/0000/1.webp",
  "avatar": "avatar/000/0000/1.webp"
}

错误响应：未登录返回 401；未传文件或文件类型不合法返回 422（errors.avatar 含具体校验信息）。

5. 内容互动接口

5.1 点赞（/api/v1/likes）

方法	路径	说明
GET	`/api/v1/likes`	我的点赞列表（分页，可按 `source_type` 过滤）
POST	`/api/v1/likes`	添加点赞
DELETE	`/api/v1/likes/{like}`	取消点赞

5.2 收藏（/api/v1/collections）

方法	路径	说明
GET	`/api/v1/collections`	我的收藏列表（分页，可按 `source_type` 过滤）
POST	`/api/v1/collections`	添加收藏
DELETE	`/api/v1/collections/{collection}`	取消收藏

5.3 关注（/api/v1/follows）

方法	路径	说明
GET	`/api/v1/follows`	我的关注列表（分页，可按 `source_type` 过滤）
POST	`/api/v1/follows`	添加关注
DELETE	`/api/v1/follows/{follow}`	取消关注

5.4 评论（/api/v1/comments）

方法	路径	说明
GET	`/api/v1/comments`	评论列表（分页，可按 `source_type` + `source_id` 过滤；公开接口）
POST	`/api/v1/comments`	发布评论（支持 `parent_id` 回复、`mentioned_users` 艾特）
DELETE	`/api/v1/comments/{comment}`	删除评论（仅本人）

5.5 访问记录（/api/v1/visits）

方法	路径	说明
POST	`/api/v1/visits`	记录一次访问（`user_id` / `ip` 由后端注入，前端仅传 `source_type` + `source_id`）
GET	`/api/v1/user/visits`	我的访问记录（分页，可按 `source_type` 过滤）

两条接口均需 Sanctum 认证；写入接口由 RecordVisitRequest::prepareForValidation() 合并 user_id 与 ip，控制器不直接拼装
资源校验复用现有 source_types() 白名单（同 Like/Collection），source_type 命中多态别名之外的值返回 422
不做唯一约束：同一用户对同一资源可重复访问，符合 PV 语义

5.6 内容互动约定

点赞、收藏、关注、访问记录全部接口需 Sanctum 认证；评论仅 POST/DELETE 需认证，列表公开
写入参数：source_type（必填，须为 config/morph_maps.php 已注册别名）、source_id（必填）、extra（可选，JSON，仅点赞/收藏/关注使用）
点赞/收藏/关注对同一资源重复提交返回 422，由 Rule::unique 拦截
越权删除他人记录返回 403，由 LikePolicy / CollectionPolicy / FollowPolicy / CommentPolicy 校验
响应中的 user_id 通过模型 #[Hidden] 隐藏
列表接口使用 Laravel 标准分页，支持 page / per_page（1-100，默认 15）

6. 公告

方法	路径	说明
GET	`/api/v1/announcements`	公告列表
GET	`/api/v1/announcements/{id}`	公告详情

7. 协议

方法	路径	说明
GET	`/api/v1/agreements/{category}`	按类别获取最新已发布协议（公开，带 HTTP 缓存）

前端传入协议类别编码（如 user_agreement、privacy_policy），返回该类别最新已发布版本的完整内容（含 title、content、version、effective_at）。

方法	路径	说明
GET	`/api/v1/banners`	获取公开 Banner 列表（自动过滤禁用/未开始/已过期）

9. 用户反馈（/api/v1/user/feedbacks）

全部接口需 Sanctum 登录认证，反馈自动绑定当前登录用户（user_id 由服务端注入，无需客户端传）。

方法	路径	说明
POST	`/api/v1/user/feedbacks`	提交用户反馈（成功返回 201，响应体含反馈单号 `code`）
GET	`/api/v1/user/feedbacks/my`	我的反馈列表（分页，按提交时间倒序）

9b. 用户举报（/api/v1/user/reports）

全部接口需 Sanctum 登录认证，举报自动绑定当前登录用户。被举报对象使用 morph_alias (comment / user) 接收，服务端按 morphMap 解析为全限定类名并校验目标存在。

方法	路径	说明
POST	`/api/v1/user/reports`	提交举报。Body：`target_type` ∈ `comment`/`user`、`target_id`、`category`（取自字典 `report_category`，9 类）、可选 `reason`（≤500 字）、可选 `evidence`（≤9 个 URL）。成功返回 201。同一人对同一目标在 `pending`/`processing` 状态下不可重复提交（返回 422）。`reason` 内容会经过敏感词过滤。目标对象不存在返回 422
GET	`/api/v1/user/reports/my`	我的举报列表（分页，按提交时间倒序）

10. 钱包接口（/api/v1/user/wallet）

方法	路径	说明	状态
GET	`/api/v1/user/wallet`	我的钱包概览（可用余额、冻结余额、累计收入、累计支出）	✅ 已交付
GET	`/api/v1/user/wallet/trades`	我的钱包流水（分页，可按 `type`/时间范围过滤）	✅ 已交付
POST	`/api/v1/user/wallet/recharges`	创建充值订单（返回 `order_no`，成功返回 201）	✅ 已交付
GET	`/api/v1/user/wallet/recharges`	我的充值订单列表（分页，可按 `pay_status` 过滤）	✅ 已交付
GET	`/api/v1/user/wallet/recharges/{recharge}`	充值订单详情（用于轮询到账状态）	✅ 已交付
POST	`/api/v1/user/wallet/withdraws`	提交提现申请（`amount`、`account_type`∈wechat/alipay/bank、`account_info:{account,real_name}`，成功返回 201，冻结对应金额）	✅ 已交付
GET	`/api/v1/user/wallet/withdraws`	我的提现列表（分页，可按 `status` 过滤，收款账号脱敏）	✅ 已交付
GET	`/api/v1/user/wallet/withdraws/{withdraw}`	提现详情（Policy 校验归属，收款账号脱敏）	✅ 已交付

钱包接口约定

全部接口需 Sanctum 认证，内部统一取 auth()->user() 作为 owner，前台无需感知多态
充值下单走 wallet.recharge_throttle 限流，提现提交走 wallet.withdraw_throttle（默认 5 次/分钟），防止刷单
越权访问他人订单返回 403，由 RechargePolicy / WithdrawPolicy 校验
提现提交需校验：开关（wallet.enable_withdraw）、金额区间（wallet.min_withdraw_amount/wallet.max_withdraw_amount）、当日次数（wallet.daily_withdraw_limit）、不存在待审核单；余额不足返回 422
金额字段统一以元为单位、decimal(16,2) 精度返回字符串，避免前端浮点精度丢失
前台提现响应使用 Api\V1\WithdrawResource，脱敏展示，不返回 owner、client_ip、reviewed_by、remark 等内部字段
支付渠道对接已挂起，pay_channel 当前仅接受 manual，到账由管理员在后台确认

11. 字典公开接口

方法	路径	说明
GET	`/api/v1/dict-items`	公开字典项查询（按 code 获取字典数据）

12. 支付回调（/callback）

方法	路径	说明
POST	`/callback/pay/wechat`	微信支付异步回调（验签后置订单成功并入账）
POST	`/callback/pay/alipay`	支付宝异步回调（验签后置订单成功并入账）

回调接口豁免 CSRF 与认证中间件，必须完成渠道验签；处理逻辑幂等（同一 order_no 重复回调只入账一次）。

13. MCP Server（/mcp/v1）

将上述 C 端接口能力封装为 MCP（Model Context Protocol）工具，供 AI 客户端直接调用。采用进程内封装：工具直接调用业务层/模型，不经过 HTTP 转发。

方法	路径	说明
POST	`/mcp/v1`	MCP JSON-RPC 2.0 端点（Sanctum Token 认证）

接入方式

请求头：Authorization: Bearer <Sanctum 个人访问令牌>，与 /api/v1 共用同一套用户令牌
Content-Type：application/json，请求体为 JSON-RPC 2.0（tools/list、tools/call 等）
未认证返回 401；工具入参校验失败在 JSON-RPC 响应中返回校验错误信息

客户端配置示例

json

{
  "mcpServers": {
    "skel-api": {
      "type": "http",
      "url": "https://laravel-skel-forge.test/mcp/v1",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

已封装工具（70 个：35 只读 + 35 写操作）

域	工具名	说明	入参
用户	`user.profile.get`	基本资料（账号、昵称、头像、积分、金币、会员状态）	无
用户	`user.login_histories.list`	登录历史	分页
用户	`user.points.list`	积分流水	分页
用户	`user.coins.list`	金币流水	分页
用户	`user.socials.list`	第三方账号绑定（openid/unionid 脱敏）	分页 + `provider`
用户	`user.visits.list`	我的访问记录	分页 + `source_type`
通知	`user.notifications.list`	通知列表	分页 + `type`
通知	`user.notifications.unread`	未读通知列表	分页 + `type`
地址	`user.address.list`	收货地址列表	分页
地址	`user.address.get`	地址详情（越权拦截）	`id`
反馈	`user.feedback.list`	我的反馈列表	分页
举报	`user.report.list`	我的举报列表	分页
实名	`user.identity.get`	最新一条实名认证记录	无
实名	`user.identity.status`	实名认证简要状态	无
钱包	`wallet.overview.get`	钱包概览（余额、冻结、累计收支）	无
钱包	`wallet.trades.list`	钱包流水	分页 + `type` / `start_date` / `end_date`
钱包	`wallet.recharge.list`	充值订单列表	分页 + `pay_status`
钱包	`wallet.recharge.get`	充值订单详情（越权拦截）	`id`
钱包	`wallet.withdraw.list`	提现申请列表	分页 + `status`
钱包	`wallet.withdraw.get`	提现详情（越权拦截）	`id`
钱包	`wallet.withdraw_account.list`	收款账户列表（默认排最前）	分页 + `account_type`
内容互动	`content.comment.list`	已审核通过的公开评论列表	分页 + `source_type` / `source_id`
内容互动	`content.collection.list`	我的收藏列表	分页 + `source_type`
内容互动	`content.like.list`	我的点赞列表	分页 + `source_type`
内容互动	`content.follow.list`	我的关注列表	分页 + `source_type`
任务	`task.list`	任务中心（按分组返回，含当前用户进度）	无
邀请	`invite.record.list`	我的邀请记录	分页
邀请	`invite.stats.get`	邀请统计（人数、是否有邀请人）	无
公开	`common.banner.list`	指定广告位生效中的 Banner	`position`
公开	`common.area.list`	地区列表（不传 `area_id` 返回省级）	`area_id`?
公开	`common.dict_item.list`	公开字典项（白名单内编码）	`code`
公开	`common.announcement.list`	已发布公告列表	分页
公开	`common.announcement.get`	公告详情	`id`
公开	`common.agreement.get`	最新已发布协议	`category`
会话	`auth.token.list`	已签发的访问令牌列表	分页

写操作工具（18 个）

域	工具名	说明	入参
内容互动	`content.comment.create`	发布评论（敏感词过滤，命中 review 级别进入待审核）	`source_type` / `source_id` / `content` / `parent_id`? / `mentioned_users`?
内容互动	`content.comment.delete`	删除自己的评论	`id`
内容互动	`content.like.create`	点赞（同一用户同一对象防重复）	`source_type` / `source_id` / `extra`?
内容互动	`content.like.delete`	取消点赞	`source_type` / `source_id`
内容互动	`content.collection.create`	收藏（防重复）	`source_type` / `source_id` / `extra`?
内容互动	`content.collection.delete`	取消收藏	`source_type` / `source_id`
内容互动	`content.follow.create`	关注（防重复）	`source_type` / `source_id` / `extra`?
内容互动	`content.follow.delete`	取消关注	`source_type` / `source_id`
用户资料	`user.profile.update`	修改个人资料（昵称、生日、性别、地区、网站、介绍、签名）	各字段可选
用户资料	`user.username.update`	修改用户名（全局唯一）	`username`
用户资料	`user.email.update`	修改邮箱（需邮件验证码）	`email` / `verify_code`
用户资料	`user.phone.update`	修改手机号（需短信验证码）	`phone` / `verify_code`
用户资料	`user.avatar.update`	修改头像（base64 编码图片，自动转 WebP）	`avatar_base64` / `extension`
用户资料	`user.password.update`	修改密码（需旧密码验证）	`old_password` / `password`
地址	`user.address.create`	添加收货地址	`name` / `phone` / `province` / `city` / `district` / `address` / `country`? / `is_default`? / `zipcode`?
地址	`user.address.update`	修改收货地址	`id` + 可选字段
地址	`user.address.delete`	删除收货地址（软删除）	`id`
地址	`user.address.set_default`	设为默认地址	`id`
反馈	`user.feedback.create`	提交用户反馈（敏感词过滤）	`title` / `content` / `type` / `images`? / `contact_name`? / `contact_info`?
举报	`user.report.create`	提交举报（同一对象未结案前不可重复）	`target_type` / `target_id` / `category` / `reason`? / `evidence`?
钱包	`wallet.recharge.create`	创建充值订单（destructive）	`amount` / `pay_channel`
钱包	`wallet.withdraw.create`	提交提现申请（destructive，冻结余额）	`amount` / `withdraw_account_id`
钱包	`wallet.withdraw_account.create`	添加收款账户（首个自动默认）	`account_type` / `real_name` / `account_no` / `bank_name`? / `bank_branch`? / `is_default`?
钱包	`wallet.withdraw_account.update`	修改收款账户	`id` + 可选字段
钱包	`wallet.withdraw_account.delete`	删除收款账户（destructive）	`id`
钱包	`wallet.withdraw_account.set_default`	设为默认收款账户	`id`
任务	`task.claim`	领取任务奖励	`task_id` / `period_key`?
通知	`notification.mark_all_read`	全部标记已读	无
通知	`notification.mark_read`	标记指定通知已读	`id`
通知	`notification.clear_read`	清空已读通知（不可恢复）	无
访问记录	`visit.record`	记录一次访问	`source_type` / `source_id`
会话	`auth.token.delete`	撤销指定访问令牌	`id`
会话	`auth.logout`	退出登录（当前令牌立即失效）	无
账户	`user.delete`	注销并删除账户（destructive，软删除）	无

写操作统一约定：

涉及内容发布的工具（评论、资料介绍/签名、反馈、举报）自动经过敏感词过滤
点赞/收藏/关注工具内置防重复校验，重复调用返回错误
删除/详情工具仅能操作当前登录用户自己的数据，越权返回错误
user.email.update / user.phone.update 需先通过 /api/v1/common/mail-captcha 或 /api/v1/common/sms-captcha 获取验证码
资金类（wallet.recharge.create、wallet.withdraw.create）与账户注销（user.delete）标记 destructiveHint=true，AI 客户端应在执行前向用户二次确认
wallet.withdraw.create 会冻结对应金额，需确保用户余额充足；同一用户仅允许一笔待审核提现

统一约定：

「分页」入参为 page（默认 1）与 per_page（默认 15，1-100）；响应统一为 {items: [...], pagination: {total, per_page, current_page, last_page, has_more}}
详情类工具在记录不存在或不属于当前用户时返回错误（isError=true），不会越权泄漏他人数据
全部工具均带 readOnlyHint 与 idempotentHint，可由 AI 客户端安全缓存结果
工具定义位于 app/Mcp/Tools/，Server 定义位于 app/Mcp/Servers/ApiServer.php
调试：php artisan mcp:inspector mcp/v1

文档来源：PRD 第 6.4 节

前台 API v1 接口（/api/v1） ​

1. 用户认证与账户 ​

2. 公共接口 ​

3. 应用版本 ​

4. 用户个人中心 ​

4.1 修改头像（POST /api/v1/user/avatar） ​

5. 内容互动接口 ​

5.1 点赞（/api/v1/likes） ​

5.2 收藏（/api/v1/collections） ​

5.3 关注（/api/v1/follows） ​

5.4 评论（/api/v1/comments） ​

5.5 访问记录（/api/v1/visits） ​

5.6 内容互动约定 ​

6. 公告 ​

7. 协议 ​

8. Banner ​

9. 用户反馈（/api/v1/user/feedbacks） ​

9b. 用户举报（/api/v1/user/reports） ​

10. 钱包接口（/api/v1/user/wallet） ​

钱包接口约定 ​

11. 字典公开接口 ​

12. 支付回调（/callback） ​

13. MCP Server（/mcp/v1） ​

接入方式 ​

客户端配置示例 ​

已封装工具（70 个：35 只读 + 35 写操作） ​

写操作工具（18 个） ​