chengma/cmsp
2
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

初始化 Wails v2 + Vue3 骨架与 SQLite 存储 #4

New Issue
Open
opened 2026-09-02 15:31:35 +08:00 by ila · 2 comments
ila commented 2026-09-02 15:31:35 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：#2
  • 所属 MVP / 版本：#3
  • 阶段：实施

依赖与并行

  • 前置工单：无
  • 是否允许与前置工单并行：是
  • 原因：本项目当前没有其他进行中的工单，本任务是所有后续任务的基础。

子项目影响

  • 仅影响的子项目 / 交付单元：cmsp 桌面应用（单一交付单元）
  • 是否跨子项目：否
  • 是否修改共享接口或契约：否
  • 各子项目需要执行的验证：go build ./...、go test ./...、wails build

原始需求

  • 来源：用户对话
  • 提出时间：2026-09-02
  • 关键原话或脱敏摘要：「接下来使用当前系统的的go版本初始化骨架。尽量从初级程序员的角度来编写文档和代码，因为后续是初级程序员来维护和更新。」

要解决什么

仓库目前只有文档和原型，没有任何产品代码。需要建立可运行、可构建、可读的 Go 骨架，
并确定目录结构、配置读写方式和 SQLite 表结构，供后续所有任务在其上叠加。

维护者是初级程序员，因此代码优先直白易读：不用泛型技巧、不做提前抽象、
每个包职责单一、注释解释「为什么」和边界而不是逐行翻译代码。

做什么 / 不做什么

  • 做：Go module 与目录骨架；Wails v2 应用入口与窗口；Vue3 + Naive UI 前端两个页面（按已确认原型 v4 的结构与命名，先用假数据）；配置读写与校验；SQLite 打开、建表与商品仓储；日志脱敏工具；go test 覆盖配置与仓储。
  • 不做：不调用货憨憨任何接口（下一个工单做）；不做淘宝相关任何功能；不做任务引擎；界面不追求像素级还原原型，但导航、工具栏结构与按钮名称必须一致。

已确认方案

技术栈按项目档案：Go 1.23.0、Wails v2、Vue 3、Naive UI、SQLite。
SQLite 驱动使用纯 Go 实现 modernc.org/sqlite，避免要求初级维护者配置 CGO 与 gcc。

目录：

main.go                Wails 启动入口
app.go                 暴露给前端的方法，只做校验与转发
internal/config/       配置结构、默认值、校验、读写
internal/store/        SQLite 打开、建表、商品仓储
internal/logx/         日志与脱敏
frontend/              Vue3 + Naive UI

预计修改文件：

  • go.mod、main.go、app.go
  • internal/config/config.go、internal/config/config_test.go
  • internal/store/store.go、internal/store/product.go、internal/store/store_test.go
  • internal/logx/logx.go、internal/logx/logx_test.go
  • frontend/（Vue3 工程与两个页面）
  • .gitignore（补充 Go 与前端构建产物）

需求变化记录

日期 变化内容 原因 用户确认
无 是

设计与原型门禁

  • 修改类型：新页面
  • 所需设计证据：已确认原型
  • 可编辑设计源、线上原型链接和访问检查：https://qux.ilapage.cn/#/apps/6a97c618191a826306a7f5f7 （已访问确认可打开）
  • 审核版本、revision、复制版本或确认日期及识别方式：v4，2026-09-02，7 屏 32 连线，起始屏「商品列表」
  • 本地 HTML 导出：未要求
  • 状态：已确认
  • 确认人、确认时间和覆盖范围：项目负责人，2026-09-02，覆盖商品列表页、参数设置页、店铺下拉、任务进行中、运行日志子窗口、淘宝登录失效弹窗

文档影响

  • 更新项目档案或本地开发与验证
  • 更新架构与代码地图

交付文档影响

  • 无交付文档影响，原因：内部工具，尚未确定外部交付对象，本任务也不产生用户可用功能。

