client

package
v1.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package client 是 Nazhi-cli SDK 的根包。

每个 Client 实例拥有独立的 HTTP cookie jar,天然并发安全。 所有方法都需要 context.Context,支持超时与取消。

error_category.go 实现错误分类(包级文档见 client.go)。

errors.go 定义 SDK 哨兵错误集(包级文档见 client.go)。

honor.go 荣誉申报 SDK。 端点映射:

GET  /api/studentMoralEduNew/getHonorType          — 获取所有荣誉类型(dataList / returnData 双通道)
GET  /api/studentMoralEduNew/getHonorTypeForSelect  — 获取级别下拉选项(returnData);荣誉类型选项在 dataList
GET  /api/studentMoralEduNew/getHonorLevel          — 获取荣誉级别(dataList,需 honorTypeId 参数)
GET  /api/studentMoralEduNew/getHonorByStudentId    — 查询已有荣誉(分页,需 &key=)
POST /api/studentMoralEduNew/addHonor               — 申报荣誉
POST /api/studentMoralEduNew/updateHonor            — 更新荣誉(未审核记录)
GET  /api/studentMoralEduNew/deleteHonorById        — 删除荣誉

pagination_bounds.go:写实分页安全——页数推导纯函数与四道闸上限常量。

页数推导提取动因(2026-09-26 架构核实):下界推导在 submitted.go 与 raw_json.go 三处逐字重复(各 4 行),limit 路径的 endPage 收敛又各写一遍。 四道闸常量集中动因(2026-09-27):此前散落 raw_json.go(页数/字节/维度) 与 submitted.go 内联(条数),新取数路径要考古四处才能装配。

抽出为纯函数/常量的原因:这些规则是分页安全的不变量(v1.6.4 / 84982af 确立),必须只有一处定义,且可被行为矩阵独立验证——它们不依赖 Client 状态、不发请求,纯 CPU 计算。

注意:这些函数只决定「要抓几页」,不得改写返回给调用方的 PageBean。 服务端声明的 totalPage/totalNum 必须原样透传(raw_json_limit_pages_test.go 锁定该契约),推导值仅用于内部翻页决策。

Index

Constants

View Source
const MaxAttachmentSize = 20 * 1024 * 1024

MaxAttachmentSize 是非图片附件直传的上限(20MB,SDK 有意放宽:前端镜像文案 20MB, 服务端实测无 2MB 硬限、真实上限约 46.86MiB,见 CLAUDE.md「G. 文件上传/下载」节)。 图片走压缩路径,上限为 MaxImageSize(5MB,SDK 放宽);两者分开校验。

View Source
const MaxImageSize = 5 * 1024 * 1024

MaxImageSize 默认压缩目标上限(5MB)。

View Source
const MinImageDimension = 10

MinImageDimension 缩放下限(像素),低于此值停止缩放。

Variables

View Source
var (
	// ErrLoginRejected 登录被拒绝(凭证无效)。
	ErrLoginRejected = errors.New("login rejected: invalid credentials")

	// ErrCookieSyncFailed 登录成功但 token 同步到 cookie jar 失败()。
	//
	// 触发场景:Login 使用 HTTP client 的 Jar 不是 *cookiejar.Jar(如调用方
	// WithHTTPClient(customClient{Jar:nil}))——Login 返回的 token 无法被后续
	// 业务请求携带,所有 dataList 接口会静默返回空。此前只 warn(调用方拿到
	// token+nil 完全感知不到),现在返回错误让调用方立即感知并修复客户端配置。
	ErrCookieSyncFailed = errors.New("login succeeded but cookie sync failed")

	// ErrNetwork 网络错误(连接超时、DNS 解析失败等)。
	ErrNetwork = errors.New("network error")

	// ErrUploadRejected 文件上传被服务器拒绝。
	ErrUploadRejected = errors.New("upload rejected by server")

	// ErrFileTooLarge 文件超出允许大小。
	ErrFileTooLarge = errors.New("file exceeds max size")

	// ErrInvalidPayload 任务请求体格式错误。
	ErrInvalidPayload = errors.New("invalid task payload")

	// ErrBusinessRejected 业务请求被服务端拒绝(非登录场景)。
	//
	// 与 ErrLoginRejected 的语义边界:
	//   - ErrLoginRejected:登录请求被拒绝(凭证无效),
	//     SDK 用户应触发重新登录流程
	//   - ErrBusinessRejected:已通过鉴权的业务请求被服务端拒绝
	//     (如任务已提交、参数错误),与登录状态无关,
	//     SDK 用户应只展示服务端 msg 或重试,不必重新登录
	//
	// SubmitTask 等业务方法应使用本哨兵而非 ErrLoginRejected,
	// 否则 SDK 用户按 errors.Is(err, ErrLoginRejected) 判定后会错误地走重新登录。
	ErrBusinessRejected = errors.New("business request rejected by server")

	// ErrSessionBackoff session 激活在 backoff 窗口内被抑制(thundering herd 防护)。
	//
	// 与 ErrNetwork / ErrBusinessRejected 的语义边界:
	//   - ErrSessionBackoff:上次激活失败后短时间内再次调用,
	//     SDK 用户应等待 backoff 窗口结束或换 token 后重试
	//   - ErrNetwork / ErrBusinessRejected:实际尝试过后的真实错误
	//
	// backoff 命中时返回本哨兵(包装上一个错误),
	// 而非直接返回 sm.lastErr。这样 SDK 用户能通过 errors.Is 识别
	// 「这是被抑制的 stale 错误」并做出有意义的重试决策。
	ErrSessionBackoff = errors.New("session activation backoff: in cooldown window")

	// ErrEmptyUserInfo 业务无用户数据(getMyInfo 成功但 returnData + dataMap 都为 nil)。
	//
	// 与 ErrBusinessRejected 的语义边界:
	//   - ErrEmptyUserInfo:服务端成功响应(HTTP 200 + code=1)但确实没有用户数据
	//     (不是错误,只是空集)。SDK 用户的最佳实践是按 status envelope 渲染。
	//   - ErrBusinessRejected:服务端主动拒绝(HTTP 200 + code=0,或业务校验失败)
	//
	// getMyInfoRaw 在全 nil fallback 时返回本哨兵,
	// 而非返回 (nil, nil) 让 cmd 层「裸 null」输出。cmd 层用 errors.Is 分支
	// 输出对称的 {status: empty, reason: ...} envelope,与 whoami 契约一致。
	ErrEmptyUserInfo = errors.New("getMyInfo returned no user data")

	// ErrRateLimited 服务端限流响应(HTTP 429)。
	//
	// 触发场景:目标平台返回 429 Too Many Requests。
	// 与 ErrNetwork / ErrBusinessRejected 的语义边界:
	//   - ErrRateLimited:服务端主动节流,SDK 用户应退避后重试
	//     (可用 Retry-After 头判断等待时间)
	//   - ErrBusinessRejected:业务校验失败(HTTP 200 + code=0 或 业务 4xx)
	//   - ErrNetwork:网络层失败(连接拒绝/超时等),与服务端策略无关
	//
	// classifyHTTPStatus 的各调用方(request.go httpDo/doBizGet、session.go doGetMenu、
	// file.go 上传/下载)在收到 429 时包装本哨兵,
	// SDK 用户通过 errors.Is(err, ErrRateLimited) 精确识别限流场景,
	// 触发退避策略而非立即报错或重连。
	ErrRateLimited = errors.New("rate limited: HTTP 429 too many requests")

	// ErrServiceUnavailable 服务端不可用(HTTP 5xx)。
	//
	// 触发场景:目标平台返回 5xx(502/503/504 等)。
	// 与 ErrNetwork / ErrRateLimited 的语义边界:
	//   - ErrServiceUnavailable:服务端主动拒绝或临时过载,
	//     SDK 用户应等待重试(指数退避)
	//   - ErrNetwork:客户端网络层失败(连不上服务端)
	//   - ErrRateLimited:限流(429),属于可预期的服务端策略
	//
	// classifyHTTPStatus 的各调用方(request.go httpDo/doBizGet、session.go doGetMenu、
	// file.go 上传/下载)在收到 5xx 时包装本哨兵。
	ErrServiceUnavailable = errors.New("service unavailable: HTTP 5xx")

	// ErrTimeout 请求超时。
	//
	// 触发场景:上下文 deadline 触发 / net/http 内部超时。
	// 与 ErrNetwork 的语义边界:
	//   - ErrTimeout:超时(带 deadline 信息),SDK 用户可按 deadline 调整
	//   - ErrNetwork:网络层失败(连接拒绝 / DNS 失败 / TLS 失败)
	//
	// 主要用途:让 SDK 用户能 errors.Is 区分「超时」与「连不上」,
	// 决定是否调大 timeout 或换网络。
	//
	ErrTimeout = errors.New("timeout: request exceeded deadline")

	// ErrInvalidResponse 服务端响应不可用或不可信——重试通常无意义。
	//
	// 触发场景比「状态码非 200」宽得多,**不要按状态码理解本哨兵**:
	//   - HTTP 协议层错误:4xx(429 除外)与 noRedirect 下的 3xx
	//   - 2xx 但响应体不是预期结构:非 JSON(nginx 维护页 / WAF 挑战页)、
	//     dataList 不是合法 JSON 数组、响应体超出限读上限
	//   - 客户端配置类永久错误:下载重定向越界或跨域、0 字节响应、附件超限
	//
	// 与相邻哨兵的语义边界:
	//   - ErrInvalidResponse:响应本身不可用(重试无意义)
	//   - ErrBusinessRejected:响应可用但业务拒绝(HTTP 200 + code=0)
	//   - ErrRateLimited:HTTP 429 限流,应退避后重试
	//   - ErrNetwork / ErrServiceUnavailable:传输或服务端临时故障,可退避重放
	//
	// 归 422 / 退出码 1(见 cmd/nazhi 的 mapSentinelToHTTPCode):与
	// ErrBusinessRejected 同档,含义是「别重试,去看服务端/改配置」。
	ErrInvalidResponse = errors.New("invalid response: unusable or untrusted server response")

	// ErrAllDecodersFailed 表示 doBizGetDecode 的所有解码器均未命中(业务成功但空数据)。
	//
	// 触发场景:服务端 code=1 但 returnData/dataMap/dataList 全为空或归一化为 nil。
	// QuerySelfEvaluation 在此场景下将本哨兵归一为 (nil,nil) 空成功,而非错误。
	// SDK 外部可通过 errors.Is(err, ErrAllDecodersFailed) 精确识别“空成功”链路,
	// 避免依赖错误字符串匹配(旧实现曾用 strings.Contains("所有解码器均失败"),脆弱)。
	ErrAllDecodersFailed = errors.New("all decoders failed: no decoder produced a value")

	// ErrRetryable 表示「context 取消导致的失败,可重试」。
	//
	// 触发场景:FetchTasks 中部分维度因 ctx cancel 而失败(cancelledCount > 0),
	// task.go 用 cancelPlaceholder = fmt.Errorf("%w: ...", ErrRetryable, ...) 包装,
	// SDK 用户可通过 errors.Is(err, ErrRetryable) 区分「ctx cancel 应重试」
	// 与「业务错误不应重试」。
	//
	// 与 ErrBusinessRejected 的语义边界:
	//   - ErrRetryable:ctx cancel 引发的「可重试」语义标记
	//   - ErrBusinessRejected:服务端业务拒绝(code=0),不应盲目重试
	//
	// 以 %w 包装语义标记(本哨兵),支持 errors.Is 识别取消场景。
	ErrRetryable = errors.New("retryable: context cancelled")
)
View Source
var ErrImageTooLarge = errors.New("image exceeds maximum size after compression")

