feat(api): 优化 Block API 文档和数据库操作逻辑

- 简化 create_block 和 _build_toc_tree 函数文档为单行注释
- 精简 BlockCreate 和 TOCMetadata Schema 文档，移除冗余说明
- 重构 ContentDB 索引创建代码，改为单行语句提高可读性
- 提取 _build_type_filter、_query_next_value 等通用查询方法
- 优化 calculate_index_for_insert 逻辑，使用 _calculate_sparse_value 统一处理
- 简化 image_service 和 storage_monitor 配置管理代码
- 规范化文件模块文档注释格式
- 移除 schema 文件多余空行，保持代码风格一致

app/api/v1/blocks.py

@@ -25,22 +25,7 @@ async def create_block(
     body: BlockCreate,
     db: AsyncSession = Depends(get_db),
 ) -> dict:
-    """在指定位置插入新 block
-    
-    Args:
-        documentId: 文档 ID
-        body: Block 创建请求
-            - type: Block 类型（heading/paragraph/table/image/toc）
-            - content: Block 内容
-            - level: 标题级别（heading 必填：1-6，其他类型固定为 0）
-            - word_style: Word 样式名（可选）
-            - style: 自定义样式（可选）
-            - metadata: 元数据（可选）
-            - after_block_id: 插入位置（null = 末尾）
-    
-    Returns:
-        包含新 block ID 的响应
-    """
+    """在指定位置插入新 block（type, content, level, style, after_block_id，返回 blockId）"""
     # 1. 参数校验
     if body.type == 'heading':
         if body.level not in range(1, 7):
