TipitakaExportController.php 3.4 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970
  1. <?php
  2. namespace App\Http\Controllers\V3;
  3. use App\Http\Controllers\Concerns\ResolvesCurrentUser;
  4. use App\Http\Controllers\Controller;
  5. use App\Http\Requests\V3\StoreTipitakaExportRequest;
  6. use App\Http\Resources\V3\TipitakaExportResource;
  7. use App\Services\V3\TipitakaExportService;
  8. use Illuminate\Http\Request;
  9. /**
  10. * 三藏下载:把一个 channel 的一部作品、一个分类或整个 channel 导出成文件。
  11. *
  12. * 新能力,没有对应的 v2 端点(v2 的 `export` / `MqExportPaliChapter` 是按章节导出的另一套,原样保留)。
  13. * library 的作品页 / 分类页下载按钮与 wikipali-mobile 都走这里。
  14. */
  15. class TipitakaExportController extends Controller
  16. {
  17. use ResolvesCurrentUser;
  18. public function __construct(private readonly TipitakaExportService $exports) {}
  19. /**
  20. * 发起下载
  21. *
  22. * 同一份文件(同一 channel、范围、格式,且译文没改过)已经生成好就直接返回 `status = ready`
  23. * 与 `download_url`(200);否则排队生成,返回 `queued`(202,带 `Retry-After`),
  24. * 之后轮询 `GET /v3/tipitaka-exports/{id}`。同一份正在生成时不会重复排队。
  25. *
  26. * 格式:`html`、`markdown`、`epub`、`docx`、`offline`(mobile 离线包,NDJSON,下载时 gzip 传输编码,
  27. * 每行一段,`html` 与 `tipitaka-reading` 的 display 相同;只能按作品,首行头里有作品的段落区间
  28. * `para` / `end`,客户端按它判断是否覆盖了自己要的范围)。单部作品的 epub / docx
  29. * 直接给文件,其余是 zip。私有 channel 只有能读它的人能下载。范围太大(超过全三藏的量)422。
  30. *
  31. * @unauthenticated
  32. *
  33. * @bodyParam channel string required channel uid。Example: a19eaf75-c63f-4b84-8125-1bce18311e23
  34. * @bodyParam work integer 作品(library 作品页 URL 里的 sn)。作品、category 只能给一个,都不给 = 整个 channel。Example: 275
  35. * @bodyParam book integer 用坐标指定作品:book + para 所在的那部作品(mobile 用,它不知道 sn)。与 para 同时给。
  36. * @bodyParam para integer 与 book 同时给,作品里的任一段落号(通常是作品起始段)。
  37. * @bodyParam category integer 分类 id(library 分类页 URL 里的 id),含后代分类。
  38. * @bodyParam format string required 文件格式。Enum: html, markdown, epub, docx, offline
  39. *
  40. * @responseStatus 202 已排队生成,响应体同 200
  41. */
  42. public function store(StoreTipitakaExportRequest $request)
  43. {
  44. $export = $this->exports->request($request->validated(), $this->currentUserUid($request));
  45. $response = TipitakaExportResource::make($export)->response();
  46. return $export['status'] === 'ready' ? $response : $response->setStatusCode(202)->header('Retry-After', '2');
  47. }
  48. /**
  49. * 查看下载状态
  50. *
  51. * `status`:`queued` 排队中 / `running` 生成中(`progress` 0–1,`message` 说明当前在哪部作品)/
  52. * `ready` 可下载(带 `download_url`)/ `failed` 失败(重新 POST 即可重试)。
  53. * 不存在或已过期 404。
  54. *
  55. * @unauthenticated
  56. *
  57. * @urlParam export string required 导出 id(POST 返回的 id)。
  58. */
  59. public function show(Request $request, string $export)
  60. {
  61. return TipitakaExportResource::make($this->exports->show($export, $this->currentUserUid($request)));
  62. }
  63. }