feat: 增加 Windows 本地开发启动脚本 #14

New Issue

2026-08-21T10:20:21+08:00

ila commented

2026-08-21 10:20:21 +08:00

基本信息

类型：需求 / 开发工具
所属 Epic：#3
所属 MVP / 版本：#4（MVP-0）
阶段：已完成

依赖与并行

前置工单：#6、#11
是否允许与 #12、#13 并行：是；仅封装已有构建和启动入口，不改变产品契约
原因：脚本依赖现有 portal 和 mock provider 入口，不依赖 MVP-0 集成验收完成。

原始需求

来源：用户对话
提出时间：2026-08-21
关键原话：用户要求“帮我编写启动项目的 bat 脚本”，并确认按 Agent 建议创建。

目标

提供 Windows 单入口本地开发脚本，让维护者能可靠启动、停止、重启和检查 Chorus portal，并可单独启动 mock provider；使用本机 MySQL 8 环境配置，同时避免误执行迁移、AutoMigrate 或 seed。

做什么

新增 scripts/chorus-dev.bat 作为用户入口，并以 scripts/chorus-dev.ps1 实现可靠的进程管理。
支持 start、stop、restart、status、start-mock。
默认读取仓库外 D:\OPC\chorus-tools\chorus-test.env.ps1，允许通过参数覆盖。
检查 Go、环境文件、数据库 TCP、端口和重复实例；构建临时二进制后后台启动。
PID、日志和临时二进制保存到 %LOCALAPPDATA%\Chorus\dev；停止前核对进程路径。
启动后探测 portal 登录页，输出 URL 和日志路径。

不做什么

不自动执行数据库迁移、AutoMigrate、seed 或创建测试账号。
不启动或修改本机 MySQL 服务，不删除数据库或业务文件。
不修改 portal、worker、provider、API 或生产部署行为。
不把凭据、完整 DSN 或测试密码写入日志、工单和仓库。

已确认方案

BAT 只做稳定入口，PowerShell 负责 Windows 进程、路径和健康检查。
使用已构建的临时 EXE，避免 go run 父子进程导致停止不完整。
普通 start 只启动 portal；start-mock 独立启动 mock，避免暗示 worker 已完整接入。
停止操作只针对 PID 文件记录且可执行文件路径匹配的 Chorus 进程。

设计证据

修改类型：非 UI 开发工具
替代证据：本工单中的运行、进程、安全与回退设计
无需 UI 原型原因：不改变用户页面、交互或产品流程。

文档影响

更新 Local-Development-and-Verification Wiki 的启动、停止、日志和排错命令
按需更新 Project-Profile 常用命令
无长期文档影响

验收标准

start/stop/restart/status/start-mock 在 Windows PowerShell/cmd 下工作。
路径包含空格时能启动，缺失 Go、环境文件、DSN、数据库或端口占用时明确失败。
重复启动不产生第二实例；陈旧 PID 可识别并安全清理。
stop 不终止路径不匹配的无关进程。
portal 登录页健康检查通过，并输出访问地址与 stdout/stderr 日志路径。
脚本不运行迁移、AutoMigrate 或 seed，且不输出凭据和完整 DSN。
git diff --check、Harness 严格检查和脚本专项验证通过。

风险与回退

风险：错误 PID 导致停止无关进程；通过 PID、进程路径和预期二进制绝对路径三重核对。
风险：后台进程启动失败但脚本误报成功；通过端口与 HTTP 健康检查确认。
回退：停止已记录进程并回退本工单提交；运行状态文件位于用户本地应用数据目录，不删除数据库或用户文件。

实施结果

实现提交：d9358b3。
文档镜像提交：babfbb1。
已推送分支：main。
Wiki：Local-Development-and-Verification@bf8347d2ea78、Project-Profile@233014296f1a。
任务归档：Task-14-增加-Windows-本地开发启动脚本@e7527760e2f5。
测试：go test ./... -count=1 通过；Harness 严格检查通过；42 项 Harness 单元测试通过；Wiki 镜像检查通过；git diff --check 通过。
脚本专项验证：默认启动、重复启动、状态、停止、带空格环境路径、独立 mock、restart、缺失环境、端口占用和跨工作目录调用通过。
未验证：未连接真实上游或生产环境；未执行破坏性的伪造 PID 对抗测试，路径匹配保护已通过代码检查和正常流程验证。
状态：待用户验收，工单保持打开。

验收结论

用户于 2026-08-21 明确确认 #14 验收通过。
工单关闭；任务归档 revision：86ab87e5cef11f6eec107205529397c21d84fd77。

