feat(export): 新增样式管理与基于 JSON 的文档样式系统

- 从可配置 JSON 路径加载样式文件（default_style_file 配置项）
- 实现样式映射与查找函数，支持按样式 ID 和名称双向检索
- 在导出请求/响应 Schema 中新增 style_id 字段，支持样式选择
- 将 JSON 中的自定义样式注入 Word 文档样式元素（upsert 语义）
- 实现 JSON 到 lxml 元素的反向转换，用于样式定义重建
- 实现 Markdown 到样式化文档的转换，支持标题与内联格式
- 支持特殊字符处理与 Unicode 全角/半角规范化
- 文档生成时自动处理文件命名与临时文件管理
- 创建 tmp 目录并提供默认样式模板（default.json）及示例输出
- 更新后端 API 文档，补充导出接口规范
- 阶段 0：后端固定使用默认样式；阶段 1 将通过 style_id 支持用户上传样式

app/api/v1/export.py

@@ -41,12 +41,14 @@ async def export_document(body: ExportDocRequest) -> dict:
     result = await export_doc(
         file_name=body.file_name,
         content=body.content,
+        style_id=body.style_id,
     )
 
     resp = ExportDocResponse(
         download_url=result["download_url"],
         file_name=result["file_name"],
         expires_at=result["expires_at"],
+        style_id=result["style_id"],
     )
     return _ok(resp.model_dump(by_alias=True))
 

app/config.py

@@ -14,6 +14,9 @@ class Settings(BaseSettings):
     # 服务对外访问地址（生成下载链接用）
     base_url: str = "http://192.168.0.200:8000"
 
+    # 默认样式文件路径（阶段 0 固定使用；阶段 1 作为未指定 styleId 时的兜底）
+    default_style_file: str = "./tmp/default.json"
+
     class Config:
         env_file = ".env"
         env_file_encoding = "utf-8"

app/schemas/export.py

@@ -8,6 +8,8 @@ class ExportDocRequest(BaseModel):
     format: Literal["doc"] = Field(..., description="阶段 0 固定为 doc")
     content: str = Field(..., description="文档当前内容（Markdown）")
     document_id: Optional[str] = Field(None, alias="documentId", description="关联文档 ID，传入时同步更新草稿")
+    # 阶段 0 暂不生效，后端固定使用 default.json；阶段 1 起传入有效 ID 则使用用户上传的样式
+    style_id: Optional[str] = Field(None, alias="styleId", description="样式 ID；不传时使用默认样式")
 
     model_config = {"populate_by_name": True}
 
@@ -16,5 +18,6 @@ class ExportDocResponse(BaseModel):
     download_url: str = Field(..., serialization_alias="downloadUrl")
     file_name: str = Field(..., serialization_alias="fileName")
     expires_at: int = Field(..., serialization_alias="expiresAt", description="Unix 毫秒时间戳")
+    style_id: str = Field(..., serialization_alias="styleId", description="实际使用的样式 ID")
 
     model_config = {"populate_by_name": True}

app/services/export_service.py

@@ -1,65 +1,195 @@
-"""
-export_service.py
-将 Markdown 内容转换为 .docx 文件并返回可下载的临时链接。
-
-阶段 0：支持导出 .doc（实际生成 .docx，浏览器以 .doc 扩展名下载）。
-依赖：python-docx, mistune
-"""
+"""export_service.py — 将 Markdown 内容转换为 .docx 文件并返回可下载的临时链接。"""
 
 import io
+import json
 import secrets
 import time
 import unicodedata
 import urllib.parse
 from pathlib import Path
+from typing import Optional
 
 import mistune
 from docx import Document
 from docx.oxml import OxmlElement
 from docx.oxml.ns import qn
 from docx.shared import Pt, RGBColor
+from lxml import etree
 
 from app.config import settings
 from app.core.exceptions import ExportError
 
 
 # ------------------------------------------------------------------ #
+# 样式文件加载
+# ------------------------------------------------------------------ #
+
+def load_style_file(style_id: Optional[str] = None) -> dict:
+    """加载样式 JSON 文件并返回解析后的字典；style_id=None 时加载默认样式文件。"""
+    if style_id is None:
+        path = Path(settings.default_style_file)
+        if not path.exists():
+            raise ExportError(f"默认样式文件不存在: {path}")
+    else:
+        # 阶段 1 占位：届时改为从数据库查路径
+        # path = style_repo.get_file_path(style_id)
+        raise ExportError(f"样式 ID 暂不支持: {style_id}（阶段 1 功能）")
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ExportError(f"样式文件解析失败: {exc}") from exc
+
+
+def build_style_map(style_data: dict) -> dict[str, dict]:
+    """将样式列表转为双键映射（style_id 和 name 均可命中）。"""
+    mapping: dict[str, dict] = {}
+    for s in style_data.get("styles", []):
+        if s.get("style_id"):
+            mapping[s["style_id"]] = s
+        if s.get("name"):
+            mapping[s["name"]] = s
+    return mapping
+
+
+# ------------------------------------------------------------------ #
+# JSON ↔ lxml 互转
+# ------------------------------------------------------------------ #
+
+def dict_to_element(d: dict) -> etree._Element:
+    """将 element_to_dict() 产生的字典还原为 lxml Element（styles.py 的逆操作）。"""
+    tag = d["@tag"]
+    attrib = {k: v for k, v in d.get("@attrib", {}).items()}
+    elem = etree.Element(tag, attrib=attrib)
+
+    if d.get("#text"):
+        elem.text = d["#text"]
+    if d.get("#tail"):
+        elem.tail = d["#tail"]
+
+    for child_tag, child_val in d.get("@children", {}).items():
+        # 同标签多子节点时存为列表
+        items = child_val if isinstance(child_val, list) else [child_val]
+        for item in items:
+            if isinstance(item, dict):
+                child_elem = dict_to_element(item)
+                elem.append(child_elem)
+
+    return elem
+
+
+def inject_styles_from_json(doc: Document, style_data: dict) -> None:
+    """
+    将 JSON 中所有样式的 full_xml_definition 注入到文档的 <w:styles> 节点。
+    已存在相同 w:styleId 的样式先移除再插入（upsert 语义），确保完整替换。
+    没有 full_xml_definition 的条目跳过。
+    """
+    styles_element = doc.styles.element  # <w:styles> 根节点
+
+    for style_entry in style_data.get("styles", []):
+        xml_def = style_entry.get("full_xml_definition")
+        if not xml_def:
+            continue
+
+        # 从字典重建 lxml element
+        try:
+            new_elem = dict_to_element(xml_def)
+        except Exception:
+            continue  # 单条解析失败不中断整体
+
+        # 取出 w:styleId 属性，用于查找并移除旧节点
+        style_id_key = qn("w:styleId")
+        new_style_id = new_elem.get(style_id_key)
+        if new_style_id:
+            existing = styles_element.find(
+                f'.//{qn("w:style")}[@{qn("w:styleId")}="{new_style_id}"]'
+            )
+            if existing is not None:
+                styles_element.remove(existing)
+
+        styles_element.append(new_elem)
+
+
+# ------------------------------------------------------------------ #
+# 样式 ID 查找辅助
+# ------------------------------------------------------------------ #
+
+def _resolve_style_id(style_map: dict, *lookup_keys: str) -> Optional[str]:
+    """
+    按优先级依次查找多个候选 key，返回第一个命中条目的 style_id。
+    用于将语义名称（如 "Normal"、"Heading 1"）映射到 JSON 中实际的 w:styleId。
+    """
+    for key in lookup_keys:
+        entry = style_map.get(key)
+        if entry and entry.get("style_id"):
+            return entry["style_id"]
+    return None
+
+
+# ------------------------------------------------------------------ #
 # Markdown → python-docx 渲染器
 # ------------------------------------------------------------------ #
 
 class DocxRenderer(mistune.BaseRenderer):
     """将 mistune AST token 流渲染到 python-docx Document 对象。"""
 
-    def __init__(self) -> None:
-        # 创建空白 Word 文档，设置默认字体
+    # Word 内置标题样式的英文名（用于查找 style_map 时的候选 key）
+    _HEADING_ALIASES = {
+        1: ["Heading 1", "heading 1"],
+        2: ["Heading 2", "heading 2"],
+        3: ["Heading 3", "heading 3"],
+        4: ["Heading 4", "heading 4"],
+        5: ["Heading 5", "heading 5"],
+        6: ["Heading 6", "heading 6"],
+    }
+
+    def __init__(self, style_map: dict, style_data: dict) -> None:
+        """初始化渲染器，注入完整样式定义并缓存常用样式 ID。"""
         super().__init__()
+        self.style_map = style_map
         self.doc = Document()
-        self._set_default_font("宋体", 12)
 
-    # ------ 字体初始化 ------ #
+        # 用 full_xml_definition 整体替换文档样式表，一次性应用所有格式
+        inject_styles_from_json(self.doc, style_data)
 
