cmbone/docs/02-requirements.md

需求说明

模板 MVP 范围

P0 · 基线必须保持

• 应用能启动 Wails 主窗口，并加载嵌入的 frontend/dist 资源。
• Windows 10+ 是主要运行和体验目标。
• 多语言资源能从 frontend/src/locales/*.json 加载，并能通过 UI / 服务切换。
• 主题配置能保存到本地 SQLite 并在前端生效。
• 快捷键配置能从数据库读取、更新，并注册到系统热键层。
• 托盘菜单能执行显示、隐藏、语言切换和退出等基础动作。
• go test ./...、npm run build、go build -o bin/cmbone.exe . 通过。

P0 · 模板必须具备

• 应用壳：侧边导航、顶部用户区、主内容区，默认布局适合长期业务操作。
• 主窗口：默认不最大化，初始 1280x800，最小 1024x720，居中，可调整大小，并恢复用户上次窗口尺寸和最大化状态。
• 页面布局：根容器 width: 100%、height: 100vh，内部使用 flex/grid 填满窗口。
• 内容区：阅读型内容保留最大宽度；列表、仪表盘、设置页自适应拉伸。
• 第二窗口：保持小窗，不参与主窗口最大化和尺寸恢复逻辑。
• 设置模块：主题、语言、窗口行为、快捷键、数据目录、日志策略。
• 登录模块：支持本地固定账号 provider；预留真实后端 provider。
• 主业务模块：以电商商品图片 AI 优化为样例，包含任务创建、列表、状态、结果和失败反馈。
• 操作日志模块：审计日志记录用户动作，运行日志记录系统错误和排错信息。
• 数据统计模块：展示第一批 P0 指标。
• 常用组件示例：输入框、多选框、下拉框、多行文本、表格、筛选、分页和状态标签。

第一批统计指标

P0 数据统计只做 6 个指标：

• 今日处理图片数。
• AI 优化成功率。
• 平均处理耗时。
• 失败任务数。
• 今日操作日志数。
• 最近 7 天处理趋势。

P1 再考虑：

• 图片优化前后平均文件大小变化。
• 不同优化类型使用次数，例如增强、压缩、背景替换。
• 最常见错误类型 Top 5。
• 当前本地数据库大小和输出目录占用空间。
• 登录成功 / 失败次数。
• 任务队列状态：待处理、处理中、成功、失败。

登录要求

• 本地固定账号只用于模板演示和离线场景。
• 固定账号密码不得写死在前端。
• 真实后端登录通过 provider 接入，返回 token 或 session。
• 登录成功、失败、退出必须写入审计日志。
• MVP 不做复杂权限、角色或 SSO。

日志要求

审计日志用于回答“谁在什么时候做了什么”：

• 登录、退出、登录失败。
• 修改设置。
• 创建图片优化任务。
• 任务成功、失败、取消。
• 导出或清理数据。

运行日志用于排错：

• AI 调用失败。
• 数据库错误。
• 文件读写失败。
• 热键注册失败。
• 未捕获的服务错误。

审计日志和运行日志不要混在同一张业务表里。

验收标准

每个任务完成前至少满足：

• 相关代码已格式化。
• 相关单元测试或构建命令通过。
• 前端页面在目标窗口尺寸下没有明显溢出或不可用控件。
• 文档中的命令、版本、接口和当前代码一致。
• progress.md 记录了本次验证命令和结果。

约束

• 当前 Go 版本为 1.23.0。
• Wails 版本固定为 v3.0.0-alpha.9。
• 前端 runtime 固定为 @wailsio/runtime 3.0.0-alpha.66。
• 不提交 node_modules、dist、bin、本地数据库或用户配置。
• 依赖升级必须单独开任务。