ErrImageTooLarge 压缩后仍超过 MaxImageSize。

View Source
var ErrUnsupportedFormat = errors.New("unsupported image format")

ErrUnsupportedFormat 不支持的图片格式。

View Source
var WithBaseURL = withURLGuard("WithBaseURL", func(c *Client, v string) { c.baseURL = v })

WithBaseURL 设置业务 API 根地址。

View Source
var WithHTTPClient = withNilGuard[*http.Client]("WithHTTPClient", func(c *Client, hc *http.Client) {
	prevTimeout := time.Duration(0)
	if c.http != nil {
		prevTimeout = c.http.Timeout
	}
	c.http = hc
	if hc.Timeout == 0 && prevTimeout > 0 {
		hc.Timeout = prevTimeout
	}
})

WithHTTPClient 设置自定义 HTTP 客户端(完全替换默认客户端)。 注意:替换后 cookie jar 由调用者负责。

行为约定:

  • hc == nil:拒绝设置并 warn,保持当前 c.http(防止 nil 静默覆盖 默认带 cookie jar 的客户端,导致后续请求 0 cookie → 空 dataList)
  • 否则:完全替换 c.http;若新客户端 Timeout 为零且此前已通过 WithTimeout 设置过超时,则继承该超时——消除 Option 声明顺序敏感性, WithTimeout(15s) 与 WithHTTPClient(custom) 先后不再影响最终生效值
View Source
var WithLogger = withNilGuard[*slog.Logger]("WithLogger", func(c *Client, l *slog.Logger) { c.logger = l })

WithLogger 设置自定义 logger。

行为约定:

  • l == nil:拒绝设置并 warn,保持当前 logger(防止 nil 覆盖后 后续 c.logger.Warn/Debug/Error 全部 nil pointer panic)
  • 否则:替换 logger
View Source
var WithSSOBase = withURLGuard("WithSSOBase", func(c *Client, v string) { c.ssoBaseURL = v })

WithSSOBase 设置 SSO 根地址(用于 login 流程)。 默认值由 defaultSSOBase 常量提供(见 request.go defaultSSOBase)。

View Source
var WithSessionBackoff = withDurationGuard("WithSessionBackoff",
	func(c *Client, d time.Duration) { c.sm.SetBackoff(d) },
)

WithSessionBackoff 设置 session 激活失败后抑制重试的时间窗口。

默认值:5 秒(见 defaultSessionBackoff 常量)。SDK 用户调高/调低本字段 可针对不同服务端稳定性做适配:

  • 高频调用场景:调小到 1s 让失败快速重试
  • 服务端降级场景:调大到 30s 让瞬时故障不被重复激活放大

行为约定:

  • d > 0:设置 c.sm.backoff
  • d = 0:拒绝并 warn,保持当前值(防止静默清零已有配置)
  • d < 0:拒绝并 warn,保持当前值(负数 time.Duration 无意义)

设计一致:与 WithTimeout 的「d<=0 拒绝 + warn」守卫对称。

与 ErrSessionBackoff 哨兵配对, 让 SDK 用户能调整 thundering herd 抑制窗口。

View Source
var WithToken = withStringGuard("WithToken", func(c *Client, v string) { c.pendingToken = v })

WithToken 预置 X-Auth-Token(同时写入 Header 和 Cookie)。

用于不经过 Login() 流程、直接从外部传入 token 的场景:

  • CLI 命令的 --token 标志
  • 从文件/CI secret 读取的存量 token

业务服务器要求 X-Auth-Token 同时存在于 Header 和 Cookie, 仅设置 Header 会导致后续接口返回空数据。

行为约定:

  • token 空字符串或纯空白:拒绝设置并 warn(同 withStringGuard 约束)
  • 否则:存到 c.pendingToken,延迟到 New() 末尾统一 syncCookieToken

注意:实际 cookie 注入延迟到 New() 末尾执行,确保 WithSSOBase / WithBaseURL / WithHTTPClient 在 WithToken 之后调用也能正确生效(避免 Option 顺序敏感性 bug)。

View Source
var WithUploadURL = withURLGuard("WithUploadURL", func(c *Client, v string) { c.uploadURL = v })

WithUploadURL 设置文件上传服务器地址。

Functions

func NormalizeDate added in v1.12.0

func NormalizeDate(input string) string

NormalizeDate 对各种常见日期输入格式进行智能规范化,统一转换为 "YYYY-MM-DD" 格式。 支持格式:

  • "2026-05-20"
  • "2026/05/20"
  • "2026.05.20"
  • "20260520"
  • "2026-5-2"、"2026/5/2"
  • 带时间的格式,如 "2026-05-20 14:30:00"(截取年月日)

若输入为空或无法识别,安全返回原字符串,不发生 panic。

func NormalizeHonorGetDate added in v1.12.0

func NormalizeHonorGetDate(s string) string

normalizeHonorGetDate 对荣誉日期进行智能变通自愈。 官方后端 DateUtil.transferDateFormat (DateUtil.java:20-36) 硬编码使用 yyyy-MM-dd'T'HH:mm:ss.SSS Z 解析;若客户端仅传入普通 yyyy-MM-dd,官方 SimpleDateFormat 会抛 ParseException 导致 getDate 被静默置为 null 丢失。 本函数自动将 YYYY-MM-DD / YYYY/MM/DD / YYYY.MM.DD 规范化为官方期待的 ISO UTC 格式, 已含 T 的 ISO 格式则原样透传,彻底杜绝官方平台丢空日期。 NormalizeHonorGetDate 对荣誉日期进行智能变通自愈。 官方后端 DateUtil.transferDateFormat (DateUtil.java:20-36) 硬编码使用 yyyy-MM-dd'T'HH:mm:ss.SSS Z 解析;若客户端仅传入普通 yyyy-MM-dd,官方 SimpleDateFormat 会抛 ParseException 导致 getDate 被静默置为 null 丢失。 本函数自动将 YYYY-MM-DD / YYYY/MM/DD / YYYY.MM.DD 规范化为官方期待的 ISO UTC 格式, 已含 T 的 ISO 格式则原样透传,彻底杜绝官方平台丢空日期。

func ParseStudentComment

func ParseStudentComment(comment string) (map[string]any, error)

ParseStudentComment 解析结构化自评的二次 JSON。

对应前端 selfgaintloss.vue:querySelfEvaluation 返回的 dataMap.student_comment 本身是 JSON.stringify(form) 的字符串,需二次 JSON.parse 才能得到表单对象。 普通文本自评(mainLeft.vue)直接为字符串,无需二次解析。

入参 comment 为 QuerySelfEvaluation 返回的 SelfEvalStatus.StudentComment。 返回:

  • 若 comment 为空或非 JSON 对象字符串,返回 (nil, nil) 或原错误;
  • 若为结构化 JSON 字符串,返回解析后的 map。

调用方可通过返回值 nil 判断为普通文本自评。

Types

type CircleListType

type CircleListType int

CircleListType 是写实列表类型:查询写实列表时的入口分类。

命名对应 CONTEXT.md「状态与列表」中的「写实列表类型」——它描述「从哪个 列表看」,与单条写实自身的状态(CircleRecord.Status:0 已发布 / 1 已锁定 / 2 被撤回)无关,也与记录自身的 type 字段(判是否学生本人发布)无关。 这三者极易混读,改动前请先读 CONTEXT.md「一处已订正的冲突」。

四个常量的整数值是 getStudentCircle 查询参数 type 的线协议约定, 改动会破坏与平台的兼容,勿动。

const (
	// CircleListPublic 公示:教师代写的全部写实记录(1 公示 / 2 教师写实
	// / 3 我发布的 / 4 被撤回的 中的第 1 类)。
	CircleListPublic CircleListType = 1
	// CircleListTeacher 教师写实:教师代写的全部写实记录。
	CircleListTeacher CircleListType = 2
	// CircleListSubmitted 我发布的:写实状态为零且由当前学生发布的记录。
	// 与「已提交(任务维度)」不是同一概念——后者说的是「这个任务交没交」。
	CircleListSubmitted CircleListType = 3
	// CircleListWithdrawn 被撤回的:写实状态为二并附撤回原因的记录。
	CircleListWithdrawn CircleListType = 4
)

func CircleListTypeFromValue

func CircleListTypeFromValue(v int) (CircleListType, bool)

CircleListTypeFromValue 从平台的 type 参数值反查写实列表类型。 用于把 CLI 的 --type 输入与 SDK 共享同一份映射,避免两侧各写一张表。

func (CircleListType) Label

func (t CircleListType) Label() string

Label 返回写实列表类型的中文领域名。未知类型返回空串,调用方应先经 Valid 判定。