-    def _set_default_font(self, font_name: str, font_size: int) -> None:
-        # 修改 Normal 样式的全局默认字体和字号
-        style = self.doc.styles["Normal"]
-        style.font.name = font_name
-        style.font.size = Pt(font_size)
+        # 缓存 Normal 的 style_id，段落渲染时使用
+        self._normal_id: Optional[str] = _resolve_style_id(
+            style_map, "Normal", "1"
+        )
 
     # ------ 块级元素 ------ #
 
     def heading(self, token: dict, state: mistune.core.BlockState) -> str:
-        # # ## ### → Heading 1/2/3，从 token attrs 读取层级，字体颜色强制设为黑色
+        # # ## ### → 从 style_map 解析对应样式 ID；找不到则回退到 python-docx 内置标题
         level = token["attrs"]["level"]
         children = token.get("children", [])
         text = self._extract_text(children)
-        para = self.doc.add_heading(text, level=level)
-        for run in para.runs:
-            run.font.color.rgb = RGBColor(0x00, 0x00, 0x00)
+
+        aliases = self._HEADING_ALIASES.get(level, [f"Heading {level}", f"heading {level}"])
+        heading_style_id = _resolve_style_id(self.style_map, *aliases)
+
+        if heading_style_id:
+            # 用 w:styleId 直接引用已注入的样式，不再手动设颜色/字号
+            para = self.doc.add_paragraph(text)
+            try:
+                para.style = self._get_style_by_id(heading_style_id)
+            except KeyError:
+                pass  # 样式注入失败时保持默认样式，不中断渲染
+        else:
+            para = self.doc.add_heading(text, level=level)
+
         return ""
 
     def paragraph(self, token: dict, state: mistune.core.BlockState) -> str:
-        # 普通段落，内部可能含粗体/斜体等内联样式，交给 _render_inline_children 处理
+        # 普通段落，内联样式由 _render_inline_children 处理
         children = token.get("children", [])
         p = self.doc.add_paragraph()
+        if self._normal_id:
+            try:
+                p.style = self._get_style_by_id(self._normal_id)
+            except Exception:
+                pass
         self._render_inline_children(p, children)
         return ""
 
@@ -68,7 +198,7 @@ class DocxRenderer(mistune.BaseRenderer):
         return ""
 
     def thematic_break(self, token: dict, state: mistune.core.BlockState) -> str:
-        # --- 分隔线：python-docx 无直接 API，手动注入 XML 段落底部边框实现
+        # --- 分隔线：通过 XML 段落底部边框实现
         p = self.doc.add_paragraph()
         pPr = p._p.get_or_add_pPr()
         pBdr = OxmlElement("w:pBdr")
@@ -82,16 +212,24 @@ class DocxRenderer(mistune.BaseRenderer):
         return ""
 
     def block_quote(self, token: dict, state: mistune.core.BlockState) -> str:
-        # > 引用块 → Word Quote 样式（缩进+斜体）
+        # > 引用块 → Quote 样式（缩进+斜体）
         children = token.get("children", [])
         for child in children:
             text = self._extract_text(child.get("children", []))
-            p = self.doc.add_paragraph(style="Quote")
-            p.add_run(text)
+            quote_id = _resolve_style_id(self.style_map, "Quote", "Quote Char")
+            if quote_id:
+                p = self.doc.add_paragraph(text)
+                try:
+                    p.style = self._get_style_by_id(quote_id)
+                except Exception:
+                    p.style = "Quote"
+            else:
+                p = self.doc.add_paragraph(style="Quote")
+                p.add_run(text)
         return ""
 
     def block_code(self, token: dict, state: mistune.core.BlockState) -> str:
-        # 代码块 → No Spacing 样式，Courier New 10pt 深灰色
+        # 代码块 → No Spacing 样式，Courier New 10pt 深灰色（样式库通常无代码块样式，保持硬编码）
         code = token.get("raw", "")
         p = self.doc.add_paragraph(style="No Spacing")
         run = p.add_run(code)
@@ -101,16 +239,14 @@ class DocxRenderer(mistune.BaseRenderer):
         return ""
 
     def list(self, token: dict, state: mistune.core.BlockState) -> str:
-        # 列表入口，判断有序/无序和当前嵌套深度，具体渲染交给 _render_list_items
+        # 列表入口，判断有序/无序和嵌套深度，委托 _render_list_items 处理
         ordered = token["attrs"].get("ordered", False)
         depth = token["attrs"].get("depth", 1)
         self._render_list_items(token.get("children", []), ordered, depth)
         return ""
 
-    def _render_list_items(
-        self, items: list, ordered: bool, depth: int
-    ) -> None:
-        # 递归处理列表项；遇到嵌套子列表时 depth+1，对应 List Bullet/Number 2 样式
+    def _render_list_items(self, items: list, ordered: bool, depth: int) -> None:
+        # 递归处理列表项；嵌套子列表 depth+1，对应 List Bullet/Number 2 样式
         for item in items:
             children = item.get("children", [])
             for child in children:
@@ -128,8 +264,7 @@ class DocxRenderer(mistune.BaseRenderer):
                     self.doc.add_paragraph(text, style=style)
 
     def table(self, token: dict, state: mistune.core.BlockState) -> str:
-        # 表格渲染
-        # mistune AST 结构：table_head 直接含 table_cell；table_body 含 table_row → table_cell
+        # 表格渲染：table_head 直接含 table_cell；table_body 含 table_row → table_cell
         children = token.get("children", [])
         if not children:
             return ""
@@ -173,7 +308,7 @@ class DocxRenderer(mistune.BaseRenderer):
     # ------ 内联样式 ------ #
 
     def _render_inline_children(self, paragraph, children: list) -> None:
-        # 遍历段落内子节点，按类型设置 run 样式：粗体/斜体/删除线/行内代码/换行
+        # 遍历子节点，按类型设置 run 样式：粗体/斜体/删除线/行内代码/换行
         for child in children:
             ctype = child.get("type", "")
             raw = child.get("raw", "")
@@ -207,6 +342,13 @@ class DocxRenderer(mistune.BaseRenderer):
 
     # ------ 工具方法 ------ #
 
+    def _get_style_by_id(self, style_id: str):
+        """通过 w:styleId 从文档样式集中查找 python-docx Style 对象。"""
+        for style in self.doc.styles:
+            if style.style_id == style_id:
+                return style
+        raise KeyError(f"样式 ID 不存在: {style_id}")
+
     @staticmethod
     def _extract_text(children: list) -> str:
         # 递归提取纯文本，用于标题/列表/表格等不需要内联样式的场景
@@ -222,7 +364,7 @@ class DocxRenderer(mistune.BaseRenderer):
         return "".join(parts)
 
     def render_token(self, token: dict, state: mistune.core.BlockState) -> str:
-        # mistune 分发入口：按 token type 找对应方法，找不到则递归渲染子节点兜底
+        # mistune 分发入口：按 token type 找对应方法，找不到则递归子节点兜底
         ttype = token["type"]
         func = getattr(self, ttype, None)
         if func:
@@ -250,9 +392,9 @@ class DocxRenderer(mistune.BaseRenderer):
 # 公共接口
 # ------------------------------------------------------------------ #
 
