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
- Variables
- func NormalizeDate(input string) string
- func NormalizeHonorGetDate(s string) string
- func ParseStudentComment(comment string) (map[string]any, error)
- type CircleListType
- type Client
- func Connect(ctx context.Context, username, password string, opts ...Option) (*Client, *types.LoginResponse, error)
- func ConnectEnv(ctx context.Context, extraOpts ...Option) (*Client, *types.LoginResponse, error)
- func ConnectURL(ctx context.Context, connURL string, extraOpts ...Option) (*Client, *types.LoginResponse, error)
- func New(opts ...Option) (*Client, error)
- func (c *Client) ActivateSession(ctx context.Context, token string) (*types.UserInfo, error)
- func (c *Client) ActivateSessionJSON(ctx context.Context, token string) (json.RawMessage, error)
- func (c *Client) AddCircleComment(ctx context.Context, token string, circleID int64, content string) (*types.Comment, error)
- func (c *Client) AddHonor(ctx context.Context, token string, payload types.AddHonorPayload) error
- func (c *Client) AddTypicalCase(ctx context.Context, token string, payload types.AddTypicalCasePayload) error
- func (c *Client) ChangePassword(ctx context.Context, token string, newPassword string) error
- func (c *Client) ClearSchoolCache()
- func (c *Client) Close() error
- func (c *Client) DeleteBatchTypicalCase(ctx context.Context, token string, ids []int64) error
- func (c *Client) DeleteCircle(ctx context.Context, token string, circleID int64) error
- func (c *Client) DeleteHonor(ctx context.Context, token string, honorID int64) error
- func (c *Client) DeleteTypicalCase(ctx context.Context, token string, id int64) error
- func (c *Client) DownloadFile(ctx context.Context, attachmentID int64, dst string) error
- func (c *Client) EditCircle(ctx context.Context, token string, input types.TaskEditInput) (*types.TaskResult, error)
- func (c *Client) Enabled(ctx context.Context, lvl slog.Level) bool
- func (c *Client) EnsureValidSession(ctx context.Context, minRemaining time.Duration) error
- func (c *Client) FetchTasks(ctx context.Context, token string) ([]types.Task, error)
- func (c *Client) FetchTasksJSON(ctx context.Context, token string) (json.RawMessage, error)
- func (c *Client) FindTaskByName(ctx context.Context, token, taskName string) (*types.Task, error)
- func (c *Client) FindTasksByKeyword(ctx context.Context, token, keyword string) ([]types.Task, error)
- func (c *Client) GetCircleImages(ctx context.Context, token string, pageNo, pageSize int) ([]map[string]any, error)
- func (c *Client) GetCircleStatistics(ctx context.Context, token string, dimensionID *int64) ([]map[string]any, error)
- func (c *Client) GetCircleStatisticsByTypeId(ctx context.Context, token string, dimensionID, typeID int64) ([]map[string]any, error)
- func (c *Client) GetCircleTasks(ctx context.Context, token string, typeID int64) ([]map[string]any, error)
- func (c *Client) GetCircleTypeByTaskID(ctx context.Context, token string, taskID int64) (*types.TaskCircleTypeInfo, error)
- func (c *Client) GetCircleTypes(ctx context.Context, token string, dimensionID int64, pid string) ([]map[string]any, error)
- func (c *Client) GetDictList(ctx context.Context, token string, cateCode int) ([]map[string]any, error)
- func (c *Client) GetDimensions(ctx context.Context, token string) ([]types.Dimension, error)
- func (c *Client) GetHonorLevel(ctx context.Context, token string, honorTypeID int64) ([]types.HonorSelectOption, error)
- func (c *Client) GetHonorList(ctx context.Context, token string, pageNo, pageSize int, key string) (*types.HonorListResult, error)
- func (c *Client) GetHonorListJSON(ctx context.Context, token string, pageNo, pageSize int, key string) (json.RawMessage, error)
- func (c *Client) GetHonorTypeForSelect(ctx context.Context, token string) ([]types.HonorSelectOption, error)
- func (c *Client) GetHonorTypeOptions(ctx context.Context, token string) ([]types.HonorSelectOption, error)
- func (c *Client) GetHonorTypes(ctx context.Context, token string) ([]types.HonorType, error)
- func (c *Client) GetHonorTypesJSON(ctx context.Context, token string) (json.RawMessage, error)
- func (c *Client) GetMyInfo(ctx context.Context, token string) (*types.UserInfo, error)
- func (c *Client) GetMyInfoJSON(ctx context.Context, token string) (json.RawMessage, error)
- func (c *Client) GetPublicCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)
- func (c *Client) GetPublicCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)
- func (c *Client) GetPublicCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)
- func (c *Client) GetRecentlyCircleTask(ctx context.Context, token string) ([]map[string]any, error)
- func (c *Client) GetSchoolID(ctx context.Context, username string) (*types.SchoolInfo, error)
- func (c *Client) GetStudentProfileSummary(ctx context.Context, token string) (*StudentProfileSummary, error)
- func (c *Client) GetSubmittedCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)
- func (c *Client) GetSubmittedCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)
- func (c *Client) GetSubmittedCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)
- func (c *Client) GetTaskCategories(ctx context.Context, token string, dimensionID int64, pid string) ([]map[string]any, error)
- func (c *Client) GetTaskItems(ctx context.Context, token string, typeID int64) ([]map[string]any, error)
- func (c *Client) GetTeacherCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)
- func (c *Client) GetTeacherCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)
- func (c *Client) GetTeacherCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)
- func (c *Client) GetToken() string
- func (c *Client) GetTypicalCaseList(ctx context.Context, token string, pageNo, pageSize int, status ...int) (*types.TypicalCaseListResult, error)
- func (c *Client) GetTypicalCaseListJSON(ctx context.Context, token string, pageNo, pageSize int, status ...int) (json.RawMessage, error)
- func (c *Client) GetWithdrawnCircles(ctx context.Context, token string, key string) ([]types.CircleRecord, error)
- func (c *Client) GetWithdrawnCirclesJSON(ctx context.Context, token string, key string) (json.RawMessage, error)
- func (c *Client) GetWithdrawnCirclesLimitJSON(ctx context.Context, token string, offset, limit int, key string) (json.RawMessage, *types.PageBean, error)
- func (c *Client) InvalidateCachedUserInfo()
- func (c *Client) IsTokenValid() bool
- func (c *Client) ListCircleRecords(ctx context.Context, token string, listType CircleListType, key string) ([]types.CircleRecord, error)
- func (c *Client) ListCirclesJSON(ctx context.Context, token string, listType CircleListType, key string) (json.RawMessage, error)
- func (c *Client) ListCirclesLimitJSON(ctx context.Context, token string, listType CircleListType, offset, limit int, ...) (json.RawMessage, *types.PageBean, error)
- func (c *Client) LogDebugForTest(ctx context.Context, format string, args ...any)
- func (c *Client) LogInfoForTest(ctx context.Context, format string, args ...any)
- func (c *Client) Login(ctx context.Context, req types.LoginRequest) (*types.LoginResponse, error)
- func (c *Client) PeekCircleTotal(ctx context.Context, token string, listType CircleListType, key string) (int, error)
- func (c *Client) PeekPublicTotal(ctx context.Context, token string, key string) (int, error)
- func (c *Client) PeekSubmittedTotal(ctx context.Context, token string, key string) (int, error)
- func (c *Client) PeekTeacherTotal(ctx context.Context, token string, key string) (int, error)
- func (c *Client) PeekWithdrawnTotal(ctx context.Context, token string, key string) (int, error)
- func (c *Client) PrefillSchoolCache(username string, info *types.SchoolInfo)
- func (c *Client) PreviewEditPayload(ctx context.Context, token string, input types.TaskEditInput) (*types.TaskAddCirclePayload, error)
- func (c *Client) PreviewSubmitPayload(ctx context.Context, token string, input types.TaskSubmitInput) (*types.TaskAddCirclePayload, error)
- func (c *Client) QuerySelfEvaluation(ctx context.Context, token string) (*types.SelfEvalStatus, error)
- func (c *Client) QuerySelfEvaluationJSON(ctx context.Context, token string) (json.RawMessage, error)
- func (c *Client) QuerySelfGradEvaluation(ctx context.Context, token string) (*map[string]any, error)
- func (c *Client) QuerySelfGradEvaluationJSON(ctx context.Context, token string) (json.RawMessage, error)
- func (c *Client) QuerySelfGradEvaluationStatus(ctx context.Context, token string) (*types.SelfGradEvalStatus, error)
- func (c *Client) QuickSubmitRecord(ctx context.Context, token string, input QuickRecordInput) error
- func (c *Client) RefreshToken(ctx context.Context) error
- func (c *Client) SetCircleLike(ctx context.Context, token string, circleID int64) error
- func (c *Client) SetToken(token string) error
- func (c *Client) SubmitSelfEvaluation(ctx context.Context, token string, comment string) error
- func (c *Client) SubmitSelfEvaluationStructured(ctx context.Context, token string, form map[string]any) error
- func (c *Client) SubmitSelfGradEvaluation(ctx context.Context, token string, comment string) error
- func (c *Client) SubmitTask(ctx context.Context, token string, input types.TaskSubmitInput) (*types.TaskResult, error)
- func (c *Client) TokenExpiresAt() time.Time
- func (c *Client) TokenRemaining() time.Duration
- func (c *Client) UpdateHonor(ctx context.Context, token string, payload map[string]any) error
- func (c *Client) UpdateMyInfo(ctx context.Context, token string, updates map[string]any) error
- func (c *Client) UpdateMyInfoStructured(ctx context.Context, token string, input types.UserUpdateInput) error
- func (c *Client) UpdateTypicalCase(ctx context.Context, token string, payload map[string]any) error
- func (c *Client) UploadFile(ctx context.Context, filePath string) (*types.UploadFileResult, error)
- type ClientBuilder
- func (b *ClientBuilder) Build() (*Client, error)
- func (b *ClientBuilder) Connect(ctx context.Context) (*Client, *types.LoginResponse, error)
- func (b *ClientBuilder) WithAutoReconnect(enable bool) *ClientBuilder
- func (b *ClientBuilder) WithBaseURL(url string) *ClientBuilder
- func (b *ClientBuilder) WithCredentials(username, password string) *ClientBuilder
- func (b *ClientBuilder) WithOptions(opts ...Option) *ClientBuilder
- func (b *ClientBuilder) WithSSOBase(url string) *ClientBuilder
- func (b *ClientBuilder) WithSchoolCache(ttl time.Duration) *ClientBuilder
- func (b *ClientBuilder) WithSchoolID(schoolID string) *ClientBuilder
- func (b *ClientBuilder) WithTimeout(d time.Duration) *ClientBuilder
- func (b *ClientBuilder) WithToken(token string) *ClientBuilder
- func (b *ClientBuilder) WithUploadURL(url string) *ClientBuilder
- type ErrorCategory
- type Option
- func WithAutoReconnect(enable bool) Option
- func WithCredentials(username, password string) Option
- func WithMaxRetries(n int) Option
- func WithOnTokenRefreshed(cb func(newToken string, exp time.Time)) Option
- func WithSchoolCache(ttl time.Duration) Option
- func WithSchoolID(schoolID string) Option
- func WithSubmittedPageSize(n int) Option
- func WithTimeout(d time.Duration) Option
- type ParallelDimsResult
- type QuickRecordInput
- type StudentProfileSummary
- type TypicalCaseStatus
Constants ¶
const MaxAttachmentSize = 20 * 1024 * 1024
MaxAttachmentSize 是非图片附件直传的上限(20MB,SDK 有意放宽:前端镜像文案 20MB, 服务端实测无 2MB 硬限、真实上限约 46.86MiB,见 CLAUDE.md「G. 文件上传/下载」节)。 图片走压缩路径,上限为 MaxImageSize(5MB,SDK 放宽);两者分开校验。
const MaxImageSize = 5 * 1024 * 1024
MaxImageSize 默认压缩目标上限(5MB)。
const MinImageDimension = 10
MinImageDimension 缩放下限(像素),低于此值停止缩放。
Variables ¶
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") // // 触发场景:目标平台返回 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") )
var ErrImageTooLarge = errors.New("image exceeds maximum size after compression")
ErrImageTooLarge 压缩后仍超过 MaxImageSize。
var ErrUnsupportedFormat = errors.New("unsupported image format")
ErrUnsupportedFormat 不支持的图片格式。
var WithBaseURL = withURLGuard("WithBaseURL", func(c *Client, v string) { c.baseURL = v })
WithBaseURL 设置业务 API 根地址。
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) 先后不再影响最终生效值
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
var WithSSOBase = withURLGuard("WithSSOBase", func(c *Client, v string) { c.ssoBaseURL = v })
WithSSOBase 设置 SSO 根地址(用于 login 流程)。 默认值由 defaultSSOBase 常量提供(见 request.go defaultSSOBase)。
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 抑制窗口。
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)。
var WithUploadURL = withURLGuard("WithUploadURL", func(c *Client, v string) { c.uploadURL = v })
WithUploadURL 设置文件上传服务器地址。
Functions ¶
func NormalizeDate ¶ added in v1.12.0
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
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 ¶
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
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 ¶
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 ¶
ActivateSession 初始化目标平台业务 Session。 按真实抓包验证:必须按以下 4 步顺序激活,否则后续接口返回空数据:
- GET /(首页)
- GET /api/studentInfo/getMenu(Referer: /homepage?token=xxx)
- GET /api/studentInfo/getMenu(Referer: /home)
- 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 ¶
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 ¶
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
ChangePassword 通过个人信息修改通道重置学生登录密码。
官方前端 modifyBox.vue 通过将新密码存入 studentUuid 字段发送给 /api/studentInfo/updateMyInfo,后端检测到 studentUuid 非空时联动修改学生密码。
func (*Client) ClearSchoolCache ¶ added in v1.12.0
func (c *Client) ClearSchoolCache()
ClearSchoolCache 清空客户端的学校信息缓存。
func (*Client) Close ¶
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 ¶
DeleteBatchTypicalCase 批量删除典型案例。 POST /api/studentCircleNew/deleteBatchTypicalCase
请求体是纯 JSON 数组 [1, 2, 3](前端源码确认)。 空/nil 切片返回 ErrInvalidPayload 而非发出字面 null 请求体 (对齐前端 classiccanter.vue 的空数组守卫与 CLI 层参数校验口径)。
func (*Client) DeleteCircle ¶
DeleteCircle 删除一条写实记录。 GET /api/studentCircleNew/deleteCircle?id=
circleID 为平台 Integer(官方 CircleController.java:132-134 @RequestParam("id")Integer id),本地前置校验与 CLI 同判据。
func (*Client) DeleteHonor ¶
DeleteHonor 删除一条荣誉记录。
真实抓包确认:接口为 GET 请求,ID 通过查询参数传递。 id 为平台 Integer(官方 StudentMoralEduController.java:66-68),本地前置校验。
func (*Client) DeleteTypicalCase ¶
DeleteTypicalCase 删除一条典型案例。 GET /api/studentCircleNew/deleteTypicalCase?id=
id 为平台 Integer(官方 CircleController.java:297-299),本地前置校验。
func (*Client) DownloadFile ¶
DownloadFile 按附件 ID 从公开文件服务器下载图片到本地 dst。
流程:
- GET {ssoBaseURL}/common/attachment/getImg?id={attachmentID}
- 服务端 302 重定向到 doc.nazhisoft.com/other/M00/...(FastDFS 真实存储)
- 跟随重定向(最多 maxDownloadRedirects 次)→ 取真实图片
- 写入本地 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 ¶
Enabled 暴露 logger 的级别判定,供跨包黑盒测试校验(不影响生产行为)。
委托给私有 logEnabled 而非自行实现:两者本是同一份知识,写两遍必然漂移 ——原实现漏掉 logEnabled 的 nil ctx 归一分支,使 ctx 为 nil 时 「级别守卫通过」与「实际会输出」不等价。现由 logEnabled 单点持有该判定。
func (*Client) EnsureValidSession ¶ added in v1.12.0
EnsureValidSession 确保当前拥有有效的会话。 若无 Token、Token 即将过期(剩余有效期小于 minRemaining)或无效, 且已配置了账号密码凭证,将自动触发无感重新登录并激活会话。
func (*Client) FetchTasks ¶
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 ¶
FetchTasksJSON 拉取全维度任务列表,返回平台原始 JSON 数组(跨维度合并)。
自动跨维度并发拉取并在 SDK 内部合并为单一 JSON 数组,保留所有平台字段。 错误聚合与 FetchTasks 对齐:
- context 取消且无 partial → ErrRetryable
- context 取消且有 partial → ErrBusinessRejected + ErrRetryable + 已合并字节
- 业务错误 → 仍返回已合并的字节 + ErrBusinessRejected(cmd 层 partial envelope)
func (*Client) FindTaskByName ¶ added in v1.12.0
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 ¶
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 ¶
GetHonorTypes 获取所有可申报的荣誉类型。
实测服务端同时支持 dataList(丰富字段)和 returnData(兼容字段)两条路径, 本方法优先解析 dataList,fallback 到 returnData。
func (*Client) GetHonorTypesJSON ¶
GetHonorTypesJSON 获取所有荣誉类型的原始 JSON 数组。
等价 GetHonorTypes 但保留平台原始字段(如备注 / 启用状态 / 上传附件要求等)。 自动 fallback:dataList(首选)→ returnData(兼容)。
func (*Client) GetMyInfo ¶
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 ¶
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 ¶
GetRecentlyCircleTask 获取学生最近提交的写实任务(对齐前端 mainLeft.vue:73)。 GET /api/studentCircleNew/getRecentlyCircleTask 返回当前学生最近填报的写实任务列表(含 id, name, scopeTypeName, circleTaskStatus 等)。
func (*Client) GetSchoolID ¶
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) 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
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 ¶
LogDebugForTest 暴露给白盒测试的 debug 入口(携带 ctx)。
委托给私有 logDebugCtx 而非自行实现:两者本是同一份知识,写两遍必然漂移 ——与上面 Enabled 委托 logEnabled 同理。改这一处时另一处必须同步。
func (*Client) LogInfoForTest ¶
LogInfoForTest 暴露给白盒测试的 info 入口(携带 ctx)。
func (*Client) Login ¶
func (c *Client) Login(ctx context.Context, req types.LoginRequest) (*types.LoginResponse, error)
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 ¶
PeekPublicTotal 快速获取公示写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListPublic, key)。
func (*Client) PeekSubmittedTotal ¶
PeekSubmittedTotal 快速获取我发布的写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListSubmitted, key)。
func (*Client) PeekTeacherTotal ¶
PeekTeacherTotal 快速获取教师写实记录总数。 等价于 PeekCircleTotal(ctx, token, CircleListTeacher, key)。
func (*Client) PeekWithdrawnTotal ¶
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
QuickSubmitRecord 便捷写实提交辅助函数。 自动对日期格式进行自愈规整、回填默认活动字段,并发起提交。
func (*Client) RefreshToken ¶ added in v1.12.0
RefreshToken 主动使用保存的凭证重新登录平台并激活会话,更新本地 Token 与 Cookie。
func (*Client) SetCircleLike ¶
SetCircleLike 点赞或取消点赞写实记录。 GET /api/studentCircleNew/setCircleLikeById?circleId= 服务端自动切换点赞/取消状态。 circleId 为平台 Integer(官方 CircleController.java:236-243),本地前置校验。
func (*Client) SubmitSelfEvaluation ¶
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 ¶
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
TokenExpiresAt 获取当前 Token 的预计过期时间。
func (*Client) TokenRemaining ¶ added in v1.12.0
TokenRemaining 获取当前 Token 的剩余有效时间。
func (*Client) UpdateHonor ¶
UpdateHonor 更新一条荣誉记录。 POST /api/studentMoralEduNew/updateHonor
与 AddHonor 对称:当 payload 含 typeId 且 typeName 为空/缺失时, 自动调用 GetHonorTypeOptions 反查补全 typeName。
func (*Client) UpdateMyInfo ¶
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 ¶
UpdateTypicalCase 更新一条典型案例。 POST /api/studentCircleNew/updateTypicalCase
与 AddTypicalCase 对称:type/role/level 有值且对应 *Name 为空时自动补展示名。 remark/content 长度校验与 Add 同族(198/1500 rune,ErrInvalidPayload)。
func (*Client) UploadFile ¶
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 (*ClientBuilder) Build ¶ added in v1.12.0
func (b *ClientBuilder) Build() (*Client, error)
Build 完成 Client 的实例化(不自动登录)。
func (*ClientBuilder) Connect ¶ added in v1.12.0
func (b *ClientBuilder) Connect(ctx context.Context) (*Client, *types.LoginResponse, error)
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 枚举。
检查优先级(短路):
- context.Canceled → CategoryContextCancel
- context.DeadlineExceeded → CategoryContextTimeout
- url.Error.Timeout() / net.OpError.Timeout() → CategoryNetworkTimeout
- errors.Is(err, ErrBusinessRejected) → CategoryBusinessError
- 其他 → CategoryUnknown
type Option ¶
type Option func(*Client)
Option 是 Client 构造函数的选项函数。
func WithAutoReconnect ¶ added in v1.12.0
WithAutoReconnect 配置是否在遇到 401 Unauthorized 时自动尝试重连续期。
func WithCredentials ¶ added in v1.12.0
WithCredentials 为客户端注入登录凭证,供 Token 过期或 401 时自动重新登录保活使用。
func WithMaxRetries ¶ added in v1.12.0
WithMaxRetries 配置瞬态错误与网络抖动的最大重试次数。 默认对幂等 GET 请求及安全的网络异常允许 1~2 次轻量重试,退避时间 100ms~300ms。 0 表示禁用重试。
func WithOnTokenRefreshed ¶ added in v1.12.0
WithOnTokenRefreshed 注册 Token 刷新成功后的回调函数。
func WithSchoolCache ¶ added in v1.12.0
WithSchoolCache 配置客户端学校信息缓存的 TTL 有效期。 启用缓存后,对同一学号的 GetSchoolID 将直接命中内存缓存,避免重复网络往返。 传入 0 表示使用默认 30 分钟 TTL;传入负数表示禁用学校缓存。
func WithSchoolID ¶ added in v1.12.0
WithSchoolID 设置预设学校 ID(供 Connect 免查校极速直连)。
func WithSubmittedPageSize ¶
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 ¶
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 )
Source Files
¶
- auth.go
- builder.go
- circle.go
- circle_list_type.go
- client.go
- connect.go
- convenience.go
- cookie_sync.go
- error_category.go
- errors.go
- file.go
- honor.go
- image_prep.go
- pagination_bounds.go
- parallel.go
- raw_json.go
- raw_paging.go
- request.go
- school_cache.go
- self_eval.go
- session.go
- session_keepalive.go
- submitted.go
- task.go
- typical_case.go
- user.go
- user_update.go