与 CLI 的措辞差异是有意的:CLI 的 circleListMode.label 用「教师」而非 「教师写实」,那处注释写明 label 是领域名词、用于简短的用户提示与错误文案。 本函数给的是词汇表里的正式术语,供需要精确表述的调用方使用。

func (CircleListType) Valid

func (t CircleListType) Valid() bool

Valid 报告该类型是否为平台承认的四种之一。

判定在发请求之前:查询参数 type 直接驱动服务端的列表过滤,传错值不会 报错,只会静默返回另一个列表的数据——这正是「写实列表类型」被反复 误读的根源,具名类型加前置校验是让它不再依赖注释提醒的根本手段。

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 是目标平台 API 的完整 Go SDK。 每个实例拥有独立的 cookie jar,天然并发安全。

func Connect added in v1.12.0

func Connect(ctx context.Context, username, password string, opts ...Option) (*Client, *types.LoginResponse, error)

Connect 是一站式优雅直通连接函数: 自动完成 Client 初始化、学校 ID 解析(未传 WithSchoolID 时自动通过 GetSchoolID 平台查校)、 账号密码登录 (Login) 与 Session 预热激活 (ActivateSession)。 返回完全就绪且注入了 Token 的 *Client 实例以及登录响应数据。

使用示例:

c, resp, err := client.Connect(ctx, "20240101", "password123",
    client.WithBaseURL("https://www.nazhisoft.com"),
)

func ConnectEnv added in v1.12.0

func ConnectEnv(ctx context.Context, extraOpts ...Option) (*Client, *types.LoginResponse, error)

ConnectEnv 自动从环境变量中读取配置并执行一键连接。 支持的环境变量:

  • NAZHI_USERNAME: 学生账号
  • NAZHI_PASSWORD: 学生密码
  • NAZHI_SCHOOL_ID: 学校 ID(可选)
  • NAZHI_BASE_URL: 业务 API 地址(可选)
  • NAZHI_SSO_BASE / NAZHI_SSO_URL: SSO 地址(可选)

func ConnectURL added in v1.12.0

func ConnectURL(ctx context.Context, connURL string, extraOpts ...Option) (*Client, *types.LoginResponse, error)

ConnectURL 通过连接字符串进行一站式连接。

连接串语法示例:

"username:password@https://www.nazhisoft.com?school=9999"
"username:password@127.0.0.1:8280"

func New

func New(opts ...Option) (*Client, error)

New 创建 Client。使用 Option 模式配置:

client := nazhicli.New(
    nazhicli.WithSSOBase("https://www.nazhisoft.com"),
    nazhicli.WithTimeout(15*time.Second),
)

登录走五育活动端免验证码接口(/uiActivityLogin/studentLogin), 密码本地 MD5 计算,无需验证码识别器。

Option 处理顺序:所有 Options 跑完后,若有 WithToken 注入,则在最终 c.http.Jar / c.ssoBaseURL / c.baseURL 已知的前提下统一 syncCookieToken(避免顺序敏感性 bug)。

返回 error:当 WithHTTPClient 自定义 Jar + WithToken 时,Jar 必须支持 cookie 写入。 若 Jar 不是 *cookiejar.Jar,syncCookieToken 会返回 error 让调用方立即感知 (避免业务接口返回空 dataList 但根因在 build client 阶段 静默 Warn,跨多步调用难关联)。

func (*Client) ActivateSession

func (c *Client) ActivateSession(ctx context.Context, token string) (*types.UserInfo, error)

ActivateSession 初始化目标平台业务 Session。 按真实抓包验证:必须按以下 4 步顺序激活,否则后续接口返回空数据:

  1. GET /(首页)
  2. GET /api/studentInfo/getMenu(Referer: /homepage?token=xxx)
  3. GET /api/studentInfo/getMenu(Referer: /home)
  4. GET /api/studentInfo/getMyInfo(获取完整个人资料,含 seat/号数)

返回用户基本信息(含座号)。4 步任一失败立即 propagate error: 步骤 4(getMyInfo)是 4 步契约的一部分,失败直接上抛,不做兜底降级。

内部实现:委托给 sm.Activate,由 sessionManager 负责持锁 fast path、 backoff 检查、持锁 4 步激活和状态记录。学校信息 SSO 回退补全 (postProcessSchoolFallback)在 sm.mu 解锁后执行——P1-B:网络往返 禁止进入临界区,否则最坏把锁窗口放大到 c.http.Timeout 秒级。

外部并发契约:

  • 本函数委托给 sm.Activate,后者在 sm.mu 持锁状态下执行 4 步网络请求 (正常数百毫秒量级),持有锁期间不会回调外层或锁住其他互斥资源; 锁内无任何计划外网络往返(学校回退已移至锁外)。
  • 外部调用方应**避免**在本函数持锁路径内嵌套其他锁, 否则可能引发 ABBA 死锁(如 errgroup.Go 中先持锁 A 再调本函数, 本函数持 sm.mu 时反调锁 A)。
  • 外部使用模式:直接 goroutine 并发调本函数是安全的——sm.mu 只会序列化 4 步激活,不会让其他 goroutine 饿死(窗口为 4 步请求耗时, 受 c.http.Timeout 封顶;锁内不含 SSO 学校回退)。
  • 如果需要在锁内调本函数(如 sync.Mutex 临界区),需确保外层锁 的获取/释放顺序一致,不会形成循环等待。

并发安全:本方法委托给 sm.Activate(持锁 fast path),同 token 二次调用 直接命中缓存不重复执行 4 步。

Backoff 缓存:失败时通过 sm.RecordFailure 更新 lastErr / lastAttempt / lastFailedToken。CLI 路径(直接调 ActivateSession)与业务方法路径 (通过 ActivateSession 间接调)共享同一份 backoff 缓存, 同 token 在窗口内的重复调用会被抑制。

func (*Client) ActivateSessionJSON

func (c *Client) ActivateSessionJSON(ctx context.Context, token string) (json.RawMessage, error)

ActivateSessionJSON 激活业务 session,返回 /api/studentInfo/getMyInfo 的 JSON(经 SDK 后处理)。

经 sessionManager 激活(含 4 步 HAR 请求),Marshal 其返回的后处理 UserInfo 为 JSON。 包含学校信息 SSO 降级补全、班级名年级前缀清理等后处理。 同时附带 4 步 HAR 激活所需的 HTTP 请求(首页 → getMenu ×2 → getMyInfo), 即使下游不消费返回的 UserInfo 也必须执行完这 4 步。

返回值:

  • json.RawMessage:处理后的 UserInfo JSON 字节;数据为空时返回 nil。
  • error:网络/解析/业务错误(含 ErrEmptyUserInfo / ErrSessionBackoff)

func (*Client) AddCircleComment

func (c *Client) AddCircleComment(ctx context.Context, token string, circleID int64, content string) (*types.Comment, error)

AddCircleComment 给写实记录添加评论。 POST /api/studentCircleNew/addCircleComment 请求体: {"circleId": circleID, "content": content}

前端在评论成功后执行 `commentList.unshift(response.data.returnData)`, 服务端 returnData 即新创建的 Comment 对象。为保留该语义,SDK 解析 returnData 并返回;调用方可直接 unshift 到本地列表而无需重新查询。 解析失败时返回 (nil, err);code=1 而 returnData 缺失/null 时返回 (nil, nil), 调用方需自判 nil——与前端「拿到什么 unshift 什么」的宽容消费行为一致。

func (*Client) AddHonor

func (c *Client) AddHonor(ctx context.Context, token string, payload types.AddHonorPayload) error

AddHonor 申报一条荣誉。

用户输入:TypeID、Level、EvaluationAgency、GetDate、证书图(可选)。 SDK 自动:

  • TypeName 空且 TypeID>0 → GetHonorTypeOptions 反查
  • Name 空 → 回落 TypeName(前端不传 name)
  • GetDate 智能变通对齐官方 DateUtil.transferDateFormat ISO 规范
  • Score 始终随请求体发出(json:"score" 无 omitempty;默认 0 对齐前端 form)

func (*Client) AddTypicalCase

func (c *Client) AddTypicalCase(ctx context.Context, token string, payload types.AddTypicalCasePayload) error

AddTypicalCase 提交一条典型案例。

用户只需填标题/类别代码/角色代码/级别代码/指导教师等; TypeName/RoleName/LevelName 为空时按前端下拉自动补全。 遵循 AddHonor 模式:doBizVoid POST → 成功返回 nil。

func (*Client) ChangePassword added in v1.12.0

func (c *Client) ChangePassword(ctx context.Context, token string, newPassword string) error

ChangePassword 通过个人信息修改通道重置学生登录密码。

官方前端 modifyBox.vue 通过将新密码存入 studentUuid 字段发送给 /api/studentInfo/updateMyInfo,后端检测到 studentUuid 非空时联动修改学生密码。

func (*Client) ClearSchoolCache added in v1.12.0

func (c *Client) ClearSchoolCache()

ClearSchoolCache 清空客户端的学校信息缓存。

func (*Client) Close

func (c *Client) Close() error

Close 释放 Client 持有的资源:

  • HTTP Transport 的空闲 keep-alive 连接
  • sessionManager backoff 状态

两个动作都不会失败,故恒返回 nil。签名保留 error 是因为调用方 (cmd/nazhi 的 closeInLIFO)按「可能失败」聚合而设计,公开 SDK 不宜因 实现细节变更签名。v1.7.0 移除验证码识别器时这里曾有第三个动作 (c.ocr.Close)并把错误 append 进 errs,那次移除带走了唯一的 append 点 却留下 errs 与 errors.Join 分支——两者此后恒为死路径,本次一并清除。

func (*Client) DeleteBatchTypicalCase

func (c *Client) DeleteBatchTypicalCase(ctx context.Context, token string, ids []int64) error

DeleteBatchTypicalCase 批量删除典型案例。 POST /api/studentCircleNew/deleteBatchTypicalCase

请求体是纯 JSON 数组 [1, 2, 3](前端源码确认)。 空/nil 切片返回 ErrInvalidPayload 而非发出字面 null 请求体 (对齐前端 classiccanter.vue 的空数组守卫与 CLI 层参数校验口径)。