-def markdown_to_docx_bytes(content: str) -> bytes:
-    """Markdown 字符串 → .docx 字节流，全程内存操作不落盘。"""
-    renderer = DocxRenderer()
+def markdown_to_docx_bytes(content: str, style_map: dict, style_data: dict) -> bytes:
+    """Markdown 字符串转 .docx 字节流，全程内存操作不落盘。"""
+    renderer = DocxRenderer(style_map=style_map, style_data=style_data)
     # 必须显式启用插件：mistune 默认不解析表格和删除线
     md = mistune.create_markdown(
         renderer=renderer,
@@ -267,7 +409,7 @@ def markdown_to_docx_bytes(content: str) -> bytes:
 
 def _safe_filename(name: str) -> str:
     """过滤文件名非法字符，规范化全角字符，返回安全的文件名。"""
-    name = unicodedata.normalize("NFKC", name)  # 全角转半角
+    name = unicodedata.normalize("NFKC", name)
     illegal = r'\/:*?"<>|'
     for ch in illegal:
         name = name.replace(ch, "_")
@@ -277,20 +419,24 @@ def _safe_filename(name: str) -> str:
 async def export_doc(
     file_name: str,
     content: str,
+    style_id: Optional[str] = None,
 ) -> dict:
-    """
-    导出入口：生成 .docx 写入临时目录，返回下载链接信息。
+    """导出入口：加载样式、生成 .docx 写入临时目录，返回 { download_url, file_name, expires_at, style_id }。"""
+    # 1. 加载样式文件，构建映射
+    style_data = load_style_file(style_id)
+    style_map = build_style_map(style_data)
+    actual_style_id = style_id or "default"
 
-    返回：{ download_url, file_name, expires_at }
-    """
+    # 2. Markdown → docx 字节流
     try:
-        doc_bytes = markdown_to_docx_bytes(content)
+        doc_bytes = markdown_to_docx_bytes(content, style_map, style_data)
     except Exception as exc:
         raise ExportError(f"Markdown 转换失败: {exc}") from exc
 
+    # 3. 写入临时目录
     safe_name = _safe_filename(file_name)
     token = secrets.token_urlsafe(8)
-    final_name = f"{safe_name}_{token}.doc"   # 磁盘文件名含中文原始名
+    final_name = f"{safe_name}_{token}.doc"
 
     tmp_dir = Path(settings.temp_dir)
     tmp_dir.mkdir(parents=True, exist_ok=True)
@@ -301,8 +447,8 @@ async def export_doc(
     except OSError as exc:
         raise ExportError(f"文件写入失败: {exc}") from exc
 
+    # 4. 生成下载链接
     expires_at_ms = int((time.time() + settings.export_link_expires) * 1000)
-    # 文件名中文部分编码进 URL，下载路由收到后 FastAPI 自动解码还原
     encoded_name = urllib.parse.quote(final_name, safe="-._~")
     download_url = f"{settings.base_url.rstrip('/')}/api/v1/files/{encoded_name}"
 
@@ -310,4 +456,5 @@ async def export_doc(
         "download_url": download_url,
         "file_name": final_name,
         "expires_at": expires_at_ms,
+        "style_id": actual_style_id,
     }

docs/export-doc-content-mapping.md

@@ -16,6 +16,7 @@
 | 核心依赖 | `python-docx 1.1.2` · `mistune 3.0.2` |
 | 文件存储 | 服务器本地 `./tmp/` 目录（临时缓存，当前不自动清理） |
 | 下载链接有效期 | 默认 3600 秒（1 小时），由 `EXPORT_LINK_EXPIRES` 配置 |
+| 默认样式文件 | `./tmp/default.json`（阶段 0 固定使用；阶段 1 起支持用户选择） |
 
 ---
 
@@ -43,7 +44,8 @@
   "fileName": "2026年Q2季度报告",
   "format": "doc",
   "content": "# 2026年Q2季度报告\n\n## 一、背景\n\n本季度整体营收同比增长15%。\n\n...",
-  "documentId": "doc-abc123"
+  "documentId": "doc-abc123",
+  "styleId": null
 }
 ```
 
@@ -53,6 +55,7 @@
 | `format` | string | 是 | 阶段 0 固定为 `"doc"` |
 | `content` | string | 是 | 文档当前 Markdown 内容，最大 200KB |
 | `documentId` | string | 否 | 关联文档 ID，传入时后端同步更新草稿记录 |
+| `styleId` | string | 否 | 样式 ID；**阶段 0 暂不生效**，后端固定使用 `default.json`；阶段 1 起传入有效 ID 则使用用户上传的样式 |
 
 #### 响应
 
@@ -65,7 +68,8 @@
   "data": {
     "downloadUrl": "http://192.168.0.200:8000/api/v1/files/2026年Q2季度报告_XnjI2ABA1kI.doc",
     "fileName": "2026年Q2季度报告.doc",
-    "expiresAt": 1749999999000
+    "expiresAt": 1749999999000,
+    "styleId": "default"
   }
 }
 ```
@@ -75,6 +79,7 @@
 | `downloadUrl` | string | 临时下载链接，有效期由 `expiresAt` 标注 |
 | `fileName` | string | 含扩展名的完整文件名 |
 | `expiresAt` | number | 链接过期时间，Unix 毫秒时间戳 |
+| `styleId` | string | 实际使用的样式 ID；阶段 0 固定返回 `"default"` |
 
 **错误响应**
 
@@ -151,31 +156,166 @@ PUT documents/{id}
     └─────┬─────┘
           |
           v
+  ┌─────────────────────────────┐
+  │        样式文件解析           │
+  │                             │
+  │  styleId 传入且有效？         │
+  │    Yes → 从样式库加载对应     │
+  │          JSON 文件           │
+  │    No  → 加载默认样式文件     │
+  │          ./tmp/default.json  │
+  │                             │
+  │  解析 JSON，提取各样式定义    │
+  │  （Normal、Heading1-6、      │
+  │   List Bullet/Number 等）    │
+  └─────────────┬───────────────┘
+                │
+                v
 export_service.export_doc()
-  1. markdown_to_docx_bytes(content)
-     - DocxRenderer 初始化
-       └── 设置默认字体：宋体 12pt
+  1. load_style_definitions(style_file)
+     - 读取样式 JSON（默认或用户指定）
+     - 构建 style_id -> 样式属性 映射表
+
+  2. markdown_to_docx_bytes(content, styles)
+     - DocxRenderer 初始化，注入样式映射
+       └── 应用 Normal 样式的字体和字号
+           （默认：宋体 12pt）
      - mistune 解析 Markdown -> AST
        plugins: table, strikethrough, url
-     - 遍历 token，映射到 python-docx
+     - 遍历 token，按映射表应用对应样式
 
-  2. _safe_filename(fileName)
+  3. _safe_filename(fileName)
      └── 过滤非法字符，规范化 Unicode
 
-  3. 写入 ./tmp/{name}_{token}.doc
+  4. 写入 ./tmp/{name}_{token}.doc
 
-  4. 生成 downloadUrl + expiresAt
+  5. 生成 downloadUrl + expiresAt
           |
           v
 返回 ExportDocResponse
-  { downloadUrl, fileName, expiresAt }
+  { downloadUrl, fileName, expiresAt, styleId }
+```
+
+### 样式加载优先级
+
+```
+请求携带 styleId（阶段 1）
+    └─ styleId 有效 → 使用用户样式库中对应的 JSON 文件
+    └─ styleId 无效 → 返回 404，不降级
+
+请求未携带 styleId（阶段 0 / 默认）
+    └─ 加载 ./tmp/default.json（由 DEFAULT_STYLE_FILE 配置）
+    └─ default.json 不存在 → 返回 500
 ```
 
 ---
 
-## 4. Markdown 与 Word 样式映射
+## 4. 默认样式文件（`default.json`）
+
+### 4.1 文件位置与用途
+
+| 项目 | 内容 |
+|------|------|
+| 文件路径 | `./tmp/default.json`（由 `DEFAULT_STYLE_FILE` 配置） |
+| 格式 | 样式 JSON，与用户上传文档提取的格式完全相同 |
+| 来源 | 从内置标准 Word 文档提取，随服务部署一同发布 |
+| 阶段 0 行为 | 所有导出请求固定使用此文件，不支持切换 |
+| 阶段 1 行为 | 用户未传 `styleId` 时作为兜底；用户可上传文档生成新样式并选用 |
+
+### 4.2 文件结构
+
+```json
+{
+  "source_file": "default.doc",
+  "total_styles": 164,
+  "styles": [
+    {
+      "name": "Normal",
+      "style_id": "Normal",
+      "type": "PARAGRAPH (1)",
+      "builtin": true,
+      "hidden": false,
+      "quick_style": true,
+      "priority": null,
+      "base_style": null,
+      "next_paragraph_style": "Normal",
+      "font": {
+        "name": "宋体",
+        "size_pt": 12.0,
+        "bold": null,
+        "italic": null,
+        "underline": null,
+        "color_rgb": null,
+        "strike": null,
+        "all_caps": null,
+        "small_caps": null
+      },
+      "paragraph_format": {
+        "alignment": null,
+        "left_indent_pt": null,
+        "right_indent_pt": null,
+        "first_line_indent_pt": null,
+        "space_before_pt": null,
+        "space_after_pt": null,
+        "line_spacing": null,
+        "keep_together": null,
+        "keep_with_next": null,
+        "page_break_before": null
+      }
+    },
+    {
+      "name": "Heading 1",
+      "style_id": "Heading1",
+      "type": "PARAGRAPH (1)",
+      "font": { "size_pt": 14.0, "bold": true, "color_rgb": "365F91" },
+      "paragraph_format": { "space_before_pt": 24.0, "space_after_pt": 0.0 }
+    }
+    // ... 其余 162 个样式定义
+  ]
+}
+```
 
-### 4.1 标题
+字段说明见 [text-editor-backend-api.md §4 数据结构](./text-editor-backend-api.md)。
+
+### 4.3 后端加载逻辑（伪代码）
+
+```python
+def load_style_file(style_id: str | None) -> dict:
+    """
+    阶段 0：style_id 始终为 None，返回 default.json
+    阶段 1：style_id 有值时从样式库查找对应 JSON 路径
+    """
+    if style_id is None:
+        path = settings.default_style_file   # ./tmp/default.json
+    else:
+        # 阶段 1：从数据库查路径，找不到抛 404
+        path = style_repo.get_file_path(style_id)
+
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def build_style_map(style_data: dict) -> dict[str, dict]:
+    """将样式列表转换为 style_id -> 样式属性 的映射，加速查询"""
+    return {s["style_id"]: s for s in style_data["styles"]}
+```
+
+### 4.4 样式应用规则
+
+导出时，`DocxRenderer` 按以下规则从样式映射中读取属性并应用到 `python-docx` 对象：
+
+| 优先级 | 规则 |
+|--------|------|
+| 1 | 使用样式 JSON 中对应 `style_id` 的字体和段落格式 |
+| 2 | JSON 中字段为 `null` 时，保留 `python-docx` 内置 Word 样式默认值 |
+| 3 | 标题颜色：JSON 有 `color_rgb` 时使用，否则强制黑色（覆盖 Word 内置蓝色） |
+| 4 | 找不到对应 `style_id` 时，回退到 `Normal` 样式 |
+
+---
+
+## 5. Markdown 与 Word 样式映射
+
+### 5.1 标题
 
 | Markdown | Word 样式 | python-docx 调用 |
 |----------|-----------|-----------------|
@@ -187,7 +327,7 @@ export_service.export_doc()
 
 > 所有标题颜色强制设为黑色，覆盖 Word 内置 Heading 样式的蓝色主题色。
 
-### 4.2 内联样式
+### 5.2 内联样式
 
 | Markdown | 语义 | python-docx 处理 |
 |----------|------|-----------------|
@@ -196,7 +336,7 @@ export_service.export_doc()
 | `~~文字~~` | 删除线 | `run.font.strike = True` |
 | `` `代码` `` | 行内代码 | `run.font.name = "Courier New"` |
 
-### 4.3 列表
+### 5.3 列表
 
 | Markdown | Word 样式 | python-docx 调用 |
 |----------|-----------|-----------------|
@@ -205,7 +345,7 @@ export_service.export_doc()
 | 二级无序缩进 | List Bullet 2 | `doc.add_paragraph(style="List Bullet 2")` |
 | 二级有序缩进 | List Number 2 | `doc.add_paragraph(style="List Number 2")` |
 
-### 4.4 块级元素
+### 5.4 块级元素
 
 | Markdown | Word 样式 | python-docx 处理 |
 |----------|-----------|-----------------|
@@ -214,7 +354,7 @@ export_service.export_doc()
 | `---` / `***` | 段落底部边框 | OxmlElement 注入 `w:pBdr` |
 | `\| 列 \| 列 \|` | Table Grid | `doc.add_table()`，表头行自动加粗 |
 
-### 4.5 表格 AST 结构说明
+### 5.5 表格 AST 结构说明
 
 mistune 3.x 解析表格后的 token 层级（需启用 `table` 插件）：
 
@@ -233,7 +373,7 @@ table
 
 ---
 
-## 5. 临时文件说明
+## 6. 临时文件说明
 
 | 项目 | 内容 |
 |------|------|
@@ -249,30 +389,32 @@ table
 
 ---
 
-## 6. 配置项
+## 7. 配置项
 
 | 环境变量 | 默认值 | 说明 |
 |---------|--------|------|
 | `TEMP_DIR` | `./tmp` | 临时文件存储目录 |
 | `EXPORT_LINK_EXPIRES` | `3600` | 下载链接有效期（秒） |
 | `BASE_URL` | `http://192.168.0.200:8000` | 服务对外地址，用于拼接 `downloadUrl` |
+| `DEFAULT_STYLE_FILE` | `./tmp/default.json` | 默认样式文件路径；阶段 0 固定使用，阶段 1 作为兜底 |
 
 ---
 
-## 7. 涉及代码文件
+## 8. 涉及代码文件
 
 | 文件 | 职责 |
 |------|------|
 | `app/api/v1/export.py` | 路由层：参数接收、可选草稿同步、响应封装 |
 | `app/schemas/export.py` | 请求/响应 Pydantic 模型，字段别名（camelCase） |
-| `app/services/export_service.py` | 核心：`DocxRenderer`、`markdown_to_docx_bytes()`、文件写入、链接生成 |
+| `app/services/export_service.py` | 核心：`DocxRenderer`、`load_style_file()`、`markdown_to_docx_bytes()`、文件写入、链接生成 |
 | `app/services/document_service.py` | 可选路径：`documentId` 存在时调用 `update_document()` |
-| `app/config.py` | `temp_dir`、`base_url`、`export_link_expires` 配置读取 |
+| `app/config.py` | `temp_dir`、`base_url`、`export_link_expires`、`default_style_file` 配置读取 |
 | `app/core/exceptions.py` | `ExportError` 定义及全局 handler（返回 HTTP 500） |
+| `tmp/default.json` | 默认样式文件，阶段 0 固定使用 |
 
 ---
 
-## 8. 请求示例
+## 9. 请求示例
 
 ### curl
 
@@ -282,10 +424,13 @@ curl -X POST http://192.168.0.200:8000/api/v1/export/doc \
   -d '{
     "fileName": "2026年Q2季度报告",
     "format": "doc",
-    "content": "# 2026年Q2季度报告\n\n## 一、背景\n\n本季度整体营收同比增长15%。\n\n## 二、核心数据\n\n### 2.1 收入\n\n| 月份 | 收入（万元） |\n|------|------|\n| 4月 | 120 |\n| 5月 | 135 |\n\n### 2.2 用户增长\n\n- 新增用户：12,000\n- 月活用户：85,000\n\n## 三、下季度计划\n\n1. 推进产品 A 上线\n2. 扩充销售团队\n"
+    "content": "# 2026年Q2季度报告\n\n## 一、背景\n\n本季度整体营收同比增长15%。\n\n## 二、核心数据\n\n### 2.1 收入\n\n| 月份 | 收入（万元） |\n|------|------|\n| 4月 | 120 |\n| 5月 | 135 |\n\n### 2.2 用户增长\n\n- 新增用户：12,000\n- 月活用户：85,000\n\n## 三、下季度计划\n\n1. 推进产品 A 上线\n2. 扩充销售团队\n",
+    "styleId": null
   }'
 ```
 
+> 阶段 0 传 `null` 或不传 `styleId`，后端均使用 `default.json`。
+
 ### 预期响应
 
 ```json
