docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+9
View File
@@ -1,3 +1,4 @@
// 项目可配置的首次引导:账号资料、工作区、可选邀请和问卷在一个事务内完成。
package platform
import (
@@ -9,10 +10,13 @@ import (
"strings"
)
// Question 引用 surveyTypes 中的固定题目键,Required 决定缺省或空白答案是否允许。
type Question struct {
Key string `json:"key"`
Required bool `json:"required"`
}
// OnboardingConfig 按项目配置必需工作区及问题清单,缺省配置允许空引导。
type OnboardingConfig struct {
RequireWorkspace bool `json:"require_workspace"`
Questions []Question `json:"questions"`
@@ -23,6 +27,7 @@ var surveyTypes = map[string]string{
"previous_use": "boolean", "purpose": "string", "company_size": "string",
}
// ParseOnboarding 启动时严格解析配置,拒绝未配置项目、未知题目和重复键。
func ParseOnboarding(raw string, callbacks map[string]string) (map[string]OnboardingConfig, error) {
configs := map[string]OnboardingConfig{}
if strings.TrimSpace(raw) == "" {
@@ -51,6 +56,7 @@ func ParseOnboarding(raw string, callbacks map[string]string) (map[string]Onboar
return configs, nil
}
// validAnswers 先验证提交键与类型,再检查必答题;必答布尔 false 合法,null 与空白必答文本不合法。
func validAnswers(config OnboardingConfig, answers map[string]json.RawMessage) bool {
questions := map[string]Question{}
for _, question := range config.Questions {
@@ -89,6 +95,7 @@ func validAnswers(config OnboardingConfig, answers map[string]json.RawMessage) b
return true
}
// onboarding GET 返回配置和已完成状态;POST 锁账户后检查既有结果,防止并发创建重复工作区。
func (s *service) onboarding(w http.ResponseWriter, r *http.Request, project, account string) error {
config := s.onboardingConfigs[project]
if config.Questions == nil {
@@ -143,6 +150,7 @@ func (s *service) onboarding(w http.ResponseWriter, r *http.Request, project, ac
}
var prior json.RawMessage
err = tx.QueryRowContext(r.Context(), "SELECT result FROM onboarding_responses WHERE project=$1 AND account_id=$2", project, account).Scan(&prior)
// 已完成直接返回已存 result;邀请明文不落库,所以重复请求不会重新返回 invite_url。
if err == nil {
reply(w, 200, response{"completed": true, "result": prior, "already_completed": true})
return nil
@@ -178,6 +186,7 @@ VALUES($1,$2,$3,'viewer',$4,now()+interval '7 days') RETURNING id::text
invitation = s.origin + "/s/" + token
}
}
// 结果只保存工作区和邀请 ID;明文 URL 仅随首次成功提交返回。
answers, _ := json.Marshal(input.Answers)
resultJSON, _ := json.Marshal(result)
_, err = tx.ExecContext(r.Context(), "INSERT INTO onboarding_responses(project,account_id,answers,result) VALUES($1,$2,$3,$4)", project, account, answers, resultJSON)