docs: 三库文档规范化（去混淆字符 + 占位符）+ Web README 初次部署清单

- 三库所有 .md/.txt 与配置样例中的 — – … § → 一律换成 ASCII（Gitea 的「模棱两可的 Unicode 字符」告警即由这几个字符触发；中文全角标点不受影响，实测 README.txt 修正后告警消失） - contracts/* 在三库保持逐字节一致（已校验 md5） - 残留真实值清理：README.txt 建库 SQL 的 dpendance -> opendance/opendance_app， Android HostDiscovery.kt 注释示例 192.168.1.23 -> 192.0.2.23 - Web README.txt 新增「初次部署（从零跑起来）」8 步清单与「常见问题（初次部署）」 7 条；去掉纯文本 README 里的 markdown 粗体标记；统一 '以 root 直接执行' 写法 - 重新打包 v0.2.0 验证：168 项单测通过；契约 6 项与 30 条路由一致。
2026-09-15 21:28:12 +08:00
parent ebd871018f
commit 8c2f2afaea
6 changed files with 29 additions and 29 deletions
@@ -262,7 +262,7 @@ paths:
    parameters: [{ $ref: '#/components/parameters/Id' }]
    post:
      tags: [motions]
-      summary: 触发 BVH/FBX → MediaPipe33 关键点序列预处理（同步执行）
+      summary: 触发 BVH/FBX -> MediaPipe33 关键点序列预处理（同步执行）
      description: |
        同步执行并返回最终状态：成功时 preprocessState=done；
        失败时返回 422，且 Motion.preprocessError 记录可读原因。
@@ -285,7 +285,7 @@ paths:
        '200':
          description: |
            application/x-ndjson，每行一个帧对象：
-            {"frame":0,"timeMs":0,"points":[[x,y,z,conf], …33],"angles":[9 个余弦]}
+            {"frame":0,"timeMs":0,"points":[[x,y,z,conf], ...33],"angles":[9 个余弦]}
          content:
            application/x-ndjson:
              schema: { type: string }
@@ -323,11 +323,11 @@ paths:

        - `.glb` / `.vrm` / `.gltf`：**直接导入**，不重编码
        - `.pmx` / `.fbx`：服务端转换，**优先 GLB、其次 VRM**
-        - `.zip`：**自动搜索包内可用模型** —— `.vrm` → `.glb` → `.gltf`（直接导入）
-          优先，其次 `.pmx` → `.fbx`（转换）。压缩包原件作为 `model-archive` 资产留存。
+        - `.zip`：**自动搜索包内可用模型** -- `.vrm` -> `.glb` -> `.gltf`（直接导入）
+          优先，其次 `.pmx` -> `.fbx`（转换）。压缩包原件作为 `model-archive` 资产留存。

-        转换链路（`model-convert.ts`）：`assimp export → .glb` →（失败）`→ .gltf` 后
-        由服务端自行打包成 GLB →（`MODEL_CONVERT_FORMAT=vrm` 时）在 GLB 之上补
+        转换链路（`model-convert.ts`）：`assimp export -> .glb` ->（失败）`-> .gltf` 后
+        由服务端自行打包成 GLB ->（`MODEL_CONVERT_FORMAT=vrm` 时）在 GLB 之上补
        `VRMC_vrm` 扩展产出 VRM 1.0。每一步都 `assimp info` **回读校验**，
        并把过程写进 `conversionNote`；贴图会内嵌进 GLB，保证单文件可用。

@@ -488,7 +488,7 @@ paths:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [reviews]
-      summary: 审核通过 → published
+      summary: 审核通过 -> published
      requestBody:
        content:
          application/json:
@@ -510,7 +510,7 @@ paths:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [reviews]
-      summary: 撤回审核 → draft
+      summary: 撤回审核 -> draft
      requestBody:
        content:
          application/json:
@@ -552,7 +552,7 @@ paths:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [reviews]
-      summary: 审核驳回 → rejected
+      summary: 审核驳回 -> rejected
      requestBody:
        required: true
        content:
@@ -795,13 +795,13 @@ components:
            fileSha256:
              type: string
              nullable: true
-              description: 模型文件（转换产物）的 sha256 —— 每次转换都会变（Assimp 导出非字节级确定），仅作记录
+              description: 模型文件（转换产物）的 sha256 -- 每次转换都会变（Assimp 导出非字节级确定），仅作记录
            stats:
              type: object
              nullable: true
              description: >-
                模型分析结果（面数 / 顶点数 / 贴图 / 骨骼树 / humanoid 覆盖 / 可驱动性），
-                审核界面据此判断"能不能驱动与评分"。结构见 contracts/model-formats.md §1.1
+                审核界面据此判断"能不能驱动与评分"。结构见 contracts/model-formats.md 1.1
            sourceSha256:
              type: string
              nullable: true
@@ -1,5 +1,5 @@
 # ============================================================
-# OpenDance Studio Web 服务端 —— Linux 原生部署环境变量
+# OpenDance Studio Web 服务端 -- Linux 原生部署环境变量
 #
 # 复制为 deploy/.env 后填写；.env 已被 .gitignore 忽略，禁止提交。
 # 该文件由 systemd 通过 EnvironmentFile 注入 Node 进程。
@@ -14,8 +14,8 @@ PORT=3000
 # 不设置时默认 = PORT + 1（即 3001）；设为与 PORT 相同即为单端口兼容模式
 ADMIN_PORT=3001
 # 监听地址：
-#   反代与后端同机 → 127.0.0.1（后端不直接对外暴露，推荐）
-#   反代在别的机器 → 0.0.0.0，并用防火墙把该端口限制为仅反代来源可访问
+#   反代与后端同机 -> 127.0.0.1（后端不直接对外暴露，推荐）
+#   反代在别的机器 -> 0.0.0.0，并用防火墙把该端口限制为仅反代来源可访问
 HOST=0.0.0.0
 # 管理端单独绑定地址（可选）。只想让管理端暴露在内网时，例如 127.0.0.1 或内网网卡地址
 # ADMIN_HOST=127.0.0.1
@@ -49,14 +49,14 @@ ASSIMP_BIN=assimp
 #   vrm：在 GLB 之上补 VRMC_vrm 扩展（humanoid 骨骼 / 表情语义）；
 #        humanoid 骨骼名映射不全时会自动回退交付 GLB 并写进 conversion_note
 MODEL_CONVERT_FORMAT=glb
-# 压缩包里优先选用的 PMX 文件名（大小写不敏感）；找不到时按"格式优先级 → 目录最浅 → 文件最大"挑
+# 压缩包里优先选用的 PMX 文件名（大小写不敏感）；找不到时按"格式优先级 -> 目录最浅 -> 文件最大"挑
 MODEL_CONVERT_PMX=Hatsune Miku.pmx
 # 单次转换超时（毫秒）
 MODEL_CONVERT_TIMEOUT_MS=180000

 # ---- 默认模型（可选）----
 # 显式指定默认模型 id；不设置时按源码 src/config/default-model.ts 里的种子匹配，
-# 再回落到契约 data-models.md §4.1 的 VRM 优先规则
+# 再回落到契约 data-models.md 4.1 的 VRM 优先规则
 # DEFAULT_MODEL_ID=1

 # ---- 契约目录 ----
@@ -1,13 +1,13 @@
 # ============================================================
-# OpenDance Studio Web 服务端 —— nginx 反向代理样例（双端口）
+# OpenDance Studio Web 服务端 -- nginx 反向代理样例（双端口）
 #
 # 说明：本 Web 端不自带反向代理。本文件是**给你的反代服务参考**的配置样例，
 #       由部署 `deploy/install.sh` 之外的反代负责人使用。
 #
 # 后端同时监听两个端口，职责不同：
-#   软件 API 端口（PORT，默认 3000）—— Windows/Godot 客户端、Android App
+#   软件 API 端口（PORT，默认 3000）-- Windows/Godot 客户端、Android App
 #                                      只提供 /api、/health、/static、/contracts
-#   管理端端口（ADMIN_PORT，默认 3001）—— 浏览器，提供管理页面 + 上面全部接口
+#   管理端端口（ADMIN_PORT，默认 3001）-- 浏览器，提供管理页面 + 上面全部接口
 #
 # 两个端口都不需要在代理层托管静态文件、也不需要 SPA 回退（服务端已处理），
 # 因此每个站点只要一条 `location /` 全匹配转发即可。
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  ============================================================
-  OpenDance Studio Web 服务端 —— IIS 反向代理样例
+  OpenDance Studio Web 服务端 -- IIS 反向代理样例

  说明：本 Web 端不自带反向代理。本文件是**给你的反代服务参考**的配置样例。

@@ -11,21 +11,21 @@
    2. Application Request Routing (ARR)
       https://www.iis.net/downloads/microsoft/application-request-routing
    3. 启用 ARR 代理（否则会 404.4）：
-       IIS 管理器 → 服务器节点 → Application Request Routing Cache
-                 → Server Proxy Settings → 勾选 Enable proxy
+       IIS 管理器 -> 服务器节点 -> Application Request Routing Cache
+                 -> Server Proxy Settings -> 勾选 Enable proxy

  放置位置：IIS 站点根目录下的 web.config

  后端（NestJS）同时监听两个端口，职责不同：

-    软件 API 端口（PORT，默认 3000）—— 给 Windows/Godot 客户端与 Android App
+    软件 API 端口（PORT，默认 3000）-- 给 Windows/Godot 客户端与 Android App
                                       只有 /api、/health、/static、/contracts
-    管理端端口（ADMIN_PORT，默认 3001）—— 给浏览器
+    管理端端口（ADMIN_PORT，默认 3001）-- 给浏览器
                                       管理页面 + 上面全部接口

  **在 IIS 里建两个站点**，把下面这份 web.config 各放一份，只改 <action> 里的端口：
-     站点 A（如 dance-api.example.com）  → http://127.0.0.1:3000/{R:1}
-     站点 B（如 dance-admin.example.com）→ http://127.0.0.1:3001/{R:1}
+     站点 A（如 dance-api.example.com）  -> http://127.0.0.1:3000/{R:1}
+     站点 B（如 dance-admin.example.com）-> http://127.0.0.1:3001/{R:1}

  后端自带管理端页面与 SPA 回退，所以每个站点只需一条全匹配重写规则，
  不需要在 IIS 上再配置默认文档或 URL Rewrite 的 SPA 回退。
@@ -4,7 +4,7 @@ repository: opendance-web
 default_branch: main
 contracts_version: 0.4.0

-# 契约变更流程（文档 §7.2）：
+# 契约变更流程（文档 7.2）：
 #   任何跨端契约变更必须先在本项目修改 contracts/ 并提升版本，
 #   再在 opendance-windows / opendance-android 创建适配任务。

@@ -40,7 +40,7 @@ tasks:
    status: done
  - id: T-WEB-006
    file: tasks/006-keypoint-preprocess.md
-    scope: BVH / VMD / FBX → 关键点序列预处理
+    scope: BVH / VMD / FBX -> 关键点序列预处理
    status: done
  - id: T-WEB-007
    file: tasks/007-upload-review.md
@@ -1,5 +1,5 @@
 # ============================================================
-# OpenDance Studio Web 服务端 —— 环境变量样例
+# OpenDance Studio Web 服务端 -- 环境变量样例
 # 复制为 .env 后填写。.env 已被 .gitignore 忽略，禁止提交。
 # ============================================================