@@ -250,14 +235,7 @@ async def get_stats(
 
 
 def _build_toc_tree(headings: list[dict]) -> list[dict]:
-    """构建目录树
-    
-    Args:
-        headings: 标题 block 列表
-        
-    Returns:
-        树形结构的目录
-    """
+    """构建目录树（headings 列表 -> 树形结构）"""
     root = []
     stack = []
     

app/schemas/block.py

@@ -1,10 +1,7 @@
 """block.py — Block 相关 Schema"""
-
 from typing import Optional
-
 from pydantic import BaseModel, Field
 
-
 class BlockBase(BaseModel):
     """Block 基础信息"""
     id: str = Field(..., validation_alias="id", serialization_alias="id")
@@ -20,7 +17,6 @@ class BlockBase(BaseModel):
     class Config:
         populate_by_name = True
 
-
 class BlockUpdate(BaseModel):
     """Block 更新请求"""
     content: Optional[str | dict | list] = None
@@ -28,14 +24,8 @@ class BlockUpdate(BaseModel):
     word_style: Optional[str] = None
     metadata: Optional[dict] = None
 
-
 class BlockCreate(BaseModel):
-    """Block 创建请求
-    
-    注意：
-    - id, index, block_order 由后端自动生成，前端无需提供
-    - level 对于 heading 类型是必填的（1-6），其他类型固定为 0（可省略）
-    """
+    """Block 创建请求（id/index/block_order 自动生成，heading 需 level 1-6，其他类型 level=0）"""
     type: str
     level: int = 0  # heading 类型必填（1-6），其他类型默认 0
     content: str | dict | list
@@ -44,12 +34,10 @@ class BlockCreate(BaseModel):
     metadata: dict = {}
     after_block_id: Optional[str] = None  # 在哪个 block 后插入（null = 末尾）
 
-
 class TOCContent(BaseModel):
     """TOC Block content 结构"""
     title: str = "目录"
 
-
 class TOCConfig(BaseModel):
     """TOC 配置"""
     levels: str = "1-1"  # 包含的标题层级
@@ -60,7 +48,6 @@ class TOCConfig(BaseModel):
     show_leader_dots: bool = True
     leader_char: str = "."
 
-
 class TOCMetadata(BaseModel):
     """TOC Block metadata 结构"""
     toc_config: TOCConfig
@@ -68,7 +55,6 @@ class TOCMetadata(BaseModel):
     readonly: bool = True
     deletable: bool = True
 
-
 class TOCBlock(BaseModel):
     """完整的 TOC Block"""
     id: str
@@ -83,7 +69,6 @@ class TOCBlock(BaseModel):
     class Config:
         populate_by_name = True
 
-
 class TOCItem(BaseModel):
     """目录树节点"""
     id: str
@@ -91,17 +76,15 @@ class TOCItem(BaseModel):
     content: str
     children: list['TOCItem'] = []
 
-
 class BlockSearchResult(BaseModel):
     """Block 搜索结果"""
     blocks: list[BlockBase]
     total: int
 
-
 class BlockStats(BaseModel):
     """Block 统计信息"""
     total: int
     by_type: dict[str, int] = Field(..., alias="byType")
     
     class Config:
-        populate_by_name = True
+        populate_by_name = True

app/services/content_db.py

@@ -1,5 +1,4 @@
-"""content_db.py — SQLite 内容数据库操作类"""
-
+"""SQLite 内容数据库操作类"""
 import json
 import sqlite3
 from pathlib import Path
@@ -7,10 +6,7 @@ from typing import Optional
 
 
 class ContentDB:
-    """SQLite 内容数据库操作类
-    
-    每个文档对应一个独立的 SQLite 数据库文件，存储文档的所有 Blocks。
-    """
+    """SQLite 内容数据库操作类，每个文档对应一个独立的 SQLite 数据库文件"""
     
     def __init__(self, db_path: str):
         self.db_path = Path(db_path)
@@ -51,17 +47,9 @@ class ContentDB:
                 metadata TEXT DEFAULT '{}'
             )
         """)
-        
-        # 创建索引
-        self.conn.execute(
-            'CREATE INDEX IF NOT EXISTS idx_block_order ON document_blocks(block_order)'
-        )
-        self.conn.execute(
-            'CREATE INDEX IF NOT EXISTS idx_type ON document_blocks(type)'
-        )
-        self.conn.execute(
-            'CREATE INDEX IF NOT EXISTS idx_level ON document_blocks(level)'
-        )
+        self.conn.execute('CREATE INDEX IF NOT EXISTS idx_block_order ON document_blocks(block_order)')
+        self.conn.execute('CREATE INDEX IF NOT EXISTS idx_type ON document_blocks(type)')
+        self.conn.execute('CREATE INDEX IF NOT EXISTS idx_level ON document_blocks(level)')
         self.conn.commit()
     
     def insert_blocks(self, blocks: list[dict]):
@@ -186,198 +174,98 @@ class ContentDB:
             'by_type': stats
         }
     
-    def calculate_index_for_insert(
-        self,
-        after_block_id: str,
-        new_type: str,
-        new_level: int = 0
+    def _build_type_filter(self, block_type: str, level: Optional[int] = None) -> tuple[str, list]:
+        """构建类型过滤条件（用于 index 查询）"""
+        if block_type == 'heading' and level is not None:
+            return "type = ? AND level = ?", [block_type, level]
+        return "type = ?", [block_type]
+    
+    def _query_next_value(self, field: str, after_order: int, type_filter: str, params: list) -> Optional[int]:
+        """查询下一个值（index 或 block_order）"""
+        sql = f'SELECT "{field}" FROM document_blocks WHERE {type_filter} AND block_order > ? ORDER BY block_order LIMIT 1'
+        cursor = self.conn.execute(sql, params + [after_order])
+        row = cursor.fetchone()
+        return row[field] if row else None
+    
+    def _query_prev_value(self, field: str, after_order: int, type_filter: str, params: list) -> Optional[int]:
+        """查询前一个值（index 或 block_order）"""
+        sql = f'SELECT "{field}" FROM document_blocks WHERE {type_filter} AND block_order <= ? ORDER BY block_order DESC LIMIT 1'
+        cursor = self.conn.execute(sql, params + [after_order])
+        row = cursor.fetchone()
+        return row[field] if row else None
+    
+    def _query_max_value(self, field: str, type_filter: str, params: list) -> Optional[int]:
+        """查询最大值（index 或 block_order）"""
+        sql = f'SELECT MAX("{field}") as max_val FROM document_blocks'
+        if type_filter:
+            sql += f' WHERE {type_filter}'
+        cursor = self.conn.execute(sql, params)
+        row = cursor.fetchone()
+        return row['max_val']
+    
+    def _calculate_sparse_value(
+        self, 
+        field: str,
+        after_block_id: Optional[str],
+        type_filter: str,
+        params: list,
+        default_min: int,
+        rebalance_func: callable
     ) -> int:
-        """计算插入 block 的 index（稀疏排序）
-        
-        Args:
-            after_block_id: 在哪个 block 后插入（如果为 None 则插入到末尾）
-            new_type: 新 block 的类型
-            new_level: 新 block 的级别（标题有效）
-            
-        Returns:
-            计算得到的 index
-        """
+        """通用稀疏值计算逻辑"""
         if after_block_id:
-            # 1. 获取 after_block 的 block_order
             after_block = self.get_block_by_id(after_block_id)
             if not after_block:
                 raise ValueError(f"Block not found: {after_block_id}")
             after_order = after_block['block_order']
             
-            # 2. 查找下一个同类型同级别的 block
-            if new_type == 'heading':
-                # 标题：按 level 查询
-                cursor = self.conn.execute("""
-                    SELECT "index" FROM document_blocks
-                    WHERE type = ? AND level = ? AND block_order > ?
-                    ORDER BY block_order LIMIT 1
-                """, (new_type, new_level, after_order))
-            else:
-                # 其他类型：只按 type 查询
-                cursor = self.conn.execute("""
-                    SELECT "index" FROM document_blocks
-                    WHERE type = ? AND block_order > ?
-                    ORDER BY block_order LIMIT 1
-                """, (new_type, after_order))
+            next_val = self._query_next_value(field, after_order, type_filter, params)
             
-            next_row = cursor.fetchone()
-            
-            if next_row:
-                next_index = next_row['index']
-                
-                # 3. 查找前一个同类型同级别的 block
-                if new_type == 'heading':
-                    cursor = self.conn.execute("""
-                        SELECT "index" FROM document_blocks
-                        WHERE type = ? AND level = ? AND block_order <= ?
-                        ORDER BY block_order DESC LIMIT 1
-                    """, (new_type, new_level, after_order))
-                else:
-                    cursor = self.conn.execute("""
-                        SELECT "index" FROM document_blocks
-                        WHERE type = ? AND block_order <= ?
-                        ORDER BY block_order DESC LIMIT 1
-                    """, (new_type, after_order))
-                
-                prev_row = cursor.fetchone()
-                prev_index = prev_row['index'] if prev_row else -100
+            if next_val is not None:
+                prev_val = self._query_prev_value(field, after_order, type_filter, params)
+                if prev_val is None:
+                    prev_val = default_min
                 
-                # 4. 计算中间值
-                gap = next_index - prev_index
+                gap = next_val - prev_val
                 if gap <= 1:
-                    # 间隙不足，触发局部重排
-                    self._rebalance_indexes_between(
-                        new_type, new_level, prev_index, next_index
-                    )
-                    # 重新查询
-                    if new_type == 'heading':
-                        cursor = self.conn.execute("""
-                            SELECT "index" FROM document_blocks
-                            WHERE type = ? AND level = ? AND block_order > ?
-                            ORDER BY block_order LIMIT 1
-                        """, (new_type, new_level, after_order))
-                    else:
-                        cursor = self.conn.execute("""
-                            SELECT "index" FROM document_blocks
-                            WHERE type = ? AND block_order > ?
-                            ORDER BY block_order LIMIT 1
-                        """, (new_type, after_order))
-                    next_row = cursor.fetchone()
-                    next_index = next_row['index'] if next_row else prev_index + 200
+                    rebalance_func(prev_val, next_val)
+                    next_val = self._query_next_value(field, after_order, type_filter, params)
+                    if next_val is None:
+                        next_val = prev_val + 200
                 
-                new_index = (prev_index + next_index) // 2
+                return (prev_val + next_val) // 2
             else:
-                # 没有下一个同类 block，追加到最后
-                if new_type == 'heading':
-                    cursor = self.conn.execute("""
-                        SELECT MAX("index") as max_index FROM document_blocks
-                        WHERE type = ? AND level = ?
-                    """, (new_type, new_level))
-                else:
-                    cursor = self.conn.execute("""
-                        SELECT MAX("index") as max_index FROM document_blocks
-                        WHERE type = ?
-                    """, (new_type,))
-                
-                row = cursor.fetchone()
-                max_index = row['max_index'] if row['max_index'] is not None else -100
-                new_index = max_index + 100
+                max_val = self._query_max_value(field, type_filter, params)
+                return (max_val if max_val is not None else default_min) + 100
         else:
-            # 插入到文档末尾
-            if new_type == 'heading':
-                cursor = self.conn.execute("""
-                    SELECT MAX("index") as max_index FROM document_blocks
-                    WHERE type = ? AND level = ?
-                """, (new_type, new_level))
-            else:
-                cursor = self.conn.execute("""
-                    SELECT MAX("index") as max_index FROM document_blocks
-                    WHERE type = ?
-                """, (new_type,))
-            
-            row = cursor.fetchone()
-            max_index = row['max_index'] if row['max_index'] is not None else -100
-            new_index = max_index + 100
-        
-        return new_index
+            max_val = self._query_max_value(field, type_filter, params)
+            return (max_val if max_val is not None else default_min) + 100
+    
+    def calculate_index_for_insert(self, after_block_id: str, new_type: str, new_level: int = 0) -> int:
+        """计算插入 block 的 index（稀疏排序）"""
+        type_filter, params = self._build_type_filter(new_type, new_level)
+        return self._calculate_sparse_value(
+            field='index',
+            after_block_id=after_block_id,
+            type_filter=type_filter,
+            params=params,
+            default_min=-100,
+            rebalance_func=lambda prev, next: self._rebalance_indexes_between(new_type, new_level, prev, next)
+        )
     
     def calculate_block_order_for_insert(self, after_block_id: str = None) -> int:
-        """计算插入 block 的 block_order（稀疏排序）
-        
-        Args:
-            after_block_id: 在哪个 block 后插入（如果为 None 则插入到末尾）
-            
-        Returns:
-            计算得到的 block_order
-        """
-        if after_block_id:
-            # 1. 获取 after_block 的 block_order
-            after_block = self.get_block_by_id(after_block_id)
-            if not after_block:
-                raise ValueError(f"Block not found: {after_block_id}")
-            after_order = after_block['block_order']
-            
-            # 2. 查询下一个 block 的 block_order
-            cursor = self.conn.execute("""
-                SELECT block_order FROM document_blocks
-                WHERE block_order > ?
-                ORDER BY block_order LIMIT 1
-            """, (after_order,))
-            
-            next_row = cursor.fetchone()
-            
-            if next_row:
-                next_order = next_row['block_order']
-                gap = next_order - after_order
-                
-                # 3. 检查间隙是否足够
-                if gap <= 1:
-                    # 触发局部重排
-                    self._rebalance_block_orders_between(after_order, next_order)
-                    # 重新查询
-                    cursor = self.conn.execute("""
-                        SELECT block_order FROM document_blocks
-                        WHERE block_order > ?
-                        ORDER BY block_order LIMIT 1
-                    """, (after_order,))
-                    next_row = cursor.fetchone()
-                    next_order = next_row['block_order'] if next_row else after_order + 200
-                
-                # 4. 计算中间值
-                return (after_order + next_order) // 2
-            else:
-                # 没有下一个 block，插入到最后
-                return after_order + 100
-        else:
-            # 插入到文档末尾
-            cursor = self.conn.execute("""
-                SELECT MAX(block_order) as max_order FROM document_blocks
-            """)
-            row = cursor.fetchone()
-            max_order = row['max_order'] if row['max_order'] is not None else 0
-            return max_order + 100
+        """计算插入 block 的 block_order（稀疏排序）"""
+        return self._calculate_sparse_value(
+            field='block_order',
+            after_block_id=after_block_id,
+            type_filter='1=1',
+            params=[],
+            default_min=0,
+            rebalance_func=self._rebalance_block_orders_between
+        )
     
-    def _rebalance_indexes_between(
-        self,
-        block_type: str,
-        level: int,
-        start_index: int,
-        end_index: int
-    ):
-        """局部重排：重新分配区间内同类型同级别 blocks 的 index
-        
-        Args:
-            block_type: Block 类型
-            level: 级别（标题有效）
-            start_index: 起始 index
-            end_index: 结束 index
-        """
-        # 查询区间内的所有同类型同级别 blocks
+    def _rebalance_indexes_between(self, block_type: str, level: int, start_index: int, end_index: int):
+        """局部重排：重新分配区间内同类型同级别 blocks 的 index"""
         if block_type == 'heading':
             cursor = self.conn.execute("""
                 SELECT id, "index" 