任务记录与可选快照

  • 单次任务事实来源：当前 Gitea 工单正文与评论
  • 默认不创建任务快照

验收标准

  • go build ./... 通过
  • go test ./... 全部通过
  • wails build 产出可执行文件
  • 程序启动后显示左侧导航（商品列表 / 参数设置），可折叠
  • 两个页面结构与按钮名称与原型 v4 一致
  • 配置可保存并在重启后读回
  • SQLite 文件被创建，商品表结构符合设计
  • 代码中无任何账号、密码、token 明文；日志脱敏有单元测试覆盖

验证方式

go build ./...
go test ./...
wails build

风险和回退

  • 风险：低。不接外部接口、不写真实数据、不涉及凭据。
  • 回退：git revert 本任务提交。
## 基本信息 - 类型：需求 - 所属 Epic：#2 - 所属 MVP / 版本：#3 - 阶段：实施 ## 依赖与并行 - 前置工单：无 - 是否允许与前置工单并行：是 - 原因：本项目当前没有其他进行中的工单，本任务是所有后续任务的基础。 ## 子项目影响 - 仅影响的子项目 / 交付单元：cmsp 桌面应用（单一交付单元） - 是否跨子项目：否 - 是否修改共享接口或契约：否 - 各子项目需要执行的验证：`go build ./...`、`go test ./...`、`wails build` ## 原始需求 - 来源：用户对话 - 提出时间：2026-09-02 - 关键原话或脱敏摘要：「接下来使用当前系统的的go版本初始化骨架。尽量从初级程序员的角度来编写文档和代码，因为后续是初级程序员来维护和更新。」 ## 要解决什么 仓库目前只有文档和原型，没有任何产品代码。需要建立可运行、可构建、可读的 Go 骨架， 并确定目录结构、配置读写方式和 SQLite 表结构，供后续所有任务在其上叠加。 维护者是初级程序员，因此代码优先直白易读：不用泛型技巧、不做提前抽象、 每个包职责单一、注释解释「为什么」和边界而不是逐行翻译代码。 ## 做什么 / 不做什么 - 做：Go module 与目录骨架；Wails v2 应用入口与窗口；Vue3 + Naive UI 前端两个页面（按已确认原型 v4 的结构与命名，先用假数据）；配置读写与校验；SQLite 打开、建表与商品仓储；日志脱敏工具；`go test` 覆盖配置与仓储。 - 不做：不调用货憨憨任何接口（下一个工单做）；不做淘宝相关任何功能；不做任务引擎；界面不追求像素级还原原型，但导航、工具栏结构与按钮名称必须一致。 ## 已确认方案 技术栈按项目档案：Go 1.23.0、Wails v2、Vue 3、Naive UI、SQLite。 SQLite 驱动使用纯 Go 实现 `modernc.org/sqlite`，避免要求初级维护者配置 CGO 与 gcc。 目录： ``` main.go Wails 启动入口 app.go 暴露给前端的方法，只做校验与转发 internal/config/ 配置结构、默认值、校验、读写 internal/store/ SQLite 打开、建表、商品仓储 internal/logx/ 日志与脱敏 frontend/ Vue3 + Naive UI ``` 预计修改文件： - `go.mod`、`main.go`、`app.go` - `internal/config/config.go`、`internal/config/config_test.go` - `internal/store/store.go`、`internal/store/product.go`、`internal/store/store_test.go` - `internal/logx/logx.go`、`internal/logx/logx_test.go` - `frontend/`（Vue3 工程与两个页面） - `.gitignore`（补充 Go 与前端构建产物） ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | | 无 | | 是 | ## 设计与原型门禁 - 修改类型：新页面 - 所需设计证据：已确认原型 - 可编辑设计源、线上原型链接和访问检查：https://qux.ilapage.cn/#/apps/6a97c618191a826306a7f5f7 （已访问确认可打开） - 审核版本、revision、复制版本或确认日期及识别方式：v4，2026-09-02，7 屏 32 连线，起始屏「商品列表」 - 本地 HTML 导出：未要求 - 状态：已确认 - 确认人、确认时间和覆盖范围：项目负责人，2026-09-02，覆盖商品列表页、参数设置页、店铺下拉、任务进行中、运行日志子窗口、淘宝登录失效弹窗 ## 文档影响 - [x] 更新项目档案或本地开发与验证 - [x] 更新架构与代码地图 ## 交付文档影响 - [x] 无交付文档影响，原因：内部工具，尚未确定外部交付对象，本任务也不产生用户可用功能。 ## 任务记录与可选快照 - 单次任务事实来源：当前 Gitea 工单正文与评论 - [x] 默认不创建任务快照 ## 验收标准 - [ ] `go build ./...` 通过 - [ ] `go test ./...` 全部通过 - [ ] `wails build` 产出可执行文件 - [ ] 程序启动后显示左侧导航（商品列表 / 参数设置），可折叠 - [ ] 两个页面结构与按钮名称与原型 v4 一致 - [ ] 配置可保存并在重启后读回 - [ ] SQLite 文件被创建，商品表结构符合设计 - [ ] 代码中无任何账号、密码、token 明文；日志脱敏有单元测试覆盖 ## 验证方式 ```powershell go build ./... go test ./... wails build ``` ## 风险和回退 - 风险：低。不接外部接口、不写真实数据、不涉及凭据。 - 回退：`git revert` 本任务提交。
ila commented 2026-09-02 16:00:50 +08:00
Author
Owner
Copy Link
Copy Source

