cmbone/progress.md

执行流水

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

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 通过。
• 非阻塞警告：
  • 文档任务未改运行代码，未重复执行构建。

补充 Windows 打包验证文档

• 任务：完成 T-032，wails3 package 前置条件、输出目录和常见失败处理写入 README 或 docs。
• 结果：
  • 新增 docs/windows-packaging.md。
  • README 和 docs/03-tech-stack.md 已链接 Windows 打包验证文档。
  • 文档明确默认 NSIS 打包路径、makensis 前置条件、bin/cmbone-amd64-installer.exe 输出目录、安装包验证清单和常见失败处理。
  • 文档明确当前项目没有 wails.json，MSIX 暂不作为验收路径。
• 验证：
  • $env:Path += ";$(go env GOPATH)\bin"; wails3 package -help 通过。
  • Get-Command makensis 未找到命令，已写入文档风险。
  • git diff --check 通过。
• 非阻塞警告：
  • 文档任务未改运行代码。
  • 本机缺少 NSIS makensis，未强跑 wails3 package。

完成模板 smoke 清单

• 任务：完成 T-033，登录、设置、业务样例、日志、统计、组件示例、托盘、热键都按清单验证并记录结果。
• 结果：
  • 新增 docs/smoke-checklist.md。
  • 清单记录登录、设置、业务样例、日志、统计、组件示例、托盘、热键的验证方式和结果。
  • 托盘记录为代码路径检查 + 启动 smoke 通过，菜单点击建议桌面人工复核。
• 验证：
  • go test ./... 通过。
  • cd frontend && npm run build 通过。
  • go build -o bin\cmbone.exe . 通过。
  • cmd /c build.bat 通过。
  • 启动 bin\cmbone.exe 后读取到主窗口标题 main，进程未提前退出。
  • 自动发送默认 Alt+P 后，可见窗口从 main 变为 second, main。
• 非阻塞警告：
  • 前端构建仍提示 Browserslist 数据过期和 chunk 大小警告。
  • cmd /c build.bat 仍提示 wails3 build 是 wails3 task 的 alias。
  • 本机缺少 NSIS makensis，未执行安装包打包 smoke。