适用源码：
fd73c2ee0dac31c7b7a96560623207e15046cd1c。本页是现行 HTTP 接口索引；字段与状态码以docs/http/下的接口文档为准。
运行
HTTP 服务与 /api/auth/* 共用监听地址和服务生命周期。需启用 http-auth、加载 AuthMe，并通过 Vite/Caddy 将同源 /api 转发到插件。默认监听 127.0.0.1:8765，HTTP 线程不直接访问 Bukkit/Towny。
鉴权与会话
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/auth/login |
AuthMe 密码校验，只接受 JSON；原 GET 登录已移除 |
| GET | /api/auth/me |
刷新空闲期限并恢复身份，成功响应含 profile |
| POST | /api/auth/logout |
注销当前会话 |
| GET/POST | /api/auth/verify |
兼容 bearer token 验证 |
| GET | /api/auth/health |
健康检查 |
浏览器保存 Cookie；/api/auth/me 及市集查询接口通过会话校验时刷新空闲期限。时效与注销状态保存在会话表，失效记录无法登录。
市集查询
| 方法 | 路径 |
|---|---|
| GET | /api/market/summaries |
| GET | /api/market/orders |
| GET | /api/market/orders/{id} |
| GET | /api/market/orders/{id}/quote?amount=10 |
| GET | /api/market/items/{itemKey}/history |
| GET | /api/market/items/{itemKey}/candles |
| GET | /api/me/market |
| GET | /api/me/orders |
| GET | /api/me/items |
| GET | /api/me/mailbox |
订单列表支持 side、itemKey、page、pageSize、sort；只返回 OPEN/PARTIAL、剩余数量大于零且尚未到期的订单。金额使用字符串、时间使用 Unix 毫秒，不返回创建者 UUID、托管信息或坐标。
市集写入
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/market/orders |
发布订单；side: "SELL" 或 "BUY" |
| POST | /api/market/buy-orders |
发布收购单，可省略 side |
| POST | /api/market/orders/{id}/buy |
买入 |
| POST | /api/market/orders/{id}/sell |
出售 |
| POST | /api/market/orders/{id}/cancel |
本镇成员撤销本镇订单 |
发布出售单使用 itemId、price、可选 amount / expiresAt；收购单使用 itemKey、amount、price、可选 expiresAt / maxTotal。四种写操作共用账号身份下的幂等键保护，不能把一个操作的请求键改用于其他操作。收购发布、买入和出售的状态通过 /api/me/operations/{key} 查询。
个人与城镇资金
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/me/profile |
在线状态、AuthMe 状态、位置、个人金币、城镇余额与存取权限 |
| POST | /api/me/town/bank/deposit |
城镇银行存入 |
| POST | /api/me/town/bank/withdraw |
城镇银行取出 |
| POST | /api/me/mailbox/claim |
领取本城镇邮箱，物品转入城镇交易所库存 |
| GET | /api/me/operations/{Idempotency-Key} |
查询写操作状态 |
领取邮箱要求在线且游戏内已通过 AuthMe 登录；物品进入本城镇有效交易所库存，不直接发放到操作者背包。
城镇快照与管理
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/towns |
分页列表，排序支持 name/members/plots/balance |
| GET | /api/towns/{uuid} |
名称、公告、镇长、国家、税额、余额、成员数、地块数 |
| GET | /api/towns/{uuid}/members |
成员与城镇 ranks |
| GET | /api/towns/{uuid}/plots |
世界、地块坐标、类型、出售价格 |
| GET | /api/towns/{uuid}/stats |
1～365 天每日余额、成员数、地块数 |
| GET | /api/me/town |
会话所属城镇详情 |
| POST | /api/towns/{uuid}/actions/{action} |
公告、税额、rank、地块出售等管理动作 |
城镇数据由 Folia 全局调度器采集，每 1200 tick 更新一次并原子写入 SQLite；HTTP 请求不访问 Towny。首次快照尚未就绪返回 503 town_snapshot_unavailable。管理动作要求在线、游戏内已登录且操作时仍为目标城镇镇长；结果持久化在 web_online_operations，可通过 /api/me/operations/{requestId} 查询。
错误与幂等
常见状态：未登录 401、无权限 403、未完成操作或请求键冲突 409（operation_pending / idempotency_conflict）。插件重启不会清除阻止重复扣款的记录；UNCERTAIN 或重启遗留阶段需管理员结合经济提供者流水核对，不能自动换键重试。
来源
docs/http/HTTP鉴权登录API.md、docs/http/市集查询API.md、docs/http/在线交易与城镇资金API.md、docs/http/报价身份与交易所校验.md；代码根 folia_plugin/src/main/java/com/flrv/infrastructure/http/。