最终证据

测试结果（真实执行）

go vet ./...                                    无输出
go build ./...                                  通过
go test ./...                                   config / logx / store 全部 ok
wails build -clean                              Built 'buildin\cmsp.exe' in 24.885s (16 MB)
python dev_scripts/harness.py check --strict    DevHarness 检查通过
python -m unittest discover -s tests            Ran 55 tests, OK

冒烟测试（临时程序，验证后已删除，未进仓库）：

1. 默认配置 OK，端口范围 19666 - 19765
2. 已写入 config.yaml，2595 字节，含注释：true
3. 读回账号 13500000000，密码前导 0 保留：true
4. 数据库就绪，结构版本 5
5. 按店铺查到 1 条，下载状态 pending
6. 日志脱敏：登录 password=*** cookie _m_h5_tk=***

环境决定

项 结论
Wails 版本 v2.15.0 稳定版。v3 最新为 v3.0.0-beta.16（2026-08-29），18 天内发了 10 个 beta，API 仍在变；三个参考项目都是 v2
Go 版本 本机 go1.23.0（C:\go1230）。Wails v2.15.0 要求 >= 1.25.0，经负责人确认采用 GOTOOLCHAIN=auto 自动拉取工具链，不升级本机 Go
SQLite 驱动 modernc.org/sqlite 纯 Go 实现，不需要 CGO 与 gcc
迁移 v3 的准备 Wails API 只出现在 main.go 与 app.go，internal/ 对 Wails 零依赖

提交

  • 2cefa67 feat: 初始化 Wails v2 + Vue3 骨架与 SQLite 存储
  • 5c5c682 docs: 记录原型确认结果并移除已删除设计规范的引用
  • 9415c20 chore: 删除淘宝流程设计规范文档

已推送到 origin/main。实现提交与文档镜像提交分开。

长期文档影响

页面 revision
Project-Profile 06187f883b4e
Architecture-and-Code-Map 94d20f4ed447
Product-Requirements-Overview dfc7d9b0abe1

