# 可复用模块：带版本与约束的语义单元
@module UserAuth v2.3 {
  # 输入契约：正式但可读的Schema
  input: {
    username: string(3-20 chars, alphanumeric)
    password: string(min_entropy: 50 bits)
  }
  
  # 行为契约：自然语言+形式化约束的混合
  behavior: {
    1. 校验用户名格式，失败抛 AuthError(code=400)
    2. 用 bcrypt(cost=12) 哈希密码，耗时控制在 300-500ms
    3. 查用户表 (SELECT * FROM users WHERE username = ?)
    4. 比对哈希，失败则记录 audit_log 并抛 AuthError(code=401)
  }
  
  # 非功能约束：可验证的元规则
  constraints: {
    retries: max 5 per IP/hour
    privacy: password 零日志、零追踪
    cost: SQL 查询必须走索引，避免全表扫描
  }
  
  # 测试用例作为一等公民
  test_cases: [
    { input: {u: "alice", p: "weak"}, expect: "entropy_error" }
    { input: {u: "nonexist", p: "Valid123!"}, expect: "user_not_found" }
  ]
}

# 主流程：组合模块，保留高层语义
@workflow CreatePost {
  steps:
    1. exec @UserAuth  # 复用认证模块
    2. authorize(user_id, "post:create")  # 隐式RBAC
    3. validate(input: {title, content}, rules: "non_empty,xss_safe")
    4. transaction {
         INSERT INTO posts ...
         UPDATE users SET post_count++ ...
       }
    5. emit Event("post:created", {post_id, user_id})  # 事件驱动
}

人类：用户注册要验证码防刷
模型 → 生成 PromptIR 草稿：
  @module RateLimit {
    behavior: "短信验证码同一手机号 1次/60s，3次/天"
    constraint: "用 Redis 原子操作实现，防竞争条件"
  }
人类：改成图形验证码，不是短信
模型 → 迭代 PromptIR（diff 视图）

promptir-compile --target=python --optimize=cost CreatePost.promptir
↓
生成生产级 Python 代码（带类型注解、日志、监控埋点）

promptir-compile --target=prddoc CreatePost.promptir
↓
生成 PRD 文档（自动提取业务规则、用例图、数据流）

人类：我要一个电商后台
系统：导入 @EcommerceCore v5.1？它依赖 @Payment/Stripe 和 @Auth/OIDC
人类：支付改成支付宝，加上库存防超卖
系统：生成 diff，修改 @Payment 子模块，新增 @Inventory/Reserve 行为约束
人类：OK，编译成 Go+React，部署到 K8s
系统：编译中... 生成代码、Dockerfile、Helm chart、监控规则、操作手册

// ============================================================
// 模块：用户认证服务
// 版本：2.3.1 | 作者：架构组 | 安全等级：P1
// ============================================================
module UserAuth {
    // 依赖声明（自动注入与版本锁定）
    import Cache from "@infra/redis" v4.1.0
    import Audit from "@compliance/logger" v1.8.0

    // 类型别名：人类可读的类型约束
    type Username = string(length: 3..20, regex: "^[a-zA-Z0-9_]+$")
    type Password = string(minEntropy: 50, disallowCommon: true)
    type UserId = uuid
    
    // 常量与配置（可override）
    const MAX_RETRY = 5
    const LOCKOUT_TIME = duration("1h")

    // ========================================================
    // 函数：验证用户密码
    // 契约：前置、后置、异常
    // ========================================================
    func authenticate(username: Username, password: Password) 
        -> Result<UserId, AuthError>
    {
        // 前置条件：不可变约束，编译时检查
        precondition {
            username != null and password != null
            not isRateLimited(clientIP)  // 隐式注入clientIP
        }

        // 主逻辑：自然语言语句 + 结构化控制流
        step("查询用户记录") {
            user = db.query(
                "SELECT id, password_hash FROM users WHERE username = ?", 
                username
            )
            if user.isEmpty {
                // 统一异常：代码生成时自动包装
                throw AuthError.USER_NOT_FOUND
                    .withLogLevel("WARN")
                    .withMetric("auth.failure.count++")
            }
        }

        step("验证密码强度与哈希") {
            // 内联约束：仅作用于本step
            timing(between: 300ms..500ms)  // 防时序攻击
            hashResult = bcrypt.verify(
                password, 
                user.password_hash, 
                cost: 12
            )
        }

        step("处理认证结果") {
            if hashResult.isValid {
                parallel {
                    Audit.log(
                        event: "user.login.success",
                        userId: user.id,
                        ip: clientIP
                    )
                    Cache.delete(key: "rate_limit:{clientIP}")  // 成功清除限流
                }
                return Success(user.id)
            } else {
                // 异常路径：自动触发审计和限流
                throw AuthError.INVALID_CREDENTIALS
                    .withSideEffect {
                        recordFailedAttempt(username)
                        Audit.log(
                            event: "user.login.failure",
                            userId: user.id,
                            ip: clientIP,
                            reason: "password_mismatch"
                        )
                    }
            }
        }

        // 后置条件：确保资源清理与状态一致性
        postcondition {
            db.connection.isClosed()
            Cache.isReleased()
        }

        // 异常契约：结构化异常处理（类似Java catch）
        handle {
            case AuthError.USER_NOT_FOUND:
                // 欺骗性延迟：防用户名枚举
                sleep(random(200ms..400ms))
                return Failure(AuthError.CREDENTIALS_INVALID)  // 模糊化错误
                
            case AuthError.INVALID_CREDENTIALS:
                if getFailedAttempts(username) >= MAX_RETRY {
                    lockAccount(username, duration: LOCKOUT_TIME)
                }
                return Failure(AuthError.CREDENTIALS_INVALID)
                
            case DatabaseError:
                // 降级策略：熔断
                CircuitBreaker.trip("user_db")
                return Failure(AuthError.SERVICE_UNAVAILABLE)
                
            default:
                Audit.log(event: "auth.unexpected_error", error: error)
                return Failure(AuthError.INTERNAL_ERROR)
        }
    }

