readme-guide 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3575 @@
1
+ {
2
+ "version": 1,
3
+ "severities": {
4
+ "error": {
5
+ "zh-TW": "錯誤",
6
+ "en": "Error"
7
+ },
8
+ "warning": {
9
+ "zh-TW": "警告",
10
+ "en": "Warning"
11
+ }
12
+ },
13
+ "statuses": {
14
+ "implemented": {
15
+ "zh-TW": "已實作",
16
+ "en": "Implemented"
17
+ },
18
+ "planned": {
19
+ "zh-TW": "規劃中",
20
+ "en": "Planned"
21
+ }
22
+ },
23
+ "categories": [
24
+ {
25
+ "id": "structure",
26
+ "name": {
27
+ "zh-TW": "結構",
28
+ "en": "Structure"
29
+ }
30
+ },
31
+ {
32
+ "id": "unfinished",
33
+ "name": {
34
+ "zh-TW": "還沒填完",
35
+ "en": "Unfinished"
36
+ }
37
+ },
38
+ {
39
+ "id": "commands",
40
+ "name": {
41
+ "zh-TW": "指令",
42
+ "en": "Commands"
43
+ }
44
+ },
45
+ {
46
+ "id": "versions",
47
+ "name": {
48
+ "zh-TW": "版本",
49
+ "en": "Versions"
50
+ }
51
+ },
52
+ {
53
+ "id": "env",
54
+ "name": {
55
+ "zh-TW": "環境變數",
56
+ "en": "Environment variables"
57
+ }
58
+ },
59
+ {
60
+ "id": "security",
61
+ "name": {
62
+ "zh-TW": "安全",
63
+ "en": "Security"
64
+ }
65
+ },
66
+ {
67
+ "id": "images",
68
+ "name": {
69
+ "zh-TW": "圖片",
70
+ "en": "Images"
71
+ }
72
+ },
73
+ {
74
+ "id": "links",
75
+ "name": {
76
+ "zh-TW": "連結",
77
+ "en": "Links"
78
+ }
79
+ },
80
+ {
81
+ "id": "license",
82
+ "name": {
83
+ "zh-TW": "授權與作者",
84
+ "en": "License and author"
85
+ }
86
+ },
87
+ {
88
+ "id": "language",
89
+ "name": {
90
+ "zh-TW": "語言",
91
+ "en": "Language"
92
+ }
93
+ },
94
+ {
95
+ "id": "ai-readability",
96
+ "name": {
97
+ "zh-TW": "AI 讀得懂",
98
+ "en": "Readable for AI"
99
+ }
100
+ },
101
+ {
102
+ "id": "type-specific",
103
+ "name": {
104
+ "zh-TW": "類型專屬",
105
+ "en": "Type-specific"
106
+ }
107
+ }
108
+ ],
109
+ "rules": [
110
+ {
111
+ "id": "STR001",
112
+ "block": null,
113
+ "category": "structure",
114
+ "severity": "warning",
115
+ "types": [
116
+ "web-app",
117
+ "course-example",
118
+ "portfolio",
119
+ "backend-api"
120
+ ],
121
+ "needsProject": true,
122
+ "status": "planned",
123
+ "title": {
124
+ "zh-TW": "檔名用 README.md",
125
+ "en": "Name the file README.md"
126
+ },
127
+ "description": {
128
+ "zh-TW": "專案根目錄的說明檔叫 README.md(全大寫加 .md),GitHub 和各種工具都認這個名字。",
129
+ "en": "Call the file at the project root README.md (capital letters plus .md). GitHub and most tools look for that exact name."
130
+ },
131
+ "fix": {
132
+ "zh-TW": "把檔名改成 README.md。",
133
+ "en": "Rename the file to README.md."
134
+ },
135
+ "messages": {}
136
+ },
137
+ {
138
+ "id": "STR002",
139
+ "block": "title",
140
+ "category": "structure",
141
+ "severity": "error",
142
+ "types": [
143
+ "web-app",
144
+ "course-example",
145
+ "portfolio",
146
+ "backend-api"
147
+ ],
148
+ "needsProject": false,
149
+ "status": "implemented",
150
+ "title": {
151
+ "zh-TW": "第一行是唯一的一級標題",
152
+ "en": "The first line is the only top-level heading"
153
+ },
154
+ "description": {
155
+ "zh-TW": "專案名稱用 `# 專案名稱` 寫在最上面,整份文件只能有這一個一級標題。人一打開就知道這是什麼,AI 和工具也靠它找到專案名稱。",
156
+ "en": "Put the project name at the very top as `# Project name`, and use only one top-level heading in the whole file. Readers see what it is right away, and AI and tools rely on it to find the project name."
157
+ },
158
+ "fix": {
159
+ "zh-TW": "把徽章、圖片和說明移到標題下面;其他一級標題改成二級標題(`##`)。",
160
+ "en": "Move badges, images and notes below the title, and turn any other top-level heading into a second-level heading (`##`)."
161
+ },
162
+ "messages": {
163
+ "notFirst": {
164
+ "zh-TW": "第一行不是一級標題,標題前面還有其他內容",
165
+ "en": "Something comes before the top-level heading"
166
+ },
167
+ "missing": {
168
+ "zh-TW": "整份文件沒有一級標題(`# 專案名稱`)",
169
+ "en": "There is no top-level heading (`# Project name`)"
170
+ },
171
+ "extra": {
172
+ "zh-TW": "這是第 {count} 個一級標題,一級標題只能有一個",
173
+ "en": "This is top-level heading number {count}; only one is allowed"
174
+ }
175
+ },
176
+ "example": {
177
+ "zh-TW": {
178
+ "before": [
179
+ "![巷口早餐店](docs/images/banner.png)",
180
+ "",
181
+ "# 巷口早餐店|線上點餐"
182
+ ],
183
+ "after": [
184
+ "# 巷口早餐店|線上點餐"
185
+ ]
186
+ },
187
+ "en": {
188
+ "before": [
189
+ "![Corner Breakfast](docs/images/banner.png)",
190
+ "",
191
+ "# Corner Breakfast"
192
+ ],
193
+ "after": [
194
+ "# Corner Breakfast"
195
+ ]
196
+ }
197
+ }
198
+ },
199
+ {
200
+ "id": "STR003",
201
+ "block": "title",
202
+ "category": "structure",
203
+ "severity": "error",
204
+ "types": [
205
+ "web-app",
206
+ "course-example",
207
+ "portfolio",
208
+ "backend-api"
209
+ ],
210
+ "needsProject": false,
211
+ "status": "implemented",
212
+ "title": {
213
+ "zh-TW": "標題下面要有一句話說明",
214
+ "en": "A one-line description under the title"
215
+ },
216
+ "description": {
217
+ "zh-TW": "一級標題的下一行,用一句話說這個專案做什麼、給誰用。讀者用幾秒鐘決定要不要往下看,AI 也會拿這句當專案的摘要。",
218
+ "en": "On the line after the title, say in one sentence what the project does and who it is for. Readers decide in seconds whether to keep reading, and AI uses this line as the project summary."
219
+ },
220
+ "fix": {
221
+ "zh-TW": "在標題下一行補一句純文字的說明,例如「讓客人用手機先點餐、到店直接取餐的網頁」。",
222
+ "en": "Add one plain sentence right under the title, for example \"A web page where customers order on their phone and pick up in the shop.\""
223
+ },
224
+ "messages": {
225
+ "missing": {
226
+ "zh-TW": "標題下面沒有一句話說明",
227
+ "en": "No one-line description under the title"
228
+ }
229
+ },
230
+ "example": {
231
+ "zh-TW": {
232
+ "before": [
233
+ "# 巷口早餐店|線上點餐",
234
+ "",
235
+ "狀態:維護中"
236
+ ],
237
+ "after": [
238
+ "# 巷口早餐店|線上點餐",
239
+ "",
240
+ "讓客人用手機先點餐、到店直接取餐的網頁。",
241
+ "",
242
+ "狀態:維護中"
243
+ ]
244
+ },
245
+ "en": {
246
+ "before": [
247
+ "# Corner Breakfast",
248
+ "",
249
+ "Status: maintained"
250
+ ],
251
+ "after": [
252
+ "# Corner Breakfast",
253
+ "",
254
+ "A web page where customers order breakfast on their phone and pick it up at the shop.",
255
+ "",
256
+ "Status: maintained"
257
+ ]
258
+ }
259
+ }
260
+ },
261
+ {
262
+ "id": "STR004",
263
+ "block": "title",
264
+ "category": "structure",
265
+ "severity": "warning",
266
+ "types": [
267
+ "web-app",
268
+ "course-example",
269
+ "portfolio",
270
+ "backend-api"
271
+ ],
272
+ "needsProject": false,
273
+ "status": "implemented",
274
+ "title": {
275
+ "zh-TW": "寫出專案狀態",
276
+ "en": "State the project status"
277
+ },
278
+ "description": {
279
+ "zh-TW": "在一句話說明下面加一行狀態,例如「狀態:維護中」。讀者和 AI 才知道這個專案還有沒有人管、能不能拿來用。",
280
+ "en": "Add one line under the description with the status, for example \"Status: maintained\". Readers and AI then know whether anyone still looks after it."
281
+ },
282
+ "fix": {
283
+ "zh-TW": "在一句話說明下一行加一行「狀態:」開頭的文字,從開發中、已完成、維護中、練習用、不再維護選一個。",
284
+ "en": "Add a line starting with \"Status:\" under the description, choosing one of: in development, completed, maintained, practice project, no longer maintained."
285
+ },
286
+ "messages": {
287
+ "missing": {
288
+ "zh-TW": "沒有寫專案狀態(例如「狀態:維護中」)",
289
+ "en": "No project status (for example \"Status: maintained\")"
290
+ }
291
+ },
292
+ "example": {
293
+ "zh-TW": {
294
+ "before": [
295
+ "讓客人用手機先點餐、到店直接取餐的網頁。"
296
+ ],
297
+ "after": [
298
+ "讓客人用手機先點餐、到店直接取餐的網頁。",
299
+ "",
300
+ "狀態:維護中"
301
+ ]
302
+ },
303
+ "en": {
304
+ "before": [
305
+ "A web page where customers order breakfast on their phone and pick it up at the shop."
306
+ ],
307
+ "after": [
308
+ "A web page where customers order breakfast on their phone and pick it up at the shop.",
309
+ "",
310
+ "Status: maintained"
311
+ ]
312
+ }
313
+ }
314
+ },
315
+ {
316
+ "id": "STR005",
317
+ "block": null,
318
+ "category": "structure",
319
+ "severity": "warning",
320
+ "types": [
321
+ "web-app",
322
+ "course-example",
323
+ "portfolio",
324
+ "backend-api"
325
+ ],
326
+ "needsProject": false,
327
+ "status": "implemented",
328
+ "title": {
329
+ "zh-TW": "標題不要跳級",
330
+ "en": "Do not skip heading levels"
331
+ },
332
+ "description": {
333
+ "zh-TW": "標題要一層一層往下,二級(`##`)下面接三級(`###`),不要直接跳到四級。跳級會讓人和 AI 看不出段落之間的上下關係。",
334
+ "en": "Go down one level at a time: a second-level heading (`##`) is followed by a third-level one (`###`), never straight to the fourth. Skipping levels hides how sections relate, for people and for AI."
335
+ },
336
+ "fix": {
337
+ "zh-TW": "把這個標題改成只比上一個標題多一層。",
338
+ "en": "Make this heading only one level deeper than the one before it."
339
+ },
340
+ "messages": {
341
+ "skip": {
342
+ "zh-TW": "標題從第 {from} 級直接跳到第 {to} 級",
343
+ "en": "Heading jumps from level {from} to level {to}"
344
+ }
345
+ },
346
+ "example": {
347
+ "zh-TW": {
348
+ "before": [
349
+ "## 安裝與執行",
350
+ "",
351
+ "#### 環境需求"
352
+ ],
353
+ "after": [
354
+ "## 安裝與執行",
355
+ "",
356
+ "### 環境需求"
357
+ ]
358
+ },
359
+ "en": {
360
+ "before": [
361
+ "## Getting Started",
362
+ "",
363
+ "#### Requirements"
364
+ ],
365
+ "after": [
366
+ "## Getting Started",
367
+ "",
368
+ "### Requirements"
369
+ ]
370
+ }
371
+ }
372
+ },
373
+ {
374
+ "id": "STR006",
375
+ "block": null,
376
+ "category": "structure",
377
+ "severity": "error",
378
+ "types": [
379
+ "web-app",
380
+ "course-example",
381
+ "portfolio",
382
+ "backend-api"
383
+ ],
384
+ "needsProject": false,
385
+ "status": "implemented",
386
+ "title": {
387
+ "zh-TW": "依專案類型,必填的章節都要有",
388
+ "en": "Every section the project type requires is there"
389
+ },
390
+ "description": {
391
+ "zh-TW": "每種專案類型都有一定要寫的章節,例如網頁專案要有「功能」「使用技術」「安裝與執行」底下的「環境需求」與「安裝步驟」、「作者與聯絡」。標題要用指南的名稱或可接受的別名,人和 AI 才找得到。「授權」只有公開的專案要寫,由另一條規則(LIC001)檢查;後端 API 的「API 文件」也由專門的規則(TYPE-API001)檢查。",
392
+ "en": "Each project type has sections it must include; a web app, for example, needs Features, Tech Stack, Getting Started with Requirements and Installation, and Author. Use the guide's heading names (or an accepted alternative) so people and AI can find them. A License section is only needed for public projects and is checked by a separate rule (LIC001); a backend API's API Documentation is checked by TYPE-API001."
393
+ },
394
+ "fix": {
395
+ "zh-TW": "照指南的標題名稱補上缺的章節;如果其實有寫、只是標題名稱不一樣,改成指南的名稱。",
396
+ "en": "Add the missing section using the guide's heading name. If the content is there under a different heading, rename the heading."
397
+ },
398
+ "messages": {
399
+ "missing": {
400
+ "zh-TW": "缺少「{section}」章節({type}必填)",
401
+ "en": "Missing the \"{section}\" section (required for the {type} type)"
402
+ }
403
+ },
404
+ "example": {
405
+ "zh-TW": {
406
+ "before": [],
407
+ "after": [
408
+ "## 使用技術",
409
+ "",
410
+ "- Vue 3",
411
+ "- Vite 6",
412
+ "- Vitest 3"
413
+ ]
414
+ },
415
+ "en": {
416
+ "before": [],
417
+ "after": [
418
+ "## Tech Stack",
419
+ "",
420
+ "- Vue 3",
421
+ "- Vite 6",
422
+ "- Vitest 3"
423
+ ]
424
+ }
425
+ }
426
+ },
427
+ {
428
+ "id": "STR007",
429
+ "block": null,
430
+ "category": "structure",
431
+ "severity": "warning",
432
+ "types": [
433
+ "web-app",
434
+ "course-example",
435
+ "portfolio",
436
+ "backend-api"
437
+ ],
438
+ "needsProject": false,
439
+ "status": "implemented",
440
+ "title": {
441
+ "zh-TW": "章節照八塊的順序排",
442
+ "en": "Sections follow the order of the eight blocks"
443
+ },
444
+ "description": {
445
+ "zh-TW": "章節的順序是固定的:先回答「這是什麼」,再來「怎麼跑起來」,最後是「怎麼改、能不能用」。順序固定,人掃得快,AI 也讀得準。",
446
+ "en": "The order is fixed: first \"What is it?\", then \"How do I run it?\", then \"How do I change it, and may I use it?\". A predictable order is quick for people to scan and easy for AI to read."
447
+ },
448
+ "fix": {
449
+ "zh-TW": "照八塊的順序調整章節的位置。",
450
+ "en": "Move the section so the blocks appear in order."
451
+ },
452
+ "messages": {
453
+ "order": {
454
+ "zh-TW": "「{heading}」(第 {number} 塊)應該放在「{before}」(第 {beforeNumber} 塊)前面",
455
+ "en": "\"{heading}\" (block {number}) should come before \"{before}\" (block {beforeNumber})"
456
+ }
457
+ },
458
+ "example": {
459
+ "zh-TW": {
460
+ "before": [
461
+ "## 功能",
462
+ "…",
463
+ "## 畫面",
464
+ "…"
465
+ ],
466
+ "after": [
467
+ "## 畫面",
468
+ "…",
469
+ "## 功能",
470
+ "…"
471
+ ]
472
+ },
473
+ "en": {
474
+ "before": [
475
+ "## Features",
476
+ "…",
477
+ "## Screenshots",
478
+ "…"
479
+ ],
480
+ "after": [
481
+ "## Screenshots",
482
+ "…",
483
+ "## Features",
484
+ "…"
485
+ ]
486
+ }
487
+ }
488
+ },
489
+ {
490
+ "id": "STR008",
491
+ "block": "license",
492
+ "category": "structure",
493
+ "severity": "warning",
494
+ "types": [
495
+ "web-app",
496
+ "course-example",
497
+ "portfolio",
498
+ "backend-api"
499
+ ],
500
+ "needsProject": false,
501
+ "status": "implemented",
502
+ "title": {
503
+ "zh-TW": "「授權」放在最後",
504
+ "en": "The license section comes last"
505
+ },
506
+ "description": {
507
+ "zh-TW": "「授權」固定是最後一個章節,想知道能不能用的人直接捲到最下面就找得到。",
508
+ "en": "The license is always the last section, so anyone asking \"may I use this?\" just scrolls to the bottom."
509
+ },
510
+ "fix": {
511
+ "zh-TW": "把「授權」移到最後;「致謝」「貢獻方式」這類章節放在它前面。",
512
+ "en": "Move the license section to the end; put sections such as Acknowledgments or Contributing before it."
513
+ },
514
+ "messages": {
515
+ "notLast": {
516
+ "zh-TW": "「授權」後面還有「{heading}」,授權要放在最後",
517
+ "en": "\"{heading}\" comes after the license; the license section goes last"
518
+ }
519
+ },
520
+ "example": {
521
+ "zh-TW": {
522
+ "before": [
523
+ "## 授權",
524
+ "…",
525
+ "## 作者與聯絡",
526
+ "…"
527
+ ],
528
+ "after": [
529
+ "## 作者與聯絡",
530
+ "…",
531
+ "## 授權",
532
+ "…"
533
+ ]
534
+ },
535
+ "en": {
536
+ "before": [
537
+ "## License",
538
+ "…",
539
+ "## Author",
540
+ "…"
541
+ ],
542
+ "after": [
543
+ "## Author",
544
+ "…",
545
+ "## License",
546
+ "…"
547
+ ]
548
+ }
549
+ }
550
+ },
551
+ {
552
+ "id": "STR009",
553
+ "block": null,
554
+ "category": "structure",
555
+ "severity": "error",
556
+ "types": [
557
+ "web-app",
558
+ "course-example",
559
+ "portfolio",
560
+ "backend-api"
561
+ ],
562
+ "needsProject": false,
563
+ "status": "implemented",
564
+ "title": {
565
+ "zh-TW": "不要留空的章節",
566
+ "en": "No empty sections"
567
+ },
568
+ "description": {
569
+ "zh-TW": "有標題就要有內容。空的章節會讓人以為漏寫了,AI 也可能自己亂補。",
570
+ "en": "A heading needs content under it. An empty section looks like something is missing, and AI may fill the gap with guesses."
571
+ },
572
+ "fix": {
573
+ "zh-TW": "補上內容,或把這個標題刪掉。",
574
+ "en": "Add the content or delete the heading."
575
+ },
576
+ "messages": {
577
+ "empty": {
578
+ "zh-TW": "「{heading}」底下沒有內容",
579
+ "en": "\"{heading}\" has no content"
580
+ }
581
+ },
582
+ "example": {
583
+ "zh-TW": {
584
+ "before": [
585
+ "### 執行測試"
586
+ ],
587
+ "after": [
588
+ "### 執行測試",
589
+ "",
590
+ "```bash",
591
+ "pnpm test",
592
+ "```"
593
+ ]
594
+ },
595
+ "en": {
596
+ "before": [
597
+ "### Running Tests"
598
+ ],
599
+ "after": [
600
+ "### Running Tests",
601
+ "",
602
+ "```bash",
603
+ "pnpm test",
604
+ "```"
605
+ ]
606
+ }
607
+ }
608
+ },
609
+ {
610
+ "id": "STR010",
611
+ "block": null,
612
+ "category": "unfinished",
613
+ "severity": "error",
614
+ "types": [
615
+ "web-app",
616
+ "course-example",
617
+ "portfolio",
618
+ "backend-api"
619
+ ],
620
+ "needsProject": false,
621
+ "status": "implemented",
622
+ "title": {
623
+ "zh-TW": "不要留下舊範本的文字",
624
+ "en": "No leftover text from an old template"
625
+ },
626
+ "description": {
627
+ "zh-TW": "從範本複製來的提醒(「請斟酌」「請務必依據你的專案來調整內容」)、假的 email(example@example.com)、單獨一行的「...」都要刪掉或換成真的內容,不然讀者和 AI 分不出哪些是真的。",
628
+ "en": "Reminders copied from a template (\"adjust this to your project\"), fake emails such as example@example.com and lines with only \"...\" must be removed or replaced with real content; otherwise readers and AI cannot tell what is real."
629
+ },
630
+ "fix": {
631
+ "zh-TW": "換成專案真正的內容,或整段刪掉。",
632
+ "en": "Replace it with the project's real content, or delete it."
633
+ },
634
+ "messages": {
635
+ "phrase": {
636
+ "zh-TW": "還留著範本的文字「{text}」",
637
+ "en": "Template text is still here: \"{text}\""
638
+ },
639
+ "ellipsis": {
640
+ "zh-TW": "單獨一行的「...」,看起來是範本還沒寫完的地方",
641
+ "en": "A line with only \"...\", which looks like an unfinished template"
642
+ }
643
+ },
644
+ "example": {
645
+ "zh-TW": {
646
+ "before": [
647
+ "- [x] 依分類瀏覽菜單與價格",
648
+ "- [x] 把餐點加進購物車、選擇取餐時間後送出訂單",
649
+ "..."
650
+ ],
651
+ "after": [
652
+ "- [x] 依分類瀏覽菜單與價格",
653
+ "- [x] 把餐點加進購物車、選擇取餐時間後送出訂單"
654
+ ]
655
+ },
656
+ "en": {
657
+ "before": [
658
+ "- [x] Browse the menu and prices by category",
659
+ "- [x] Add dishes to the cart, pick a pickup time and place the order",
660
+ "..."
661
+ ],
662
+ "after": [
663
+ "- [x] Browse the menu and prices by category",
664
+ "- [x] Add dishes to the cart, pick a pickup time and place the order"
665
+ ]
666
+ }
667
+ }
668
+ },
669
+ {
670
+ "id": "STR011",
671
+ "block": null,
672
+ "category": "structure",
673
+ "severity": "warning",
674
+ "types": [
675
+ "web-app",
676
+ "course-example",
677
+ "portfolio",
678
+ "backend-api"
679
+ ],
680
+ "needsProject": false,
681
+ "status": "planned",
682
+ "title": {
683
+ "zh-TW": "同一層的標題不要重複",
684
+ "en": "No duplicate headings at the same level"
685
+ },
686
+ "description": {
687
+ "zh-TW": "同一個章節底下出現兩個一樣的標題,連結和 AI 都分不出是哪一個。",
688
+ "en": "Two identical headings under the same parent make links and AI unable to tell them apart."
689
+ },
690
+ "fix": {
691
+ "zh-TW": "合併成一個,或改成能區分的名稱。",
692
+ "en": "Merge them or give them distinct names."
693
+ },
694
+ "messages": {}
695
+ },
696
+ {
697
+ "id": "STR012",
698
+ "block": null,
699
+ "category": "structure",
700
+ "severity": "warning",
701
+ "types": [
702
+ "web-app",
703
+ "course-example",
704
+ "portfolio",
705
+ "backend-api"
706
+ ],
707
+ "needsProject": false,
708
+ "status": "planned",
709
+ "title": {
710
+ "zh-TW": "不要用粗體字代替標題",
711
+ "en": "Do not use bold text as a heading"
712
+ },
713
+ "description": {
714
+ "zh-TW": "整行粗體看起來像標題,但它不是,目錄和 AI 都抓不到。",
715
+ "en": "A bold line looks like a heading but is not one, so outlines and AI miss it."
716
+ },
717
+ "fix": {
718
+ "zh-TW": "改成真正的標題(`###`)。",
719
+ "en": "Turn it into a real heading (`###`)."
720
+ },
721
+ "messages": {}
722
+ },
723
+ {
724
+ "id": "STR013",
725
+ "block": null,
726
+ "category": "structure",
727
+ "severity": "warning",
728
+ "types": [
729
+ "web-app",
730
+ "course-example",
731
+ "portfolio",
732
+ "backend-api"
733
+ ],
734
+ "needsProject": false,
735
+ "status": "planned",
736
+ "title": {
737
+ "zh-TW": "手寫目錄的連結要對得到標題",
738
+ "en": "A hand-written table of contents points at real headings"
739
+ },
740
+ "description": {
741
+ "zh-TW": "README 超過 100 行可以加目錄;有加目錄,每個連結都要連得到對應的標題。",
742
+ "en": "A README longer than 100 lines may have a table of contents; if it does, every entry must reach its heading."
743
+ },
744
+ "fix": {
745
+ "zh-TW": "更新目錄,讓每個連結都對到現在的標題。",
746
+ "en": "Update the table of contents to match the current headings."
747
+ },
748
+ "messages": {}
749
+ },
750
+ {
751
+ "id": "STR014",
752
+ "block": "title",
753
+ "category": "structure",
754
+ "severity": "warning",
755
+ "types": [
756
+ "web-app",
757
+ "course-example",
758
+ "portfolio",
759
+ "backend-api"
760
+ ],
761
+ "needsProject": false,
762
+ "status": "implemented",
763
+ "title": {
764
+ "zh-TW": "一句話說明用純文字,不要太長",
765
+ "en": "Keep the one-line description plain and short"
766
+ },
767
+ "description": {
768
+ "zh-TW": "一句話說明不要用引用格式(`>` 開頭),中文 60 字、英文 120 個字元以內。引用格式在 GitHub 上看起來像在引述別人,太長就不是一句話了。",
769
+ "en": "Do not write the description as a quote (starting with `>`), and keep it within 120 characters in English or 60 in Chinese. A quote looks like someone else's words on GitHub, and a long one stops being one line."
770
+ },
771
+ "fix": {
772
+ "zh-TW": "拿掉開頭的 `>`;太長就只留「做什麼、給誰用」,其他移到「功能」。",
773
+ "en": "Remove the leading `>`. If it is too long, keep only what it does and who it is for, and move the rest to Features."
774
+ },
775
+ "messages": {
776
+ "quote": {
777
+ "zh-TW": "一句話說明用了引用格式(`>`)",
778
+ "en": "The one-line description is written as a quote (`>`)"
779
+ },
780
+ "tooLong": {
781
+ "zh-TW": "一句話說明有 {length} 個字,建議在 {max} 個字以內",
782
+ "en": "The one-line description is {length} characters long; keep it within {max}"
783
+ }
784
+ },
785
+ "example": {
786
+ "zh-TW": {
787
+ "before": [
788
+ "> 讓客人用手機先點餐、到店直接取餐的網頁。"
789
+ ],
790
+ "after": [
791
+ "讓客人用手機先點餐、到店直接取餐的網頁。"
792
+ ]
793
+ },
794
+ "en": {
795
+ "before": [
796
+ "> A web page where customers order breakfast on their phone and pick it up at the shop."
797
+ ],
798
+ "after": [
799
+ "A web page where customers order breakfast on their phone and pick it up at the shop."
800
+ ]
801
+ }
802
+ }
803
+ },
804
+ {
805
+ "id": "STR015",
806
+ "block": null,
807
+ "category": "unfinished",
808
+ "severity": "error",
809
+ "types": [
810
+ "web-app",
811
+ "course-example",
812
+ "portfolio",
813
+ "backend-api"
814
+ ],
815
+ "needsProject": false,
816
+ "status": "implemented",
817
+ "title": {
818
+ "zh-TW": "範本的待填文字都要換掉",
819
+ "en": "Every template blank is filled in"
820
+ },
821
+ "description": {
822
+ "zh-TW": "指南的範本用 `{{請填:…}}` 標出要填的地方,成品裡一個都不能留。說明只有刪節號的 `{{請填:…}}` 是在介紹這個寫法本身,不算還沒填。",
823
+ "en": "The guide's templates mark every blank with `{{FILL: …}}`. None may be left in the finished README. A blank whose description is only an ellipsis, such as `{{FILL: …}}`, is talking about the syntax itself and is not reported."
824
+ },
825
+ "fix": {
826
+ "zh-TW": "換成專案真正的內容;查不到的資料先問專案負責人,不要自己編。用不到的段落就整段刪掉。",
827
+ "en": "Replace it with the project's real content. Ask the project owner about anything you cannot find instead of making it up, and delete parts that do not apply."
828
+ },
829
+ "messages": {
830
+ "placeholder": {
831
+ "zh-TW": "還有沒填的地方:{text}",
832
+ "en": "Still to fill in: {text}"
833
+ }
834
+ },
835
+ "example": {
836
+ "zh-TW": {
837
+ "before": [
838
+ "[巷口早餐店線上點餐]({{請填:線上網址}})"
839
+ ],
840
+ "after": [
841
+ "[巷口早餐店線上點餐](https://zaocan.github.io/breakfast-order/)"
842
+ ]
843
+ },
844
+ "en": {
845
+ "before": [
846
+ "[Corner Breakfast online ordering]({{FILL:live-url}})"
847
+ ],
848
+ "after": [
849
+ "[Corner Breakfast online ordering](https://zaocan.github.io/breakfast-order/)"
850
+ ]
851
+ }
852
+ }
853
+ },
854
+ {
855
+ "id": "STR016",
856
+ "block": "structure",
857
+ "category": "structure",
858
+ "severity": "warning",
859
+ "types": [
860
+ "web-app",
861
+ "course-example",
862
+ "portfolio",
863
+ "backend-api"
864
+ ],
865
+ "needsProject": true,
866
+ "status": "implemented",
867
+ "title": {
868
+ "zh-TW": "「資料夾結構」列出的項目要存在",
869
+ "en": "Folders listed in Project Structure exist"
870
+ },
871
+ "description": {
872
+ "zh-TW": "「資料夾結構」列了專案裡根本沒有的資料夾或檔案,多半是從範本或舊版本照抄的,照著找會找不到。只檢查最上層、結尾是 `/` 的資料夾或有副檔名的檔案;看不懂的寫法、`node_modules` 這類不會放進 repo 的資料夾、有 `*` 或 `…` 的項目都不檢查。",
873
+ "en": "Listing folders or files that do not exist, usually copied from a template or an older version, sends readers looking for nothing. Only top-level entries ending in `/` or with a file extension are checked; unfamiliar layouts, folders that never go into the repository such as `node_modules`, and entries with `*` or `…` are skipped."
874
+ },
875
+ "fix": {
876
+ "zh-TW": "刪掉不存在的項目,或改成專案裡真正的名稱。",
877
+ "en": "Remove entries that do not exist, or change them to the real names."
878
+ },
879
+ "messages": {
880
+ "missing": {
881
+ "zh-TW": "「資料夾結構」列了 {name},專案裡找不到",
882
+ "en": "Project Structure lists {name}, but it does not exist in the project"
883
+ }
884
+ },
885
+ "example": {
886
+ "zh-TW": {
887
+ "before": [
888
+ "```text",
889
+ "src/ 畫面與程式",
890
+ "views/ 頁面",
891
+ "```"
892
+ ],
893
+ "after": [
894
+ "```text",
895
+ "src/ 頁面、元件與呼叫 API 的函式",
896
+ "public/ 不經過打包、直接提供的檔案",
897
+ "docs/ README 用的截圖",
898
+ "```"
899
+ ]
900
+ },
901
+ "en": {
902
+ "before": [
903
+ "```text",
904
+ "src/ Screens and code",
905
+ "views/ Pages",
906
+ "```"
907
+ ],
908
+ "after": [
909
+ "```text",
910
+ "src/ Pages, components and API calls",
911
+ "public/ Files served as they are, without bundling",
912
+ "docs/ Screenshots used in this README",
913
+ "```"
914
+ ]
915
+ }
916
+ }
917
+ },
918
+ {
919
+ "id": "STR017",
920
+ "block": null,
921
+ "category": "structure",
922
+ "severity": "warning",
923
+ "types": [
924
+ "web-app",
925
+ "course-example",
926
+ "portfolio",
927
+ "backend-api"
928
+ ],
929
+ "needsProject": false,
930
+ "status": "planned",
931
+ "title": {
932
+ "zh-TW": "標題用指南的正式名稱",
933
+ "en": "Headings use the guide's official names"
934
+ },
935
+ "description": {
936
+ "zh-TW": "「專案技術」「資料夾說明」這類別名檢查工具認得,但每份 README 用一樣的標題,人和 AI 找起來最快。內部專案常見的「維護團隊」「負責人」等寫法是否也要提醒,實作前再決定。",
937
+ "en": "Alternatives such as \"Built With\" or \"Folder Structure\" are recognized, but the same headings in every README are fastest to scan for people and AI. Whether to flag internal-project alternatives such as \"Owners\" will be decided before this is implemented."
938
+ },
939
+ "fix": {
940
+ "zh-TW": "把標題改成指南的正式名稱,例如「專案技術」改成「使用技術」。",
941
+ "en": "Rename the heading to the guide's official name, for example \"Built With\" to \"Tech Stack\"."
942
+ },
943
+ "messages": {}
944
+ },
945
+ {
946
+ "id": "CMD001",
947
+ "block": "install",
948
+ "category": "commands",
949
+ "severity": "error",
950
+ "types": [
951
+ "web-app",
952
+ "course-example",
953
+ "portfolio",
954
+ "backend-api"
955
+ ],
956
+ "needsProject": false,
957
+ "status": "planned",
958
+ "title": {
959
+ "zh-TW": "「安裝與執行」至少有一個指令區塊",
960
+ "en": "Getting Started has at least one command block"
961
+ },
962
+ "description": {
963
+ "zh-TW": "安裝與啟動的指令要放在程式碼區塊裡,讀者才能直接複製,AI 才知道要執行什麼。",
964
+ "en": "Install and start commands belong in code blocks so readers can copy them and AI knows exactly what to run."
965
+ },
966
+ "fix": {
967
+ "zh-TW": "把指令放進 ```bash 區塊。",
968
+ "en": "Put the commands in a ```bash block."
969
+ },
970
+ "messages": {}
971
+ },
972
+ {
973
+ "id": "CMD002",
974
+ "block": null,
975
+ "relatedBlocks": [
976
+ "install"
977
+ ],
978
+ "category": "commands",
979
+ "severity": "warning",
980
+ "types": [
981
+ "web-app",
982
+ "course-example",
983
+ "portfolio",
984
+ "backend-api"
985
+ ],
986
+ "needsProject": false,
987
+ "status": "implemented",
988
+ "title": {
989
+ "zh-TW": "程式碼區塊要標語言",
990
+ "en": "Code blocks name their language"
991
+ },
992
+ "description": {
993
+ "zh-TW": "程式碼區塊開頭的 ``` 後面寫上語言(`bash`、`json`、`text`),GitHub 才會正確上色,AI 也分得出哪些是要執行的指令。",
994
+ "en": "Write the language after the opening ``` (`bash`, `json`, `text`) so GitHub colors it correctly and AI can tell commands from other text."
995
+ },
996
+ "fix": {
997
+ "zh-TW": "在 ``` 後面加上語言,例如 ```bash;純文字或執行結果用 ```text。",
998
+ "en": "Add the language after ```, for example ```bash; use ```text for plain output."
999
+ },
1000
+ "messages": {
1001
+ "missing": {
1002
+ "zh-TW": "程式碼區塊沒有標語言",
1003
+ "en": "Code block has no language"
1004
+ }
1005
+ },
1006
+ "example": {
1007
+ "zh-TW": {
1008
+ "before": [
1009
+ "```",
1010
+ "pnpm test",
1011
+ "```"
1012
+ ],
1013
+ "after": [
1014
+ "```bash",
1015
+ "pnpm test",
1016
+ "```"
1017
+ ]
1018
+ },
1019
+ "en": {
1020
+ "before": [
1021
+ "```",
1022
+ "pnpm test",
1023
+ "```"
1024
+ ],
1025
+ "after": [
1026
+ "```bash",
1027
+ "pnpm test",
1028
+ "```"
1029
+ ]
1030
+ }
1031
+ }
1032
+ },
1033
+ {
1034
+ "id": "CMD003",
1035
+ "block": null,
1036
+ "relatedBlocks": [
1037
+ "install"
1038
+ ],
1039
+ "category": "commands",
1040
+ "severity": "warning",
1041
+ "types": [
1042
+ "web-app",
1043
+ "course-example",
1044
+ "portfolio",
1045
+ "backend-api"
1046
+ ],
1047
+ "needsProject": false,
1048
+ "status": "implemented",
1049
+ "title": {
1050
+ "zh-TW": "指令前面不要加 $",
1051
+ "en": "No $ in front of commands"
1052
+ },
1053
+ "description": {
1054
+ "zh-TW": "指令前面加 `$`,複製貼上時會連 `$` 一起貼,執行就失敗。要示範執行結果,輸入和結果分成兩個區塊,或把示範區塊的語言標成 `console`。",
1055
+ "en": "A `$` in front of a command gets copied along with it and the command fails. To show output, put input and output in separate blocks, or mark the demo block as `console`."
1056
+ },
1057
+ "fix": {
1058
+ "zh-TW": "刪掉每行開頭的 `$ `。",
1059
+ "en": "Remove the leading `$ ` from each line."
1060
+ },
1061
+ "messages": {
1062
+ "prompt": {
1063
+ "zh-TW": "指令前面有提示符號 `$`({lines}),複製貼上會執行失敗",
1064
+ "en": "Commands start with a `$` prompt ({lines}); copying them will fail"
1065
+ }
1066
+ },
1067
+ "example": {
1068
+ "zh-TW": {
1069
+ "before": [
1070
+ "```bash",
1071
+ "$ pnpm test",
1072
+ "```"
1073
+ ],
1074
+ "after": [
1075
+ "```bash",
1076
+ "pnpm test",
1077
+ "```"
1078
+ ]
1079
+ },
1080
+ "en": {
1081
+ "before": [
1082
+ "```bash",
1083
+ "$ pnpm test",
1084
+ "```"
1085
+ ],
1086
+ "after": [
1087
+ "```bash",
1088
+ "pnpm test",
1089
+ "```"
1090
+ ]
1091
+ }
1092
+ }
1093
+ },
1094
+ {
1095
+ "id": "CMD004",
1096
+ "block": "install",
1097
+ "category": "commands",
1098
+ "severity": "error",
1099
+ "types": [
1100
+ "web-app",
1101
+ "course-example",
1102
+ "portfolio",
1103
+ "backend-api"
1104
+ ],
1105
+ "needsProject": true,
1106
+ "status": "implemented",
1107
+ "title": {
1108
+ "zh-TW": "指令用的套件管理工具跟專案一致",
1109
+ "en": "Commands use the project's package manager"
1110
+ },
1111
+ "description": {
1112
+ "zh-TW": "專案用哪個套件管理工具,看專案裡鎖定版本的檔案(例如 `pnpm-lock.yaml`)和 package.json 的 `packageManager`。README 寫別的管理器,照做會裝出不一樣的版本,甚至裝不起來。",
1113
+ "en": "The project's package manager is shown by its lock file (for example `pnpm-lock.yaml`) and the `packageManager` field in package.json. Commands for a different one install different versions or fail."
1114
+ },
1115
+ "fix": {
1116
+ "zh-TW": "把指令換成專案用的套件管理工具,例如 `npm install` 改成 `pnpm install`、`npm run dev` 改成 `pnpm dev`。",
1117
+ "en": "Switch the commands to the project's package manager, for example `npm install` to `pnpm install` and `npm run dev` to `pnpm dev`."
1118
+ },
1119
+ "messages": {
1120
+ "mismatch": {
1121
+ "zh-TW": "寫的是 {used},專案實際用的是 {expected}(依據 {evidence})",
1122
+ "en": "This uses {used}, but the project uses {expected} (see {evidence})"
1123
+ }
1124
+ },
1125
+ "example": {
1126
+ "zh-TW": {
1127
+ "before": [
1128
+ "npm install",
1129
+ "cp .env.example .env",
1130
+ "npm run dev"
1131
+ ],
1132
+ "after": [
1133
+ "pnpm install",
1134
+ "cp .env.example .env",
1135
+ "pnpm dev"
1136
+ ]
1137
+ },
1138
+ "en": {
1139
+ "before": [
1140
+ "npm install",
1141
+ "cp .env.example .env",
1142
+ "npm run dev"
1143
+ ],
1144
+ "after": [
1145
+ "pnpm install",
1146
+ "cp .env.example .env",
1147
+ "pnpm dev"
1148
+ ]
1149
+ }
1150
+ }
1151
+ },
1152
+ {
1153
+ "id": "CMD005",
1154
+ "block": "install",
1155
+ "category": "commands",
1156
+ "severity": "error",
1157
+ "types": [
1158
+ "web-app",
1159
+ "course-example",
1160
+ "portfolio",
1161
+ "backend-api"
1162
+ ],
1163
+ "needsProject": true,
1164
+ "status": "implemented",
1165
+ "title": {
1166
+ "zh-TW": "指令要對得到 package.json 的 scripts",
1167
+ "en": "Commands match the scripts in package.json"
1168
+ },
1169
+ "description": {
1170
+ "zh-TW": "`npm run dev`、`pnpm build` 這類指令,後面的名稱要在 package.json 的 `scripts` 裡找得到,不然一執行就失敗。",
1171
+ "en": "The name in commands such as `npm run dev` or `pnpm build` must exist under `scripts` in package.json, or the command fails immediately."
1172
+ },
1173
+ "fix": {
1174
+ "zh-TW": "改成 package.json 裡真的有的名稱,或在 `scripts` 補上這個指令。",
1175
+ "en": "Use a name that exists in package.json, or add the script to `scripts`."
1176
+ },
1177
+ "messages": {
1178
+ "missing": {
1179
+ "zh-TW": "package.json 沒有「{script}」這個指令(有的是:{available})",
1180
+ "en": "package.json has no \"{script}\" script (available: {available})"
1181
+ },
1182
+ "noScripts": {
1183
+ "zh-TW": "package.json 沒有任何 scripts,「{script}」執行不了",
1184
+ "en": "package.json has no scripts, so \"{script}\" cannot run"
1185
+ }
1186
+ },
1187
+ "example": {
1188
+ "zh-TW": {
1189
+ "before": [
1190
+ "pnpm serve"
1191
+ ],
1192
+ "after": [
1193
+ "pnpm dev"
1194
+ ]
1195
+ },
1196
+ "en": {
1197
+ "before": [
1198
+ "pnpm serve"
1199
+ ],
1200
+ "after": [
1201
+ "pnpm dev"
1202
+ ]
1203
+ }
1204
+ }
1205
+ },
1206
+ {
1207
+ "id": "CMD006",
1208
+ "block": "install",
1209
+ "category": "commands",
1210
+ "severity": "warning",
1211
+ "types": [
1212
+ "web-app",
1213
+ "course-example",
1214
+ "portfolio",
1215
+ "backend-api"
1216
+ ],
1217
+ "needsProject": true,
1218
+ "status": "planned",
1219
+ "title": {
1220
+ "zh-TW": "git clone 的網址是這個專案",
1221
+ "en": "The git clone URL points at this project"
1222
+ },
1223
+ "description": {
1224
+ "zh-TW": "`git clone` 後面的網址要是這個專案在 GitHub 上的網址,複製範本時最常忘記改。",
1225
+ "en": "The URL after `git clone` must be this project's own address; it is the line most often left unchanged from a template."
1226
+ },
1227
+ "fix": {
1228
+ "zh-TW": "換成這個專案的網址。",
1229
+ "en": "Replace it with this project's URL."
1230
+ },
1231
+ "messages": {}
1232
+ },
1233
+ {
1234
+ "id": "CMD007",
1235
+ "block": "install",
1236
+ "category": "commands",
1237
+ "severity": "warning",
1238
+ "types": [
1239
+ "web-app",
1240
+ "course-example",
1241
+ "portfolio",
1242
+ "backend-api"
1243
+ ],
1244
+ "needsProject": true,
1245
+ "status": "planned",
1246
+ "title": {
1247
+ "zh-TW": "cd 的資料夾名稱跟專案一致",
1248
+ "en": "The cd folder name matches the project"
1249
+ },
1250
+ "description": {
1251
+ "zh-TW": "clone 完要 `cd` 進去的資料夾名稱,要跟 repo 名稱一樣。",
1252
+ "en": "The folder you `cd` into after cloning must match the repository name."
1253
+ },
1254
+ "fix": {
1255
+ "zh-TW": "改成 repo 的名稱。",
1256
+ "en": "Use the repository name."
1257
+ },
1258
+ "messages": {}
1259
+ },
1260
+ {
1261
+ "id": "CMD008",
1262
+ "block": null,
1263
+ "relatedBlocks": [
1264
+ "install"
1265
+ ],
1266
+ "category": "commands",
1267
+ "severity": "warning",
1268
+ "types": [
1269
+ "web-app",
1270
+ "course-example",
1271
+ "portfolio",
1272
+ "backend-api"
1273
+ ],
1274
+ "needsProject": false,
1275
+ "status": "implemented",
1276
+ "title": {
1277
+ "zh-TW": "指令區塊裡只放指令",
1278
+ "en": "Command blocks contain only commands"
1279
+ },
1280
+ "description": {
1281
+ "zh-TW": "標成 `bash`、`sh` 的區塊,讀者會整段複製到終端機執行,AI 也可能直接執行。說明文字、帳號密碼、要用瀏覽器打開的網址放在裡面,複製貼上就會出錯。",
1282
+ "en": "Readers paste `bash` and `sh` blocks straight into a terminal, and AI may run them as they are. Explanations, logins or a URL meant for the browser inside them break that."
1283
+ },
1284
+ "fix": {
1285
+ "zh-TW": "說明改寫在區塊外面;帳號密碼改用清單或表格;要用瀏覽器打開的網址改成一般文字或連結。",
1286
+ "en": "Move explanations outside the block, list logins in a list or table, and write browser URLs as normal text or a link."
1287
+ },
1288
+ "messages": {
1289
+ "account": {
1290
+ "zh-TW": "指令區塊裡有帳號或密碼,這不是指令",
1291
+ "en": "A login inside a command block; it is not a command"
1292
+ },
1293
+ "text": {
1294
+ "zh-TW": "指令區塊裡有說明文字,這不是指令",
1295
+ "en": "Explanatory text inside a command block; it is not a command"
1296
+ },
1297
+ "url": {
1298
+ "zh-TW": "指令區塊裡只有一個網址,這不是指令",
1299
+ "en": "A bare URL inside a command block; it is not a command"
1300
+ }
1301
+ },
1302
+ "example": {
1303
+ "zh-TW": {
1304
+ "before": [
1305
+ "pnpm dev",
1306
+ "http://localhost:5173",
1307
+ "```"
1308
+ ],
1309
+ "after": [
1310
+ "pnpm dev",
1311
+ "```",
1312
+ "",
1313
+ "打開 http://localhost:5173,看到菜單就成功了。"
1314
+ ]
1315
+ },
1316
+ "en": {
1317
+ "before": [
1318
+ "pnpm dev",
1319
+ "http://localhost:5173",
1320
+ "```"
1321
+ ],
1322
+ "after": [
1323
+ "pnpm dev",
1324
+ "```",
1325
+ "",
1326
+ "Open http://localhost:5173 in your browser; once you see the menu, it is running."
1327
+ ]
1328
+ }
1329
+ }
1330
+ },
1331
+ {
1332
+ "id": "CMD009",
1333
+ "block": null,
1334
+ "category": "commands",
1335
+ "severity": "warning",
1336
+ "types": [
1337
+ "web-app",
1338
+ "course-example",
1339
+ "portfolio",
1340
+ "backend-api"
1341
+ ],
1342
+ "needsProject": false,
1343
+ "status": "planned",
1344
+ "title": {
1345
+ "zh-TW": "指令裡要替換的地方要說明",
1346
+ "en": "Explain any part of a command that must be replaced"
1347
+ },
1348
+ "description": {
1349
+ "zh-TW": "指令裡有 `YOUR_TOKEN` 這類要換掉的字,區塊下面要說明換成什麼。",
1350
+ "en": "If a command contains something like `YOUR_TOKEN`, say right below the block what to replace it with."
1351
+ },
1352
+ "fix": {
1353
+ "zh-TW": "在區塊下方說明每個要替換的字。",
1354
+ "en": "Explain each value to replace below the block."
1355
+ },
1356
+ "messages": {}
1357
+ },
1358
+ {
1359
+ "id": "CMD010",
1360
+ "block": null,
1361
+ "relatedBlocks": [
1362
+ "install"
1363
+ ],
1364
+ "category": "commands",
1365
+ "severity": "error",
1366
+ "types": [
1367
+ "web-app",
1368
+ "course-example",
1369
+ "portfolio",
1370
+ "backend-api"
1371
+ ],
1372
+ "needsProject": false,
1373
+ "status": "implemented",
1374
+ "title": {
1375
+ "zh-TW": "指令裡不能有全形字元",
1376
+ "en": "No full-width characters in commands"
1377
+ },
1378
+ "description": {
1379
+ "zh-TW": "全形空白、全形引號、全形冒號這類字貼到終端機會執行失敗,而且肉眼很難看出來。常見原因是先在文書軟體打好再貼過來。",
1380
+ "en": "Full-width spaces, quotes or colons make a pasted command fail and are hard to see. They usually come from writing the command in a word processor first."
1381
+ },
1382
+ "fix": {
1383
+ "zh-TW": "把全形字元換成半形,例如全形空白換成一般空白、「“”」換成 `\"`。",
1384
+ "en": "Replace them with their normal (half-width) versions, for example a full-width space with a normal space and “” with `\"`."
1385
+ },
1386
+ "messages": {
1387
+ "found": {
1388
+ "zh-TW": "指令裡有全形字元「{char}」",
1389
+ "en": "Full-width character \"{char}\" in a command"
1390
+ }
1391
+ },
1392
+ "example": {
1393
+ "zh-TW": {
1394
+ "before": [
1395
+ "cp .env.example\u3000.env"
1396
+ ],
1397
+ "after": [
1398
+ "cp .env.example .env"
1399
+ ]
1400
+ },
1401
+ "en": {
1402
+ "before": [
1403
+ "cp .env.example\u3000.env"
1404
+ ],
1405
+ "after": [
1406
+ "cp .env.example .env"
1407
+ ]
1408
+ }
1409
+ }
1410
+ },
1411
+ {
1412
+ "id": "CMD011",
1413
+ "block": "install",
1414
+ "category": "commands",
1415
+ "severity": "warning",
1416
+ "types": [
1417
+ "web-app",
1418
+ "course-example",
1419
+ "portfolio",
1420
+ "backend-api"
1421
+ ],
1422
+ "needsProject": true,
1423
+ "status": "planned",
1424
+ "title": {
1425
+ "zh-TW": "本機網址的埠號跟設定一致",
1426
+ "en": "The local URL uses the configured port"
1427
+ },
1428
+ "description": {
1429
+ "zh-TW": "README 寫的 `http://localhost:埠號`,要跟專案設定的埠號一樣。",
1430
+ "en": "The `http://localhost:port` in the README must match the port the project is configured to use."
1431
+ },
1432
+ "fix": {
1433
+ "zh-TW": "照專案設定改埠號。",
1434
+ "en": "Change the port to match the project settings."
1435
+ },
1436
+ "messages": {}
1437
+ },
1438
+ {
1439
+ "id": "CMD012",
1440
+ "block": "install",
1441
+ "category": "commands",
1442
+ "severity": "warning",
1443
+ "types": [
1444
+ "web-app",
1445
+ "course-example",
1446
+ "portfolio",
1447
+ "backend-api"
1448
+ ],
1449
+ "needsProject": true,
1450
+ "status": "implemented",
1451
+ "title": {
1452
+ "zh-TW": "有測試就寫怎麼跑",
1453
+ "en": "If there are tests, say how to run them"
1454
+ },
1455
+ "description": {
1456
+ "zh-TW": "package.json 有 `test` 指令,README 卻沒寫怎麼跑測試。想改程式的人和 AI 都需要知道改完怎麼確認沒弄壞。",
1457
+ "en": "package.json has a `test` script but the README never says how to run it. Anyone changing the code, including AI, needs to know how to check nothing broke."
1458
+ },
1459
+ "fix": {
1460
+ "zh-TW": "在「安裝與執行」底下加「執行測試」,放一個跑測試的指令。",
1461
+ "en": "Add \"Running Tests\" under Getting Started with the command that runs the tests."
1462
+ },
1463
+ "messages": {
1464
+ "missing": {
1465
+ "zh-TW": "package.json 有測試指令({command}),README 沒寫怎麼跑",
1466
+ "en": "package.json has a test script ({command}), but the README never says how to run it"
1467
+ }
1468
+ },
1469
+ "example": {
1470
+ "zh-TW": {
1471
+ "before": [],
1472
+ "after": [
1473
+ "### 執行測試",
1474
+ "",
1475
+ "```bash",
1476
+ "pnpm test",
1477
+ "```"
1478
+ ]
1479
+ },
1480
+ "en": {
1481
+ "before": [],
1482
+ "after": [
1483
+ "### Running Tests",
1484
+ "",
1485
+ "```bash",
1486
+ "pnpm test",
1487
+ "```"
1488
+ ]
1489
+ }
1490
+ }
1491
+ },
1492
+ {
1493
+ "id": "VER001",
1494
+ "block": "install",
1495
+ "category": "versions",
1496
+ "severity": "error",
1497
+ "types": [
1498
+ "web-app",
1499
+ "course-example",
1500
+ "portfolio",
1501
+ "backend-api"
1502
+ ],
1503
+ "needsProject": false,
1504
+ "status": "planned",
1505
+ "title": {
1506
+ "zh-TW": "有「環境需求」小節(已併入 STR006)",
1507
+ "en": "A Requirements subsection (now part of STR006)"
1508
+ },
1509
+ "description": {
1510
+ "zh-TW": "「環境需求」已經列在每種類型的必填章節,由 STR006 一起檢查,這條保留代號不另外實作。",
1511
+ "en": "Requirements is now a required section for every type and is checked by STR006; this ID is kept for reference only."
1512
+ },
1513
+ "fix": {
1514
+ "zh-TW": "見 STR006。",
1515
+ "en": "See STR006."
1516
+ },
1517
+ "messages": {}
1518
+ },
1519
+ {
1520
+ "id": "VER002",
1521
+ "block": "install",
1522
+ "category": "versions",
1523
+ "severity": "error",
1524
+ "types": [
1525
+ "web-app",
1526
+ "course-example",
1527
+ "portfolio",
1528
+ "backend-api"
1529
+ ],
1530
+ "needsProject": true,
1531
+ "status": "implemented",
1532
+ "title": {
1533
+ "zh-TW": "Node.js 版本跟專案設定一致",
1534
+ "en": "The Node.js version matches the project settings"
1535
+ },
1536
+ "description": {
1537
+ "zh-TW": "README 寫的 Node.js 版本,要跟 package.json 的 `engines`、`.nvmrc` 這類檔案對得上。對不上的話,照 README 裝了還是跑不起來。",
1538
+ "en": "The Node.js version in the README must agree with `engines` in package.json and files such as `.nvmrc`. If they disagree, following the README still leaves a project that will not run."
1539
+ },
1540
+ "fix": {
1541
+ "zh-TW": "照專案設定改 README 的版本;如果是設定檔過時,就改設定檔。",
1542
+ "en": "Update the README to match the project settings, or update the settings if they are the outdated part."
1543
+ },
1544
+ "messages": {
1545
+ "mismatch": {
1546
+ "zh-TW": "README 寫 Node.js {readme},但 {source} 是 {project}",
1547
+ "en": "The README says Node.js {readme}, but {source} says {project}"
1548
+ }
1549
+ },
1550
+ "example": {
1551
+ "zh-TW": {
1552
+ "before": [
1553
+ "- Node.js 16 以上"
1554
+ ],
1555
+ "after": [
1556
+ "- Node.js 22 以上"
1557
+ ]
1558
+ },
1559
+ "en": {
1560
+ "before": [
1561
+ "- Node.js 16 or later"
1562
+ ],
1563
+ "after": [
1564
+ "- Node.js 22 or later"
1565
+ ]
1566
+ }
1567
+ }
1568
+ },
1569
+ {
1570
+ "id": "VER003",
1571
+ "block": "install",
1572
+ "category": "versions",
1573
+ "severity": "warning",
1574
+ "types": [
1575
+ "web-app",
1576
+ "course-example",
1577
+ "portfolio",
1578
+ "backend-api"
1579
+ ],
1580
+ "needsProject": true,
1581
+ "status": "planned",
1582
+ "title": {
1583
+ "zh-TW": "套件管理工具版本跟 packageManager 一致",
1584
+ "en": "The package manager version matches packageManager"
1585
+ },
1586
+ "description": {
1587
+ "zh-TW": "README 寫的 pnpm、yarn 版本,要跟 package.json 的 `packageManager` 一致。",
1588
+ "en": "The pnpm or yarn version in the README must match `packageManager` in package.json."
1589
+ },
1590
+ "fix": {
1591
+ "zh-TW": "照 `packageManager` 改版本。",
1592
+ "en": "Match the version in `packageManager`."
1593
+ },
1594
+ "messages": {}
1595
+ },
1596
+ {
1597
+ "id": "VER004",
1598
+ "block": "tech",
1599
+ "category": "versions",
1600
+ "severity": "warning",
1601
+ "types": [
1602
+ "web-app",
1603
+ "course-example",
1604
+ "portfolio",
1605
+ "backend-api"
1606
+ ],
1607
+ "needsProject": true,
1608
+ "status": "planned",
1609
+ "title": {
1610
+ "zh-TW": "「使用技術」的主版號跟專案一致",
1611
+ "en": "Tech Stack major versions match the project"
1612
+ },
1613
+ "description": {
1614
+ "zh-TW": "「使用技術」寫的 Vue 3、Vite 6 這類主版號,要跟 package.json 裡的套件版本對得上。",
1615
+ "en": "Major versions listed under Tech Stack, such as Vue 3 or Vite 6, must match the packages in package.json."
1616
+ },
1617
+ "fix": {
1618
+ "zh-TW": "照 package.json 改主版號,不用寫到小版號。",
1619
+ "en": "Match the major version in package.json; minor versions are not needed."
1620
+ },
1621
+ "messages": {}
1622
+ },
1623
+ {
1624
+ "id": "VER005",
1625
+ "block": "install",
1626
+ "category": "versions",
1627
+ "severity": "warning",
1628
+ "types": [
1629
+ "web-app",
1630
+ "course-example",
1631
+ "portfolio",
1632
+ "backend-api"
1633
+ ],
1634
+ "needsProject": false,
1635
+ "status": "implemented",
1636
+ "title": {
1637
+ "zh-TW": "版本要寫具體數字",
1638
+ "en": "Versions are specific numbers"
1639
+ },
1640
+ "description": {
1641
+ "zh-TW": "「最新版」「16 以上...」這種說法沒辦法確認,過一陣子就不對了。寫具體的版本號或範圍,例如「Node.js 22 以上」。",
1642
+ "en": "Phrases like \"latest version\" cannot be checked and go out of date. Write a specific version or range, for example \"Node.js 22 or later\"."
1643
+ },
1644
+ "fix": {
1645
+ "zh-TW": "改成具體的版本,例如「Node.js 22」「pnpm 10」。",
1646
+ "en": "Use a specific version, for example \"Node.js 22\" or \"pnpm 10\"."
1647
+ },
1648
+ "messages": {
1649
+ "vague": {
1650
+ "zh-TW": "「{text}」不是具體的版本",
1651
+ "en": "\"{text}\" is not a specific version"
1652
+ }
1653
+ },
1654
+ "example": {
1655
+ "zh-TW": {
1656
+ "before": [
1657
+ "- Node.js 最新版"
1658
+ ],
1659
+ "after": [
1660
+ "- Node.js 22 以上"
1661
+ ]
1662
+ },
1663
+ "en": {
1664
+ "before": [
1665
+ "- Node.js latest version"
1666
+ ],
1667
+ "after": [
1668
+ "- Node.js 22 or later"
1669
+ ]
1670
+ }
1671
+ }
1672
+ },
1673
+ {
1674
+ "id": "VER006",
1675
+ "block": "install",
1676
+ "category": "versions",
1677
+ "severity": "warning",
1678
+ "types": [
1679
+ "web-app",
1680
+ "course-example",
1681
+ "portfolio",
1682
+ "backend-api"
1683
+ ],
1684
+ "needsProject": false,
1685
+ "status": "planned",
1686
+ "title": {
1687
+ "zh-TW": "不要要求已經停止支援的版本",
1688
+ "en": "Do not require a version that is no longer supported"
1689
+ },
1690
+ "description": {
1691
+ "zh-TW": "README 要求的 Node.js 版本如果已經停止支援,新手很難裝到,也有安全疑慮。",
1692
+ "en": "A Node.js version that is no longer supported is hard for newcomers to install and may be unsafe."
1693
+ },
1694
+ "fix": {
1695
+ "zh-TW": "升級到還在支援的版本,並更新 README。",
1696
+ "en": "Upgrade to a supported version and update the README."
1697
+ },
1698
+ "messages": {}
1699
+ },
1700
+ {
1701
+ "id": "VER007",
1702
+ "block": "install",
1703
+ "category": "versions",
1704
+ "severity": "warning",
1705
+ "types": [
1706
+ "web-app",
1707
+ "course-example",
1708
+ "portfolio",
1709
+ "backend-api"
1710
+ ],
1711
+ "needsProject": true,
1712
+ "status": "implemented",
1713
+ "title": {
1714
+ "zh-TW": "專案指定了 Node.js 版本,README 也要寫",
1715
+ "en": "If the project sets a Node.js version, the README states it"
1716
+ },
1717
+ "description": {
1718
+ "zh-TW": "專案有指定 Node.js 版本,README 的「環境需求」也要寫出具體的版本號,不要讓人和 AI 用猜的。",
1719
+ "en": "When the project sets a Node.js version, the README's Requirements must state it too, so nobody has to guess."
1720
+ },
1721
+ "fix": {
1722
+ "zh-TW": "在「環境需求」寫出具體版本,例如「Node.js 22 以上」。",
1723
+ "en": "Write the specific version under Requirements, for example \"Node.js 22 or later\"."
1724
+ },
1725
+ "messages": {
1726
+ "missing": {
1727
+ "zh-TW": "專案指定了 Node.js {project}({source}),README 沒寫版本",
1728
+ "en": "The project sets Node.js {project} ({source}), but the README gives no version"
1729
+ }
1730
+ },
1731
+ "example": {
1732
+ "zh-TW": {
1733
+ "before": [
1734
+ "### 環境需求",
1735
+ "",
1736
+ "- pnpm 10"
1737
+ ],
1738
+ "after": [
1739
+ "### 環境需求",
1740
+ "",
1741
+ "- Node.js 22 以上",
1742
+ "- pnpm 10"
1743
+ ]
1744
+ },
1745
+ "en": {
1746
+ "before": [
1747
+ "### Requirements",
1748
+ "",
1749
+ "- pnpm 10"
1750
+ ],
1751
+ "after": [
1752
+ "### Requirements",
1753
+ "",
1754
+ "- Node.js 22 or later",
1755
+ "- pnpm 10"
1756
+ ]
1757
+ }
1758
+ }
1759
+ },
1760
+ {
1761
+ "id": "ENV001",
1762
+ "block": "env",
1763
+ "category": "env",
1764
+ "severity": "error",
1765
+ "types": [
1766
+ "web-app",
1767
+ "course-example",
1768
+ "portfolio",
1769
+ "backend-api"
1770
+ ],
1771
+ "needsProject": true,
1772
+ "status": "implemented",
1773
+ "title": {
1774
+ "zh-TW": "有 .env.example 就要有「環境變數」章節",
1775
+ "en": "A .env.example means an Environment Variables section"
1776
+ },
1777
+ "description": {
1778
+ "zh-TW": "專案有 `.env.example`,代表要先設定環境變數才能跑。README 要有「環境變數」章節,說明每個變數的用途、是否必填、去哪裡拿。",
1779
+ "en": "A `.env.example` file means settings are needed before the project runs. The README needs an Environment Variables section explaining what each one is for, whether it is required and where to get it."
1780
+ },
1781
+ "fix": {
1782
+ "zh-TW": "加一個「環境變數」章節,用表格列出 `.env.example` 裡的每個變數。",
1783
+ "en": "Add an Environment Variables section with a table of every variable in `.env.example`."
1784
+ },
1785
+ "messages": {
1786
+ "missing": {
1787
+ "zh-TW": "專案有 {file},README 卻沒有「環境變數」章節",
1788
+ "en": "The project has {file}, but the README has no Environment Variables section"
1789
+ }
1790
+ },
1791
+ "example": {
1792
+ "zh-TW": {
1793
+ "before": [],
1794
+ "after": [
1795
+ "## 環境變數",
1796
+ "",
1797
+ "| 名稱 | 必填 | 用途 | 去哪裡拿 |",
1798
+ "| ---- | ---- | ---- | ---- |",
1799
+ "| `VITE_API_BASE_URL` | 是 | 點餐 API 的網址 | 啟動點餐 API 後的網址 |"
1800
+ ]
1801
+ },
1802
+ "en": {
1803
+ "before": [],
1804
+ "after": [
1805
+ "## Environment Variables",
1806
+ "",
1807
+ "| Name | Required | Purpose | Where to get it |",
1808
+ "| ---- | ---- | ---- | ---- |",
1809
+ "| `VITE_API_BASE_URL` | Yes | Address of the ordering API | Where the ordering API runs |"
1810
+ ]
1811
+ }
1812
+ }
1813
+ },
1814
+ {
1815
+ "id": "ENV002",
1816
+ "block": "env",
1817
+ "category": "env",
1818
+ "severity": "error",
1819
+ "types": [
1820
+ "web-app",
1821
+ "course-example",
1822
+ "portfolio",
1823
+ "backend-api"
1824
+ ],
1825
+ "needsProject": true,
1826
+ "status": "implemented",
1827
+ "title": {
1828
+ "zh-TW": ".env.example 的變數都要寫到",
1829
+ "en": "Every variable in .env.example is documented"
1830
+ },
1831
+ "description": {
1832
+ "zh-TW": "`.env.example` 裡的每個變數,「環境變數」章節都要寫到,不然別人不知道要填什麼。",
1833
+ "en": "Every variable in `.env.example` must appear in the Environment Variables section, or nobody knows what to fill in."
1834
+ },
1835
+ "fix": {
1836
+ "zh-TW": "在「環境變數」的表格補上這些變數:用途、是否必填、去哪裡拿。",
1837
+ "en": "Add these variables to the table: what each is for, whether it is required, and where to get it."
1838
+ },
1839
+ "messages": {
1840
+ "missing": {
1841
+ "zh-TW": "「環境變數」沒寫到 {file} 裡的 {names}",
1842
+ "en": "The Environment Variables section does not mention {names} from {file}"
1843
+ }
1844
+ },
1845
+ "example": {
1846
+ "zh-TW": {
1847
+ "before": [
1848
+ "| 名稱 | 必填 | 用途 | 去哪裡拿 |",
1849
+ "| ---- | ---- | ---- | ---- |",
1850
+ "| `VITE_API_BASE_URL` | 是 | 點餐 API 的網址 | 啟動點餐 API 後的網址 |"
1851
+ ],
1852
+ "after": [
1853
+ "| 名稱 | 必填 | 用途 | 去哪裡拿 |",
1854
+ "| ---- | ---- | ---- | ---- |",
1855
+ "| `VITE_API_BASE_URL` | 是 | 點餐 API 的網址 | 啟動點餐 API 後的網址 |",
1856
+ "| `VITE_SHOP_PHONE` | 否 | 頁尾顯示的店家電話 | 店家提供 |"
1857
+ ]
1858
+ },
1859
+ "en": {
1860
+ "before": [
1861
+ "| Name | Required | Purpose | Where to get it |",
1862
+ "| ---- | ---- | ---- | ---- |",
1863
+ "| `VITE_API_BASE_URL` | Yes | Address of the ordering API | Where the ordering API runs |"
1864
+ ],
1865
+ "after": [
1866
+ "| Name | Required | Purpose | Where to get it |",
1867
+ "| ---- | ---- | ---- | ---- |",
1868
+ "| `VITE_API_BASE_URL` | Yes | Address of the ordering API | Where the ordering API runs |",
1869
+ "| `VITE_SHOP_PHONE` | No | Shop phone number shown in the footer | Provided by the shop |"
1870
+ ]
1871
+ }
1872
+ }
1873
+ },
1874
+ {
1875
+ "id": "ENV003",
1876
+ "block": "env",
1877
+ "category": "env",
1878
+ "severity": "warning",
1879
+ "types": [
1880
+ "web-app",
1881
+ "course-example",
1882
+ "portfolio",
1883
+ "backend-api"
1884
+ ],
1885
+ "needsProject": true,
1886
+ "status": "planned",
1887
+ "title": {
1888
+ "zh-TW": "程式用到的環境變數都在 .env.example",
1889
+ "en": "Every variable the code uses is in .env.example"
1890
+ },
1891
+ "description": {
1892
+ "zh-TW": "程式碼讀了某個環境變數,`.env.example` 卻沒有,別人就不知道要設定它。",
1893
+ "en": "If the code reads a variable that `.env.example` does not list, nobody knows to set it."
1894
+ },
1895
+ "fix": {
1896
+ "zh-TW": "把它加進 `.env.example` 和 README。",
1897
+ "en": "Add it to `.env.example` and the README."
1898
+ },
1899
+ "messages": {}
1900
+ },
1901
+ {
1902
+ "id": "ENV004",
1903
+ "block": null,
1904
+ "relatedBlocks": [
1905
+ "env"
1906
+ ],
1907
+ "category": "security",
1908
+ "severity": "error",
1909
+ "types": [
1910
+ "web-app",
1911
+ "course-example",
1912
+ "portfolio",
1913
+ "backend-api"
1914
+ ],
1915
+ "needsProject": false,
1916
+ "status": "implemented",
1917
+ "title": {
1918
+ "zh-TW": "不要貼真的金鑰",
1919
+ "en": "No real secret keys"
1920
+ },
1921
+ "description": {
1922
+ "zh-TW": "README 是公開的,貼上去的金鑰、密碼、權杖等於公開給所有人。範例值請用 `your-api-key` 這類明顯是假的文字。",
1923
+ "en": "A README is public, so any key, password or token in it is public too. Use obviously fake example values such as `your-api-key`."
1924
+ },
1925
+ "fix": {
1926
+ "zh-TW": "換成假的範例值,並且到該服務把這組金鑰作廢、重新產生一組。",
1927
+ "en": "Replace it with a fake example value, then revoke the key in that service and create a new one."
1928
+ },
1929
+ "messages": {
1930
+ "found": {
1931
+ "zh-TW": "這裡看起來貼了真的金鑰",
1932
+ "en": "This looks like a real secret key"
1933
+ }
1934
+ },
1935
+ "example": {
1936
+ "zh-TW": {
1937
+ "before": [
1938
+ "| `ORDER_API_TOKEN` | 是 | 呼叫點餐 API 用的權杖 | `9f3ac1d27e…` |"
1939
+ ],
1940
+ "after": [
1941
+ "| `ORDER_API_TOKEN` | 是 | 呼叫點餐 API 用的權杖 | 店家後台的「API 權杖」頁面 |"
1942
+ ]
1943
+ },
1944
+ "en": {
1945
+ "before": [
1946
+ "| `ORDER_API_TOKEN` | Yes | Token for calling the ordering API | `9f3ac1d27e…` |"
1947
+ ],
1948
+ "after": [
1949
+ "| `ORDER_API_TOKEN` | Yes | Token for calling the ordering API | The \"API tokens\" page of the shop dashboard |"
1950
+ ]
1951
+ }
1952
+ }
1953
+ },
1954
+ {
1955
+ "id": "ENV005",
1956
+ "block": "env",
1957
+ "category": "security",
1958
+ "severity": "error",
1959
+ "types": [
1960
+ "web-app",
1961
+ "course-example",
1962
+ "portfolio",
1963
+ "backend-api"
1964
+ ],
1965
+ "needsProject": true,
1966
+ "status": "planned",
1967
+ "title": {
1968
+ "zh-TW": ".env 沒有被放進 repo",
1969
+ "en": ".env is not committed"
1970
+ },
1971
+ "description": {
1972
+ "zh-TW": "`.env` 放的是真的設定,不能放進 repo;放進去的是 `.env.example`。",
1973
+ "en": "`.env` holds real settings and must not be committed; commit `.env.example` instead."
1974
+ },
1975
+ "fix": {
1976
+ "zh-TW": "把 `.env` 從 repo 移除並加進 `.gitignore`,裡面的金鑰全部換新。",
1977
+ "en": "Remove `.env` from the repository, add it to `.gitignore`, and replace every key in it."
1978
+ },
1979
+ "messages": {}
1980
+ },
1981
+ {
1982
+ "id": "ENV006",
1983
+ "block": "env",
1984
+ "category": "security",
1985
+ "severity": "warning",
1986
+ "types": [
1987
+ "web-app",
1988
+ "course-example",
1989
+ "portfolio",
1990
+ "backend-api"
1991
+ ],
1992
+ "needsProject": false,
1993
+ "status": "planned",
1994
+ "title": {
1995
+ "zh-TW": "會公開到前端的變數不要放秘密",
1996
+ "en": "Variables exposed to the browser hold no secrets"
1997
+ },
1998
+ "description": {
1999
+ "zh-TW": "`VITE_`、`NEXT_PUBLIC_` 開頭的變數會被打包進網頁,任何人都看得到,名稱裡有 SECRET、PASSWORD 就要小心。",
2000
+ "en": "Variables starting with `VITE_` or `NEXT_PUBLIC_` end up in the web page where anyone can read them; be careful when the name says SECRET or PASSWORD."
2001
+ },
2002
+ "fix": {
2003
+ "zh-TW": "秘密只放在伺服器端的變數。",
2004
+ "en": "Keep secrets in server-side variables only."
2005
+ },
2006
+ "messages": {}
2007
+ },
2008
+ {
2009
+ "id": "ENV007",
2010
+ "block": "env",
2011
+ "category": "env",
2012
+ "severity": "warning",
2013
+ "types": [
2014
+ "web-app",
2015
+ "course-example",
2016
+ "portfolio",
2017
+ "backend-api"
2018
+ ],
2019
+ "needsProject": false,
2020
+ "status": "planned",
2021
+ "title": {
2022
+ "zh-TW": "每個變數都寫出必填與否和說明",
2023
+ "en": "Each variable says whether it is required and what it does"
2024
+ },
2025
+ "description": {
2026
+ "zh-TW": "環境變數用一張四欄的表格寫:名稱、必填、用途、去哪裡拿。想多放一欄範例值也可以,範例值要是假的。",
2027
+ "en": "Document variables in a four-column table: name, required, purpose, where to get it. An extra column with a (fake) example value is fine."
2028
+ },
2029
+ "fix": {
2030
+ "zh-TW": "補齊「名稱、必填、用途、去哪裡拿」四欄。",
2031
+ "en": "Fill in all four columns: name, required, purpose, where to get it."
2032
+ },
2033
+ "messages": {}
2034
+ },
2035
+ {
2036
+ "id": "ENV008",
2037
+ "block": "install",
2038
+ "category": "env",
2039
+ "severity": "warning",
2040
+ "types": [
2041
+ "web-app",
2042
+ "course-example",
2043
+ "portfolio",
2044
+ "backend-api"
2045
+ ],
2046
+ "needsProject": true,
2047
+ "status": "implemented",
2048
+ "title": {
2049
+ "zh-TW": "安裝步驟要提到建立 .env",
2050
+ "en": "Setup steps mention creating .env"
2051
+ },
2052
+ "description": {
2053
+ "zh-TW": "專案有 `.env.example`,安裝步驟就要有一步把它複製成 `.env`,不然照著做會因為少了設定而跑不起來。",
2054
+ "en": "With a `.env.example` in the project, the setup steps need a step that copies it to `.env`; otherwise following them leaves the settings missing."
2055
+ },
2056
+ "fix": {
2057
+ "zh-TW": "在安裝步驟加一個 `cp .env.example .env` 的指令,並說明每個變數請看「環境變數」。",
2058
+ "en": "Add a `cp .env.example .env` step and point to the Environment Variables section for details."
2059
+ },
2060
+ "messages": {
2061
+ "missing": {
2062
+ "zh-TW": "專案裡有 {file},安裝步驟卻沒提到",
2063
+ "en": "The project has {file}, but the setup steps never mention it"
2064
+ }
2065
+ },
2066
+ "example": {
2067
+ "zh-TW": {
2068
+ "before": [
2069
+ "pnpm install",
2070
+ "pnpm dev"
2071
+ ],
2072
+ "after": [
2073
+ "pnpm install",
2074
+ "cp .env.example .env",
2075
+ "pnpm dev"
2076
+ ]
2077
+ },
2078
+ "en": {
2079
+ "before": [
2080
+ "pnpm install",
2081
+ "pnpm dev"
2082
+ ],
2083
+ "after": [
2084
+ "pnpm install",
2085
+ "cp .env.example .env",
2086
+ "pnpm dev"
2087
+ ]
2088
+ }
2089
+ }
2090
+ },
2091
+ {
2092
+ "id": "ENV009",
2093
+ "block": "env",
2094
+ "category": "env",
2095
+ "severity": "warning",
2096
+ "types": [
2097
+ "web-app",
2098
+ "course-example",
2099
+ "portfolio",
2100
+ "backend-api"
2101
+ ],
2102
+ "needsProject": true,
2103
+ "status": "planned",
2104
+ "title": {
2105
+ "zh-TW": "README 不要列 .env.example 沒有的變數",
2106
+ "en": "The README lists no variables missing from .env.example"
2107
+ },
2108
+ "description": {
2109
+ "zh-TW": "README 寫了某個變數,`.env.example` 卻沒有,代表其中一邊過時了。",
2110
+ "en": "A variable in the README that is not in `.env.example` means one of them is out of date."
2111
+ },
2112
+ "fix": {
2113
+ "zh-TW": "兩邊對齊。",
2114
+ "en": "Bring the two back in line."
2115
+ },
2116
+ "messages": {}
2117
+ },
2118
+ {
2119
+ "id": "IMG001",
2120
+ "block": null,
2121
+ "relatedBlocks": [
2122
+ "demo"
2123
+ ],
2124
+ "category": "images",
2125
+ "severity": "error",
2126
+ "types": [
2127
+ "web-app",
2128
+ "course-example",
2129
+ "portfolio",
2130
+ "backend-api"
2131
+ ],
2132
+ "needsProject": false,
2133
+ "status": "implemented",
2134
+ "title": {
2135
+ "zh-TW": "圖片要有替代文字",
2136
+ "en": "Images have alt text"
2137
+ },
2138
+ "description": {
2139
+ "zh-TW": "每張圖都要有替代文字(`![這裡](圖片路徑)` 中括號裡的字),說明這張圖要讓人知道什麼。看不到圖的人和 AI 只能讀這段字。",
2140
+ "en": "Every image needs alt text (the words inside the brackets of `![here](image path)`) saying what the image shows. People who cannot see it, and AI, only get this text."
2141
+ },
2142
+ "fix": {
2143
+ "zh-TW": "在中括號裡寫一句話描述圖片的重點,例如「點餐頁:左邊是菜單,右邊是購物車」。",
2144
+ "en": "Write one sentence about what matters in the image, for example \"Order page: menu on the left, cart on the right\"."
2145
+ },
2146
+ "messages": {
2147
+ "missing": {
2148
+ "zh-TW": "圖片沒有替代文字",
2149
+ "en": "Image has no alt text"
2150
+ }
2151
+ },
2152
+ "example": {
2153
+ "zh-TW": {
2154
+ "before": [
2155
+ "![](docs/images/order-page.png)"
2156
+ ],
2157
+ "after": [
2158
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](docs/images/order-page.png)"
2159
+ ]
2160
+ },
2161
+ "en": {
2162
+ "before": [
2163
+ "![](docs/images/order-page.png)"
2164
+ ],
2165
+ "after": [
2166
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](docs/images/order-page.png)"
2167
+ ]
2168
+ }
2169
+ }
2170
+ },
2171
+ {
2172
+ "id": "IMG002",
2173
+ "block": null,
2174
+ "relatedBlocks": [
2175
+ "demo"
2176
+ ],
2177
+ "category": "images",
2178
+ "severity": "warning",
2179
+ "types": [
2180
+ "web-app",
2181
+ "course-example",
2182
+ "portfolio",
2183
+ "backend-api"
2184
+ ],
2185
+ "needsProject": false,
2186
+ "status": "implemented",
2187
+ "title": {
2188
+ "zh-TW": "替代文字要說出圖片的重點",
2189
+ "en": "Alt text says what the image shows"
2190
+ },
2191
+ "description": {
2192
+ "zh-TW": "替代文字不要只寫檔名、「圖片」「截圖」「範例圖片 1」,也不要用「圖片:」開頭,要寫出這張圖讓人知道什麼。",
2193
+ "en": "Alt text should not be a file name, \"image\", \"screenshot\" or \"Image of…\". Say what the reader should learn from the picture."
2194
+ },
2195
+ "fix": {
2196
+ "zh-TW": "改成一句描述重點的話。",
2197
+ "en": "Replace it with one sentence describing what matters."
2198
+ },
2199
+ "messages": {
2200
+ "generic": {
2201
+ "zh-TW": "替代文字「{alt}」沒有說出圖片的重點",
2202
+ "en": "Alt text \"{alt}\" does not say what the image shows"
2203
+ }
2204
+ },
2205
+ "example": {
2206
+ "zh-TW": {
2207
+ "before": [
2208
+ "![order-page.png](docs/images/order-page.png)"
2209
+ ],
2210
+ "after": [
2211
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](docs/images/order-page.png)"
2212
+ ]
2213
+ },
2214
+ "en": {
2215
+ "before": [
2216
+ "![order-page.png](docs/images/order-page.png)"
2217
+ ],
2218
+ "after": [
2219
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](docs/images/order-page.png)"
2220
+ ]
2221
+ }
2222
+ }
2223
+ },
2224
+ {
2225
+ "id": "IMG003",
2226
+ "block": null,
2227
+ "relatedBlocks": [
2228
+ "demo"
2229
+ ],
2230
+ "category": "images",
2231
+ "severity": "error",
2232
+ "types": [
2233
+ "web-app",
2234
+ "course-example",
2235
+ "portfolio",
2236
+ "backend-api"
2237
+ ],
2238
+ "needsProject": true,
2239
+ "status": "implemented",
2240
+ "title": {
2241
+ "zh-TW": "相對路徑的圖片檔要存在",
2242
+ "en": "Images with relative paths exist"
2243
+ },
2244
+ "description": {
2245
+ "zh-TW": "用相對路徑引用的圖片(例如 `docs/images/home.png`),專案裡要真的有這個檔案,不然 GitHub 上會顯示破圖。",
2246
+ "en": "An image referenced by a relative path (for example `docs/images/home.png`) must exist in the project, or GitHub shows a broken image."
2247
+ },
2248
+ "fix": {
2249
+ "zh-TW": "把圖片放到這個路徑,或改成正確的路徑(注意大小寫)。",
2250
+ "en": "Add the image at that path or fix the path (mind upper and lower case)."
2251
+ },
2252
+ "messages": {
2253
+ "missing": {
2254
+ "zh-TW": "找不到圖片檔 {path}",
2255
+ "en": "Image file not found: {path}"
2256
+ }
2257
+ },
2258
+ "example": {
2259
+ "zh-TW": {
2260
+ "before": [
2261
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](images/order-page.png)"
2262
+ ],
2263
+ "after": [
2264
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](docs/images/order-page.png)"
2265
+ ]
2266
+ },
2267
+ "en": {
2268
+ "before": [
2269
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](images/order-page.png)"
2270
+ ],
2271
+ "after": [
2272
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](docs/images/order-page.png)"
2273
+ ]
2274
+ }
2275
+ }
2276
+ },
2277
+ {
2278
+ "id": "IMG004",
2279
+ "block": null,
2280
+ "relatedBlocks": [
2281
+ "demo"
2282
+ ],
2283
+ "category": "unfinished",
2284
+ "severity": "error",
2285
+ "types": [
2286
+ "web-app",
2287
+ "course-example",
2288
+ "portfolio",
2289
+ "backend-api"
2290
+ ],
2291
+ "needsProject": false,
2292
+ "status": "implemented",
2293
+ "title": {
2294
+ "zh-TW": "不要用佔位圖",
2295
+ "en": "No placeholder images"
2296
+ },
2297
+ "description": {
2298
+ "zh-TW": "fakeimg.pl、placehold.co 這類服務產生的是空白示意圖,代表截圖還沒換上去。",
2299
+ "en": "Services such as fakeimg.pl or placehold.co produce blank stand-in images, which means the real screenshot is still missing."
2300
+ },
2301
+ "fix": {
2302
+ "zh-TW": "換成專案真正的截圖,放在 repo 裡用相對路徑引用(例如 `docs/images/home.png`)。",
2303
+ "en": "Use a real screenshot stored in the repository and referenced by a relative path (for example `docs/images/home.png`)."
2304
+ },
2305
+ "messages": {
2306
+ "found": {
2307
+ "zh-TW": "這是佔位圖({host}),還沒換成真的截圖",
2308
+ "en": "This is a placeholder image ({host}), not a real screenshot"
2309
+ }
2310
+ },
2311
+ "example": {
2312
+ "zh-TW": {
2313
+ "before": [
2314
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](https://fakeimg.pl/800x500/)"
2315
+ ],
2316
+ "after": [
2317
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](docs/images/order-page.png)"
2318
+ ]
2319
+ },
2320
+ "en": {
2321
+ "before": [
2322
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](https://fakeimg.pl/800x500/)"
2323
+ ],
2324
+ "after": [
2325
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](docs/images/order-page.png)"
2326
+ ]
2327
+ }
2328
+ }
2329
+ },
2330
+ {
2331
+ "id": "IMG005",
2332
+ "block": "demo",
2333
+ "category": "images",
2334
+ "severity": "warning",
2335
+ "types": [
2336
+ "web-app",
2337
+ "portfolio"
2338
+ ],
2339
+ "needsProject": false,
2340
+ "status": "implemented",
2341
+ "title": {
2342
+ "zh-TW": "至少一張畫面或一個線上網址",
2343
+ "en": "At least one screenshot or live link"
2344
+ },
2345
+ "description": {
2346
+ "zh-TW": "網頁專案和作品集,讀者最想先看到長什麼樣子。至少放一張截圖,或一個可以直接打開的線上網址。",
2347
+ "en": "For web apps and portfolios, readers first want to see what it looks like. Include at least one screenshot or a live link they can open."
2348
+ },
2349
+ "fix": {
2350
+ "zh-TW": "在「畫面」放一到三張截圖,或在「線上展示」放網址。",
2351
+ "en": "Add one to three screenshots under Screenshots, or a link under Demo."
2352
+ },
2353
+ "messages": {
2354
+ "missing": {
2355
+ "zh-TW": "整份文件沒有任何畫面,也沒有線上網址",
2356
+ "en": "No screenshots and no live link anywhere"
2357
+ }
2358
+ },
2359
+ "example": {
2360
+ "zh-TW": {
2361
+ "before": [],
2362
+ "after": [
2363
+ "## 畫面",
2364
+ "",
2365
+ "![點餐頁:上方是分類標籤,下方列出餐點與價格,右下角是購物車按鈕](docs/images/order-page.png)"
2366
+ ]
2367
+ },
2368
+ "en": {
2369
+ "before": [],
2370
+ "after": [
2371
+ "## Screenshots",
2372
+ "",
2373
+ "![Order page: category tabs at the top, dishes and prices below, cart button at the bottom right](docs/images/order-page.png)"
2374
+ ]
2375
+ }
2376
+ }
2377
+ },
2378
+ {
2379
+ "id": "IMG006",
2380
+ "block": null,
2381
+ "category": "images",
2382
+ "severity": "warning",
2383
+ "types": [
2384
+ "web-app",
2385
+ "course-example",
2386
+ "portfolio",
2387
+ "backend-api"
2388
+ ],
2389
+ "needsProject": true,
2390
+ "status": "planned",
2391
+ "title": {
2392
+ "zh-TW": "圖片檔不要太大",
2393
+ "en": "Image files are not too large"
2394
+ },
2395
+ "description": {
2396
+ "zh-TW": "太大的圖片或動圖會讓 README 打開很慢。",
2397
+ "en": "Very large images or animations make the README slow to open."
2398
+ },
2399
+ "fix": {
2400
+ "zh-TW": "壓縮圖片或縮小尺寸。",
2401
+ "en": "Compress or resize the image."
2402
+ },
2403
+ "messages": {}
2404
+ },
2405
+ {
2406
+ "id": "IMG007",
2407
+ "block": "title",
2408
+ "category": "images",
2409
+ "severity": "warning",
2410
+ "types": [
2411
+ "web-app",
2412
+ "course-example",
2413
+ "portfolio",
2414
+ "backend-api"
2415
+ ],
2416
+ "needsProject": false,
2417
+ "status": "implemented",
2418
+ "title": {
2419
+ "zh-TW": "不要放人氣徽章",
2420
+ "en": "No popularity badges"
2421
+ },
2422
+ "description": {
2423
+ "zh-TW": "星星數、fork 數、issue 數這類徽章看不出專案品質,新專案顯示 0 反而扣分。要放徽章,就放建置狀態、測試覆蓋率、授權這類。",
2424
+ "en": "Star, fork or issue count badges say nothing about quality, and a new project showing 0 looks worse. If you use badges, show build status, test coverage or license."
2425
+ },
2426
+ "fix": {
2427
+ "zh-TW": "刪掉人氣徽章,最多保留三個跟品質有關的徽章。",
2428
+ "en": "Remove popularity badges and keep at most three quality-related ones."
2429
+ },
2430
+ "messages": {
2431
+ "found": {
2432
+ "zh-TW": "人氣徽章({kinds})看不出專案品質",
2433
+ "en": "Popularity badges ({kinds}) say nothing about quality"
2434
+ }
2435
+ },
2436
+ "example": {
2437
+ "zh-TW": {
2438
+ "before": [
2439
+ "# 巷口早餐店|線上點餐",
2440
+ "",
2441
+ "![GitHub stars](https://img.shields.io/github/stars/zaocan/breakfast-order)"
2442
+ ],
2443
+ "after": [
2444
+ "# 巷口早餐店|線上點餐"
2445
+ ]
2446
+ },
2447
+ "en": {
2448
+ "before": [
2449
+ "# Corner Breakfast",
2450
+ "",
2451
+ "![GitHub stars](https://img.shields.io/github/stars/zaocan/breakfast-order)"
2452
+ ],
2453
+ "after": [
2454
+ "# Corner Breakfast"
2455
+ ]
2456
+ }
2457
+ }
2458
+ },
2459
+ {
2460
+ "id": "LNK001",
2461
+ "block": null,
2462
+ "relatedBlocks": [
2463
+ "demo"
2464
+ ],
2465
+ "category": "links",
2466
+ "severity": "error",
2467
+ "types": [
2468
+ "web-app",
2469
+ "course-example",
2470
+ "portfolio",
2471
+ "backend-api"
2472
+ ],
2473
+ "needsProject": true,
2474
+ "status": "implemented",
2475
+ "title": {
2476
+ "zh-TW": "相對路徑的連結要連得到",
2477
+ "en": "Relative links point at real files"
2478
+ },
2479
+ "description": {
2480
+ "zh-TW": "連到專案裡其他檔案的連結(例如 `docs/api.md`、`LICENSE`),檔案要真的存在。",
2481
+ "en": "Links to other files in the project (for example `docs/api.md` or `LICENSE`) must point at files that exist."
2482
+ },
2483
+ "fix": {
2484
+ "zh-TW": "補上檔案,或改成正確的路徑(注意大小寫)。",
2485
+ "en": "Add the file or fix the path (mind upper and lower case)."
2486
+ },
2487
+ "messages": {
2488
+ "missing": {
2489
+ "zh-TW": "找不到連結的檔案 {path}",
2490
+ "en": "Linked file not found: {path}"
2491
+ }
2492
+ },
2493
+ "example": {
2494
+ "zh-TW": {
2495
+ "before": [
2496
+ "MIT,全文見 [LICENSE](LICENSE.md)。"
2497
+ ],
2498
+ "after": [
2499
+ "MIT,全文見 [LICENSE](LICENSE)。"
2500
+ ]
2501
+ },
2502
+ "en": {
2503
+ "before": [
2504
+ "MIT; see [LICENSE](LICENSE.md) for the full text."
2505
+ ],
2506
+ "after": [
2507
+ "MIT; see [LICENSE](LICENSE) for the full text."
2508
+ ]
2509
+ }
2510
+ }
2511
+ },
2512
+ {
2513
+ "id": "LNK002",
2514
+ "block": null,
2515
+ "category": "links",
2516
+ "severity": "error",
2517
+ "types": [
2518
+ "web-app",
2519
+ "course-example",
2520
+ "portfolio",
2521
+ "backend-api"
2522
+ ],
2523
+ "needsProject": false,
2524
+ "status": "planned",
2525
+ "title": {
2526
+ "zh-TW": "連到標題的連結要對得到",
2527
+ "en": "Links to headings reach a real heading"
2528
+ },
2529
+ "description": {
2530
+ "zh-TW": "`#安裝與執行` 這類連到同一份文件標題的連結,標題改名後就會失效。",
2531
+ "en": "Links such as `#getting-started` break when the heading is renamed."
2532
+ },
2533
+ "fix": {
2534
+ "zh-TW": "改成現在的標題。",
2535
+ "en": "Point it at the current heading."
2536
+ },
2537
+ "messages": {}
2538
+ },
2539
+ {
2540
+ "id": "LNK003",
2541
+ "block": null,
2542
+ "category": "links",
2543
+ "severity": "warning",
2544
+ "types": [
2545
+ "web-app",
2546
+ "course-example",
2547
+ "portfolio",
2548
+ "backend-api"
2549
+ ],
2550
+ "needsProject": false,
2551
+ "status": "planned",
2552
+ "title": {
2553
+ "zh-TW": "外部連結打得開",
2554
+ "en": "External links open"
2555
+ },
2556
+ "description": {
2557
+ "zh-TW": "連到其他網站的連結要打得開。這條要連網路,建議只在定期檢查時跑。",
2558
+ "en": "Links to other sites must open. This needs the network, so it is best run on a schedule."
2559
+ },
2560
+ "fix": {
2561
+ "zh-TW": "更新或移除失效的連結。",
2562
+ "en": "Update or remove broken links."
2563
+ },
2564
+ "messages": {}
2565
+ },
2566
+ {
2567
+ "id": "LNK004",
2568
+ "block": null,
2569
+ "relatedBlocks": [
2570
+ "demo"
2571
+ ],
2572
+ "category": "links",
2573
+ "severity": "warning",
2574
+ "types": [
2575
+ "web-app",
2576
+ "course-example",
2577
+ "portfolio",
2578
+ "backend-api"
2579
+ ],
2580
+ "needsProject": false,
2581
+ "status": "implemented",
2582
+ "title": {
2583
+ "zh-TW": "連結文字要說得出連去哪",
2584
+ "en": "Link text says where it goes"
2585
+ },
2586
+ "description": {
2587
+ "zh-TW": "「點這裡」「連結」「here」這種連結文字,用報讀軟體的人和 AI 都不知道會連去哪裡。",
2588
+ "en": "Link text such as \"click here\" or \"link\" tells screen reader users and AI nothing about the destination."
2589
+ },
2590
+ "fix": {
2591
+ "zh-TW": "改成說明目的地的文字,例如「線上展示(GitHub Pages)」。",
2592
+ "en": "Describe the destination instead, for example \"Live demo (GitHub Pages)\"."
2593
+ },
2594
+ "messages": {
2595
+ "vague": {
2596
+ "zh-TW": "連結文字「{text}」看不出會連去哪",
2597
+ "en": "Link text \"{text}\" does not say where it goes"
2598
+ }
2599
+ },
2600
+ "example": {
2601
+ "zh-TW": {
2602
+ "before": [
2603
+ "[點這裡](https://zaocan.github.io/breakfast-order/)看線上版本。"
2604
+ ],
2605
+ "after": [
2606
+ "[巷口早餐店線上點餐](https://zaocan.github.io/breakfast-order/)"
2607
+ ]
2608
+ },
2609
+ "en": {
2610
+ "before": [
2611
+ "[Click here](https://zaocan.github.io/breakfast-order/) to try it online."
2612
+ ],
2613
+ "after": [
2614
+ "[Corner Breakfast online ordering](https://zaocan.github.io/breakfast-order/)"
2615
+ ]
2616
+ }
2617
+ }
2618
+ },
2619
+ {
2620
+ "id": "LNK005",
2621
+ "block": null,
2622
+ "category": "links",
2623
+ "severity": "warning",
2624
+ "types": [
2625
+ "web-app",
2626
+ "course-example",
2627
+ "portfolio",
2628
+ "backend-api"
2629
+ ],
2630
+ "needsProject": false,
2631
+ "status": "planned",
2632
+ "title": {
2633
+ "zh-TW": "網址要做成有文字的連結",
2634
+ "en": "URLs are written as links with text"
2635
+ },
2636
+ "description": {
2637
+ "zh-TW": "直接貼一長串網址不好讀,改成 `[說明文字](網址)`。",
2638
+ "en": "A raw URL is hard to read; write `[description](url)` instead."
2639
+ },
2640
+ "fix": {
2641
+ "zh-TW": "加上連結文字。",
2642
+ "en": "Add link text."
2643
+ },
2644
+ "messages": {}
2645
+ },
2646
+ {
2647
+ "id": "LNK006",
2648
+ "block": null,
2649
+ "category": "links",
2650
+ "severity": "warning",
2651
+ "types": [
2652
+ "web-app",
2653
+ "course-example",
2654
+ "portfolio",
2655
+ "backend-api"
2656
+ ],
2657
+ "needsProject": true,
2658
+ "status": "planned",
2659
+ "title": {
2660
+ "zh-TW": "連到自己 repo 的檔案用相對路徑",
2661
+ "en": "Files in your own repository use relative links"
2662
+ },
2663
+ "description": {
2664
+ "zh-TW": "用完整網址連到自己 repo 的檔案,換分支或 fork 之後就會連錯。",
2665
+ "en": "Full URLs to files in your own repository point at the wrong place after a fork or a branch switch."
2666
+ },
2667
+ "fix": {
2668
+ "zh-TW": "改成相對路徑,例如 `docs/api.md`。",
2669
+ "en": "Use a relative path such as `docs/api.md`."
2670
+ },
2671
+ "messages": {}
2672
+ },
2673
+ {
2674
+ "id": "LIC001",
2675
+ "block": "license",
2676
+ "category": "license",
2677
+ "severity": "error",
2678
+ "types": [
2679
+ "web-app",
2680
+ "course-example",
2681
+ "portfolio",
2682
+ "backend-api"
2683
+ ],
2684
+ "needsProject": true,
2685
+ "status": "implemented",
2686
+ "title": {
2687
+ "zh-TW": "專案有授權,README 就要有「授權」章節",
2688
+ "en": "A licensed project has a License section"
2689
+ },
2690
+ "description": {
2691
+ "zh-TW": "專案根目錄有授權檔,或 package.json 的 `license` 寫了具體的授權,表示這是開放給別人用的專案,README 要有「授權」章節講清楚能怎麼用。公司內部或不公開的專案沒有授權檔、package.json 寫 `UNLICENSED`,可以不寫授權章節,這條不會提醒。另外,只有 package.json 寫 `ISC`、沒有授權檔時也不提醒,因為那是 npm 建立專案時自動填的預設值,不一定是刻意選的。",
2692
+ "en": "A license file at the project root, or a specific license in the `license` field of package.json, means the project is meant to be reused, so the README needs a License section saying how. Internal or private projects with no license file and `UNLICENSED` in package.json may leave the section out; this rule stays quiet for them. It also stays quiet when package.json says `ISC` and there is no license file, because npm fills that in by default."
2693
+ },
2694
+ "fix": {
2695
+ "zh-TW": "在 README 最後加上「## 授權」,寫出授權名稱並連到 `LICENSE` 檔。如果其實是內部專案,把 package.json 的 `license` 改成 `UNLICENSED`。",
2696
+ "en": "Add \"## License\" at the end of the README, naming the license and linking to the `LICENSE` file. If the project is actually internal, set `license` in package.json to `UNLICENSED`."
2697
+ },
2698
+ "messages": {
2699
+ "file": {
2700
+ "zh-TW": "專案有 {file} 檔({license}),README 卻沒有「授權」章節",
2701
+ "en": "The project has a {file} file ({license}), but the README has no License section"
2702
+ },
2703
+ "package": {
2704
+ "zh-TW": "package.json 的 license 是 {license},README 卻沒有「授權」章節",
2705
+ "en": "package.json says the license is {license}, but the README has no License section"
2706
+ }
2707
+ },
2708
+ "example": {
2709
+ "zh-TW": {
2710
+ "before": [],
2711
+ "after": [
2712
+ "## 授權",
2713
+ "",
2714
+ "MIT,全文見 [LICENSE](LICENSE)。"
2715
+ ]
2716
+ },
2717
+ "en": {
2718
+ "before": [],
2719
+ "after": [
2720
+ "## License",
2721
+ "",
2722
+ "MIT; see [LICENSE](LICENSE) for the full text."
2723
+ ]
2724
+ }
2725
+ }
2726
+ },
2727
+ {
2728
+ "id": "LIC002",
2729
+ "block": "license",
2730
+ "category": "license",
2731
+ "severity": "error",
2732
+ "types": [
2733
+ "web-app",
2734
+ "course-example",
2735
+ "portfolio",
2736
+ "backend-api"
2737
+ ],
2738
+ "needsProject": true,
2739
+ "status": "implemented",
2740
+ "title": {
2741
+ "zh-TW": "授權在三個地方要一致",
2742
+ "en": "The license agrees in all three places"
2743
+ },
2744
+ "description": {
2745
+ "zh-TW": "README 的「授權」、`LICENSE` 檔、package.json 的 `license`,寫的要是同一種授權。對不上的話,別人不知道到底能不能用。",
2746
+ "en": "The README's License section, the `LICENSE` file and `license` in package.json must name the same license; otherwise nobody knows what is allowed."
2747
+ },
2748
+ "fix": {
2749
+ "zh-TW": "以 LICENSE 檔為準,把另外兩處改成一樣。",
2750
+ "en": "Treat the LICENSE file as the reference and make the other two match it."
2751
+ },
2752
+ "messages": {
2753
+ "mismatch": {
2754
+ "zh-TW": "授權對不上:{details}",
2755
+ "en": "The license does not match: {details}"
2756
+ }
2757
+ },
2758
+ "example": {
2759
+ "zh-TW": {
2760
+ "before": [
2761
+ "## 授權",
2762
+ "",
2763
+ "Apache-2.0"
2764
+ ],
2765
+ "after": [
2766
+ "## 授權",
2767
+ "",
2768
+ "MIT,全文見 [LICENSE](LICENSE)。"
2769
+ ]
2770
+ },
2771
+ "en": {
2772
+ "before": [
2773
+ "## License",
2774
+ "",
2775
+ "Apache-2.0"
2776
+ ],
2777
+ "after": [
2778
+ "## License",
2779
+ "",
2780
+ "MIT; see [LICENSE](LICENSE) for the full text."
2781
+ ]
2782
+ }
2783
+ }
2784
+ },
2785
+ {
2786
+ "id": "LIC003",
2787
+ "block": "license",
2788
+ "category": "license",
2789
+ "severity": "warning",
2790
+ "types": [
2791
+ "web-app",
2792
+ "course-example",
2793
+ "portfolio",
2794
+ "backend-api"
2795
+ ],
2796
+ "needsProject": true,
2797
+ "status": "implemented",
2798
+ "title": {
2799
+ "zh-TW": "寫了授權就要有 LICENSE 檔",
2800
+ "en": "A named license comes with a LICENSE file"
2801
+ },
2802
+ "description": {
2803
+ "zh-TW": "README 寫了開放授權(例如 MIT),專案裡也要有 `LICENSE` 檔放授權全文,GitHub 才認得出來。不開放的話,直接寫「保留所有權利」。",
2804
+ "en": "If the README names an open license (for example MIT), the project needs a `LICENSE` file with the full text so GitHub recognizes it. If it is not open, say \"All rights reserved\"."
2805
+ },
2806
+ "fix": {
2807
+ "zh-TW": "在專案根目錄加 `LICENSE` 檔;不開放就把 README 的授權改成「保留所有權利」。",
2808
+ "en": "Add a `LICENSE` file at the project root, or change the README to \"All rights reserved\" if it is not open."
2809
+ },
2810
+ "messages": {
2811
+ "missing": {
2812
+ "zh-TW": "README 寫了授權({license}),專案裡卻沒有 LICENSE 檔",
2813
+ "en": "The README names a license ({license}), but there is no LICENSE file"
2814
+ }
2815
+ }
2816
+ },
2817
+ {
2818
+ "id": "LIC004",
2819
+ "block": "license",
2820
+ "category": "license",
2821
+ "severity": "warning",
2822
+ "types": [
2823
+ "web-app",
2824
+ "course-example",
2825
+ "portfolio",
2826
+ "backend-api"
2827
+ ],
2828
+ "needsProject": true,
2829
+ "status": "planned",
2830
+ "title": {
2831
+ "zh-TW": "歡迎別人貢獻,就要寫授權",
2832
+ "en": "Accepting contributions needs a license"
2833
+ },
2834
+ "description": {
2835
+ "zh-TW": "README 有「貢獻方式」,表示歡迎別人一起改程式;但專案和 README 都找不到授權,別人依法不能使用這份程式碼,也不知道自己的修改會怎麼被使用。",
2836
+ "en": "A Contributing section invites others to change the code, but with no license anywhere in the project or the README, nobody may legally reuse it, and contributors do not know how their changes will be used."
2837
+ },
2838
+ "fix": {
2839
+ "zh-TW": "選一種授權,加上 `LICENSE` 檔與「授權」章節;不打算開放的話,拿掉「貢獻方式」。",
2840
+ "en": "Pick a license and add a `LICENSE` file and a License section, or remove the Contributing section if the project is not open."
2841
+ },
2842
+ "messages": {}
2843
+ },
2844
+ {
2845
+ "id": "META001",
2846
+ "block": "title",
2847
+ "category": "structure",
2848
+ "severity": "warning",
2849
+ "types": [
2850
+ "web-app",
2851
+ "course-example",
2852
+ "portfolio",
2853
+ "backend-api"
2854
+ ],
2855
+ "needsProject": true,
2856
+ "status": "planned",
2857
+ "title": {
2858
+ "zh-TW": "一句話說明跟 package.json 的 description 一致",
2859
+ "en": "The description matches package.json"
2860
+ },
2861
+ "description": {
2862
+ "zh-TW": "一句話說明、package.json 的 `description`、GitHub repo 的描述最好是同一句。",
2863
+ "en": "The one-line description, `description` in package.json and the repository description should say the same thing."
2864
+ },
2865
+ "fix": {
2866
+ "zh-TW": "三處改成同一句。",
2867
+ "en": "Use the same sentence in all three."
2868
+ },
2869
+ "messages": {}
2870
+ },
2871
+ {
2872
+ "id": "META002",
2873
+ "block": "title",
2874
+ "category": "structure",
2875
+ "severity": "warning",
2876
+ "types": [
2877
+ "web-app",
2878
+ "course-example",
2879
+ "portfolio",
2880
+ "backend-api"
2881
+ ],
2882
+ "needsProject": true,
2883
+ "status": "planned",
2884
+ "title": {
2885
+ "zh-TW": "標題對得到 repo 名稱",
2886
+ "en": "The title can be matched to the repository name"
2887
+ },
2888
+ "description": {
2889
+ "zh-TW": "標題跟 repo 名稱差很多時(例如中文名稱),在標題後面用括號附上 repo 名稱,AI 才知道要進哪個資料夾。",
2890
+ "en": "If the title differs a lot from the repository name, add the repository name in brackets so AI knows which folder it is."
2891
+ },
2892
+ "fix": {
2893
+ "zh-TW": "在標題後面加上(`repo 名稱`)。",
2894
+ "en": "Add (`repo-name`) after the title."
2895
+ },
2896
+ "messages": {}
2897
+ },
2898
+ {
2899
+ "id": "LANG001",
2900
+ "block": null,
2901
+ "category": "language",
2902
+ "severity": "warning",
2903
+ "types": [
2904
+ "web-app",
2905
+ "course-example",
2906
+ "portfolio",
2907
+ "backend-api"
2908
+ ],
2909
+ "needsProject": true,
2910
+ "status": "planned",
2911
+ "title": {
2912
+ "zh-TW": "翻譯版的檔名用語言代碼",
2913
+ "en": "Translated files use language codes"
2914
+ },
2915
+ "description": {
2916
+ "zh-TW": "其他語言的版本命名成 `README.en.md`、`README.zh-TW.md`。",
2917
+ "en": "Name translated versions like `README.en.md` or `README.zh-TW.md`."
2918
+ },
2919
+ "fix": {
2920
+ "zh-TW": "改檔名。",
2921
+ "en": "Rename the file."
2922
+ },
2923
+ "messages": {}
2924
+ },
2925
+ {
2926
+ "id": "LANG002",
2927
+ "block": null,
2928
+ "category": "language",
2929
+ "severity": "warning",
2930
+ "types": [
2931
+ "web-app",
2932
+ "course-example",
2933
+ "portfolio",
2934
+ "backend-api"
2935
+ ],
2936
+ "needsProject": true,
2937
+ "status": "planned",
2938
+ "title": {
2939
+ "zh-TW": "各語言版本的章節一致",
2940
+ "en": "Language versions have the same sections"
2941
+ },
2942
+ "description": {
2943
+ "zh-TW": "不同語言的 README 章節數量與順序要一樣,而且互相連結。",
2944
+ "en": "README files in different languages have the same sections in the same order and link to each other."
2945
+ },
2946
+ "fix": {
2947
+ "zh-TW": "補齊章節並互相加上連結。",
2948
+ "en": "Add the missing sections and link the versions."
2949
+ },
2950
+ "messages": {}
2951
+ },
2952
+ {
2953
+ "id": "LANG003",
2954
+ "block": null,
2955
+ "category": "language",
2956
+ "severity": "warning",
2957
+ "types": [
2958
+ "web-app",
2959
+ "course-example",
2960
+ "portfolio",
2961
+ "backend-api"
2962
+ ],
2963
+ "needsProject": false,
2964
+ "status": "planned",
2965
+ "title": {
2966
+ "zh-TW": "用台灣的繁體中文用語",
2967
+ "en": "Use Taiwanese Traditional Chinese terms"
2968
+ },
2969
+ "description": {
2970
+ "zh-TW": "繁體中文版不要出現簡體字和大陸用語,要用「資訊」「預設」「專案」這類台灣用語。",
2971
+ "en": "The Traditional Chinese version should avoid Simplified characters and mainland terms."
2972
+ },
2973
+ "fix": {
2974
+ "zh-TW": "換成台灣用語。",
2975
+ "en": "Use the Taiwanese term."
2976
+ },
2977
+ "messages": {}
2978
+ },
2979
+ {
2980
+ "id": "LANG004",
2981
+ "block": null,
2982
+ "category": "language",
2983
+ "severity": "warning",
2984
+ "types": [
2985
+ "web-app",
2986
+ "course-example",
2987
+ "portfolio",
2988
+ "backend-api"
2989
+ ],
2990
+ "needsProject": false,
2991
+ "status": "planned",
2992
+ "title": {
2993
+ "zh-TW": "中英文之間的空格一致(預設關閉)",
2994
+ "en": "Consistent spacing between Chinese and English (off by default)"
2995
+ },
2996
+ "description": {
2997
+ "zh-TW": "中文與英文、數字之間要不要空一格,各團隊習慣不同。這條預設不檢查,專案要用再打開。",
2998
+ "en": "Teams differ on spacing between Chinese and English text, so this is off unless a project turns it on."
2999
+ },
3000
+ "fix": {
3001
+ "zh-TW": "整份文件用同一種寫法。",
3002
+ "en": "Use one style throughout."
3003
+ },
3004
+ "messages": {}
3005
+ },
3006
+ {
3007
+ "id": "AIR001",
3008
+ "block": null,
3009
+ "category": "ai-readability",
3010
+ "severity": "warning",
3011
+ "types": [
3012
+ "web-app",
3013
+ "course-example",
3014
+ "portfolio",
3015
+ "backend-api"
3016
+ ],
3017
+ "needsProject": false,
3018
+ "status": "implemented",
3019
+ "title": {
3020
+ "zh-TW": "不要寫「如上所述」",
3021
+ "en": "Do not write \"as mentioned above\""
3022
+ },
3023
+ "description": {
3024
+ "zh-TW": "「如上所述」「同上」「as mentioned above」這類說法,段落被單獨拿出來讀就看不懂。AI 常常只讀其中一段。",
3025
+ "en": "Phrases like \"as mentioned above\" or \"see above\" make no sense when a section is read on its own, and AI often reads just one section."
3026
+ },
3027
+ "fix": {
3028
+ "zh-TW": "直接寫出指的是哪裡,例如「照『安裝步驟』的第 3 步」。",
3029
+ "en": "Name what you mean, for example \"step 3 of Installation\"."
3030
+ },
3031
+ "messages": {
3032
+ "found": {
3033
+ "zh-TW": "「{text}」沒說清楚指的是哪裡",
3034
+ "en": "\"{text}\" does not say what it refers to"
3035
+ }
3036
+ },
3037
+ "example": {
3038
+ "zh-TW": {
3039
+ "before": [
3040
+ "如上所述,打開網址就可以了。"
3041
+ ],
3042
+ "after": [
3043
+ "打開 http://localhost:5173,看到菜單就成功了。"
3044
+ ]
3045
+ },
3046
+ "en": {
3047
+ "before": [
3048
+ "As mentioned above, open the address and you are done."
3049
+ ],
3050
+ "after": [
3051
+ "Open http://localhost:5173 in your browser; once you see the menu, it is running."
3052
+ ]
3053
+ }
3054
+ }
3055
+ },
3056
+ {
3057
+ "id": "AIR002",
3058
+ "block": null,
3059
+ "category": "ai-readability",
3060
+ "severity": "warning",
3061
+ "types": [
3062
+ "web-app",
3063
+ "course-example",
3064
+ "portfolio",
3065
+ "backend-api"
3066
+ ],
3067
+ "needsProject": false,
3068
+ "status": "planned",
3069
+ "title": {
3070
+ "zh-TW": "不要寫模糊的動作",
3071
+ "en": "No vague instructions"
3072
+ },
3073
+ "description": {
3074
+ "zh-TW": "「安裝相關套件」「適當設定」「自行調整」沒說要做什麼,人和 AI 都只能用猜的。",
3075
+ "en": "\"Install the relevant packages\" or \"configure as needed\" does not say what to do, so people and AI have to guess."
3076
+ },
3077
+ "fix": {
3078
+ "zh-TW": "寫出具體的指令或設定值。",
3079
+ "en": "Give the exact command or value."
3080
+ },
3081
+ "messages": {}
3082
+ },
3083
+ {
3084
+ "id": "AIR003",
3085
+ "block": null,
3086
+ "category": "ai-readability",
3087
+ "severity": "warning",
3088
+ "types": [
3089
+ "web-app",
3090
+ "course-example",
3091
+ "portfolio",
3092
+ "backend-api"
3093
+ ],
3094
+ "needsProject": false,
3095
+ "status": "planned",
3096
+ "title": {
3097
+ "zh-TW": "章節不要只有圖片",
3098
+ "en": "A section is not only images"
3099
+ },
3100
+ "description": {
3101
+ "zh-TW": "整個章節只有圖片,看不到圖的人和 AI 就什麼都拿不到。",
3102
+ "en": "A section with only images gives nothing to people who cannot see them, or to AI."
3103
+ },
3104
+ "fix": {
3105
+ "zh-TW": "在圖片下面補一句文字說明重點。",
3106
+ "en": "Add a sentence under the image with the key point."
3107
+ },
3108
+ "messages": {}
3109
+ },
3110
+ {
3111
+ "id": "AIR004",
3112
+ "block": "install",
3113
+ "category": "ai-readability",
3114
+ "severity": "warning",
3115
+ "types": [
3116
+ "web-app",
3117
+ "course-example",
3118
+ "portfolio",
3119
+ "backend-api"
3120
+ ],
3121
+ "needsProject": false,
3122
+ "status": "planned",
3123
+ "title": {
3124
+ "zh-TW": "同一步只給一種做法",
3125
+ "en": "One way to do each step"
3126
+ },
3127
+ "description": {
3128
+ "zh-TW": "同一步驟同時給 npm、yarn、pnpm 三種指令,新手和 AI 都要多做選擇,也容易混著用。",
3129
+ "en": "Giving npm, yarn and pnpm commands for the same step forces newcomers and AI to choose, and invites mixing them."
3130
+ },
3131
+ "fix": {
3132
+ "zh-TW": "只留專案用的那一種。",
3133
+ "en": "Keep only the one the project uses."
3134
+ },
3135
+ "messages": {}
3136
+ },
3137
+ {
3138
+ "id": "AIR005",
3139
+ "block": null,
3140
+ "category": "ai-readability",
3141
+ "severity": "warning",
3142
+ "types": [
3143
+ "web-app",
3144
+ "course-example",
3145
+ "portfolio",
3146
+ "backend-api"
3147
+ ],
3148
+ "needsProject": false,
3149
+ "status": "implemented",
3150
+ "title": {
3151
+ "zh-TW": "README 不要寫對 AI 說話的句子",
3152
+ "en": "No instructions aimed at AI in the README"
3153
+ },
3154
+ "description": {
3155
+ "zh-TW": "「你是一個資深工程師」「You are a senior engineer」這種給 AI 的指示不要寫進 README,人讀起來很怪。真的需要,另外放在專門給 AI 的說明檔。",
3156
+ "en": "Lines like \"You are a senior engineer\" are instructions for AI and read oddly to people. If you need them, put them in a separate file meant for AI."
3157
+ },
3158
+ "fix": {
3159
+ "zh-TW": "刪掉這句,改寫成給人看的說明。",
3160
+ "en": "Remove it or rewrite it as an explanation for people."
3161
+ },
3162
+ "messages": {
3163
+ "found": {
3164
+ "zh-TW": "「{text}」是對 AI 說話的句子",
3165
+ "en": "\"{text}\" is an instruction aimed at AI"
3166
+ }
3167
+ },
3168
+ "example": {
3169
+ "zh-TW": {
3170
+ "before": [
3171
+ "## 作者與聯絡",
3172
+ "",
3173
+ "你是一位資深前端工程師,請幫忙維護這個專案。",
3174
+ "",
3175
+ "是 Ray 不是 Array|hello@example.com"
3176
+ ],
3177
+ "after": [
3178
+ "## 作者與聯絡",
3179
+ "",
3180
+ "是 Ray 不是 Array|hello@example.com"
3181
+ ]
3182
+ },
3183
+ "en": {
3184
+ "before": [
3185
+ "## Author",
3186
+ "",
3187
+ "You are a senior frontend engineer. Keep this project up to date.",
3188
+ "",
3189
+ "是 Ray 不是 Array | hello@example.com"
3190
+ ],
3191
+ "after": [
3192
+ "## Author",
3193
+ "",
3194
+ "是 Ray 不是 Array | hello@example.com"
3195
+ ]
3196
+ }
3197
+ }
3198
+ },
3199
+ {
3200
+ "id": "AIR006",
3201
+ "block": null,
3202
+ "category": "ai-readability",
3203
+ "severity": "warning",
3204
+ "types": [
3205
+ "web-app",
3206
+ "course-example",
3207
+ "portfolio",
3208
+ "backend-api"
3209
+ ],
3210
+ "needsProject": false,
3211
+ "status": "planned",
3212
+ "title": {
3213
+ "zh-TW": "篇幅不要太長",
3214
+ "en": "Keep the length reasonable"
3215
+ },
3216
+ "description": {
3217
+ "zh-TW": "README 太長,人讀不完,AI 也比較容易漏看。細節可以移到 `docs/` 再連過去。",
3218
+ "en": "A very long README is not read to the end, and AI misses more of it. Move details to `docs/` and link to them."
3219
+ },
3220
+ "fix": {
3221
+ "zh-TW": "把細節移到其他文件。",
3222
+ "en": "Move details to other documents."
3223
+ },
3224
+ "messages": {}
3225
+ },
3226
+ {
3227
+ "id": "TYPE-API001",
3228
+ "block": "demo",
3229
+ "category": "type-specific",
3230
+ "severity": "error",
3231
+ "types": [
3232
+ "backend-api"
3233
+ ],
3234
+ "needsProject": false,
3235
+ "status": "implemented",
3236
+ "title": {
3237
+ "zh-TW": "寫出 API 文件在哪",
3238
+ "en": "Say where the API documentation is"
3239
+ },
3240
+ "description": {
3241
+ "zh-TW": "後端 API 的讀者第一個要找的是 API 文件:本機跑起來在哪個網址、線上版在哪裡。",
3242
+ "en": "Readers of a backend API first look for its documentation: the local address once it runs, and the online version."
3243
+ },
3244
+ "fix": {
3245
+ "zh-TW": "加一個「API 文件」章節,寫出本機與線上的網址。",
3246
+ "en": "Add an API Documentation section with the local and online addresses."
3247
+ },
3248
+ "messages": {
3249
+ "missing": {
3250
+ "zh-TW": "沒寫 API 文件在哪",
3251
+ "en": "Does not say where the API documentation is"
3252
+ }
3253
+ },
3254
+ "example": {
3255
+ "zh-TW": {
3256
+ "before": [],
3257
+ "after": [
3258
+ "## API 文件",
3259
+ "",
3260
+ "本機啟動後打開 http://localhost:3000/api-docs,可以看到每支 API 的說明並直接試打。"
3261
+ ]
3262
+ },
3263
+ "en": {
3264
+ "before": [],
3265
+ "after": [
3266
+ "## API Documentation",
3267
+ "",
3268
+ "Start the server and open http://localhost:3000/api-docs to read about every endpoint and try it out."
3269
+ ]
3270
+ }
3271
+ }
3272
+ },
3273
+ {
3274
+ "id": "TYPE-API002",
3275
+ "block": "install",
3276
+ "category": "type-specific",
3277
+ "severity": "error",
3278
+ "types": [
3279
+ "backend-api"
3280
+ ],
3281
+ "needsProject": true,
3282
+ "status": "implemented",
3283
+ "title": {
3284
+ "zh-TW": "寫出怎麼建立資料庫",
3285
+ "en": "Explain how to set up the database"
3286
+ },
3287
+ "description": {
3288
+ "zh-TW": "專案有資料庫的設定,README 就要寫建立資料表、放入測試資料的指令,不然跑起來會因為沒有資料表而失敗。",
3289
+ "en": "If the project has database setup files, the README must give the commands that create the tables and load sample data; otherwise it fails on the first request."
3290
+ },
3291
+ "fix": {
3292
+ "zh-TW": "加一個「建立資料庫」章節,把建立資料表、放入測試資料的指令放進程式碼區塊,一行一個。",
3293
+ "en": "Add a Database Setup section with the commands that create the tables and load sample data in a code block, one per line."
3294
+ },
3295
+ "messages": {
3296
+ "missing": {
3297
+ "zh-TW": "專案有資料庫設定({evidence}),README 沒寫怎麼建立資料庫",
3298
+ "en": "The project has database setup ({evidence}), but the README does not explain how to set it up"
3299
+ }
3300
+ },
3301
+ "example": {
3302
+ "zh-TW": {
3303
+ "before": [],
3304
+ "after": [
3305
+ "## 建立資料庫",
3306
+ "",
3307
+ "```bash",
3308
+ "pnpm db:migrate",
3309
+ "```"
3310
+ ]
3311
+ },
3312
+ "en": {
3313
+ "before": [],
3314
+ "after": [
3315
+ "## Database Setup",
3316
+ "",
3317
+ "```bash",
3318
+ "pnpm db:migrate",
3319
+ "```"
3320
+ ]
3321
+ }
3322
+ }
3323
+ },
3324
+ {
3325
+ "id": "TYPE-API003",
3326
+ "block": "install",
3327
+ "category": "type-specific",
3328
+ "severity": "warning",
3329
+ "types": [
3330
+ "backend-api"
3331
+ ],
3332
+ "needsProject": false,
3333
+ "status": "implemented",
3334
+ "title": {
3335
+ "zh-TW": "至少一個請求範例",
3336
+ "en": "At least one request example"
3337
+ },
3338
+ "description": {
3339
+ "zh-TW": "放一個可以直接複製的請求範例(例如 `curl`),再用另一個區塊放回應,讀者和 AI 馬上知道怎麼呼叫。",
3340
+ "en": "Include one request people can copy (for example `curl`) and the response in a separate block, so readers and AI see how to call it."
3341
+ },
3342
+ "fix": {
3343
+ "zh-TW": "在「使用方式」放一個 `curl` 範例和它的回應。",
3344
+ "en": "Add a `curl` example and its response under Usage."
3345
+ },
3346
+ "messages": {
3347
+ "missing": {
3348
+ "zh-TW": "沒有任何請求範例(例如 curl 指令)",
3349
+ "en": "No request example (for example a curl command)"
3350
+ }
3351
+ },
3352
+ "example": {
3353
+ "zh-TW": {
3354
+ "before": [
3355
+ "## 使用方式",
3356
+ "",
3357
+ "打開 `/api/menu` 就會拿到菜單。"
3358
+ ],
3359
+ "after": [
3360
+ "## 使用方式",
3361
+ "",
3362
+ "```bash",
3363
+ "curl http://localhost:3000/api/menu",
3364
+ "```"
3365
+ ]
3366
+ },
3367
+ "en": {
3368
+ "before": [
3369
+ "## Usage",
3370
+ "",
3371
+ "Open `/api/menu` to get the menu."
3372
+ ],
3373
+ "after": [
3374
+ "## Usage",
3375
+ "",
3376
+ "```bash",
3377
+ "curl http://localhost:3000/api/menu",
3378
+ "```"
3379
+ ]
3380
+ }
3381
+ }
3382
+ },
3383
+ {
3384
+ "id": "TYPE-API004",
3385
+ "block": "install",
3386
+ "category": "type-specific",
3387
+ "severity": "warning",
3388
+ "types": [
3389
+ "backend-api"
3390
+ ],
3391
+ "needsProject": false,
3392
+ "status": "planned",
3393
+ "title": {
3394
+ "zh-TW": "請求和回應分開放",
3395
+ "en": "Request and response in separate blocks"
3396
+ },
3397
+ "description": {
3398
+ "zh-TW": "請求指令和回應的內容放在同一個區塊,複製時會連回應一起貼。",
3399
+ "en": "With request and response in one block, copying the command also copies the response."
3400
+ },
3401
+ "fix": {
3402
+ "zh-TW": "拆成兩個區塊。",
3403
+ "en": "Split them into two blocks."
3404
+ },
3405
+ "messages": {}
3406
+ },
3407
+ {
3408
+ "id": "TYPE-PF001",
3409
+ "block": "features",
3410
+ "category": "type-specific",
3411
+ "severity": "warning",
3412
+ "types": [
3413
+ "portfolio"
3414
+ ],
3415
+ "needsProject": false,
3416
+ "status": "implemented",
3417
+ "title": {
3418
+ "zh-TW": "寫出「我負責的部分」",
3419
+ "en": "Include \"My Role\""
3420
+ },
3421
+ "description": {
3422
+ "zh-TW": "作品集的讀者想知道你做了什麼。團隊專案一定要寫自己負責的功能或頁面;一個人做的也寫一句「全部由我獨立完成」。",
3423
+ "en": "Portfolio readers want to know what you did. In a team project list your own features or pages; for a solo project say you built all of it."
3424
+ },
3425
+ "fix": {
3426
+ "zh-TW": "加一個「我負責的部分」章節。",
3427
+ "en": "Add a \"My Role\" section."
3428
+ },
3429
+ "messages": {
3430
+ "missing": {
3431
+ "zh-TW": "沒有「我負責的部分」",
3432
+ "en": "No \"My Role\" section"
3433
+ }
3434
+ },
3435
+ "example": {
3436
+ "zh-TW": {
3437
+ "before": [],
3438
+ "after": [
3439
+ "## 我負責的部分",
3440
+ "",
3441
+ "- 點餐頁與購物車的畫面和程式",
3442
+ "- 取餐時間的計算與測試"
3443
+ ]
3444
+ },
3445
+ "en": {
3446
+ "before": [],
3447
+ "after": [
3448
+ "## My Role",
3449
+ "",
3450
+ "- The order page and cart, both screens and code",
3451
+ "- Pickup time calculation and its tests"
3452
+ ]
3453
+ }
3454
+ }
3455
+ },
3456
+ {
3457
+ "id": "TYPE-PF002",
3458
+ "block": "tech",
3459
+ "category": "type-specific",
3460
+ "severity": "warning",
3461
+ "types": [
3462
+ "portfolio"
3463
+ ],
3464
+ "needsProject": false,
3465
+ "status": "implemented",
3466
+ "title": {
3467
+ "zh-TW": "寫出「為什麼這樣做」",
3468
+ "en": "Include \"Design Decisions\""
3469
+ },
3470
+ "description": {
3471
+ "zh-TW": "選這個框架、這種做法的理由與取捨,最能讓作品跟別人不一樣。",
3472
+ "en": "Why you chose this framework or approach, and what you traded off, is what sets the work apart."
3473
+ },
3474
+ "fix": {
3475
+ "zh-TW": "加一個「為什麼這樣做」章節,寫一兩個決定和理由。",
3476
+ "en": "Add a \"Design Decisions\" section with one or two decisions and why."
3477
+ },
3478
+ "messages": {
3479
+ "missing": {
3480
+ "zh-TW": "沒有「為什麼這樣做」",
3481
+ "en": "No \"Design Decisions\" section"
3482
+ }
3483
+ },
3484
+ "example": {
3485
+ "zh-TW": {
3486
+ "before": [],
3487
+ "after": [
3488
+ "## 為什麼這樣做",
3489
+ "",
3490
+ "購物車的金額只在一個函式裡算,畫面只負責顯示,金額算錯時只要查一個地方。"
3491
+ ]
3492
+ },
3493
+ "en": {
3494
+ "before": [],
3495
+ "after": [
3496
+ "## Design Decisions",
3497
+ "",
3498
+ "Cart totals are calculated in one function and the screens only display them, so a wrong total means checking one place."
3499
+ ]
3500
+ }
3501
+ }
3502
+ },
3503
+ {
3504
+ "id": "TYPE-CS002",
3505
+ "block": "features",
3506
+ "category": "type-specific",
3507
+ "severity": "warning",
3508
+ "types": [
3509
+ "course-example"
3510
+ ],
3511
+ "needsProject": false,
3512
+ "status": "implemented",
3513
+ "title": {
3514
+ "zh-TW": "寫出對應的課程單元",
3515
+ "en": "Say which lesson it belongs to"
3516
+ },
3517
+ "description": {
3518
+ "zh-TW": "課程範例要寫對應哪一堂課、哪一週,學生才知道要配哪一段內容看。",
3519
+ "en": "A course example should say which lesson or week it belongs to, so students know what to watch or read with it."
3520
+ },
3521
+ "fix": {
3522
+ "zh-TW": "加一個「對應單元」章節,寫課程名稱與第幾週或第幾單元。",
3523
+ "en": "Add a Course Unit section with the course name and the week or lesson."
3524
+ },
3525
+ "messages": {
3526
+ "missing": {
3527
+ "zh-TW": "沒寫對應哪一個課程單元",
3528
+ "en": "Does not say which lesson it belongs to"
3529
+ }
3530
+ },
3531
+ "example": {
3532
+ "zh-TW": {
3533
+ "before": [],
3534
+ "after": [
3535
+ "## 對應單元",
3536
+ "",
3537
+ "前端入門課第 3 週:用 Vue 做購物車。"
3538
+ ]
3539
+ },
3540
+ "en": {
3541
+ "before": [],
3542
+ "after": [
3543
+ "## Course Unit",
3544
+ "",
3545
+ "Week 3 of the intro front-end course: building a cart with Vue."
3546
+ ]
3547
+ }
3548
+ }
3549
+ },
3550
+ {
3551
+ "id": "TYPE-CS003",
3552
+ "block": "install",
3553
+ "category": "type-specific",
3554
+ "severity": "warning",
3555
+ "types": [
3556
+ "course-example"
3557
+ ],
3558
+ "needsProject": true,
3559
+ "status": "planned",
3560
+ "title": {
3561
+ "zh-TW": "有起始版和完成版就說明怎麼切換",
3562
+ "en": "Explain how to switch between starter and solution"
3563
+ },
3564
+ "description": {
3565
+ "zh-TW": "專案有 `start`、`finish` 這類分支或資料夾時,README 要說明哪個是起點、哪個是完成版、怎麼切換。",
3566
+ "en": "If the project has starter and solution branches or folders, the README should say which is which and how to switch."
3567
+ },
3568
+ "fix": {
3569
+ "zh-TW": "加一個「起始版與完成版」章節。",
3570
+ "en": "Add a Starter and Solution section."
3571
+ },
3572
+ "messages": {}
3573
+ }
3574
+ ]
3575
+ }