From 9472f005c8c9a733c275ff668ffffef2a0261163 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 8 Jul 2026 15:49:44 +0800 Subject: [PATCH] docs: define main window layout strategy --- docs/00-ai-start-here.md | 1 + docs/02-requirements.md | 5 +++++ docs/04-architecture.md | 13 ++++++++++++- docs/06-tasks.md | 18 ++++++++++-------- docs/current-state.md | 6 +++++- docs/quality-document.md | 4 ++-- docs/routes.md | 16 +++++++++++++++- progress.md | 26 ++++++++++++++++++++++++++ 8 files changed, 76 insertions(+), 13 deletions(-) diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 2758d76..26f9eef 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -57,6 +57,7 @@ MVP 只做： - 应用壳：主窗口、侧边导航、顶部用户区、内容区，Windows 10+ 优先。 +- 窗口策略：主窗口默认不最大化，初始 `1280x800`，居中且可调整大小；第二窗口保持小窗。 - 登录：本地固定账号 provider 和真实后端 provider 的可替换边界。 - 设置：主题、语言、窗口行为、快捷键、数据目录和日志策略。 - 主业务样例：电商商品图片 AI 优化的任务列表、状态、结果和失败反馈。 diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 4b904bf..5af6211 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -15,6 +15,10 @@ ### P0 · 模板必须具备 - 应用壳：侧边导航、顶部用户区、主内容区，默认布局适合长期业务操作。 +- 主窗口：默认不最大化，初始 `1280x800`，最小 `1024x720`，居中，可调整大小。 +- 页面布局：根容器 `width: 100%`、`height: 100vh`，内部使用 flex/grid 填满窗口。 +- 内容区：阅读型内容保留最大宽度；列表、仪表盘、设置页自适应拉伸。 +- 第二窗口：保持小窗，不参与主窗口最大化和尺寸恢复逻辑。 - 设置模块：主题、语言、窗口行为、快捷键、数据目录、日志策略。 - 登录模块：支持本地固定账号 provider；预留真实后端 provider。 - 主业务模块：以电商商品图片 AI 优化为样例，包含任务创建、列表、状态、结果和失败反馈。 @@ -35,6 +39,7 @@ P0 数据统计只做 6 个指标： P1 再考虑： +- 保存主窗口尺寸和最大化状态，下次启动恢复用户上次选择。 - 图片优化前后平均文件大小变化。 - 不同优化类型使用次数，例如增强、压缩、背景替换。 - 最常见错误类型 Top 5。 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 6a4040b..e81a5bf 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -195,7 +195,18 @@ image_task_results( - 托盘菜单由 `AppService` 配置。 - 热键触发目标可以是打开主窗口、打开快捷功能或创建快速任务。 -窗口策略：主窗口承载长期业务操作，默认应充分利用屏幕空间；第二窗口只保留轻量快捷功能，不承载复杂业务流程。 +窗口策略： + +- 主窗口承载长期业务操作，默认不最大化。 +- 主窗口初始尺寸为 `1280x800`，最小尺寸为 `1024x720`。 +- 主窗口启动时居中，并允许用户调整大小。 +- 前端根容器使用 `width: 100%` 和 `height: 100vh`。 +- 主应用布局内部使用 flex 或 grid 填满窗口。 +- 阅读型内容保留最大宽度，列表、仪表盘、设置页等工作型页面自适应拉伸。 +- 第二窗口保持当前小窗定位，不参与最大化、尺寸恢复和主布局填充逻辑。 +- 后续增强再保存主窗口尺寸和最大化状态，下次启动恢复用户选择。 + +实现顺序：先落主窗口初始尺寸和布局填充，再落路由骨架；窗口尺寸持久化依赖设置 schema 后续实现。 ## 关键风险 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index a52f8a8..405645d 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -26,17 +26,19 @@ | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | -| T-010 | 建立 Windows-first 主窗口布局策略 | T-002 | 明确是否默认最大化；侧边导航、顶部用户区、内容区能填满空余空间；小窗口无明显溢出 | TODO | -| T-011 | 搭建主应用路由骨架 | T-010 | `login`、`dashboard`、`image-optimizer`、`logs`、`statistics`、`settings`、`components` 路由可访问 | TODO | -| T-012 | 实现登录 provider 边界 | T-011 | 支持本地固定账号 provider；预留 remote provider；账号密码不写死在前端；登录事件写审计日志 | TODO | -| T-013 | 收敛设置模块 schema | T-011 | 主题、语言、窗口行为、快捷键、数据目录、日志策略都有统一配置定义和默认值 | TODO | +| T-010 | 确定 Windows-first 窗口与布局策略 | T-002 | 主窗口默认不最大化，初始 `1280x800`，最小 `1024x720`，居中，可调整大小；页面根容器 `width: 100%`、`height: 100vh`；内部用 flex/grid 填满窗口；第二窗口保持小窗 | DONE | +| T-011 | 实现主窗口启动参数与根布局策略 | T-010 | Go 侧设置主窗口初始宽高、居中、可调整大小；前端根容器和主布局填满窗口；阅读型内容有最大宽度，列表/仪表盘/设置页可自适应拉伸 | TODO | +| T-012 | 搭建主应用路由骨架 | T-011 | `login`、`dashboard`、`image-optimizer`、`logs`、`statistics`、`settings`、`components` 路由可访问 | TODO | +| T-013 | 实现登录 provider 边界 | T-012 | 支持本地固定账号 provider；预留 remote provider；账号密码不写死在前端；登录事件写审计日志 | TODO | +| T-014 | 收敛设置模块 schema | T-012 | 主题、语言、窗口行为、快捷键、数据目录、日志策略都有统一配置定义和默认值 | TODO | +| T-015 | 持久化窗口尺寸和最大化状态 | T-014 | 保存主窗口尺寸和最大化状态；下次启动恢复用户上次选择；第二窗口不参与该逻辑 | TODO | ## Phase 2 · 业务样例与日志统计 | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | -| T-020 | 建立商品图片 AI 优化任务模型 | T-012 | `image_tasks`、`image_task_results` 迁移和基础测试通过；可创建模拟任务 | TODO | -| T-021 | 实现审计日志与运行日志边界 | T-012 | 审计日志和运行日志分开；登录、设置变更、任务创建、任务失败可记录 | TODO | +| T-020 | 建立商品图片 AI 优化任务模型 | T-013 | `image_tasks`、`image_task_results` 迁移和基础测试通过；可创建模拟任务 | TODO | +| T-021 | 实现审计日志与运行日志边界 | T-013 | 审计日志和运行日志分开；登录、设置变更、任务创建、任务失败可记录 | TODO | | T-022 | 实现 P0 数据统计 | T-020 | 今日处理图片数、成功率、平均耗时、失败数、今日操作日志数、7 天趋势可查询 | TODO | | T-023 | 实现商品图片 AI 优化页面 | T-020 | 上传/选择图片、任务列表、状态、结果预览、失败提示路径可用 | TODO | @@ -44,8 +46,8 @@ | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | -| T-030 | 建立常用组件示例页 | T-011 | 输入框、多选框、下拉框、多行文本、表格、筛选、分页、状态标签有可运行示例 | TODO | -| T-031 | 文档化 Wails bindings 生成流程 | T-011 | README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求 | TODO | +| T-030 | 建立常用组件示例页 | T-012 | 输入框、多选框、下拉框、多行文本、表格、筛选、分页、状态标签有可运行示例 | TODO | +| T-031 | 文档化 Wails bindings 生成流程 | T-012 | README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求 | TODO | | T-032 | 补充 Windows 打包验证文档 | T-031 | `wails3 package` 前置条件、输出目录和常见失败处理写入 README 或 docs | TODO | | T-033 | 完成一次模板 smoke 清单 | T-023 | 登录、设置、业务样例、日志、统计、组件示例、托盘、热键都按清单验证并记录结果 | TODO | diff --git a/docs/current-state.md b/docs/current-state.md index 89235db..56449a5 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -25,6 +25,10 @@ - 本地数据库：SQLite，用户配置目录下 `cmbone/cmbone.db` - 当前主窗口路由：`/#/` - 当前第二窗口路由：`/#/second` +- 已确定主窗口策略：默认不最大化，初始 `1280x800`，最小 `1024x720`，居中，可调整大小。 +- 已确定页面布局策略：根容器 `width: 100%`、`height: 100vh`，内部 flex/grid 填满窗口。 +- 已确定内容区策略：阅读型内容保留最大宽度；列表、仪表盘、设置页自适应拉伸。 +- 已确定第二窗口策略：保持小窗，不参与主窗口最大化和尺寸恢复逻辑。 ## 当前命令 @@ -81,7 +85,7 @@ wails3 dev ## 下一步 -从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-010`：建立 Windows-first 主窗口布局策略。 +从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-011`：实现主窗口启动参数与根布局策略。 ## 当前 blocker diff --git a/docs/quality-document.md b/docs/quality-document.md index 67c4580..aea1dda 100644 --- a/docs/quality-document.md +++ b/docs/quality-document.md @@ -8,7 +8,7 @@ | 产品定位 | B | 已校准为 Windows-first 可复用桌面应用模板，后续需要代码落地 | | 后端服务 | B | 现有服务边界清晰，登录、日志、统计和业务样例服务尚未实现 | | 本地存储 | B | SQLite 初始化和基础测试已存在，目标新增表需要迁移和测试 | -| 前端结构 | B- | Vue 组件按功能拆分，但尚未形成模板化主布局和目标路由 | +| 前端结构 | B- | Vue 组件按功能拆分，窗口和布局策略已明确，但尚未代码落地为模板化主布局和目标路由 | | 构建验证 | B | Go 测试、前端构建、后端编译可运行 | | 文档 | B+ | Harness Coding 文档已接入，并同步了模板愿景 | @@ -44,7 +44,7 @@ ## 改进方向 -- 建立 Windows-first 主窗口最大化和自适应布局策略。 +- 按已确定的 Windows-first 窗口和布局策略实现主窗口启动参数、根容器和主布局。 - 为登录、日志、图片任务和统计新增服务、模型、迁移和测试。 - 为商品图片 AI 优化样例补充真实页面闭环。 - 为 Wails bindings 生成流程补充完整操作说明。 diff --git a/docs/routes.md b/docs/routes.md index bae85f6..e11182f 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -33,11 +33,25 @@ - 顶部区域：当前用户、运行状态、快捷动作。 - 内容区：路由页面，填满剩余空间。 -Windows 10+ 是主要体验目标。主窗口是否默认最大化需要通过任务确认，但内容区必须能稳定填满空余区域，不能只占左上角小块。 +Windows 10+ 是主要体验目标。主窗口策略已经确定： + +- 默认不最大化。 +- 初始宽高：`1280x800`。 +- 最小宽高：`1024x720`。 +- 启动时居中。 +- 允许用户调整大小。 +- 页面根容器使用 `width: 100%` 和 `height: 100vh`。 +- 主布局内部使用 flex 或 grid，让侧边导航、顶部区域和内容区稳定填满窗口。 +- 阅读型内容使用最大宽度，建议 `max-width: 960px` 并居中。 +- 列表、仪表盘、设置页等工作型页面自适应拉伸，占满可用内容区。 +- 第二窗口保持小窗，不参与主窗口最大化、尺寸恢复和布局填充逻辑。 + +后续增强：保存主窗口尺寸和最大化状态，下次启动恢复用户上次选择。 ## 页面规则 - 新增页面必须先确认属于模板能力、业务样例还是开发者示例。 - 主业务页面放在主窗口，不放在第二窗口。 - 第二窗口保持轻量快捷功能，不承载长期复杂业务流程。 +- 页面内容不得只占左上角小块；除阅读型内容外，默认应填满主内容区域。 - 路由变化必须同步本文和相关任务验收。 diff --git a/progress.md b/progress.md index 93a3e90..80403fa 100644 --- a/progress.md +++ b/progress.md @@ -52,3 +52,29 @@ - `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。