From 799216b184b897994b14f74082be05b4493bb283 Mon Sep 17 00:00:00 2001
From: yuetsh <517252939@qq.com>
Date: Sun, 14 Jun 2026 06:40:04 -0600
Subject: [PATCH] docs: add design spec for code formatting feature

---
 .../2026-06-14-code-formatting-design.md      | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-14-code-formatting-design.md

diff --git a/docs/superpowers/specs/2026-06-14-code-formatting-design.md b/docs/superpowers/specs/2026-06-14-code-formatting-design.md
new file mode 100644
index 0000000..98c9550
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-14-code-formatting-design.md
@@ -0,0 +1,52 @@
+# 代码格式化（整理代码）功能设计
+
+## 背景
+
+`codenext` 编辑器支持 Python（含海龟绘图）、C、C++ 四种语言，目前没有一键格式化代码的功能。需要类似 Prettier 的"整理代码"按钮。
+
+## 方案
+
+后端 `codeapinew` 新增 `POST /format` 接口，按语言调用对应的格式化工具；前端在编辑器工具栏新增"整理代码"按钮调用该接口并替换编辑器内容。
+
+### 后端
+
+**Schema**（`schemas.py`）：
+
+```python
+class FormatRequest(BaseModel):
+    code: str
+    language: str  # python | turtle | c | cpp
+
+class FormatResponse(BaseModel):
+    code: str
+```
+
+**接口**（`main.py`）：
+
+- `POST /format`
+- `language` 为 `python` 或 `turtle` → 调用 `ruff format -`（通过 stdin/stdout 管道）
+- `language` 为 `c` 或 `cpp` → 调用 `clang-format`，使用自定义 style：
+  `-style="{BasedOnStyle: LLVM, IndentWidth: 4, BreakBeforeBraces: Allman}"`
+  （贴近现有模板的 4 空格缩进 + Allman 大括号风格）
+- 用 `subprocess.run`，设置超时（5 秒）
+- 工具返回非零退出码（语法错误等）时，返回 HTTP 400，附带 stderr 作为错误信息；原代码不受影响
+
+### 依赖
+
+- `pyproject.toml` 增加 `ruff` 依赖（同步更新 `requirements.txt`）
+- `Dockerfile` 的 `apt-get install` 增加 `clang-format`
+
+### 前端（`codenext`）
+
+- `src/api.ts` 新增 `formatCode(code: string, language: LANGUAGE)`，调用 `POST /format`
+- `src/composables/code.ts` 新增 `format()`：调用接口成功后替换 `code.value`（自动触发已有的 localStorage 缓存逻辑）；失败时抛出错误供调用方提示
+- `src/desktop/CodeSection.vue` 的 `#actions` 插槽中增加"整理代码"按钮（位于"复制"和"清空"之间），点击调用 `format()`，失败时通过 `useMessage().error(...)` 提示错误信息
+
+## 错误处理
+
+- 网络/接口错误或格式化失败：弹出错误提示，编辑器内容不变
+- 超时：视为格式化失败，同样提示并保持原内容
+
+## 范围
+
+仅涉及 `codeapinew`（新增 `/format` 接口及依赖）和 `codenext`（新增按钮与调用逻辑）。移动端 `CodeEditor` 未使用 `label`，不渲染 `#actions` 插槽，与现有"调试"按钮一致，移动端不加入该功能。