# RooCode Spec v1
version: 1
project:
  name: your-repo
  shell:
    type: powershell
    flags: "-NoLogo -NoProfile -ExecutionPolicy Bypass"
  os: windows
  line_endings: crlf
  encoding: utf-8

objectives:
  - "仅修改与当前任务直接相关的代码；非相关文件保持不变。"
  - "公共模块或共享代码修改前必须完成影响评估并获得批准。"
  - "需求不清晰或存在冲突时应立即暂停修改，提出问题并等待确认。"
  - "代码命名必须与数据库字段一致，不得随意重命名或私自创造字段名。"
  - "遵守统一代码规范与格式要求。"

# —— 文件范围控制 ————————————————————————————————————————————————
scope:
  blocked_paths:            # 禁止修改的文件或目录（根据项目实际补充）

  # 仅定义“禁止修改”范围，其他文件默认可修改
  # 一旦检测到修改这些路径，将强制中止执行并要求说明理由

# —— 询问/暂停策略 ————————————————————————————————————————————————
ask_policy:
  must_ask_when:
    - "需求描述不完整、目标不明确或与当前任务冲突"
    - "涉及公共模块、接口、数据库结构、跨服务依赖"
    - "修改内容可能引发大范围影响或兼容性问题"
    - "测试覆盖不全或存在潜在回归风险"
  stop_and_wait_for_confirmation: true
  question_template: |
    **不清楚点/风险：**
    1. …
    2. …
    **建议方案：**
    - A: …
    - B: …
    **请求确认：**
    请确认后继续修改。

# —— 公共代码改动与影响评估 ————————————————————————————————
public_code:
  globs:
    - "common/**"
    - "packages/shared/**"
    - "libs/**"
  require_impact_assessment: true
  impact_assessment_file: ".roocode/impact_assessment.md"
  impact_assessment_must_include:
    - "变更目的与动机"
    - "受影响模块与兼容性评估"
    - "数据迁移或回滚方案"
    - "测试验证计划"
    - "风险与缓解措施"

# —— 命名与数据库一致性 ————————————————————————————————————————————
naming_conventions:
  db_schema_source_of_truth:
    - "docs/db/schema.sql"
    - "migrations/**"
  rules:
    - "字段命名以数据库定义为基准。"
    - "如需 camelCase 映射，必须一一对应且注明。"
    - "新增字段前必须在数据库中定义并确认默认值。"
    - "禁止删除或重命名字段而无迁移方案。"-+

# —— 文本与文件格式规范（新增部分） ————————————————————————————————
text_format:
  encoding:
    required: "UTF-8 (无 BOM)"
    description: |
      所有代码文件必须使用 **UTF-8 无 BOM** 编码。
      不允许 UTF-16、GBK、ANSI、或 UTF-8 with BOM。
      若 IDE 或 AI 工具自动生成文件，应强制转换为 UTF-8 无 BOM。
      AI 编辑器请严格遵守此格式，不得自动更改文件编码。
  line_endings:
    required: "CRLF (Windows)"
    description: |
      所有文本文件换行符必须为 CRLF (`\r\n`)。
      禁止混用 LF 与 CRLF；避免提交时触发大面积 diff。
      若检测到混用换行符，应自动修复为 CRLF。
  indentation:
    style: "spaces"
    size: 2
    description: |
      统一使用空格缩进，禁止使用 Tab。
      YAML / JSON / JS / TS / Java / XML / HTML 等文件均保持 2 个空格缩进。
  trailing_spaces:
    remove: true
    description: "提交前自动移除行尾多余空格。"
  final_newline:
    ensure: true
    description: "每个文件末尾必须保留一个空行（单个换行符）。"
  ai_editing_guidelines:
    - "AI 生成或修改文件时必须保留原有编码、缩进和换行风格。"
    - "AI 不得自动转换为 LF 或添加 BOM。"
    - "AI 不得在无内容变化时重写整个文件或格式化不相关区域。"
    - "若文件格式未知，应先读取并检测现有编码与缩进再修改。"
    - "禁止出现乱码、双字节符号或混用全角/半角标点。"
  comment_style:
    preferred:
      - "//"       # Java, JS, TS, Go
      - "#"        # YAML, Python, Shell
      - "<!-- -->" # XML, HTML

# —— 代码风格与校验 ————————————————————————————————————————————————
code_style:
  formatters:
    - "Java: Spotless / GoogleJavaFormat"
    - "TS/JS: Prettier / ESLint"
  rules_of_thumb:
    - "严格类型检查"
    - "公共接口必须带注释"
    - "新增逻辑必须有测试覆盖"
    - "提交前应通过 lint 与测试"

# —— 预检查命令（Windows PowerShell 兼容） ————————————————————————
checks:
  pre_commit:
    - name: "Java Build & Test"
      run: |
        if (Test-Path ".\mvnw.cmd") { .\mvnw.cmd -q test } `
        elseif (Test-Path ".\gradlew.bat") { .\gradlew.bat test } `
        elseif (Get-Command mvn -ErrorAction SilentlyContinue) { mvn -q test } `
        else { Write-Host "No Java build tool found." }

    - name: "Node Lint & Test"
      run: |
        if (Test-Path ".\package.json") {
          npm ci
          npm run -s lint
          npm test --silent
        }

# —— 危险操作拦截 ————————————————————————————————————————————————
dangerous_operations:
  block_without_explicit_approval:
    - "跨模块重命名或重构"
    - "依赖大版本升级"
    - "数据库结构变更（新增/删除/重命名表或字段）"
    - "公共 API 或 DTO 的破坏性修改"
  require_ask_policy: true

# —— 提交与说明规范 ————————————————————————————————————————————————
commit_policy:
  single_purpose_commits: true
  message_template: |
    <type>(<scope>): <subject>

    WHY:
    - 变更目的 …
    WHAT:
    - 修改内容 …
    TEST:
    - 测试说明 …
    RISK:
    - 潜在风险 …
  require:
    - "影响评估链接（如涉及公共模块）"
    - "任务编号或需求 ID"
    - "测试报告摘要"

# —— 最终保护措施 ————————————————————————————————————————————————
guardrails:
  fail_on_blocked_path_change: true
  fail_on_public_code_change_without_assessment: true
  deny_unapproved_mass_changes: true