# 执行流水

> 记录已经完成的任务、验证命令、结果和关键决策。任务完成必须有可执行证据，不只写“已完成”。

## 2026-07-08

### 基线整理

- 任务：从 `SuiDemo` 迁移并整理为 `cmbone` Wails v3 项目。
- 结果：完成项目结构整理、README 维护、`.gitignore` 更新和初始提交。
- 已知验证：
  - `go test ./...` 通过。
  - `cd frontend && npm run build` 通过。
  - `go build -o bin/cmbone.exe .` 通过。
  - 启动 `bin/cmbone.exe` 后 Wails/WebView2 可初始化并加载前端资源。

### 接入 Harness Coding 文档

- 任务：参考 `D:\github\harness_coding_docs` 的模板，在本项目生成 Harness Coding 文档。
- 决策：保留模板的 `AGENTS.md`、`docs/00-ai-start-here.md`、任务看板、当前状态、质量清单和初始化脚本结构；内容改为本项目真实技术栈和命令。
- 结果：新增仓库级 agent 入口、文档导航、需求/架构/API/路由/质量/任务文档和 `init.ps1` / `init.sh`。
- 验证：
  - `.\init.ps1` 通过。
  - 脚本内 `npm install` 通过。
  - 脚本内 `go test ./...` 通过。
  - 脚本内 `cd frontend && npm run build` 通过。
  - 脚本内 `go build -o bin\cmbone.exe .` 通过。
- 非阻塞警告：
  - `npm install` 报告 3 个 moderate audit findings，本次文档任务未处理依赖审计。
  - 前端构建提示 Browserslist 数据过期。
  - Vite 提示生产 chunk 大于 500 kB。

### 校准为可复用桌面应用模板

- 任务：根据项目愿景，把文档从基础 Wails 工程调整为 Windows-first、可扩展到其他平台的可复用桌面应用模板。
- 决策：
  - 模板核心模块包括应用壳、设置、登录、主业务、操作日志、数据统计和常用组件示例。
  - 第一批业务样例使用“电商商品图片 AI 优化”。
  - 登录设计为本地固定账号 provider 和真实后端 provider 两种路径。
  - 操作日志分为审计日志和运行日志，分别服务审计和排错。
  - 第一批统计指标为今日处理图片数、AI 优化成功率、平均处理耗时、失败任务数、今日操作日志数、最近 7 天处理趋势。
- 结果：更新 README、AGENTS、愿景、需求、技术栈、架构、编码规则、任务看板、API、路由、当前状态、方法地图和质量文档。
- 验证：
  - 旧定位关键词搜索通过，未发现旧定位残留。
  - `git diff --check` 通过。
  - `.\init.ps1` 通过。
  - 脚本内 `npm install` 通过。
  - 脚本内 `go test ./...` 通过。
  - 脚本内 `cd frontend && npm run build` 通过。
  - 脚本内 `go build -o bin\cmbone.exe .` 通过。
- 非阻塞警告：
  - `npm install` 仍报告 3 个 moderate audit findings。
  - 前端构建仍提示 Browserslist 数据过期。
  - Vite 仍提示生产 chunk 大于 500 kB。

### 确定 Windows-first 窗口与布局策略

- 任务：落地 `T-010`，明确主窗口、页面根容器、内容区和第二窗口的布局策略。
- 决策：
  - 主窗口默认不最大化。
  - 主窗口初始尺寸为 `1280x800`，最小尺寸为 `1024x720`。
  - 主窗口启动时居中，并允许用户调整大小。
  - 页面根容器使用 `width: 100%` 和 `height: 100vh`。
  - 主布局内部使用 flex 或 grid 填满窗口。
  - 阅读型内容保留最大宽度；列表、仪表盘、设置页自适应拉伸。
  - 保存窗口尺寸和最大化状态作为后续增强任务，不阻塞主布局。
  - 第二窗口保持小窗，不参与最大化和尺寸恢复逻辑。
- 结果：更新 `docs/06-tasks.md`、`docs/routes.md`、`docs/04-architecture.md`、`docs/02-requirements.md`、`docs/00-ai-start-here.md`、`docs/current-state.md` 和 `docs/quality-document.md`。
- 验证：
  - 旧 T-010 / 最大化策略相关临时表述搜索通过，未发现残留。
  - `git diff --check` 通过。
  - `.\init.ps1` 通过。
  - 脚本内 `npm install` 通过。
  - 脚本内 `go test ./...` 通过。
  - 脚本内 `cd frontend && npm run build` 通过。
  - 脚本内 `go build -o bin\cmbone.exe .` 通过。