@@ -295,7 +440,8 @@ curl -X POST http://192.168.0.200:8000/api/v1/export/doc \
   "data": {
     "downloadUrl": "http://192.168.0.200:8000/api/v1/files/2026年Q2季度报告_XnjI2ABA1kI.doc",
     "fileName": "2026年Q2季度报告.doc",
-    "expiresAt": 1749999999000
+    "expiresAt": 1749999999000,
+    "styleId": "default"
   }
 }
 ```
@@ -309,6 +455,6 @@ curl -O "http://192.168.0.200:8000/api/v1/files/2026年Q2季度报告_XnjI2ABA1k
 
 ---
 
-**文档版本**：v2.1
-**更新日期**：2026-06-12
+**文档版本**：v2.2
+**更新日期**：2026-06-15
 **关联文档**：[text-editor-backend-api.md](./text-editor-backend-api.md) · [text-editor-architecture.md](./text-editor-architecture.md) · [environment-setup.md](./environment-setup.md)

docs/text-editor-backend-api.md

@@ -14,12 +14,23 @@
 
 | 阶段 | 新增 API |
 |------|---------|
-| 阶段 0 | 文档 CRUD |
-| 阶段 1 | 模板管理、DOCX 下载导出 |
+| 阶段 0 | 文档 CRUD、导出 .doc（默认样式） |
+| 阶段 1 | 样式管理、模板管理、导出 DOCX |
 | 阶段 2 | 编辑会话（Token）、Webhook |
 | 阶段 3 | PDF 导出、版本管理 |
 
-### 1.3 通用响应格式
+### 1.3 样式与模板的区别
+
+这是两个独立功能，用户可以按需使用其中一个或两个都不用：
+
+| | 样式（Style） | 模板（Template） |
+|---|---|---|
+| 用途 | 控制输出文件的字体、颜色、标题层级等视觉格式 | 定义文档结构，内容填入占位符位置 |
+| 上传内容 | 任意 Word 文档，后端提取其中的样式文件 | 带占位符（`{{名称}}`）的 Word 文档 |
+| 导出方式 | 导出 .doc 时选择样式，不选用系统默认 | 导出 DOCX 时指定模板，内容按标题匹配占位符 |
+| 是否必须 | 否，有默认样式兜底 | 否，不使用模板则走样式导出流程 |
+
+### 1.4 通用响应格式
 
 ```json
 {
@@ -53,8 +64,7 @@ class CreateDocumentRequest(BaseModel):
     content: str                                    # 文档内容（Markdown），最大 200KB
     format: Literal["markdown"] = "markdown"        # 内容格式，默认 markdown
     session_id: Optional[str] = None                # 关联的聊天会话 ID
-    template_id: Optional[str] = None              # 关联 Word 模板 ID（阶段 1，工作流文档必填）
-    source: Literal["chat", "workflow"] = "chat"   # 来源，默认 chat
+    template_id: Optional[str] = None              # 关联 Word 模板 ID（阶段 1 引入）
 
 # 更新文档请求（全量或局部块）
 class UpdateDocumentRequest(BaseModel):
@@ -70,7 +80,6 @@ class DocumentResponse(BaseModel):
     format: str
     session_id: Optional[str] = None
     template_id: Optional[str] = None
-    source: Literal["chat", "workflow"]
     created_by: str
     created_at: datetime
     updated_at: datetime
@@ -79,7 +88,6 @@ class DocumentResponse(BaseModel):
 class DocumentListItem(BaseModel):
     id: str
     title: str
-    source: Literal["chat", "workflow"]
     template_id: Optional[str] = None
     created_at: datetime
     updated_at: datetime
@@ -107,8 +115,7 @@ class Pagination(BaseModel):
   "content": "# 标题\n\n这是文档内容...",
   "format": "markdown",
   "sessionId": "chat-session-123",
-  "templateId": "tpl-001",
-  "source": "chat"
+  "templateId": "tpl-001"
 }
 ```
 
@@ -118,8 +125,7 @@ class Pagination(BaseModel):
 | content | string | 是 | 文档内容，最大 200KB |
 | format | string | 否 | 默认 `markdown` |
 | sessionId | string | 否 | 关联聊天会话 ID |
-| templateId | string | 否 | 关联 Word 模板 ID（阶段 1 引入，工作流文档必填） |
-| source | string | 否 | `chat` / `workflow`，默认 `chat` |
+| templateId | string | 否 | 关联 Word 模板 ID（阶段 1 引入） |
 
 **响应示例**:
 ```json
