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
+20
View File
@@ -1,3 +1,4 @@
// 不可变画布图片资产:上传原图字节并保留身份,读取时按当前绑定画布权限决定可见性。
package platform
import (
@@ -20,9 +21,11 @@ import (
_ "golang.org/x/image/webp"
)
// assetLimit 是单图编码字节上限,assetPixelLimit 在完整解码前限制像素分配预算。
const assetLimit = 20 << 20
const assetPixelLimit = 40_000_000
// assetInfo 是公开元数据,URL 稳定引用私有原图路由,不包含图片内容或上传者身份。
type assetInfo struct {
ID string `json:"id"`
MIME string `json:"mime_type"`
@@ -32,12 +35,14 @@ type assetInfo struct {
URL string `json:"url"`
}
// assetURL 将项目与工作区按路径段转义,所有绑定校验使用同一 URL 生成规则。
func (s *service) assetURL(project, workspace, id string) string {
return s.origin + "/projects/" + url.PathEscape(project) + "/workspaces/" + url.PathEscape(workspace) + "/assets/" + id
}
// Decode headers first and bound allocation before decoding the actual image.
// The MIME comes from the decoder, never from the filename or upload header.
// inspectAsset 先读取尺寸预算再完整解码,并比较两次识别格式/尺寸,拒绝截断或伪造头部图片。
func inspectAsset(encoded []byte) (string, int, int, error) {
config, format, err := image.DecodeConfig(bytes.NewReader(encoded))
if err != nil {
@@ -55,6 +60,9 @@ func inspectAsset(encoded []byte) (string, int, int, error) {
}
return "image/" + format, config.Width, config.Height, nil
}
// uploadAsset 分两次事务检查编辑权限:接收慢 multipart 正文和解码时不持有工作区锁。
// 幂等键限定在上传者/工作区,重复请求必须保持相同图片摘要和可选资源 ID。
func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -70,6 +78,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
reject(w, 400, "invalid_resource_id")
return nil
}
// 兼容旧版直接返回 assetInfo;指定 X-Resource-Id 的客户端获得带请求 ID 的 v2 应用回执。
respond := func(info assetInfo) {
if resourceID == "" {
reply(w, 201, info)
@@ -152,6 +161,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
reject(w, 403, "forbidden")
return nil
}
// 第二次取锁后重读权限和幂等记录,防止上传期间撤权或并发重试产生重复资产。
digest := sha256.Sum256(encoded)
hash := hex.EncodeToString(digest[:])
info := assetInfo{MIME: mime, Bytes: len(encoded), Width: width, Height: height}
@@ -192,6 +202,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
}
// A missing receipt is unknown: callers may only retry the same resource/key/bytes.
// assetOperation 在当前成员授权下查找本人上传回执;缺记录为 unknown,不能据此换键重传或判定零写入。
func (s *service) assetOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -223,6 +234,9 @@ func (s *service) assetOperation(w http.ResponseWriter, r *http.Request, project
reply(w, 200, response{"protocol_version": 2, "request_id": key, "status": "applied", "asset": info})
return nil
}
// assetReadable 依赖调用方持有工作区锁:无绑定时只允许上传者/admin,有绑定时需至少一个绑定画布可读。
// 绑定可读性复用 lockMaterial,因此继承根画布权限并尊重子图归档状态。
func assetReadable(r *http.Request, tx *sql.Tx, project, workspace, id, account string) (bool, error) {
var uploader string
err := tx.QueryRowContext(r.Context(), `SELECT uploaded_by::text FROM canvas_assets WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, id).Scan(&uploader)
@@ -273,6 +287,7 @@ func assetReadable(r *http.Request, tx *sql.Tx, project, workspace, id, account
}
// Metadata uses the same read policy as original bytes; it is not a persistent grant.
// getAssetMetadata 每次重新鉴权,读取不可变身份摘要后先提交释放锁,再写 JSON,不发放持久权限。
func (s *service) getAssetMetadata(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -318,6 +333,7 @@ func (s *service) getAssetMetadata(w http.ResponseWriter, r *http.Request, proje
return nil
}
// getAsset 同时服务原图与固定预览变体;先一致读取权限/字节,释放事务后才缩图或写响应。
func (s *service) getAsset(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -383,6 +399,7 @@ func (s *service) getAsset(w http.ResponseWriter, r *http.Request, project, acco
return err
}
// attachCanvasAssets 为文档内显式 assetId 或同工作区托管 URL 追加绑定;不删除旧绑定,调用方先验证权限。
func (s *service) attachCanvasAssets(r *http.Request, tx *sql.Tx, project, workspace, board string, raw json.RawMessage) error {
for _, data := range canvasNodeData(raw) {
id, _ := data["assetId"].(string)
@@ -406,6 +423,9 @@ func (s *service) attachCanvasAssets(r *http.Request, tx *sql.Tx, project, works
}
return nil
}
// validateCanvasAssets 对托管 URL 强制 ID/URL 一致并实时验证可读性,合法引用在同事务中建立当前画布绑定。
// 普通外部图片 URL 在此跳过,交给快照结构校验;它们不会成为私有资产绑定。
func (s *service) validateCanvasAssets(r *http.Request, tx *sql.Tx, project, workspace, account string, raw json.RawMessage) (bool, error) {
for _, data := range canvasNodeData(raw) {
id, explicit := data["assetId"].(string)