cmbone/docs/current-state.md

# 当前状态

更新时间：2026-07-09

## 当前阶段

项目处于 `ec` 分支的电商场景开发起步阶段。主线模板能力已经具备，当前分支开始把模板能力收敛成面向电商运营的桌面端应用。

当前代码已从迁移后的 Wails/Vue/SQLite 基线推进到主应用路由骨架、登录 provider 边界、统一设置 schema、主窗口状态恢复、商品中心、商品图片 AI 优化页面、日志服务边界、P0 数据统计和常用组件示例阶段，已具备设置、多语言、主题、本地配置、热键、托盘、OCR 示例、本地登录能力、商品运营入口、本地模拟图片优化任务能力、审计日志、运行日志和 P0 统计查询能力。统计页面仍是骨架，尚未展示真实统计数据。

## 已确认事实

- 项目类型：可复用桌面应用模板。
- 当前业务分支：`ec`，面向电商运营应用开发。
- 主要运行场景：Windows 10 以及以后的 Windows 操作系统。
- 跨平台策略：Windows-first，保留 macOS / Linux 适配边界，不在 MVP 承诺完整体验。
- 第一批业务样例：电商商品图片 AI 优化。
- 登录策略：本地固定账号 provider 已实现，真实后端 provider 已预留边界。
- 日志策略：审计日志用于用户动作追踪，运行日志用于系统排错。
- 第一批统计指标：今日处理图片数、AI 优化成功率、平均处理耗时、失败任务数、今日操作日志数、最近 7 天处理趋势。
- Go 模块名：`cmbone`
- Go 版本：`1.23.0`
- Wails 版本：`v3.0.0-alpha.9`
- 前端 runtime：`@wailsio/runtime 3.0.0-alpha.66`
- 前端框架：Vue 3、Vite、TypeScript、Tailwind CSS、Ant Design Vue
- 当前 Wails 前端 bindings：由 `wails3 build` / `wails3 generate bindings` 生成的 `.js` 文件。
- 已文档化 Wails bindings 生成流程：README 和技术栈文档包含固定版本、生成命令、失败处理和提交要求。
- 已文档化 Windows 打包验证流程：`docs/windows-packaging.md` 包含 `wails3 package` 前置条件、NSIS 输出目录、验证清单和常见失败处理。
- 已完成模板 smoke 清单：`docs/smoke-checklist.md` 记录登录、设置、业务样例、日志、统计、组件示例、托盘和热键验证结果。
- 本地数据库：SQLite，用户配置目录下 `cmbone/cmbone.db`
- 当前本地演示账号：`admin` / `admin123`，密码由后端初始化为 salt + SHA-256 hash，不写死在前端。
- 当前主窗口路由：`/#/` 重定向到 `/#/dashboard`。
- 当前主应用模块路由：`/#/login`、`/#/dashboard`、`/#/products`、`/#/image-optimizer`、`/#/logs`、`/#/statistics`、`/#/settings`、`/#/components`。
- 当前兼容重定向路由：`/#/business/image-optimizer`、`/#/logs/audit`、`/#/logs/app`。
- 当前第二窗口路由：`/#/second`
- 已实现主窗口策略：默认不最大化，初始 `1280x800`，最小 `1024x720`，居中，可调整大小；启动后可按 `window.*` 配置恢复尺寸和最大化状态。
- 已实现页面布局策略：根容器 `width: 100%`、`height: 100vh`，内部 flex/grid 填满窗口；主窗口最大化后背景、根容器和主布局铺满可用区域，不出现左右黑边。
- 已实现内容区策略：阅读型内容保留最大宽度；列表、仪表盘、设置页自适应拉伸。
- 已保留第二窗口策略：保持小窗，不参与主窗口最大化和尺寸恢复逻辑。
- 已实现 AuthService：`GetAuthProviders`、`GetAuthMode`、`SetAuthMode`、`Login`、`Logout`、`GetCurrentSession`。
- 已实现登录审计留痕：登录成功、登录失败和退出写入 `audit_logs`。
- 已实现统一设置 schema：主题、语言、窗口行为、快捷键展示、数据目录、日志策略和登录 provider 配置都有默认值、说明和基础校验。
- 已实现设置页 schema 展示：`/#/settings` 可读取后端 `GetSettingsSchema` 并展示分组、当前值、默认值、说明和只读标记。
- 已实现主窗口状态持久化：主窗口普通尺寸和最大化状态会写回 `appconfig`，下次启动恢复；第二窗口不参与该逻辑。
- 已实现商品中心页面：支持商品草稿、SKU、类目、渠道、售价、库存、上架状态、图片状态、筛选和分页展示。
- 已实现 ImageOptimizationService：`CreateTask`、`ListTasks`、`GetTask`、`CancelTask`，当前 provider 为本地模拟实现。
- 已实现 `image_tasks` 和 `image_task_results` 表，模拟任务可写入成功状态、耗时、输出路径和前后文件大小。
- 已实现商品图片 AI 优化页面：支持文件选择、手动图片路径、创建任务、筛选任务、任务列表、状态标签、结果预览和失败提示。
- 已实现 AuditLogService：`Record`、`List`，登录、设置变更和图片任务创建会写入 `audit_logs`。
- 已实现 AppLogService：`Record`、`List`，图片任务创建失败和服务内部错误会写入 `app_logs`。
- 已实现 MetricsService：`GetDashboardMetrics`、`GetProcessingTrend`，可查询今日处理量、成功率、平均耗时、失败数、今日审计日志数和最近 N 天趋势。
- 已实现常用组件示例页：输入框、多选框、下拉框、多行文本、表格、筛选、分页和状态标签都有可运行示例。