    // ========================================================
    // 辅助函数：限流检查（私有）
    // ========================================================
    private func isRateLimited(ip: string) -> bool {
        // 约束驱动实现：模型知道该选Redis令牌桶还是漏桶
        constraint {
            algorithm: "token_bucket",
            capacity: 10,
            refillRate: 1_per_second,
            storage: Cache
        }
        
        // 自然语言逻辑：模型决定具体命令（INCR/EVAL）
        checkRateLimit in Cache for key "rate_limit:{ip}"
        
        return checkRateLimit.isExceeded
    }

    // ========================================================
    // 测试用例：作为函数的一部分，可提取执行
    // ========================================================
    test {
        case "正常登录" {
            given: username="alice", password="Valid123!"
            mock: db.return(user_exists), bcrypt.return(true)
            expect: Success(userId="uuid-alice")
            expect: Audit.log.called(times: 1)
        }
        
        case "密码错误触发限流" {
            given: username="bob", password="WrongPass"
            repeat: 5 times
            expect: Failure(CREDENTIALS_INVALID)
            
            on 6th attempt:
                expect: Failure(ACCOUNT_LOCKED)
                expect: Cache.set(key: "lock:bob", ttl: 1h)
        }
        
        case "数据库宕机触发熔断" {
            mock: db.raise(DatabaseError)
            expect: Failure(SERVICE_UNAVAILABLE)
            expect: CircuitBreaker.trip("user_db")
        }
    }
}

// ============================================================
// 主流程：组合模块，定义编排
// ============================================================
workflow CreateUserPost {
    // 输入DTO：结构化schema，可生成TypeScript/Java类
    input {
        title: string(length: 5..100, required: true)
        content: markdown(maxLength: 10_000)
        tags: array<string>(maxItems: 5)
        draft: boolean(default: false)
    }

    // 步骤编排：显式顺序、并行、Saga事务
    steps {
        step1: authenticate_user {
            // 调用模块函数，自动注入上下文
            authResult = UserAuth.authenticate(
                fromHeader("X-User-Token")
            )
            // 短路失败：authResult必须是Success
            require authResult.isSuccess
            userId = authResult.value
        }

        step2: check_permissions {
            // RBAC检查：自然语言策略
            hasPermission = RBAC.check(
                userId,
                "post:create",
                onResource: input.tags
            )
            require hasPermission else throw ForbiddenError
        }

        step3: validate_content {
            // 并行校验：模型知道如何优化
            parallel {
                spamScore = MLModel.predict("spam_detector", input.content)
                require spamScore < 0.8
                
                toxicity = MLModel.predict("toxicity", input.content)
                require toxicity < 0.5
            }
        }

        step4: save_to_database {
            // Saga事务：成功则commit，失败则compensate
            transaction(type: saga) {
                postId = db.insert("posts", {
                    title: input.title,
                    content: input.content,
                    userId: userId,
                    draft: input.draft
                })
                
                // 补偿动作：生成时自动创建rollback函数
                compensation {
                    db.delete("posts", id: postId)
                    Audit.log(event: "post.create.rollback", postId: postId)
                }
            }
        }

        step5: update_sidebar_cache {
            // 异步副作用：不要求强一致性
            fireAndForget {
                Cache.invalidate(pattern: "sidebar:recent_posts:*")
            }
        }

        step6: notify_followers {
            // 消息队列：模型选择Kafka/RabbitMQ
            emitEvent(
                topic: "social.post_created",
                payload: {
                    postId: postId,
                    authorId: userId,
                    tags: input.tags
                },
                qos: "at_least_once"
            )
        }
    }

    // 输出契约：后处理与格式化
    output {
        status: "created"
        postId: postId
        url: format("/posts/{postId}")
        // 自动处理敏感字段脱敏
        sanitize: ["userId"]
    }

    // 性能与非功能需求：全局约束
    constraints {
        timeout: duration("5s")
        memory: max("256MB")
        cpu: max("100ms")
        retries: count(3, backoff: exponential)
        circuitBreaker: "default"
    }

    // 监控埋点：自动生成Prometheus/Metrics代码
    telemetry {
        metric: "post.create.duration".histogram(buckets: [100ms, 500ms, 1s])
        metric: "post.create.failure".counter
        trace: span("create-post", propagate: true)
    }
}

