OPC/chorus
2
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 完善技术基线与实施约束 #1

New Issue
Closed
opened 2026-08-20 14:45:55 +08:00 by ila · 1 comment
ila commented 2026-08-20 14:45:55 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：无（仓库尚无 Epic）
  • 所属 MVP / 版本：跨 MVP 开发基线
  • 阶段：已完成

依赖与并行

  • 前置工单：无
  • 是否允许与前置工单并行：是
  • 原因：只整理已确认的长期设计，不依赖产品代码。

子项目影响

  • 交付单元：internal/core、portal、admin、migrations 的长期文档及部署说明
  • 是否跨子项目：是
  • 是否修改共享接口或契约：仅完善设计基线，不修改运行代码；后续以 Wiki 与 migrations/ 为事实来源
  • 验证：Harness 严格检查、Wiki 镜像一致性检查、文档交叉核对

原始需求

  • 来源：用户对话
  • 提出时间：2026-08-20
  • 摘要：将全栈审查结论以及本地 go-admin、go-admin-ui 调研后的最终调整更新到项目文档；两个项目使用 D:\github\goadmin 中的版本。

要解决什么

修正管理端版本、生产迁移与代码生成边界、队列租约、安全、MVP、UI 和部署验收要求，使后续工单、原型和实现使用一致的长期事实来源。

做什么 / 不做什么

  • 做：固定来源提交和工具链；记录 schema-first CRUD 生成流程；完善架构、数据、MVP、安全、队列、UI、测试与部署要求；新增 Deployment-and-Operations。
  • 不做：不实现产品代码、迁移或 UI 原型；不运行 AutoMigrate；不导出 docs/task/；不加入计费、支付和内容审核等排除范围。