## 当前命令

统一验证：

```powershell
.\init.ps1
```

拆分验证：

```powershell
go test ./...
cd frontend
npm run build
npm run typecheck
cd ..
go build -o bin\cmbone.exe .
```

Wails CLI：

```powershell
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9
wails3 dev
wails3 build
.\dev.bat
.\build.bat
```

## 已知风险

- 模板范围容易膨胀，必须按任务小步实现。
- Wails v3 alpha 版本需要保持 CLI、Go 模块和前端 runtime 匹配。
- 真实后端登录 provider、真实 AI provider 尚未实现；统计页面展示仍待后续扩展。
- WebView 文件选择器不一定返回绝对路径，图片优化页面已保留手动路径输入。
- OCR 和热键依赖平台实现，跨平台修改需要分别验证。
- 当前前端以构建检查为主，暂未引入专门的前端单元测试。
- bindings 生成依赖本机安装的 `wails3`。
- 待修复：Windows 无边框主窗口顶部拖拽区域双击不能像原生标题栏一样切换最大化/还原。
- Windows 默认打包路径依赖 NSIS `makensis`；当前本机 PATH 未检测到 `makensis`。
- 当前项目未配置 `wails.json`，MSIX 暂不作为可用打包路径。
- 托盘菜单点击行为仍建议在真实桌面环境人工复核，本轮已确认初始化代码路径和应用启动 smoke。
- `npm install` 当前报告 3 个 moderate audit findings，后续如做依赖治理应单独开任务。
- 前端构建当前有 Browserslist 数据过期和 chunk 大小警告，不阻塞生产构建。
- Windows 快捷脚本依赖 `go env GOPATH` 下的 `bin\wails3.exe`，如果未安装 Wails CLI，先按 README 安装固定版本。
- `dev.bat` 为了尽快打开 GUI，使用不含 `vue-tsc` 的 `build:dev`；提交前必须继续运行 `npm run build`。

## 最近验证

2026-07-08 已运行：

```powershell
.\init.ps1
```

结果：

- `npm install` 通过。
- `go test ./...` 通过。
- `npm run build` 通过。
- `go build -o bin\cmbone.exe .` 通过。

同日完成可复用桌面应用模板定位校准后，已再次运行旧定位残留检查、`git diff --check` 和 `.\init.ps1`，结果均通过。

同日完成主窗口启动参数与根布局策略实现后，已运行：

- `.\init.ps1` 通过。
- `go test ./...` 通过。
- `cd frontend && npm run build` 通过。
- `go build -o bin\cmbone.exe .` 通过。
- `bin\cmbone.exe` 启动 6 秒 smoke 通过。

同日新增 Windows Wails 快捷脚本：