## 基本信息 - 类型：需求 / 开发工具 - 所属 Epic：#3 - 所属 MVP / 版本：#4（MVP-0） - 阶段：已完成 ## 依赖与并行 - 前置工单：#6、#11 - 是否允许与 #12、#13 并行：是；仅封装已有构建和启动入口，不改变产品契约 - 原因：脚本依赖现有 portal 和 mock provider 入口，不依赖 MVP-0 集成验收完成。 ## 原始需求 - 来源：用户对话 - 提出时间：2026-08-21 - 关键原话：用户要求“帮我编写启动项目的 bat 脚本”，并确认按 Agent 建议创建。 ## 目标提供 Windows 单入口本地开发脚本，让维护者能可靠启动、停止、重启和检查 Chorus portal，并可单独启动 mock provider；使用本机 MySQL 8 环境配置，同时避免误执行迁移、AutoMigrate 或 seed。 ## 做什么 - 新增 `scripts/chorus-dev.bat` 作为用户入口，并以 `scripts/chorus-dev.ps1` 实现可靠的进程管理。 - 支持 `start`、`stop`、`restart`、`status`、`start-mock`。 - 默认读取仓库外 `D:\OPC\chorus-tools\chorus-test.env.ps1`，允许通过参数覆盖。 - 检查 Go、环境文件、数据库 TCP、端口和重复实例；构建临时二进制后后台启动。 - PID、日志和临时二进制保存到 `%LOCALAPPDATA%\Chorus\dev`；停止前核对进程路径。 - 启动后探测 portal 登录页，输出 URL 和日志路径。 ## 不做什么 - 不自动执行数据库迁移、AutoMigrate、seed 或创建测试账号。 - 不启动或修改本机 MySQL 服务，不删除数据库或业务文件。 - 不修改 portal、worker、provider、API 或生产部署行为。 - 不把凭据、完整 DSN 或测试密码写入日志、工单和仓库。 ## 已确认方案 - BAT 只做稳定入口，PowerShell 负责 Windows 进程、路径和健康检查。 - 使用已构建的临时 EXE，避免 `go run` 父子进程导致停止不完整。 - 普通 `start` 只启动 portal；`start-mock` 独立启动 mock，避免暗示 worker 已完整接入。 - 停止操作只针对 PID 文件记录且可执行文件路径匹配的 Chorus 进程。 ## 设计证据 - 修改类型：非 UI 开发工具 - 替代证据：本工单中的运行、进程、安全与回退设计 - 无需 UI 原型原因：不改变用户页面、交互或产品流程。 ## 文档影响 - [x] 更新 Local-Development-and-Verification Wiki 的启动、停止、日志和排错命令 - [x] 按需更新 Project-Profile 常用命令 - [ ] 无长期文档影响 ## 验收标准 - [x] `start/stop/restart/status/start-mock` 在 Windows PowerShell/cmd 下工作。 - [x] 路径包含空格时能启动，缺失 Go、环境文件、DSN、数据库或端口占用时明确失败。 - [x] 重复启动不产生第二实例；陈旧 PID 可识别并安全清理。 - [x] `stop` 不终止路径不匹配的无关进程。 - [x] portal 登录页健康检查通过，并输出访问地址与 stdout/stderr 日志路径。 - [x] 脚本不运行迁移、AutoMigrate 或 seed，且不输出凭据和完整 DSN。 - [x] `git diff --check`、Harness 严格检查和脚本专项验证通过。 ## 风险与回退 - 风险：错误 PID 导致停止无关进程；通过 PID、进程路径和预期二进制绝对路径三重核对。 - 风险：后台进程启动失败但脚本误报成功；通过端口与 HTTP 健康检查确认。 - 回退：停止已记录进程并回退本工单提交；运行状态文件位于用户本地应用数据目录，不删除数据库或用户文件。 ## 实施结果 - 实现提交：`d9358b3`。 - 文档镜像提交：`babfbb1`。 - 已推送分支：`main`。 - Wiki：`Local-Development-and-Verification@bf8347d2ea78`、`Project-Profile@233014296f1a`。 - 任务归档：`Task-14-增加-Windows-本地开发启动脚本@e7527760e2f5`。 - 测试：`go test ./... -count=1` 通过；Harness 严格检查通过；42 项 Harness 单元测试通过；Wiki 镜像检查通过；`git diff --check` 通过。 - 脚本专项验证：默认启动、重复启动、状态、停止、带空格环境路径、独立 mock、restart、缺失环境、端口占用和跨工作目录调用通过。 - 未验证：未连接真实上游或生产环境；未执行破坏性的伪造 PID 对抗测试，路径匹配保护已通过代码检查和正常流程验证。 - 状态：待用户验收，工单保持打开。 ## 验收结论 - 用户于 2026-08-21 明确确认 #14 验收通过。 - 工单关闭；任务归档 revision：`86ab87e5cef11f6eec107205529397c21d84fd77`。

ila referenced this issue

2026-08-21 10:20:43 +08:00

mvp: MVP-0 单上游安全异步生成闭环 #4

ila referenced this issue from a commit

2026-08-21 10:36:19 +08:00

feat: 增加 Windows 本地开发启动脚本 (#14)

ila referenced this issue from a commit

2026-08-21 10:36:19 +08:00

docs: 记录 Windows 启动脚本流程 (#14)

ila closed this issue

2026-08-21 10:55:57 +08:00

ila referenced this issue