- 非阻塞警告：
  - `npm install` 仍报告 3 个 moderate audit findings。
  - 前端构建仍提示 Browserslist 数据过期。
  - Vite 仍提示生产 chunk 大于 500 kB。

### 实现主窗口启动参数与根布局策略

- 任务：实现 `T-011`，把已确定的主窗口与布局策略落到代码。
- 结果：
  - Go 侧主窗口设置为初始 `1280x800`、最小 `1024x720`、居中、可调整大小、正常窗口状态。
  - 第二窗口继续保持 `340x320` 小窗。
  - 前端 `html`、`body`、`#app` 和应用根容器撑满窗口并隐藏外层滚动。
  - 主窗口侧边栏、顶部栏和内容区使用 flex 填满窗口。
  - Dashboard、General、Tags 等现有页面补充了宽度和最小尺寸约束。
  - 根路由保留为主窗口入口，不再自动跳转到第二窗口。
- 验证：
  - `.\init.ps1` 通过。
  - `go test ./...` 通过。
  - `cd frontend && npm run build` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `bin\cmbone.exe` 启动 6 秒 smoke 通过。
- 非阻塞警告：
  - `npm install` 仍报告 3 个 moderate audit findings。
  - 前端构建仍提示 Browserslist 数据过期。
  - Vite 仍提示生产 chunk 大于 500 kB。

### 添加 Windows Wails 快捷脚本

- 任务：完成 `T-034`，新增一行 bat 脚本运行 Wails dev 和 build 命令。
- 结果：
  - 新增 `dev.bat`，切到项目根目录，通过 `go env GOPATH` 把 Go bin 加入当前进程 PATH，并从 `9245` 开始选择空闲端口运行 `wails3 dev`。
  - 新增 `build.bat`，切到项目根目录，通过 `go env GOPATH` 把 Go bin 加入当前进程 PATH 并运行 `wails3 build`。
  - 补齐 `build/windows/wails.exe.manifest` 和 `build/windows/info.json`，满足 Windows syso 生成步骤。
  - `wails3 build` 按当前 CLI 重新生成 `frontend/bindings`，当前绑定文件形态为 `.js`。
  - 更新 README、技术栈、API、当前状态和任务看板。
- 验证：
  - `wails3.exe version` 通过，版本为 `v3.0.0-alpha.9`。
  - 使用 bat 中同样 PATH 逻辑执行 `wails3 dev -help` 通过。
  - `cmd /c build.bat` 通过。
  - `.\init.ps1` 通过。
  - `git diff --check` 通过。
- 修复记录：
  - 用户反馈 `dev.bat` 没有 GUI 窗口后，复现发现原因是 Vite 端口 `9245` 被占用，Wails dev 在前端启动阶段失败。
  - `dev.bat` 已改为先切到项目根目录，再从 `9245` 开始选择空闲端口运行 `wails3 dev`。
  - 修复后 `dev.bat` 已进入 `windows:run`，连接前端 dev server，并加载 WebView 资源。
  - `build.bat` 已改为先切到项目根目录，避免从其他目录运行时找不到项目配置。
- 非阻塞警告：
  - `wails3 build` 提示 `wails3 build` 是 `wails3 task` 的 alias。
  - `npm install` 仍报告 3 个 moderate audit findings。
  - 前端构建仍提示 Browserslist 数据过期。
  - Vite 仍提示生产 chunk 大于 500 kB。

### 修复 dev.bat GUI 启动等待过长

- 任务：用户反馈 `dev.bat` 仍然看不到 GUI 后，继续排查 Windows dev 启动链路。
- 发现：
  - 清理旧的无窗口 `bin/cmbone.exe` 残留进程后，`dev.bat` 可以进入 `windows:run`。
  - GUI 不是完全无法创建，而是开发启动链路先执行 `vue-tsc && vite build --minify false --mode development`，窗口要等该步骤完成后才出现。
  - 窗口枚举确认主窗口可见，标题为 `main`，第二窗口保持隐藏。
