TermExchangeService.php 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355
  1. <?php
  2. namespace App\Services\V3;
  3. use App\Exceptions\BusinessException;
  4. use App\Models\Channel;
  5. use App\Models\DhammaTerm;
  6. use Illuminate\Auth\Access\AuthorizationException;
  7. use Illuminate\Database\Eloquent\Builder;
  8. use Illuminate\Http\UploadedFile;
  9. use Illuminate\Validation\ValidationException;
  10. use PhpOffice\PhpSpreadsheet\Cell\Coordinate;
  11. use PhpOffice\PhpSpreadsheet\IOFactory;
  12. use PhpOffice\PhpSpreadsheet\Spreadsheet;
  13. use PhpOffice\PhpSpreadsheet\Writer\Xlsx;
  14. /**
  15. * 术语的批量导入 / 导出(xlsx)。
  16. *
  17. * 取代 v2 `terms-export`(生成后存 Redis 5 分钟、再凭 uuid 下载)与 `terms-import`(GET 写入、读附件临时文件)。
  18. *
  19. * 导出:列表接口带 `Accept: xlsx` 时整表返回(过滤同列表、不分页),权限同列表。
  20. * 导入:上传 xlsx。按**表头的列名**取值,所以 v2 导出的旧表格(id / word / meaning / other_meaning / note / tag /
  21. * language / channel_id)也能直接导入。规则(2026-11-17 用户定):
  22. * - **部分成功**:出错的行跳过、其余照写,响应逐行列出跳过的原因
  23. * - 有 id:改那一条。word / tag 与库里不同就报错(建立后不能改);带 etag 列且与当前不一致就报「导出之后被改过」
  24. * - 无 id:同范围里已有同 word + tag 的就改它,没有就新建
  25. * - word 为空报错(v2「有 id、word 为空就删除」不保留,删除走单条删除)
  26. * - 每行的权限与单条新建 / 修改相同;只给人类(不支持 agent 代写)
  27. * - 改动不超过 {@see self::REINDEX_LIMIT} 条时立即重建搜索索引,更多的等每周 `opensearch:index-term`
  28. */
  29. class TermExchangeService
  30. {
  31. public const MIME = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
  32. public const MAX_ROWS = 5000;
  33. /** 改动不超过这么多条才立即重建搜索索引(逐条渲染全文,量大会很慢;线上没有队列 worker) */
  34. public const REINDEX_LIMIT = 50;
  35. /** 导出的列(导入按列名认,顺序无所谓) */
  36. public const COLUMNS = [
  37. 'id', 'word', 'tag', 'meaning', 'other_meaning', 'summary', 'note',
  38. 'quality', 'content_type', 'redirect', 'language', 'channel_id', 'etag',
  39. ];
  40. /** 导入时可以改的内容列 */
  41. private const CONTENT = ['meaning', 'other_meaning', 'summary', 'note', 'quality', 'content_type', 'redirect'];
  42. public function __construct(
  43. private readonly TermService $terms,
  44. private readonly ChannelAbilityService $channels,
  45. private readonly GroupAbilityService $groups,
  46. private readonly AgentGrantService $agents,
  47. ) {}
  48. /* ------------------------------------------------------------------ 导出 */
  49. /**
  50. * 把查询结果写成 xlsx(二进制内容)。
  51. *
  52. * @param Builder<DhammaTerm> $query
  53. */
  54. public function export(Builder $query): string
  55. {
  56. $spreadsheet = new Spreadsheet;
  57. $sheet = $spreadsheet->getActiveSheet();
  58. $sheet->fromArray([self::COLUMNS], null, 'A1');
  59. $line = 2;
  60. foreach ($query->cursor() as $term) {
  61. $sheet->fromArray([[
  62. $term->guid, $term->word, $this->terms->normalizeTag($term->tag), $term->meaning,
  63. $term->other_meaning, $term->summary, $term->note, $term->quality,
  64. $term->effectiveContentType(), $term->redirect, $term->language, $term->channal, $term->etag(),
  65. ]], null, "A{$line}", true);
  66. $line++;
  67. }
  68. $stream = fopen('php://memory', 'r+');
  69. (new Xlsx($spreadsheet))->save($stream);
  70. rewind($stream);
  71. $content = (string) stream_get_contents($stream);
  72. fclose($stream);
  73. return $content;
  74. }
  75. /* ------------------------------------------------------------------ 导入 */
  76. /**
  77. * 导入到 channel:所有行都落在这个 channel,owner 与语言跟 channel(表里的 channel_id / language 列不看)。
  78. *
  79. * @return array{created: int, updated: int, unchanged: int, reindexed: bool, errors: list<array{row: int, message: string}>}
  80. *
  81. * @throws AuthorizationException 不能写这个 channel,或是 AI 模型
  82. * @throws ValidationException 文件读不了、缺 word / meaning 列、行数超限
  83. */
  84. public function importToChannel(Channel $channel, string $actorUid, UploadedFile $file): array
  85. {
  86. $this->agents->assertHuman($actorUid);
  87. if (! $this->channels->abilities($channel, $actorUid)['write']) {
  88. throw new AuthorizationException(__('messages.term_forbidden'));
  89. }
  90. return $this->import($actorUid, $file, fn (array $row) => [
  91. 'scope' => DhammaTerm::query()->where('channal', $channel->uid),
  92. 'target' => ['channel' => $channel->uid, 'owner' => $channel->owner_uid, 'language' => $channel->lang],
  93. 'language_editable' => false,
  94. ]);
  95. }
  96. /**
  97. * 导入到 studio:channel_id 列有值的落在那个 channel(必须是这个 studio 的、你能写的),
  98. * 没有的是 studio 级术语(要 language 列)。
  99. *
  100. * @return array{created: int, updated: int, unchanged: int, reindexed: bool, errors: list<array{row: int, message: string}>}
  101. *
  102. * @throws AuthorizationException 不是本人,也不是这个团队的成员;或是 AI 模型
  103. * @throws ValidationException
  104. */
  105. public function importToStudio(string $studioUid, string $actorUid, UploadedFile $file): array
  106. {
  107. $this->agents->assertHuman($actorUid);
  108. if (! $this->groups->can($actorUid, $studioUid, GroupAbilityService::READ)) {
  109. throw new AuthorizationException(__('messages.channel_studio_forbidden'));
  110. }
  111. $channels = [];
  112. return $this->import($actorUid, $file, function (array $row) use ($studioUid, $actorUid, &$channels) {
  113. $channelUid = $row['channel_id'] ?? null;
  114. if ($channelUid === null) {
  115. $language = $row['language'] ?? null;
  116. if ($language === null) {
  117. throw new TermImportRowError(__('messages.term_import_language_required'));
  118. }
  119. return [
  120. 'scope' => DhammaTerm::query()->where('owner', $studioUid)->whereNull('channal')->where('language', $language),
  121. 'target' => ['channel' => null, 'owner' => $studioUid, 'language' => $language],
  122. 'language_editable' => true,
  123. ];
  124. }
  125. $channel = $channels[$channelUid] ??= Channel::where('uid', $channelUid)->first(['uid', 'owner_uid', 'lang', 'status', 'is_system']);
  126. if ($channel === null || $channel->owner_uid !== $studioUid) {
  127. throw new TermImportRowError(__('messages.term_import_channel_not_in_studio', ['channel' => $channelUid]));
  128. }
  129. if (! $this->channels->abilities($channel, $actorUid)['write']) {
  130. throw new TermImportRowError(__('messages.term_forbidden'));
  131. }
  132. return [
  133. 'scope' => DhammaTerm::query()->where('channal', $channel->uid),
  134. 'target' => ['channel' => $channel->uid, 'owner' => $studioUid, 'language' => $channel->lang],
  135. 'language_editable' => false,
  136. ];
  137. });
  138. }
  139. /**
  140. * @param callable(array<string, string|null>): array{scope: Builder<DhammaTerm>, target: array{channel: string|null, owner: string, language: string}, language_editable: bool} $placeOf
  141. * @return array{created: int, updated: int, unchanged: int, reindexed: bool, errors: list<array{row: int, message: string}>}
  142. */
  143. private function import(string $actorUid, UploadedFile $file, callable $placeOf): array
  144. {
  145. $rows = $this->readRows($file);
  146. $actor = ['editor' => $actorUid, 'co_editor' => null, 'scope' => null];
  147. $result = ['created' => 0, 'updated' => 0, 'unchanged' => 0, 'reindexed' => false, 'errors' => []];
  148. $written = [];
  149. foreach ($rows as $line => $row) {
  150. try {
  151. $outcome = $this->importRow($actor, $row, $placeOf($row));
  152. $result[$outcome['status']]++;
  153. if ($outcome['term'] !== null) {
  154. $written[] = $outcome['term'];
  155. }
  156. } catch (TermImportRowError|BusinessException $e) {
  157. $result['errors'][] = ['row' => $line, 'message' => $e->getMessage()];
  158. } catch (ValidationException $e) {
  159. $result['errors'][] = ['row' => $line, 'message' => collect($e->errors())->flatten()->implode(' ')];
  160. } catch (AuthorizationException $e) {
  161. $result['errors'][] = ['row' => $line, 'message' => $e->getMessage() ?: __('messages.term_forbidden')];
  162. }
  163. }
  164. if (count($written) <= self::REINDEX_LIMIT) {
  165. foreach ($written as $term) {
  166. $this->terms->afterWrite($term);
  167. }
  168. $result['reindexed'] = true;
  169. }
  170. return $result;
  171. }
  172. /**
  173. * 一行:新建、修改或没变化。出错抛异常,由调用方记进 errors。
  174. *
  175. * @param array{editor: string, co_editor: null, scope: null} $actor
  176. * @param array<string, string|null> $row
  177. * @param array{scope: Builder<DhammaTerm>, target: array{channel: string|null, owner: string, language: string}, language_editable: bool} $place
  178. * @return array{status: 'created'|'updated'|'unchanged', term: DhammaTerm|null}
  179. */
  180. private function importRow(array $actor, array $row, array $place): array
  181. {
  182. $word = $row['word'] ?? null;
  183. if ($word === null) {
  184. throw new TermImportRowError(__('messages.term_import_word_required'));
  185. }
  186. $tag = $this->terms->normalizeTag($row['tag'] ?? null);
  187. if (($row['id'] ?? null) !== null) {
  188. $term = (clone $place['scope'])->where('guid', $row['id'])->first();
  189. if ($term === null) {
  190. throw new TermImportRowError(__('messages.term_import_not_found', ['id' => $row['id']]));
  191. }
  192. if ($term->word !== $word || $this->terms->normalizeTag($term->tag) !== $tag) {
  193. throw new TermImportRowError(__('messages.term_word_immutable'));
  194. }
  195. if (($row['etag'] ?? null) !== null && $row['etag'] !== $term->etag()) {
  196. throw new TermImportRowError(__('messages.term_import_modified'));
  197. }
  198. } else {
  199. $term = $this->terms->findExisting(clone $place['scope'], $word, $tag);
  200. }
  201. $changes = $this->contentOf($row, $place['language_editable']);
  202. $this->terms->guardRedirect($word, $tag, $changes);
  203. if ($term === null) {
  204. $this->assertCanCreate($actor['editor'], $place['target']);
  205. if (($changes['meaning'] ?? null) === null) {
  206. throw new TermImportRowError(__('messages.term_import_meaning_required'));
  207. }
  208. $created = $this->terms->insert($actor, $changes + ['word' => $word, 'tag' => $tag] + $place['target'], index: false);
  209. return ['status' => 'created', 'term' => $created];
  210. }
  211. if (! $this->terms->abilitiesMany(collect([$term]), $actor['editor'])[$term->guid]['update']) {
  212. throw new TermImportRowError(__('messages.term_forbidden'));
  213. }
  214. if (array_key_exists('meaning', $changes) && $changes['meaning'] === null) {
  215. throw new TermImportRowError(__('messages.term_import_meaning_required'));
  216. }
  217. $changes = array_filter($changes, fn ($value, $field) => $value !== $this->current($term, $field), ARRAY_FILTER_USE_BOTH);
  218. if ($changes === []) {
  219. return ['status' => 'unchanged', 'term' => null];
  220. }
  221. if (array_key_exists('note', $changes) && ! array_key_exists('content_type', $changes)) {
  222. $changes['content_type'] = $term->effectiveContentType();
  223. }
  224. if (! $this->terms->applyChanges($term, $actor, $changes, index: false)) {
  225. throw new TermImportRowError(__('messages.term_import_modified'));
  226. }
  227. return ['status' => 'updated', 'term' => $term->fresh()];
  228. }
  229. /**
  230. * 表里有的内容列 → 要写的值(空格子 = 清空)。quality / content_type 校验取值。
  231. *
  232. * @param array<string, string|null> $row
  233. * @return array<string, string|null>
  234. */
  235. private function contentOf(array $row, bool $languageEditable): array
  236. {
  237. $changes = array_intersect_key($row, array_flip(self::CONTENT));
  238. if ($languageEditable && array_key_exists('language', $row) && $row['language'] !== null) {
  239. $changes['language'] = $row['language'];
  240. }
  241. if (($changes['quality'] ?? null) !== null && ! in_array($changes['quality'], DhammaTerm::QUALITIES, true)) {
  242. throw new TermImportRowError(__('messages.term_import_bad_value', ['field' => 'quality', 'value' => $changes['quality']]));
  243. }
  244. if (array_key_exists('content_type', $changes)) {
  245. if ($changes['content_type'] === null) {
  246. unset($changes['content_type']);
  247. } elseif (! in_array($changes['content_type'], DhammaTerm::CONTENT_TYPES, true)) {
  248. throw new TermImportRowError(__('messages.term_import_bad_value', ['field' => 'content_type', 'value' => $changes['content_type']]));
  249. }
  250. }
  251. return $changes;
  252. }
  253. private function current(DhammaTerm $term, string $field): ?string
  254. {
  255. $value = $field === 'content_type' ? $term->effectiveContentType() : $term->getAttribute($field);
  256. return $value === null || $value === '' ? null : (string) $value;
  257. }
  258. /**
  259. * @param array{channel: string|null, owner: string, language: string} $target
  260. */
  261. private function assertCanCreate(string $actorUid, array $target): void
  262. {
  263. $allowed = $target['channel'] !== null
  264. ? true // channel 的写权限在定位时已经查过
  265. : $this->groups->can($actorUid, $target['owner'], GroupAbilityService::CREATE);
  266. if (! $allowed) {
  267. throw new TermImportRowError(__('messages.term_forbidden'));
  268. }
  269. }
  270. /**
  271. * 读表格:第一行是列名(不分大小写),之后每行按列名取值;整行空的跳过。键是表格里的行号。
  272. *
  273. * @return array<int, array<string, string|null>>
  274. *
  275. * @throws ValidationException
  276. */
  277. private function readRows(UploadedFile $file): array
  278. {
  279. try {
  280. $reader = IOFactory::createReader('Xlsx');
  281. $reader->setReadDataOnly(true);
  282. $sheet = $reader->load($file->getRealPath())->getActiveSheet();
  283. } catch (\Throwable) {
  284. throw ValidationException::withMessages(['file' => __('messages.term_import_unreadable')]);
  285. }
  286. $highestColumn = Coordinate::columnIndexFromString($sheet->getHighestColumn());
  287. $headers = [];
  288. for ($col = 1; $col <= $highestColumn; $col++) {
  289. $name = strtolower(trim((string) $sheet->getCell([$col, 1])->getValue()));
  290. if (in_array($name, self::COLUMNS, true)) {
  291. $headers[$col] = $name;
  292. }
  293. }
  294. if (! in_array('word', $headers, true) || ! in_array('meaning', $headers, true)) {
  295. throw ValidationException::withMessages(['file' => __('messages.term_import_header_required')]);
  296. }
  297. $rows = [];
  298. $highestRow = $sheet->getHighestDataRow();
  299. if ($highestRow - 1 > self::MAX_ROWS) {
  300. throw ValidationException::withMessages(['file' => __('messages.term_import_too_many', ['max' => self::MAX_ROWS])]);
  301. }
  302. for ($line = 2; $line <= $highestRow; $line++) {
  303. $row = [];
  304. foreach ($headers as $col => $name) {
  305. $value = trim((string) $sheet->getCell([$col, $line])->getValue());
  306. $row[$name] = $value === '' ? null : $value;
  307. }
  308. if (array_filter($row, fn ($value) => $value !== null) === []) {
  309. continue;
  310. }
  311. $rows[$line] = $row;
  312. }
  313. return $rows;
  314. }
  315. }