@@ -154,7 +160,6 @@ class Pagination(BaseModel):
     "format": "markdown",
     "sessionId": "chat-session-123",
     "templateId": "tpl-001",
-    "source": "workflow",
     "createdBy": "user-xyz",
     "createdAt": 1680000000000,
     "updatedAt": 1680000100000
@@ -243,7 +248,6 @@ class Pagination(BaseModel):
 | page | integer | 否 | 页码，默认 1 |
 | pageSize | integer | 否 | 每页数量，默认 20，最大 100 |
 | sessionId | string | 否 | 按聊天会话过滤 |
-| source | string | 否 | `chat` / `workflow` |
 | sortBy | string | 否 | `createdAt` / `updatedAt`，默认 `updatedAt` |
 | sortOrder | string | 否 | `asc` / `desc`，默认 `desc` |
 
@@ -256,7 +260,6 @@ class Pagination(BaseModel):
       {
         "id": "doc-abc123",
         "title": "我的文档",
-        "source": "workflow",
         "templateId": "tpl-001",
         "createdAt": 1680000000000,
         "updatedAt": 1680000100000
@@ -276,6 +279,8 @@ class Pagination(BaseModel):
 
 ## 3. 导出 API（阶段 0）
 
+**本节说明**：阶段 0 导出不依赖样式库和模板，使用系统内置默认样式将 Markdown 内容转换为 .doc 文件。阶段 1 引入样式管理后，本接口扩展支持用户选择自定义样式（通过 `styleId` 参数），接口结构不变。
+
 ### 数据结构
 
 ```python
@@ -284,22 +289,24 @@ from typing import Literal, Optional
 
 # 导出 .doc 请求
 class ExportDocRequest(BaseModel):
-    file_name: str              # 文件名（不含扩展名），最大 255 字符
-    format: Literal["doc"]      # 阶段 0 固定为 doc
-    content: str                # 文档当前内容（Markdown）
+    file_name: str                      # 文件名（不含扩展名），最大 255 字符
+    format: Literal["doc"]              # 阶段 0 固定为 doc
+    content: str                        # 文档当前内容（Markdown）
     document_id: Optional[str] = None  # 关联文档 ID，传入时后端同步更新草稿记录
+    style_id: Optional[str] = None     # 样式 ID；不传时使用系统默认样式；阶段 1 起支持用户自定义样式
 
 # 导出响应
 class ExportDocResponse(BaseModel):
     download_url: str   # 临时下载链接，有效期 1 小时
     file_name: str      # 含扩展名的完整文件名，如 季度报告_2026Q2.doc
     expires_at: int     # 链接过期时间，Unix 毫秒时间戳
+    style_id: str       # 实际使用的样式 ID
 ```
 
 ### 3.1 导出 .doc 并下载
 
 **触发时机**：用户点击编辑器"保存"按钮，在弹出对话框中填写文件名、选择格式并确认后触发。  
-**目的**：根据用户填写的文件名、格式和当前文档内容，生成对应格式的文件，返回临时下载链接，前端自动触发浏览器下载。  
+**目的**：将 Markdown 内容按指定样式渲染生成 .doc 文件，返回临时下载链接。输出字体、标题层级、段落间距等均由样式文件控制。  
 **注意**：此接口不操作数据库文档记录，仅负责文件生成与下载链接的返回。如需同时更新草稿，可传入 `documentId`，后端会先更新一次记录再生成文件。
 
 **接口地址**: `POST /api/v1/export/doc`
@@ -310,7 +317,8 @@ class ExportDocResponse(BaseModel):
   "fileName": "季度报告_2026Q2",
   "format": "doc",
   "content": "# 标题\n\n这是文档内容...",
-  "documentId": "doc-abc123"
+  "documentId": "doc-abc123",
+  "styleId": "style-001"
 }
 ```
 
@@ -319,7 +327,8 @@ class ExportDocResponse(BaseModel):
 | fileName | string | 是 | 用户填写的文件名（不含扩展名），最大 255 字符 |
 | format | string | 是 | 文件格式，阶段 0 固定为 `doc` |
 | content | string | 是 | 文档当前内容（Markdown） |
-| documentId | string | 否 | 关联的文档 ID，用于更新自动保存记录 |
+| documentId | string | 否 | 关联的文档 ID，用于同步更新自动保存记录 |
+| styleId | string | 否 | 样式 ID；不传时使用系统默认样式；阶段 1 起可传用户上传的自定义样式 ID |
 
 **响应示例**:
 ```json