- 结果：
  - `frontend/package.json` 新增 `typecheck` 脚本。
  - `build:dev` 改为只执行快速 Vite dev 构建，避免开发启动时被 `vue-tsc` 长时间阻塞。
  - `npm run build` 仍保留 `vue-tsc`，提交前完整质量门禁不变。
  - 修复 `App.vue` 的 `ConfigProvider` 导入和第二窗口 OCR 卡片的 `TransitionGroup` key 警告。
- 验证：
  - `go test ./...` 通过。
  - `cd frontend && npm run typecheck` 通过。
  - `cd frontend && npm run build:dev` 通过，Vite dev 构建约 1 秒完成。
  - `cd frontend && npm run build` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过。
  - `dev.bat` 烟测通过，进入 `windows:run` 后拉起 `bin/cmbone.exe`，窗口枚举显示主窗口 `main` 可见，第二窗口 `second` 保持隐藏。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - `npm install` 仍报告 3 个 moderate audit findings。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 搭建主应用路由骨架

- 任务：完成 `T-012`，让 `login`、`dashboard`、`image-optimizer`、`logs`、`statistics`、`settings`、`components` 路由可访问。
- 结果：
  - 新增 `frontend/src/layouts/MainLayout.vue`，主窗口由侧边导航、顶部窗口区和路由内容区组成。
  - 新增 `frontend/src/components/template/ModulePageShell.vue`，复用模块标题、状态和摘要卡片。
  - 新增 `frontend/src/modules/auth/LoginPage.vue`、`dashboard/DashboardPage.vue`、`image-optimizer/ImageOptimizerPage.vue`、`logs/LogsPage.vue`、`statistics/StatisticsPage.vue`、`settings/SettingsPage.vue`、`components-demo/ComponentsDemoPage.vue`。
  - `frontend/src/router/index.ts` 切换为 hash 路由骨架，`/#/` 重定向到 `/#/dashboard`，`/#/second` 继续用于第二窗口。
  - `/#/business/image-optimizer`、`/#/logs/audit`、`/#/logs/app` 暂时重定向到当前主入口。
  - 更新路由、架构、方法地图、当前状态和任务看板文档。
- 验证：
  - `cd frontend && npm run typecheck` 通过。
  - `cd frontend && npm run build` 通过。
  - `cd frontend && npm run build:dev` 通过。
  - `go test ./...` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过。
  - `dev.bat` 烟测通过，主窗口 `main` 可见，日志显示加载 `frontend/src/layouts/MainLayout.vue` 和 `frontend/src/modules/dashboard/DashboardPage.vue`。
- 非阻塞警告：
  - 并行运行 `npm run build:dev` 和 `go test/go build` 会因为 `frontend/dist` 被重写导致 Go embed 读取旧 hash 文件失败；正确做法是前端构建完成后再运行 Go 命令。
  - `dev.bat` 日志仍有 `SetProcessDpiAwarenessContext failed ... Access is denied`，不影响窗口创建和页面加载。
  - Browserslist 数据过期、Vite chunk 体积警告和 `wails3 build` alias 警告仍存在。

### 实现登录 provider 边界

- 任务：完成 `T-013`，支持本地固定账号 provider，预留 remote provider，账号密码不写死在前端，登录事件写审计日志。
- 结果：
  - 新增 `internal/services/auth_service.go`，提供 `AuthService`、`LocalAuthProvider` 和 `RemoteAuthProvider`。
  - 新增 `internal/models/auth.go`，提供 `AuthSession` 和 `AuthProviderOption` 前端绑定模型。
  - SQLite 迁移新增 `auth_sessions` 和 `audit_logs`，并初始化本地演示账号配置。
  - `main.go` 注册 `AuthService`，并重新生成 Wails `.js` bindings。
  - 登录页通过 `AuthService.Login` 登录，Provider 列表来自后端，前端不保存固定账号密码。
  - 主布局读取当前 session，并在侧边栏底部展示登录状态。
- 验证：
  - `go test ./...` 通过，覆盖本地登录成功、登录失败审计、退出和 remote provider 预留错误。
  - `cd frontend && npm run typecheck` 通过。
  - `cd frontend && npm run build` 通过。
  - `cd frontend && npm run build:dev` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过，并重新生成 Wails `.js` bindings。
  - `dev.bat` 烟测通过，主窗口可见，日志显示加载 `authservice.js` 并调用 `AuthService.GetCurrentSession`。
