thread-master/AGENTS.md

# 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/             # 舊計劃文件
```

複製模式可以，**不要**把半成品與死碼整包搬回主線。