已确认方案

  1. 固定来源：go-admin f06540883b41d03782bb6b2c4150f298f328c6b6，go-admin-ui 67d393d713877572fab0b897296a4c1d525fc81d，go-admin-doc 424855aacf6905f3fde860c3331385cb25529a0d；构建和 CI 不依赖本地绝对路径。
  2. 生产表结构只由可审查的 migrations/*.up.sql 和 *.down.sql 演进。go-admin AutoMigrate 只能作为固定提交的研究参考，由人工在隔离、可丢弃数据库中独立执行，不进入产品启动、部署或生产命令。
  3. 管理端采用：版本化 SQL → 隔离开发库 → go-admin-ui 导入已有表 → 配置/预览/生成 CRUD → 人工评审 → 菜单/API 配置转换为可逆 SQL。生产不注册 dev-tools 路由；“生成迁移脚本”不视为业务 DDL。
  4. internal/core 只依赖 GORM 和标准库；gobreaker、imaging 放在 internal/platform，通过接口注入。
  5. ProviderModel 持有 api_type、能力、extra_body 和超时；补充 prompt_templates、lease token/owner、CAS 最终写入、用户级幂等键、索引/外键/唯一约束。
  6. MVP-0 自动把第一张图作为主图，模板可配置；图片角色编辑/排序属于 MVP-1。MVP-0 隐藏点数和 API Key 导航、延后公开注册，但移动端必须具备可用单列布局。
  7. 补充 CSRF、Cookie、密码哈希、登录节流、上传限制、SSRF 重定向/IPv6/代理/result URL、受保护输出、原子写入、错误脱敏、密钥 key_id 和轮换。
  8. UI 验收覆盖完整任务状态、认证失效、轮询错误、375/768/1024 宽度、44px 触控目标、键盘替代、焦点、aria-live 和 reduced-motion。
  9. 测试覆盖迁移 up/down、队列并发和陈旧 worker、SSRF、认证/CSRF/越权、HTMX E2E 与依赖安全检查。
  10. 新增部署拓扑、环境变量、迁移顺序、健康检查、存储备份/磁盘监控、worker 优雅退出、回退和生产关闭 dev-tools。

预计更新 Wiki：Project-Profile、Architecture-and-Code-Map、Business-Rules-and-Glossary、Local-Development-and-Verification、Common-Changes、Troubleshooting、Product-Requirements-Overview；新建 Deployment-and-Operations；更新 wiki-docs.json 并同步 docs/。

需求变化记录

日期 变化内容 原因 用户确认
2026-08-20 固定使用本地 go-admin/go-admin-ui 提交 避免按错误版本设计 是
2026-08-20 AutoMigrate 仅作隔离开发研究参考，生产仍只接受可逆 SQL 对齐实际初始化与 schema-first 流程 是
2026-08-20 将全部分析和调整写入长期文档 形成实施基线 是

设计与原型门禁

  • 修改类型：非 UI
  • 所需证据：架构、API、数据、状态和流程设计
  • 事实来源：上述固定提交和 2026-08-20 用户确认
  • HTML 快照：不适用
  • 状态：已确认
  • 确认人和范围：用户，2026-08-20，本工单全部文档调整
  • 无需 UI 原型：不实现页面，只定义后续验收约束。

文档影响

  • 更新项目档案或本地开发与验证
  • 更新架构与代码地图
  • 更新业务规则与术语
  • 更新常见修改或故障排查
  • 更新产品需求总览和部署运维页面

交付文档影响

  • 更新现有核心 Wiki，受众：开发与测试人员
  • 新增 Deployment-and-Operations，受众：开发与运维人员
  • 不需要客户代表验证；由维护者核对命令和边界

验收标准

  • 不再存在 Vue 2 等与固定提交冲突的描述。
  • 生产迁移、隔离初始化和代码生成边界清晰一致。
  • 架构、数据、MVP、安全、队列、UI、测试和部署要求无冲突。
  • 部署页已创建并纳入镜像映射。
  • 变更页面均在线回读 revision，本地镜像一致。
  • 严格检查、单元测试和 git diff --check 通过。

验证方式

python dev_scripts/harness.py sync
python dev_scripts/harness.py sync --check
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
git diff --check

本任务不包含 Go 产品代码；本机 Go/MySQL/migrate 也不满足目标基线，不伪记 Go 构建或迁移验证。

风险和回退

风险是多页约束重复或冲突。更新后按来源版本、MVP、数据、迁移、安全、UI、测试和部署交叉检查。回退时恢复本任务 Git 提交，并把 Wiki 恢复到更新前 revision；不涉及生产代码或数据。

过程说明

Gitea MCP 无法连接，按规则回退到 Gitea API；凭据从本地 gitea.env 进程内加载，不写入仓库或文档。

实施结果

最终差异

  • 固定 go-admin/go-admin-ui/go-admin-doc 三个来源提交，统一目标 Go 1.26.5、Node >=22、pnpm 9.15.1，并修正 go-admin-ui 为 Vue 3.5.41 + Element Plus 2.14.4 + Vue CLI 5.0.9。
  • 明确生产只运行可逆 SQL；AutoMigrate 仅可由人工在隔离可丢弃库研究固定提交结构。
  • 记录 go-admin-ui schema-first 导表/生成流程、菜单/API 配置转换和生产移除 dev-tools 的要求。
  • 完善 core/platform 依赖、ProviderModel 字段、租约 token/CAS、幂等、SSRF、鉴权文件、密钥信封/轮换、MVP、UI 状态及测试策略。
  • 新建 Deployment-and-Operations，并纳入 Wiki 镜像与根 README 导航。

修改文件

  • README.md、wiki-docs.json
  • docs/README.md
  • docs/00-project-profile.md
  • docs/02-architecture-and-code-map.md
  • docs/03-business-rules-and-glossary.md
  • docs/04-local-development-and-verification.md
  • docs/05-common-changes.md
  • docs/06-troubleshooting.md
  • docs/09-product-requirements-overview.md
  • docs/10-deployment-and-operations.md

Wiki 回读证据

  • Home：3d6efad79056ff85f7532e28a90c80f2c710c332
  • Project-Profile：4a1a822e3cce84386e80447f0aa05fad92544ce9
  • Architecture-and-Code-Map：b1268df4bd1d7e4fc6ca0a418da7215e61a4af91
  • Business-Rules-and-Glossary：284ba550f90df865e75f16b8852a55c6197787ce
  • Local-Development-and-Verification：4cb7c477267bfc28c8582e275e02e20acfc2c83e
  • Common-Changes：ec313fafcc8df6060e650e3d9ddf95be8d7eb63f
  • Troubleshooting：d37761a10ea18c62e0cd0680e65d9b462d79b4f5
  • Product-Requirements-Overview：8b37c55fc3231b78c9b0a9d8cd99ce6e7357c312
  • Deployment-and-Operations：040f4c2c3e16def91fe612fa09cf0a6aa7288445

验证结果

  • python dev_scripts/harness.py check --strict：通过。
  • python -m unittest discover -s tests -v：42/42 通过。
  • python dev_scripts/harness.py sync --check：16 个映射页面全部一致。
  • git diff --check：通过。
  • Go 构建/迁移未执行：本任务无产品代码，且本机 Go 1.23/MySQL 5.7/缺少 migrate 不满足已记录目标；未伪记为验证。
  • 未使用真实上游额度，未处理生产数据，未导出 docs/task/。

提交与推送

  • 264d930 docs: 完善技术基线与实施约束 (#1)
  • 3442daa docs: 补充密钥与界面验收约束 (#1)
  • 已推送至 origin/main。

验收记录

## 基本信息 - 类型：需求 - 所属 Epic：无（仓库尚无 Epic） - 所属 MVP / 版本：跨 MVP 开发基线 - 阶段：已完成 ## 依赖与并行 - 前置工单：无 - 是否允许与前置工单并行：是 - 原因：只整理已确认的长期设计，不依赖产品代码。 ## 子项目影响 - 交付单元：`internal/core`、`portal`、`admin`、`migrations` 的长期文档及部署说明 - 是否跨子项目：是 - 是否修改共享接口或契约：仅完善设计基线，不修改运行代码；后续以 Wiki 与 `migrations/` 为事实来源 - 验证：Harness 严格检查、Wiki 镜像一致性检查、文档交叉核对 ## 原始需求 - 来源：用户对话 - 提出时间：2026-08-20 - 摘要：将全栈审查结论以及本地 go-admin、go-admin-ui 调研后的最终调整更新到项目文档；两个项目使用 `D:\github\goadmin` 中的版本。 ## 要解决什么 修正管理端版本、生产迁移与代码生成边界、队列租约、安全、MVP、UI 和部署验收要求，使后续工单、原型和实现使用一致的长期事实来源。 ## 做什么 / 不做什么 - 做：固定来源提交和工具链；记录 schema-first CRUD 生成流程；完善架构、数据、MVP、安全、队列、UI、测试与部署要求；新增 `Deployment-and-Operations`。 - 不做：不实现产品代码、迁移或 UI 原型；不运行 AutoMigrate；不导出 `docs/task/`；不加入计费、支付和内容审核等排除范围。 ## 已确认方案 1. 固定来源：go-admin `f06540883b41d03782bb6b2c4150f298f328c6b6`，go-admin-ui `67d393d713877572fab0b897296a4c1d525fc81d`，go-admin-doc `424855aacf6905f3fde860c3331385cb25529a0d`；构建和 CI 不依赖本地绝对路径。 2. 生产表结构只由可审查的 `migrations/*.up.sql` 和 `*.down.sql` 演进。go-admin AutoMigrate 只能作为固定提交的研究参考，由人工在隔离、可丢弃数据库中独立执行，不进入产品启动、部署或生产命令。 3. 管理端采用：版本化 SQL → 隔离开发库 → go-admin-ui 导入已有表 → 配置/预览/生成 CRUD → 人工评审 → 菜单/API 配置转换为可逆 SQL。生产不注册 dev-tools 路由；“生成迁移脚本”不视为业务 DDL。 4. `internal/core` 只依赖 GORM 和标准库；gobreaker、imaging 放在 `internal/platform`，通过接口注入。 5. ProviderModel 持有 `api_type`、能力、`extra_body` 和超时；补充 prompt_templates、lease token/owner、CAS 最终写入、用户级幂等键、索引/外键/唯一约束。 6. MVP-0 自动把第一张图作为主图，模板可配置；图片角色编辑/排序属于 MVP-1。MVP-0 隐藏点数和 API Key 导航、延后公开注册，但移动端必须具备可用单列布局。 7. 补充 CSRF、Cookie、密码哈希、登录节流、上传限制、SSRF 重定向/IPv6/代理/result URL、受保护输出、原子写入、错误脱敏、密钥 key_id 和轮换。 8. UI 验收覆盖完整任务状态、认证失效、轮询错误、375/768/1024 宽度、44px 触控目标、键盘替代、焦点、aria-live 和 reduced-motion。 9. 测试覆盖迁移 up/down、队列并发和陈旧 worker、SSRF、认证/CSRF/越权、HTMX E2E 与依赖安全检查。 10. 新增部署拓扑、环境变量、迁移顺序、健康检查、存储备份/磁盘监控、worker 优雅退出、回退和生产关闭 dev-tools。 预计更新 Wiki：`Project-Profile`、`Architecture-and-Code-Map`、`Business-Rules-and-Glossary`、`Local-Development-and-Verification`、`Common-Changes`、`Troubleshooting`、`Product-Requirements-Overview`；新建 `Deployment-and-Operations`；更新 `wiki-docs.json` 并同步 `docs/`。 ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-20 | 固定使用本地 go-admin/go-admin-ui 提交 | 避免按错误版本设计 | 是 | | 2026-08-20 | AutoMigrate 仅作隔离开发研究参考，生产仍只接受可逆 SQL | 对齐实际初始化与 schema-first 流程 | 是 | | 2026-08-20 | 将全部分析和调整写入长期文档 | 形成实施基线 | 是 | ## 设计与原型门禁 - 修改类型：非 UI - 所需证据：架构、API、数据、状态和流程设计 - 事实来源：上述固定提交和 2026-08-20 用户确认 - HTML 快照：不适用 - 状态：已确认 - 确认人和范围：用户，2026-08-20，本工单全部文档调整 - 无需 UI 原型：不实现页面，只定义后续验收约束。 ## 文档影响 - [x] 更新项目档案或本地开发与验证 - [x] 更新架构与代码地图 - [x] 更新业务规则与术语 - [x] 更新常见修改或故障排查 - [x] 更新产品需求总览和部署运维页面 ## 交付文档影响 - [x] 更新现有核心 Wiki，受众：开发与测试人员 - [x] 新增 `Deployment-and-Operations`，受众：开发与运维人员 - [x] 不需要客户代表验证；由维护者核对命令和边界 ## 验收标准 - [x] 不再存在 Vue 2 等与固定提交冲突的描述。 - [x] 生产迁移、隔离初始化和代码生成边界清晰一致。 - [x] 架构、数据、MVP、安全、队列、UI、测试和部署要求无冲突。 - [x] 部署页已创建并纳入镜像映射。 - [x] 变更页面均在线回读 revision，本地镜像一致。 - [x] 严格检查、单元测试和 `git diff --check` 通过。 ## 验证方式 ```powershell python dev_scripts/harness.py sync python dev_scripts/harness.py sync --check python dev_scripts/harness.py check --strict python -m unittest discover -s tests -v git diff --check ``` 本任务不包含 Go 产品代码；本机 Go/MySQL/migrate 也不满足目标基线，不伪记 Go 构建或迁移验证。 ## 风险和回退 风险是多页约束重复或冲突。更新后按来源版本、MVP、数据、迁移、安全、UI、测试和部署交叉检查。回退时恢复本任务 Git 提交，并把 Wiki 恢复到更新前 revision；不涉及生产代码或数据。 ## 过程说明 Gitea MCP 无法连接，按规则回退到 Gitea API；凭据从本地 `gitea.env` 进程内加载，不写入仓库或文档。 ## 实施结果 ### 最终差异 - 固定 go-admin/go-admin-ui/go-admin-doc 三个来源提交，统一目标 Go 1.26.5、Node >=22、pnpm 9.15.1，并修正 go-admin-ui 为 Vue 3.5.41 + Element Plus 2.14.4 + Vue CLI 5.0.9。 - 明确生产只运行可逆 SQL；AutoMigrate 仅可由人工在隔离可丢弃库研究固定提交结构。 - 记录 go-admin-ui schema-first 导表/生成流程、菜单/API 配置转换和生产移除 dev-tools 的要求。 - 完善 core/platform 依赖、ProviderModel 字段、租约 token/CAS、幂等、SSRF、鉴权文件、密钥信封/轮换、MVP、UI 状态及测试策略。 - 新建 Deployment-and-Operations，并纳入 Wiki 镜像与根 README 导航。 ### 修改文件 - `README.md`、`wiki-docs.json` - `docs/README.md` - `docs/00-project-profile.md` - `docs/02-architecture-and-code-map.md` - `docs/03-business-rules-and-glossary.md` - `docs/04-local-development-and-verification.md` - `docs/05-common-changes.md` - `docs/06-troubleshooting.md` - `docs/09-product-requirements-overview.md` - `docs/10-deployment-and-operations.md` ### Wiki 回读证据 - Home：`3d6efad79056ff85f7532e28a90c80f2c710c332` - Project-Profile：`4a1a822e3cce84386e80447f0aa05fad92544ce9` - Architecture-and-Code-Map：`b1268df4bd1d7e4fc6ca0a418da7215e61a4af91` - Business-Rules-and-Glossary：`284ba550f90df865e75f16b8852a55c6197787ce` - Local-Development-and-Verification：`4cb7c477267bfc28c8582e275e02e20acfc2c83e` - Common-Changes：`ec313fafcc8df6060e650e3d9ddf95be8d7eb63f` - Troubleshooting：`d37761a10ea18c62e0cd0680e65d9b462d79b4f5` - Product-Requirements-Overview：`8b37c55fc3231b78c9b0a9d8cd99ce6e7357c312` - Deployment-and-Operations：`040f4c2c3e16def91fe612fa09cf0a6aa7288445` ### 验证结果 - `python dev_scripts/harness.py check --strict`：通过。 - `python -m unittest discover -s tests -v`：42/42 通过。 - `python dev_scripts/harness.py sync --check`：16 个映射页面全部一致。 - `git diff --check`：通过。 - Go 构建/迁移未执行：本任务无产品代码，且本机 Go 1.23/MySQL 5.7/缺少 migrate 不满足已记录目标；未伪记为验证。 - 未使用真实上游额度，未处理生产数据，未导出 `docs/task/`。 ### 提交与推送 - `264d930` docs: 完善技术基线与实施约束 (#1) - `3442daa` docs: 补充密钥与界面验收约束 (#1) - 已推送至 `origin/main`。 ## 验收记录 - 验收人：用户 - 验收时间：2026-08-20 - 结果：用户明确验收通过 - 任务归档：https://git.ilapage.cn/OPC/chorus/wiki/Task-1-%E5%AE%8C%E5%96%84%E6%8A%80%E6%9C%AF%E5%9F%BA%E7%BA%BF%E4%B8%8E%E5%AE%9E%E6%96%BD%E7%BA%A6%E6%9D%9F.- - 归档 revision：2cf3435c023f28b5684c8bf4432d1593b0511d30 - 实现提交：264d930、3442daa - 核心 Wiki 镜像：16 个映射页面执行 sync --check 全部通过 - Git：main 与 origin/main 双向差异为 0，远端已是最新 - 父工单：无，不需要同步 - docs/task/：按规则未导出
ila commented 2026-08-20 15:13:07 +08:00
Author
Owner
Copy Link
Copy Source

归档闭环完成：

  • Wiki 任务归档：Task-1-完善技术基线与实施约束
  • 归档 revision：05906c0230dd4676251f541afcb9545cda877de6
  • 实现提交：264d930、3442daa
  • 推送分支：origin/main
  • 归档后再次执行 python dev_scripts/harness.py sync --check：16 个核心/映射页面全部一致
  • 按规则未导出 docs/task/

工单保持“待验收”且继续开启，等待用户确认。

归档闭环完成： - Wiki 任务归档：[Task-1-完善技术基线与实施约束](https://git.ilapage.cn/OPC/chorus/wiki/Task-1-%E5%AE%8C%E5%96%84%E6%8A%80%E6%9C%AF%E5%9F%BA%E7%BA%BF%E4%B8%8E%E5%AE%9E%E6%96%BD%E7%BA%A6%E6%9D%9F.-) - 归档 revision：`05906c0230dd4676251f541afcb9545cda877de6` - 实现提交：`264d930`、`3442daa` - 推送分支：`origin/main` - 归档后再次执行 `python dev_scripts/harness.py sync --check`：16 个核心/映射页面全部一致 - 按规则未导出 `docs/task/` 工单保持“待验收”且继续开启，等待用户确认。
ila closed this issue 2026-08-20 16:06:38 +08:00
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: OPC/chorus#1