func (*Client) DeleteCircle

func (c *Client) DeleteCircle(ctx context.Context, token string, circleID int64) error

DeleteCircle 删除一条写实记录。 GET /api/studentCircleNew/deleteCircle?id=

circleID 为平台 Integer(官方 CircleController.java:132-134 @RequestParam("id")Integer id),本地前置校验与 CLI 同判据。

func (*Client) DeleteHonor

func (c *Client) DeleteHonor(ctx context.Context, token string, honorID int64) error

DeleteHonor 删除一条荣誉记录。

真实抓包确认:接口为 GET 请求,ID 通过查询参数传递。 id 为平台 Integer(官方 StudentMoralEduController.java:66-68),本地前置校验。

func (*Client) DeleteTypicalCase

func (c *Client) DeleteTypicalCase(ctx context.Context, token string, id int64) error

DeleteTypicalCase 删除一条典型案例。 GET /api/studentCircleNew/deleteTypicalCase?id=

id 为平台 Integer(官方 CircleController.java:297-299),本地前置校验。

func (*Client) DownloadFile

func (c *Client) DownloadFile(ctx context.Context, attachmentID int64, dst string) error

DownloadFile 按附件 ID 从公开文件服务器下载图片到本地 dst。

流程:

  1. GET {ssoBaseURL}/common/attachment/getImg?id={attachmentID}
  2. 服务端 302 重定向到 doc.nazhisoft.com/other/M00/...(FastDFS 真实存储)
  3. 跟随重定向(最多 maxDownloadRedirects 次)→ 取真实图片
  4. 写入本地 dst

安全约束(与 UploadFile 对称):

  • 不发送任何 Token / Cookie / Authorization 头(公开服务)
  • 重定向仅跟随到 nazhisoft.com / doc.nazhisoft.com 同主机域, 防止恶意 Location 跳转到第三方主机
  • 重定向次数上限 5,防止恶意循环

错误契约:

  • HTTP 429 → ErrRateLimited;5xx → ErrServiceUnavailable; 其余非 2xx(403/404 等服务端明确拒绝)→ ErrInvalidResponse (与 request.go httpDo/doBizGet、session.go doGetMenu 同口径;4xx 不是网络故障, 归 ErrNetwork 会让脚本按可重试语义对永久失败无限重试)
  • 写入失败 → fmt.Errorf("写入文件失败: %w", err)
  • 重定向超过上限/跨域重定向 → fmt.Errorf("%w: ...", ErrInvalidResponse, ...) (重定向违规是永久性配置错误,重试不会自愈,归 ErrInvalidResponse 而非 ErrNetwork)

func (*Client) EditCircle

func (c *Client) EditCircle(ctx context.Context, token string, input types.TaskEditInput) (*types.TaskResult, error)

EditCircle 修改一条已提交的写实记录。

与 SubmitTask 对称:内部自动完成 getCircleTypeByTaskId → 图片上传 → 组装 editCircle payload。 区别:

  • SubmitTask 调用 addCircle(无 id 字段,新增记录)
  • EditCircle 调用 editCircle(必须传 id 字段,修改已有记录)

用户字段(address/level/playRole 等活动字段)空串原样发送,不发明学校名或等级 5; 任务元数据与图片由 SDK 自动补齐。

编辑模式特别提示(见 CLAUDE.md「C. 写实提交/编辑/预览」编辑回填节):前端 openEdit→getCircleTypeByTaskId 把列表记录的 26 个活动字段(name/hostName/circleDate/rank/level/circleBeginDate/ circleEndDate/checkResult/patentType/patentNum/address/termName/各类型专属字段/ playRole/likeSpecialty1-3 等)整体回填,JSON.stringify 后整包提交。SDK 编辑路径 若只填 {id,taskId,content},则上述字段全部以空串上线——CLI 官方示例正是如此引导。 要保留原记录任何字段的值,调用方应从 CircleRecord 对应字段显式赋值给 input, 否则与原记录不同的字段会被空串静默改写(服务端对空串是否覆盖未抓包证实,挂账)。

hours 例外——编辑留空时回填任务元数据预设(getCircleTypeByTaskId.hours), 而前端编辑是用列表记录值覆盖任务预设。要保留原记录值,请从列表记录 (CircleRecord 的 hours)显式赋值给 input.Hours,否则与预设不同的记录会被静默改写。 注意:任务预设 hours<=0 且 targetType∈{1,6,10} 时,Hours 留空不会 回填而是直接拒绝(ErrInvalidPayload,parseHours)——此时必须从列表记录显式回填 Hours。 playRole/level 恒以字符串发送;前端编辑回填列表记录时为 number(HAR 实证 editCircle body playRole:3/level:5),服务端对两形态均已接受。

图片同理——不传 ImageIDs 时 wire 上发送 pictureList:[],而前端编辑恒把原记录 图片回填进 pictureList(openEdit→imgList)。若服务端以空数组覆盖原附件则编辑会 静默丢图;要保留原图,请从 CircleRecord.ImgList 的 attachment_id 回填 input.ImageIDs。 服务端对空数组的真实语义未抓包证实(挂账)。

func (*Client) Enabled

func (c *Client) Enabled(ctx context.Context, lvl slog.Level) bool

Enabled 暴露 logger 的级别判定,供跨包黑盒测试校验(不影响生产行为)。

委托给私有 logEnabled 而非自行实现:两者本是同一份知识,写两遍必然漂移 ——原实现漏掉 logEnabled 的 nil ctx 归一分支,使 ctx 为 nil 时 「级别守卫通过」与「实际会输出」不等价。现由 logEnabled 单点持有该判定。

func (*Client) EnsureValidSession added in v1.12.0

func (c *Client) EnsureValidSession(ctx context.Context, minRemaining time.Duration) error

EnsureValidSession 确保当前拥有有效的会话。 若无 Token、Token 即将过期(剩余有效期小于 minRemaining)或无效, 且已配置了账号密码凭证,将自动触发无感重新登录并激活会话。

func (*Client) FetchTasks

func (c *Client) FetchTasks(ctx context.Context, token string) ([]types.Task, error)

FetchTasks 拉取目标平台全部维度的任务列表。 内部流程:ActivateSession → getDimensions → 遍历维度 getCircleStatistics → 聚合。

并发拉取:多个维度的 getCircleStatistics 通过 errgroup 并发执行, 并发上限 = min(len(dimensions), fetchTasksConcurrentLimit)。 既享受并发提速(20 维度 ≈ 3 RTT vs 串行 20 RTT), 又防止 > 50 维度的业务接口把服务端打爆(无限制 goroutine fan-out 风险)。

单个维度失败时通过 c.logDebug() 记录(不会中断整体拉取), 调用方可通过 client.WithLogger() 注入自定义 logger 捕获详细错误。

func (*Client) FetchTasksJSON

func (c *Client) FetchTasksJSON(ctx context.Context, token string) (json.RawMessage, error)

FetchTasksJSON 拉取全维度任务列表,返回平台原始 JSON 数组(跨维度合并)。

自动跨维度并发拉取并在 SDK 内部合并为单一 JSON 数组,保留所有平台字段。 错误聚合与 FetchTasks 对齐:

  • context 取消且无 partial → ErrRetryable
  • context 取消且有 partial → ErrBusinessRejected + ErrRetryable + 已合并字节
  • 业务错误 → 仍返回已合并的字节 + ErrBusinessRejected(cmd 层 partial envelope)

func (*Client) FindTaskByName added in v1.12.0

func (c *Client) FindTaskByName(ctx context.Context, token, taskName string) (*types.Task, error)

FindTaskByName 根据任务名称精确查找任务定义。 若 token 为空,自动使用客户端当前活跃的 Token。若未找到返回 nil, nil。

func (*Client) FindTasksByKeyword added in v1.12.0

func (c *Client) FindTasksByKeyword(ctx context.Context, token, keyword string) ([]types.Task, error)

FindTasksByKeyword 根据关键字模糊查找匹配的任务列表。 若 token 为空,自动使用客户端当前活跃的 Token。

func (*Client) GetCircleImages

func (c *Client) GetCircleImages(ctx context.Context, token string, pageNo, pageSize int) ([]map[string]any, error)

GetCircleImages 获取当前用户上传的写实图片列表。 GET /api/studentCircleNew/getCircleImg?pageNo=&pageSize=

pageNo/pageSize 为平台 Integer(官方 CircleController.java:43-45), 非正数本地前置拦截,归 ErrInvalidPayload。

func (*Client) GetCircleStatistics added in v1.12.0

func (c *Client) GetCircleStatistics(ctx context.Context, token string, dimensionID *int64) ([]map[string]any, error)

GetCircleStatistics 获取维度下的写实统计数据。

对应 GET /api/studentCircleNew/getCircleStatistics?dimensionId=

func (*Client) GetCircleStatisticsByTypeId added in v1.12.0

func (c *Client) GetCircleStatisticsByTypeId(ctx context.Context, token string, dimensionID, typeID int64) ([]map[string]any, error)

GetCircleStatisticsByTypeId 获取指定维度和类型的写实统计数据。

对应 GET /api/studentCircleNew/getCircleStatisticsByTypeId?dimensionId=&typeId=

func (*Client) GetCircleTasks

func (c *Client) GetCircleTasks(ctx context.Context, token string, typeID int64) ([]map[string]any, error)

GetCircleTasks 为 GetTaskItems 的向后兼容别名。

func (*Client) GetCircleTypeByTaskID

func (c *Client) GetCircleTypeByTaskID(ctx context.Context, token string, taskID int64) (*types.TaskCircleTypeInfo, error)

GetCircleTypeByTaskID 获取任务提交前所需的 circleTypeId / dimensionId / hours 等元数据。

真实网页在打开任务提交通道前会先请求 getCircleTypeByTaskId,再用返回的 dataMap 填充 addCircle 请求体。SDK 暴露该方法,避免调用方手工猜测 circleTypeId。

func (*Client) GetCircleTypes

func (c *Client) GetCircleTypes(ctx context.Context, token string, dimensionID int64, pid string) ([]map[string]any, error)

GetCircleTypes 为 GetTaskCategories 的向后兼容别名。

func (*Client) GetDictList