@@ -398,12 +286,9 @@ class ContentDB:
         if not blocks:
             return
         
-        # 计算新的间隔
         count = len(blocks)
         gap = end_index - start_index
         step = gap // (count + 1)
-        
-        # 重新分配 index
         new_index = start_index
         for block in blocks:
             new_index += step
@@ -415,13 +300,7 @@ class ContentDB:
         self.conn.commit()
     
     def _rebalance_block_orders_between(self, start_order: int, end_order: int):
-        """局部重排：重新分配区间内所有 blocks 的 block_order
-        
-        Args:
-            start_order: 起始 block_order
-            end_order: 结束 block_order
-        """
-        # 查询区间内的所有 blocks
+        """局部重排：重新分配区间内所有 blocks 的 block_order"""
         cursor = self.conn.execute("""
             SELECT id, block_order 
             FROM document_blocks 
@@ -434,12 +313,9 @@ class ContentDB:
         if not blocks:
             return
         
-        # 计算新的间隔
         count = len(blocks)
         gap = end_order - start_order
         step = gap // (count + 1)
-        
-        # 重新分配 block_order
         new_order = start_order
         for block in blocks:
             new_order += step
@@ -453,8 +329,6 @@ class ContentDB:
     def _row_to_dict(self, row) -> dict:
         """将 sqlite3.Row 转换为字典"""
         d = dict(row)
-        
-        # 解析 JSON 字段
         if d.get('style'):
             try:
                 d['style'] = json.loads(d['style'])
@@ -470,28 +344,17 @@ class ContentDB:
                 d['metadata'] = {}
         else:
             d['metadata'] = {}
-        
-        # content 可能是 JSON（富文本或表格）
         if d.get('content'):
             try:
                 d['content'] = json.loads(d['content'])
             except (json.JSONDecodeError, TypeError):
-                pass  # 保持原字符串
+                pass
         
         return d
     
     @staticmethod
     def generate_block_id(block_type: str, level: int, index: int) -> str:
-        """生成 Block ID
-        
-        Args:
-            block_type: Block 类型
-            level: 级别（标题有效）
-            index: 序号
-            
-        Returns:
-            生成的 Block ID
-        """
+        """生成 Block ID"""
         if block_type == 'heading':
             return f'block-h{level}-{index}'
         elif block_type == 'paragraph':
@@ -503,4 +366,4 @@ class ContentDB:
         elif block_type == 'toc':
             return f'block-toc-{index}'
         else:
-            return f'block-{block_type}-{index}'
+            return f'block-{block_type}-{index}'

app/services/export_service.py

@@ -1,5 +1,4 @@
 """export_service.py — 将 Blocks 转换为 .doc 文件并返回永久下载链接"""
-
 import base64
 import io
 import json
@@ -7,6 +6,8 @@ import time
 import unicodedata
 from pathlib import Path
 from typing import Optional
+import platform
+import os
 
 from docx import Document
 from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT
@@ -26,23 +27,7 @@ from app.core.exceptions import ExportError
 # ------------------------------------------------------------------ #
 
 def update_document_fields(file_path: str) -> bool:
-    """使用 WPS/Word COM API 更新文档中的所有域（目录、页码等）
-    
-    Args:
-        file_path: 文档文件路径（绝对路径）
-        
-    Returns:
-        bool: 更新是否成功
-        
-    Note:
-        - 仅在 Windows 平台且安装了 WPS/Word 时可用
-        - 如果更新失败，不影响原文件（会有错误日志）
-        - 更新会直接覆盖原文件
-        - 支持 .docx 和 .doc 格式
-    """
-    import platform
-    import os
-    
+    """使用 WPS/Word COM API 更新文档域（目录、页码等），支持 .docx/.doc，仅 Windows 可用"""
     # 仅在 Windows 平台尝试更新
     if platform.system() != 'Windows':
         print(f"提示: 非 Windows 平台，跳过域更新（文档可在打开时自动更新）")
@@ -119,7 +104,6 @@ def update_document_fields(file_path: str) -> bool:
         print(f"警告: 启动 WPS/Word 失败: {e}")
         return False
 
-
 # ------------------------------------------------------------------ #
 # 样式文件加载
 # ------------------------------------------------------------------ #
@@ -140,7 +124,6 @@ def load_style_file(style_id: Optional[str] = None) -> dict:
     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] = {}
@@ -151,7 +134,6 @@ def build_style_map(style_data: dict) -> dict[str, dict]:
             mapping[s["name"]] = s
     return mapping
 
-
 # ------------------------------------------------------------------ #
 # JSON ↔ lxml 互转
 # ------------------------------------------------------------------ #
@@ -170,7 +152,6 @@ def dict_to_element(d: dict) -> etree._Element:
                 elem.append(dict_to_element(item))
     return elem
 
-
 def inject_styles_from_json(doc: Document, style_data: dict) -> None:
     """将 JSON 中所有样式的 full_xml_definition upsert 到文档 <w:styles> 节点"""
     styles_element = doc.styles.element
@@ -196,7 +177,6 @@ def inject_styles_from_json(doc: Document, style_data: dict) -> None:
     inject_numbering_from_json(doc, style_data)
     
     # 强制清除 python-docx 的样式缓存，确保后续使用的是新注入的样式
-    # 这一步很重要，因为 python-docx 会缓存样式对象
     try:
         # 清除样式字典缓存，强制重新从 XML 读取
         if hasattr(doc.styles, '_element'):
@@ -205,18 +185,12 @@ def inject_styles_from_json(doc: Document, style_data: dict) -> None:
     except Exception:
         pass
 
-
 def inject_numbering_from_json(doc: Document, style_data: dict) -> None:
-    """将 JSON 中的编号格式定义注入到文档
-    
-    由于 python-docx 对 numbering part 的支持有限，
-    我们需要在保存后通过修改 ZIP 文件来注入编号格式。
-    这个函数主要是为了记录编号定义，实际注入在 blocks_to_docx_bytes 中完成。
-    """
+    """注入编号格式到文档 numbering.xml（python-docx 不支持，通过修改 ZIP 实现）"""
+
     # 暂时不在这里注入，而是在生成文档后通过 ZIP 修改
     pass
 
-
 def _resolve_style_id(style_map: dict, *keys: str) -> Optional[str]:
     """解析样式 ID"""
     for key in keys:
@@ -225,7 +199,6 @@ def _resolve_style_id(style_map: dict, *keys: str) -> Optional[str]:
             return entry["style_id"]
     return None
 
-
 def _apply_paragraph_style(para, style: dict):
     """应用段落级样式（对齐方式、行距、缩进等）"""
     # 对齐方式
@@ -263,7 +236,6 @@ def _apply_paragraph_style(para, style: dict):
         except Exception:
             pass
 
-
 def _apply_run_style(run, style: dict):
     """应用 run 级样式（字符级格式）- 增强版"""
     # 字体名称（支持中文字体 eastAsia）- 优先处理字体
@@ -370,7 +342,6 @@ def _apply_run_style(run, style: dict):
         except (ValueError, AttributeError):
             pass
 
-
 # ------------------------------------------------------------------ #
 # 页面设置应用
 # ------------------------------------------------------------------ #
@@ -383,14 +354,7 @@ def twips_to_emu(twips: int) -> int:
 
 
 def apply_page_setup(doc: Document, style_data: dict) -> None:
-    """应用页面设置到文档
-    
-    从 style_data 中读取 page_setup，应用到文档的第一个 section
-    
-    Args:
-        doc: python-docx Document 对象
-        style_data: 样式数据（包含 page_setup）
-    """
+    """应用页面设置到文档第一个 section (doc: Document, style_data: dict)"""
     page_setup = style_data.get("page_setup")
     if not page_setup:
         return
@@ -473,16 +437,8 @@ def apply_page_setup(doc: Document, style_data: dict) -> None:
         print(f"警告: 应用页面设置失败: {e}")
         pass
 
-
 def _apply_document_grid(section, grid_type: str = None, chars_per_line: int = None, lines_per_page: int = None) -> None:
-    """应用文档网格设置（通过 XML 操作）
-    
-    Args:
-        section: python-docx Section 对象
-        grid_type: 网格类型（default/lines/linesAndChars/snapToChars）
-        chars_per_line: 每行字符数
-        lines_per_page: 每页行数
-    """
+    """应用文档网格设置到 section（grid_type/chars_per_line/lines_per_page，通过 XML 操作）"""
     try:
         # 获取 section 的 XML 元素
         sectPr = None
@@ -508,12 +464,10 @@ def _apply_document_grid(section, grid_type: str = None, chars_per_line: int = N
             docGrid.set(qn('w:type'), grid_type)
         
         # 设置每页行数（linePitch）
-        # 注意：Word XML 中 linePitch 表示行间距，用于控制每页行数
         if lines_per_page is not None and lines_per_page > 0:
             docGrid.set(qn('w:linePitch'), str(lines_per_page))
         
         # 设置每行字符数（charSpace）
-        # 注意：Word XML 中 charSpace 表示字符间距，用于控制每行字符数
         if chars_per_line is not None and chars_per_line > 0:
             docGrid.set(qn('w:charSpace'), str(chars_per_line))
         
@@ -521,7 +475,6 @@ def _apply_document_grid(section, grid_type: str = None, chars_per_line: int = N
         print(f"警告: 应用文档网格失败: {e}")
         pass
 
-
 # ------------------------------------------------------------------ #
 # Blocks → Word 转换
 # ------------------------------------------------------------------ #

app/services/image_service.py

@@ -1,5 +1,4 @@
 """image_service.py — 图片提取和处理服务"""
-
 import base64
 import json
 from typing import Dict, List
@@ -7,19 +6,8 @@ from typing import Dict, List
 from docx import Document
 from docx.enum.text import WD_ALIGN_PARAGRAPH
 
-
 def extract_images_from_word(doc: Document) -> List[Dict]:
-    """从 Word 文档提取图片及基本样式信息
-    
-    Args:
-        doc: python-docx Document 对象
-        
-    Returns:
-        图片列表，每个元素包含：
-        - paragraph_index: 图片所在段落索引
-        - data_url: Base64 编码的 Data URL
-        - style: 样式信息（宽度、高度、对齐方式、段落样式）
-    """
+    """从 Word 文档提取图片（paragraph_index, data_url, style: 宽高/对齐/段落样式）"""
     images = []
     
     # 建立 rel_id -> 图片数据映射
@@ -83,21 +71,7 @@ def extract_images_from_word(doc: Document) -> List[Dict]:
     
     return images
 
-
 def create_image_markdown(data_url: str, style: Dict, alt: str = "图片") -> str:
-    """生成带样式注释的图片 Markdown
-    
-    Args:
-        data_url: Base64 编码的 Data URL
-        style: 样式字典（width, height, align）
-        alt: 图片替代文本
-        
-    Returns:
-        格式化的 Markdown 字符串
-        
-    Example:
-        <!-- img-style: {"width": 4.0, "height": 3.0, "align": "center"} -->
-        ![图片](data:image/png;base64,...)
-    """
+    """生成带样式注释的图片 Markdown（<!-- img-style: {...} --> ![alt](data_url)）"""
     style_json = json.dumps(style, ensure_ascii=False)
     return f'<!-- img-style: {style_json} -->\n![{alt}]({data_url})\n'

app/services/storage_monitor.py

@@ -9,7 +9,6 @@ from app.config import settings
 
 logger = logging.getLogger(__name__)
 
-
 # ------------------------------------------------------------------ #
 # 磁盘统计工具
 # ------------------------------------------------------------------ #