面向初级维护者的措施

  • 每个包开头写「设计约定，改代码前请先读」
  • store.go 写明迁移语句只能往末尾追加，绝不能改已发布的
  • config.go 写明新增字段要改四处，漏一处单测会失败
  • 保存配置按模板渲染以保留注释，有 TestSaveKeepsComments 守着
  • TestTaobaoConfigHasNoCredentialFields 挡住后续往淘宝配置加账号密码
  • 未实现的方法返回「还没实现，见工单 R1」，不静默失败

过程中修正的两个问题

  1. 提交历史混淆：一次 git add -A 导致骨架代码被并进文档提交，提交信息只写了文档。推送前发现，已 git reset --soft 重做为三笔独立提交。
  2. build/ 被误忽略：继承自 DevHarness 的通用规则 build/ 会让 Wails 的图标与 manifest 无法提交，别人克隆后 wails build 失败。改为只忽略 build/bin/，并在 .gitignore 写明原因。

安全处理

负责人在实施期间放入 payloads/ 的抓包文件含真实手机号（createUser 字段 21 处）以及两个 HAR（含 Cookie 与 token）。按负责人指示已加入 .gitignore（payloads/ 与 *.har），未进入任何提交。提交前做了凭据扫描，0 命中。

未验证部分

  • 界面未经人工实机操作验证。cmsp.exe 构建成功，但没有真实点击过窗口：没有 GUI 环境可自动化验证。需要负责人双击 buildin\cmsp.exe 确认导航折叠、两个页面、日志窗口和路径选择框的实际表现。
  • 下载数据、下载视频、上传数据、店铺下拉均未实现，点击只会提示「还没实现」，属于本工单范围外（R1~R5）。
  • 图片空间容量卡片是占位提示，未接 getMaterialSize。

补充发现（对后续工单有用）

负责人提供的 huohanhan_product.har 是商品列表页抓包，包含 product/shop/getPage（12 次）、product/shop/getCount（10 次）、erp/shop/all（3 次），R1 需要的三个接口都有真实请求与响应可对照。

但其中 batchUpdateShopProductVideo、uploadFiles、getMaterialSize 出现 0 次，因此需求总览的 Q1 与 Q2 仍未解决，R5 仍不能开始实现，需要单独抓一次上传视频的包。

状态置为待验收。

