hurole
d22fdc9618
## 后端改动 - 添加 Project.envPresets 字段（JSON 格式） - 移除 Deployment.env 字段，统一使用 envVars - 更新部署 DTO，支持 envVars (Record<string, string>) - pipeline-runner 支持解析并注入 envVars 到环境 - 移除稀疏检出模板和相关环境变量 - 优化代码格式（Biome lint & format） ## 前端改动 - 新增 EnvPresetsEditor 组件（支持单选/多选/输入框类型） - 项目创建/编辑界面集成环境预设编辑器 - 部署界面基于预设动态生成环境变量表单 - 移除稀疏检出表单项 - 项目详情页添加环境变量预设配置 tab - 优化部署界面布局（基本参数 & 环境变量分区） ## 文档 - 添加完整文档目录结构（docs/） - 创建设计文档 design-0005（部署流程重构） - 添加 API 文档、架构设计文档等 ## 数据库 - 执行 prisma db push 同步 schema 变更
117 lines
2.9 KiB
Markdown
117 lines
2.9 KiB
Markdown
---
|
||
title: 设计文档模板
|
||
summary: 记录一个功能/模块的设计方案、权衡与落地计划（建议配套 ADR）。
|
||
owners:
|
||
- team: <team>
|
||
reviewers:
|
||
- <name-or-team>
|
||
status: draft
|
||
date: 2026-01-03
|
||
version: 0.1.0
|
||
related:
|
||
- adr: docs/architecture/adr-xxxx-<slug>.md
|
||
- pr: <link>
|
||
- issue: <link>
|
||
---
|
||
|
||
# 设计文档：<标题>
|
||
|
||
## 1. 背景（Context）
|
||
|
||
- 当前问题是什么？为什么现在要做？
|
||
- 相关现状：已有模块/接口/数据模型（附链接）
|
||
- 约束：技术栈、部署方式、团队边界、时间/人力
|
||
|
||
## 2. 目标（Goals）
|
||
|
||
- [ ] 目标 1（可验证）
|
||
- [ ] 目标 2（可验证）
|
||
|
||
## 3. 非目标（Non-goals）
|
||
|
||
- 不做什么（防止范围膨胀）
|
||
|
||
## 4. 需求与范围（Requirements & Scope）
|
||
|
||
- 用户/角色：谁会用？（例如：管理员、开发者、CI runner）
|
||
- 功能需求：
|
||
- R1:
|
||
- R2:
|
||
- 非功能需求：性能、可用性、可维护性、可观测性
|
||
|
||
## 5. 方案概览（High-level Design）
|
||
|
||
- 用 5-10 行描述整体方案（模块、数据流、调用链）
|
||
- 关键选择：为什么选这个方案？
|
||
|
||
## 6. 详细设计（Detailed Design）
|
||
|
||
### 6.1 接口/API 设计
|
||
|
||
- 新增/变更端点（路径、方法、权限、请求/响应示例）
|
||
- 错误码与错误语义（与 `BusinessError` 对齐）
|
||
|
||
### 6.2 数据模型/数据库
|
||
|
||
- Prisma model 变更（字段、索引、迁移策略）
|
||
- 数据一致性与幂等策略（例如：重试/重复提交）
|
||
|
||
### 6.3 任务/队列/异步处理（如有）
|
||
|
||
- 队列模型：入队、出队、并发、重试、死信/失败处理
|
||
- 状态机：状态枚举与迁移
|
||
|
||
### 6.4 配置与环境变量
|
||
|
||
- 新增 env（默认值、是否敏感、是否需要重启）
|
||
|
||
### 6.5 可观测性
|
||
|
||
- 日志：关键日志点、traceId/requestId（如有）
|
||
- 指标：成功率、延迟、队列长度、失败原因分布
|
||
- 告警：P0/P1 触发条件
|
||
|
||
### 6.6 安全与权限
|
||
|
||
- 认证：是否要求登录（session）
|
||
- 授权：角色/资源权限（项目级、流水线级）
|
||
- 数据安全：敏感信息、token、日志脱敏
|
||
|
||
## 7. 影响与权衡（Trade-offs）
|
||
|
||
- 性能影响
|
||
- 运维影响
|
||
- 对现有接口/调用方的影响
|
||
- 技术债与后续演进
|
||
|
||
## 8. 兼容性与迁移（Compatibility & Migration）
|
||
|
||
- 是否 breaking change？
|
||
- 迁移步骤（DB、配置、数据回填）
|
||
- 回滚策略
|
||
|
||
## 9. 测试计划（Test Plan）
|
||
|
||
- 单测：覆盖哪些模块
|
||
- 集成测试：关键链路（如：创建部署 -> 入队 -> 执行 -> 状态更新）
|
||
- 手工验证：步骤清单
|
||
|
||
## 10. 发布计划（Rollout Plan）
|
||
|
||
- 分阶段：灰度/开关/逐步放量（如有）
|
||
- 监控指标与验收标准
|
||
|
||
## 11. 备选方案（Alternatives Considered）
|
||
|
||
- 方案 A：为什么不用
|
||
- 方案 B：为什么不用
|
||
|
||
## 12. 风险与开放问题（Risks & Open Questions）
|
||
|
||
- 风险 1
|
||
- 问题 1（需要谁来决定/何时决定）
|
||
|
||
## 13. 附录（Appendix）
|
||
|
||
- 相关链接：控制器、DTO、Prisma schema、PR 等
|