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
+13
View File
@@ -1,3 +1,4 @@
// 素材 CRUD、根画布授权继承与乐观版本控制;画布专用结构由其他文件处理。
package platform
import (
@@ -8,6 +9,8 @@ import (
"strconv"
)
// lockMaterial 先锁工作区,再向上遍历最多八层子图祖先获取根素材授权,返回目标类型与有效角色。
// 任一祖先关系归档则不可访问;子素材单独授权不能绕过父级。事务由调用方持有。
func lockMaterial(ctx context.Context, tx *sql.Tx, project, workspace, material, account string) (string, string, error) {
var locked, kind, role string
err := tx.QueryRowContext(ctx, "SELECT id::text FROM workspaces WHERE project=$1 AND id=$2 FOR UPDATE", project, workspace).Scan(&locked)
@@ -36,6 +39,7 @@ func lockMaterial(ctx context.Context, tx *sql.Tx, project, workspace, material,
return kind, role, err
}
// expectedVersion 解析带双引号的正整数 If-Match;缺少返回 428,格式错误返回 400。
func expectedVersion(w http.ResponseWriter, r *http.Request) (int64, bool) {
header := r.Header.Get("If-Match")
if header == "" {
@@ -53,10 +57,13 @@ func expectedVersion(w http.ResponseWriter, r *http.Request) (int64, bool) {
}
return version, true
}
// setVersion 将素材版本写成带引号 ETag,与 expectedVersion 的输入格式对应。
func setVersion(w http.ResponseWriter, version int64) {
w.Header().Set("ETag", strconv.Quote(strconv.FormatInt(version, 10)))
}
// materials 的 GET 转入筛选列表,POST 要求工作区编辑权限并按种类验证内容后创建版本一。
func (s *service) materials(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method == http.MethodGet {
return s.listMaterials(w, r, project, account)
@@ -110,6 +117,7 @@ VALUES($1,$2,$3,$4,$5,$6,$7,$8) RETURNING id::text,slug
return nil
}
// material 先校验根级权限;读取返回完整内容与 ETag,修改/删除同时要求角色和预期版本。
func (s *service) material(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPatch && r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -182,6 +190,7 @@ WHERE project=$1 AND workspace_id=$2 AND id=$3 AND version=$7
if err != nil {
return err
}
// 已通过可见性检查但版本条件未命中,视为并发冲突;事务回滚,不能覆盖其他客户端更新。
if n == 0 {
reject(w, 412, "version_conflict")
return nil
@@ -196,6 +205,7 @@ WHERE project=$1 AND workspace_id=$2 AND id=$3 AND version=$7
return nil
}
// openMaterial 记录当前账户最近打开时间,重复打开更新同一记录,不修改素材内容版本。
func (s *service) openMaterial(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -224,6 +234,7 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET opened_at
return nil
}
// listMaterials 按授权与筛选返回元数据,默认隐藏子图;排序片段只从固定白名单选择。
func (s *service) listMaterials(w http.ResponseWriter, r *http.Request, project, account string) error {
sort := r.URL.Query().Get("sort")
orders := map[string]string{
@@ -267,6 +278,7 @@ func (s *service) listMaterials(w http.ResponseWriter, r *http.Request, project,
reject(w, 400, "invalid_filter")
return nil
}
// 子图默认通过父画布进入;显式请求后仍需根级权限且整条祖先链未归档。
includeSubgraphs := false
if value := r.URL.Query().Get("include_subgraphs"); value != "" {
if value != "true" && value != "false" {
@@ -314,6 +326,7 @@ ORDER BY `+order+` LIMIT $7 OFFSET $8`, project, r.PathValue("workspace"), accou
if err := rows.Err(); err != nil {
return err
}
// SQL 多取一条探测后页;响应截回 limit,并给出下一次应使用的 offset。
var next *int
if len(items) > limit {
items = items[:limit]