# 编译为生产级Python
promptir-compile UserAuth.promptir --target=python --output=auth.py
# 生成：带async/await、typing、decorator、prometheus指标的代码

# 编译为Go微服务
promptir-compile UserAuth.promptir --target=go --output=user_service/
# 生成：interface、error wrapping、context超时、otel tracing

# 编译为PRD文档
promptir-compile UserAuth.promptir --target=prddoc --output=auth_prd.md
# 生成：用例图、时序图、边界条件表格、SLA定义

# 编译为测试套件
promptir-compile UserAuth.promptir --target=pytest --output=test_auth.py
# 生成：参数化测试、mock fixture、性能基准测试

func login(...) {
    step { checkRateLimit() }
    step { hashPassword(cost: 10) }
    step { logFailure() }
    timeout: 3s
}

- hashPassword(cost: 10)  [警告：成本过低，建议12+]
+ hashPassword(cost: 12)
+ constraint { algorithm: "bcrypt" }  [明确算法]
- timeout: 3s  [建议分离：操作超时 vs 连接池超时]
+ timeout: 5s
+ dbTimeout: 2s

func login(...) {
    constraint {
        passwordHash: "bcrypt(v12)"
        timingAttack: "constant_time"
    }
    step("验证逻辑") {
        timing(between: 300ms..500ms)
        ...
    }
}

// ============================================================
// 模块：用户认证服务
// 版本：2.3.1 | 作者：架构组 | 安全等级：P1
// ============================================================
模块 UserAuth {
    // 依赖声明（自动注入与版本锁定）
    引入 Cache 从 "@infra/redis" 版本 4.1.0
    引入 Audit 从 "@compliance/logger" 版本 1.8.0

    // 类型别名：人类可读的类型约束
    类型 Username = 字符串(长度: 3..20, 正则: "^[a-zA-Z0-9_]+$")
    类型 Password = 字符串(最小熵: 50, 禁用常见密码: 真)
    类型 UserId = UUID

    // 常量与配置（可覆盖）
    常量 最大重试次数 = 5
    常量 锁定时间 = 时长("1h")

    // ========================================================
    // 函数：验证用户密码
    // 契约：前置、后置、异常
    // ========================================================
    函数 认证(用户名: Username, 密码: Password) 
        -> 结果<UserId, 认证错误>
    {
        // 前置条件：不可变约束，编译时检查
        前置条件 {
            用户名 != 空 且 密码 != 空
            非 是否被限流(客户端IP)  // 隐式注入客户端IP
        }

        // 主逻辑：自然语言语句 + 结构化控制流
        步骤("查询用户记录") {
            用户 = 数据库.查询(
                "SELECT id, password_hash FROM users WHERE username = ?", 
                用户名
            )
            如果 用户.为空 {
                // 统一异常：代码生成时自动包装
                抛出 认证错误.用户未找到
                    .附带日志级别("WARN")
                    .附带指标("auth.failure.count++")
            }
        }

        步骤("验证密码强度与哈希") {
            // 内联约束：仅作用于本步骤
            响应时间(介于: 300毫秒..500毫秒)  // 防时序攻击
            哈希结果 = bcrypt.比对(
                密码, 
                用户.password_hash, 
                成本: 12
            )
        }

        步骤("处理认证结果") {
            如果 哈希结果.有效 {
                并行执行 {
                    Audit.记录(
                        事件: "user.login.success",
                        用户Id: 用户.id,
                        IP: 客户端IP
                    )
                    Cache.删除(键: "rate_limit:{客户端IP}")  // 成功清除限流
                }
                返回 成功(用户.id)
            } 否则 {
                // 异常路径：自动触发审计和限流
                抛出 认证错误.凭证无效
                    .附带副作用 {
                        记录失败尝试(用户名)
                        Audit.记录(
                            事件: "user.login.failure",
                            用户Id: 用户.id,
                            IP: 客户端IP,
                            原因: "password_mismatch"
                        )
                    }
            }
        }

        // 后置条件：确保资源清理与状态一致性
        后置条件 {
            数据库.连接.已关闭()
            Cache.已释放()
        }

        // 异常契约：结构化异常处理（类似Java catch）
        捕获 {
            情况 认证错误.用户未找到:
                // 欺骗性延迟：防用户名枚举
                睡眠(随机(200毫秒..400毫秒))
                返回 失败(认证错误.凭证无效)  // 模糊化错误
                
            情况 认证错误.凭证无效:
                如果 获取失败次数(用户名) >= 最大重试次数 {
                    锁定账户(用户名, 时长: 锁定时间)
                }
                返回 失败(认证错误.凭证无效)
                
            情况 数据库错误:
                // 降级策略：熔断
                熔断器.触发("user_db")
                返回 失败(认证错误.服务不可用)
                
            默认:
                Audit.记录(事件: "auth.unexpected_error", 错误: 错误)
                返回 失败(认证错误.内部错误)
        }
    }

    // ========================================================
    // 辅助函数：限流检查（私有）
    // ========================================================
    私有 函数 是否被限流(IP地址: 字符串) -> 布尔值 {
        // 约束驱动实现：模型知道该选Redis令牌桶还是漏桶
        约束 {
            算法: "token_bucket",
            容量: 10,
            速率: 每秒1个,
            存储: Cache
        }
        
        // 自然语言逻辑：模型决定具体命令（INCR/EVAL）
        检查限流 in Cache 对于 键 "rate_limit:{IP地址}"
        
        返回 检查限流.已超限
    }

    // ========================================================
    // 测试用例：作为函数的一部分，可提取执行
    // ========================================================
    测试 {
        用例 "正常登录" {
            假设: 用户名="alice", 密码="Valid123!"
            模拟: 数据库.返回(用户存在), bcrypt.返回(真)
            期望: 成功(用户Id="uuid-alice")
            期望: Audit.记录.被调用(次数: 1)
        }
        
        用例 "密码错误触发限流" {
            假设: 用户名="bob", 密码="WrongPass"
            重复: 5 次
            期望: 失败(凭证无效)
            
            第6次尝试:
                期望: 失败(账户已锁定)
                期望: Cache.设置(键: "lock:bob", 过期: 1小时)
        }
        
        用例 "数据库宕机触发熔断" {
            模拟: 数据库.抛出(数据库错误)
            期望: 失败(服务不可用)
            期望: 熔断器.触发("user_db")
        }
    }
}