func (c *Client) GetDictList(ctx context.Context, token string, cateCode int) ([]map[string]any, error)

GetDictList 获取系统字典列表。 GET /api/common/sys/dict/list?cateCode=

cateCode 为平台 Integer(官方 DictController.java:37),非正数本地前置拦截。

func (*Client) GetDimensions

func (c *Client) GetDimensions(ctx context.Context, token string) ([]types.Dimension, error)

GetDimensions 获取任务维度列表。

SDK 高级用户使用;CLI 经 `nazhi task dimensions` 命令调用(task_metadata.go)。

func (*Client) GetHonorLevel

func (c *Client) GetHonorLevel(ctx context.Context, token string, honorTypeID int64) ([]types.HonorSelectOption, error)

GetHonorLevel 获取指定荣誉类型的可用级别。

honorTypeId 为平台 Integer(官方 StudentMoralEduController.java:143-145), 非正数或越界本地前置拦截,归 ErrInvalidPayload。

func (*Client) GetHonorList

func (c *Client) GetHonorList(ctx context.Context, token string, pageNo, pageSize int, key string) (*types.HonorListResult, error)

GetHonorList 查询当前学生已申报的荣誉记录(分页)。

服务端要求同时带上 &key= 参数(可空值),否则返回 HTTP 400。 pageNo 从 1 开始,pageSize 默认 10(与前端一致)。 key 为搜索关键字(可空,会做 URL 转义)。 pageNo/pageSize 为平台 Integer(官方 StudentMoralEduController.java:55-58), 非正数本地前置拦截,归 ErrInvalidPayload。

func (*Client) GetHonorListJSON

func (c *Client) GetHonorListJSON(ctx context.Context, token string, pageNo, pageSize int, key string) (json.RawMessage, error)

GetHonorListJSON 获取指定页荣誉记录的原始 JSON(不含自动翻页)。

与 GetHonorList 1:1 等价(按页调用,不自动翻页), 返回拼装后的完整 JSON 对象 `{"records":..., "page":...}`, records 和 page 字段值都是平台原始字节。 key 为搜索关键字(可空,会做 URL 转义)。

func (*Client) GetHonorTypeForSelect

func (c *Client) GetHonorTypeForSelect(ctx context.Context, token string) ([]types.HonorSelectOption, error)

GetHonorTypeForSelect 获取荣誉等级下拉选项(returnData)。 返回标签/值对(如 [{label:"校",value:5}])。

func (*Client) GetHonorTypeOptions

func (c *Client) GetHonorTypeOptions(ctx context.Context, token string) ([]types.HonorSelectOption, error)

GetHonorTypeOptions 获取荣誉类型下拉选项(荣誉名称列表)。

对应前端 initHonorTypeAndLevel 中 dataList 的读取。 与 GetHonorTypeForSelect 调用同一个接口,但读取 dataList 而非 returnData。

func (*Client) GetHonorTypes

func (c *Client) GetHonorTypes(ctx context.Context, token string) ([]types.HonorType, error)

GetHonorTypes 获取所有可申报的荣誉类型。

实测服务端同时支持 dataList(丰富字段)和 returnData(兼容字段)两条路径, 本方法优先解析 dataList,fallback 到 returnData。

func (*Client) GetHonorTypesJSON

func (c *Client) GetHonorTypesJSON(ctx context.Context, token string) (json.RawMessage, error)

GetHonorTypesJSON 获取所有荣誉类型的原始 JSON 数组。

等价 GetHonorTypes 但保留平台原始字段(如备注 / 启用状态 / 上传附件要求等)。 自动 fallback:dataList(首选)→ returnData(兼容)。

func (*Client) GetMyInfo

func (c *Client) GetMyInfo(ctx context.Context, token string) (*types.UserInfo, error)

GetMyInfo 获取完整的用户个人资料。 包含:姓名、性别、学号、学校、年级、班级、座号(seat)等。

错误契约:

  • 网络/HTTP 失败 → 返回 (nil, fmt.Errorf("GetMyInfo 请求失败: %w", err))
  • 业务 code≠1 → 返回 (nil, fmt.Errorf("获取用户信息业务错误: %w", errors.Join(ErrBusinessRejected, err)))
  • returnData + dataMap 都为空(服务端成功响应但确实无用户数据)→ 返回 (nil, fmt.Errorf("%w: ...", ErrEmptyUserInfo))

调用方应使用 errors.Is 分支判定,**不要**用 `if info == nil { ... }` 兜底:

  • `errors.Is(err, client.ErrEmptyUserInfo)` → 业务成功但无数据,可走 status envelope
  • `errors.Is(err, client.ErrBusinessRejected)` → 服务端主动拒绝(如 session 过期)
  • 其他 err → 真正的网络/HTTP 故障

业务成功但无数据时返回 ErrEmptyUserInfo 哨兵,cmd 层可据此走 status envelope。

func (*Client) GetMyInfoJSON

func (c *Client) GetMyInfoJSON(ctx context.Context, token string) (json.RawMessage, error)

GetMyInfoJSON 获取当前用户完整个人资料的 JSON(经 SDK 后处理)。

内部调用 GetMyInfo() 获取已后处理的 UserInfo struct,再 Marshal 回 JSON。 包含 GetMyInfo 的全部后处理:学校信息 SSO 降级补全、班级名年级前缀清理。

返回值:

  • json.RawMessage:处理后的 UserInfo JSON 字节; 当数据为空时返回 (nil, ErrEmptyUserInfo)。
  • error:网络/解析/业务错误

func (*Client) GetPublicCircles

func (c *Client) GetPublicCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)

GetPublicCircles 获取公示的全部写实记录(全班)。 等价于 ListCircleRecords(ctx, token, CircleListPublic, key)。

func (*Client) GetPublicCirclesJSON

func (c *Client) GetPublicCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)

GetPublicCirclesJSON 获取公示的全部写实记录(全班),返回平台原始 JSON 数组。 等价于 ListCirclesJSON(ctx, token, CircleListPublic, key)。

func (*Client) GetPublicCirclesLimitJSON

func (c *Client) GetPublicCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)

GetPublicCirclesLimitJSON 按偏移和条数限制拉取公示写实记录。 等价于 ListCirclesLimitJSON(ctx, token, CircleListPublic, offset, limit, key)。

func (*Client) GetRecentlyCircleTask

func (c *Client) GetRecentlyCircleTask(ctx context.Context, token string) ([]map[string]any, error)

GetRecentlyCircleTask 获取学生最近提交的写实任务(对齐前端 mainLeft.vue:73)。 GET /api/studentCircleNew/getRecentlyCircleTask 返回当前学生最近填报的写实任务列表(含 id, name, scopeTypeName, circleTaskStatus 等)。

func (*Client) GetSchoolID

func (c *Client) GetSchoolID(ctx context.Context, username string) (*types.SchoolInfo, error)

GetSchoolID 根据学号查询学校 ID 和学校名称。 优先从内存 schoolCache 中读取,若命中则立即返回避免网络往返;未命中时请求 SSO 接口并自动回写缓存。

func (*Client) GetStudentProfileSummary added in v1.12.0

func (c *Client) GetStudentProfileSummary(ctx context.Context, token string) (*StudentProfileSummary, error)

GetStudentProfileSummary 一站式获取学生的扁平化画像摘要。 若 token 为空,自动使用客户端活跃的 Token。

func (*Client) GetSubmittedCircles

func (c *Client) GetSubmittedCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)

GetSubmittedCircles 获取当前用户自己发布的写实记录。 等价于 ListCircleRecords(ctx, token, CircleListSubmitted, key)。

func (*Client) GetSubmittedCirclesJSON

func (c *Client) GetSubmittedCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)

GetSubmittedCirclesJSON 获取当前用户自己发布的写实记录,返回平台原始 JSON 数组。 等价于 ListCirclesJSON(ctx, token, CircleListSubmitted, key)。

func (*Client) GetSubmittedCirclesLimitJSON

func (c *Client) GetSubmittedCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)

GetSubmittedCirclesLimitJSON 按偏移和条数限制拉取当前用户自己发布的写实记录。 等价于 ListCirclesLimitJSON(ctx, token, CircleListSubmitted, offset, limit, key)。

func (*Client) GetTaskCategories

func (c *Client) GetTaskCategories(ctx context.Context, token string, dimensionID int64, pid string) ([]map[string]any, error)

GetTaskCategories 获取指定维度下的写实类别(对齐前端 managementRightTop.vue:817)。 GET /api/studentCircleNew/getCircleType?dimensionId=&pid= pid 为空时省略 &pid=,与普校前端(`?dimensionId=`+e.id)一致; 非空 pid 必须是数字,非法在本地拦截(见 validateCircleTypeQuery)。

func (*Client) GetTaskItems

func (c *Client) GetTaskItems(ctx context.Context, token string, typeID int64) ([]map[string]any, error)

GetTaskItems 获取指定类别下的写实任务(对齐前端 managementRightTop.vue:869)。 GET /api/studentCircleNew/getCircleTask?typeId=

func (*Client) GetTeacherCircles

func (c *Client) GetTeacherCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)

GetTeacherCircles 获取教师代写的全部写实记录。 等价于 ListCircleRecords(ctx, token, CircleListTeacher, key)。

func (*Client) GetTeacherCirclesJSON

func (c *Client) GetTeacherCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)

GetTeacherCirclesJSON 获取教师代写的全部写实记录,返回平台原始 JSON 数组。 等价于 ListCirclesJSON(ctx, token, CircleListTeacher, key)。

func (*Client) GetTeacherCirclesLimitJSON

func (c *Client) GetTeacherCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)

GetTeacherCirclesLimitJSON 按偏移和条数限制拉取教师写实记录。 等价于 ListCirclesLimitJSON(ctx, token, CircleListTeacher, offset, limit, key)。

func (*Client) GetToken added in v1.12.0

func (c *Client) GetToken() string

GetToken 获取当前客户端持有的 X-Auth-Token。

func (*Client) GetTypicalCaseList

func (c *Client) GetTypicalCaseList(ctx context.Context, token string, pageNo, pageSize int, status ...int) (*types.TypicalCaseListResult, error)

GetTypicalCaseList 查询典型案例列表(分页)。