@@ -328,7 +337,8 @@ class ExportDocResponse(BaseModel):
   "data": {
     "downloadUrl": "https://api.axonix.com/files/download/季度报告_2026Q2.doc?token=xxx",
     "fileName": "季度报告_2026Q2.doc",
-    "expiresAt": 1680003600000
+    "expiresAt": 1680003600000,
+    "styleId": "default"
   }
 }
 ```
@@ -337,7 +347,15 @@ class ExportDocResponse(BaseModel):
 
 ---
 
-## 4. Word 模板管理 API（阶段 1）
+## 4. 样式管理 API（阶段 1）
+
+用户上传任意 Word 文档，后端自动提取其中**所有样式的完整 XML 定义**，生成与原文档同名的样式文件并持久化存储，加入用户的样式缓存列表，导出 .doc 时可从列表中选择使用。
+
+### 功能说明
+
+- 上传文档后，后端遍历文档中的所有样式（段落样式、字符样式、表格样式、列表样式等），完整保留每个样式的原始 XML 结构（含所有属性、子元素和命名空间），不做任何简化裁剪。
+- 样式文件以上传文档的原始文件名命名（去掉扩展名），存入用户的样式库缓存。
+- 每次导出 .doc 时，用户可从缓存列表中选择一个样式应用到输出文件；不选则使用系统默认样式。
 
 ### 数据结构
 
@@ -346,45 +364,308 @@ from pydantic import BaseModel
 from typing import Optional
 from datetime import datetime
 
-# 标题样式
-class HeadingStyle(BaseModel):
-    level: int              # 标题等级 1-6
-    font: str               # 字体名称，如 "宋体"
-    size: int               # 字号（半磅单位，22 = 11pt）
-    bold: bool
-    color: Optional[str] = None  # 十六进制颜色，如 "#000000"
-
-# 页边距
-class PageMargins(BaseModel):
-    top: float      # 单位：磅
-    bottom: float
-    left: float
-    right: float
-
-# 模板样式元数据
-class TemplateStyles(BaseModel):
-    headings: list[HeadingStyle]
-    default_font: str
-    default_size: int
-    page_margins: Optional[PageMargins] = None
-    has_header: bool
-    has_footer: bool
+# 单个样式的完整定义
+class StyleDefinition(BaseModel):
+    name: str               # 样式名称，如 "标题 1"
+    style_id: str           # 样式 ID，如 "1"
+    type: str               # 样式类型：paragraph / character / table / numbering
+    builtin: bool           # 是否为内置样式
+    hidden: bool            # 是否隐藏
+    quick_style: bool       # 是否显示在快速样式库
+    priority: Optional[int] # 显示优先级
+    base_style: Optional[str]           # 基础样式名称
+    next_paragraph_style: Optional[str] # 下一段落样式名称
+    font_summary: Optional[dict]        # 字体摘要（name, size_pt, bold, italic 等）
+    paragraph_format_summary: Optional[dict]  # 段落格式摘要（alignment, indent, spacing 等）
+    full_xml_definition: dict           # 完整原始 XML（转换为嵌套字典，保留所有属性和子元素）
+
+# 样式文件摘要（列表展示用）
+class StyleFileSummary(BaseModel):
+    default_font: str           # 正文默认字体，如 "宋体"
+    default_size_pt: float      # 正文默认字号（磅），如 12.0
+    heading_fonts: list[str]    # 各级标题字体列表（H1 到 H6）
+    total_styles: int           # 提取到的样式总数
+    style_types: dict[str, int] # 各类型样式数量，如 {"paragraph": 120, "character": 40}
+
+# 样式文件完整信息（响应）
+class StyleFileResponse(BaseModel):
+    style_id: str               # 样式文件唯一 ID
+    name: str                   # 样式文件名（源文档文件名去扩展名）
+    source_file: str            # 原始上传文件名（含扩展名）
+    summary: StyleFileSummary   # 摘要信息，用于列表展示
+    is_default: bool            # 是否为系统默认样式
+    created_at: datetime
+
+# 样式文件列表项（不含完整样式定义，减少传输量）
+class StyleFileListItem(BaseModel):
+    style_id: str
+    name: str
+    source_file: str
+    summary: StyleFileSummary
+    is_default: bool
+    created_at: datetime
+```
+
+### 后端提取流程
+
+上传文档后，后端执行以下步骤：
+
+1. 使用 `python-docx` 打开上传的 Word 文档（.doc / .docx）
+2. 遍历文档 `doc.styles` 中的所有样式对象
+3. 对每个样式提取：
+   - 基本属性（`name`、`style_id`、`type`、`builtin`、`hidden` 等）
+   - 字体摘要（通过 `style.font` API 读取 `name`、`size_pt`、`bold`、`italic`、`color_rgb` 等）
+   - 段落格式摘要（通过 `style.paragraph_format` API 读取 `alignment`、`indent`、`spacing` 等）
+   - **完整 XML 定义**（对 `style.element` 递归转换为嵌套字典，保留所有属性、子元素和文本节点）
+4. 以上传文件名（去扩展名）命名，序列化为 JSON 保存到存储层
+5. 写入数据库样式缓存记录，返回摘要信息
+
+### 4.1 上传样式（从 Word 文档提取全量样式 XML）
+
+**目的**：用户上传任意 Word 文档，后端提取其中所有样式的完整 XML 定义，生成同名样式文件存入缓存列表，供后续导出时选用。
+
+**接口地址**: `POST /api/v1/styles`
+
+**请求格式**: `multipart/form-data`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file | File | 是 | Word 文档（.doc / .docx），最大 20MB |
+| name | string | 否 | 自定义样式名称；不传时默认使用上传文件名（去扩展名） |
+
+**后端处理说明**：
+
+- 样式文件名默认取自上传文件名（去扩展名），例如上传 `季报模板_2026Q2.docx`，生成样式文件名为 `季报模板_2026Q2`
+- 提取结果以 JSON 格式持久化，字段 `full_xml_definition` 包含每个样式的完整原始 XML，转换为嵌套字典结构，保留所有命名空间属性（`w:`、`w14:` 等）和子元素
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "styleId": "style-001",
+    "name": "季报模板_2026Q2",
+    "sourceFile": "季报模板_2026Q2.docx",
+    "summary": {
+      "defaultFont": "宋体",
+      "defaultSizePt": 12.0,
+      "headingFonts": ["黑体", "黑体", "宋体", "宋体", "宋体", "宋体"],
+      "totalStyles": 164,
+      "styleTypes": {
+        "paragraph": 120,
+        "character": 40,
+        "table": 3,
+        "numbering": 1
+      }
+    },
+    "isDefault": false,
+    "createdAt": 1680000000000
+  }
+}
+```
+
+**错误情况**：
+
+| HTTP 状态码 | 错误码 | 说明 |
+|------------|--------|------|
+| 400 | 4001 | 文件格式不支持（非 .doc / .docx） |
+| 413 | 4002 | 文件超过 20MB 限制 |
+| 422 | 4003 | 文档无法解析（损坏或加密） |
+| 409 | 4004 | 同名样式文件已存在（可用 `?overwrite=true` 强制覆盖） |
+
+---
+
+### 4.2 获取样式列表（样式缓存）
+
+**目的**：返回当前用户的样式缓存列表，包含系统默认样式，供前端展示样式选择器。列表按创建时间倒序排列，每次导出时用户从此列表中选择应用哪个样式。
+
+**接口地址**: `GET /api/v1/styles`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| page | integer | 否 | 页码，默认 1 |
+| pageSize | integer | 否 | 每页数量，默认 20，最大 100 |
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "styles": [
+      {
+        "styleId": "default",
+        "name": "系统默认样式",
+        "sourceFile": null,
+        "summary": {
+          "defaultFont": "宋体",
+          "defaultSizePt": 12.0,
+          "headingFonts": ["黑体", "黑体", "宋体", "宋体", "宋体", "宋体"],
+          "totalStyles": 20,
+          "styleTypes": { "paragraph": 15, "character": 5, "table": 0, "numbering": 0 }
+        },
+        "isDefault": true,
+        "createdAt": 1680000000000
+      },
+      {
+        "styleId": "style-001",
+        "name": "季报模板_2026Q2",
+        "sourceFile": "季报模板_2026Q2.docx",
+        "summary": {
+          "defaultFont": "宋体",
+          "defaultSizePt": 12.0,
+          "headingFonts": ["黑体", "黑体", "宋体", "宋体", "宋体", "宋体"],
+          "totalStyles": 164,
+          "styleTypes": { "paragraph": 120, "character": 40, "table": 3, "numbering": 1 }
+        },
+        "isDefault": false,
+        "createdAt": 1680000000000
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "pageSize": 20,
+      "total": 2,
+      "totalPages": 1
+    }
+  }
+}
+```
+
+---
+
+### 4.3 获取样式详情（含完整 XML 定义）
+
+**目的**：返回指定样式文件的完整信息，包含所有样式的完整 XML 定义，供调试或样式预览使用。
+
+**接口地址**: `GET /api/v1/styles/{styleId}`
+
+**响应示例**（`styles` 数组内每条记录结构）:
+```json
+{
+  "code": 0,
+  "data": {
+    "styleId": "style-001",
+    "name": "季报模板_2026Q2",
+    "sourceFile": "季报模板_2026Q2.docx",
+    "summary": {
+      "defaultFont": "宋体",
+      "defaultSizePt": 12.0,
+      "headingFonts": ["黑体", "黑体", "宋体", "宋体", "宋体", "宋体"],
+      "totalStyles": 164,
+      "styleTypes": { "paragraph": 120, "character": 40, "table": 3, "numbering": 1 }
+    },
+    "isDefault": false,
+    "createdAt": 1680000000000,
+    "styles": [
+      {
+        "name": "标题 1",
+        "styleId": "1",
+        "type": "paragraph",
+        "builtin": true,
+        "hidden": false,
+        "quickStyle": true,
+        "priority": 9,
+        "baseStyle": "正文",
+        "nextParagraphStyle": "正文",
+        "fontSummary": {
+          "name": "黑体",
+          "sizePt": 16.0,
+          "bold": true,
+          "italic": false,
+          "underline": false,
+          "colorRgb": "000000",
+          "strike": false,
+          "allCaps": false,
+          "smallCaps": false
+        },
+        "paragraphFormatSummary": {
+          "alignment": "LEFT",
+          "leftIndentPt": null,
+          "rightIndentPt": null,
+          "firstLineIndentPt": null,
+          "spaceBeforePt": 12.0,
+          "spaceAfterPt": 6.0,
+          "lineSpacing": 1.5,
+          "keepTogether": false,
+          "keepWithNext": true,
+          "pageBreakBefore": false
+        },
+        "fullXmlDefinition": {
+          "@tag": "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}style",
+          "@attrib": {
+            "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}type": "paragraph",
+            "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}styleId": "1"
+          },
+          "@children": {
+            "{...}name": { "@tag": "...", "@attrib": { "{...}val": "heading 1" } },
+            "{...}rPr": { "...": "完整字符属性 XML" },
+            "{...}pPr": { "...": "完整段落属性 XML" }
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+> `fullXmlDefinition` 字段为嵌套字典格式，`@tag` 为完整 Clark 表示法标签名（含命名空间），`@attrib` 为属性字典，`@children` 为子元素字典（同名子元素自动合并为数组）。
+
+---
+
+### 4.4 删除样式
+
+**接口地址**: `DELETE /api/v1/styles/{styleId}`
+
+> 系统默认样式（`styleId: "default"`）不可删除，返回 403。  
+> 若该样式正在被某个文档引用，返回 409，需先解除引用再删除。
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "message": "Style deleted successfully"
+}
+```
+
+---
+
+## 5. 模板管理 API（阶段 1）
+
+用户上传带占位符的 Word 文档作为模板，占位符格式为 `{{名称}}`。导出时后端根据文档内容按标题名称匹配占位符，替换后生成 DOCX。
+
+### 占位符匹配规则
+
+- 占位符名称与 Markdown 文档中的**标题名称完全一致**时匹配，替换为该标题下的完整内容块（含子标题）
+- 匹配不上的占位符**清空**（替换为空字符串）
+- 示例：模板含 `{{一季度回顾}}`，文档中有 `## 一季度回顾`，则该标题及其下文内容替换占位符
+
+### 数据结构
+
+```python
+from pydantic import BaseModel
+from typing import Optional
+from datetime import datetime
 
 # 模板完整信息（响应）
-class DocumentTemplateResponse(BaseModel):
+class TemplateResponse(BaseModel):
     template_id: str
     name: str
-    styles: TemplateStyles
+    placeholders: list[str]     # 模板中所有占位符名称列表，如 ["一季度回顾", "二季度展望"]
+    has_header: bool            # 是否包含页眉
+    has_footer: bool            # 是否包含页脚
     created_at: datetime
 
 # 模板列表项
 class TemplateListItem(BaseModel):
     template_id: str
     name: str
+    placeholders: list[str]
     created_at: datetime
 ```
 