// ============================================================
// 主流程：组合模块，定义编排
// ============================================================
工作流 创建用户文章 {
    // 输入DTO：结构化schema，可生成TypeScript/Java类
    输入 {
        标题: 字符串(长度: 5..100, 必填: 真)
        内容:  Markdown(最大长度: 10_000)
        标签: 数组<字符串>(最大数量: 5)
        草稿: 布尔值(默认: 假)
    }

    // 步骤编排：显式顺序、并行、Saga事务
    步骤们 {
        步骤1: 认证用户 {
            // 调用模块函数，自动注入上下文
            认证结果 = UserAuth.认证(
                从请求头("X-User-Token")
            )
            // 短路失败：认证结果必须是成功
            要求 认证结果.是成功
            用户Id = 认证结果.值
        }

        步骤2: 检查权限 {
            // RBAC检查：自然语言策略
            有权限 = RBAC.检查(
                用户Id,
                "post:create",
                资源: 输入.标签
            )
            要求 有权限 否则 抛出 无权限错误
        }

        步骤3: 校验内容 {
            // 并行校验：模型知道如何优化
            并行 {
                垃圾分 = 机器学习模型.预测("spam_detector", 输入.内容)
                要求 垃圾分 < 0.8
                
                毒性 = 机器学习模型.预测("toxicity", 输入.内容)
                要求 毒性 < 0.5
            }
        }

        步骤4: 保存到数据库 {
            // Saga事务：成功则提交，失败则补偿
            事务(类型: saga) {
                文章Id = 数据库.插入("posts", {
                    标题: 输入.标题,
                    内容: 输入.内容,
                    用户Id: 用户Id,
                    草稿: 输入.草稿
                })
                
                // 补偿动作：生成时自动创建rollback函数
                补偿 {
                    数据库.删除("posts", 编号: 文章Id)
                    Audit.记录(事件: "post.create.rollback", 文章Id: 文章Id)
                }
            }
        }

        步骤5: 更新侧边栏缓存 {
            // 异步副作用：不要求强一致性
            异步执行 {
                Cache.失效(模式: "sidebar:recent_posts:*")
            }
        }

        步骤6: 通知关注者 {
            // 消息队列：模型选择Kafka/RabbitMQ
            发送事件(
                主题: "social.post_created",
                负载: {
                    文章Id: 文章Id,
                    作者Id: 用户Id,
                    标签: 输入.标签
                },
                可靠性: "至少一次"
            )
        }
    }

    // 输出契约：后处理与格式化
    输出 {
        状态: "已创建"
        文章Id: 文章Id
        链接: 格式化("/posts/{文章Id}")
        // 自动处理敏感字段脱敏
        脱敏: ["用户Id"]
    }

    // 性能与非功能需求：全局约束
    约束 {
        超时: 时长("5秒")
        内存: 最大("256MB")
        CPU: 最大("100毫秒")
        重试: 次数(3, 退避: 指数)
        熔断器: "默认"
    }

    // 监控埋点：自动生成Prometheus/Metrics代码
    遥测 {
        指标: "post.create.duration".直方图(桶: [100毫秒, 500毫秒, 1秒])
        指标: "post.create.failure".计数器
        追踪: 跨度("create-post", 传播: 真)
    }
}