## 最终证据 ### 测试结果（真实执行） ``` go vet ./... 无输出 go build ./... 通过 go test ./... config / logx / store 全部 ok wails build -clean Built 'buildin\cmsp.exe' in 24.885s (16 MB) python dev_scripts/harness.py check --strict DevHarness 检查通过 python -m unittest discover -s tests Ran 55 tests, OK ``` 冒烟测试（临时程序，验证后已删除，未进仓库）： ``` 1. 默认配置 OK，端口范围 19666 - 19765 2. 已写入 config.yaml，2595 字节，含注释：true 3. 读回账号 13500000000，密码前导 0 保留：true 4. 数据库就绪，结构版本 5 5. 按店铺查到 1 条，下载状态 pending 6. 日志脱敏：登录 password=*** cookie _m_h5_tk=*** ``` ### 环境决定 | 项 | 结论 | |---|---| | Wails 版本 | **v2.15.0 稳定版**。v3 最新为 v3.0.0-beta.16（2026-08-29），18 天内发了 10 个 beta，API 仍在变；三个参考项目都是 v2 | | Go 版本 | 本机 `go1.23.0`（`C:\go1230`）。Wails v2.15.0 要求 >= 1.25.0，经负责人确认采用 `GOTOOLCHAIN=auto` 自动拉取工具链，不升级本机 Go | | SQLite 驱动 | `modernc.org/sqlite` 纯 Go 实现，不需要 CGO 与 gcc | | 迁移 v3 的准备 | Wails API 只出现在 `main.go` 与 `app.go`，`internal/` 对 Wails 零依赖 | ### 提交 - `2cefa67` feat: 初始化 Wails v2 + Vue3 骨架与 SQLite 存储 - `5c5c682` docs: 记录原型确认结果并移除已删除设计规范的引用 - `9415c20` chore: 删除淘宝流程设计规范文档 已推送到 `origin/main`。实现提交与文档镜像提交分开。 ### 长期文档影响 | 页面 | revision | |---|---| | Project-Profile | `06187f883b4e` | | Architecture-and-Code-Map | `94d20f4ed447` | | Product-Requirements-Overview | `dfc7d9b0abe1` | ### 面向初级维护者的措施 - 每个包开头写「设计约定，改代码前请先读」 - `store.go` 写明迁移语句只能往末尾追加，绝不能改已发布的 - `config.go` 写明新增字段要改四处，漏一处单测会失败 - 保存配置按模板渲染以保留注释，有 `TestSaveKeepsComments` 守着 - `TestTaobaoConfigHasNoCredentialFields` 挡住后续往淘宝配置加账号密码 - 未实现的方法返回「还没实现，见工单 R1」，不静默失败 ### 过程中修正的两个问题 1. **提交历史混淆**：一次 `git add -A` 导致骨架代码被并进文档提交，提交信息只写了文档。推送前发现，已 `git reset --soft` 重做为三笔独立提交。 2. **build/ 被误忽略**：继承自 DevHarness 的通用规则 `build/` 会让 Wails 的图标与 manifest 无法提交，别人克隆后 `wails build` 失败。改为只忽略 `build/bin/`，并在 `.gitignore` 写明原因。 ### 安全处理 负责人在实施期间放入 `payloads/` 的抓包文件含真实手机号（`createUser` 字段 21 处）以及两个 HAR（含 Cookie 与 token）。按负责人指示已加入 `.gitignore`（`payloads/` 与 `*.har`），未进入任何提交。提交前做了凭据扫描，0 命中。 ### 未验证部分 - **界面未经人工实机操作验证**。`cmsp.exe` 构建成功，但没有真实点击过窗口：没有 GUI 环境可自动化验证。需要负责人双击 `buildin\cmsp.exe` 确认导航折叠、两个页面、日志窗口和路径选择框的实际表现。 - 下载数据、下载视频、上传数据、店铺下拉均未实现，点击只会提示「还没实现」，属于本工单范围外（R1~R5）。 - 图片空间容量卡片是占位提示，未接 `getMaterialSize`。 ### 补充发现（对后续工单有用） 负责人提供的 `huohanhan_product.har` 是商品列表页抓包，包含 `product/shop/getPage`（12 次）、`product/shop/getCount`（10 次）、`erp/shop/all`（3 次），**R1 需要的三个接口都有真实请求与响应可对照**。 但其中 `batchUpdateShopProductVideo`、`uploadFiles`、`getMaterialSize` 出现 **0 次**，因此需求总览的 **Q1 与 Q2 仍未解决**，R5 仍不能开始实现，需要单独抓一次上传视频的包。 状态置为**待验收**。
ila commented 2026-09-02 16:55:35 +08:00
Author
Owner
Copy Link
Copy Source

实机验证后的缺陷修复

负责人实机运行 run_dev.bat 后发现界面无法正常显示，截图证据见对话。
定位并修复两个缺陷，均属本工单遗留，修复提交 d8e9078。

缺陷一：Naive UI 组件从未注册

frontend/src/main.js 少了 app.use(naive)。模板里的 n-button、
n-input、n-select、n-data-table、n-modal 全部未注册，Vue 将其
当作未知 HTML 元素处理，表现为：

现象 原因
按钮变成纯文本链接 未知元素只渲染插槽文字
输入框、下拉框、表格不显示 无插槽内容，渲染为空
日志窗常驻页面、不受控制 n-modal 未注册，v-model:show 失效
侧边栏正常 它是手写 HTML+CSS，不依赖 Naive UI

最后一行是定位线索：唯一不用 Naive UI 的部分是唯一正常的部分。

