feat: 初始化 Go 项目骨架与可逆数据库迁移 #6

New Issue

2026-08-20T18:00:59+08:00

ila commented

2026-08-20 18:00:59 +08:00

基本信息

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

依赖与并行

前置工单：#5
是否允许与前置工单并行：否
原因：依赖项定义本工单所需的可执行环境、共享模型、接口或已确认设计；未满足时保持待实施，不标记阻塞。

子项目影响

仅影响的子项目 / 交付单元：仓库骨架、migrations
是否跨子项目：是
是否修改共享接口或契约：是；建立数据库结构和配置事实来源
各子项目需要执行的验证：见“验证方式”和验收标准。

原始需求

来源：用户对话；Product-Requirements-Overview、Architecture-and-Code-Map、Business-Rules-and-Glossary
提出时间：2026-08-20
关键原话或脱敏摘要：用户要求“为 MVP-0 的生产实现拆分单元工单”；本工单负责初始化 Go 项目骨架、运行配置和 MVP-0 可逆迁移。

要解决什么

仓库目前只有文档和原型，没有可构建的 Go 项目、生产迁移或配置入口。本工单建立后续单元任务共同依赖的最小骨架和数据库契约。

做什么 / 不做什么

做

初始化 Go 1.26.5 模块和 internal/core、internal/platform、portal 的最小可构建入口。
建立环境配置加载、必填项校验和 development/test/production 安全门禁，不输出密钥。
编写 users、providers、provider_models、prompt_templates、generations、generation_inputs、generation_outputs 的 up/down SQL。
明确索引、外键、唯一约束、删除行为、租约字段、attempt/error/rendered_prompt 字段。
建立幂等且可重复的默认 Prompt/ProviderModel/种子用户配置命令接口；测试只用构造数据。

不做

不使用 GORM AutoMigrate，不接入 admin/admin-ui 或 sys_*。
不实现业务编排、队列认领、上游请求、页面或真实 Provider 配置。
不把生产阈值和凭据硬编码为默认值。

已确认方案

migrations 是生产数据库结构唯一事实来源；每个版本有 up/down。
GORM 模型只能在后续工单映射既有 schema，应用启动绝不迁移表。
(user_id,idempotency_key) 唯一；取任务、用户历史和 ProviderModel 绑定具备明确索引。
默认 Prompt 使用 #2 前置确认的 chat 与 images_edits 数据，不写 Go 常量。

预计修改文件：

