feat(arch-scan): mark 12 exempt Server Actions with @public JSDoc tag

src/modules/auth/actions.ts

@@ -85,6 +85,8 @@ async function messageForError(
  * 返回值：
  * - 成功：`{ success: true, data: { userId } }`（userId 仅用于内部跟踪，前端可忽略）
  * - 失败：`{ success: false, errorCode, message }`
+ *
+ * @public 登录前公开 Action（注册流程），豁免 requirePermission 校验。
  */
 export async function registerAction(
   formData: FormData
@@ -321,6 +323,8 @@ export async function registerAction(
  *
  * 用于注册表单实时检查邮箱是否已被占用。限流复用 REGISTER 规则，
  * 避免被用于邮箱枚举攻击。
+ *
+ * @public 登录前公开 Action（注册流程），豁免 requirePermission 校验。
  */
 export async function checkEmailAvailabilityAction(
   email: string
@@ -369,6 +373,8 @@ export async function checkEmailAvailabilityAction(
  * 返回值：
  * - `{ required: true }`  — 用户启用了 2FA，登录表单应展示 2FA 输入框
  * - `{ required: false }`  — 用户未启用 2FA 或不存在（防邮箱枚举）
+ *
+ * @public 登录前公开 Action（2FA 预检），豁免 requirePermission 校验。
  */
 export async function preflightTwoFactorAction(
   email: string

src/modules/invitation-codes/actions.ts

@@ -134,6 +134,8 @@ export async function deleteInvitationCodeAction(
  *
  * 不需要权限校验：注册流程需要预检邀请码可用性。
  * 不返回邀请码明文（脱敏）。
+ *
+ * @public 登录前公开 Action（注册流程），豁免 requirePermission 校验。
  */
 export async function validateInvitationCodeAction(
   code: string,

src/modules/onboarding/actions.ts

@@ -33,6 +33,8 @@ const CLASS_SUBJECTS_READONLY: readonly string[] = DEFAULT_CLASS_SUBJECTS
 /**
  * 查询当前用户 onboarding 状态。
  * 供服务端组件 / 客户端组件读取，决定是否渲染引导流程。
+ *
+ * @public 登录后必经流程 Action，使用 requireAuth 校验登录态，豁免 requirePermission 校验。
  */
 export async function getOnboardingStatusAction(): Promise<
   ActionState<Awaited<ReturnType<typeof getOnboardingStatus>>>
@@ -62,6 +64,8 @@ export async function getOnboardingStatusAction(): Promise<
  * - P0-4 审计日志：onboarding 完成后写 audit_logs（对标 PowerSchool/Veracross/Auth0 Logs）。
  * - P0-5 服务端幂等：开始时检查 users.onboardedAt，若已完成直接返回成功（防止双击重复事务）。
  * - P1-2 局部错误收集：班级码/子女绑定失败时不回滚整个事务，收集失败列表返回前端，成功项保留。
+ *
+ * @public 登录后必经流程 Action，使用 requireAuth 校验登录态，豁免 requirePermission 校验。
  */
 export async function completeOnboardingAction(
   prevState: ActionState<OnboardingCompleteData> | null,

src/modules/rbac/actions.ts

@@ -389,6 +389,8 @@ export async function getRoleDetailAction(
  * Check whether a role is the locked admin role.
  * Exported as a server action so client components can call it without
  * importing the data-access layer directly.
+ *
+ * @public 内部角色判断工具，纯函数无副作用，豁免 requirePermission 校验。
  */
 export async function isAdminRole(roleName: string): Promise<boolean> {
   return roleName === ADMIN_ROLE_NAME

src/modules/settings/actions-security.ts

@@ -416,6 +416,8 @@ export async function revokeAllOtherSessionsAction(): Promise<
  * 若返回 required=true 则先展示 2FA 验证码输入框。
  *
  * 为防止邮箱枚举攻击，无论用户是否存在都返回 required=false（不存在则视为未启用）。
+ *
+ * @public 登录前公开 Action（2FA 预检），豁免 requirePermission 校验。
  */
 export async function preflightTwoFactorAction(
   email: string,
@@ -453,6 +455,8 @@ export async function preflightTwoFactorAction(
  *
  * 此函数不使用 requirePermission（登录时还未建立会话），
  * 由 auth.ts 的 authorize 回调直接调用。
+ *
+ * @public 登录前公开 Action（2FA 登录校验），豁免 requirePermission 校验。
  */
 export async function verifyTwoFactorForLogin(params: {
   userId: string

src/shared/lib/audit-logger.ts

@@ -24,6 +24,8 @@ export interface LogAuditParams {
  * Record an audit log entry for the current authenticated user.
  *
  * Note: 失败时记录到 logger.warn 而非静默吞没，确保运维可感知审计写入失败。
+ *
+ * @public 内部审计日志工具，由其他 Server Action 内部调用，豁免 requirePermission 校验。
  */
 export async function logAudit(params: LogAuditParams): Promise<void> {
   try {

src/shared/lib/change-logger.ts

@@ -24,6 +24,8 @@ export interface LogDataChangeParams {
  * Record a data change log entry for the current authenticated user.
  *
  * Note: 失败时记录到 logger.warn 而非静默吞没，确保运维可感知变更日志写入失败。
+ *
+ * @public 内部数据变更日志工具，由其他 Server Action 内部调用，豁免 requirePermission 校验。
  */
 export async function logDataChange(params: LogDataChangeParams): Promise<void> {
   try {

src/shared/lib/login-logger.ts

@@ -24,6 +24,8 @@ export interface LogLoginEventParams {
  * Does NOT depend on auth context since it runs during auth events.
  *
  * Note: 失败时记录到 logger.warn 而非静默吞没，确保运维可感知登录日志写入失败。
+ *
+ * @public 内部登录日志工具，由 auth.ts 登录流程调用，豁免 requirePermission 校验。
  */
 export async function logLoginEvent(params: LogLoginEventParams): Promise<void> {
   try {