- 默认本地演示账号：
  - 用户名：`admin`
  - 密码：`admin123`
  - 密码以后端配置的 salt + SHA-256 hash 保存，不写入前端页面。
- 非阻塞警告：
  - `dev.bat` 日志仍有 `SetProcessDpiAwarenessContext failed ... Access is denied`，不影响窗口创建和页面加载。
  - Browserslist 数据过期、Vite chunk 体积警告和 `wails3 build` alias 警告仍存在。

### 收敛设置模块 schema

- 任务：完成 `T-014`，让主题、语言、窗口行为、快捷键、数据目录和日志策略都有统一配置定义和默认值。
- 结果：
  - 新增 `internal/models/settings.go`，定义 `AppSettingGroup`、`AppSettingDefinition` 和 `AppSettingOption`。
  - 新增 `internal/services/settings_schema.go`，集中定义设置 key、类型、默认值、说明、选项和只读策略，并由 schema 生成 `appconfig` 初始化 SQL。
  - `AppConfigService` 新增 `GetSettingsSchema`，返回分组、当前值和默认值。
  - `SetAppConfig` 对 schema 已知项执行 select、boolean、number 和只读校验。
  - 设置页 `/#/settings` 展示后端统一 schema，主题设置改为读写 `theme.mode`。
  - 重新生成 Wails `.js` bindings。
- 覆盖的配置分组：
  - 外观与语言：`theme.mode`、`language`。
  - 窗口行为：`window.start_state`、`window.width`、`window.height`、`window.remember_state`。
  - 快捷键：`shortcut.open_second_window`、`shortcut.open_main_window`，只读展示，实际更新仍走 `HotkeyService`。
  - 数据目录：`data.root_mode`、`data.custom_directory`。
  - 日志策略：`logs.level`、`logs.audit_retention_days`、`logs.app_retention_days`。
  - 登录：`auth.provider` 和本地演示账号 hash 配置。
- 验证：
  - `go test ./...` 通过。
  - `cd frontend && npm run typecheck` 通过。
  - `cd frontend && npm run build` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过，并重新生成 Wails `.js` bindings。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 持久化窗口尺寸和最大化状态

- 任务：完成 `T-015`，保存主窗口尺寸和最大化状态，下次启动恢复用户上次选择，第二窗口不参与该逻辑。
- 结果：
  - 新增 `internal/services/window_state.go`，集中处理主窗口状态读取、恢复和写回。
  - 主窗口启动时读取 `window.width`、`window.height`、`window.start_state` 和 `window.remember_state`。
  - 主窗口 resize、maximize、restore 和 closing 时保存普通尺寸和最大化状态。
  - `window.remember_state` 默认值调整为 `true`，关闭后默认恢复用户上次选择。
  - 补充旧默认值迁移，把 T-014 旧描述下的 `window.remember_state=false` 升级为 `true`。
  - 第二窗口仍固定为 `340x320`，没有注册窗口状态持久化逻辑。
  - 新增窗口状态配置单元测试。
- 验证：
  - `go test ./...` 通过。
  - `cd frontend && npm run build` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 建立商品图片 AI 优化任务模型

- 任务：完成 `T-020`，新增 `image_tasks`、`image_task_results` 迁移和基础测试，并支持创建模拟任务。
- 结果：
  - 新增 `internal/models/image_task.go`，定义图片任务输入、过滤器、任务、结果和详情模型。
  - 新增 `internal/services/image_optimization_service.go`，提供 `CreateTask`、`ListTasks`、`GetTask` 和 `CancelTask`。
  - SQLite 迁移新增 `image_tasks`、`image_task_results` 和基础索引。
  - `CreateTask` 当前使用本地模拟 provider，立即写入成功任务和结果记录。
  - `main.go` 注册 `ImageOptimizationService`。
  - 重新生成 Wails `.js` bindings，新增 `frontend/bindings/cmbone/internal/services/imageoptimizationservice.js`。
