docs: synchronize documentation with current implementation

web/API_REQUEST.md

@@ -1,11 +1,32 @@
-# 前后端协调
+# 前后端接口对接
 
-前端 agent 当前工具没有 actor/send，无法直接发送给 general-2。请后端在根目录 API.md 记录实际接口、鉴权/CSRF、列表 envelope、实例/profile/备份/升级、文件上传和管理员字段。前端将以 API.md 校对实现，不模拟成功。
+根目录 API.md 是接口契约。公共请求封装与响应类型在 src/api.ts，实例、备份及管理员等组件也通过 api.request 发起业务请求。本文记录当前前端依赖，不将界面入口或请求成功等同于端到端验收。
 
-Vite 开发监听 127.0.0.1，代理默认 http://127.0.0.1:8088，生产构建 web/dist，同源 /api 和 /dsh。
+## 运行与认证
 
-已完成中文页面与首次构建，当前待确认的响应字段：images 是 id 还是 image_id；builds 日志字段 logs；ws/tree 是否直接数组及 is_dir/mod_time；usage used_bytes/quota_bytes；audit user_id/created_at；backups id/size/created_at。请明确空列表返回 [] 或 null。恢复/下载备份/升级接口尚未列出，UI 将明确提示缺口而不猜测接口。
+Vite 开发监听 127.0.0.1，默认端口 5173（占用时自动尝试后续端口），代理至 http://127.0.0.1:8088；/dsh 启用 WebSocket 代理。生产构建目录为 web/dist，需由后端同源提供静态页面、/api 和 /dsh。
 
-11:24 检查 internal/api/api.go：创建实例入参目前 struct{ Name, ImageID, Version string } 无 json 标签，image_id 不会映射到 ImageID，需后端补标签。生命周期仍只是写 start/stop 字符串而非真实 Docker 操作，前端不会把 start 字符串映射成 running。请务必真实实现或返回明确错误，避免假成功。
+- 登录和 /api/me 返回 {user,csrf_token}。认证使用 HttpOnly Cookie；浏览器请求携带同源 Cookie，非 GET 请求从可读的 dsh_csrf Cookie 设置 X-CSRF-Token，而不是只使用内存中的旧 token。
+- 存在 CSRF token 时，非登录/刷新请求的首次 401 会尝试恢复会话，再重试原请求；使用页内共享 Promise 和可用时的 Web Locks 协调刷新，刷新冲突后复验 /api/me。无法恢复的会话通过 session-expired 通知界面。
+- 错误响应读取 {error:string}；网络错误和非 JSON 成功响应均显示明确错误，不模拟成功。文件/备份下载和图片预览直接使用同源资源地址，不经过 JSON 请求封装。
 
-验证：npm test 六项全部通过；npm run build 通过。Playwright 真浏览器已验证桌面/390px 移动登录界面、离线登录错误，移动 documentWidth=390 无横向溢出。8088 暂未启动，无法验证登录后页面；请父 agent 启动后端后通知可用临时验证账号，避免操作共享数据。
+## 响应结构与镜像构建
+
+- 实例、镜像、构建历史、工作区目录、用户、审计、备份及孤儿容器的 GET 列表响应为顶层数组，不使用 data envelope；空列表应返回 []。其中 /api/orphans 返回容器 ID 字符串数组；详情、用量和操作结果不适用此列表约定。
+- 镜像类型含 id、可选 image_id、version、status、admission、admission_reason、selectable 等字段；前端提交镜像标识时使用 image_id || id，仅允许 status=available 且 selectable=true 的镜像用于创建/升级。
+- 构建历史通过 GET /api/builds?limit=...&offset=... 获取摘要；前端每页显示 20 条、多取 1 条判断下一页，不读取 X-Has-More。日志按需通过 GET /api/builds/{id} 的 logs 字段获取。
+- 管理员通过 GET /api/releases/latest 检查 Git 发布，确认后 POST /api/releases/build {commit}；构建来源字段包括 release_id、source_commit、source_repository。镜像准入使用 POST /api/images/admission {image_id,state,evidence}。不使用旧的 /api/latest、/api/compatibility、POST /api/builds 或创建意图接口。
+- 工作区目录项读取 name/path/is_dir/size/mod_time；用量读取 used_bytes/quota_bytes；审计读取 user_id/created_at 等字段；备份读取 id/size/created_at。
+
+## 已接入的业务操作
+
+- 创建实例：POST /api/instances {name,image_id}，当前前端不发送 version。启动/停止/重启调用实例对应子路径；删除使用 DELETE /api/instances/{id}。显示后端返回的实例状态，不把操作名称当作运行状态。
+- Profile：读取 /profile 和 /profile-preview；停止实例后 PUT /profile {content,restart:true} 保存并启动验证。日志读取 /logs 的 logs 字段。上述路径均位于 /api/instances/{id} 下。
+- 备份：GET /api/instances/{id}/backups 列表，POST 同路径 JSON {password} 创建，multipart file,password 导入；GET 同路径 ?download={backup_id} 下载；POST /api/instances/{id}/restore {backup_id,password} 恢复。
+- 升级：POST /api/instances/{id}/upgrade {image_id,password}。创建备份和升级使用当前登录密码；导入/恢复使用原包密码，旧平台 key 包可留空。恢复和升级有二次确认。
+- 工作区：/api/ws/tree、usage、mkdir、rename、delete、upload、download，并通过 instance 参数选择实例；上传使用 multipart file,path。图片预览使用 /api/ws/image；文本读取 /api/ws/text 返回 {content,version}，保存 PUT 同路径 {content,version}，冲突不静默覆盖。
+- 账户管理：本人 POST /api/me/password；管理员通过 /api/users 创建用户、PATCH 修改配额，通过 /api/users/reset-password 重设密码，并读取 /api/audit。本人改密后重新登录，管理员重设按 reauthenticate 决定是否退出当前会话。孤儿容器回收使用 /api/orphans，删除提交 id 与 confirm。
+
+## 验证边界
+
+在 web/ 执行 npm test 和 npm run build 获取当前测试与构建结果，不沿用早期测试数量或临时服务状态。单元测试包含 fetch 替身，不能证明真实后端、Docker、WS/SSE 或数据恢复流程已验收；真实联调需独立测试环境和授权账号，具体后端限制与验收记录见根目录 API.md、README.md、ACCEPTANCE.md。