status 为可选变参:不传时默认 3(全部),与前端默认一致。 取值:0 未审 / 1 通过 / 2 驳回 / 3 全部;非法值在发请求前归 ErrInvalidPayload(400 / 退出码 3),不发出任何业务请求。

签名:GetTypicalCaseList(ctx, token, pageNo, pageSize, status...int) 多传 status 时仅用第一个。

func (*Client) GetTypicalCaseListJSON

func (c *Client) GetTypicalCaseListJSON(ctx context.Context, token string, pageNo, pageSize int, status ...int) (json.RawMessage, error)

GetTypicalCaseListJSON 返回典型案例列表的原始 JSON(CLI 1:1 对齐)。

status 变参语义同 GetTypicalCaseList:默认 3(全部),非法值同样在 发请求前被拒。拼装 {"records":..., "page":...},records 和 page 均为 平台原始字节。

func (*Client) GetWithdrawnCircles

func (c *Client) GetWithdrawnCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)

GetWithdrawnCircles 获取被撤回的全部写实记录。 等价于 ListCircleRecords(ctx, token, CircleListWithdrawn, key)。

func (*Client) GetWithdrawnCirclesJSON

func (c *Client) GetWithdrawnCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)

GetWithdrawnCirclesJSON 获取被撤回的全部写实记录,返回平台原始 JSON 数组。 等价于 ListCirclesJSON(ctx, token, CircleListWithdrawn, key)。

func (*Client) GetWithdrawnCirclesLimitJSON

func (c *Client) GetWithdrawnCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)

GetWithdrawnCirclesLimitJSON 按偏移和条数限制拉取被撤回写实记录。 等价于 ListCirclesLimitJSON(ctx, token, CircleListWithdrawn, offset, limit, key)。

func (*Client) InvalidateCachedUserInfo

func (c *Client) InvalidateCachedUserInfo()

InvalidateCachedUserInfo 清空 session 缓存的 UserInfo。

供调用方在绕过 UpdateMyInfo 直接改服务端用户资料后,主动让本地缓存失效。 UpdateMyInfo / UpdateMyInfoStructured 成功路径已自动调用本方法。

func (*Client) IsTokenValid added in v1.12.0

func (c *Client) IsTokenValid() bool

IsTokenValid 判定当前 Token 是否非空且未过期(剩余有效期大于 10 秒缓冲区)。

func (*Client) ListCircleRecords

func (c *Client) ListCircleRecords(ctx context.Context, token string, listType CircleListType, key string) ([]types.CircleRecord, error)

ListCircleRecords 按写实列表类型获取写实记录(结构化路径,自动翻页合并)。

这是 GetPublicCircles / GetTeacherCircles / GetSubmittedCircles / GetWithdrawnCircles 四个入口的统一形式——它们除方法名与那个数字外逐字 相同。保留旧入口为薄壳,理由与 ListCirclesJSON 相同。

与 ListCirclesJSON 的分工:CLI 走透传路径(byte-for-byte 保持平台 JSON), 需要强类型结构的 Go 调用方走本方法。

func (*Client) ListCirclesJSON

func (c *Client) ListCirclesJSON(ctx context.Context, token string, listType CircleListType, key string) (json.RawMessage, error)

ListCirclesJSON 按写实列表类型获取写实记录,返回平台原始 JSON 数组。

这是 GetPublicCirclesJSON / GetTeacherCirclesJSON / GetSubmittedCirclesJSON / GetWithdrawnCirclesJSON 四个入口的统一形式——它们除方法名与那个数字外 逐字相同,四个入口曾各自占一行转发(raw_json.go),调用方要学四个名字却 只用上一份知识。旧入口保留为薄壳,转发到本方法,行为逐字不变 (由 TestListCirclesJSON_EquivOldEntrypoints 锁定)。

key 为搜索关键字(可空,对应 getStudentCircle 的 key 查询参数)。 取消语义:ctx 取消时返回(已有合并数据, ctx.Err()),调用方按 partial envelope 处理。

func (*Client) ListCirclesLimitJSON

func (c *Client) ListCirclesLimitJSON(ctx context.Context, token string, listType CircleListType, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)

ListCirclesLimitJSON 按写实列表类型分页获取写实记录,返回平台原始 JSON 数组与分页元数据。

offset=0, limit=0 时为全量(等于 ListCirclesJSON),此时仍保留 PageBean—— 丢弃分页元数据是已修复过的回归,不得回退。 offset/limit 超出实际数据量时返回空数组,不报错。

func (*Client) LogDebugForTest

func (c *Client) LogDebugForTest(ctx context.Context, format string, args ...any)

LogDebugForTest 暴露给白盒测试的 debug 入口(携带 ctx)。

委托给私有 logDebugCtx 而非自行实现:两者本是同一份知识,写两遍必然漂移 ——与上面 Enabled 委托 logEnabled 同理。改这一处时另一处必须同步。

func (*Client) LogInfoForTest

func (c *Client) LogInfoForTest(ctx context.Context, format string, args ...any)

LogInfoForTest 暴露给白盒测试的 info 入口(携带 ctx)。

func (*Client) Login

Login 完成五育活动端免验证码登录并返回 Token。

登录流程:

  • 若请求未携带 SchoolID,先通过匿名接口 GetSchoolID 自动推断;
  • 密码本地计算 MD5(hex_md5 口径,与官方 APK 一致)后, POST /uiActivityLogin/studentLogin 免验证码直签 JWT;
  • 解析 returnData.token 并同步到 cookie jar。

该端点无验证码、无 ticket;与主站 X-Auth-Token 同认证体系。

func (*Client) PeekCircleTotal

func (c *Client) PeekCircleTotal(ctx context.Context, token string, listType CircleListType, key string) (int, error)

PeekCircleTotal 按写实列表类型取总条数,不做全量取数。

这是 PeekPublicTotal / PeekTeacherTotal / PeekSubmittedTotal / PeekWithdrawnTotal 四个入口的统一形式,理由同 ListCirclesJSON。 CLI 的 --count 分支用它输出记录总数。

func (*Client) PeekPublicTotal

func (c *Client) PeekPublicTotal(ctx context.Context, token string, key string) (int, error)

PeekPublicTotal 快速获取公示写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListPublic, key)。

func (*Client) PeekSubmittedTotal

func (c *Client) PeekSubmittedTotal(ctx context.Context, token string, key string) (int, error)

PeekSubmittedTotal 快速获取我发布的写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListSubmitted, key)。

func (*Client) PeekTeacherTotal

func (c *Client) PeekTeacherTotal(ctx context.Context, token string, key string) (int, error)

PeekTeacherTotal 快速获取教师写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListTeacher, key)。

func (*Client) PeekWithdrawnTotal

func (c *Client) PeekWithdrawnTotal(ctx context.Context, token string, key string) (int, error)

PeekWithdrawnTotal 快速获取被撤回写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListWithdrawn, key)。

func (*Client) PrefillSchoolCache added in v1.12.0

func (c *Client) PrefillSchoolCache(username string, info *types.SchoolInfo)

PrefillSchoolCache 主动预填某个学号的学校缓存信息。

func (*Client) PreviewEditPayload

func (c *Client) PreviewEditPayload(ctx context.Context, token string, input types.TaskEditInput) (*types.TaskAddCirclePayload, error)

PreviewEditPayload 预览编辑时的最终 payload。同 PreviewSubmitPayload: 不发 editCircle 提交请求、不上传图片,但会拉取任务元数据并预热 session。

func (*Client) PreviewSubmitPayload

func (c *Client) PreviewSubmitPayload(ctx context.Context, token string, input types.TaskSubmitInput) (*types.TaskAddCirclePayload, error)

PreviewSubmitPayload 预览提交时的最终 payload。不发 addCircle 提交请求、不做 图片上传本地副作用,但仍会真实调用 getCircleTypeByTaskId 拉取任务元数据并预热 session(镜像前端打开提交弹窗时的固有网络步骤),离线环境不可用。 与 SubmitTask 共用 buildTaskPayload 同一组装链路(等价不变式见 task_preview_parity_test.go); 上传钩子为 nil:跳过 ImagePaths——pictureList 只含 ImageIDs,ImagePaths 在预览路径被忽略。

func (*Client) QuerySelfEvaluation

func (c *Client) QuerySelfEvaluation(ctx context.Context, token string) (*types.SelfEvalStatus, error)

QuerySelfEvaluation 查询自我评价状态 + 教师评语。

使用 doBizGetDecode 的 fallback 链(returnData → dataMap → dataList[0])。

空数据契约:服务端 code=1 但尚未提交评价(returnData/dataMap/dataList 全空, 或解码后归一化为 nil)时返回 (nil, nil),与 QuerySelfEvaluationJSON 对齐。 不把「未提交」误判为 doBizGetDecode 的「所有解码器均失败」。

func (*Client) QuerySelfEvaluationJSON

func (c *Client) QuerySelfEvaluationJSON(ctx context.Context, token string) (json.RawMessage, error)

QuerySelfEvaluationJSON 查询自我评价状态的原始 JSON。

等价 QuerySelfEvaluation 但保留平台原始字段。 结构化方法内部是 returnData → dataMap → dataList[0] 三解码器 fallback 链; 本方法走 rawSingleObjectBytes:returnData 对象优先,其次 dataList[0],再 dataMap。 对账口径:前端唯一读取通道是 dataMap(mainLeft.vue);若服务端异常地 双容器并存且内容不同,本方法透传的是 returnData 内容,与网页所见可能 不一致——对账请以结构化方法或 dataMap 字段为准。

func (*Client) QuerySelfGradEvaluation

func (c *Client) QuerySelfGradEvaluation(ctx context.Context, token string) (*map[string]any, error)

QuerySelfGradEvaluation 查询毕业状态。

CLI 通过 QuerySelfGradEvaluationJSON 透传原始 JSON(self-eval grad-status)。 使用 doBizGetDecode 的 fallback 链(returnData → dataMap)。

func (*Client) QuerySelfGradEvaluationJSON

func (c *Client) QuerySelfGradEvaluationJSON(ctx context.Context, token string) (json.RawMessage, error)

