前端开发 Runbook

本地启动、环境变量、代理 / CORS 与质量门禁。前台产品架构见 Infinite Canvas 前台、前端应用总览。

前置条件

• Node 22（见 src/agent-system/.node-version；canvas 建议同主版本）
• 包管理：agent / admin 用 pnpm；infinitecanvas 用 npm
• 后端：本地或远端 backend（默认 :8001）；生图 / 上传视需求再启 storage、Redis

make install          # 后端 Poetry + 主前端依赖（按 Makefile）
# 或分别进入各 app 安装依赖

启动命令

命令	应用	地址
make agent-dev	agent-system	http://127.0.0.1:5174
make canvas-dev	infinitecanvas（前台）	http://127.0.0.1:5173
make admin-dev	admin-system	http://127.0.0.1:5175

也可使用 harness 编排：make up / MCP start_service（见 AGENTS.md）。

端口与主机（单一真相）

应用	Dev 端口	本地域名（K3s）	ACK 域名
infinitecanvas	5173	canvas.localhost	canvas.harness.local
agent-system	5174	agent.localhost	agent.harness.local
admin-system	5175	admin.localhost	admin.harness.local

说明：端口以 harness.yaml 为准，并与各 app vite.config.ts 对齐。

API 代理与跨域

agent / admin

vite.config.ts：/api → http://localhost:8001，开发期同源，无 CORS 问题。

infinitecanvas（前台）

1. 推荐（默认开发）：不设置 VITE_BACKEND_API_URL，请求走相对路径 /api/...，在 vite.config.ts 打开：

proxy: {
  '/api': {
    target: 'http://backend.harness.local', // 或 http://127.0.0.1:8001
    changeOrigin: true,
  },
},

1. 直连远端（测 CORS）：注释掉 proxy，在 .env.development 设置例如：

VITE_BACKEND_API_URL=http://demo.harness.local
# 或
VITE_BACKEND_API_URL=http://backend.harness.local

须重启 Vite。此时浏览器 Origin 为 http://localhost:5173（canvas），backend 须在 CORS_ORIGINS 或 allow_origin_regex 中放行，否则 Network 预检 OPTIONS 失败、控制台报 CORS。

1. ACK 同源：页面与 API 均在 https?://canvas.harness.local，经 Ingress 转发，不依赖 Vite 代理。

环境变量模板：src/infinitecanvas/.env.example。

快速自检 CORS

# 预检：应返回 200，且含 Access-Control-Allow-Origin
curl -sS -D- -o /dev/null -X OPTIONS \
  'http://demo.harness.local/api/user/task-types' \
  -H 'Origin: http://localhost:5173' \
  -H 'Access-Control-Request-Method: GET' \
  -H 'Access-Control-Request-Headers: authorization'

若状态为 400 且无 access-control-allow-origin，说明线上 CORS 白名单未覆盖该 Origin（需更新 ConfigMap / 重新部署 backend，见 deploy/ACK/patches/backend-config.yaml 与 src/backend/main.py）。

质量门禁

命令	内容
make agent-check	typecheck + lint + format + build + test + arch
make admin-check	同上
make canvas-check	typecheck + build + test

提交前另跑仓库级 pre-commit（见 pre-commit 手册）。前端相关钩子由 scripts/frontend_precommit.py 调度。

编码速查

agent / admin

• 新页面：features/<name>/，共享能力进 shared/
• HTTP：仅 shared/api/httpClient.ts
• 测试：Vitest +（可选）Playwright；覆盖率门禁 80%

infinitecanvas

• 新功能页：pages/*Page.tsx + components/<feature>/
• AI 工作区优先复用 AiWorkspacePage 壳
• 生图：runUserGenerateTask()（兼容同步 image_urls 与异步 job_id）
• HTTP：shared/api/backendHttpClient.ts 与领域 API 模块

部署镜像

Make 目标	说明
make k3s-build-infinitecanvas-frontend	本地 K3s 镜像
make ack-push-infinitecanvas-frontend	推送 ACR（不可变 tag + latest）
make ack-deploy	按 image-tags.env 部署到 ACK
make ack-rollback SERVICE=infinitecanvas-frontend TAG=…	回滚 Canvas
make ack-push-agent-frontend / ack-push-admin-frontend	同理

构建时默认不注入远端 API 地址（同源 /api，见各前端 Dockerfile）。部署步骤见 ACK / K3s。

文档站点

make docs-serve   # http://127.0.0.1:8001
make docs         # mkdocs build --strict

云端文档站示例：http://docs.harness.local/（本机 hosts 指向文档 SLB / 节点 IP）。内容来自仓库 docs/ + mkdocs.yml。