- 验证：
  - `go test ./...` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cd frontend && npm run build` 通过。
  - `cmd /c build.bat` 通过。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 实现审计日志与运行日志边界

- 任务：完成 `T-021`，审计日志和运行日志分开；登录、设置变更、任务创建、任务失败可记录。
- 结果：
  - 新增 `internal/models/log.go`，定义审计日志过滤器、运行日志和运行日志过滤器。
  - 新增 `internal/services/log_service.go`，提供 `AuditLogService.Record/List` 和 `AppLogService.Record/List`。
  - SQLite 迁移新增 `app_logs` 和日志查询索引。
  - 登录审计改为复用统一审计写入 helper。
  - 设置变更会记录 `settings.update` 审计；自动窗口状态保存不会写审计。
  - 图片任务创建会记录 `image_task.create` 审计；创建失败和服务错误会写 `app_logs`。
  - `main.go` 注册 `AuditLogService` 和 `AppLogService`。
  - 重新生成 Wails `.js` bindings，新增 `auditlogservice.js` 和 `applogservice.js`。
- 验证：
  - `go test ./...` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cd frontend && npm run build` 通过。
  - `cmd /c build.bat` 通过。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 实现 P0 数据统计

- 任务：完成 `T-022`，今日处理图片数、成功率、平均耗时、失败数、今日操作日志数、7 天趋势可查询。
- 结果：
  - 新增 `internal/models/metrics.go`，定义 `DashboardMetrics` 和 `DailyMetric`。
  - 新增 `internal/services/metrics_service.go`，提供 `MetricsService.GetDashboardMetrics/GetProcessingTrend`。
  - 统计按本机本地自然日计算，并用 UTC 字符串匹配现有 `created_at`。
  - SQLite 迁移新增 `image_tasks(created_at)` 和 `audit_logs(created_at)` 查询索引。
  - `main.go` 注册 `MetricsService`。
  - 重新生成 Wails `.js` bindings，新增 `metricsservice.js`。
- 验证：
  - `go test ./...` 通过。
  - `cd frontend && npm run build` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过。
- 非阻塞警告：
  - 当前 PowerShell 会话 PATH 没有 Go bin，直接运行 `wails3 generate bindings` 会找不到命令；已按项目脚本方式临时补 PATH 后生成绑定。
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 实现商品图片 AI 优化页面

- 任务：完成 `T-023`，上传/选择图片、任务列表、状态、结果预览、失败提示路径可用。
- 结果：
  - `frontend/src/modules/image-optimizer/ImageOptimizerPage.vue` 接入 `ImageOptimizationService` bindings。
  - 页面支持选择图片、手动输入图片路径、选择优化类型和创建模拟任务。
  - 页面支持按状态和优化类型筛选任务，展示任务编号、图片路径、类型、状态、耗时和创建时间。
  - 页面支持查看任务详情，展示原图/结果占位预览、输出路径、前后文件大小和失败原因。
  - WebView 文件选择器不返回绝对路径时，页面提示用户粘贴图片绝对路径。
- 验证：
  - `cd frontend && npm run build` 通过。
  - `go test ./...` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 建立常用组件示例页

- 任务：完成 `T-030`，输入框、多选框、下拉框、多行文本、表格、筛选、分页、状态标签有可运行示例。
- 结果：
  - `frontend/src/modules/components-demo/ComponentsDemoPage.vue` 从静态骨架改为可交互示例。
  - 表单区支持输入框、多选框、下拉框、多行文本，并实时展示当前值。
  - 表格区支持关键字、分类、状态筛选。
  - 表格底部支持分页，状态列支持可用、草稿、阻塞三类状态标签。
- 验证：
  - `cd frontend && npm run build` 通过。
  - `go test ./...` 通过。
  - `go build -o bin\cmbone.exe .` 通过。
  - `cmd /c build.bat` 通过。
- 非阻塞警告：
  - `cmd /c build.bat` 仍提示 `wails3 build` 是 `wails3 task` 的 alias。
  - 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。

### 文档化 Wails bindings 生成流程

- 任务：完成 `T-031`，README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求。
- 结果：
  - README 新增 `Wails Bindings` 章节。
  - `docs/03-tech-stack.md` 新增 `Wails Bindings 生成流程` 章节。
  - 明确固定版本、生成时机、生成命令、失败处理、提交要求和验证命令。
- 验证：
  - `git diff --check` 通过。
- 非阻塞警告：
  - 文档任务未改运行代码，未重复执行构建。