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
+24
View File
@@ -1,3 +1,4 @@
// PostgreSQL 研究库只读适配器:游标先选窄 ID 集合,再按同一事务快照批量补齐论文元数据。
package research
import (
@@ -14,6 +15,7 @@ import (
// The fixed Paper Atlas migration a3b677b preserves business columns as TEXT
// and BIGINT and creates the English title/abstract GIN expression below.
// No schema creation, indexing or other writes belong to this repository.
// PostgresRepository 的 prefix 仅由已校验 schema 构造;encoded 在启动 Check 成功后确定。
type PostgresRepository struct {
db *sql.DB
prefix string
@@ -23,6 +25,7 @@ type PostgresRepository struct {
var schemaName = regexp.MustCompile(`^[a-z][a-z0-9_]{0,35}$`)
// NewPostgresRepository 只构造仓库,不连接或迁移;调用方还需在对外服务前执行 Check。
func NewPostgresRepository(db *sql.DB, schema string) (*PostgresRepository, error) {
if db == nil || !schemaName.MatchString(schema) {
return nil, errors.New("invalid research database configuration")
@@ -30,10 +33,13 @@ func NewPostgresRepository(db *sql.DB, schema string) (*PostgresRepository, erro
return &PostgresRepository{db: db, prefix: `"` + schema + `".`, schema: schema}, nil
}
// query 只替换受信任的 schema 占位符;搜索词、ID 等业务值始终通过 SQL 参数绑定。
func (r *PostgresRepository) query(value string) string {
return strings.ReplaceAll(value, "{schema}", r.prefix)
}
// begin 为一次 API 请求建立可重复读、只读事务,并设置事务内的查询时间及内存限制。
// 设置失败先回滚;成功后由 List/Get/Check 的 defer 负责兜底回收事务。
func (r *PostgresRepository) begin(ctx context.Context) (*sql.Tx, error) {
tx, err := r.db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelRepeatableRead, ReadOnly: true})
if err != nil {
@@ -51,6 +57,7 @@ func (r *PostgresRepository) begin(ctx context.Context) (*sql.Tx, error) {
// Check resolves required columns and SELECT permissions without scanning the
// corpus. The migration publishes the complete schema atomically.
// Check 读取 schema 注释识别文本转义协议,用 WHERE false 探测字段和权限而不扫描语料。
func (r *PostgresRepository) Check(ctx context.Context) error {
tx, err := r.begin(ctx)
if err != nil {
@@ -88,6 +95,7 @@ func (r *PostgresRepository) Check(ctx context.Context) error {
return nil
}
// whereClause 构造可组合筛选片段及对应参数;作者用 simple 全文检索,标题/摘要用 english。
func whereClause(filters Filters) (string, []any) {
clauses, values := []string{}, []any{}
if filters.Query != "" {
@@ -112,8 +120,10 @@ func whereClause(filters Filters) (string, []any) {
return " WHERE " + strings.Join(clauses, " AND "), values
}
// scanner 让单行 QueryRow 与多行 Rows 共用论文投影读取逻辑。
type scanner interface{ Scan(...any) error }
// scanPaper 先解码数据库文本,再解析作者 JSON;空摘要和发布日期保留为 nil。
func (r *PostgresRepository) scanPaper(row scanner) (Paper, error) {
p := Paper{Authors: []string{}, Topics: []string{}, Sources: []Source{}}
var id int64
@@ -134,6 +144,7 @@ func (r *PostgresRepository) scanPaper(row scanner) (Paper, error) {
return p, err
}
// decodeAuthors 兼容直接姓名字符串与 arXiv 元组;交换姓/名展示顺序,忽略第四项所属机构。
func decodeAuthors(raw string) ([]string, error) {
var entries []json.RawMessage
if err := json.Unmarshal([]byte(raw), &entries); err != nil {
@@ -173,6 +184,7 @@ func decodeAuthors(raw string) ([]string, error) {
return names, nil
}
// positions 只读取 ID 和原始排序键;流式读取或关闭前的错误均交回上层终止本页。
func (r *PostgresRepository) positions(ctx context.Context, tx *sql.Tx, query string, args []any) ([]position, error) {
rows, err := tx.QueryContext(ctx, r.query(query), args...)
if err != nil {
@@ -191,12 +203,14 @@ func (r *PostgresRepository) positions(ctx context.Context, tx *sql.Tx, query st
return positions, rows.Err()
}
// List 在一个快照中完成锚点选择、详情补全和主题列表;多读一行判定是否还有下一页。
func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, error) {
result := Page{Items: []Paper{}, Topics: []string{}, PageSize: filters.PageSize}
cursor, err := decodeCursor(filters)
if err != nil {
return result, err
}
// 保留未转义筛选条件来生成游标摘要;仅实际 SQL 绑定值按已发布 schema 的 codec 转义。
original := filters
tx, err := r.begin(ctx)
if err != nil {
@@ -208,6 +222,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e
filters.Topic = encodeText(filters.Topic)
}
where, args := whereClause(filters)
// 最近排序按 ID 倒序,标题按 (title_key,id) 正序;向前翻页同时反转比较和 SQL 排序。
if cursor.ID != 0 {
clause := " AND "
if where == "" {
@@ -253,6 +268,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e
}
positions := []position{}
topicOnly := filters.Sort != "title" && filters.Topic != "" && filters.Query == ""
// 纯主题查询直接走标签关联索引,不必先读取所有匹配论文的宽行。
if topicOnly {
// The published paper_tags foreign key guarantees these IDs exist.
// Walk the (tag_id,paper_id) index instead of joining all matching
@@ -290,6 +306,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e
return result, err
}
}
// 常见搜索词先试 512/4096 的有限 ID 窗口;不足一页加一行时回退完整索引检索,避免漏项。
for _, window := range []int64{512, 4096} {
bound, op := int64(0), ">="
if anchor > window {
@@ -320,6 +337,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e
return result, err
}
}
// 截去探测行后恢复面向客户端的固定顺序,再按首尾锚点构造可用方向的游标。
more := len(positions) > filters.PageSize
if more {
positions = positions[:filters.PageSize]
@@ -336,6 +354,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e
if (!cursor.Before && more) || (cursor.Before && cursor.ID != 0) {
result.NextCursor = encodeCursor(original, positions[len(positions)-1], false)
}
// ANY 查询不保证输入顺序,先按 ID 收集再依照 positions 重新组装结果。
ids := make([]int64, len(positions))
byID := map[string]Paper{}
for i, p := range positions {
@@ -389,6 +408,7 @@ func (r *PostgresRepository) List(ctx context.Context, filters Filters) (Page, e
return result, tx.Commit()
}
// Get 与列表共享解码和 enrich,在同一事务内读取单篇论文及其附属信息。
func (r *PostgresRepository) Get(ctx context.Context, id int64) (Paper, error) {
tx, err := r.begin(ctx)
if err != nil {
@@ -408,11 +428,13 @@ func (r *PostgresRepository) Get(ctx context.Context, id int64) (Paper, error) {
// Batch metadata queries avoid per-paper round trips and share the page
// snapshot. User values are bound; only the validated schema is interpolated.
// enrich 批量原地填充 papers:主题、来源、DOI、投稿和决策,所有查询复用调用方事务。
func (r *PostgresRepository) enrich(ctx context.Context, tx *sql.Tx, papers []Paper) error {
if len(papers) == 0 {
return nil
}
ids := make([]int64, len(papers))
// 指针指向切片元素,使多组关系查询的追加结果直接回写最终页面。
byID := map[int64]*Paper{}
for i := range papers {
id, err := strconv.ParseInt(papers[i].ID, 10, 64)
@@ -466,6 +488,7 @@ func (r *PostgresRepository) enrich(ctx context.Context, tx *sql.Tx, papers []Pa
source.Label = "PMLR"
}
p.Sources = append(p.Sources, source)
// 按来源记录顺序采用第一个非空元数据;坏 JSON 不阻止来源链接展示。
var fields map[string]json.RawMessage
if json.Unmarshal([]byte(metadata), &fields) == nil {
for key, target := range map[string]**string{"doi": &p.DOI, "journal-ref": &p.Journal, "comments": &p.Comments} {
@@ -501,6 +524,7 @@ func (r *PostgresRepository) enrich(ctx context.Context, tx *sql.Tx, papers []Pa
if err != nil {
return err
}
// 每条投稿通过 LATERAL 选择最新观察到的决策;没有决策时仍保留投稿并标为 unknown。
rows, err = tx.QueryContext(ctx, r.query(`SELECT s.paper_id,v.acronym,e.year,e.track,coalesce(d.status,'unknown'),coalesce(d.evidence_url,'')
FROM {schema}submissions s JOIN {schema}editions e ON e.id=s.edition_id JOIN {schema}venues v ON v.id=e.venue_id
LEFT JOIN LATERAL (SELECT status,evidence_url FROM {schema}decisions WHERE submission_id=s.id