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
+14
View File
@@ -1,3 +1,4 @@
// Package platform 提供项目隔离的工作区、素材、画布和协作 API;HTTP 认证与业务事务分层处理。
package platform
import (
@@ -17,6 +18,7 @@ import (
"github.com/jackc/pgx/v5/pgconn"
)
// service 共享连接池与启动配置;canvasAI 可缺省,队列仅在配置了客户端时启动。
type service struct {
canvasAI *codex.CanvasClient
db *sql.DB
@@ -25,8 +27,10 @@ type service struct {
onboardingConfigs map[string]OnboardingConfig
}
// response 用于小型 JSON 对象;大型画布文档通常保留 RawMessage 避免重编码字段。
type response map[string]any
// reply 写出 JSON 与 no-store;value 为 nil 时只写状态,供 204 响应使用。
func reply(w http.ResponseWriter, status int, value any) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
@@ -36,10 +40,12 @@ func reply(w http.ResponseWriter, status int, value any) {
}
}
// reject 用稳定错误码表示可预期业务拒绝;调用者随后返回 nil,避免 protected 重复响应。
func reject(w http.ResponseWriter, status int, code string) {
reply(w, status, response{"error": code})
}
// decode 对普通业务 JSON 限制 1 MiB,拒绝未知字段以及第二个 JSON 值;失败已经写出 400。
func decode(w http.ResponseWriter, r *http.Request, value any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
decoder.DisallowUnknownFields()
@@ -54,8 +60,10 @@ func decode(w http.ResponseWriter, r *http.Request, value any) bool {
return true
}
// endpoint 接收已认证的 project/account;具体资源可见性仍由业务处理器在事务内校验。
type endpoint func(http.ResponseWriter, *http.Request, string, string) error
// protected 是统一路由包装:项目白名单/CORS、会话续期、资源别名解析、canonical 写入守卫和错误映射。
func (s *service) protected(callbacks map[string]string, handle endpoint) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
project := r.PathValue("project")
@@ -74,6 +82,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
w.Header().Set("Access-Control-Allow-Origin", origin)
w.Header().Set("Access-Control-Expose-Headers", "ETag, X-Canvas-Schema-Version, "+auth.SessionExpiryHeader)
}
// 预检只验证项目和 Origin,不要求 bearer;真正业务请求仍必须通过会话认证。
if r.Method == http.MethodOptions {
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type, If-Match, Idempotency-Key, X-Expected-Account, X-Resource-Id")
@@ -88,11 +97,13 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
account := session.AccountID
if err == nil {
auth.WriteSessionHeaders(w, session)
// 客户端可携带预期账户,阻止浏览器切换身份后把旧页面的写入落到新账户。
if expected := r.Header.Get("X-Expected-Account"); expected != "" && expected != account {
reject(w, 409, "identity_changed")
return
}
}
// 将 slug 或 UUID 统一为 UUID 后再分派,后续 SQL 无需兼容两种引用;这一步不替代资源授权。
if err == nil && r.PathValue("workspace") != "" {
var id string
err = s.db.QueryRowContext(r.Context(), "SELECT id::text FROM workspaces WHERE project=$1 AND (id::text=$2 OR slug=$2)", project, r.PathValue("workspace")).Scan(&id)
@@ -117,6 +128,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
if err == nil {
err = handle(w, r, project, account)
}
// 只公开可识别的约束/领域错误;其余依赖错误记录类型并统一返回 503。
if err != nil {
var pg *pgconn.PgError
switch {
@@ -140,6 +152,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
}
}
// Register 由 main 装配平台路径;私有 AI 客户端存在时启动进程级队列,公开短链接单独处理。
func Register(mux *http.ServeMux, db *sql.DB, callbacks map[string]string, origin string, configs map[string]OnboardingConfig, clients ...*codex.CanvasClient) {
s := &service{db: db, origin: origin, callbacks: callbacks, onboardingConfigs: configs}
if len(clients) > 0 {
@@ -198,6 +211,7 @@ func Register(mux *http.ServeMux, db *sql.DB, callbacks map[string]string, origi
var usernamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{2,39}$`)
// profile 只操作当前项目的本人账户;PATCH 规范化用户名后与 GET 共用完整资料响应。
func (s *service) profile(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method == http.MethodPatch {
var input struct {