TermController.php 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127
  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\LookupTermRequest;
  6. use App\Http\Requests\V3\ShowTermRequest;
  7. use App\Http\Requests\V3\UpdateTermRequest;
  8. use App\Http\Resources\V3\TermResource;
  9. use App\Models\DhammaTerm;
  10. use App\Services\V3\AgentGrantService;
  11. use App\Services\V3\TermService;
  12. use Illuminate\Http\Request;
  13. /**
  14. * 术语 / 百科词条:按词查、单条、改、删。
  15. *
  16. * 取代 `GET /v2/terms?view=word`、`GET /v2/terms/{id}`、`PUT /v2/terms/{id}`、`DELETE /v2/terms/{id}`
  17. * (`DhammaTermController`)。v2 那份在 dashboard-v4 下线前原样保留,不要改动。
  18. * 列表与新建在 {@see ChannelTermController}、{@see StudioTermController}。
  19. *
  20. * AI 模型可凭人类授权(请求头 `X-Agent-Grant`)代写 channel 里的术语:editor 记授权人、co_editor 记模型。
  21. */
  22. class TermController extends Controller
  23. {
  24. use ResolvesCurrentUser;
  25. public function __construct(
  26. private readonly TermService $terms,
  27. private readonly AgentGrantService $grants,
  28. ) {}
  29. /**
  30. * 按词查术语
  31. *
  32. * 这些词在你看得见的 channel 与 studio 级术语里的词条(编辑时看同词的其它义项、社区译法)。
  33. *
  34. * @unauthenticated
  35. *
  36. * @queryParam word string required 巴利词,逗号分隔,最多 50 个
  37. * @queryParam tag string 义项;传空串只要没有义项的
  38. * @queryParam channel string 只要这个 channel 的
  39. * @queryParam language string 只要这个语言的
  40. * @queryParam with_body boolean 每条都带渲染后的正文 `body`
  41. * @queryParam page integer 页码
  42. * @queryParam per_page integer 每页条数,最大 200。Default: 20
  43. */
  44. public function index(LookupTermRequest $request)
  45. {
  46. return TermResource::collection($this->terms->lookup(
  47. ['with_body' => $request->boolean('with_body')] + $request->validated(),
  48. $this->currentUserUid($request),
  49. $request->integer('per_page', 20),
  50. ));
  51. }
  52. /**
  53. * 术语详情
  54. *
  55. * 带渲染后的「摘要 + 正文」(`body`)。channel 里的术语跟 channel 的可见性,studio 级的谁都能看。
  56. * 响应带 `ETag` 头(与 `etag` 字段相同),修改时放进 `If-Match`。
  57. *
  58. * @unauthenticated
  59. *
  60. * @urlParam term string required 术语 id(guid)
  61. *
  62. * @queryParam channels string 正文按这些 channel 解析(句子、术语),逗号分隔,最多 20 个;只认你看得见的,不给就用术语所在 channel
  63. * @queryParam mode string 正文模式。Enum: read,edit Default: read
  64. * @queryParam format string 正文格式:tree 给节点树 `body`,html 给 HTML 字符串 `html`(WebView 显示用)。Enum: tree,html Default: tree
  65. *
  66. * @responseStatus 403 所在 channel 看不见
  67. */
  68. public function show(ShowTermRequest $request, DhammaTerm $term)
  69. {
  70. return TermResource::make($this->terms->show($term, $this->currentUserUid($request), $request->render()));
  71. }
  72. /**
  73. * 改术语
  74. *
  75. * 只改传了的字段;word / tag 不能改(要改就新建一条,把旧的 redirect 过去)。必须带请求头
  76. * `If-Match`(取自详情的 `etag` / `ETag`):不带 428,这条在你编辑期间被改过 412(响应里给出最新的 `etag`)。
  77. * 分类从 note 的 `{{category|…}}` 重新抽取。channel 里的术语跟 channel 的写权限,studio 级的要团队 editor 以上。
  78. *
  79. * @urlParam term string required 术语 id(guid)
  80. *
  81. * @bodyParam meaning string 释义
  82. * @bodyParam other_meaning string|null 其它释义
  83. * @bodyParam note string|null 正文
  84. * @bodyParam summary string|null 摘要,格式与 note 相同
  85. * @bodyParam quality string|null 质量。Enum: featured,standard,draft,pending
  86. * @bodyParam content_type string 正文方言。Enum: markdown,markdown-e2
  87. * @bodyParam redirect string|null 重定向到 word 或 word@tag
  88. * @bodyParam language string 语言(只有 studio 级术语能改)
  89. *
  90. * @responseStatus 403 不能修改
  91. * @responseStatus 412 这条在你编辑期间被改过
  92. * @responseStatus 428 没带 If-Match
  93. */
  94. public function update(UpdateTermRequest $request, DhammaTerm $term)
  95. {
  96. return TermResource::make($this->terms->update(
  97. $term,
  98. $this->grants->actor(
  99. $this->currentUser($request)['user_uid'],
  100. $request->header(AgentGrantService::HEADER),
  101. ),
  102. $request->validated(),
  103. $request->header('If-Match'),
  104. ));
  105. }
  106. /**
  107. * 删术语
  108. *
  109. * 软删除,返回被删的术语。拥有者本人或团队 owner 能删;AI 模型不能删。
  110. *
  111. * @urlParam term string required 术语 id(guid)
  112. *
  113. * @responseStatus 403 不能删除
  114. */
  115. public function destroy(Request $request, DhammaTerm $term)
  116. {
  117. return TermResource::make($this->terms->delete($term, $this->currentUser($request)['user_uid']));
  118. }
  119. }