- `dev.bat` 一行切到项目根目录，把 Go bin 加入当前进程 PATH，并从 `9245` 开始选择空闲端口运行 `wails3 dev`。
- `build.bat` 一行切到项目根目录，把 Go bin 加入当前进程 PATH 并运行 `wails3 build`。
- 已补齐 `build/windows/wails.exe.manifest` 和 `build/windows/info.json`，使 `wails3 build` 的 Windows syso 生成步骤可运行。
- `cmd /c build.bat` 通过。
- `dev.bat` 已验证能避开端口占用问题，进入 `windows:run` 并加载 WebView 资源。
- 使用同样 PATH 逻辑执行 `wails3 dev -help` 通过。
- `.\init.ps1` 通过。

同日修复 `dev.bat` 启动 GUI 等待过长问题：

- `frontend` 的 `build:dev` 改为快速 Vite dev 构建，避免 `vue-tsc` 在开发启动链路中长时间阻塞窗口打开。
- 新增 `npm run typecheck`，正式质量门禁仍由 `npm run build` 覆盖类型检查和生产构建。
- 已验证 `dev.bat` 能进入 `windows:run`，拉起 `bin/cmbone.exe`，并创建可见主窗口。

同日完成主应用路由骨架：

- 新增 `frontend/src/layouts/MainLayout.vue`，主窗口改为侧边导航、顶部窗口区和路由内容区。
- 新增登录、工作台、商品图片 AI 优化、操作日志、数据统计、设置、组件示例模块页。
- 新增 `frontend/src/components/template/ModulePageShell.vue`，用于模块标题、状态和摘要卡片。
- `frontend/src/router/index.ts` 已切换为主应用模块路由，第二窗口继续保留 `/#/second`。
- `npm run typecheck`、`npm run build`、`npm run build:dev`、`go test ./...`、`go build -o bin\cmbone.exe .`、`cmd /c build.bat` 和 `dev.bat` 烟测通过。

同日完成登录 provider 边界：

- 新增 `AuthService`、`LocalAuthProvider` 和 `RemoteAuthProvider`。
- 新增 `auth_sessions` 和 `audit_logs` 迁移。
- 登录页通过 Wails bindings 调用后端 AuthService，不在前端写固定账号密码。
- 默认本地演示账号为 `admin` / `admin123`，密码以后端配置 hash 形式保存。
- 登录成功、失败和退出会写审计日志。
- `go test ./...`、`npm run typecheck`、`npm run build`、`npm run build:dev`、`go build -o bin\cmbone.exe .`、`cmd /c build.bat` 和 `dev.bat` 烟测通过。

同日完成统一设置 schema：

- 新增 `internal/services/settings_schema.go` 和 `internal/models/settings.go`。
- `AppConfigService.GetSettingsSchema` 返回设置分组、配置项、默认值和当前值。
- `SetAppConfig` 对 schema 已知项执行 select、boolean、number 和只读校验。
- `theme.mode` 改为从后端配置读取，并支持 `light`、`dark`、`systemdefault`。
- `/#/settings` 展示统一设置 schema。
- `go test ./...`、`npm run typecheck`、`npm run build`、`go build -o bin\cmbone.exe .`、`cmd /c build.bat` 通过。

2026-07-09 完成主窗口状态持久化：

- 主窗口启动时读取 `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 ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日完成商品图片 AI 优化任务模型：

- 新增 `internal/models/image_task.go` 和 `internal/services/image_optimization_service.go`。
- 新增 `image_tasks`、`image_task_results` 迁移和索引。
- 新增 `ImageOptimizationService.CreateTask/ListTasks/GetTask/CancelTask`。
- 当前 `CreateTask` 使用本地模拟 provider，创建成功任务和结果记录。
- 已重新生成 Wails `.js` bindings。
- `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日完成审计日志与运行日志边界：