修复后打包产物由 258 KB 增至 1.46 MB，可反证此前 Naive UI 确实
没有进入产物。

缺陷二：窗口高于屏幕，标题栏被顶出可视区

负责人屏幕工作区   1920 x 1030（去掉任务栏）
系统缩放           125%
原设定窗口         1440 x 900（逻辑像素，照搬原型尺寸）
实际占用           1800 x 1125 物理像素   ← 高出 95px

Wails 的 Width/Height 是逻辑像素，Windows 按系统缩放放大。窗口高于
可用高度后被居中，上边缘移出屏幕，标题栏与最小化/最大化/关闭按钮一起消失。

修复：改为 WindowStartState: options.Maximised，还原尺寸降至 1280x760，
最小尺寸降至 1024x600，并在 main.go 中写明这个坑，避免后续维护者
再按设计稿尺寸写死。

顺带给工具栏加 flex-wrap，窄窗口下筛选控件换行而非挤压。

验证

负责人重新运行 run_dev.bat 后确认界面正常显示。

go build ./...      通过
npx vite build      通过

过程反思

本工单先前的最终证据里写了「界面未经人工实机操作验证」，但仍将状态
置为待验收。既然界面从未被人打开过，当时就不应报待验收，而应先请
负责人运行一次。

后续涉及界面的工单（#8 及之后），改为先由负责人实机确认，再回写证据
和置待验收。

## 实机验证后的缺陷修复 负责人实机运行 `run_dev.bat` 后发现界面无法正常显示，截图证据见对话。 定位并修复两个缺陷，均属本工单遗留，修复提交 `d8e9078`。 ### 缺陷一：Naive UI 组件从未注册 `frontend/src/main.js` 少了 `app.use(naive)`。模板里的 `n-button`、 `n-input`、`n-select`、`n-data-table`、`n-modal` 全部未注册，Vue 将其 当作未知 HTML 元素处理，表现为： | 现象 | 原因 | |---|---| | 按钮变成纯文本链接 | 未知元素只渲染插槽文字 | | 输入框、下拉框、表格不显示 | 无插槽内容，渲染为空 | | 日志窗常驻页面、不受控制 | `n-modal` 未注册，`v-model:show` 失效 | | 侧边栏正常 | 它是手写 HTML+CSS，不依赖 Naive UI | 最后一行是定位线索：唯一不用 Naive UI 的部分是唯一正常的部分。 修复后打包产物由 **258 KB 增至 1.46 MB**，可反证此前 Naive UI 确实 没有进入产物。 ### 缺陷二：窗口高于屏幕，标题栏被顶出可视区 ``` 负责人屏幕工作区 1920 x 1030（去掉任务栏） 系统缩放 125% 原设定窗口 1440 x 900（逻辑像素，照搬原型尺寸） 实际占用 1800 x 1125 物理像素 ← 高出 95px ``` Wails 的 `Width`/`Height` 是逻辑像素，Windows 按系统缩放放大。窗口高于 可用高度后被居中，上边缘移出屏幕，标题栏与最小化/最大化/关闭按钮一起消失。 修复：改为 `WindowStartState: options.Maximised`，还原尺寸降至 1280x760， 最小尺寸降至 1024x600，并在 `main.go` 中写明这个坑，避免后续维护者 再按设计稿尺寸写死。 顺带给工具栏加 `flex-wrap`，窄窗口下筛选控件换行而非挤压。 ### 验证 负责人重新运行 `run_dev.bat` 后确认界面正常显示。 ``` go build ./... 通过 npx vite build 通过 ``` ### 过程反思 本工单先前的最终证据里写了「界面未经人工实机操作验证」，但仍将状态 置为待验收。既然界面从未被人打开过，当时就不应报待验收，而应先请 负责人运行一次。 后续涉及界面的工单（#8 及之后），改为先由负责人实机确认，再回写证据 和置待验收。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: chengma/cmsp#4