QuerySelfGradEvaluationJSON 查询毕业评价状态的原始 JSON。

等价 QuerySelfGradEvaluation 但保留平台原始字段。 前端 mainLeft.vue 主读 dataMap.student_comment / isGrad; 本方法走 rawSingleObjectBytes:returnData 对象优先,其次 dataList[0],再 dataMap。 对账口径:若服务端异常地双容器并存且内容不同,透传的是 returnData 内容, 与网页所见的 dataMap 可能不一致——对账请以结构化方法或 dataMap 字段为准。 空数据时返回 (nil, nil)。

func (*Client) QuerySelfGradEvaluationStatus added in v1.12.0

func (c *Client) QuerySelfGradEvaluationStatus(ctx context.Context, token string) (*types.SelfGradEvalStatus, error)

QuerySelfGradEvaluationStatus 查询毕业评价状态(强类型)。

对应平台 querySelfGradEvaluation 接口返回(nazhi-src StudentMoralEduController.java:169-253)。 平台在 studentClass.gradeName == "高三" && currentTermName 包含 "下学期" 时下发 isGrad=1,其余下发 0。 使用 doBizGetDecode 的 fallback 链(returnData → dataMap)。

func (*Client) QuickSubmitRecord added in v1.12.0

func (c *Client) QuickSubmitRecord(ctx context.Context, token string, input QuickRecordInput) error

QuickSubmitRecord 便捷写实提交辅助函数。 自动对日期格式进行自愈规整、回填默认活动字段,并发起提交。

func (*Client) RefreshToken added in v1.12.0

func (c *Client) RefreshToken(ctx context.Context) error

RefreshToken 主动使用保存的凭证重新登录平台并激活会话,更新本地 Token 与 Cookie。

func (*Client) SetCircleLike

func (c *Client) SetCircleLike(ctx context.Context, token string, circleID int64) error

SetCircleLike 点赞或取消点赞写实记录。 GET /api/studentCircleNew/setCircleLikeById?circleId= 服务端自动切换点赞/取消状态。 circleId 为平台 Integer(官方 CircleController.java:236-243),本地前置校验。

func (*Client) SetToken added in v1.12.0

func (c *Client) SetToken(token string) error

SetToken 手动设置并同步客户端的 X-Auth-Token,同时更新其过期时间并同步 Cookie。

func (*Client) SubmitSelfEvaluation

func (c *Client) SubmitSelfEvaluation(ctx context.Context, token string, comment string) error

SubmitSelfEvaluation 提交自我评价文本。

func (*Client) SubmitSelfEvaluationStructured

func (c *Client) SubmitSelfEvaluationStructured(ctx context.Context, token string, form map[string]any) error

SubmitSelfEvaluationStructured 提交结构化自我评价。

对应前端 selfgaintloss.vue 的"诉得失"页面:会做人/会求知/会生活/会创造/表现/优势/劣势 + 下学期目标。 SDK 内部将 form 对象 JSON 序列化后,再包装为 {"studentComment": "<json>"} 提交。

典型字段:

bxqhzr — 本学期会做人目标
bxqhqz — 本学期会求知目标
bxqhsh — 本学期会生活目标
bxqhcz — 本学期会创造目标
bxqbx  — 本学期表现
bxqys  — 本学期优势
bxqls  — 本学期劣势
sxqhzr — 下学期会做人目标
sxqhqz — 下学期会求知目标
sxqhsh — 下学期会生活目标
sxqhcz — 下学期会创造目标

func (*Client) SubmitSelfGradEvaluation

func (c *Client) SubmitSelfGradEvaluation(ctx context.Context, token string, comment string) error

SubmitSelfGradEvaluation 提交毕业评价。

与 SubmitSelfEvaluation 对称,使用 {"studentComment": "<评语>"} 请求体。

func (*Client) SubmitTask

func (c *Client) SubmitTask(ctx context.Context, token string, input types.TaskSubmitInput) (*types.TaskResult, error)

公开接口仅接收最少必要输入,SDK 内部自动补齐真实网页提交流程所需字段: getCircleTypeByTaskId → UploadFile → addCircle(不再发明学校名/默认等级)。

func (*Client) TokenExpiresAt added in v1.12.0

func (c *Client) TokenExpiresAt() time.Time

TokenExpiresAt 获取当前 Token 的预计过期时间。

func (*Client) TokenRemaining added in v1.12.0

func (c *Client) TokenRemaining() time.Duration

TokenRemaining 获取当前 Token 的剩余有效时间。

func (*Client) UpdateHonor

func (c *Client) UpdateHonor(ctx context.Context, token string, payload map[string]any) error

UpdateHonor 更新一条荣誉记录。 POST /api/studentMoralEduNew/updateHonor

与 AddHonor 对称:当 payload 含 typeId 且 typeName 为空/缺失时, 自动调用 GetHonorTypeOptions 反查补全 typeName。

func (*Client) UpdateMyInfo

func (c *Client) UpdateMyInfo(ctx context.Context, token string, updates map[string]any) error

UpdateMyInfo 更新当前用户个人信息。 POST /api/studentInfo/updateMyInfo updates 是 map,只传需要修改的字段,如:

{"telephone": "138xxx", "familyAddress": "福建省福州市", "hobbies": "阅读"}

可写字段为更新接口的线格式键名(studentName/studentNumber/telephone/gender 数字码/youthLeagueFlag/nation/idType/idCard/birthday/seat/studentUuid 等)—— 注意与读接口 UserInfo 的 json tag 不同形(读侧是 name/genderName,写侧是 studentName/gender 数字),照抄 UserInfo tag 会静默无效。中文枚举转数字码 请改用 UpdateMyInfoStructured。

成功后会失效 sm.cachedUserInfo:ActivateSession 步骤 4 缓存的 UserInfo 不再对 GetMyInfo 的持锁 fast path 可见,下次 GetMyInfo 会重新拉取。

func (*Client) UpdateMyInfoStructured

func (c *Client) UpdateMyInfoStructured(ctx context.Context, token string, input types.UserUpdateInput) error

UpdateMyInfoStructured 使用面向用户的字段名更新个人信息。

与 UpdateMyInfo 的区别:接收友好字段名(如 GenderName="男"), SDK 内部自动转换为 API 数字代码(如 gender=1)。 零值/空串字段跳过,不会覆盖服务端已有值。

支持的字段转换:

  • GenderName → gender
  • YouthLeague → youthLeagueFlag
  • NationName → nation
  • IdCardType → idType

用户可编辑透传:Telephone / FamilyAddress / Hobbies / IDCard / Birthday / BirthdayStr / Seat / StudentUuid Birthday 优先对应前端 birthday 键;BirthdayStr 仅作为旧调用兼容字段。 可选高级:Name→studentName、StudentNumber 不写入:NationalStudentNumber(前端只读,Structured 忽略以免误改学籍)

func (*Client) UpdateTypicalCase

func (c *Client) UpdateTypicalCase(ctx context.Context, token string, payload map[string]any) error

UpdateTypicalCase 更新一条典型案例。 POST /api/studentCircleNew/updateTypicalCase

与 AddTypicalCase 对称:type/role/level 有值且对应 *Name 为空时自动补展示名。 remark/content 长度校验与 Add 同族(198/1500 rune,ErrInvalidPayload)。

func (*Client) UploadFile

func (c *Client) UploadFile(ctx context.Context, filePath string) (*types.UploadFileResult, error)

UploadFile 上传图片或前端允许的非图片附件,返回附件 ID。

关键约束:本方法不发送任何 Token / Cookie / Authorization 头。 文件服务器(doc.nazhisoft.com)是独立公共服务,不需要业务域鉴权。 SDK 内部使用独立的 clean http.Client(无 cookie jar),全程不携带任何鉴权头。

域隔离约束:syncCookieToken 只在 c.baseURL 域写入 X-Auth-Token cookie, 而 UploadFile 走 c.uploadURL 域(独立文件服务器)。 若 c.uploadURL 与 c.baseURL 指向同一主机(自定义部署场景), 则 syncCookieToken 写入的 cookie 在上传请求中不会泄漏(newCleanClient 无 cookie jar)。 但调用方应注意不要在业务 Client 的 baseURL 域上传敏感文件。

上传前自动预处理:

  • 图片(扩展名不在下方白名单内者):按魔术字节尝试解码(已注册 jpeg/png/gif/webp/bmp), 解码成功后转 JPG + 透明合成 + 压缩至 ≤ 5MB(MaxImageSize,SDK 放宽);解码器不认识的格式报错拒绝
  • 非图片附件(directUploadExtensions 白名单:.pdf/.mp4/.txt/.doc/.docx/.wps/.rar/.zip):原样直传,上限 20MB(MaxAttachmentSize,SDK 有意放宽;前端镜像文案 20MB,服务端真实上限约 46.86MiB)

统一说明:图片压缩后 5MB(SDK 放宽),非图片附件 20MB(SDK 有意放宽,服务端实测支撑) 全部在内存中完成,不写盘、不修改原文件。

type ClientBuilder added in v1.12.0

type ClientBuilder struct {
	// contains filtered or unexported fields
}

ClientBuilder 提供链式(Fluent)客户端构建与连接支持。

func NewBuilder added in v1.12.0

func NewBuilder() *ClientBuilder

NewBuilder 创建一个流式客户端构建器。

func (*ClientBuilder) Build added in v1.12.0

func (b *ClientBuilder) Build() (*Client, error)

Build 完成 Client 的实例化(不自动登录)。

func (*ClientBuilder) Connect added in v1.12.0

Connect 使用链中配置的凭据与选项执行一站式直接连接(查校、登录、Session 预热)。

func (*ClientBuilder) WithAutoReconnect added in v1.12.0

func (b *ClientBuilder) WithAutoReconnect(enable bool) *ClientBuilder

WithAutoReconnect 配置遇到 401 时是否自动重连自愈。

func (*ClientBuilder) WithBaseURL added in v1.12.0

func (b *ClientBuilder) WithBaseURL(url string) *ClientBuilder

WithBaseURL 设置业务 API 根地址。

func (*ClientBuilder) WithCredentials added in v1.12.0

func (b *ClientBuilder) WithCredentials(username, password string) *ClientBuilder