web/README.md

@@ -1,10 +1,10 @@
 # DSH 中文工作台
 
-React 19 + TypeScript + Vite；普通 CSS 响应式布局，没有运行时演示数据。
+React 19 + TypeScript + Vite；使用 Tailwind CSS 4、Radix UI 和自定义 CSS 构建响应式界面，Profile 编辑器按需加载 Monaco，没有运行时演示数据。
 
 ## 开发与验证
 
-使用 Node.js 22+：
+使用 Node.js 22+，在 web/ 目录执行：
 
 ~~~bash
 npm ci
@@ -13,14 +13,16 @@ npm test
 npm run build
 ~~~
 
-开发服务只监听 127.0.0.1:5173，/api 和 /dsh 代理至 127.0.0.1:8088。生产产物为 dist/，由后端同源提供；不能直接通过 file:// 使用。
+开发服务监听 127.0.0.1，默认端口 5173（占用时 Vite 会尝试后续端口）；/api 和 /dsh 代理至 127.0.0.1:8088，/dsh 支持 WebSocket 代理。生产产物为 web/dist/，需配置后端静态目录并同源提供；不能直接通过 file:// 使用。
 
 ## API 与安全
 
-- 根目录 API.md 是接口契约；API 客户端集中在 src/api.ts，可注入 fetch 进行独立单元测试。
-- HttpOnly Cookie 登录；CSRF token 仅留在内存，刷新通过 /api/me 重新获取。密码、token 不写入 localStorage。
+- 根目录 API.md 是接口契约；公共请求封装和类型位于 src/api.ts，可注入 fetch 进行独立单元测试。业务组件也通过 api.request 调用接口；当前对接说明见 API_REQUEST.md。
+- 使用同源 HttpOnly 认证 Cookie；浏览器写请求从可读的 dsh_csrf Cookie 获取 X-CSRF-Token。启动时通过 /api/me 恢复登录状态，符合条件的 401 会触发 /api/refresh 并重试原请求，支持并发刷新协调。密码、token 不写入 localStorage；工作台所选实例会按用户保存在 localStorage。
 - 操作失败保留错误，不模拟成功；删除、重启、构建等操作二次确认。
-- 备份恢复和升级等待后端契约，当前明确显示不可用说明，不发送猜测接口。
+- 已接入 Profile 编辑/预览、加密备份创建/导入/下载/恢复和本地镜像升级；创建备份和升级要求当前登录密码，导入/恢复使用原备份密码。
+- 创建实例和升级只允许 status=available 且 selectable=true 的本地镜像；管理员通过 Git 发布检查与精确 commit 提交构建，并可管理镜像准入策略。
+- 工作区支持文件管理、目录 ZIP 下载、图片预览和带版本校验的文本编辑；管理员页面提供用户、配额、密码重设、审计及孤儿容器回收，本人可修改密码。
 - 单元测试里的 fetch 替身仅用于测试，不打包进生产页面。
 
-当前后端仍在实现部分端点，页面会真实显示其 HTTP 错误。请不要把前端入口存在等同于后端能力已交付。
+测试使用 Vitest，覆盖 API、认证刷新、组件和构建分块等行为；其中构建测试使用不落盘的 Vite 构建。测试或构建通过不等于真实 Docker 生命周期、代理会话及备份恢复已完成端到端验收；部署限制和后端验收范围以根目录 README.md、API.md 和 ACCEPTANCE.md 为准。