go.mod、必要的 go.sum
migrations/*.up.sql、migrations/*.down.sql
internal/、portal/ 最小入口与配置包
业务种子命令使用独立目录，不放入 dev_scripts/

需求变化记录

2026-08-20：#5 已完成技术验收并提供隔离 MySQL 8.4.8、Go 1.26.5 与 migrate v4.19.1，虽仍待用户验收但本工单真实环境依赖已满足；按用户“按照顺序开始建工单做工单”的授权继续实施。实现中若范围、接口、数据、依赖、验收或风险发生变化，必须先更新本工单；改变已确认结果时重新等待用户确认。

设计与原型门禁

修改类型：非 UI
所需设计证据：已确认的架构、数据、安全或流程设计；不要求 UI 原型
事实来源：核心 Wiki 与父工单 #4
状态：已确认；具体实现差异仍须按工单变化规则处理
无需 UI 原型原因：本工单不改变用户界面

文档影响

不影响长期文档
按实际变化更新 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations 或 Business-Rules-and-Glossary
Wiki 先改、在线回读后再同步 docs/，不得直接维护镜像

交付文档影响

无交付文档影响，原因：内部实现任务；若实际改变部署、配置或支持方式，执行前更新本项
更新已有交付文档
新增交付文档

验收标准

go build ./...、go vet ./...、go test ./... 通过。
空 MySQL 8 完成全量 up/down/up，逐项核对表、索引、外键和唯一约束。
重复执行种子命令不产生重复数据，默认 Prompt 与已确认文本一致。
应用启动路径不引用 AutoMigrate，仓库搜索无生产 AutoMigrate 调用。
生产环境缺少关键配置时失败关闭，日志不包含密钥或完整 DSN。

验证方式

go build ./...
go vet ./...
go test ./...
migrate -path migrations -database "<隔离 MySQL 8 URL>" up/down/up
schema、索引和约束查询
rg -n "AutoMigrate" --glob "*.go" .

未执行或因环境不足无法执行的验证必须如实回写，不得把预期结果记为通过。

风险和回退

风险：迁移错误会影响全部后续任务；只在空隔离库验证，未经用户授权不接触现有数据库。
风险：down 丢失数据是预期回退行为，但必须仅用于隔离验收并在工单写明。
回退：执行对应 down 并回退本工单提交；禁止用 AutoMigrate 修补差异。

实施与验证证据（2026-08-20）

实现：Go 1.26.5 模块、配置门禁、7 表可逆迁移、结构化默认 Prompt 和事务化幂等种子命令。
MySQL：隔离 8.4.8 完成 up/down/up；最终迁移版本 1、dirty=0。
schema：7 表、3 个关键索引、5 个外键及删除规则；重复用户幂等键、无效外键和无效状态均被数据库拒绝。
种子：连续执行两次后用户/Provider/ProviderModel/Prompt 数量为 1/1/2/2，已确认 Prompt 哈希稳定。
安全：Go 代码无 AutoMigrate；生产缺少关键变量时失败关闭，错误不含测试 DSN 的秘密值；未接触生产/共享数据库。
Go 验证：go build ./...、go vet ./...、go test ./... 和 config/seed race 测试通过。
文档验证：Harness 严格检查、42 项 Python 测试、Wiki 镜像一致性和 git diff --check 通过。
核心 Wiki revision：Project-Profile 662746817d09f4d182c6cf6db71e963d330141e8；Architecture-and-Code-Map a4a15b3cdb690590a8ce7a85edc42cfc7c400a2d；Local-Development-and-Verification c26069b43dadcab393678caf8f579c13cfa90068。
任务归档 revision：8d233d707f526cc0553d202e8d839ed6f1863875。
提交：de49b4d483bbc89e268b4dde378ec2b79c24d9c7、470b54c89e60207442e16f74df0d18b71ca99d29，均已推送。
未验证：GORM 模型和业务读写属于 #7 起；真实 Provider 密钥加密属于 #8。

当前状态：待用户验收，不关闭。#7 可基于已经验证的 schema 顺序继续。

验收结论

用户于 2026-08-21 明确确认 #6 验收通过。
MVP-0 单元验收文档提交：919e11f，已推送到 main。
任务归档 revision：011e628003dd。

## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#4（MVP-0） - 阶段：已完成 ## 依赖与并行 - 前置工单：#5 - 是否允许与前置工单并行：否 - 原因：依赖项定义本工单所需的可执行环境、共享模型、接口或已确认设计；未满足时保持待实施，不标记阻塞。 ## 子项目影响 - 仅影响的子项目 / 交付单元：仓库骨架、migrations - 是否跨子项目：是 - 是否修改共享接口或契约：是；建立数据库结构和配置事实来源 - 各子项目需要执行的验证：见“验证方式”和验收标准。 ## 原始需求 - 来源：用户对话；Product-Requirements-Overview、Architecture-and-Code-Map、Business-Rules-and-Glossary - 提出时间：2026-08-20 - 关键原话或脱敏摘要：用户要求“为 MVP-0 的生产实现拆分单元工单”；本工单负责初始化 Go 项目骨架、运行配置和 MVP-0 可逆迁移。 ## 要解决什么仓库目前只有文档和原型，没有可构建的 Go 项目、生产迁移或配置入口。本工单建立后续单元任务共同依赖的最小骨架和数据库契约。 ## 做什么 / 不做什么 ### 做 - 初始化 Go 1.26.5 模块和 `internal/core`、`internal/platform`、`portal` 的最小可构建入口。 - 建立环境配置加载、必填项校验和 `development/test/production` 安全门禁，不输出密钥。 - 编写 `users`、`providers`、`provider_models`、`prompt_templates`、`generations`、`generation_inputs`、`generation_outputs` 的 up/down SQL。 - 明确索引、外键、唯一约束、删除行为、租约字段、attempt/error/rendered_prompt 字段。 - 建立幂等且可重复的默认 Prompt/ProviderModel/种子用户配置命令接口；测试只用构造数据。 ### 不做 - 不使用 GORM AutoMigrate，不接入 admin/admin-ui 或 `sys_*`。 - 不实现业务编排、队列认领、上游请求、页面或真实 Provider 配置。 - 不把生产阈值和凭据硬编码为默认值。 ## 已确认方案 - migrations 是生产数据库结构唯一事实来源；每个版本有 up/down。 - GORM 模型只能在后续工单映射既有 schema，应用启动绝不迁移表。 - `(user_id,idempotency_key)` 唯一；取任务、用户历史和 ProviderModel 绑定具备明确索引。 - 默认 Prompt 使用 #2 前置确认的 `chat` 与 `images_edits` 数据，不写 Go 常量。预计修改文件： - `go.mod`、必要的 `go.sum` - `migrations/*.up.sql`、`migrations/*.down.sql` - `internal/`、`portal/` 最小入口与配置包 - 业务种子命令使用独立目录，不放入 `dev_scripts/` ## 需求变化记录 - 2026-08-20：#5 已完成技术验收并提供隔离 MySQL 8.4.8、Go 1.26.5 与 migrate v4.19.1，虽仍待用户验收但本工单真实环境依赖已满足；按用户“按照顺序开始建工单做工单”的授权继续实施。实现中若范围、接口、数据、依赖、验收或风险发生变化，必须先更新本工单；改变已确认结果时重新等待用户确认。 ## 设计与原型门禁 - 修改类型：非 UI - 所需设计证据：已确认的架构、数据、安全或流程设计；不要求 UI 原型 - 事实来源：核心 Wiki 与父工单 #4 - 状态：已确认；具体实现差异仍须按工单变化规则处理 - 无需 UI 原型原因：本工单不改变用户界面 ## 文档影响 - [ ] 不影响长期文档 - [x] 按实际变化更新 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations 或 Business-Rules-and-Glossary - Wiki 先改、在线回读后再同步 `docs/`，不得直接维护镜像 ## 交付文档影响 - [x] 无交付文档影响，原因：内部实现任务；若实际改变部署、配置或支持方式，执行前更新本项 - [ ] 更新已有交付文档 - [ ] 新增交付文档 ## 验收标准 - [x] `go build ./...`、`go vet ./...`、`go test ./...` 通过。 - [x] 空 MySQL 8 完成全量 up/down/up，逐项核对表、索引、外键和唯一约束。 - [x] 重复执行种子命令不产生重复数据，默认 Prompt 与已确认文本一致。 - [x] 应用启动路径不引用 AutoMigrate，仓库搜索无生产 AutoMigrate 调用。 - [x] 生产环境缺少关键配置时失败关闭，日志不包含密钥或完整 DSN。 ## 验证方式 - `go build ./...` - `go vet ./...` - `go test ./...` - `migrate -path migrations -database "<隔离 MySQL 8 URL>" up/down/up` - schema、索引和约束查询 - `rg -n "AutoMigrate" --glob "*.go" .` 未执行或因环境不足无法执行的验证必须如实回写，不得把预期结果记为通过。 ## 风险和回退 - 风险：迁移错误会影响全部后续任务；只在空隔离库验证，未经用户授权不接触现有数据库。 - 风险：down 丢失数据是预期回退行为，但必须仅用于隔离验收并在工单写明。 - 回退：执行对应 down 并回退本工单提交；禁止用 AutoMigrate 修补差异。 ## 实施与验证证据（2026-08-20） - 实现：Go 1.26.5 模块、配置门禁、7 表可逆迁移、结构化默认 Prompt 和事务化幂等种子命令。 - MySQL：隔离 8.4.8 完成 up/down/up；最终迁移版本 `1`、`dirty=0`。 - schema：7 表、3 个关键索引、5 个外键及删除规则；重复用户幂等键、无效外键和无效状态均被数据库拒绝。 - 种子：连续执行两次后用户/Provider/ProviderModel/Prompt 数量为 `1/1/2/2`，已确认 Prompt 哈希稳定。 - 安全：Go 代码无 `AutoMigrate`；生产缺少关键变量时失败关闭，错误不含测试 DSN 的秘密值；未接触生产/共享数据库。 - Go 验证：`go build ./...`、`go vet ./...`、`go test ./...` 和 config/seed race 测试通过。 - 文档验证：Harness 严格检查、42 项 Python 测试、Wiki 镜像一致性和 `git diff --check` 通过。 - 核心 Wiki revision：Project-Profile `662746817d09f4d182c6cf6db71e963d330141e8`；Architecture-and-Code-Map `a4a15b3cdb690590a8ce7a85edc42cfc7c400a2d`；Local-Development-and-Verification `c26069b43dadcab393678caf8f579c13cfa90068`。 - 任务归档 revision：`8d233d707f526cc0553d202e8d839ed6f1863875`。 - 提交：`de49b4d483bbc89e268b4dde378ec2b79c24d9c7`、`470b54c89e60207442e16f74df0d18b71ca99d29`，均已推送。 - 未验证：GORM 模型和业务读写属于 #7 起；真实 Provider 密钥加密属于 #8。当前状态：待用户验收，不关闭。#7 可基于已经验证的 schema 顺序继续。 ## 验收结论 - 用户于 2026-08-21 明确确认 #6 验收通过。 - MVP-0 单元验收文档提交：`919e11f`，已推送到 `main`。 - 任务归档 revision：`011e628003dd`。

ila referenced this issue

2026-08-20 18:01:08 +08:00

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

ila referenced this issue

2026-08-20 18:01:09 +08:00

epic: chorus 图文生成服务交付 #3

ila referenced this issue

2026-08-20 22:55:52 +08:00

chore: 准备 MVP-0 可复现开发与测试环境 #5

ila referenced this issue from a commit

2026-08-20 23:11:36 +08:00

feat: initialize Go schema and seed baseline (#6)