WithCredentials 设置登录凭据(学号和密码)。

func (*ClientBuilder) WithOptions added in v1.12.0

func (b *ClientBuilder) WithOptions(opts ...Option) *ClientBuilder

WithOptions 追加任意原始 Option。

func (*ClientBuilder) WithSSOBase added in v1.12.0

func (b *ClientBuilder) WithSSOBase(url string) *ClientBuilder

WithSSOBase 设置 SSO 根地址。

func (*ClientBuilder) WithSchoolCache added in v1.12.0

func (b *ClientBuilder) WithSchoolCache(ttl time.Duration) *ClientBuilder

WithSchoolCache 配置学校内存缓存。

func (*ClientBuilder) WithSchoolID added in v1.12.0

func (b *ClientBuilder) WithSchoolID(schoolID string) *ClientBuilder

WithSchoolID 设置预设学校 ID。

func (*ClientBuilder) WithTimeout added in v1.12.0

func (b *ClientBuilder) WithTimeout(d time.Duration) *ClientBuilder

WithTimeout 设置 HTTP 客户端超时。

func (*ClientBuilder) WithToken added in v1.12.0

func (b *ClientBuilder) WithToken(token string) *ClientBuilder

WithToken 预置 X-Auth-Token。

func (*ClientBuilder) WithUploadURL added in v1.12.0

func (b *ClientBuilder) WithUploadURL(url string) *ClientBuilder

WithUploadURL 设置文件上传服务器地址。

type ErrorCategory

type ErrorCategory int

ErrorCategory 是错误分类枚举。

const (
	CategoryUnknown        ErrorCategory = iota
	CategoryContextCancel                // 上下文取消
	CategoryContextTimeout               // 上下文超时
	CategoryNetworkTimeout               // 网络层超时(TCP/TLS/响应头)
	CategoryBusinessError                // 业务拒绝(ErrBusinessRejected)
)

func ClassifyError

func ClassifyError(err error) ErrorCategory

ClassifyError 对错误进行分类,返回 ErrorCategory 枚举。

检查优先级(短路):

  1. context.Canceled → CategoryContextCancel
  2. context.DeadlineExceeded → CategoryContextTimeout
  3. url.Error.Timeout() / net.OpError.Timeout() → CategoryNetworkTimeout
  4. errors.Is(err, ErrBusinessRejected) → CategoryBusinessError
  5. 其他 → CategoryUnknown

func (ErrorCategory) String

func (c ErrorCategory) String() string

String 实现 fmt.Stringer。

type Option

type Option func(*Client)

Option 是 Client 构造函数的选项函数。

func WithAutoReconnect added in v1.12.0

func WithAutoReconnect(enable bool) Option

WithAutoReconnect 配置是否在遇到 401 Unauthorized 时自动尝试重连续期。

func WithCredentials added in v1.12.0

func WithCredentials(username, password string) Option

WithCredentials 为客户端注入登录凭证,供 Token 过期或 401 时自动重新登录保活使用。

func WithMaxRetries added in v1.12.0

func WithMaxRetries(n int) Option

WithMaxRetries 配置瞬态错误与网络抖动的最大重试次数。 默认对幂等 GET 请求及安全的网络异常允许 1~2 次轻量重试,退避时间 100ms~300ms。 0 表示禁用重试。

func WithOnTokenRefreshed added in v1.12.0

func WithOnTokenRefreshed(cb func(newToken string, exp time.Time)) Option

WithOnTokenRefreshed 注册 Token 刷新成功后的回调函数。

func WithSchoolCache added in v1.12.0

func WithSchoolCache(ttl time.Duration) Option

WithSchoolCache 配置客户端学校信息缓存的 TTL 有效期。 启用缓存后,对同一学号的 GetSchoolID 将直接命中内存缓存,避免重复网络往返。 传入 0 表示使用默认 30 分钟 TTL;传入负数表示禁用学校缓存。

func WithSchoolID added in v1.12.0

func WithSchoolID(schoolID string) Option

WithSchoolID 设置预设学校 ID(供 Connect 免查校极速直连)。

func WithSubmittedPageSize

func WithSubmittedPageSize(n int) Option

WithSubmittedPageSize 配置 GetSubmittedCircles 每页请求条数。

行为约定:

  • n <= 0:拒绝设置并 warn,保持当前值(防止清零或负数)
  • n > maxSubmittedPageSize:拒绝设置并 warn,保持当前值
  • 其余:设置每页请求条数

上界的必要性:翻页路径的容量上界是「钳制页数 × pageSize」(见 submitted.go 的 maxSubmittedCapacityCeiling 与随后的条数闸)。该上界 必须在本选项这里就被限制,否则 pageSize 无界会让容量上界随调用方 输入膨胀:本选项是公开 API,调用方可能传入任意值。

注意成因与钳制的比较方式:submitted.go 已改为除法比较 (capacity/maxTotalPage > pageSize),使乘法回绕不再发生——因此 「pageSize 极大导致 make 拿到负容量」是已修缺陷的历史成因,不是 当前行为。本选项的价值是防容量上界膨胀,不是防乘法溢出。

上界取值远高于服务端实际上限 500(实测 pageSize=10000 被服务端截断为 500),此处只作为容量膨胀防线,不改变正常取值范围。

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout 设置 HTTP 客户端超时(包括连接、TLS 握手、响应体读取)。

行为约定:

  • c.http == nil:拒绝设置并 warn(外部 WithHTTPClient(nil) 误用, 静默 return 会让调用方完全感知不到 timeout 未生效)
  • d > 0:设置超时
  • d = 0:拒绝设置并 warn,保持当前 Timeout(防止静默把已有 正数超时清零为 net/http 默认"无超时",请求可能永久挂起)
  • d < 0:拒绝设置并 warn,保持当前 Timeout(防止意外把超时改小)

type ParallelDimsResult

type ParallelDimsResult[T any] struct {
	Items          []T     // 所有成功维度的 item(按维度声明顺序拼接)
	BizErrors      []error // 非 context 取消的业务错误
	ContextErrors  []error // context 取消/超时错误
	CancelledCount int     // 因 ctx 取消/超时而失败的维度数
	FailedCount    int     // 因业务错误而失败的维度数
}

ParallelDimsResult 是并行维度查询的聚合结果。

func ParallelDims

func ParallelDims[T any](ctx context.Context, dims []types.Dimension, limit int, fn func(context.Context, types.Dimension) ([]T, error)) (result *ParallelDimsResult[T], egErr error)

ParallelDims 对维度列表并发执行 fn,聚合结果并自动分类错误。

行为:

  • 跳过 id=0 的汇总维度
  • 并发上限 = limit;limit<=0 时按 1(串行)执行
  • fn 接收含 errgroup 取消传播的 ctx 和单个 dimension,返回该维度的 items 和 error
  • 单个维度失败不中断其他维度的执行
  • Items 按维度声明顺序拼接(与完成顺序无关),保证同输入同输出

返回的 ParallelDimsResult 包含聚合后的 items、分类后的错误列表和计数。 egErr 是 errgroup.Wait() 返回的错误(当 goroutine 直接 return err 时触发, 通常只传递 context 取消信号)。

fan-out 与保序落槽由 collectDims 内核承担(透传路径 FetchTasksJSON 共用 同一内核),本函数只负责展平分片与按 ClassifyError 口径分类错误。 维度数上界由本导出层持有:collectDimsOpts 零值表示不钳制是内核的显式 契约(见 TestCollectDims_NoClampWhenUnset),但 ParallelDims 是面向调用方 的入口,防护不该依赖「内部调用方恰好自己预钳了一次」。维度闸与两条取数 路径同源,均为 maxFetchTasksDims。

type QuickRecordInput added in v1.12.0

type QuickRecordInput struct {
	TaskID             int64   `json:"taskId"`
	Content            string  `json:"content"`
	Date               string  `json:"date,omitempty"` // 支持多种输入格式,底层自动 NormalizeDate
	Hours              string  `json:"hours,omitempty"`
	ActivityName       string  `json:"activityName,omitempty"`
	ImageIDs           []int64 `json:"imageIds,omitempty"`
	AllowEmptyPictures bool    `json:"allowEmptyPictures,omitempty"`
}

QuickRecordInput 描述简化的写实记录提交参数。

type StudentProfileSummary added in v1.12.0

type StudentProfileSummary struct {
	ID                    int64  `json:"id"`
	Name                  string `json:"name"`
	StudentNumber         string `json:"studentNumber"`
	SchoolID              int64  `json:"schoolId"`
	SchoolName            string `json:"schoolName"`
	GradeID               int64  `json:"gradeId"`
	GradeName             string `json:"gradeName"`
	ClassID               int64  `json:"classId"`
	ClassName             string `json:"className"`
	Seat                  int    `json:"seat"`
	NationalStudentNumber string `json:"nationalStudentNumber,omitempty"`
}

StudentProfileSummary 是学生身份与班级档案的扁平化全景视图。

type TypicalCaseStatus

type TypicalCaseStatus int

TypicalCaseStatus 是典型案例审核状态,即 getTypicalCase 查询参数 status 的线协议取值(与前端 classiccanter.vue 的下拉一致)。

与写实列表类型同理:status 直接驱动服务端的列表过滤,非法值不会报错, 只会静默返回一份意料之外的记录集合。做成具名类型并在发请求前 Valid, 是让它不再依赖「记得只在 0..3 里选」的根本手段。

它与写实状态(CircleRecord.Status:0 已发布 / 1 已锁定 / 2 被撤回) 不是同一概念,勿混读。

const (
	// TypicalCaseStatusPending 未审核。
	TypicalCaseStatusPending TypicalCaseStatus = 0
	// TypicalCaseStatusApproved 审核通过。
	TypicalCaseStatusApproved TypicalCaseStatus = 1
	// TypicalCaseStatusRejected 审核驳回。
	TypicalCaseStatusRejected TypicalCaseStatus = 2
	// TypicalCaseStatusAll 全部(前端默认)。
	TypicalCaseStatusAll TypicalCaseStatus = 3
)

func (TypicalCaseStatus) Valid

func (s TypicalCaseStatus) Valid() bool

Valid 报告该状态是否为平台承认的四种之一。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址