步骤("查询用户") {
    用户 = 数据库.查询("SELECT * FROM users WHERE id = ?", 用户Id)
    如果 用户.为空 {
        抛出 错误.用户未找到
    }
}
约束 {
    超时: 100毫秒
    重试: 3次
}

// 自动生成的生产级代码
func (r *userRepo) GetUser(ctx context.Context, userID string) (*User, error) {
    ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
    defer cancel()
    
    var user User
    err := retry.WithAttempts(3, func() error {
        return r.db.QueryRowContext(ctx, 
            "SELECT * FROM users WHERE id = ?", userID).Scan(&user)
    })
    
    if err == sql.ErrNoRows {
        return nil, ErrUserNotFound // 带堆栈追踪
    }
    return &user, err
}

# 自动生成的async函数
@retry(stop=stop_after_attempt(3))
@timeout(0.1)  # 100ms
async def get_user(user_id: str) -> User:
    async with db.acquire() as conn:
        row = await conn.fetchrow(
            "SELECT * FROM users WHERE id = $1", user_id
        )
        if not row:
            raise UserNotFoundError().with_stacktrace()
        return User(**row)

### 3.2 用户查询功能

**业务规则**：
- 若用户ID不存在，系统应抛出"用户未找到"错误
- 操作超时时间：100ms（避免级联延迟）
- 自动重试：最多3次（应对瞬时网络抖动）

**异常处理**：
| 错误类型 | 用户提示 | 监控指标 |
|----------|----------|----------|
| 用户未找到 | "账号不存在" | `user.not_found` +1 |
| 超时 | "服务繁忙" | `db.timeout` +1 |

