docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]
This commit is contained in:
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user