- 新增 `internal/models/log.go` 和 `internal/services/log_service.go`。
- 新增 `app_logs` 迁移和日志查询索引。
- 新增 `AuditLogService.Record/List` 和 `AppLogService.Record/List`。
- 登录审计改为复用统一审计写入 helper。
- `AppConfigService.SetAppConfig` 会记录用户配置变更审计，自动窗口状态保存不会写审计。
- `ImageOptimizationService.CreateTask` 会记录任务创建审计，创建失败和服务错误会写运行日志。
- 已重新生成 Wails `.js` bindings。
- `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日完成 P0 数据统计服务：

- 新增 `internal/models/metrics.go` 和 `internal/services/metrics_service.go`。
- 新增 `DashboardMetrics` 和 `DailyMetric` 绑定模型。
- `MetricsService.GetDashboardMetrics` 可查询今日处理图片数、成功率、平均耗时、失败任务数和今日审计日志数。
- `MetricsService.GetProcessingTrend` 可查询最近 N 天处理趋势，默认 7 天，最多 30 天。
- SQLite 迁移新增 `image_tasks(created_at)` 和 `audit_logs(created_at)` 查询索引。
- 已重新生成 Wails `.js` bindings，新增 `metricsservice.js`。
- `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日完成商品图片 AI 优化页面：

- `frontend/src/modules/image-optimizer/ImageOptimizerPage.vue` 接入 `ImageOptimizationService` bindings。
- 页面支持选择图片、手动输入图片路径、选择优化类型、创建模拟任务。
- 页面支持按状态和优化类型筛选任务，展示任务列表、状态、耗时和创建时间。
- 页面支持查看任务详情，展示原图/结果占位预览、输出路径、文件大小、失败原因。
- WebView 文件选择器不返回绝对路径时，页面会提示用户粘贴绝对路径。
- `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日完成常用组件示例页：

- `frontend/src/modules/components-demo/ComponentsDemoPage.vue` 从静态骨架改为可交互示例。
- 表单区支持输入框、多选框、下拉框和多行文本，并实时展示当前值。
- 表格区支持关键字、分类、状态筛选，展示分页和状态标签。
- `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日完成 Wails bindings 生成流程文档：

- README 新增 `Wails Bindings` 章节。
- `docs/03-tech-stack.md` 新增 `Wails Bindings 生成流程` 章节。
- 明确固定版本：Go `1.23.0`、Wails CLI `v3.0.0-alpha.9`、`@wailsio/runtime 3.0.0-alpha.66`。
- 明确生成命令、生成时机、常见失败处理、提交要求和验证命令。

同日完成 Windows 打包验证文档：

- 新增 `docs/windows-packaging.md`。
- README 和技术栈文档已链接该文档。
- 文档记录 `wails3 package` 前置条件、默认 NSIS 路径、输出目录、安装包验证清单和常见失败处理。
- 已确认本机 `wails3 package -help` 可用，但 PATH 中未检测到 `makensis`，因此未强跑 NSIS 打包。

同日完成模板 smoke 清单：

- 新增 `docs/smoke-checklist.md`。
- `go test ./...`、`npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。
- 启动 `bin\cmbone.exe` 后进程未退出，主窗口标题为 `main`。
- 自动发送默认 `Alt+P` 后可见窗口包含 `second, main`，热键打开第二窗口通过。
- 登录、设置、业务样例、日志、统计、组件示例、托盘、热键均已按清单记录验证方式和结果。

同日创建 `ec` 分支并启动电商场景：

- `ec` 分支已推送到 `origin/ec`。
- 新增 `/#/products` 商品中心路由。
- 新增商品中心页面，当前使用前端本地示例数据。
- 商品中心支持商品草稿、SKU、类目、渠道、售价、库存、上架状态、图片状态、筛选、分页和图片优化入口。
- 新增 `docs/ecommerce-scenario.md`。
- `go test ./...`、`cd frontend && npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。

同日修复主窗口最大化黑边与布局填充：

- Go 侧主窗口设置 `BackgroundColour`，避免 WebView 外围区域显示默认黑底。
- 前端 `html`、`body`、`#app`、应用根容器和主布局统一填满窗口，并设置明暗主题背景。
- `go test ./...`、`cd frontend && npm run build`、`go build -o bin\cmbone.exe .` 和 `cmd /c build.bat` 通过。
- 启动 `bin\cmbone.exe` 后程序化最大化窗口，左右边缘采样 `11264` 个像素，纯黑像素数为 `0`。

## 下一步

先领取 [`06-tasks.md`](06-tasks.md) 的 `T-036`：支持 Windows 主窗口标题栏双击最大化；完成后继续 `EC-002` 建立商品后端模型。

## 当前 blocker

无。