-### 4.1 上传 Word 模板
+### 5.1 上传模板
+
+**目的**：用户上传带占位符的 Word 文档，后端解析出所有 `{{名称}}` 占位符列表并返回，供用户确认模板结构。
 
 **接口地址**: `POST /api/v1/templates`
 
@@ -392,7 +673,7 @@ class TemplateListItem(BaseModel):
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| file | File | 是 | Word 模板文件（.docx），最大 20MB |
+| file | File | 是 | Word 文档（.docx），最大 20MB，需包含 `{{名称}}` 格式占位符 |
 | name | string | 是 | 模板名称 |
 
 **响应示例**:
@@ -401,17 +682,10 @@ class TemplateListItem(BaseModel):
   "code": 0,
   "data": {
     "templateId": "tpl-001",
-    "name": "标准报告模板",
-    "styles": {
-      "headings": [
-        { "level": 1, "font": "宋体", "size": 22, "bold": true },
-        { "level": 2, "font": "宋体", "size": 18, "bold": true }
-      ],
-      "defaultFont": "宋体",
-      "defaultSize": 12,
-      "hasHeader": true,
-      "hasFooter": true
-    },
+    "name": "季度报告模板",
+    "placeholders": ["报告摘要", "一季度回顾", "二季度展望", "风险提示"],
+    "hasHeader": true,
+    "hasFooter": true,
     "createdAt": 1680000000000
   }
 }
@@ -419,7 +693,7 @@ class TemplateListItem(BaseModel):
 
 ---
 
-### 4.2 获取模板信息
+### 5.2 获取模板信息
 
 **接口地址**: `GET /api/v1/templates/{templateId}`
 
@@ -429,8 +703,10 @@ class TemplateListItem(BaseModel):
   "code": 0,
   "data": {
     "templateId": "tpl-001",
-    "name": "标准报告模板",
-    "styles": { ... },
+    "name": "季度报告模板",
+    "placeholders": ["报告摘要", "一季度回顾", "二季度展望", "风险提示"],
+    "hasHeader": true,
+    "hasFooter": true,
     "createdAt": 1680000000000
   }
 }
@@ -438,7 +714,7 @@ class TemplateListItem(BaseModel):
 
 ---
 
-### 4.3 获取模板列表
+### 5.3 获取模板列表
 
 **接口地址**: `GET /api/v1/templates`
 
@@ -450,7 +726,8 @@ class TemplateListItem(BaseModel):
     "templates": [
       {
         "templateId": "tpl-001",
-        "name": "标准报告模板",
+        "name": "季度报告模板",
+        "placeholders": ["报告摘要", "一季度回顾", "二季度展望", "风险提示"],
         "createdAt": 1680000000000
       }
     ]
@@ -460,55 +737,81 @@ class TemplateListItem(BaseModel):
 
 ---
 
-## 5. 导出 API（阶段 1）
+### 5.4 删除模板
+
+**接口地址**: `DELETE /api/v1/templates/{templateId}`
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "message": "Template deleted successfully"
+}
+```
+
+---
+
+## 6. 导出 DOCX API（阶段 1）
 
 ### 数据结构
 
 ```python
 from pydantic import BaseModel
 
-# 导出 DOCX（保持模板格式）请求
+# 导出 DOCX（模板填充）请求
 class ExportDocxRequest(BaseModel):
-    document_id: str  # 文档 ID，需有关联 template_id
+    document_id: str    # 文档 ID，后端查文档内容并按标题匹配占位符
+    template_id: str    # 模板 ID，必须指定
 
 # 响应为文件流，HTTP Header 如下：
 # Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
 # Content-Disposition: attachment; filename="{title}.docx"
 ```
 
-### 5.1 下载 DOCX（保持模板格式）
+### 6.1 导出 DOCX（模板填充）
+
+**触发时机**：用户在编辑器中选择了模板并完成编辑后，点击"下载"按钮时触发。  
+**目的**：后端以指定模板为基础，解析文档 Markdown 内容按标题拆分为内容块，按标题名称匹配模板中的 `{{占位符}}`，替换后生成 DOCX。输出文件的字体、样式、页眉页脚完全继承模板。  
 
-**触发时机**：工作流文档编辑完成后，用户点击"下载"按钮时触发。  
-**目的**：将编辑器中的最新内容与原始 Word 模板合并，生成 DOCX 文件并直接返回文件流，前端触发下载。下载的文件字体、标题样式、页眉页脚与原模板完全一致。  
-**与阶段 0 导出的区别**：阶段 0 导出不依赖模板，直接将 Markdown 转为 .doc；本接口需要关联模板，目的是保证格式与模板一致。
+**后端处理流程**：
+1. 根据 `documentId` 查文档内容（Markdown）
+2. 根据 `templateId` 加载模板文件和占位符列表
+3. 将 Markdown 按标题拆分为内容块（标题名 → 内容）
+4. 遍历占位符，标题名称匹配则替换为对应内容，匹配不上则清空
+5. 生成 DOCX 文件流返回
 
 **接口地址**: `POST /api/v1/export/docx`
 
 **请求体**:
 ```json
 {
-  "documentId": "doc-abc123"
+  "documentId": "doc-abc123",
+  "templateId": "tpl-001"
 }
 ```
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| documentId | string | 是 | 文档 ID，需有关联 templateId |
-
-**响应**:
+| documentId | string | 是 | 文档 ID，后端据此获取内容并拆分内容块 |
+| templateId | string | 是 | 模板 ID，决定输出文件的结构和样式 |
 
-直接返回 DOCX 文件流，前端触发浏览器下载。
+**响应**：直接返回 DOCX 文件流，前端触发浏览器下载。
 
 ```
 Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
-Content-Disposition: attachment; filename="document.docx"
+Content-Disposition: attachment; filename="{title}.docx"
 ```
 
-> 若文档无关联模板，则以默认样式生成 DOCX。
+**错误情况**：
+
+| 错误码 | 说明 |
+|--------|------|
+| 404 | documentId 或 templateId 不存在 |
+| 422 | 文档内容为空，无法生成 |
 
 ---
 
-## 6. 编辑会话 API（阶段 2）
+## 7. 编辑会话 API（阶段 2）
 
 ### 数据结构
 
@@ -552,7 +855,7 @@ class SessionDocumentResponse(BaseModel):
     session_info: SessionInfo
 ```
 
-### 6.1 创建编辑会话
+### 7.1 创建编辑会话
 
 **触发时机**：oil-agent 需要让用户编辑某份文档时，由 oil-agent 后端调用此接口。  
 **目的**：生成一个与指定文档绑定的临时 Token 和编辑器 URL，供 oil-agent 将 URL 传给用户打开，实现免登录访问编辑器。Token 与文档 ID 强绑定，无法访问其他文档。
@@ -591,7 +894,7 @@ class SessionDocumentResponse(BaseModel):
 
 ---
 
-### 6.2 凭 Token 获取文档
+### 7.2 凭 Token 获取文档
 
 **触发时机**：编辑器页面加载时，用 URL 中的 Token 换取文档内容。  
 **目的**：校验 Token 有效性，返回对应文档内容和权限信息，完成免登录鉴权。
@@ -624,7 +927,7 @@ class SessionDocumentResponse(BaseModel):
 
 ---
 
-### 6.3 关闭编辑会话
+### 7.3 关闭编辑会话
 
 **触发时机**：用户关闭编辑器或 oil-agent 主动撤回访问权限时。  
 **目的**：立即撤销 Token，使该链接失效，防止 Token 被复用。
@@ -643,7 +946,7 @@ class SessionDocumentResponse(BaseModel):
 
 ---
 
-## 7. Webhook 通知（阶段 2）
+## 8. Webhook 通知（阶段 2）
 
 ### 数据结构
 
@@ -671,7 +974,7 @@ class SessionClosedData(BaseModel):
     duration: int   # 会话持续时长（秒）
 ```
 
-### 7.1 配置 Webhook
+### 8.1 配置 Webhook
 
 **接口地址**: `POST /api/v1/webhooks`
 
@@ -684,7 +987,7 @@ class SessionClosedData(BaseModel):
 }
 ```
 
