jiantw83
f4e489ceb4
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與 「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上 看起來像普通文字或死連結，巡不到也修不了。 連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API， 不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把 好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁 整批判死。
86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 交付：{計畫名稱} {WP-nn} {工作包名稱}
|
||
|
||
> {ANALYZE 頁絕對網址} 由 `jsc-gitea/tools/gitea.sh wiki-url` 取得。
|
||
> 連結寫法：一律寫成 `[{文字}]({連結})`，連結一律用絕對網址，不自行組路徑，也不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`：後者只在同一個 wiki 內解析，寫錯不會報錯，畫面上看起來像純文字或死連結，巡不到也修不了。
|
||
> 寫入前驗證：要放進本頁的每一個連結先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫入。有一筆 DEAD 就不寫，把連不到的清單回報給呼叫端。驗證走 API，不看網頁狀態碼：私有存取庫的網頁網址對沒帶金鑰的請求一律回 404，照狀態碼判會把還活著的頁判成死連結。結束碼 `1`=至少一筆連不到、`2`=一個網址都沒給、`3`=`GITEA_HOST` 未設定、`7`=金鑰失效，停下回報金鑰問題，不得當成連不到。
|
||
|
||
- 頁名：`DELIVER_{HASH}`
|
||
- HASH：`{HASH}`
|
||
- 對應分析：[ANALYZE_{HASH}]({ANALYZE 頁絕對網址})
|
||
- 存取庫：`{owner}/{repo}`
|
||
- 來源分支（＝PR 目標）：`origin/{來源分支}`
|
||
- 工作證：`TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`
|
||
- 交付工作包：是 <!-- 是 | 否 -->
|
||
- 交付型別：API 文件 <!-- API 文件 | 由使用者輸入：{說明} -->
|
||
- 交付時間：{yyyy-MM-dd HH:mm:ss}
|
||
|
||
## 交付內容
|
||
|
||
| 項目 | 說明 |
|
||
| --- | --- |
|
||
| 這次交付什麼 | {一句話講清楚接手者拿到什麼} |
|
||
| 接手者需要做什麼 | {下一步動作；沒有就寫「無」} |
|
||
| 尚未交付的部分 | {留在候補的實作工作包，或寫「無」} |
|
||
|
||
## API 文件
|
||
|
||
<!-- 交付型別為「由使用者輸入」時，本節改成使用者指定的內容，不套下面的格式。 -->
|
||
|
||
### {方法} {端點路徑}
|
||
|
||
- 端點狀態：本次新增 <!-- 本次新增 | 既有端點 -->
|
||
- 說明：{這個端點做什麼}
|
||
|
||
標示規則：🆕 **新增**、⚠️ **變更**、❌ **移除**（含淘汰時程）、既有參數留空。
|
||
資料來源：`真實：{source}` 或 `推論：無來源`。範例只留格式，個資不留值。
|
||
|
||
#### 輸入參數（全部）
|
||
|
||
| 參數 | 位置 | 型別 | 必填 | 範例 | 資料來源 | 狀態 |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| {name} | path／query／header／body | {型別} | 是、否 | {值} | 真實：{source} | 🆕 **新增** |
|
||
|
||
#### 輸出參數（全部）
|
||
|
||
| 參數 | 型別 | 說明 | 範例 | 資料來源 | 狀態 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| {name} | {型別} | {說明} | {值} | 真實：{source} | |
|
||
|
||
#### 錯誤回應
|
||
|
||
| 狀態碼 | 條件 | 回應結構 |
|
||
| --- | --- | --- |
|
||
| {400} | {條件} | {結構} |
|
||
|
||
#### 新舊差異
|
||
|
||
<!-- 既有端點必附；本次新增的端點可省略。diff 區塊會被 Gitea 上色，不要用 HTML style。 -->
|
||
|
||
```diff
|
||
{方法} {端點路徑}
|
||
{既有參數} {型別} {必填}
|
||
+ {新增參數} {型別} {必填} {預設值}（本次新增）
|
||
- {移除參數} {型別} {必填} （本次移除，{日期} 前相容）
|
||
! {變更參數} {型別} {必填} （本次變更：{變更內容}）
|
||
```
|
||
|
||
### 驗收條件
|
||
|
||
- [ ] {可驗證的條件}
|
||
|
||
## 變更檔案
|
||
|
||
| 檔案 | 變更 |
|
||
| --- | --- |
|
||
| `{path}` | {做了什麼} |
|
||
|
||
## 驗證方式
|
||
|
||
| 項目 | 指令或步驟 | 結果 |
|
||
| --- | --- | --- |
|
||
| {測試} | `{指令}` | {通過、失敗} |
|
||
|
||
## 已知限制
|
||
|
||
- {限制或風險；沒有就寫「無」}
|