49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# Agent 規範（重構主線）
|
||
|
||
## 封存與主線
|
||
|
||
- **`old/`**：舊系統整包封存，**只讀參考**。不要在 `old/` 修功能當交付。
|
||
- **新碼**：只寫在 **`apps/`** 下（前端 `apps/web`、後端 `apps/backend` 等，以 `docs/product` 為準）。
|
||
- **後端落點**：Phase C 巡樓 API／worker 在 **`apps/backend`**（go-zero；由 `stand-alone-service` 遷入改造）。
|
||
- **後端寫法（硬性）**：一律 **goctl**：改 `generate/api/*.api` → `make gen-api` → 業務只寫 `internal/logic/**` 與 `internal/module/**`。**禁止**手寫 `handler`／`routes.go` 當主路徑。
|
||
- **產品真相**：`docs/product/<slug>/`（requirements → spec → plan → tasks）。
|
||
- **流程**：`/spec-driven`（`.grok/skills/spec-driven/`）。
|
||
|
||
## 交付順序（硬性）
|
||
|
||
1. Phase A 地基
|
||
2. Phase B 前端 + mock（操作順再往下）
|
||
3. Phase C 接真 API
|
||
4. Phase D 業務加深
|
||
|
||
B 未過關前，不大寫業務後端。
|
||
|
||
## 後端契約精神（實作時遵守）
|
||
|
||
- 時間：**UTC**；儲存 **unix nanoseconds** `int64`。
|
||
- JSON：`code` / `message` / `data` / `error`；成功碼 `102000`。
|
||
- 列表：`page` / `pageSize` → `pagination` + `list`。
|
||
- Job：狀態 **guarded** 更新；Redis lock value = `workerID`。
|
||
- 會員 JWT vs AI provider token 分離。
|
||
- **禁止**未實作 API 回成功空資料。
|
||
|
||
## 前端精神（Harbor Desk）
|
||
|
||
- 新殼在 `apps/web`；不引入 MUI/Ant/Chakra。
|
||
- 不複製任天堂 / Nook UI；不用 emoji 當主 icon。
|
||
- 字體：Inter + Taipei Sans TC。
|
||
- mock | live 同一 repository 介面。
|
||
- 詳見 `docs/product/haixun-console/spec.md`。
|
||
|
||
## 參考舊碼
|
||
|
||
需要對照實作時：
|
||
|
||
```text
|
||
old/backend/ # 舊 Go / web / node workers
|
||
old/AGENTS.md # 舊詳細規範
|
||
old/docs/ # 舊計劃文件
|
||
```
|
||
|
||
複製模式可以，**不要**把半成品與死碼整包搬回主線。
|