-### 7.2 Webhook 事件格式
+### 8.2 Webhook 事件格式
 
 #### document.updated
 ```json
@@ -713,7 +1016,7 @@ class SessionClosedData(BaseModel):
 }
 ```
 
-### 7.3 签名验证
+### 8.3 签名验证
 
 请求头: `X-Axonix-Signature: sha256=<hmac_hex>`
 
@@ -727,7 +1030,7 @@ def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
 
 ---
 
-## 8. 导出扩展 API（阶段 3）
+## 9. 导出扩展 API（阶段 3）
 
 ### 数据结构
 
@@ -751,7 +1054,7 @@ class ExportPdfRequest(BaseModel):
 # Content-Disposition: attachment; filename="{title}.pdf"
 ```
 
-### 8.1 导出为 PDF
+### 9.1 导出为 PDF
 
 **接口地址**: `POST /api/v1/export/pdf`
 
@@ -777,7 +1080,7 @@ Content-Disposition: attachment; filename="document.pdf"
 
 ---
 
-## 9. 版本管理 API（阶段 3）
+## 10. 版本管理 API（阶段 3）
 
 ### 数据结构
 
@@ -809,7 +1112,7 @@ class RestoreVersionResponse(BaseModel):
     updated_at: datetime
 ```
 
-### 9.1 获取版本历史
+### 10.1 获取版本历史
 
 **接口地址**: `GET /api/v1/documents/{documentId}/versions`
 
@@ -830,7 +1133,7 @@ class RestoreVersionResponse(BaseModel):
 }
 ```
 
-### 9.2 回滚版本
+### 10.2 回滚版本
 
 **接口地址**: `POST /api/v1/documents/{documentId}/versions/{versionId}/restore`
 
@@ -846,7 +1149,7 @@ class RestoreVersionResponse(BaseModel):
 }
 ```
 
-### 9.3 版本对比
+### 10.3 版本对比
 
 **接口地址**: `GET /api/v1/documents/{documentId}/versions/diff?from={versionId}&to={versionId}`
 
@@ -866,7 +1169,7 @@ class RestoreVersionResponse(BaseModel):
 
 ---
 
-## 10. 限流与配额
+## 11. 限流与配额
 
 | 接口类型 | 限制 | 窗口期 |
 |---------|------|--------|
@@ -879,7 +1182,7 @@ class RestoreVersionResponse(BaseModel):
 
 ---
 
-## 11. 测试环境
+## 12. 测试环境
 
 - **Base URL**: `https://api-dev.axonix.com`
 - **测试文档 ID**: `test-doc-001`

tmp/styles.py

@@ -0,0 +1,195 @@
+"""
+提取 Word 文档中所有样式的完整 XML 定义（不遗漏任何属性）。
+目标文件: 2026年Q2季度报告_E-EdHk4r1Lg.doc
+"""
+
+import json
+from pathlib import Path
+from docx import Document
+from docx.oxml.ns import qn
+from lxml import etree
+
+DOC_PATH = Path(__file__).parent / "default.docx"
+OUTPUT_PATH = Path(__file__).parent / "default.json"
+
+
+def emu_to_pt(emu) -> float | None:
+    """EMU 转磅（1 pt = 12700 EMU）"""
+    if emu is None:
+        return None
+    return round(int(emu) / 12700, 2)
+
+
+def extract_font(style) -> dict | None:
+    """通过 API 提取字体信息（作为便捷摘要）"""
+    try:
+        f = style.font
+        color_rgb = None
+        try:
+            if f.color and f.color.type:
+                color_rgb = str(f.color.rgb)
+        except Exception:
+            pass
+        return {
+            "name": f.name,
+            "size_pt": emu_to_pt(f.size),
+            "bold": f.bold,
+            "italic": f.italic,
+            "underline": f.underline,
+            "color_rgb": color_rgb,
+            "strike": f.strike,
+            "all_caps": f.all_caps,
+            "small_caps": f.small_caps,
+        }
+    except Exception:
+        return None
+
+
+def extract_paragraph_format(style) -> dict | None:
+    """通过 API 提取段落格式（作为便捷摘要）"""
+    try:
+        pf = style.paragraph_format
+        return {
+            "alignment": str(pf.alignment) if pf.alignment else None,
+            "left_indent_pt": emu_to_pt(pf.left_indent),
+            "right_indent_pt": emu_to_pt(pf.right_indent),
+            "first_line_indent_pt": emu_to_pt(pf.first_line_indent),
+            "space_before_pt": emu_to_pt(pf.space_before),
+            "space_after_pt": emu_to_pt(pf.space_after),
+            "line_spacing": float(pf.line_spacing) if pf.line_spacing else None,
+            "keep_together": pf.keep_together,
+            "keep_with_next": pf.keep_with_next,
+            "page_break_before": pf.page_break_before,
+        }
+    except Exception:
+        return None
+
+
+def element_to_dict(elem: etree._Element) -> dict | list | str | None:
+    """
+    将 lxml Element 转换为字典，完整保留标签、属性、文本和子元素。
+    处理重复子元素（转为列表）。
+    使用 '{namespace}localname' 格式作为标签名。
+    """
+    # 标签名（完整 Clark 表示法）
+    tag = elem.tag
+
+    # 属性字典
+    attrib = dict(elem.attrib)
+
+    # 子元素处理
+    children = list(elem)
+    if children:
+        # 子元素可能重复，使用字典存储列表
+        child_dict = {}
+        for child in children:
+            child_tag = child.tag
+            child_val = element_to_dict(child)
+            if child_tag in child_dict:
+                # 相同标签名出现多次，转为列表
+                if not isinstance(child_dict[child_tag], list):
+                    child_dict[child_tag] = [child_dict[child_tag]]
+                child_dict[child_tag].append(child_val)
+            else:
+                child_dict[child_tag] = child_val
+        # 合并文本：如果存在文本（非空白），作为 '#text' 字段
+        text = elem.text.strip() if elem.text else None
+        tail = elem.tail.strip() if elem.tail else None
+        result = {"@tag": tag, "@attrib": attrib, "@children": child_dict}
+        if text:
+            result["#text"] = text
+        if tail:
+            result["#tail"] = tail
+        return result
+    else:
+        # 叶子节点：直接返回文本或属性+文本
+        text = elem.text.strip() if elem.text else None
+        tail = elem.tail.strip() if elem.tail else None
+        if attrib or text or tail:
+            result = {"@tag": tag, "@attrib": attrib}
+            if text:
+                result["#text"] = text
+            if tail:
+                result["#tail"] = tail
+            return result
+        else:
+            # 完全空的元素，可简化为 None 但保持结构
+            return {"@tag": tag, "@attrib": attrib}
+
+
+def extract_style_full_xml(style) -> dict:
+    """提取样式的完整 XML 定义（转换为字典）"""
+    elem = style.element
+    if elem is None:
+        return None
+    # 整个样式元素转换为字典
+    style_dict = element_to_dict(elem)
+    return style_dict
+
+
+def extract_styles(doc_path: Path) -> list[dict]:
+    doc = Document(str(doc_path))
+    styles_data = []
+
+    for style in doc.styles:
+        info = {
+            "name": style.name,
+            "style_id": style.style_id,
+            "type": str(style.type),
+            "builtin": style.builtin,
+            "hidden": style.hidden,
+            "quick_style": style.quick_style,
+            "priority": style.priority,
+            "base_style": (
+                style.base_style.name
+                if hasattr(style, "base_style") and style.base_style
+                else None
+            ),
+            "next_paragraph_style": (
+                style.next_paragraph_style.name
+                if hasattr(style, "next_paragraph_style") and style.next_paragraph_style
+                else None
+            ),
+            "font_summary": extract_font(style),      # 便捷摘要
+            "paragraph_format_summary": extract_paragraph_format(style),  # 便捷摘要
+            "full_xml_definition": extract_style_full_xml(style)   # 完整原始定义
+        }
+        styles_data.append(info)
+
+    return styles_data
+
+
+def main():
+    print(f"读取文件: {DOC_PATH}")
+    if not DOC_PATH.exists():
+        raise FileNotFoundError(f"文件不存在: {DOC_PATH}")
+
+    styles_data = extract_styles(DOC_PATH)
+
+    result = {
+        "source_file": DOC_PATH.name,
+        "total_styles": len(styles_data),
+        "styles": styles_data,
+    }
+
+    OUTPUT_PATH.write_text(
+        json.dumps(result, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+    print(f"共提取 {len(styles_data)} 个样式")
+    print(f"完整 XML 定义已保存至: {OUTPUT_PATH}")
+
+    # 打印摘要
+    by_type: dict[str, list[str]] = {}
+    for s in styles_data:
+        t = s["type"]
+        by_type.setdefault(t, []).append(s["name"])
+
+    print("\n--- 样式类型分布 ---")
+    for t, names in by_type.items():
+        print(f"  {t}: {len(names)} 个")
+
+
+if __name__ == "__main__":
+    main()