;; ============================================================
;; 模块：用户认证服务
;; 版本：2.3.1 | 作者：架构组 | 安全等级：P1
;; ============================================================
(module UserAuth
  ;; ──────────────────────────────────────────────────────────
  ;; 依赖声明（自动注入与版本锁定）
  ;; ──────────────────────────────────────────────────────────
  (import Cache "@infra/redis" :version "4.1.0")
  (import Audit "@compliance/logger" :version "1.8.0")

  ;; ──────────────────────────────────────────────────────────
  ;; 类型别名：约束即类型，类型即文档
  ;; ──────────────────────────────────────────────────────────
  (type Username (string :length (3 20) :regex "^[a-zA-Z0-9_]+$"))
  (type Password (string :min-entropy 50 :disallow-common-patterns? #t))
  (type UserId uuid)

  ;; ──────────────────────────────────────────────────────────
  ;; 配置常量：可覆盖，可审计
  ;; ──────────────────────────────────────────────────────────
  (define MAX-RETRY 5)
  (define LOCKOUT-TIME (duration "1h"))

  ;; ──────────────────────────────────────────────────────────
  ;; 函数：认证主流程
  ;; 契约：前置条件 → 步骤 → 后置条件 → 异常捕获
  ;; ──────────────────────────────────────────────────────────
  (func authenticate ((username Username) (password Password))
    -> (Result UserId AuthError)
    
    ;; 前置条件：编译时验证的不可变断言
    (precondition
      (and (not (null? username))
           (not (null? password))
           (not (is-rate-limited? client-ip))))  ; 隐式注入client-ip

    ;; 主体：步骤列表，顺序执行，可插拔
    (steps
      ;; ─────────────────────────────────────────────────────
      (step "查询用户记录"
        (let ((user (db:query
                      "SELECT id, password_hash FROM users WHERE username = ?"
                      username)))
          (when (empty? user)
            (throw (AuthError 'user-not-found)
                   :log-level "WARN"
                   :metric "auth.failure.count++"))))

      ;; ─────────────────────────────────────────────────────
      (step "验证密码哈希"
        (constraint :timing (between 300ms 500ms))  ; 防时序攻击
        (let ((hash-result (bcrypt:verify password
                                           user.password_hash
                                           :cost 12)))
          hash-result))

      ;; ─────────────────────────────────────────────────────
      (step "处理认证结果"
        (if (valid? hash-result)
          (progn  ; 成功分支：并行审计与清理
            (parallel
              (Audit:log :event "user.login.success"
                         :user-id user.id
                         :ip client-ip)
              (Cache:delete :key (format "rate_limit:{}" client-ip)))
            (return (Success user.id)))
          
          ;; 失败分支：副作用显式声明
          (throw (AuthError 'invalid-credentials)
                 :side-effect
                 (lambda ()
                   (record-failed-attempt username)
                   (Audit:log :event "user.login.failure"
                              :user-id user.id
                              :ip client-ip
                              :reason "password_mismatch"))))))

    ;; 后置条件：资源清理保证
    (postcondition
      (and (db:connection-closed?)
           (Cache:released?)))

    ;; 异常契约：结构化模式匹配
    (handle
      ((AuthError 'user-not-found)
       ;; 欺骗性延迟：防用户名枚举攻击
       (sleep (random 200ms 400ms))
       (return (Failure (AuthError 'credentials-invalid))))
      
      ((AuthError 'invalid-credentials)
       (when (>= (get-failed-attempts username) MAX-RETRY)
         (lock-account username :duration LOCKOUT-TIME))
       (return (Failure (AuthError 'credentials-invalid))))
      
      (DatabaseError
       ;; 熔断降级
       (CircuitBreaker:trip "user_db")
       (return (Failure (AuthError 'service-unavailable))))
      
      (_  ; 默认兜底
       (Audit:log :event "auth.unexpected_error" :error error)
       (return (Failure (AuthError 'internal-error))))))

  ;; ──────────────────────────────────────────────────────────
  ;; 私有辅助：限流检查
  ;; ──────────────────────────────────────────────────────────
  (func (private) is-rate-limited? ((ip string)) -> bool
    ;; 约束驱动：模型自动选择最优算法
    (constraint :algorithm 'token-bucket
                :capacity 10
                :refill-rate (per-second 1)
                :storage Cache)
    
    ;; 自然语言与形式化混合
    (let ((check-result (in Cache check-rate-limit :key (format "rate_limit:{}" ip))))
      (exceeded? check-result)))

  ;; ──────────────────────────────────────────────────────────
  ;; 测试用例：可执行、可提取、即文档
  ;; ──────────────────────────────────────────────────────────
  (test-suite authenticate
    (test-case "正常登录"
      :given (username "alice" password "Valid123!")
      :mock ((db:query (return user-exists))
             (bcrypt:verify (return #t)))
      :expect ((Success user-id "uuid-alice")
               (Audit:log called? #t :times 1)))
    
    (test-case "密码错误触发限流"
      :given (username "bob" password "WrongPass")
      :repeat 5
      :expect (Failure 'credentials-invalid)
      
      :on-6th-attempt
      :expect ((Failure 'account-locked)
               (Cache:set key "lock:bob" ttl (duration "1h"))))
    
    (test-case "数据库宕机触发熔断"
      :mock ((db:query (raise DatabaseError)))
      :expect ((Failure 'service-unavailable)
               (CircuitBreaker:trip "user_db")))))

;; ============================================================
;; 工作流：创建用户文章（组合模块）
;; ============================================================
(workflow CreateUserPost
  ;; ──────────────────────────────────────────────────────────
  ;; 输入Schema：自文档化，可生成DTO
  ;; ──────────────────────────────────────────────────────────
  (input
    (title (string :length (5 100) :required? #t))
    (content (markdown :max-length 10000))
    (tags (array string :max-items 5))
    (draft (bool :default #f)))

  ;; ──────────────────────────────────────────────────────────
  ;; 步骤编排：显式顺序/并行/Saga
  ;; ──────────────────────────────────────────────────────────
  (steps
    (step "认证用户"
      (let ((auth-result (UserAuth:authenticate (from-header "X-User-Token"))))
        (require (success? auth-result))
        (define user-id (value auth-result))))

    (step "检查权限"
      (let ((has-perm? (RBAC:check user-id "post:create" :resource tags)))
        (require has-perm? else (throw ForbiddenError))))

    (step "校验内容"
      (parallel
        (let ((spam-score (MLModel:predict "spam_detector" content)))
          (require (< spam-score 0.8)))
        
        (let ((toxicity (MLModel:predict "toxicity" content)))
          (require (< toxicity 0.5)))))

    (step "保存到数据库"
      (transaction :type 'saga
        (let ((post-id (db:insert "posts"
                                   (alist title content user-id draft))))
          (compensation  ; 自动回滚逻辑
            (db:delete "posts" :id post-id)
            (Audit:log :event "post.create.rollback" :post-id post-id)))))

    (step "更新缓存"
      (fire-and-forget
        (Cache:invalidate :pattern "sidebar:recent_posts:*")))

    (step "通知关注者"
      (emit-event :topic "social.post_created"
                  :payload (alist post-id user-id tags)
                  :qos "at_least_once")))

  ;; ──────────────────────────────────────────────────────────
  ;; 输出格式化
  ;; ──────────────────────────────────────────────────────────
  (output
    (status "created")
    (post-id post-id)
    (url (format "/posts/{}" post-id))
    (sanitize '(user-id)))  ; 自动脱敏

  ;; ──────────────────────────────────────────────────────────
  ;; 全局约束：性能、资源、容错
  ;; ──────────────────────────────────────────────────────────
  (constraints
    :timeout (duration "5s")
    :memory (max "256MB")
    :cpu (max "100ms")
    :retries (count 3 :backoff 'exponential)
    :circuit-breaker "default")

  ;; ──────────────────────────────────────────────────────────
  ;; 遥测埋点：自动生成监控代码
  ;; ──────────────────────────────────────────────────────────
  (telemetry
    (metric "post.create.duration" 
            (histogram :buckets '(100ms 500ms 1s)))
    (metric "post.create.failure" counter)
    (trace "create-post" :propagate? #t)))

;; 模型生成的diff
(module UserAuth
  (import Cache ...)
+ (import Captcha "@security/captcha" :version "3.0.0")  ; 自动添加依赖
  
  (func authenticate ...
    (steps
+     (step "验证图形验证码"  ; 插入新步骤
+       (let ((captcha-token (from-header "X-Captcha-Token")))
+         (require (Captcha:verify captcha-token :type "slide-puzzle")
+                  else (throw (AuthError 'captcha-invalid)))))
      
      (step "查询用户记录" ...))))

;; 人类修改：调整验证码类型，加注释
(step "验证图形验证码"
  ;; 产品要求：使用reCAPTCHA v3，非侵入式
  (constraint :provider "recaptcha-v3" :threshold 0.7)
  (let ((token (from-header "X-Recaptcha-Token")))
    (require (Captcha:verify token :action "login")
             else (throw (AuthError 'captcha-failed)))))

promptir-compile --target=python auth.promptir
;; 生成：自动插入验证码SDK调用、异步校验、重试逻辑

> (load "UserAuth.promptir")
> (test-run 'UserAuth:authenticate 
    :mock '((db:query . ,(lambda () fake-user))))
;; 立即在REPL中测试语义，无需生成代码

;; ============================================================
;; 模块：用户认证服务
;; ── 版本 2.3.1 | 安全等级 P1 | 可观测性：高
;; ============================================================
(module 用户认证
  ;; ──────────────────────────────────────────────────────────
  ;; 依赖：效应系统自动注入版本与配置
  ;; ──────────────────────────────────────────────────────────
  (import 缓存 :from "@infra/redis" :version "4.1")
  (import 审计 :from "@compliance/audit" :version "1.8")

  ;; ──────────────────────────────────────────────────────────
  ;; 类型约束：静态分析与动态校验统一
  ;; ──────────────────────────────────────────────────────────
  (define-type 用户名 
    (符合正则 "^[a-zA-Z0-9_]+$" 且 长度在 3 到 20 之间))
  
  (define-type 密码
    (熵值大于 50 且 不在常见密码列表中))

  ;; ──────────────────────────────────────────────────────────
  ;; 纯函数：无副作用，可缓存，可并发
  ;; ──────────────────────────────────────────────────────────
  (defun 校验凭证格式 (用户名 密码) -> (要么 真 格式错误)
    "验证输入是否满足基本格式要求"
    (匹配 (列表 用户名 密码)
      [(用户名 为空) (格式错误 "用户名不能为空")]
      [(密码 长度小于 6) (格式错误 "密码太短")]
      [_ (成功 真)]))  ; 通配符，返回成功

  ;; ──────────────────────────────────────────────────────────
  ;; 不纯函数：显式声明效应
  ;; ──────────────────────────────────────────────────────────
  (defun 查询用户! (用户名) -> (可选 用户记录)
    "带缓存的用户查询，效应：数据库读取 + 缓存写入"
    (效应
      (数据库 查询)
      (缓存 读取/写入)
      (审计 读操作日志))
    
    (let*  ; 按顺序绑定，每个绑定可见后续
          [(缓存键 (字符串拼接 "user:" 用户名))
           (缓存结果 (缓存.获取 缓存键))]
      (如果 (存在? 缓存结果)
        (成功 缓存结果)  ; 缓存命中
        (let [(数据库结果 (数据库.执行 "SELECT * FROM users WHERE username = ?" 用户名))]
          (匹配 数据库结果
            [(为空) (返回 无)]  ; 用户不存在
            [用户 (do
                    (缓存.设置 缓存键 用户 :过期 5分钟)
                    (成功 用户))])))))

  ;; ──────────────────────────────────────────────────────────
  ;; 高阶函数：接收验证策略作为参数
  ;; ──────────────────────────────────────────────────────────
  (defun 重试验证! (验证函数 最大次数) -> (函数)
    "返回一个带重试逻辑的新函数，效应：副作用累积"
    (lambda (输入)
      (循环 ((剩余次数 最大次数) (上次错误 无))
        (如果 (<= 剩余次数 0)
          (失败 上次错误)  ; 耗尽次数，返回最后的错误
          
          (匹配 (验证函数 输入)
            [(成功 结果) (成功 结果)]
            [(失败 原因) 
             (审计.记录 "验证失败" :原因 原因 :剩余次数 剩余次数)
             (继续 (- 剩余次数 1) 原因)])))))  ; 递归重试

  ;; ──────────────────────────────────────────────────────────
  ;; 主函数：组合子模式，声明式流程
  ;; ──────────────────────────────────────────────────────────
  (defun 认证! (用户名 密码) -> (要么 令牌 认证错误)
    "完整的认证流程，效应：读数据库、写缓存、记审计、发指标"
    (效应
      (数据库 读)
      (缓存 读/写/删除)
      (审计 写)
      (监控 指标上报))
    
    (管道
      ;; 阶段1：格式校验（纯函数，可短路）
      (校验凭证格式 用户名 密码)
      
      ;; 阶段2：限流检查（不纯，可能抛出异常）
      (λ (中间结果)
        (如果 (被限流? 客户端IP)
          (认证错误 "请求过于频繁")
          (成功 中间结果)))
      
      ;; 阶段3：用户查询（带缓存）
      (λ (_) (查询用户! 用户名))
      
      ;; 阶段4：密码比对（固定时间算法）
      (λ (用户)
        (匹配 (密码.固定时间比对 密码 用户.password_hash)
          [真 (成功 用户)]
          [假 (认证错误 "凭证无效")]))
      
      ;; 阶段5：成功后处理（并行效应）
      (λ (用户)
        (并发执行
          (审计.记录 "登录成功" :用户ID 用户.id)
          (监控.递增 "auth.success")
          (缓存.删除 (字符串拼接 "rate_limit:" 客户端IP)))
        (成功 (令牌.生成 用户.id :过期时间 "24h")))))
  
  ;; ──────────────────────────────────────────────────────────
  ;; 辅助函数：限流判定
  ;; ──────────────────────────────────────────────────────────
  (defun 被限流? (IP地址) -> 布尔值
    "检查IP是否超过请求阈值，效应：缓存读取"
    (效应 (缓存 读))
    
    (let [(次数 (缓存.自增 (字符串拼接 "rate_limit:" IP地址) :过期 1小时))]
      (> 次数 10)))  ; 阈值配置可外部注入

  ;; ──────────────────────────────────────────────────────────
  ;; 测试契约：测试即函数式规约
  ;; ──────────────────────────────────────────────────────────
  (defproperty 认证幂等性
    "相同凭证多次认证应返回相同令牌（缓存一致）"
    ;; 属性：纯函数行为的声明
    (对所有 (用户名 密码)
      (匹配 (列表 (认证! 用户名 密码) (认证! 用户名 密码))
        [(成功 令牌1) (成功 令牌2)] (= 令牌1 令牌2)]
        [(失败 错误1) (失败 错误2)] (= 错误1 错误2)])))

  (deftest 认证测试套件
    (测试用例 "正常登录"
      :前提 (模拟 数据库) :返回 测试用户
      :动作 (认证! "alice" "正确的密码")
      :期望 (成功 令牌)
      :并确保 (审计.记录已被调用 :事件 "登录成功"))
    
    (测试用例 "密码错误触发限流"
      :动作 (重复 5 (认证! "bob" "错误密码"))
      :期望 (列表 (全部 失败) (理由 "凭证无效"))
      :副作用 (监控.指标 "auth.failure" 等于 5))
    
    (测试用例 "第六次登录应锁定账户"
      :前提 (模拟 缓存.获取 "rate_limit:bob" :返回 6)
      :动作 (认证! "bob" "任意密码")
      :期望 (失败 (认证错误 "请求过于频繁")))))

;; ============================================================
;; 工作流：创建文章（组合多个效应函数）
;; ── 展示函数式编排：Monad风格或Effect Row
;; ============================================================
(workflow 创建文章
  ;; 输入Schema
  (输入 (标题 字符串 长度5到100 必填)
        (内容 Markdown 最大10000)
        (标签 列表<字符串> 最多5个)
        (草稿? 布尔 默认#f))

  ;; 环境读取：依赖注入的函数式风格
  (环境 (当前用户 (从请求头 "X-User-Token"))
        (客户端IP (从上下文 "client-ip")))

  ;; 主流程：Kleisli组合（伪造货→函数式效应流）
  (流程 (组合
         认证用户!          ; Either 令牌 错误
         检查权限!          ; 需要令牌，返回是否有权限
         校验内容!          ; 需要内容和权限，返回校验结果
         保存数据库!        ; Saga事务，返回文章ID
         发送通知!))        ; 副作用，返回空

  ;; 错误处理：函数式的Either模式匹配
  (错误处理
    (左边 错误
      (匹配 错误
        [(权限不足) (返回 403 :消息 "您无法在此分类下发布")]
        [(内容违规 原因) (返回 400 :消息 原因)]
        [其他 (返回 500 :消息 "系统繁忙")]))
    
    (右边 结果
      (返回 成功 :文章ID 结果.ID :链接 (路由.生成 "/posts/{}" 结果.ID))))

  ;; 遥测：纯函数式追踪
  (遥测 (让* [(开始时间 (当前时间))]
          (监控.记录耗时 "workflow.create_post" (- (当前时间) 开始时间))
          (追踪.结束跨度 "create-post"))))

;; diff：在步骤2插入新验证
(流程 (组合
       校验凭证格式
+      (λ (_)
+        (require (reCAPTCHA.验证 (从请求头 "X-Recaptcha-Token") :动作 "login")
+                 :阈值 0.7
+                 :失败时 (认证错误 "人机验证失败")))
       查询用户!
       比对密码!))

(reCAPTCHA.验证 ... 
+ :阈值 0.6
+ :失败时 (do (审计.记录 "reCAPTCHA失败" :分数 分数)
+             (认证错误 "人机验证失败")))

promptir-compile auth.promptir --target=python
;; 生成：自动插入recaptcha SDK调用、异步验证、指标上报