diff --git a/.gitignore b/.gitignore
index 855e2c6a..3cc071be 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,9 +10,7 @@ __pycache__/
 log/
 tmp/
 
-# 开发文档：仅「10、项目管理」进库并镜像 Gitea；其余子目录与根下 md/资源仅保留在本机
-开发文档/*
-!开发文档/10、项目管理/
+# 开发文档：全目录纳入版本库并同步 Gitea（同步 GitHub 前请自行审阅敏感内容）
 .obsidian/
 
 # 二进制/压缩/临时产物
diff --git a/miniprogram/pages/read/read.wxml b/miniprogram/pages/read/read.wxml
index 4c7533eb..aced9408 100644
--- a/miniprogram/pages/read/read.wxml
+++ b/miniprogram/pages/read/read.wxml
@@ -78,10 +78,14 @@
         <view wx:elif="{{item.length === 1 && item[0].type === 'image'}}" class="paragraph">
           <image class="content-image" src="{{item[0].src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{item[0].src}}"></image>
         </view>
+        <view wx:elif="{{item.length === 1 && item[0].type === 'video'}}" class="paragraph content-video-wrap">
+          <video class="content-video" src="{{item[0].src}}" controls show-center-play-btn object-fit="contain"></video>
+        </view>
         <view wx:else class="paragraph">
           <text user-select><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><text wx:if="{{seg.type === 'text'}}">{{seg.text}}</text><text wx:elif="{{seg.type === 'mention'}}" class="mention" bindtap="onMentionTap" data-user-id="{{seg.userId}}" data-nickname="{{seg.nickname}}">{{seg.mentionDisplay}}</text><text wx:elif="{{seg.type === 'linkTag'}}" class="link-tag" bindtap="onLinkTagTap" data-url="{{seg.url}}" data-label="{{seg.label}}" data-tag-type="{{seg.tagType}}" data-page-path="{{seg.pagePath}}" data-tag-id="{{seg.tagId}}" data-app-id="{{seg.appId}}" data-mp-key="{{seg.mpKey}}">#{{seg.label}}</text></block></text>
           <block wx:for="{{item}}" wx:key="index" wx:for-item="seg">
             <image wx:if="{{seg.type === 'image'}}" class="content-image" src="{{seg.src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{seg.src}}"></image>
+            <video wx:elif="{{seg.type === 'video'}}" class="content-video" src="{{seg.src}}" controls show-center-play-btn object-fit="contain"></video>
           </block>
         </view>
       </block>
@@ -153,7 +157,8 @@
             <scroll-view wx:elif="{{item.length === 1 && item[0].type === 'table'}}" scroll-x class="table-scroll"><view class="content-table"><view class="table-row table-header-row" wx:if="{{item[0].headers.length}}"><text class="table-cell table-header-cell" wx:for="{{item[0].headers}}" wx:key="index" wx:for-item="hdr">{{hdr}}</text></view><view class="table-row" wx:for="{{item[0].rows}}" wx:key="index" wx:for-item="row"><text class="table-cell" wx:for="{{row}}" wx:key="index" wx:for-item="cell">{{cell}}</text></view></view></scroll-view>
             <view wx:elif="{{item.length === 1 && item[0].type === 'listItem'}}" class="seg-list-item"><text class="seg-list-marker" wx:if="{{item[0].ordered}}">{{item[0].number}}.</text><text class="seg-list-marker" wx:else>•</text><text class="seg-list-text" user-select>{{item[0].text}}</text></view>
             <view wx:elif="{{item.length === 1 && item[0].type === 'image'}}" class="paragraph"><image class="content-image" src="{{item[0].src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{item[0].src}}"></image></view>
-            <view wx:else class="paragraph"><text user-select><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><text wx:if="{{seg.type === 'text'}}">{{seg.text}}</text><text wx:elif="{{seg.type === 'mention'}}" class="mention" bindtap="onMentionTap" data-user-id="{{seg.userId}}" data-nickname="{{seg.nickname}}">{{seg.mentionDisplay}}</text><text wx:elif="{{seg.type === 'linkTag'}}" class="link-tag" bindtap="onLinkTagTap" data-url="{{seg.url}}" data-label="{{seg.label}}" data-tag-type="{{seg.tagType}}" data-page-path="{{seg.pagePath}}" data-tag-id="{{seg.tagId}}" data-app-id="{{seg.appId}}" data-mp-key="{{seg.mpKey}}">#{{seg.label}}</text></block></text><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><image wx:if="{{seg.type === 'image'}}" class="content-image" src="{{seg.src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{seg.src}}"></image></block></view>
+            <view wx:elif="{{item.length === 1 && item[0].type === 'video'}}" class="paragraph content-video-wrap"><video class="content-video" src="{{item[0].src}}" controls show-center-play-btn object-fit="contain"></video></view>
+            <view wx:else class="paragraph"><text user-select><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><text wx:if="{{seg.type === 'text'}}">{{seg.text}}</text><text wx:elif="{{seg.type === 'mention'}}" class="mention" bindtap="onMentionTap" data-user-id="{{seg.userId}}" data-nickname="{{seg.nickname}}">{{seg.mentionDisplay}}</text><text wx:elif="{{seg.type === 'linkTag'}}" class="link-tag" bindtap="onLinkTagTap" data-url="{{seg.url}}" data-label="{{seg.label}}" data-tag-type="{{seg.tagType}}" data-page-path="{{seg.pagePath}}" data-tag-id="{{seg.tagId}}" data-app-id="{{seg.appId}}" data-mp-key="{{seg.mpKey}}">#{{seg.label}}</text></block></text><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><image wx:if="{{seg.type === 'image'}}" class="content-image" src="{{seg.src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{seg.src}}"></image><video wx:elif="{{seg.type === 'video'}}" class="content-video" src="{{seg.src}}" controls show-center-play-btn object-fit="contain"></video></block></view>
           </block>
         </view>
         <view class="fade-mask"></view>
@@ -245,7 +250,8 @@
             <scroll-view wx:elif="{{item.length === 1 && item[0].type === 'table'}}" scroll-x class="table-scroll"><view class="content-table"><view class="table-row table-header-row" wx:if="{{item[0].headers.length}}"><text class="table-cell table-header-cell" wx:for="{{item[0].headers}}" wx:key="index" wx:for-item="hdr">{{hdr}}</text></view><view class="table-row" wx:for="{{item[0].rows}}" wx:key="index" wx:for-item="row"><text class="table-cell" wx:for="{{row}}" wx:key="index" wx:for-item="cell">{{cell}}</text></view></view></scroll-view>
             <view wx:elif="{{item.length === 1 && item[0].type === 'listItem'}}" class="seg-list-item"><text class="seg-list-marker" wx:if="{{item[0].ordered}}">{{item[0].number}}.</text><text class="seg-list-marker" wx:else>•</text><text class="seg-list-text" user-select>{{item[0].text}}</text></view>
             <view wx:elif="{{item.length === 1 && item[0].type === 'image'}}" class="paragraph"><image class="content-image" src="{{item[0].src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{item[0].src}}"></image></view>
-            <view wx:else class="paragraph"><text user-select><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><text wx:if="{{seg.type === 'text'}}">{{seg.text}}</text><text wx:elif="{{seg.type === 'mention'}}" class="mention" bindtap="onMentionTap" data-user-id="{{seg.userId}}" data-nickname="{{seg.nickname}}">{{seg.mentionDisplay}}</text><text wx:elif="{{seg.type === 'linkTag'}}" class="link-tag" bindtap="onLinkTagTap" data-url="{{seg.url}}" data-label="{{seg.label}}" data-tag-type="{{seg.tagType}}" data-page-path="{{seg.pagePath}}" data-tag-id="{{seg.tagId}}" data-app-id="{{seg.appId}}" data-mp-key="{{seg.mpKey}}">#{{seg.label}}</text></block></text><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><image wx:if="{{seg.type === 'image'}}" class="content-image" src="{{seg.src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{seg.src}}"></image></block></view>
+            <view wx:elif="{{item.length === 1 && item[0].type === 'video'}}" class="paragraph content-video-wrap"><video class="content-video" src="{{item[0].src}}" controls show-center-play-btn object-fit="contain"></video></view>
+            <view wx:else class="paragraph"><text user-select><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><text wx:if="{{seg.type === 'text'}}">{{seg.text}}</text><text wx:elif="{{seg.type === 'mention'}}" class="mention" bindtap="onMentionTap" data-user-id="{{seg.userId}}" data-nickname="{{seg.nickname}}">{{seg.mentionDisplay}}</text><text wx:elif="{{seg.type === 'linkTag'}}" class="link-tag" bindtap="onLinkTagTap" data-url="{{seg.url}}" data-label="{{seg.label}}" data-tag-type="{{seg.tagType}}" data-page-path="{{seg.pagePath}}" data-tag-id="{{seg.tagId}}" data-app-id="{{seg.appId}}" data-mp-key="{{seg.mpKey}}">#{{seg.label}}</text></block></text><block wx:for="{{item}}" wx:key="index" wx:for-item="seg"><image wx:if="{{seg.type === 'image'}}" class="content-image" src="{{seg.src}}" mode="widthFix" show-menu-by-longpress bindtap="onImageTap" data-src="{{seg.src}}"></image><video wx:elif="{{seg.type === 'video'}}" class="content-video" src="{{seg.src}}" controls show-center-play-btn object-fit="contain"></video></block></view>
           </block>
         </view>
         <view class="fade-mask"></view>
diff --git a/miniprogram/pages/read/read.wxss b/miniprogram/pages/read/read.wxss
index 41d21aa8..78b4ab66 100644
--- a/miniprogram/pages/read/read.wxss
+++ b/miniprogram/pages/read/read.wxss
@@ -728,6 +728,20 @@
   margin-left: 8rpx;
 }
 
+/* 正文内嵌视频（管理端 rich-video-wrap → contentParser type:video） */
+.content-video-wrap {
+  width: 100%;
+  margin: 24rpx 0;
+  box-sizing: border-box;
+}
+.content-video {
+  width: 100%;
+  max-width: 100%;
+  min-height: 360rpx;
+  border-radius: 12rpx;
+  background: #0a0f14;
+}
+
 .paywall-singlepage-note {
   display: block;
   margin-top: 8rpx;
diff --git a/miniprogram/utils/contentParser.js b/miniprogram/utils/contentParser.js
index 9299a909..caf96099 100644
--- a/miniprogram/utils/contentParser.js
+++ b/miniprogram/utils/contentParser.js
@@ -7,6 +7,7 @@
  *   { type: 'mention', userId, nickname }        — @某人，点击加好友（提交存客宝见 utils/soulBridge.submitCkbLead）
  *   { type: 'linkTag', label, url, ... }         — #链接标签，点击跳转（阅读页 onLinkTagTap：外链→link-preview、小程序→navigateToMiniProgram）
  *   { type: 'image',   src, alt }               — 图片
+ *   { type: 'video',   src }                    — 正文内嵌视频（管理端 rich-video-wrap / <video>）
  */
 
 /** 判断内容是否为 HTML */
@@ -249,6 +250,24 @@ function parseHtmlToSegments(html, config) {
     return '\n__Q_' + idx + '__\n'
   })
 
+  // 2.5 内嵌视频：去掉管理端「rich-video-caption」说明（仅编辑器用）；整段 <video> 抽成占位
+  // 须在列表拆解之前执行，否则 li/段落内 video 会在 parseBlockToSegments 里被 strip 成纯文本
+  const videos = []
+  text = text.replace(/<div[^>]*\brich-video-caption\b[^>]*>[\s\S]*?<\/div>/gi, '')
+  text = text.replace(/<video\b[^>]*>[\s\S]*?<\/video>/gi, function (match) {
+    const sm = match.match(/\bsrc\s*=\s*"([^"]*)"/i) || match.match(/\bsrc\s*=\s*'([^']*)'/i)
+    const rawSrc = sm ? String(sm[1] || '').trim() : ''
+    if (!rawSrc) return match
+    const decoded = decodeEntities(rawSrc)
+    const src =
+      config && config.assetBase
+        ? resolveArticleImageSrc(decoded, config.assetBase)
+        : resolveArticleImageSrc(decoded, '')
+    const idx = videos.length
+    videos.push({ src })
+    return '\n__VIDEO_' + idx + '__\n'
+  })
+
   // 3. 列表 → listItem 占位（保留 ordered 标记）
   var olDepth = 0
   var olCounter = 0
@@ -259,6 +278,11 @@ function parseHtmlToSegments(html, config) {
   text = text.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, function (_, inner) {
     var cleaned = inner.replace(/<p[^>]*>/gi, '').replace(/<\/p>/gi, '').trim()
     if (!cleaned) return '\n'
+    // 列表项内仅有视频占位时，提升为独立视频块（避免 __VIDEO_n__ 当正文展示）
+    var onlyVid = cleaned.match(/^__VIDEO_(\d+)__$/)
+    if (onlyVid) {
+      return '\n__VIDEO_' + onlyVid[1] + '__\n'
+    }
     if (olDepth > 0) {
       olCounter++
       return '\n__LI_O_' + olCounter + '__ ' + cleaned + '\n'
@@ -292,6 +316,17 @@ function parseHtmlToSegments(html, config) {
       continue
     }
 
+    // video
+    var vidM = block.trim().match(/^__VIDEO_(\d+)__$/)
+    if (vidM) {
+      var vid = videos[parseInt(vidM[1], 10)]
+      if (vid && vid.src) {
+        lines.push('')
+        segments.push([{ type: 'video', src: vid.src }])
+      }
+      continue
+    }
+
     // heading
     var hM = block.trim().match(/^__H_(\d+)__$/)
     if (hM) {
diff --git a/scripts/content_download.py b/scripts/content_download.py
index c43bf4b2..77cd2bee 100644
--- a/scripts/content_download.py
+++ b/scripts/content_download.py
@@ -8,7 +8,9 @@
   SOUL_TEST_ENV=soulapi python3 scripts/content_download.py --id 10.27
   python3 scripts/content_download.py 128 --out-dir /path/to/2026每日派对干货
 
-2026 场次（第102场起）对应 id 10.01、10.02、…、10.27（第128场）…
+2026 每日派对章节挂在 part-2026-02 / part-2026-03 / part-2026-04 等篇章下，
+业务 id（如 10.34）与「第 N 场」不是简单线性公式；若按场次推算 404，脚本会
+自动在上述 part 里按 sectionTitle「第N场」解析真实 id。
 """
 import argparse
 import os
@@ -34,15 +36,40 @@ DEFAULT_BOOK_2026 = Path(
 
 
 def field_to_id(field: int) -> str:
-    """第 N 场（≥102）→ 10.xx；第101场及以前在第九章为 9.xx。API 上第128场可能为 9.28。"""
+    """首猜 id：≥102 用 10.(field-102+1)；与线上一致性不保证，404 时会走 resolve。"""
     if field >= 102:
         n = field - 102 + 1
         return f"10.{n:02d}"
     if field >= 1:
-        return f"9.{field:02d}"  # 第9章 9.01～9.99，按场次
+        return f"9.{field:02d}"
     raise ValueError("场次请用 1～999")
 
 
+def resolve_2026_chapter_id_by_field(base: str, field: int, requests_mod) -> str | None:
+    """在 part-2026-* 下按标题「第N场」查真实 chapters.id。"""
+    parts_url = f"{base}/api/miniprogram/book/parts"
+    pr = requests_mod.get(parts_url, timeout=30)
+    if pr.status_code != 200:
+        return None
+    pdata = pr.json()
+    parts = pdata.get("parts") or []
+    needle = f"第{field}场"
+    for p in parts:
+        pid = p.get("id") or ""
+        if not pid.startswith("part-2026-"):
+            continue
+        url = f"{base}/api/miniprogram/book/chapters-by-part?partId={pid}"
+        cr = requests_mod.get(url, timeout=30)
+        if cr.status_code != 200:
+            continue
+        cdata = cr.json().get("data") or []
+        for row in cdata:
+            title = row.get("sectionTitle") or ""
+            if needle in title:
+                return row.get("id")
+    return None
+
+
 def main():
     parser = argparse.ArgumentParser(description="从小程序 API 下载单章为 md")
     parser.add_argument("field", nargs="?", type=int, help="场次号，如 128 表示第128场")
@@ -83,6 +110,13 @@ def main():
         r = requests.get(url, timeout=30)
         if r.status_code == 200:
             chapter_id = fallback_id
+    if r.status_code == 404 and args.field is not None and not args.id:
+        resolved = resolve_2026_chapter_id_by_field(base, args.field, requests)
+        if resolved:
+            chapter_id = resolved
+            url = f"{base}/api/miniprogram/book/chapter/by-id/{chapter_id}"
+            print(f"404，按 2026 篇章标题解析到 id: {chapter_id} | GET {url}")
+            r = requests.get(url, timeout=30)
     r.raise_for_status()
     data = r.json()
     if not data.get("success"):
diff --git a/开发文档/.github/workflows/sync_from_coding.yml b/开发文档/.github/workflows/sync_from_coding.yml
new file mode 100644
index 00000000..bf82de99
--- /dev/null
+++ b/开发文档/.github/workflows/sync_from_coding.yml
@@ -0,0 +1,36 @@
+name: Sync from Coding
+
+on:
+  schedule:
+    - cron: '0 */2 * * *'   # 每2小时执行一次
+  workflow_dispatch:        # 允许手动触发
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # 确保此行存在，赋予工作流写入仓库内容的权限，这是解决 403 权限问题的基础
+    steps:
+      - name: 检出 GitHub 仓库
+        uses: actions/checkout@v4
+        with:
+          ref: develop # 明确检出 develop 分支，确保在正确的分支上操作
+
+      - name: 配置 Git 用户并合并 Coding 代码到 GitHub
+        run: |
+          # 配置 Git 用户信息
+          git config user.name "zhiqun@qq.com"
+          git config user.email "zhiqun@qq.com"
+
+          # 添加 Coding 仓库为一个新的远程源
+          git remote add coding-origin https://${{ secrets.CODING_USERNAME }}:${{ secrets.CODING_TOKEN }}@e.coding.net/g-xtcy5189/cunkebao/cunkebao_v3.git
+          
+          # 从 Coding 远程仓库获取 develop 分支的最新信息
+          git fetch coding-origin develop
+
+          # 合并 Coding 的 develop 分支到本地的 develop 分支
+          # --allow-unrelated-histories 允许合并两个没有共同历史的分支
+          git merge --no-ff --allow-unrelated-histories coding-origin/develop
+
+          # 将合并后的本地 develop 分支推送到 GitHub 的 develop 分支
+          git push origin develop
diff --git a/开发文档/1、需求/2026-03-20-需求.md b/开发文档/1、需求/2026-03-20-需求.md
new file mode 100644
index 00000000..31ed427b
--- /dev/null
+++ b/开发文档/1、需求/2026-03-20-需求.md
@@ -0,0 +1,74 @@
+# Soul 创业派对 - 需求汇总
+
+> **主需求文件**（日期最新）。基准：《[以界面定需求](以界面定需求.md)》
+
+---
+
+## 需求基准
+
+- **以代码为准**：需求文档滞后于实现时，以实际代码行为为准，**反向补齐文档**。
+- 需求以《以界面定需求》为界面级基准；新增/变更功能时先对齐界面再落需求清单。
+- 需求文件命名：`YYYY-MM-DD-需求.md`，**日期最新的为主需求文件**
+
+---
+
+## 需求清单
+
+| 日期 | 描述 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-02 | 内容管理页仅保留「API 接口」按钮 | 已完成 | soul-admin ContentPage |
+| 2026-02 | 侧栏与分销页「交易中心」→「推广中心」 | 已完成 | AdminLayout、DistributionPage |
+| 2026-02 | 推广中心/我的收益：绑定中、已付款、已过期清晰展示 | 已有 | referral 页 |
+| 2026-02 | 海报小程序码带用户 ID（scene ref=userId） | 已完成 | referral.js generatePoster |
+| 2026-02 | 复制朋友圈文案去掉「专属邀请码」展示 | 已完成 | 海报 |
+| 2026-02 | 我的页：待领收益→我的收益、头像/昵称/ID 一键获取 | 已有 | my.wxml |
+| 2026-02 | 设置页：手机/微信号一键获取、自动提现默认开启 | 已有 | settings.js |
+| 2026-02 | 后台与前台参数一致（绑定有效期、自动提现、免费章节等） | 已检查 | 推广设置 |
+| 2026-02 | 找伙伴匹配后台用户库、资源对接两步 | 已有 | match 页 |
+| 2026-02 | VIP 手动设置 + 支付设置 + 日志 | 已完成 | 用户详情弹窗、支付回调 |
+| 2026-02 | 管理端设置 VIP 必填到期日 | 已完成 | 前后端校验 |
+| 2026-02 | 会员订单分润差异化（会员 20% / 非会员 10%） | 已完成 | computeOrderCommission |
+| 2026-02 | VIP 设置入口拆分、SetVipModal、VIP 角色管理 | 已完成 | UserDetailModal、SetVipModal |
+| 2026-02 | VIP 排序：vip_activated_at、vip_sort | 已完成 | VipMembers |
+| 2026-02 | VIP 角色：可选择 + 可手动填写 | 已完成 | vip_roles 表 |
+| 2026-03-08 | 文章阅读付费规则：免费章节以 free_chapters 为准；VIP 全章免费 | 已完成 | soul-api book.go |
+| 2026-03-10 | 我的页阅读统计改为后端接口（真实数据） | 已完成 | loadDashboardStats |
+| 2026-03-10 | 富文本渲染升级（TipTap HTML → rich-text，保留 @mention） | 待实施 | 确认 DB 格式 |
+| 2026-03-16 | 文章编辑 @某人/#标签 自动创建并同步存客宝 | 已完成 | ParseAutoLinkContent |
+| 2026-03-16 | 编辑资料页分享名片：Canvas 封面、标题「昵称+为您分享名片」 | 已完成 | profile-edit.js |
+| 2026-03-16 | 链接人与事列表：table、planId/apiKey 列、删除 Dialog | 已完成 | ContentPage.tsx |
+| 2026-03-16 | 存客宝创建计划参数：planType=1、sceneId=9、status=1 | 已完成 | db_person.go |
+| 2026-03-16 | @mention 存储格式：span 必须含 data-label | 已完成 | ParseAutoLinkContent |
+| 2026-03-17 | 代付统一到代付页 | 已完成 | read.js onLoad |
+| 2026-03-18 | 代付流程：阅读页弹窗选择名额→支付→分享；好友自动领取 | 已完成 | read 页、singlePage 引导 |
+| 2026-03-18 | 代付退款后禁用：status=refunded | 已完成 | gift_pay_requests |
+| 2026-03-20 | 提现审批逻辑修复：批准时校验「累计-已提现>=待审核」 | 已完成 | doApproveWithdrawal |
+| 2026-03-20 | 我的页「我的收益」取 availableEarnings | 已完成 | my.wxml pendingEarnings |
+| 2026-03-20 | 推广设置：提现手续费、自动提现开关 | 已完成 | ReferralSettingsPage |
+| 2026-03-20 | 提现审核列表：自动审批开关、备注列 | 已完成 | DistributionPage |
+| 2026-03-20 | 提现失败记录：fail_reason/error_message 落库 | 已完成 | admin_withdrawals |
+| 2026-03-18 | 资料完善引导：checkVipContactRequiredAndGuide、avatar-nickname、profile-edit、VIP 支付成功引导、新用户强制引导 | 已完成 | app.js、miniprogram/docs/资料完善引导流程图.md |
+| 2026-03-18 | 购买≥3 章显示「解锁全书」按钮 | 已完成 | read.wxml wx:if="{{purchasedCount >= 3}}" |
+| 2026-03-24 | 分润比例前端从 config 读取（shareRate） | 已完成 | config/core、read/referral 页 |
+
+---
+
+## 三端需求速查
+
+| 端 | 主需求 |
+|----|--------|
+| 小程序 | 我的收益、推广中心、代付、阅读统计、VIP |
+| 管理端 | 推广设置、提现审核、VIP 设置、链接人与事 |
+| 后端 | 提现审批、referral_config、代付、分润 |
+
+---
+
+## 文档同步记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-04-07 | 与 [开发文档索引](../索引.md)、[闭环与文档同步-2026-04-07.md](../10、项目管理/闭环与文档同步-2026-04-07.md) 交叉对齐；主需求文件未更名，仍以本文件为日期最新主需求 |
+
+---
+
+**最后更新**：2026-04-07（清单内容基准日仍为 2026-03-20；同步记录见上表）
diff --git a/开发文档/1、需求/AI剪辑分发功能需求.md b/开发文档/1、需求/AI剪辑分发功能需求.md
new file mode 100644
index 00000000..a0d86c55
--- /dev/null
+++ b/开发文档/1、需求/AI剪辑分发功能需求.md
@@ -0,0 +1,60 @@
+# AI 剪辑分发功能需求
+
+**记录日期：** 2026-03-28  
+**所属项目：** 卡若创业派对  
+**状态：** 需求待评审  
+
+---
+
+## 功能概述
+
+在「卡若创业派对」App 中新增 AI 对话式视频剪辑 + 多平台自动分发模块。用户通过与 AI 对话描述剪辑需求，AI 自动完成剪辑并推送结果，用户确认后一键分发到各平台，实现持续收益。
+
+---
+
+## 核心功能
+
+### 1. AI 对话式剪辑
+- 用户与 AI 直接对话，描述剪辑需求
+- 输入格式示例：「帮我剪 3月20日 第2场，从10分钟到25分钟」
+- AI 理解意图后自动执行剪辑
+- 剪辑完成后推送视频 + 对应文字内容给用户确认
+
+### 2. 多平台自动分发
+- 剪辑内容一键分发到各平台（抖音、视频号、小红书等）
+- 通过保存各平台 Cookie 实现免登录自动发布
+- Cookie 与卡若创业派对账号绑定，长期保存
+- 每次发布后平台产生的收益归属用户
+
+---
+
+## 用户流程
+
+```
+用户与AI对话
+  → 指定日期 / 场次 / 片段时间范围
+  → AI 自动剪辑
+  → 推送视频 + 文字内容给用户确认
+  → 用户确认
+  → 一键分发到各平台
+  → 平台自动发布
+  → 产生收益
+```
+
+---
+
+## 技术要点（待细化）
+
+- AI 剪辑引擎（ffmpeg / 云剪辑 API）
+- 平台 Cookie 管理与自动刷新机制
+- 多平台发布 API 或自动化方案
+- 收益数据回流追踪
+
+---
+
+## 待办
+
+- [ ] 技术方案评审
+- [ ] 优先级排期
+- [ ] UI/UX 设计
+- [ ] 平台 Cookie 合规性确认
diff --git a/开发文档/1、需求/archive/README.md b/开发文档/1、需求/archive/README.md
new file mode 100644
index 00000000..dc2ae4ab
--- /dev/null
+++ b/开发文档/1、需求/archive/README.md
@@ -0,0 +1,11 @@
+# 1、需求 - 归档
+
+专项需求、技术分析、已合并或过时文档，保留供追溯。
+
+| 文件 | 说明 |
+|------|------|
+| 链接人与事-实现方案.md | 实现方案 |
+| 链接人与事-存客宝同步-需求规划.md | 存客宝同步需求规划 |
+| 链接人与事-所有同步需求.md | 链接人与事所有同步需求 |
+| 链接人与事-置顶功能-技术分析.md | 置顶功能技术分析 |
+| 文章详情-阅读页线框图.md | 阅读页线框图 |
diff --git a/开发文档/1、需求/archive/文章详情-阅读页线框图.md b/开发文档/1、需求/archive/文章详情-阅读页线框图.md
new file mode 100644
index 00000000..c8c5563b
--- /dev/null
+++ b/开发文档/1、需求/archive/文章详情-阅读页线框图.md
@@ -0,0 +1,158 @@
+# 文章详情（阅读页）线框图
+
+> Soul 创业派对 - 小程序 `pages/read/read` 界面结构
+
+---
+
+## 一、完整内容态（免费/已购买）
+
+```
+┌─────────────────────────────────────────┐
+│ ████████████░░░░░░░░░░  阅读进度 60%     │  ← 顶部固定进度条
+├─────────────────────────────────────────┤
+│  ←    第 4 章 真实的行业                 │  ← 导航栏
+├─────────────────────────────────────────┤
+│  [4] [免费]                             │  ← 章节元信息
+│  4.1 旅游号：30天10万粉的真实逻辑       │  ← 章节标题（可长按复制）
+├─────────────────────────────────────────┤
+│                                         │
+│  这是一段正文内容，文中包含 @卡若 和     │
+│  #创业资源 可以点击。支持长按复制文字。  │  ← @ 高亮可点，# 金色可点
+│                                         │
+│  第二段纯文本，无特殊标记。              │
+│                                         │
+│  ┌─────────────────────────────────┐   │  ← 图片（可点击全屏预览）
+│  │         [ 插图 ]                │   │
+│  └─────────────────────────────────┘   │
+│                                         │
+├─────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────────┐│
+│  │ 上一篇       │  │ 下一篇            ││  ← 章节导航
+│  │ 3.5 桶装水   │  │ 4.2 美业整合  →  ││
+│  └──────────────┘  └──────────────────┘│
+│                                         │
+│  [ 📣 分享到朋友圈 ] [ 🖼️ 生成海报 ]    │  ← 操作区
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 二、付费墙态（未登录）
+
+```
+┌─────────────────────────────────────────┐
+│  ←    第 4 章 真实的行业                 │
+├─────────────────────────────────────────┤
+│  这是一段预览内容，显示前 50%...         │
+│  第二段预览...                          │
+│                                         │
+│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │  ← 渐变遮罩
+│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
+├─────────────────────────────────────────┤
+│              🔒                         │
+│        登录后继续阅读                    │
+│    已阅读50%，登录后查看完整内容          │
+│                                         │
+│        [ 立即登录 ]                      │
+├─────────────────────────────────────────┤
+│  [ 上一篇 ]          [ 下一篇 → ]       │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 三、付费墙态（已登录未购买）
+
+```
+┌─────────────────────────────────────────┐
+│  （同上：预览内容 + 渐变遮罩）            │
+├─────────────────────────────────────────┤
+│              🔒                         │
+│        解锁完整内容                      │
+│    已阅读50%，购买后继续阅读              │
+│                                         │
+│  [ 购买本章  ¥1.0 ]                      │
+│  [ ✨ 解锁全部 62 章  ¥9.9  省82% ]      │  ← 购买≥3章才显示
+│                                         │
+│  分享给好友一起学习，还能赚取佣金         │
+├─────────────────────────────────────────┤
+│  [ 上一篇 ]          [ 下一篇 → ]       │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 四、交互说明
+
+| 元素 | 交互 |
+|------|------|
+| **@卡若** | 点击 → 确认弹窗「是否添加 @卡若？」→ 调 CKB 留资加好友 |
+| **#创业资源** | 点击 → 按类型：内链跳转 / 外链复制 / 小程序唤醒 / CKB 加好友 |
+| **正文/标题** | 长按 → 选中复制（user-select） |
+| **图片** | 点击 → 全屏预览；长按 → 保存菜单 |
+| **上一篇/下一篇** | 点击 → 切换章节 |
+
+---
+
+## 五、@ / # 三端数据流线框图
+
+```mermaid
+flowchart TB
+    subgraph 管理端["管理端 soul-admin"]
+        A1[链接人与事 Person]
+        A2[链接标签 LinkTag]
+        A3[RichEditor 编辑]
+        A4[autoLinkContent 转换]
+        A1 --> A3
+        A2 --> A3
+        A3 --> A4
+        A4 --> |"content HTML"| DB
+    end
+
+    subgraph 后端["后端 soul-api"]
+        DB[(chapters.content)]
+        API[GET /api/miniprogram/book/chapter]
+        CKB[POST /api/miniprogram/ckb/lead]
+        CFG[GET /api/miniprogram/config]
+        DB --> API
+    end
+
+    subgraph 小程序["小程序 miniprogram"]
+        B1[contentParser 解析]
+        B2[contentSegments 渲染]
+        B3[onMentionTap]
+        B4[onLinkTagTap]
+        API --> B1
+        B1 --> B2
+        B2 --> B3
+        B2 --> B4
+        B3 --> CKB
+        B4 --> |"内链"| Nav[wx.navigateTo]
+        B4 --> |"外链"| Clip[复制剪贴板]
+        B4 --> |"miniprogram"| MP[wx.navigateToMiniProgram]
+        CFG --> B4
+    end
+```
+
+---
+
+## 六、数据流文字说明
+
+```
+管理端 ContentPage
+  → 编辑插入 @[名称](token) / #标签
+  → 保存 content（TipTap HTML）
+
+后端 chapters.content
+  → 原样存储、原样返回
+
+小程序 contentParser
+  → 解析 → contentSegments
+  → WXML 渲染 text / mention / linkTag / image
+
+用户点击 @
+  → onMentionTap → POST /api/miniprogram/ckb/lead
+
+用户点击 #
+  → onLinkTagTap → 按 tagType 分支处理
+```
diff --git a/开发文档/1、需求/archive/链接人与事-存客宝同步-需求规划.md b/开发文档/1、需求/archive/链接人与事-存客宝同步-需求规划.md
new file mode 100644
index 00000000..64ceaff0
--- /dev/null
+++ b/开发文档/1、需求/archive/链接人与事-存客宝同步-需求规划.md
@@ -0,0 +1,296 @@
+# 链接人与事 — 存客宝同步 需求规划
+
+> 参与角色：产品经理、管理端开发工程师、后端开发  
+> 创建日期：2026-03-13  
+> **同步需求汇总**：见 `链接人与事-所有同步需求.md`
+
+---
+
+## 一、需求概述
+
+**模块**：内容管理 → 链接AI → AI列表（链接人与事）
+
+**核心变更**：
+
+1. **创建 Person 时**：同步在存客宝创建「场景获客计划」
+2. **创建后**：数据（含密钥）记录到本地 `persons` 表
+3. **编辑时**：管理端可编辑，编辑数据同步到存客宝
+4. **UI 布局**：考虑是否另起独立 tab/页面，便于操作
+
+---
+
+## 二、现状梳理
+
+| 项目 | 现状 |
+|------|------|
+| Person 模型 | `person_id`、`token`（32 位）、`name`、`label`、`ckb_api_key` |
+| 创建流程 | 管理端填表 → `POST /api/db/persons` → 仅落本地库 |
+| 密钥 | `ckb_api_key` 手动填写，留空则用全局 `CKB_LEAD_API_KEY` |
+| 存客宝 API | 开放接口：`/v1/open/auth/token` 获取 JWT → `POST /v1/open/scenarios` 创建/提交 |
+| 链接AI 位置 | ContentPage 的「链接AI」tab 下，与「#链接标签」同屏 |
+
+---
+
+## 三、产品建议：是否另起 Tab/页面
+
+### 方案 A：保持链接AI tab，在现有卡片内增强
+
+- **优点**：改动小，与编辑器 @ 场景就近
+- **缺点**：链接AI 已含「AI 人物」+「链接标签」两块，再加 CKB 同步、编辑同步逻辑会拥挤
+
+### 方案 B：独立「链接人与事」页面（推荐）
+
+- **优点**：
+  - 与「关联小程序」对称（LinkedMpPage 独立在设置下）
+  - 空间充足，可做：创建表单、CKB 同步状态、编辑同步、密钥管理、列表筛选
+  - 后续扩展（如批量同步、同步日志）更方便
+- **缺点**：需新增路由与导航入口
+
+**建议**：采用 **方案 B**，在「设置」下新增「链接人与事」tab（或与「关联小程序」并列），与 `LinkedMpPage` 结构类似。
+
+---
+
+## 四、业务流程（产品 + 后端）
+
+### 4.1 创建 Person 流程
+
+```
+管理端填写：名称、人物ID（可选）、标签、存客宝账号（account）
+     │
+     ▼
+后端 DBPersonSave：
+  1. 生成 token（已有）
+  2. 调用存客宝开放 API：
+     - POST /v1/open/auth/token（apiKey + account + sign）
+     - POST /v1/open/scenarios 创建场景获客计划（需确认 CKB 创建计划接口）
+  3. 存客宝返回 planId、apiKey（若 CKB 有返回）
+  4. 落库 persons：person_id、token、name、label、ckb_api_key、ckb_plan_id（新增）
+```
+
+**待确认**：存客宝「创建场景获客计划」的具体接口路径、请求/响应格式。当前 `open-api-sign.md` 示例为「提交 lead」到已有 plan，创建 plan 的接口需向存客宝方确认。
+
+### 4.2 编辑 Person 流程
+
+```
+管理端编辑：名称、标签、其他可编辑字段
+     │
+     ▼
+后端 DBPersonSave（更新逻辑）：
+  1. 更新本地 persons
+  2. 若该 Person 有 ckb_plan_id：调用存客宝更新接口，同步变更
+```
+
+**待确认**：存客宝是否有「更新计划」接口（PUT/PATCH）。
+
+### 4.3 本地存储扩展
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ckb_plan_id` | int/varchar | 存客宝场景获客计划 ID，创建时由 CKB 返回 |
+| `ckb_api_key` | varchar | 存客宝 API Key（已有，创建时由 CKB 返回或沿用全局配置） |
+| `ckb_account` | varchar | 存客宝账号，用于鉴权（可选，若每个 Person 独立账号） |
+
+---
+
+## 五、后端开发任务
+
+| 序号 | 任务 | 说明 |
+|------|------|------|
+| 1 | 实现 CKB 开放 API 客户端 | `internal/ckb/open_client.go`：鉴权签名、获取 token、调用 plan 接口 |
+| 2 | 扩展 Person 模型 | 新增 `ckb_plan_id`；创建计划时 name=SOUL链接人与事-{name} |
+| 3 | 改造 DBPersonSave | 新增：调 CKB 创建计划 → 落库；更新：调 CKB 更新计划 |
+| 4 | 改造 DBPersonDelete | 删除：若有 ckb_plan_id，先调 CKB 删除计划，再删本地 |
+| 5 | 配置项 | `CKB_OPEN_API_KEY`、`CKB_OPEN_ACCOUNT`（全局） |
+
+---
+
+## 六、管理端开发任务
+
+| 序号 | 任务 | 说明 | 状态 |
+|------|------|------|------|
+| 1 | 扩展现有链接人与事卡片 | 在 ContentPage 的 link-person tab 内 | ✅ |
+| 2 | **添加/编辑弹窗** | 点击「添加」或「编辑」打开弹窗，配置与存客宝 API 获客一致（见 7.4） | ✅ |
+| 3 | 列表展示 | 展示 token、ckb_plan_id、同步状态、密钥状态 | ✅ |
+| 4 | **编辑计划入口** | 每行「编辑计划」按钮，有 ckbPlanId 时跳转存客宝编辑页 | ✅ |
+| 5 | 编辑能力 | 弹窗内编辑全部配置；编辑计划跳转存客宝 | ✅ |
+
+---
+
+## 七、存客宝 API 接口（来自 Cunkebao 前端项目）
+
+> 来源：`Cunkebao/src/pages/mobile/scenarios/` 及 `step.api.ts`、`index.api.ts`
+
+### 7.1 计划（Plan）相关
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 获取场景类型 | GET | `/v1/plan/scenes` | 场景列表，用于新建时选择 |
+| **创建计划** | **POST** | **`/v1/plan/create`** | 创建获客计划 |
+| **更新计划** | **PUT** | **`/v1/plan/update`** | 更新获客计划 |
+| **删除计划** | **DELETE** | **`/v1/plan/delete`** | 删除获客计划（body: planId） |
+| 获取计划详情 | GET | `/v1/plan/detail?planId=xxx` | 计划详情 |
+
+### 7.2 场景（Scenario）相关
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 获取场景列表 | GET | `/v1/plan/scenes` | 同 plan/scenes |
+| 获取场景详情 | GET | `/v1/scenarios/{id}` | 场景详情 |
+| 创建场景 | POST | `/v1/scenarios` | 创建场景 |
+| 更新场景 | PUT | `/v1/scenarios/{id}` | 更新场景 |
+| 删除场景 | DELETE | `/v1/scenarios/{id}` | 删除场景 |
+
+### 7.3 创建计划请求体（createPlan）
+
+来自 `NewPlan/index.tsx` 与 `index.data.ts`，核心字段：
+
+```ts
+{
+  name: string;           // 计划名称
+  sceneId: number;       // 场景 ID（1=海报等）
+  scenario: number;      // 同 sceneId
+  remarkType: string;    // 备注类型，如 "phone"
+  greeting: string;      // 打招呼语
+  addInterval: number;   // 加人间隔
+  startTime: string;     // 如 "09:00"
+  endTime: string;       // 如 "18:00"
+  enabled: boolean;      // 是否启用
+  tips?: string;         // 获客成功提示
+  distributionEnabled?: boolean;      // 是否开启分销
+  distributionChannels?: number[];    // 分销渠道 ID 列表
+  customerRewardAmount?: number;      // 获客奖励金额
+  addFriendRewardAmount?: number;     // 添加奖励金额
+  // 编辑时需传
+  id?: number;
+  planId?: number;
+}
+```
+
+### 7.4 场景获客创建 — 用户需输入项（Soul 管理端）
+
+| 字段 | 必填 | 说明 | 默认值 |
+|------|------|------|--------|
+| **名称** | 是 | 计划名称，对应 Person 的 name | - |
+| **人物ID** | 否 | 本地 person_id，不传则自动生成 | 自动 |
+| **标签** | 否 | 身份/角色，如「超级个体」 | - |
+| **场景类型** | 否 | sceneId，1=海报 11=API获客 等 | 11（API获客） |
+| **存客宝账号** | 是* | account，用于开放 API 鉴权 | 全局配置 |
+| **打招呼语** | 否 | greeting | 「你好，请通过」 |
+| **获客成功提示** | 否 | tips | 「请注意消息，稍后加你微信」 |
+| **存客宝密钥** | 否 | 创建后 CKB 返回，可手动覆盖 | 创建后落库 |
+
+\* 若使用全局 CKB_OPEN_ACCOUNT，则用户可不填。
+
+### 7.5 列表展示（简化）
+
+| 字段 | 说明 |
+|------|------|
+| **token** | 32 位唯一标识，文章 @ 时存此值 |
+| **@的人** | 人物名称，编辑器 @ 时展示 |
+| **获客计划活动名** | 固定格式：`SOUL链接人与事-{名称}` |
+
+删除人物时，后端需同时删除存客宝对应获客计划。
+
+### 7.6 列表 — 编辑计划入口
+
+创建后，列表每行需提供**编辑计划**入口：
+
+| 入口类型 | 说明 |
+|----------|------|
+| **跳转存客宝** | 按钮「编辑计划」→ 新开 `https://h5.ckb.quwanzhi.com/scenarios/edit/{planId}`（需确认 Cunkebao 编辑页 URL） |
+| **管理端内嵌** | 按钮「编辑计划」→ 弹窗拉取计划详情，表单编辑后提交，后端调 CKB 更新 |
+
+建议：优先**跳转存客宝**，用户直接在存客宝完整编辑；若需闭环在 Soul 内，再做内嵌表单。
+
+### 7.7 鉴权方式
+
+Cunkebao 前端使用 `Authorization: Bearer <token>`，token 来自登录接口。Soul 对接时需确认：
+
+- **开放 API**（`open-api-sign.md`）：先 `POST /v1/open/auth/token` 获取 JWT，再 Bearer 调用
+- **内部 API**：Cunkebao 管理端登录后直接 Bearer，可能与开放 API 不同
+
+---
+
+## 八、已确认项（2026-03-13）
+
+| 项 | 结论 |
+|----|------|
+| 创建计划接口 | `POST /v1/plan/create` |
+| 更新计划接口 | `PUT /v1/plan/update` |
+| 鉴权 | **开放 API**：先 `POST /v1/open/auth/token` 获取 JWT，再 Bearer 调用 plan 接口 |
+| 响应体 | **是**：`createPlan` 返回 `planId`、`apiKey`，需落库到 persons |
+| 创建参数 | **标准创建**：按 Cunkebao 标准参数创建，不精简 |
+
+---
+
+## 九、验收标准（草案）
+
+| 场景 | 验收点 |
+|------|--------|
+| 创建 Person | 填写名称等 → 提交 → 本地 persons 有记录，且 ckb_plan_id 有值 |
+| 编辑 Person | 修改名称/标签 → 提交 → 本地更新，存客宝计划同步更新 |
+| 密钥展示 | 列表显示「密钥 ✓」或「用默认密钥」 |
+| 小程序 @ 流程 | 文章 @ 人物 → 小程序点击 → 留资 → 正确推送到对应存客宝计划（现有逻辑保持） |
+
+---
+
+## 十、链接人与事 — 三端流程总结
+
+### 10.1 管理端（soul-admin）
+
+| 步骤 | 操作 | 说明 |
+|------|------|------|
+| 1 | 内容管理 → 链接人与事 → 添加 | 打开弹窗，填写名称、人物ID、标签、存客宝账号、密钥、打招呼语、获客提示 |
+| 2 | 提交 | 后端创建 Person + 调 CKB 创建获客计划（name=SOUL链接人与事-{名称}，sceneId=11 API获客） |
+| 3 | 列表 | 仅显示 token、获客计划活动名（SOUL链接人与事-{名称}） |
+| 4 | 编辑 | 打开弹窗修改，后端同步更新存客宝计划 |
+| 5 | 编辑计划 | 跳转存客宝编辑页（需 ckbPlanId） |
+| 6 | 删除 | 删除 Person + 后端调 CKB 删除对应获客计划 |
+
+### 10.2 后端（soul-api）
+
+| 步骤 | 接口 | 说明 |
+|------|------|------|
+| 1 | POST /api/db/persons | 新增：生成 token → 调 CKB 开放 API 创建计划（name=SOUL链接人与事-{name}）→ 落库 person_id、token、name、label、ckb_api_key、ckb_plan_id |
+| 2 | POST /api/db/persons | 更新：更新本地 → 若有 ckb_plan_id 调 CKB 更新计划 |
+| 3 | DELETE /api/db/persons?personId=xxx | 删除：删本地 → 若有 ckb_plan_id 调 CKB 删除计划 |
+| 4 | GET /api/db/persons | 列表：返回 persons（含 token、name、ckb_plan_id 等） |
+
+### 10.3 小程序（miniprogram）
+
+| 步骤 | 操作 | 说明 |
+|------|------|------|
+| 1 | 文章渲染 | contentParser 解析 @mention，data-id 存 token |
+| 2 | 用户点击 @人物 | onMentionTap → targetUserId 传 token |
+| 3 | 留资提交 | POST /api/miniprogram/ckb/lead，body 含 targetUserId（token） |
+| 4 | 后端 | 用 token 查 persons 得 ckb_api_key → 推存客宝 scenarios |
+
+### 10.4 数据流总览
+
+```
+管理端添加 Person
+  → 后端：生成 token + 调 CKB 创建计划（SOUL链接人与事-{name}）
+  → 落库：person_id、token、name、ckb_api_key、ckb_plan_id
+
+管理端编辑文章，写入 @[名称](token)
+  → 小程序 contentParser 解析，data-id=token
+
+用户点击 @人物
+  → 小程序 onMentionTap(targetUserId=token)
+  → POST /api/miniprogram/ckb/lead
+  → 后端：token → persons.ckb_api_key → 推存客宝
+
+管理端删除 Person
+  → 后端：删本地 + 调 CKB 删除计划
+```
+
+---
+
+## 十一、参考文档
+
+- `open-api-sign.md`：存客宝开放 API 鉴权规范
+- `Cunkebao/src/pages/mobile/scenarios/plan/new/index.api.ts`：创建/更新计划接口
+- `Cunkebao/src/pages/mobile/scenarios/plan/new/steps/step.api.ts`：场景 CRUD、计划列表
+- `Cunkebao/src/api/request.ts`：请求封装，baseURL=ckbapi.quwanzhi.com，Bearer token
+- `soul-api/internal/handler/db_person.go`：当前 Person 增删改
+- `soul-admin/src/pages/linked-mp/LinkedMpPage.tsx`：关联小程序独立页面结构
diff --git a/开发文档/1、需求/archive/链接人与事-实现方案.md b/开发文档/1、需求/archive/链接人与事-实现方案.md
new file mode 100644
index 00000000..b946e096
--- /dev/null
+++ b/开发文档/1、需求/archive/链接人与事-实现方案.md
@@ -0,0 +1,206 @@
+# 链接人与事 — 实现方案（综合分析）
+
+> 基于需求规划与存客宝源码分析，整理实现清单与实施顺序
+
+---
+
+## 一、现状与缺口
+
+### 1.1 已完成
+
+| 模块 | 内容 | 状态 |
+|------|------|------|
+| 管理端 | 链接人与事 tab、添加/编辑弹窗 PersonAddEditModal | ✅ |
+| 管理端 | 列表展示 token、@的人、获客计划活动名、planId、apiKey（table 布局、apiKey 复制图标） | ✅ |
+| 管理端 | 删除前 Dialog 二次确认弹窗 | ✅ |
+| 管理端 | 编辑计划按钮（跳转存客宝） | ✅ |
+| 后端 | Person CRUD（仅本地，未接 CKB） | ✅ |
+| 后端 | getCkbLeadApiKey（site_settings.ckbLeadApiKey） | ✅ |
+| 小程序 | @ 用 token、onMentionTap 传 targetUserId | ✅ |
+
+### 1.2 待实现
+
+| 模块 | 内容 |
+|------|------|
+| 后端 | Person 模型新增 `ckb_plan_id` |
+| 后端 | CKB 开放 API 客户端（鉴权 + 创建/更新/删除计划） |
+| 后端 | DBPersonSave 接入 CKB 创建/更新 |
+| 后端 | DBPersonDelete 接入 CKB 删除计划 |
+| 管理端 | PersonAddEditModal 提交时传 greeting、tips、ckbAccount（供后端调 CKB） |
+| 待确认 | 设备选择：CKB 创建计划需 deviceGroups，开放 API 是否支持？Soul 如何获取设备？ |
+
+---
+
+## 二、删除二次确认
+
+### 2.1 当前实现（2026-03-16 已升级为 Dialog）
+
+- 使用 `Dialog` + `DialogFooter` 做确认弹窗，替代原生 `confirm()`
+- 按钮：「取消」「确定删除」
+- 弹窗尺寸：max-w-md、p-4，避免过大
+
+---
+
+## 三、后端实现清单
+
+### 3.1 数据库
+
+```sql
+-- persons 表新增 ckb_plan_id
+ALTER TABLE persons ADD COLUMN ckb_plan_id INT DEFAULT NULL COMMENT '存客宝获客计划ID';
+```
+
+### 3.2 Person 模型
+
+```go
+// model/person.go
+CkbPlanId *int `gorm:"column:ckb_plan_id" json:"ckbPlanId"`
+```
+
+### 3.3 CKB 开放 API 客户端
+
+新建 `internal/ckb/open_client.go`：
+
+| 函数 | 说明 |
+|------|------|
+| `GetToken(apiKey, account string) (string, error)` | POST /v1/open/auth/token，返回 JWT |
+| `CreatePlan(token string, req CreatePlanReq) (*CreatePlanResp, error)` | POST /v1/plan/create |
+| `UpdatePlan(token string, planId int, req UpdatePlanReq) error` | PUT /v1/plan/update |
+| `DeletePlan(token string, planId int) error` | DELETE /v1/plan/delete |
+
+**鉴权**：按 `open-api-sign.md`，`sign = MD5(MD5(account+timestamp)+apiKey)`。
+
+**配置**：`CKB_OPEN_API_KEY`、`CKB_OPEN_ACCOUNT`（或从 site_settings 读）。
+
+### 3.4 创建计划请求体（按 Cunkebao 标准）
+
+```go
+type CreatePlanReq struct {
+    Name        string   `json:"name"`        // SOUL链接人与事-{name}
+    SceneId     int      `json:"sceneId"`     // 9（2026-03-16 修正）
+    Scenario    int      `json:"scenario"`    // 9
+    Greeting    string   `json:"greeting"`    // 你好，请通过
+    Tips        string   `json:"tips"`       // 请注意消息，稍后加你微信
+    RemarkType  string   `json:"remarkType"`  // phone
+    AddInterval int      `json:"addInterval"` // 1
+    StartTime   string   `json:"startTime"`   // 09:00
+    EndTime     string   `json:"endTime"`    // 18:00
+    Enabled     bool     `json:"enabled"`     // true
+    DeviceGroups []int   `json:"deviceGroups,omitempty"` // 待确认：开放 API 是否必填
+}
+```
+
+### 3.5 设备选择（待确认）
+
+- Cunkebao 前端创建计划时需选择设备（`deviceGroups`）
+- Soul 通过开放 API 创建时：
+  - 开放 API 是否支持 `deviceGroups`？
+  - 若支持，Soul 如何获取设备列表？是否有 `/v1/open/devices` 或类似接口？
+  - 若不支持或可不传，是否允许 `deviceGroups: []` 创建？
+
+**建议**：先不传 `deviceGroups` 或传空数组，实测 CKB 是否接受；若报错再与存客宝确认。
+
+### 3.6 DBPersonSave 改造
+
+**新增**：
+
+1. 生成 token
+2. 调 `GetToken` 获取 JWT
+3. 调 `CreatePlan`，name=`SOUL链接人与事-{name}`，planType=1、sceneId=9、status=1
+4. 落库：person_id、token、name、label、ckb_api_key（CKB 返回）、ckb_plan_id（CKB 返回）
+
+**更新**：
+
+1. 更新本地 persons
+2. 若有 ckb_plan_id，调 `UpdatePlan` 同步 name、greeting、tips 等
+
+### 3.7 DBPersonDelete 改造
+
+1. 查 Person 得 ckb_plan_id
+2. 若有 ckb_plan_id：调 `GetToken` → `DeletePlan`
+3. 删本地 persons
+
+### 3.8 DBPersonSave 请求体扩展
+
+```go
+var body struct {
+    PersonID   string `json:"personId"`
+    Name       string `json:"name"`
+    Label      string `json:"label"`
+    CkbApiKey  string `json:"ckbApiKey"`
+    CkbAccount string `json:"ckbAccount"`  // 新增：开放 API 鉴权用
+    Greeting   string `json:"greeting"`    // 新增：创建计划用
+    Tips       string `json:"tips"`       // 新增：创建计划用
+}
+```
+
+---
+
+## 四、管理端实现清单
+
+### 4.1 PersonAddEditModal 提交扩展
+
+当前只传 `personId`、`name`、`label`、`ckbApiKey`。需增加：
+
+- `ckbAccount`：存客宝账号（鉴权）
+- `greeting`：打招呼语
+- `tips`：获客成功提示
+
+弹窗内已有这些字段，只需在 `onSubmit` 的 payload 中带上。
+
+### 4.2 ContentPage 提交 payload
+
+```ts
+const payload = {
+  personId: data.personId || ...,
+  name: data.name,
+  label: data.label,
+  ckbApiKey: data.ckbApiKey || undefined,
+  ckbAccount: data.ckbAccount || undefined,  // 新增
+  greeting: data.greeting || undefined,     // 新增
+  tips: data.tips || undefined,             // 新增
+}
+```
+
+### 4.3 删除确认（可选升级）
+
+- 方案 A：保持 `confirm()`，无需改动
+- 方案 B：用 `Dialog` 做确认弹窗，与整体 UI 统一
+
+---
+
+## 五、实施顺序建议
+
+| 阶段 | 任务 | 依赖 |
+|------|------|------|
+| 1 | 数据库迁移：persons 加 ckb_plan_id | - |
+| 2 | Person 模型加 CkbPlanId | 1 |
+| 3 | 实现 CKB 开放 API 客户端（GetToken、CreatePlan、UpdatePlan、DeletePlan） | open-api-sign.md |
+| 4 | DBPersonSave 扩展 body（ckbAccount、greeting、tips） | - |
+| 5 | DBPersonSave 新增逻辑：调 CKB 创建计划 → 落库 | 2, 3, 4 |
+| 6 | DBPersonSave 更新逻辑：调 CKB 更新计划 | 2, 3 |
+| 7 | DBPersonDelete：先删 CKB 计划再删本地 | 2, 3 |
+| 8 | PersonAddEditModal 提交时传 greeting、tips、ckbAccount | - |
+| 9 | ContentPage onSubmit 传完整 payload | 8 |
+| 10 | （可选）删除确认改为 Dialog | - |
+
+---
+
+## 六、风险与待确认
+
+| 项 | 说明 |
+|----|------|
+| 设备选择 | CKB 创建计划是否强制 deviceGroups？开放 API 是否支持？ |
+| 开放 API 路径 | plan 接口是 `/v1/plan/create` 还是 `/v1/open/plan/create`？需确认 baseURL |
+| 错误处理 | CKB 创建失败时，是否仍落库 Person（ckb_plan_id 为空）？建议：创建失败则整体回滚，不落库 |
+| 配置来源 | apiKey、account 用 env 还是 site_settings？当前 ckbLeadApiKey 已支持 site_settings |
+
+---
+
+## 七、参考
+
+- `开发文档/1、需求/链接人与事-存客宝同步-需求规划.md`
+- `open-api-sign.md`
+- `Cunkebao/src/pages/mobile/scenarios/plan/new/`
+- `soul-api/internal/handler/db_person.go`
+- `soul-api/internal/handler/ckb.go`
diff --git a/开发文档/1、需求/archive/链接人与事-所有同步需求.md b/开发文档/1、需求/archive/链接人与事-所有同步需求.md
new file mode 100644
index 00000000..d7285b20
--- /dev/null
+++ b/开发文档/1、需求/archive/链接人与事-所有同步需求.md
@@ -0,0 +1,82 @@
+# 链接人与事 — 所有同步需求汇总
+
+> 整合自：链接人与事-存客宝同步-需求规划、实现方案、2026-03-16 文章编辑自动创建
+
+---
+
+## 一、同步场景总览
+
+| 场景 | 触发 | 同步动作 | 状态 |
+|------|------|----------|------|
+| **创建 Person** | 管理端添加 / 文章 @某人 不存在时自动创建 | 调存客宝创建获客计划 → 落库 ckb_plan_id、ckb_api_key | ✅ 已实现 |
+| **编辑 Person** | 管理端编辑弹窗保存 | 调存客宝更新计划 | 待实现 |
+| **删除 Person** | 管理端删除 | 调存客宝删除计划 → 再删本地 | ✅ 已实现 |
+| **文章 @某人 不存在** | 编辑文章输入 @新人物 并保存 | ensureMentionsAndTags → POST persons → 自动创建 + 同步存客宝 | ✅ 已实现 |
+
+---
+
+## 二、已实现同步
+
+### 2.1 创建 Person 时同步存客宝
+
+- **触发**：POST /api/db/persons（仅传 name 或完整表单）
+- **流程**：生成 token → 调 ckbOpenCreatePlan（deviceGroups 未传时默认选名为 soul 的设备）→ 落库 person_id、token、name、ckb_api_key、ckb_plan_id
+- **实现**：`soul-api/internal/handler/db_person.go`、`ckb_open.go`
+
+### 2.2 删除 Person 时同步删存客宝
+
+- **触发**：DELETE /api/db/persons?personId=xxx
+- **流程**：若有 ckb_plan_id → 调 ckbOpenDeletePlan → 再删本地
+- **实现**：`db_person.go` DBPersonDelete
+
+### 2.3 文章 @某人 自动创建并同步
+
+- **触发**：管理端保存文章，content 含 @新人物（persons 中不存在）
+- **流程**：ensureMentionsAndTags 提取 @name → POST /api/db/persons {name} → 创建 Person + 存客宝计划
+- **实现**：`soul-admin` ContentPage ensureMentionsAndTags；`db_person.go` 按 name 查找/创建
+
+---
+
+## 三、待实现同步
+
+### 3.1 编辑 Person 时同步存客宝
+
+- **触发**：管理端编辑 Person 后保存（PUT 逻辑，personId 已存在）
+- **流程**：更新本地 persons → 若有 ckb_plan_id，调存客宝 PUT /v1/plan/update 同步 name、greeting、tips 等
+- **参考**：`链接人与事-存客宝同步-需求规划.md` 4.2、7.1
+
+---
+
+## 四、配置与前置
+
+| 配置 | 说明 |
+|------|------|
+| CKB_OPEN_API_KEY | 存客宝开放 API 密钥 |
+| CKB_OPEN_ACCOUNT | 存客宝账号（鉴权） |
+| 设备 | 创建计划时 deviceGroups 必填；未传时默认选 memo/nickname 含 "soul" 的设备 |
+
+### 创建计划必填参数（2026-03-16）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| planType | 1 | 必填 |
+| sceneId | 9 | 必填 |
+| scenario | 9 | 与 sceneId 一致 |
+| status | 1 | 必填 |
+
+---
+
+## 五、mention 存储格式（2026-03-16）
+
+| 规则 | 说明 |
+|------|------|
+| **data-label 必填** | TipTap Mention 仅从 `data-label` 解析显示名，缺则回退显示 `data-id`（token） |
+| **ParseAutoLinkContent** | 输出 `data-type="mention"` 的 span 必须含 `data-label` |
+| **已损坏内容** | span 内为 token 时，用 token 查 persons 取真实名字补回 data-label |
+
+## 六、相关文档
+
+- `链接人与事-存客宝同步-需求规划.md` — 原始需求与 API 约定
+- `链接人与事-实现方案.md` — 实现清单
+- `临时需求池/2026-03-16-文章编辑自动创建@和#.md` — 自动创建需求
+- `开发文档/存客宝对接逻辑图.md` — 对接逻辑与参数约定
diff --git a/开发文档/1、需求/archive/链接人与事-置顶功能-技术分析.md b/开发文档/1、需求/archive/链接人与事-置顶功能-技术分析.md
new file mode 100644
index 00000000..dd831c55
--- /dev/null
+++ b/开发文档/1、需求/archive/链接人与事-置顶功能-技术分析.md
@@ -0,0 +1,226 @@
+# 链接人与事 — 置顶功能 技术分析
+
+> 参与角色：管理端开发工程师、后端工程师、小程序开发工程师  
+> 创建日期：2026-03-20  
+> 需求：管理端「链接人与事」列表增加「置顶」能力，置顶人昵称+头像显示在小程序首页右上角；置顶唯一（只能一人）
+
+---
+
+## 一、现状梳理
+
+| 模块 | 现状 |
+|------|------|
+| **管理端** | ContentPage「链接人与事」tab，列表展示 token、@的人、获客数、planId、apiKey、操作（编辑/查看新客户/编辑计划/删除） |
+| **Person 模型** | person_id、token、name、label、user_id、ckb_api_key、ckb_plan_id 等；**无 avatar 字段** |
+| **小程序首页** | 右上角固定展示 `/assets/images/author-avatar.png` + 文案「点击链接卡若」 |
+| **index-lead** | `POST /api/miniprogram/ckb/index-lead` 使用全局 `getCkbLeadApiKey()` 推送到存客宝，文案硬编码「卡若会尽快联系您」 |
+| **置顶存储** | 无，需新增 |
+
+---
+
+## 二、改造方案总览
+
+### 2.1 数据层
+
+| 改造项 | 方案 | 说明 |
+|--------|------|------|
+| 置顶存储 | `system_config` 新增 `pinned_person_token` | config_value 存 `{"token":"xxx"}`，token 为 persons.token |
+| Person 头像 | 方案 A：Person 表加 `avatar` 字段 | 管理端可编辑，小程序展示 |
+| Person 头像 | 方案 B：有 user_id 时 JOIN users 取 avatar | 无 user_id 时用默认占位图 |
+
+**推荐**：Person 表加 `avatar` 字段（VARCHAR 255），管理端 PersonAddEditModal 可编辑；有 user_id 时可选从 users 同步（后续扩展）。
+
+### 2.2 接口层
+
+| 接口 | 使用方 | 说明 |
+|------|--------|------|
+| `PUT /api/db/persons/pin` | 管理端 | body: `{ token }`，置顶该人；先清空其他置顶再设置 |
+| `GET /api/miniprogram/ckb/pinned-person` | 小程序 | 返回 `{ nickname, avatar, token }` 或空（无置顶时） |
+| `POST /api/miniprogram/ckb/index-lead` | 小程序 | 改造：根据 pinned_person_token 查 persons 得 ckb_api_key，推送到该人计划；无置顶时 fallback 全局密钥 |
+
+### 2.3 管理端
+
+- 操作列新增「置顶」图标（Pin 或 Star）
+- 点击置顶：调用 `PUT /api/db/persons/pin`，成功后刷新列表，已置顶行显示「已置顶」标识
+- 置顶互斥：新置顶时，后端自动取消其他人置顶
+
+### 2.4 小程序
+
+- 首页 onLoad/onShow 调用 `GET /api/miniprogram/ckb/pinned-person` 获取置顶人
+- 有数据：展示 `avatar`（网络图需配置 downloadFile 域名）+ `nickname` + 文案「点击链接{nickname}」
+- 无数据：展示默认头像 + 「点击链接卡若」（兼容旧版）
+- 点击留资：仍调 `index-lead`，后端按置顶人 token 推送到对应存客宝计划
+
+---
+
+## 三、流程图
+
+### 3.1 置顶设置流程（管理端）
+
+```mermaid
+flowchart TB
+    subgraph 管理端
+        A[管理员点击「置顶」] --> B[PUT /api/db/persons/pin]
+        B --> C{后端处理}
+        C --> D[读取 system_config.pinned_person_token]
+        D --> E[更新 config_value = 新 token]
+        E --> F[返回 success]
+        F --> G[管理端刷新列表]
+        G --> H[置顶行显示「已置顶」]
+    end
+
+    subgraph 后端
+        C --> I[清空原 pinned_person_token]
+        I --> J[写入新 token]
+        J --> F
+    end
+```
+
+### 3.2 小程序首页展示与留资流程
+
+```mermaid
+flowchart TB
+    subgraph 小程序首页
+        A1[onLoad / onShow] --> A2[GET /api/miniprogram/ckb/pinned-person]
+        A2 --> A3{有置顶人?}
+        A3 -->|是| A4[展示 nickname + avatar]
+        A3 -->|否| A5[展示默认「点击链接卡若」]
+        A4 --> A6[用户点击]
+        A5 --> A6
+        A6 --> A7[POST /api/miniprogram/ckb/index-lead]
+    end
+
+    subgraph 后端 index-lead
+        A7 --> B1[读取 pinned_person_token]
+        B1 --> B2{有置顶?}
+        B2 -->|是| B3[查 persons 得 ckb_api_key]
+        B3 --> B4[用该 key 推存客宝]
+        B2 -->|否| B5[用全局 getCkbLeadApiKey]
+        B5 --> B4
+        B4 --> B6[返回 success]
+    end
+```
+
+### 3.3 三端协同时序图
+
+```mermaid
+sequenceDiagram
+    participant 管理端
+    participant 后端
+    participant 小程序
+
+    Note over 管理端: 阶段 1：置顶设置
+    管理端->>后端: PUT /api/db/persons/pin { token }
+    后端->>后端: 更新 system_config.pinned_person_token
+    后端-->>管理端: success
+
+    Note over 小程序: 阶段 2：首页展示
+    小程序->>后端: GET /api/miniprogram/ckb/pinned-person
+    后端->>后端: 读 pinned_person_token → 查 persons
+    后端-->>小程序: { nickname, avatar, token }
+    小程序->>小程序: 渲染右上角
+
+    Note over 小程序: 阶段 3：用户点击留资
+    小程序->>后端: POST /api/miniprogram/ckb/index-lead
+    后端->>后端: 按 pinned token 取 ckb_api_key → 推存客宝
+    后端-->>小程序: success
+```
+
+---
+
+## 四、实施清单（按角色）
+
+### 4.1 后端工程师
+
+| 序号 | 任务 | 说明 |
+|------|------|------|
+| 1 | Person 模型加 `avatar` | `Avatar string gorm:"column:avatar;size:255" json:"avatar"` |
+| 2 | 迁移脚本 | `ALTER TABLE persons ADD COLUMN avatar VARCHAR(255) DEFAULT ''` |
+| 3 | `PUT /api/db/persons/pin` | body: `{ token }`，更新 system_config.pinned_person_token |
+| 4 | `GET /api/miniprogram/ckb/pinned-person` | 读 pinned token → 查 persons → 返回 nickname、avatar、token |
+| 5 | 改造 CKBIndexLead | 有 pinned 时用 persons.ckb_api_key；无则 fallback 全局 |
+| 6 | PersonAddEditModal 支持 avatar | 管理端提交时传 avatar（可选） |
+
+### 4.2 管理端开发工程师
+
+| 序号 | 任务 | 说明 |
+|------|------|------|
+| 1 | 操作列加「置顶」按钮 | Pin 图标，title「设为置顶」 |
+| 2 | 调用 PUT /api/db/persons/pin | 成功后 toast + 刷新 loadPersons |
+| 3 | 置顶状态展示 | 列表加载后需知「当前置顶是谁」→ 需 GET pinned 接口或列表返回 isPinned |
+| 4 | PersonAddEditModal 加 avatar 输入 | 可选，URL 输入框 |
+
+**置顶状态获取**：后端 `GET /api/db/persons` 可扩展返回 `pinnedToken`（或单独 `GET /api/db/config?key=pinned_person_token`），管理端据此标亮已置顶行。
+
+### 4.3 小程序开发工程师
+
+| 序号 | 任务 | 说明 |
+|------|------|------|
+| 1 | 首页 initData 加 loadPinnedPerson | 调用 GET /api/miniprogram/ckb/pinned-person |
+| 2 | data 增加 pinnedPerson | `{ nickname, avatar, token }` 或 null |
+| 3 | WXML 动态渲染 | `wx:if` 有 pinnedPerson 时用其 avatar + nickname，否则默认 |
+| 4 | 文案 | 有置顶：「点击链接{{pinnedPerson.nickname}}」；无：「点击链接卡若」 |
+| 5 | 头像 | 网络图需配置 downloadFile 合法域名；失败时用占位 |
+
+---
+
+## 五、接口契约
+
+### 5.1 PUT /api/db/persons/pin（管理端）
+
+**请求**：
+```json
+{ "token": "32位persons.token" }
+```
+
+**响应**：
+```json
+{ "success": true }
+```
+或
+```json
+{ "success": false, "error": "该人物不存在" }
+```
+
+### 5.2 GET /api/miniprogram/ckb/pinned-person（小程序）
+
+**响应（有置顶）**：
+```json
+{
+  "success": true,
+  "data": {
+    "nickname": "卡若",
+    "avatar": "https://xxx/avatar.png",
+    "token": "xxx"
+  }
+}
+```
+
+**响应（无置顶）**：
+```json
+{
+  "success": true,
+  "data": null
+}
+```
+
+### 5.3 管理端获取当前置顶
+
+- 方案 A：`GET /api/db/config?key=pinned_person_token` 返回 `{ "token": "xxx" }`
+- 方案 B：`GET /api/db/persons` 响应增加 `pinnedToken` 字段
+
+推荐方案 A，与现有 config 接口一致。
+
+---
+
+## 六、注意事项
+
+1. **缓存**：pinned-person 可加入 config 缓存或短 TTL（如 1 分钟），置顶变更后需失效。
+2. **兼容**：无置顶时，index-lead 保持现有逻辑（全局密钥），文案可继续「卡若会尽快联系您」或改为通用「提交成功」。
+3. **Person 删除**：删除已置顶的 Person 时，后端应同时清空 pinned_person_token。
+4. **头像域名**：小程序展示网络头像需在微信后台配置 downloadFile 合法域名。
+
+---
+
+**创建时间**：2026-03-20  
+**适用**：链接人与事置顶、小程序首页动态展示
diff --git a/开发文档/1、需求/以界面定需求.md b/开发文档/1、需求/以界面定需求.md
new file mode 100644
index 00000000..9f49ce39
--- /dev/null
+++ b/开发文档/1、需求/以界面定需求.md
@@ -0,0 +1,155 @@
+# 以界面定需求
+
+> 开发团队对齐业务逻辑：**以实际界面为准定义需求**，三端（小程序、管理端、soul-api）按界面与接口一致实现。  
+> 本文档为需求与验收的**界面级基准**，新增/变更功能时先对齐界面再落需求文档。
+
+---
+
+## 一、原则
+
+| 原则 | 说明 |
+|------|------|
+| **界面即需求** | 产品需求以「用户可见的界面与操作」为准；接口与数据模型服务于界面。 |
+| **三端路由隔离** | 小程序只调 `/api/miniprogram/*`；管理端只调 `/api/admin/*`、`/api/db/*`、`/api/orders` 等；禁止混用。 |
+| **资料展示统一** | 用户/VIP 展示资料以**用户资料**为准（nickname、avatar、projectIntro、phone 等）；不再单独存 vip_name/vip_avatar 等「VIP 资料列」，小程序与接口均优先读用户资料。 |
+| **文档同步** | 界面或业务规则变更时，同步更新本文档与《需求汇总》需求清单、运营与变更。 |
+
+---
+
+## 二、小程序界面清单
+
+以下为 miniprogram 当前页面（以 `app.json` 与实际调用为准），每页标注：**功能要点**、**主要接口**（均为 `/api/miniprogram/*`）。
+
+| 页面路径 | 功能要点 | 主要接口 |
+|----------|----------|----------|
+| **pages/index/index** | 首页：超级个体/VIP 成员、精选推荐、目录入口、最新章节、用户资料弹窗 | `GET /api/miniprogram/vip/members`、`GET /api/miniprogram/users`、`GET /api/miniprogram/book/recommended`、`GET /api/miniprogram/book/all-chapters`、`GET /api/miniprogram/book/latest-chapters`、`GET /api/miniprogram/user/profile` |
+| **pages/chapters/chapters** | 目录：章节列表、免费/付费/VIP 权限、热门与最新 | `GET /api/miniprogram/book/all-chapters`、`GET /api/miniprogram/config` |
+| **pages/read/read** | 阅读：章节内容、购买状态、支付下单、阅读进度、@提及、代付分享（发起→支付→分享；好友自动领取解锁） | `GET /api/miniprogram/book/chapter`、`GET /api/miniprogram/user/purchase-status`、`POST /api/miniprogram/pay`、`POST /api/miniprogram/user/reading-progress`、`GET /api/miniprogram/config`、`POST /api/miniprogram/gift-pay/create`、`POST /api/miniprogram/gift-pay/initiator-pay`、`POST /api/miniprogram/gift-pay/redeem`、`GET /api/miniprogram/gift-pay/detail` |
+| **pages/match/match** | 找伙伴：匹配类型、留资/匹配提交、资源对接 | `GET /api/miniprogram/config`（match_config）、`POST /api/miniprogram/match/*` 等 |
+| **pages/my/my** | 我的：配置、阅读统计、待确认提现、收益、VIP 状态、提现入口 | `GET /api/miniprogram/config`、`GET /api/miniprogram/user/dashboard-stats`、`GET /api/miniprogram/withdraw/pending-confirm`、`GET /api/miniprogram/earnings`、`GET /api/miniprogram/vip/status`、`POST /api/miniprogram/user/update`、`POST /api/miniprogram/withdraw` |
+| **pages/referral/referral** | 推广中心：推广数据、海报与小程序码、复制文案、申请提现 | `GET /api/miniprogram/referral/data`、`POST /api/miniprogram/qrcode`、`POST /api/miniprogram/withdraw` |
+| **pages/settings/settings** | 设置：头像/昵称/手机/微信号、用户资料编辑、一键获取 | `GET /api/miniprogram/user/profile`、`POST /api/miniprogram/user/update`、`POST /api/miniprogram/phone` |
+| **components/login-modal** | 公用登录弹窗：手机号一键登录、隐私协议、协议勾选；read/my/gift-pay 等页面引入 | 无独立接口，内部调 `app.loginWithPhone`、`app.login` |
+| **pages/vip/vip** | VIP：状态查询、开通支付 | `GET /api/miniprogram/vip/status`、`POST /api/miniprogram/pay`（productType=vip） |
+| **pages/purchases/purchases** | 购买记录 | `GET /api/miniprogram/orders` |
+| **pages/withdraw-records/withdraw-records** | 提现记录、确认收款 | `GET /api/miniprogram/withdraw/records`、`GET /api/miniprogram/withdraw/confirm-info` |
+| **pages/member-detail/member-detail** | 会员详情：展示用户资料（昵称/头像/联系方式/项目介绍，优先用户资料） | `GET /api/miniprogram/user/profile` 或会员接口 |
+| **pages/profile-show/profile-show** | 资料展示 | `GET /api/miniprogram/user/profile` |
+| **pages/profile-edit/profile-edit** | 资料编辑 | `GET /api/miniprogram/user/profile`、`GET /api/miniprogram/vip/status`、`POST /api/miniprogram/user/update` |
+| **pages/mentors/mentors** | 导师列表 | `GET /api/miniprogram/mentors` 等 |
+| **pages/mentor-detail/mentor-detail** | 导师详情、预约 | 导师详情与预约接口 |
+| **pages/about/about** | 关于作者、书籍统计 | `GET /api/miniprogram/about/author`、`GET /api/miniprogram/book/stats` |
+| **pages/addresses/** | 收货地址列表与编辑 | 地址相关 `/api/miniprogram/*` |
+| **pages/search/search** | 搜索 | `GET /api/miniprogram/book/*` 或搜索接口 |
+| **pages/agreement/agreement** | 用户协议 | 静态或配置 |
+| **pages/privacy/privacy** | 隐私政策 | 静态或配置 |
+| **pages/avatar-nickname/avatar-nickname** | 头像+昵称引导页（新用户/非 VIP 完善用） | 无接口，跳转自 app.checkAvatarNicknameAndGuide |
+| **pages/gift-pay/detail** | 代付详情：发起人分享/好友帮他付款 | `GET /api/miniprogram/gift-pay/detail`、支付与领取接口 |
+| **pages/gift-pay/list** | 我的代付列表 | `GET /api/miniprogram/gift-pay/my-requests` 等 |
+| **pages/gift-pay/redemption-detail** | 代付领取详情（发起人查看领取明细） | gift-pay 相关接口 |
+| **pages/wallet/wallet** | 余额/钱包 | 余额相关 `/api/miniprogram/*` |
+| **pages/link-preview/link-preview** | 链接预览（分享/H5 跳转用） | 静态或配置 |
+
+---
+
+## 三、管理端界面清单
+
+以下为 soul-admin 路由（以 `App.tsx`、`AdminLayout` 为准），每页标注：**功能要点**、**主要接口**（`/api/admin/*`、`/api/db/*`、`/api/orders` 等）。
+
+| 路由 | 功能要点 | 主要接口 |
+|------|----------|----------|
+| **/login** | 登录 | `POST /api/admin/login` |
+| **/dashboard** | 数据概览：用户/订单/收入、最近订单、新用户 | `GET /api/admin`、`GET /api/orders`、用户与订单统计 |
+| **/content** | 内容管理：章节树、API 文档入口 | `GET /api/db/chapters`、内容相关 db 接口 |
+| **/users** | 用户管理：列表、搜索、用户详情、设置 VIP、用户规则、超级个体、用户旅程 | `GET /api/db/users`、`PUT /api/db/users`、`GET/POST/PUT/DELETE /api/db/user-rules`、`GET /api/admin/users/:id/balance` |
+| **/find-partner** | 找伙伴：CKB 配置、匹配池、导师、匹配记录、资源对接等 Tab | `GET /api/db/config/full?key=ckb_config`、匹配与导师相关 db/admin 接口 |
+| **/distribution** | 推广中心：分销统计、推广设置入口 | `GET /api/db/distribution`、订单统计 |
+| **/orders** | 订单列表：筛选、分页、退款、用户/推荐人信息、支付方式（微信/余额/代付） | `GET /api/orders`、`PUT /api/admin/orders/refund` |
+| **/withdrawals** | 提现列表：审核、打款、状态 | `GET /api/admin/withdrawals`、提现审核接口 |
+| **/settings** | 系统设置：作者设置、管理员、功能开关、站点、推广设置、免费章节等 | `GET /api/db/config/full`、`POST /api/db/config` 等 |
+| **/vip-roles** | VIP 角色管理：CRUD 预设角色 | `GET /api/db/vip-roles`、`POST /api/db/vip-roles` 等 |
+| **/mentors** | 导师管理 | `GET /api/db/mentors` 等 |
+| **/mentor-consultations** | 导师预约单 | `GET /api/db/mentor-consultations` 等 |
+| **/payment** | 支付相关配置或日志 | 支付相关 admin/db 接口 |
+| **/site** | 站点配置 | `GET /api/db/config`、site 相关 |
+| **/qrcodes** | 小程序码管理 | 小程序码相关接口 |
+| **/match** | 匹配配置或匹配池 | 匹配相关 |
+| **/match-records** | 匹配记录列表 | `GET /api/db/match-records` 等 |
+| **/api-doc** | API 文档 | 静态或链接 soul-api 文档 |
+
+---
+
+## 四、业务逻辑对齐（界面驱动）
+
+以下为团队已对齐的规则，**以界面行为为准**，需求与开发文档与之保持一致。
+
+### 4.1 用户/VIP 资料展示
+
+| 规则 | 说明 |
+|------|------|
+| **展示以用户资料为准** | 昵称、头像、项目介绍、联系方式等一律优先使用用户资料（nickname、avatar、projectIntro、phone、wechatId 等）。 |
+| **不再单独存 VIP 资料列** | 数据库迁移不再新增 vip_name、vip_avatar、vip_project、vip_contact、vip_bio；已有库可保留兼容。 |
+| **VIP 身份与状态仍存 users** | is_vip、vip_expire_date、vip_activated_at、vip_sort、vip_role 仍保留，用于「是否 VIP、到期时间、排序、角色」。 |
+| **小程序展示** | 首页/会员详情等：`name: u.nickname \|\| u.vipName \|\| '会员'`，以用户资料优先。 |
+
+### 4.2 三端 API 边界
+
+| 端 | 允许路径 | 禁止 |
+|----|----------|------|
+| 小程序 | `/api/miniprogram/*` | 禁止调用 `/api/admin/*`、`/api/db/*` |
+| 管理端 | `/api/admin/*`、`/api/db/*`、`/api/orders` 等 | 禁止调用 `/api/miniprogram/*` |
+| soul-api | 路由分组 miniprogram / admin / db，按使用方挂载 | 禁止混用路径语义 |
+
+### 4.3 免费章节与 VIP 阅读
+
+| 规则 | 说明 |
+|------|------|
+| 免费章节 | 以管理端「系统设置 → 免费章节」配置为准（free_chapters / chapter_config.freeChapters），后端合并到章节接口。 |
+| VIP 全章免费 | is_vip=1 且 vip_expire_date>NOW() 时，check-purchased 视为已购买，无需再按章付费。 |
+
+### 4.4 分销与提现
+
+| 规则 | 说明 |
+|------|------|
+| 推广中心 | 管理端「推广中心」对应 distribution；小程序「推广中心」对应 referral 页（海报、数据、提现）。 |
+| 会员分润 | 会员订单推广者 20%、非会员 10%（可配置）；内容订单推广者 90%（可配置，config.shareRate）。 |
+| 提现 | 小程序申请提现走 `/api/miniprogram/withdraw`；管理端审核/打款走 `/api/admin/withdrawals`。 |
+
+### 4.5 资料完善引导（代码已实现）
+
+| 规则 | 说明 |
+|------|------|
+| 入口统一 | `app.checkVipContactRequiredAndGuide`（onLaunch 1.5s / onShow 0.5s 节流 5min / 登录成功 1.2s / VIP 支付成功） |
+| 非 VIP | `checkAvatarNicknameAndGuide`：头像/昵称未完善且今日未提示 → 弹窗「请设置头像和昵称」→ navigateTo avatar-nickname |
+| VIP | 头像/昵称未改 → 弹窗「完善资料」→ redirectTo profile-edit；无手机号 → 弹窗引导；无微信号 → 弹窗引导 |
+| 新用户 | 登录返回 isNewUser 且头像昵称未改 → redirectTo avatar-nickname（无弹窗） |
+| VIP 支付成功 | 弹窗「请填写好资料」→ redirectTo profile-edit?from=vip |
+| 页面分工 | avatar-nickname：仅头像+昵称；profile-edit：完整资料（手机、微信号、MBTI 等） |
+
+### 4.6 购买≥3 章解锁全书
+
+| 规则 | 说明 |
+|------|------|
+| 展示条件 | 阅读页付费墙：`purchasedCount >= 3` 时显示「解锁全部 X 章」按钮 |
+| 无独立弹窗 | 当前实现为按钮直接展示，购买第 3 章后自动出现；无「购买成功弹窗引导解锁全书」 |
+
+---
+
+## 五、与需求文档的关系
+
+| 文档 | 关系 |
+|------|------|
+| **本文档（以界面定需求）** | 界面级需求基准；新增/改版界面或业务规则时先更新本文档。 |
+| **1、需求/索引.md** | 主需求 = 日期最新的需求文件（如 2026-03-20-需求.md）；需求描述与验收标准应与本文档界面及§四业务逻辑一致。 |
+| **运营与变更.md** | 近期变更、讨论结论、技术决策；涉及界面或规则时同步引用本文档。 |
+
+---
+
+## 六、变更记录
+
+| 日期 | 变更内容 |
+|------|----------|
+| 2026-03-11 | 初版：小程序与管理端界面清单、业务逻辑对齐（VIP 资料以用户资料为准、三端路由、免费章与 VIP、分销提现）；与需求汇总、README、运营与变更同步。 |
+| 2026-03-17 | 管理端清单补充：用户规则、用户余额、订单支付方式；详见《管理端迁移分析-基于小程序功能.md》。 |
+| 2026-03-20 | 小程序：登录改为手机号一键登录；新增公用组件 login-modal（read/my/gift-pay 引入）；getPhoneNumber 需耦合 agreePrivacyAuthorization。 |
+| 2026-03-24 | **以代码为准反向补齐**：补充 avatar-nickname、gift-pay 系列、wallet、link-preview；§4.5 资料完善引导、§4.6 购买≥3章解锁全书；config.shareRate 分润展示。 |
diff --git a/开发文档/1、需求/修改/20260406数据管理.plan.md b/开发文档/1、需求/修改/20260406数据管理.plan.md
new file mode 100644
index 00000000..06e832b7
--- /dev/null
+++ b/开发文档/1、需求/修改/20260406数据管理.plan.md
@@ -0,0 +1,19 @@
+
+
+这个目录不要移动到其他地方。这个需求目录。
+
+功能一：
+![](images/2026-04-06-15-12-49.png)首先用户管理这里的这个获客列表已经移动到这个那个推广中心里面，并且把整一个获客利表移动到推广中心，并且把这个页面重构一下，然后这边的话算法配置，最终把这个算法配置给它隐藏掉，给他只显示按钮，不是隐藏掉显示按钮就不要整显示按钮。点击展开就可以了，跟那个是一样的。
+
+![](images/2026-04-06-15-13-14.png)这个推广中心把这个上面的标签作为一些融合跟整合，然后把这个整个推广中心的页面变得那个界面风格变得简洁一些，嗯
+
+
+![](images/2026-04-06-15-14-04.png)首页这里的话只保持前面总用户数到转化率，这边像纯客保获客的标签和这个你个找伙伴相应的摇钱树重新的整合到用户标签，点击统计，然后这个标签体系下老，然后重新的把这个整个的结构变得清晰可见。那变得结构清晰。
+
+![](images/2026-04-06-15-14-42.png)包括这里的话，用户管理的话，这个用户的旅程重重难，这个也是属于数据统计，也是放到这个数据概览的标签里面帮我那个转移，并且把这个界面
+
+![](images/2026-04-06-15-16-48.png)那我把着火犯的这个算法设计清楚，把着火的算法那匹配值这边的算法设计清晰，是随机匹配的，随机匹配按要按照这个人填写的那个标签去匹配用户，填写在用户管理里面，这个用户点击匹配标签，类似的人默认匹配标签内类似的人。如果没有标签，尽可能的去标签类似，然后男生算法是这样的，男生匹配女生，第一个的话是匹配标签算法，标签类似的人，用户旅程类似的人，行为类似的人，那匹配那个 emmbt 还性格互补的人。这个按这个算法去匹配第二个在如果这一切没有填写在匹配男女第三个的话，在匹配那个。在匹配最后没有的话再随机匹配它整个的找伙伴的算法是这样，帮我把这个重新设计一下，并且这个算法是可编辑的。这个把这个算法。解放那个右上角，然后把这个存克宝的右上角，这个存克宝的这个功能跟推广中心的功能做一个融合，直接把功能不要重复，直接融合到推广中心里面。
+
+![](images/2026-04-06-15-17-39.png)把整个推广中心的所有的目录跟结构变得更有序，核心的一点是知道谁获客多少，谁绑定了多少，然后谁是最佳的那个推广的人，以及他的绑定收益和提现相关的功能，把整个推广中心做一个深度的一个重构。
+
+![](images/2026-04-06-15-18-46.png)然后一定要确定这个，这里面就不用头像，就不要有这么多选项了，确保不要是裂开的头像。在 EMBTI 头像那，确保每一用户都有相应的那个 MBTI 的头像。然后把整个头像重构的极度简单，然后确保整个的那个用户在前端也是可以选择在后台的头像的，没有选择，有选就自动按照他的那个性格直接匹配，没有的话就直接选择。然后把整个界面包括那些说明缩进一点简介简洁一点，缩进说说一些进去。
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/20260406用户管理-超级个体重构.md b/开发文档/1、需求/修改/20260406用户管理-超级个体重构.md
new file mode 100644
index 00000000..49c0cfdf
--- /dev/null
+++ b/开发文档/1、需求/修改/20260406用户管理-超级个体重构.md
@@ -0,0 +1,30 @@
+
+
+> **承接**：`-4` 已归档 `已完成/用户管理 20260406-2.plan.md`。  
+> 有下一批网关/观测需求时在此表排期；无则保持空模板。
+
+---
+
+## 待排期
+
+| 项 | 状态 | 说明 |
+|:---|:---|:---|
+![](images/2026-04-06-09-33-10.png)这个应，这个要更新一个 go购买的，购买状态的用户旅程的一个模块，用户旅程的模块放到里面，比如他购买的任何，包括我们新增的任何的那个收费项目，都要显示在这个购买的状态里面，那我知道所有的那个购买的人的那个收益，清晰的知道他的那个收益。
+
+功能二：
+/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/static
+
+用户的头像，用户的这个头像，NBTI 默认用这16个头像的，NBTI 默认就用这16个头像，直接就可以在后台是可以直接选择这个头像，没有，如果没有设置性格的话，就有设置性格就匹配性格，没有设置性格的话是随机选一张图片，男男的女的都可以。是可以选男版，可以选女版，分开把这个头像做优化迭代，然后把所有的这些会员，没有头像的会员全部设置一下
+
+功能三：
+![](images/2026-04-06-10-31-25.png)这个 BTI 的这个头像两版根据那个男的女的自由的去分配，有选择男的女的在，可以只有这两个版本，其他的版本全部删掉，那男的女的版本，然后确保它是显示可以显示出来，那我把那个 SVG 的格式改成那个 PNG 的格式。那把这个 NBT 这个头像库，这一个简洁一点的，弄得简洁一点，现在看稿件有点太复杂了，弄得简洁一些。
+![](images/2026-04-06-10-31-58.png)然后把用户，那个用户的里面去随机匹配用户列表，随机匹配，把这个没有的头像的这一些用户没有头像的随机匹配掉，然后购买状态这边要跟咱们有付款行为的都可以都要显示在这个购买状态里面，最近一次购买只显示这一个，不要显示未购买的状态。目标是确保有相应的那个头像和人设
+
+功能四：迁移
+![](images/2026-04-06-10-32-42.png)然后这个获客列表。霍克利，表帮我放到那个推广中心里面，并且整个页面重构的剪辑一些。
+
+功能五：
+![](images/2026-04-06-10-34-23.png)那个超级个体的一些那个获客情况跟那个超级个体的这个获客情况。在这个我的里面找一个比较一个不那么显眼的一个地方的页面，帮我做一个那个超级个体的一个获客情况，以及它的一个热度。这怎么一个界面在上面的一个功能？
+
+![](images/2026-04-06-10-37-33.png)
+![](images/2026-04-06-10-37-52.png)然后根据这整个的这个用户旅程总览这边的话，根据这整个的那个用户列表和这个用户目的是让我能清楚的知道所有的这个用户哪一个流量池好过什么用户流旅程哪个流量池，然后的整个用户的一个关系，目的是让我知道这一些客户的一个具体的一些详细的一个情况。然后以及表格行为表格一个分析，然后这些分析触发，最终得到这个用户估值的一整个分析的一个解决方案，然后通过用户里程来进行各个板块的分析，然后这个把这整个的用户里程的界面帮我做一些，做一下那个重构。
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/20260406用户管理-首页入口融合.md b/开发文档/1、需求/修改/20260406用户管理-首页入口融合.md
new file mode 100644
index 00000000..6bf3af39
--- /dev/null
+++ b/开发文档/1、需求/修改/20260406用户管理-首页入口融合.md
@@ -0,0 +1,25 @@
+
+
+> **承接**：`-4` 已归档 `已完成/用户管理 20260406-2.plan.md`。  
+> 有下一批网关/观测需求时在此表排期；无则保持空模板。
+
+---
+
+## 待排期
+
+| 项 | 状态 | 说明 |
+|:---|:---|:---|
+功能一：
+
+这首夜路口默认的位置，这个。这个直接是要并到那个超级个体的那个目录底下的，直接就是并到超级个体的那个目录底下。超级的直接就是变成超级个体的，指定的超级个体的配置里面。而不是独立一项去做选择，就每一个超级个体都可以像做小检选择，然后把整个页面那个重构一下，简洁一点![](images/2026-04-06-04-17-32.png)
+然后这里首页的入口默认这个，就不要选这一个目录，就直接合并到这里，就不要再显示了。
+配置简洁一些，配置界面简洁一些，不要搞得这么复杂
+
+
+功能二：
+![](images/2026-04-06-05-53-15.png)这个搜索会员用户没有搜索到有问题，并不精确。嗯，搜索这个名字并不精确，没有搜索到，帮我处理一下这个问题，并且详细检查一下一系列的相关的可能出现的一个问题的一个处理。
+![](images/2026-04-06-05-54-12.png)然后这个超级，这个点击这边不精确点击，就是实际的点击，现在不可能只点击都放到这个流光底下的，其他的那个点击的情况你看一下到底是什么，什么什么情况，帮我修复一下这个点击的一个问题。点击了一个相关的问题。帮你，帮我处理一下。脑以及存克宝相关的这个配置。
+
+![](images/2026-04-06-05-55-07.png)然后还有一点的话，就是这个点，那个获客这里的话要需要和纯客保那边的获客是那个那协同的纯科宝那边具体的那个获客的数据就这里要能点击并获客，这里要可以点击展开。然后并且这个成员这里的话，也是需要能直接点击就打开这个会员的那个用户的相关的那个数据，这个需要跟那个前端的用户页，用户管理里面实际的那个用户是捆绑关系，超级个体也是归属于用户的用户列表里面的一种。
+
+![](images/2026-04-06-05-55-49.png)然后这个功能完善之后，在咱们的那个小程序这里要反映过来，小程序这边的话能直接显示并且配置清楚那个所有的点击的这个功能可以直接展开，包括超级个体里面的话。这个功能每个超级个体点点击上去的话，配置好都是可以使用这个的功能的。
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/20260408用户管理—1—.md b/开发文档/1、需求/修改/20260408用户管理—1—.md
new file mode 100644
index 00000000..2c0091b1
--- /dev/null
+++ b/开发文档/1、需求/修改/20260408用户管理—1—.md
@@ -0,0 +1,17 @@
+
+
+
+功能一：
+![](images/2026-04-08-04-40-30.png)
+这个用户的用户详情的这个旅程与鬼用户旅程跟轨迹和用户没匹配不上。检查一下。
+
+功能二：
+![](images/2026-04-08-04-43-15.png)这里的话要确保这个行为标签是中文的，像这个 form 点击了一个按钮，不清楚。以后这个点击的这个标签的按钮得清晰一些。要变成中文的，具体点击谁的，哪一个的清晰。
+
+
+![](images/2026-04-08-04-45-27.png)
+小伙伴，找伙伴底下的这个找伙伴的数据概览，这个删除掉。
+
+![](images/2026-04-08-04-46-25.png)推广中心的这个获客列表的页面重构，直接重构掉。
+
+![](images/2026-04-08-04-47-06.png)那前面的话那个排行。推广排行的话，底下这些人编辑可以去掉，可以隐藏掉，可以忽略到排行表上面，把分数去掉，可以按那个按分数去排行。给指定人去做排行。
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/Soul  20260118.pdf b/开发文档/1、需求/修改/Soul  20260118.pdf
new file mode 100644
index 00000000..02b7a2ec
Binary files /dev/null and b/开发文档/1、需求/修改/Soul  20260118.pdf differ
diff --git a/开发文档/1、需求/修改/images/![描述](./images/截图1.png)`.png b/开发文档/1、需求/修改/images/![描述](./images/截图1.png)`.png
new file mode 100644
index 00000000..691139b9
Binary files /dev/null and b/开发文档/1、需求/修改/images/![描述](./images/截图1.png)`.png differ
diff --git a/开发文档/1、需求/修改/images/.gitkeep b/开发文档/1、需求/修改/images/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-02-44.png b/开发文档/1、需求/修改/images/2026-03-08-08-02-44.png
new file mode 100644
index 00000000..26a4fcb4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-02-44.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-05-57.png b/开发文档/1、需求/修改/images/2026-03-08-08-05-57.png
new file mode 100644
index 00000000..691139b9
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-05-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-08-36.png b/开发文档/1、需求/修改/images/2026-03-08-08-08-36.png
new file mode 100644
index 00000000..362b6679
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-08-36.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-11-21.png b/开发文档/1、需求/修改/images/2026-03-08-08-11-21.png
new file mode 100644
index 00000000..b5cc0318
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-11-21.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-16-43.png b/开发文档/1、需求/修改/images/2026-03-08-08-16-43.png
new file mode 100644
index 00000000..54c56ae6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-16-43.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-16-47.png b/开发文档/1、需求/修改/images/2026-03-08-08-16-47.png
new file mode 100644
index 00000000..54c56ae6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-16-47.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-35-20.png b/开发文档/1、需求/修改/images/2026-03-08-08-35-20.png
new file mode 100644
index 00000000..be69f520
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-35-20.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-37-41.png b/开发文档/1、需求/修改/images/2026-03-08-08-37-41.png
new file mode 100644
index 00000000..8bc262c6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-37-41.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-42-59.png b/开发文档/1、需求/修改/images/2026-03-08-08-42-59.png
new file mode 100644
index 00000000..96425dfc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-42-59.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-08-45-48.png b/开发文档/1、需求/修改/images/2026-03-08-08-45-48.png
new file mode 100644
index 00000000..7713b2b2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-08-45-48.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-09-07-07.png b/开发文档/1、需求/修改/images/2026-03-08-09-07-07.png
new file mode 100644
index 00000000..d6d3a9cd
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-09-07-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-09-07-58.png b/开发文档/1、需求/修改/images/2026-03-08-09-07-58.png
new file mode 100644
index 00000000..6c2e9f77
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-09-07-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-09-10-04.png b/开发文档/1、需求/修改/images/2026-03-08-09-10-04.png
new file mode 100644
index 00000000..91ea3896
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-09-10-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-08-47.png b/开发文档/1、需求/修改/images/2026-03-08-10-08-47.png
new file mode 100644
index 00000000..3e5f98da
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-08-47.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-17-14.png b/开发文档/1、需求/修改/images/2026-03-08-10-17-14.png
new file mode 100644
index 00000000..c5021da2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-17-14.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-18-28.png b/开发文档/1、需求/修改/images/2026-03-08-10-18-28.png
new file mode 100644
index 00000000..f2da3e2e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-18-28.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-21-19.png b/开发文档/1、需求/修改/images/2026-03-08-10-21-19.png
new file mode 100644
index 00000000..154d9cfa
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-21-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-28-11.png b/开发文档/1、需求/修改/images/2026-03-08-10-28-11.png
new file mode 100644
index 00000000..8e9f093f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-28-11.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-30-34.png b/开发文档/1、需求/修改/images/2026-03-08-10-30-34.png
new file mode 100644
index 00000000..cb02a3be
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-30-34.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-31-24.png b/开发文档/1、需求/修改/images/2026-03-08-10-31-24.png
new file mode 100644
index 00000000..2fb548f7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-31-24.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-43-44.png b/开发文档/1、需求/修改/images/2026-03-08-10-43-44.png
new file mode 100644
index 00000000..809d7ac1
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-43-44.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-44-05.png b/开发文档/1、需求/修改/images/2026-03-08-10-44-05.png
new file mode 100644
index 00000000..532f8e7c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-44-05.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-46-02.png b/开发文档/1、需求/修改/images/2026-03-08-10-46-02.png
new file mode 100644
index 00000000..c053e673
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-46-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-47-24.png b/开发文档/1、需求/修改/images/2026-03-08-10-47-24.png
new file mode 100644
index 00000000..caa38799
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-47-24.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-56-15.png b/开发文档/1、需求/修改/images/2026-03-08-10-56-15.png
new file mode 100644
index 00000000..1f3d6a05
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-56-15.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-58-04.png b/开发文档/1、需求/修改/images/2026-03-08-10-58-04.png
new file mode 100644
index 00000000..822f57cc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-58-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-10-59-57.png b/开发文档/1、需求/修改/images/2026-03-08-10-59-57.png
new file mode 100644
index 00000000..4f4fe844
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-10-59-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-17-15.png b/开发文档/1、需求/修改/images/2026-03-08-11-17-15.png
new file mode 100644
index 00000000..aa7cd440
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-17-15.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-18-04.png b/开发文档/1、需求/修改/images/2026-03-08-11-18-04.png
new file mode 100644
index 00000000..a337b0cb
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-18-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-19-38.png b/开发文档/1、需求/修改/images/2026-03-08-11-19-38.png
new file mode 100644
index 00000000..9e50cffc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-19-38.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-20-02.png b/开发文档/1、需求/修改/images/2026-03-08-11-20-02.png
new file mode 100644
index 00000000..43ccdabd
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-20-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-22-09.png b/开发文档/1、需求/修改/images/2026-03-08-11-22-09.png
new file mode 100644
index 00000000..a91f5df6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-22-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-30-23.png b/开发文档/1、需求/修改/images/2026-03-08-11-30-23.png
new file mode 100644
index 00000000..c127e04d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-30-23.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-31-27.png b/开发文档/1、需求/修改/images/2026-03-08-11-31-27.png
new file mode 100644
index 00000000..bb6d0efc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-31-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-32-34.png b/开发文档/1、需求/修改/images/2026-03-08-11-32-34.png
new file mode 100644
index 00000000..bd25583d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-32-34.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-11-32-54.png b/开发文档/1、需求/修改/images/2026-03-08-11-32-54.png
new file mode 100644
index 00000000..6c4a6aeb
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-11-32-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-15-58-20.png b/开发文档/1、需求/修改/images/2026-03-08-15-58-20.png
new file mode 100644
index 00000000..2ca829f5
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-15-58-20.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-15-59-01.png b/开发文档/1、需求/修改/images/2026-03-08-15-59-01.png
new file mode 100644
index 00000000..b8c0d2e3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-15-59-01.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-15-59-53.png b/开发文档/1、需求/修改/images/2026-03-08-15-59-53.png
new file mode 100644
index 00000000..eae81c52
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-15-59-53.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-02-09.png b/开发文档/1、需求/修改/images/2026-03-08-16-02-09.png
new file mode 100644
index 00000000..a1be22bf
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-02-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-14-58.png b/开发文档/1、需求/修改/images/2026-03-08-16-14-58.png
new file mode 100644
index 00000000..35f17fad
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-14-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-15-14.png b/开发文档/1、需求/修改/images/2026-03-08-16-15-14.png
new file mode 100644
index 00000000..169bb455
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-15-14.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-15-31.png b/开发文档/1、需求/修改/images/2026-03-08-16-15-31.png
new file mode 100644
index 00000000..4b9c3001
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-15-31.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-18-08.png b/开发文档/1、需求/修改/images/2026-03-08-16-18-08.png
new file mode 100644
index 00000000..9cc05b91
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-18-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-30-11.png b/开发文档/1、需求/修改/images/2026-03-08-16-30-11.png
new file mode 100644
index 00000000..0910aa79
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-30-11.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-31-01.png b/开发文档/1、需求/修改/images/2026-03-08-16-31-01.png
new file mode 100644
index 00000000..f41b0768
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-31-01.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-32-02.png b/开发文档/1、需求/修改/images/2026-03-08-16-32-02.png
new file mode 100644
index 00000000..639c2dc6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-32-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-33-49.png b/开发文档/1、需求/修改/images/2026-03-08-16-33-49.png
new file mode 100644
index 00000000..7b43e266
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-33-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-34-58.png b/开发文档/1、需求/修改/images/2026-03-08-16-34-58.png
new file mode 100644
index 00000000..30a38b25
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-34-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-36-11.png b/开发文档/1、需求/修改/images/2026-03-08-16-36-11.png
new file mode 100644
index 00000000..6c600ca0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-36-11.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-47-03.png b/开发文档/1、需求/修改/images/2026-03-08-16-47-03.png
new file mode 100644
index 00000000..0e6c2bfb
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-47-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-47-11.png b/开发文档/1、需求/修改/images/2026-03-08-16-47-11.png
new file mode 100644
index 00000000..59c150bf
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-47-11.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-16-48-36.png b/开发文档/1、需求/修改/images/2026-03-08-16-48-36.png
new file mode 100644
index 00000000..820c88a6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-16-48-36.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-09-33.png b/开发文档/1、需求/修改/images/2026-03-08-17-09-33.png
new file mode 100644
index 00000000..5a6b2276
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-09-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-10-32.png b/开发文档/1、需求/修改/images/2026-03-08-17-10-32.png
new file mode 100644
index 00000000..af310b88
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-10-32.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-11-50.png b/开发文档/1、需求/修改/images/2026-03-08-17-11-50.png
new file mode 100644
index 00000000..66228136
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-11-50.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-13-34.png b/开发文档/1、需求/修改/images/2026-03-08-17-13-34.png
new file mode 100644
index 00000000..6e5c7200
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-13-34.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-14-04.png b/开发文档/1、需求/修改/images/2026-03-08-17-14-04.png
new file mode 100644
index 00000000..ca0b85f7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-14-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-15-30.png b/开发文档/1、需求/修改/images/2026-03-08-17-15-30.png
new file mode 100644
index 00000000..71e956b2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-15-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-16-57.png b/开发文档/1、需求/修改/images/2026-03-08-17-16-57.png
new file mode 100644
index 00000000..ec3e0071
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-16-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-08-17-17-25.png b/开发文档/1、需求/修改/images/2026-03-08-17-17-25.png
new file mode 100644
index 00000000..a9e8b98b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-08-17-17-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-36-17.png b/开发文档/1、需求/修改/images/2026-03-09-04-36-17.png
new file mode 100644
index 00000000..ebe6d3db
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-36-17.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-37-35.png b/开发文档/1、需求/修改/images/2026-03-09-04-37-35.png
new file mode 100644
index 00000000..35db7280
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-37-35.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-38-20.png b/开发文档/1、需求/修改/images/2026-03-09-04-38-20.png
new file mode 100644
index 00000000..8656d862
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-38-20.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-42-08.png b/开发文档/1、需求/修改/images/2026-03-09-04-42-08.png
new file mode 100644
index 00000000..fdfe3da7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-42-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-46-02.png b/开发文档/1、需求/修改/images/2026-03-09-04-46-02.png
new file mode 100644
index 00000000..c7d9b287
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-46-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-48-03.png b/开发文档/1、需求/修改/images/2026-03-09-04-48-03.png
new file mode 100644
index 00000000..fe0ec8c3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-48-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-49-01.png b/开发文档/1、需求/修改/images/2026-03-09-04-49-01.png
new file mode 100644
index 00000000..373c090c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-49-01.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-50-16.png b/开发文档/1、需求/修改/images/2026-03-09-04-50-16.png
new file mode 100644
index 00000000..d958869b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-50-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-04-51-03.png b/开发文档/1、需求/修改/images/2026-03-09-04-51-03.png
new file mode 100644
index 00000000..4f694777
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-04-51-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-18-28.png b/开发文档/1、需求/修改/images/2026-03-09-05-18-28.png
new file mode 100644
index 00000000..499f2111
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-18-28.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-22-19.png b/开发文档/1、需求/修改/images/2026-03-09-05-22-19.png
new file mode 100644
index 00000000..55deb595
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-22-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-23-53.png b/开发文档/1、需求/修改/images/2026-03-09-05-23-53.png
new file mode 100644
index 00000000..8cb4d840
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-23-53.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-24-19.png b/开发文档/1、需求/修改/images/2026-03-09-05-24-19.png
new file mode 100644
index 00000000..8ef20f12
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-24-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-25-52.png b/开发文档/1、需求/修改/images/2026-03-09-05-25-52.png
new file mode 100644
index 00000000..4d916e3b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-25-52.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-35-24.png b/开发文档/1、需求/修改/images/2026-03-09-05-35-24.png
new file mode 100644
index 00000000..f411da30
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-35-24.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-09-05-36-51.png b/开发文档/1、需求/修改/images/2026-03-09-05-36-51.png
new file mode 100644
index 00000000..55774621
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-09-05-36-51.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-08-58-59.png b/开发文档/1、需求/修改/images/2026-03-15-08-58-59.png
new file mode 100644
index 00000000..5fce6756
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-08-58-59.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-08-59-21.png b/开发文档/1、需求/修改/images/2026-03-15-08-59-21.png
new file mode 100644
index 00000000..d3b76108
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-08-59-21.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-08-59-41.png b/开发文档/1、需求/修改/images/2026-03-15-08-59-41.png
new file mode 100644
index 00000000..252ad185
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-08-59-41.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-01-19.png b/开发文档/1、需求/修改/images/2026-03-15-09-01-19.png
new file mode 100644
index 00000000..e29e8c8e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-01-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-03-58.png b/开发文档/1、需求/修改/images/2026-03-15-09-03-58.png
new file mode 100644
index 00000000..9669aa4c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-03-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-52-35.png b/开发文档/1、需求/修改/images/2026-03-15-09-52-35.png
new file mode 100644
index 00000000..0767ea7a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-52-35.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-52-53.png b/开发文档/1、需求/修改/images/2026-03-15-09-52-53.png
new file mode 100644
index 00000000..922b17b7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-52-53.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-54-15.png b/开发文档/1、需求/修改/images/2026-03-15-09-54-15.png
new file mode 100644
index 00000000..580cc3ce
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-54-15.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-56-46.png b/开发文档/1、需求/修改/images/2026-03-15-09-56-46.png
new file mode 100644
index 00000000..748e59e7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-56-46.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-57-27.png b/开发文档/1、需求/修改/images/2026-03-15-09-57-27.png
new file mode 100644
index 00000000..7f4e9fc2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-57-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-57-54.png b/开发文档/1、需求/修改/images/2026-03-15-09-57-54.png
new file mode 100644
index 00000000..2f7ae776
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-57-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-09-58-57.png b/开发文档/1、需求/修改/images/2026-03-15-09-58-57.png
new file mode 100644
index 00000000..f4ebeaf0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-09-58-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-10-00-09.png b/开发文档/1、需求/修改/images/2026-03-15-10-00-09.png
new file mode 100644
index 00000000..aa897e96
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-10-00-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-10-00-33.png b/开发文档/1、需求/修改/images/2026-03-15-10-00-33.png
new file mode 100644
index 00000000..580b07e3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-10-00-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-10-02-49.png b/开发文档/1、需求/修改/images/2026-03-15-10-02-49.png
new file mode 100644
index 00000000..3c5fb2c8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-10-02-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-10-04-37.png b/开发文档/1、需求/修改/images/2026-03-15-10-04-37.png
new file mode 100644
index 00000000..2822e21f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-10-04-37.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-10-31-25.png b/开发文档/1、需求/修改/images/2026-03-15-10-31-25.png
new file mode 100644
index 00000000..68926c1f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-10-31-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-10-38-24.png b/开发文档/1、需求/修改/images/2026-03-15-10-38-24.png
new file mode 100644
index 00000000..a44bc092
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-10-38-24.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-02-38.png b/开发文档/1、需求/修改/images/2026-03-15-11-02-38.png
new file mode 100644
index 00000000..ec53fd8c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-02-38.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-06-59.png b/开发文档/1、需求/修改/images/2026-03-15-11-06-59.png
new file mode 100644
index 00000000..5985ad61
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-06-59.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-13-16.png b/开发文档/1、需求/修改/images/2026-03-15-11-13-16.png
new file mode 100644
index 00000000..463a11f0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-13-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-17-27.png b/开发文档/1、需求/修改/images/2026-03-15-11-17-27.png
new file mode 100644
index 00000000..e7eb5875
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-17-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-38-40.png b/开发文档/1、需求/修改/images/2026-03-15-11-38-40.png
new file mode 100644
index 00000000..772b50a0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-38-40.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-39-07.png b/开发文档/1、需求/修改/images/2026-03-15-11-39-07.png
new file mode 100644
index 00000000..9a9d9b9b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-39-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-40-29.png b/开发文档/1、需求/修改/images/2026-03-15-11-40-29.png
new file mode 100644
index 00000000..f5122ad2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-40-29.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-48-00.png b/开发文档/1、需求/修改/images/2026-03-15-11-48-00.png
new file mode 100644
index 00000000..2d0c0b15
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-48-00.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-11-54-06.png b/开发文档/1、需求/修改/images/2026-03-15-11-54-06.png
new file mode 100644
index 00000000..5e02b01a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-11-54-06.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-12-00-17.png b/开发文档/1、需求/修改/images/2026-03-15-12-00-17.png
new file mode 100644
index 00000000..0ac81ce1
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-12-00-17.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-35-04.png b/开发文档/1、需求/修改/images/2026-03-15-13-35-04.png
new file mode 100644
index 00000000..9fd558fa
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-35-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-38-39.png b/开发文档/1、需求/修改/images/2026-03-15-13-38-39.png
new file mode 100644
index 00000000..5bf8fa9f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-38-39.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-39-09.png b/开发文档/1、需求/修改/images/2026-03-15-13-39-09.png
new file mode 100644
index 00000000..f25fd79c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-39-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-40-30.png b/开发文档/1、需求/修改/images/2026-03-15-13-40-30.png
new file mode 100644
index 00000000..999aefa8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-40-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-41-54.png b/开发文档/1、需求/修改/images/2026-03-15-13-41-54.png
new file mode 100644
index 00000000..cb279231
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-41-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-42-55.png b/开发文档/1、需求/修改/images/2026-03-15-13-42-55.png
new file mode 100644
index 00000000..7fbd0d92
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-42-55.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-45-21.png b/开发文档/1、需求/修改/images/2026-03-15-13-45-21.png
new file mode 100644
index 00000000..58fef7b3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-45-21.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-46-08.png b/开发文档/1、需求/修改/images/2026-03-15-13-46-08.png
new file mode 100644
index 00000000..1a2cea04
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-46-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-13-48-10.png b/开发文档/1、需求/修改/images/2026-03-15-13-48-10.png
new file mode 100644
index 00000000..e9aa0eee
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-13-48-10.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-14-00-44.png b/开发文档/1、需求/修改/images/2026-03-15-14-00-44.png
new file mode 100644
index 00000000..1ccf744e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-14-00-44.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-14-00-57.png b/开发文档/1、需求/修改/images/2026-03-15-14-00-57.png
new file mode 100644
index 00000000..4ed7a10a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-14-00-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-14-34.png b/开发文档/1、需求/修改/images/2026-03-15-15-14-34.png
new file mode 100644
index 00000000..d791a330
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-14-34.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-17-08.png b/开发文档/1、需求/修改/images/2026-03-15-15-17-08.png
new file mode 100644
index 00000000..95dbf795
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-17-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-23-04.png b/开发文档/1、需求/修改/images/2026-03-15-15-23-04.png
new file mode 100644
index 00000000..28010a7a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-23-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-28-26.png b/开发文档/1、需求/修改/images/2026-03-15-15-28-26.png
new file mode 100644
index 00000000..0b938bca
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-28-26.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-29-05.png b/开发文档/1、需求/修改/images/2026-03-15-15-29-05.png
new file mode 100644
index 00000000..aae67f85
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-29-05.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-31-01.png b/开发文档/1、需求/修改/images/2026-03-15-15-31-01.png
new file mode 100644
index 00000000..927d3dc9
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-31-01.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-32-18.png b/开发文档/1、需求/修改/images/2026-03-15-15-32-18.png
new file mode 100644
index 00000000..85447568
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-32-18.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-38-25.png b/开发文档/1、需求/修改/images/2026-03-15-15-38-25.png
new file mode 100644
index 00000000..b60aed28
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-38-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-38-44.png b/开发文档/1、需求/修改/images/2026-03-15-15-38-44.png
new file mode 100644
index 00000000..8a8ef913
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-38-44.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-43-56.png b/开发文档/1、需求/修改/images/2026-03-15-15-43-56.png
new file mode 100644
index 00000000..1e6a6fe4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-43-56.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-44-38.png b/开发文档/1、需求/修改/images/2026-03-15-15-44-38.png
new file mode 100644
index 00000000..fd5dc071
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-44-38.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-45-31.png b/开发文档/1、需求/修改/images/2026-03-15-15-45-31.png
new file mode 100644
index 00000000..8dea2f10
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-45-31.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-47-07.png b/开发文档/1、需求/修改/images/2026-03-15-15-47-07.png
new file mode 100644
index 00000000..2db78822
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-47-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-51-08.png b/开发文档/1、需求/修改/images/2026-03-15-15-51-08.png
new file mode 100644
index 00000000..571b5de8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-51-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-52-30.png b/开发文档/1、需求/修改/images/2026-03-15-15-52-30.png
new file mode 100644
index 00000000..9a66d004
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-52-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-53-00.png b/开发文档/1、需求/修改/images/2026-03-15-15-53-00.png
new file mode 100644
index 00000000..d212eaaa
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-53-00.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-15-55-33.png b/开发文档/1、需求/修改/images/2026-03-15-15-55-33.png
new file mode 100644
index 00000000..aa65fe27
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-15-55-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-19-13-23.png b/开发文档/1、需求/修改/images/2026-03-15-19-13-23.png
new file mode 100644
index 00000000..395cceca
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-19-13-23.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-19-53-08.png b/开发文档/1、需求/修改/images/2026-03-15-19-53-08.png
new file mode 100644
index 00000000..0e133bd7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-19-53-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-19-53-58.png b/开发文档/1、需求/修改/images/2026-03-15-19-53-58.png
new file mode 100644
index 00000000..faba27a5
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-19-53-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-19-56-29.png b/开发文档/1、需求/修改/images/2026-03-15-19-56-29.png
new file mode 100644
index 00000000..f86d8e56
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-19-56-29.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-20-00-02.png b/开发文档/1、需求/修改/images/2026-03-15-20-00-02.png
new file mode 100644
index 00000000..b4463bf2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-20-00-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-20-01-17.png b/开发文档/1、需求/修改/images/2026-03-15-20-01-17.png
new file mode 100644
index 00000000..194f5d12
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-20-01-17.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-20-01-58.png b/开发文档/1、需求/修改/images/2026-03-15-20-01-58.png
new file mode 100644
index 00000000..cf885186
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-20-01-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-20-04-09.png b/开发文档/1、需求/修改/images/2026-03-15-20-04-09.png
new file mode 100644
index 00000000..8b31997b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-20-04-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-22-57.png b/开发文档/1、需求/修改/images/2026-03-15-22-22-57.png
new file mode 100644
index 00000000..1de46951
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-22-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-23-49.png b/开发文档/1、需求/修改/images/2026-03-15-22-23-49.png
new file mode 100644
index 00000000..da2f5d88
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-23-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-24-45.png b/开发文档/1、需求/修改/images/2026-03-15-22-24-45.png
new file mode 100644
index 00000000..18b7a638
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-24-45.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-27-57.png b/开发文档/1、需求/修改/images/2026-03-15-22-27-57.png
new file mode 100644
index 00000000..0c607e4e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-27-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-28-36.png b/开发文档/1、需求/修改/images/2026-03-15-22-28-36.png
new file mode 100644
index 00000000..696e293b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-28-36.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-33-29.png b/开发文档/1、需求/修改/images/2026-03-15-22-33-29.png
new file mode 100644
index 00000000..4ccf52a1
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-33-29.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-34-51.png b/开发文档/1、需求/修改/images/2026-03-15-22-34-51.png
new file mode 100644
index 00000000..22f6d964
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-34-51.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-37-27.png b/开发文档/1、需求/修改/images/2026-03-15-22-37-27.png
new file mode 100644
index 00000000..dd9456bc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-37-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-37-52.png b/开发文档/1、需求/修改/images/2026-03-15-22-37-52.png
new file mode 100644
index 00000000..ca1e6b12
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-37-52.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-39-38.png b/开发文档/1、需求/修改/images/2026-03-15-22-39-38.png
new file mode 100644
index 00000000..c53869a2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-39-38.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-22-41-02.png b/开发文档/1、需求/修改/images/2026-03-15-22-41-02.png
new file mode 100644
index 00000000..716f7dac
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-22-41-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-23-04-54.png b/开发文档/1、需求/修改/images/2026-03-15-23-04-54.png
new file mode 100644
index 00000000..8d6042e1
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-23-04-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-15-23-05-29.png b/开发文档/1、需求/修改/images/2026-03-15-23-05-29.png
new file mode 100644
index 00000000..d04a672b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-15-23-05-29.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-14-51-34.png b/开发文档/1、需求/修改/images/2026-03-19-14-51-34.png
new file mode 100644
index 00000000..b575744b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-14-51-34.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-14-54-24.png b/开发文档/1、需求/修改/images/2026-03-19-14-54-24.png
new file mode 100644
index 00000000..a4eb4f89
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-14-54-24.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-14-54-56.png b/开发文档/1、需求/修改/images/2026-03-19-14-54-56.png
new file mode 100644
index 00000000..756d2d15
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-14-54-56.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-14-56-16.png b/开发文档/1、需求/修改/images/2026-03-19-14-56-16.png
new file mode 100644
index 00000000..ccb6ebdb
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-14-56-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-14-59-01.png b/开发文档/1、需求/修改/images/2026-03-19-14-59-01.png
new file mode 100644
index 00000000..10b0d993
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-14-59-01.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-15-13-48.png b/开发文档/1、需求/修改/images/2026-03-19-15-13-48.png
new file mode 100644
index 00000000..8b10784e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-15-13-48.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-19-15-14-18.png b/开发文档/1、需求/修改/images/2026-03-19-15-14-18.png
new file mode 100644
index 00000000..befac097
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-19-15-14-18.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-13-56-22.png b/开发文档/1、需求/修改/images/2026-03-21-13-56-22.png
new file mode 100644
index 00000000..0565aa0b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-13-56-22.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-13-57-06.png b/开发文档/1、需求/修改/images/2026-03-21-13-57-06.png
new file mode 100644
index 00000000..1cb8989b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-13-57-06.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-13-57-45.png b/开发文档/1、需求/修改/images/2026-03-21-13-57-45.png
new file mode 100644
index 00000000..719b51d4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-13-57-45.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-16-48.png b/开发文档/1、需求/修改/images/2026-03-21-14-16-48.png
new file mode 100644
index 00000000..77724fea
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-16-48.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-18-05.png b/开发文档/1、需求/修改/images/2026-03-21-14-18-05.png
new file mode 100644
index 00000000..afce5157
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-18-05.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-19-16.png b/开发文档/1、需求/修改/images/2026-03-21-14-19-16.png
new file mode 100644
index 00000000..afc5010d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-19-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-19-58.png b/开发文档/1、需求/修改/images/2026-03-21-14-19-58.png
new file mode 100644
index 00000000..7da92555
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-19-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-20-47.png b/开发文档/1、需求/修改/images/2026-03-21-14-20-47.png
new file mode 100644
index 00000000..7642596e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-20-47.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-21-10.png b/开发文档/1、需求/修改/images/2026-03-21-14-21-10.png
new file mode 100644
index 00000000..f7cf81f6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-21-10.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-29-58.png b/开发文档/1、需求/修改/images/2026-03-21-14-29-58.png
new file mode 100644
index 00000000..34947c49
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-29-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-30-08.png b/开发文档/1、需求/修改/images/2026-03-21-14-30-08.png
new file mode 100644
index 00000000..e530157a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-30-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-31-45.png b/开发文档/1、需求/修改/images/2026-03-21-14-31-45.png
new file mode 100644
index 00000000..5107d802
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-31-45.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-14-59-39.png b/开发文档/1、需求/修改/images/2026-03-21-14-59-39.png
new file mode 100644
index 00000000..3195bcde
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-14-59-39.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-01-31.png b/开发文档/1、需求/修改/images/2026-03-21-15-01-31.png
new file mode 100644
index 00000000..618886e7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-01-31.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-02-16.png b/开发文档/1、需求/修改/images/2026-03-21-15-02-16.png
new file mode 100644
index 00000000..4a53ed51
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-02-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-03-23.png b/开发文档/1、需求/修改/images/2026-03-21-15-03-23.png
new file mode 100644
index 00000000..7a8e7741
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-03-23.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-03-30.png b/开发文档/1、需求/修改/images/2026-03-21-15-03-30.png
new file mode 100644
index 00000000..7a8e7741
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-03-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-04-47.png b/开发文档/1、需求/修改/images/2026-03-21-15-04-47.png
new file mode 100644
index 00000000..aa239d83
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-04-47.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-07-25.png b/开发文档/1、需求/修改/images/2026-03-21-15-07-25.png
new file mode 100644
index 00000000..41b4d328
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-07-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-08-05.png b/开发文档/1、需求/修改/images/2026-03-21-15-08-05.png
new file mode 100644
index 00000000..b46c7069
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-08-05.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-15-09-12.png b/开发文档/1、需求/修改/images/2026-03-21-15-09-12.png
new file mode 100644
index 00000000..0fc770a1
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-15-09-12.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-12-26.png b/开发文档/1、需求/修改/images/2026-03-21-20-12-26.png
new file mode 100644
index 00000000..0930f1ff
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-12-26.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-13-07.png b/开发文档/1、需求/修改/images/2026-03-21-20-13-07.png
new file mode 100644
index 00000000..4575182c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-13-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-14-07.png b/开发文档/1、需求/修改/images/2026-03-21-20-14-07.png
new file mode 100644
index 00000000..60640a69
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-14-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-16-36.png b/开发文档/1、需求/修改/images/2026-03-21-20-16-36.png
new file mode 100644
index 00000000..c2c39fab
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-16-36.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-17-09.png b/开发文档/1、需求/修改/images/2026-03-21-20-17-09.png
new file mode 100644
index 00000000..ec71d188
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-17-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-18-22.png b/开发文档/1、需求/修改/images/2026-03-21-20-18-22.png
new file mode 100644
index 00000000..d489655e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-18-22.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-20-16.png b/开发文档/1、需求/修改/images/2026-03-21-20-20-16.png
new file mode 100644
index 00000000..46e7f33b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-20-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-21-09.png b/开发文档/1、需求/修改/images/2026-03-21-20-21-09.png
new file mode 100644
index 00000000..06d5a8f9
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-21-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-22-04.png b/开发文档/1、需求/修改/images/2026-03-21-20-22-04.png
new file mode 100644
index 00000000..b13e4557
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-22-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-32-38.png b/开发文档/1、需求/修改/images/2026-03-21-20-32-38.png
new file mode 100644
index 00000000..6461ff69
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-32-38.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-32-46.png b/开发文档/1、需求/修改/images/2026-03-21-20-32-46.png
new file mode 100644
index 00000000..065704ac
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-32-46.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-34-39.png b/开发文档/1、需求/修改/images/2026-03-21-20-34-39.png
new file mode 100644
index 00000000..972983bc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-34-39.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-36-42.png b/开发文档/1、需求/修改/images/2026-03-21-20-36-42.png
new file mode 100644
index 00000000..2b182941
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-36-42.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-39-10.png b/开发文档/1、需求/修改/images/2026-03-21-20-39-10.png
new file mode 100644
index 00000000..77c4a0f3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-39-10.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-41-32.png b/开发文档/1、需求/修改/images/2026-03-21-20-41-32.png
new file mode 100644
index 00000000..67acdfde
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-41-32.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-42-03.png b/开发文档/1、需求/修改/images/2026-03-21-20-42-03.png
new file mode 100644
index 00000000..14901ee2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-42-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-43-21.png b/开发文档/1、需求/修改/images/2026-03-21-20-43-21.png
new file mode 100644
index 00000000..f9cc7bd0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-43-21.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-45-12.png b/开发文档/1、需求/修改/images/2026-03-21-20-45-12.png
new file mode 100644
index 00000000..8e821ba5
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-45-12.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-45-52.png b/开发文档/1、需求/修改/images/2026-03-21-20-45-52.png
new file mode 100644
index 00000000..1e55e17c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-45-52.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-46-57.png b/开发文档/1、需求/修改/images/2026-03-21-20-46-57.png
new file mode 100644
index 00000000..fa8efc29
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-46-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-47-22.png b/开发文档/1、需求/修改/images/2026-03-21-20-47-22.png
new file mode 100644
index 00000000..efca6e92
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-47-22.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-20-47-34.png b/开发文档/1、需求/修改/images/2026-03-21-20-47-34.png
new file mode 100644
index 00000000..c1d7c614
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-20-47-34.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-41-29.png b/开发文档/1、需求/修改/images/2026-03-21-22-41-29.png
new file mode 100644
index 00000000..2e30c8a9
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-41-29.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-42-05.png b/开发文档/1、需求/修改/images/2026-03-21-22-42-05.png
new file mode 100644
index 00000000..1caab9b3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-42-05.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-42-46.png b/开发文档/1、需求/修改/images/2026-03-21-22-42-46.png
new file mode 100644
index 00000000..29865179
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-42-46.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-43-45.png b/开发文档/1、需求/修改/images/2026-03-21-22-43-45.png
new file mode 100644
index 00000000..13d21725
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-43-45.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-44-35.png b/开发文档/1、需求/修改/images/2026-03-21-22-44-35.png
new file mode 100644
index 00000000..c4c62a9f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-44-35.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-44-44.png b/开发文档/1、需求/修改/images/2026-03-21-22-44-44.png
new file mode 100644
index 00000000..c4c62a9f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-44-44.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-46-49.png b/开发文档/1、需求/修改/images/2026-03-21-22-46-49.png
new file mode 100644
index 00000000..e3e2c815
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-46-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-22-58-44.png b/开发文档/1、需求/修改/images/2026-03-21-22-58-44.png
new file mode 100644
index 00000000..01c42815
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-22-58-44.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-23-00-16.png b/开发文档/1、需求/修改/images/2026-03-21-23-00-16.png
new file mode 100644
index 00000000..e6e802c4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-23-00-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-23-00-41.png b/开发文档/1、需求/修改/images/2026-03-21-23-00-41.png
new file mode 100644
index 00000000..d5e65e30
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-23-00-41.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-23-01-29.png b/开发文档/1、需求/修改/images/2026-03-21-23-01-29.png
new file mode 100644
index 00000000..b9f8652b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-23-01-29.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-23-02-49.png b/开发文档/1、需求/修改/images/2026-03-21-23-02-49.png
new file mode 100644
index 00000000..f0dc6dfe
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-23-02-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-23-03-09.png b/开发文档/1、需求/修改/images/2026-03-21-23-03-09.png
new file mode 100644
index 00000000..9fe1a87f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-23-03-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-21-23-03-31.png b/开发文档/1、需求/修改/images/2026-03-21-23-03-31.png
new file mode 100644
index 00000000..98bbd664
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-21-23-03-31.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-51-18.png b/开发文档/1、需求/修改/images/2026-03-22-13-51-18.png
new file mode 100644
index 00000000..da26f431
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-51-18.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-51-33.png b/开发文档/1、需求/修改/images/2026-03-22-13-51-33.png
new file mode 100644
index 00000000..6c03f569
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-51-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-52-25.png b/开发文档/1、需求/修改/images/2026-03-22-13-52-25.png
new file mode 100644
index 00000000..0e952940
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-52-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-52-59.png b/开发文档/1、需求/修改/images/2026-03-22-13-52-59.png
new file mode 100644
index 00000000..9d5237b6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-52-59.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-54-25.png b/开发文档/1、需求/修改/images/2026-03-22-13-54-25.png
new file mode 100644
index 00000000..ac00818f
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-54-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-55-56.png b/开发文档/1、需求/修改/images/2026-03-22-13-55-56.png
new file mode 100644
index 00000000..38d1e95e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-55-56.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-22-13-56-49.png b/开发文档/1、需求/修改/images/2026-03-22-13-56-49.png
new file mode 100644
index 00000000..abb5a06d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-22-13-56-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-17-51-54.png b/开发文档/1、需求/修改/images/2026-03-23-17-51-54.png
new file mode 100644
index 00000000..0d3a443b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-17-51-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-17-53-17.png b/开发文档/1、需求/修改/images/2026-03-23-17-53-17.png
new file mode 100644
index 00000000..aafc4fc3
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-17-53-17.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-17-54-27.png b/开发文档/1、需求/修改/images/2026-03-23-17-54-27.png
new file mode 100644
index 00000000..d0836030
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-17-54-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-17-57-25.png b/开发文档/1、需求/修改/images/2026-03-23-17-57-25.png
new file mode 100644
index 00000000..cf0b02b0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-17-57-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-18-06-39.png b/开发文档/1、需求/修改/images/2026-03-23-18-06-39.png
new file mode 100644
index 00000000..d2f8c3a4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-18-06-39.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-18-07-51.png b/开发文档/1、需求/修改/images/2026-03-23-18-07-51.png
new file mode 100644
index 00000000..aa53df67
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-18-07-51.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-18-10-33.png b/开发文档/1、需求/修改/images/2026-03-23-18-10-33.png
new file mode 100644
index 00000000..8022915b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-18-10-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-23-18-13-16.png b/开发文档/1、需求/修改/images/2026-03-23-18-13-16.png
new file mode 100644
index 00000000..0db7ed9e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-23-18-13-16.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-24-00-32-22.png b/开发文档/1、需求/修改/images/2026-03-24-00-32-22.png
new file mode 100644
index 00000000..da31b553
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-24-00-32-22.png differ
diff --git a/开发文档/1、需求/修改/images/2026-03-24-00-33-23.png b/开发文档/1、需求/修改/images/2026-03-24-00-33-23.png
new file mode 100644
index 00000000..acd01cf6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-03-24-00-33-23.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-04-17-32.png b/开发文档/1、需求/修改/images/2026-04-06-04-17-32.png
new file mode 100644
index 00000000..9d9aae11
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-04-17-32.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-05-53-15.png b/开发文档/1、需求/修改/images/2026-04-06-05-53-15.png
new file mode 100644
index 00000000..3646f403
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-05-53-15.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-05-54-12.png b/开发文档/1、需求/修改/images/2026-04-06-05-54-12.png
new file mode 100644
index 00000000..0e953300
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-05-54-12.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-05-55-07.png b/开发文档/1、需求/修改/images/2026-04-06-05-55-07.png
new file mode 100644
index 00000000..d8465633
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-05-55-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-05-55-49.png b/开发文档/1、需求/修改/images/2026-04-06-05-55-49.png
new file mode 100644
index 00000000..a3ce3206
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-05-55-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-06-45-24.png b/开发文档/1、需求/修改/images/2026-04-06-06-45-24.png
new file mode 100644
index 00000000..b4441ba4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-06-45-24.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-06-47-03.png b/开发文档/1、需求/修改/images/2026-04-06-06-47-03.png
new file mode 100644
index 00000000..128b9ac2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-06-47-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-09-33-10.png b/开发文档/1、需求/修改/images/2026-04-06-09-33-10.png
new file mode 100644
index 00000000..50c26858
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-09-33-10.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-10-31-25.png b/开发文档/1、需求/修改/images/2026-04-06-10-31-25.png
new file mode 100644
index 00000000..9e3d54d5
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-10-31-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-10-31-58.png b/开发文档/1、需求/修改/images/2026-04-06-10-31-58.png
new file mode 100644
index 00000000..7e1429f6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-10-31-58.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-10-32-42.png b/开发文档/1、需求/修改/images/2026-04-06-10-32-42.png
new file mode 100644
index 00000000..4ce511bb
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-10-32-42.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-10-34-23.png b/开发文档/1、需求/修改/images/2026-04-06-10-34-23.png
new file mode 100644
index 00000000..1f53cdb8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-10-34-23.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-10-37-33.png b/开发文档/1、需求/修改/images/2026-04-06-10-37-33.png
new file mode 100644
index 00000000..cfc87601
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-10-37-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-10-37-52.png b/开发文档/1、需求/修改/images/2026-04-06-10-37-52.png
new file mode 100644
index 00000000..0ef413f1
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-10-37-52.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-30-53.png b/开发文档/1、需求/修改/images/2026-04-06-11-30-53.png
new file mode 100644
index 00000000..bc6bb67c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-30-53.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-31-10.png b/开发文档/1、需求/修改/images/2026-04-06-11-31-10.png
new file mode 100644
index 00000000..c5c03445
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-31-10.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-31-22.png b/开发文档/1、需求/修改/images/2026-04-06-11-31-22.png
new file mode 100644
index 00000000..a807d727
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-31-22.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-33-41.png b/开发文档/1、需求/修改/images/2026-04-06-11-33-41.png
new file mode 100644
index 00000000..1eb53afb
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-33-41.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-34-09.png b/开发文档/1、需求/修改/images/2026-04-06-11-34-09.png
new file mode 100644
index 00000000..c8ea2b79
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-34-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-36-12.png b/开发文档/1、需求/修改/images/2026-04-06-11-36-12.png
new file mode 100644
index 00000000..331e78f9
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-36-12.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-36-26.png b/开发文档/1、需求/修改/images/2026-04-06-11-36-26.png
new file mode 100644
index 00000000..459f0a17
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-36-26.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-37-08.png b/开发文档/1、需求/修改/images/2026-04-06-11-37-08.png
new file mode 100644
index 00000000..9ac72e8c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-37-08.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-37-39.png b/开发文档/1、需求/修改/images/2026-04-06-11-37-39.png
new file mode 100644
index 00000000..eeab29e8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-37-39.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-38-46.png b/开发文档/1、需求/修改/images/2026-04-06-11-38-46.png
new file mode 100644
index 00000000..2de731ea
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-38-46.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-11-39-26.png b/开发文档/1、需求/修改/images/2026-04-06-11-39-26.png
new file mode 100644
index 00000000..a85bfb2d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-11-39-26.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-12-49.png b/开发文档/1、需求/修改/images/2026-04-06-15-12-49.png
new file mode 100644
index 00000000..2de5633c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-12-49.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-13-14.png b/开发文档/1、需求/修改/images/2026-04-06-15-13-14.png
new file mode 100644
index 00000000..0a27b304
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-13-14.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-14-04.png b/开发文档/1、需求/修改/images/2026-04-06-15-14-04.png
new file mode 100644
index 00000000..eaa8c95c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-14-04.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-14-42.png b/开发文档/1、需求/修改/images/2026-04-06-15-14-42.png
new file mode 100644
index 00000000..d1dacb19
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-14-42.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-16-48.png b/开发文档/1、需求/修改/images/2026-04-06-15-16-48.png
new file mode 100644
index 00000000..5317fc09
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-16-48.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-17-39.png b/开发文档/1、需求/修改/images/2026-04-06-15-17-39.png
new file mode 100644
index 00000000..705c38f6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-17-39.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-06-15-18-46.png b/开发文档/1、需求/修改/images/2026-04-06-15-18-46.png
new file mode 100644
index 00000000..28ff1575
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-06-15-18-46.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-18-42-56.png b/开发文档/1、需求/修改/images/2026-04-07-18-42-56.png
new file mode 100644
index 00000000..af2729c5
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-18-42-56.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-18-43-36.png b/开发文档/1、需求/修改/images/2026-04-07-18-43-36.png
new file mode 100644
index 00000000..a6ad4ed0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-18-43-36.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-23-45.png b/开发文档/1、需求/修改/images/2026-04-07-22-23-45.png
new file mode 100644
index 00000000..feedba1d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-23-45.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-24-27.png b/开发文档/1、需求/修改/images/2026-04-07-22-24-27.png
new file mode 100644
index 00000000..2512a5c9
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-24-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-25-02.png b/开发文档/1、需求/修改/images/2026-04-07-22-25-02.png
new file mode 100644
index 00000000..2efe15c8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-25-02.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-25-30.png b/开发文档/1、需求/修改/images/2026-04-07-22-25-30.png
new file mode 100644
index 00000000..ea1529a4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-25-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-26-12.png b/开发文档/1、需求/修改/images/2026-04-07-22-26-12.png
new file mode 100644
index 00000000..c305f56a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-26-12.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-27-06.png b/开发文档/1、需求/修改/images/2026-04-07-22-27-06.png
new file mode 100644
index 00000000..fc3d2a5a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-27-06.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-28-48.png b/开发文档/1、需求/修改/images/2026-04-07-22-28-48.png
new file mode 100644
index 00000000..38375276
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-28-48.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-29-03.png b/开发文档/1、需求/修改/images/2026-04-07-22-29-03.png
new file mode 100644
index 00000000..8a47e596
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-29-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-29-54.png b/开发文档/1、需求/修改/images/2026-04-07-22-29-54.png
new file mode 100644
index 00000000..01e13b8c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-29-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-30-57.png b/开发文档/1、需求/修改/images/2026-04-07-22-30-57.png
new file mode 100644
index 00000000..c0e31ca4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-30-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-32-13.png b/开发文档/1、需求/修改/images/2026-04-07-22-32-13.png
new file mode 100644
index 00000000..827f9f16
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-32-13.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-32-54.png b/开发文档/1、需求/修改/images/2026-04-07-22-32-54.png
new file mode 100644
index 00000000..cf4f0004
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-32-54.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-33-19.png b/开发文档/1、需求/修改/images/2026-04-07-22-33-19.png
new file mode 100644
index 00000000..437fe906
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-33-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-52-19.png b/开发文档/1、需求/修改/images/2026-04-07-22-52-19.png
new file mode 100644
index 00000000..3daa0a9e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-52-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-53-30.png b/开发文档/1、需求/修改/images/2026-04-07-22-53-30.png
new file mode 100644
index 00000000..d2bb2df6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-53-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-54-27.png b/开发文档/1、需求/修改/images/2026-04-07-22-54-27.png
new file mode 100644
index 00000000..0540564d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-54-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-56-07.png b/开发文档/1、需求/修改/images/2026-04-07-22-56-07.png
new file mode 100644
index 00000000..9d4f1234
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-56-07.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-58-57.png b/开发文档/1、需求/修改/images/2026-04-07-22-58-57.png
new file mode 100644
index 00000000..101d80f7
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-58-57.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-22-59-32.png b/开发文档/1、需求/修改/images/2026-04-07-22-59-32.png
new file mode 100644
index 00000000..c8f1ad6b
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-22-59-32.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-00-47.png b/开发文档/1、需求/修改/images/2026-04-07-23-00-47.png
new file mode 100644
index 00000000..9ef60039
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-00-47.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-01-40.png b/开发文档/1、需求/修改/images/2026-04-07-23-01-40.png
new file mode 100644
index 00000000..45cea47d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-01-40.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-02-33.png b/开发文档/1、需求/修改/images/2026-04-07-23-02-33.png
new file mode 100644
index 00000000..b1bfa421
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-02-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-02-56.png b/开发文档/1、需求/修改/images/2026-04-07-23-02-56.png
new file mode 100644
index 00000000..6035ea9d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-02-56.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-05-33.png b/开发文档/1、需求/修改/images/2026-04-07-23-05-33.png
new file mode 100644
index 00000000..34b65711
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-05-33.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-08-05.png b/开发文档/1、需求/修改/images/2026-04-07-23-08-05.png
new file mode 100644
index 00000000..d251ceb4
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-08-05.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-08-47.png b/开发文档/1、需求/修改/images/2026-04-07-23-08-47.png
new file mode 100644
index 00000000..c49081e2
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-08-47.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-21-06.png b/开发文档/1、需求/修改/images/2026-04-07-23-21-06.png
new file mode 100644
index 00000000..e1a5ca4a
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-21-06.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-24-19.png b/开发文档/1、需求/修改/images/2026-04-07-23-24-19.png
new file mode 100644
index 00000000..0e963ae0
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-24-19.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-25-03.png b/开发文档/1、需求/修改/images/2026-04-07-23-25-03.png
new file mode 100644
index 00000000..afff557e
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-25-03.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-07-23-26-09.png b/开发文档/1、需求/修改/images/2026-04-07-23-26-09.png
new file mode 100644
index 00000000..60a24d0d
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-07-23-26-09.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-08-04-40-30.png b/开发文档/1、需求/修改/images/2026-04-08-04-40-30.png
new file mode 100644
index 00000000..6413d828
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-08-04-40-30.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-08-04-43-15.png b/开发文档/1、需求/修改/images/2026-04-08-04-43-15.png
new file mode 100644
index 00000000..42828ec6
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-08-04-43-15.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-08-04-45-27.png b/开发文档/1、需求/修改/images/2026-04-08-04-45-27.png
new file mode 100644
index 00000000..27da52c8
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-08-04-45-27.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-08-04-46-25.png b/开发文档/1、需求/修改/images/2026-04-08-04-46-25.png
new file mode 100644
index 00000000..4936e806
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-08-04-46-25.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-08-04-47-06.png b/开发文档/1、需求/修改/images/2026-04-08-04-47-06.png
new file mode 100644
index 00000000..0848f58c
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-08-04-47-06.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-11-17-34-28.png b/开发文档/1、需求/修改/images/2026-04-11-17-34-28.png
new file mode 100644
index 00000000..956b98bc
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-11-17-34-28.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-11-17-35-26.png b/开发文档/1、需求/修改/images/2026-04-11-17-35-26.png
new file mode 100644
index 00000000..e93a7bf5
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-11-17-35-26.png differ
diff --git a/开发文档/1、需求/修改/images/2026-04-11-17-36-03.png b/开发文档/1、需求/修改/images/2026-04-11-17-36-03.png
new file mode 100644
index 00000000..b3263f02
Binary files /dev/null and b/开发文档/1、需求/修改/images/2026-04-11-17-36-03.png differ
diff --git a/开发文档/1、需求/修改/images/image.png.png b/开发文档/1、需求/修改/images/image.png.png
new file mode 100644
index 00000000..d1f497a3
Binary files /dev/null and b/开发文档/1、需求/修改/images/image.png.png differ
diff --git a/开发文档/1、需求/修改/全站修改 20260407-1.plan.md b/开发文档/1、需求/修改/全站修改 20260407-1.plan.md
new file mode 100644
index 00000000..9eca91f1
--- /dev/null
+++ b/开发文档/1、需求/修改/全站修改 20260407-1.plan.md	
@@ -0,0 +1,36 @@
+
+---
+
+## 待排期
+
+| 项 | 状态 | 说明 |
+|:---|:---|:---|
+功能一：
+image.png![](images/2026-04-07-22-23-45.png)
+![](images/2026-04-07-22-24-27.
+![](images/2026-04-07-22-25-02.png)png)着伙伴的这个数据。找伙伴的数据概览。找伙伴的这个数据概览跟推广中心的这个。找伙伴那个数据概览。帮我直接的放到那个数据概览的这个标签页里面，合并到数据概览的标签页里。合并到这个数据概览的这个标签页里面，然后把整个的这个标签页的数据更做的更有参考意义一些。好。然后他是独立的一个标签页，跟这个数据开展，这个首页要分开，那整合成一个标签页
+那个着火伴跟那个推广中心的这个数据都统一的放到
+
+![](images/2026-04-07-22-25-30.png)
+两个标签里面。然后这个用户数据的，用户旅程的数据得更有参考意义，现在的这个界面看出看不出任何东西出来，你帮我思考一下这个的一个用户，然后帮我把这个页面重构一下，让我更清晰一点
+
+
+功能二：内容章节折叠
+![](images/2026-04-07-22-26-12.png)这个内容页这边的话，这个第一章，第二章这里也是有一个可以折叠的小三角，可以直接折叠。可以折叠展开
+
+![](images/2026-04-07-22-27-06.png)然后这个用户界面这边获客跟点击这里不要急，不要挤在一起，只能挤在一起，让他就是横横的，不要挤在一起。
+
+功能三：推广中心重构
+![](images/2026-04-07-22-28-48.png)
+![](images/2026-04-07-22-29-03.png)整个推广中心的那些功能获客列表有点拥挤，帮我处理清楚整个推广中心那个获客列表帮有点拥挤，帮我处理清楚，然后那个。那个里面的这一个相关的订单和代付，跟这个订单跟代付。和那个。提现审核放到一个地方，然后分别是获客列表，然后绑定管理、推广排行，然后订单和待付，然后提现审核，然后存克宝这个跟那个重复的去掉，然后推广设置的页面也做的重新设计一下，有点拥挤，设计的简洁一些，以这个为核心，整个推广中心做一个重构。但功能不要丢失。在一个字体太多了，该说明的文字就说明，就不要搞那么多字，这一个页面推广设置的页面也是一个整理。
+
+![](images/2026-04-07-22-29-54.png)然后这个系统设置里面的接口。接口功能测试的做的清晰一些，包括各个的接口传输文件的到传输文件的文档的这个接口也完善一下，让我可以通过那 AI 来，嗯，管理，并且通过 API 来写文章可以调用相应的数据。
+
+功能四：分析表格：
+![](images/2026-04-07-22-30-57.png)然后这边的话相应的标签，每一个章节的那个标签都得做的清晰一些，这个标签统计这边新的每一个章节、每一个点击都做，以及这个标签统计的一些内容能得到什么样的结果？为什么是这样？做一个分析，做个标签统计之外，也可以一个分析的一个表格图形出来，表格图形
+
+功能五：内容排行榜
+![](images/2026-04-07-22-32-13.png)这个内容展示规则这个地方不是放在这里，你看一下这个放到内容管理的什么地方？帮我那个显示一下，放到排名算法的旁边，但是都是一个小标签，点击展开再来做配置。
+
+功能六：![](images/2026-04-07-22-32-54.png)
+![](images/2026-04-07-22-33-19.png)那这个推广排行在前，这个后端得有一个按钮，可以看到前端的那个小程序这边的一个推广排行，并且能在上面能开关，有开有关的，那这个小程序的一个推广排行的话，主要就是显示在首页的这一个，这个最新新增跟这个精选推荐中间。并且这里是可以直接隐隐藏掉的这推广排行的这一个事情，然后推广排行现有的一些数据，帮我整理一下现有的实际的那个推广排行的一些数据，那以实际的数据那个。那个。实际的数据。做一个排行，但是在前端不想不显示收益，只显示推广能力，就是它的排行榜显示的是它点击进去就这个人的一个推广能力分，那这个推广能力分在那个25，那个5,000到2万之间，那这个推广能力值。那这个做一个排名，以他的那个实际现在的一个推广的那个数量，那能力分整个推广的钱的数量以及推广的如果是章节一小节，一块钱的这一个小节算法是这样，以推广多少的收入，多少小节以及多少的会员？no，以及它的活跃点击的这个热度为基准，这三重为基准来成立一个倍数，那这个倍数乘以之后就是只显示前五名嘛？那这个显示的这个排行总的这个参数，这前五名乘起来的话，总的数值是5,000到1万之间，然后直接在这个推广排行上面直接显示，并且做一个标签，在这个地方跟超级个体的标签是一样的。不要写这个推广排行，就写排行榜就可以了，名字就写排行榜。分享排行榜，分享排行榜名字叫这个
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/全站修改 20260407-2.plan.md b/开发文档/1、需求/修改/全站修改 20260407-2.plan.md
new file mode 100644
index 00000000..0c9d5748
--- /dev/null
+++ b/开发文档/1、需求/修改/全站修改 20260407-2.plan.md	
@@ -0,0 +1,38 @@
+所有的功能、所有的项目、所有的文件，认真的思考，并且认真的思考每一个功能，思考完之后再来做执行，每一步都认真的思考，边做边完成边检测，合理性，发现不合理你就要思考一下怎么样去帮我配置合理。
+
+![](images/2026-04-07-22-52-19.png)这一个标签统计的页面不要显示英文，这些内容都是需要有意义的内容和位置。那并且要明确到点击到哪一个标签，谁啊？名字叫什么，或者文章的章节叫什么，以及
+
+
+![](images/2026-04-07-22-53-30.png)然后这个美文章这里的话，那个哲那个小三角还是没有显示，就是这个折叠的章节的，这里的那个小三角没有显示，就这个章节这边那个倒三角这里的话需要在这个第一章，第二章这个地方要增加一个章节，并且每一篇文章。被谁点击的上面是有显示的，每篇文章上面有点击多少次，但是谁点击了，把这个，谁点击的这个谁也记录下来，点击点点一下这个是可以看得到那个谁点击的这个按钮的，能统计的到点击进去就看到哪一个用户可以点击的，以及这个用户点击的次数的排行榜。点击这个按钮上去就可以看得到，那并且这个文章的那个点击的排行榜也放到首页上面，去，首页的那个数据概览上面，嗯，点击的排行榜也放在首页的数据概览的标签里面
+
+![](images/2026-04-07-22-54-27.png)这个内容的排行榜，咱们也放到这个数据概览里面。
+
+
+![](images/2026-04-07-22-56-07.png)那个数据概览这里的话，找伙伴跟推广中心这里的话去掉。曾找伙伴成为推广中心这个数据概览的这个找伙伴里面这个去掉，然后第二个的话显示的文章的排行榜内容管理放到这里，然后第二个显示的话就用那个标签点击统计，那第三个的话超级个体。统计，然后其他的保持一致的顺序
+
+
+功能二：数据概览优化
+![](images/2026-04-07-22-58-57.png)然后用户标签点击同统计这一块，整个的所有的数据统计都需要重构一下，这个的话所有的核心是以用户为核心，是哪一个用户做了什么行为？统计一下这个用户和相关的点击行为，那核心这个用户的排行榜，特别是数据概览上面新增一类就是一排，这一排就是显示那个最有价值的这个用户的一个排行榜，那包括这一些统计的数据是可要记录用户的 RFM 估值里面的，把这个算法估值也叠加进去。通过统计数据，那所有的标签都是除了基础的功能之外，跟界面简洁之外，所有的标签都是以用户单个个体的，用户的实际的用户旅程为核心做一个参考数据，这个整个的这个统计数据要简洁、大方方，简洁，然后一致性，然后围绕着这一个，我们要找出精准的核心。用户为核心来做这个事情，以及用户的行为触发跟用户旅程来做这一个。
+
+![](images/2026-04-07-22-59-32.png)然后找伙伴导航里的里面的这个数据概览就去掉了，就不要再有重复的这个功能了，自己整合掉了，这个去掉、删除掉。
+
+功能三：
+头像
+![](images/2026-04-07-23-00-47.png)
+![](images/2026-04-07-23-01-40.png)然后很重要的一点就是这里的用户信息的头像要跟那个 NBTI 头像，确保不是空的，反复检查确定用 NBTI 的这一个 PNG 的格式，并且不是空的那个格式，帮我把这个格式显示清楚。并且这个性格里面填写的性格跟可性格测试和性格测试完之后的一个反返回，跟 ID 的返回这一个功能得保持是一致的。确定有这个头像的这个功能可以批量，并且可以批量分配给无头像的这个客户。不用试，不用使用篮板和使用女版，这个男女就自动分配、自动改写、自动分配，然后这些头像都需要显示出来，确定这个功能可用。
+
+功能四：用户详情
+![](images/2026-04-07-23-02-33.png)这个用户详情里面的用户详情的排版得弄清晰一些，现在排版有点乱，在不改变原有的需求的时候，把整个排版那个重构一下，但是功能不要变，并且要验证一下功能，把这个排版重新的设计一下。
+
+![](images/2026-04-07-23-02-56.png)算法这边的算法的权重是可以修改的，在咱们后台这个算法配置这边可以直接做修改，然后把按 RF n 排序，去掉这个小标签，右上角的小标签去掉。
+
+功能五：书
+![](images/2026-04-07-23-05-33.png)后，这个整本书的这个规则是可以配置整本单本书的这个显示的百分比的，单本书显示的百分比是可以做那个设置的，这个也帮我思考一下。
+
+
+功能六：小程序分享朋友圈页面
+![](images/2026-04-07-23-08-05.png)程序，咱们点击这个朋友圈里面分享的这个程序的时候。点击朋友圈分享这个程序的时候，点击支付一块钱的自负1元解锁全文的这个按钮的时候，底下就要有跳出弹出一个那个点击右下角，并且点击右下角看看全文。然后并且有一个箭头是可以直接指向这个漂亮的箭头，并且动态的箭头可以指向，请问下方指向拳王小程序的这个地方，那然后点击前往小程序，直接跳转到这个朋友圈的这个页面，直接跳转到那个付费的这个位置，支付的的这个支付的这个地方，这个哪个页面就支付的哪个页面的这个地方。并且这个小按钮是动态的，也是有动态的功能，小箭头
+
+![](images/2026-04-07-23-08-47.png)
+哪有？然后还有一点的话，这个指向分享到朋友圈这边的这个小箭头，是用线下下的，这个小箭头不是向上的，不是像柚子是向下的小箭头，这个别搞错了。
+哪有？然后还有一点的话，这个指向分享到朋友圈这边的这个小箭头，是用线下下的，这个小箭头不是向上的，不是像柚子是向下的小箭头，这个别搞错了。
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/全站修改 20260407-3.plan.md b/开发文档/1、需求/修改/全站修改 20260407-3.plan.md
new file mode 100644
index 00000000..a317f054
--- /dev/null
+++ b/开发文档/1、需求/修改/全站修改 20260407-3.plan.md	
@@ -0,0 +1,18 @@
+所有的功能、所有的项目、所有的文件，认真的思考，并且认真的思考每一个功能，思考完之后再来做执行，每一步都认真的思考，边做边完成边检测，合理性，发现不合理你就要思考一下怎么样去帮我配置合理。
+
+功能：
+![](images/2026-04-07-23-26-09.png)一个，先修复一下这个错误，然后继续往下执行。
+
+
+功能一：推送到存客宝朋友圈
+在一个需要有一个推送他朋友乘客宝推从通过推送到乘客宝内容库所有的新增的章节，或者那个新成功注册的会员都可以推送到乘客宝的内容库的一个功能跟乘客宝那个内容库对接的这么一个门和接口，让乘客把，直接我提供接口给乘客把拉取。或者乘客给提供接口，给我把这个接口也写清楚，那你帮我把这个文章和推送到乘客，把这个功能跟乘客这方面的那些东西做一个重构，简洁一些，让我清晰的知道怎么样去操作
+
+
+功能二：
+![](images/2026-04-07-23-21-06.png)所有的这个功能，就比如看几章和相应的那个规则，得完全的帮我实现。那后台像，比如看三章，就看三章之后就是需要就这个用户看规则配置，看三章这些都是可以配置的，看三章就会，比如在看文章里面看三章就跳出支付这个365的这个按钮，那这里面也是在这里这个规则配置是可以配置的。把相应的程序里面的所有的那个规则都帮我在这里边显示，并且已经开通了规则显示，并且可以配置
+
+功能三：
+![](images/2026-04-07-23-24-19.png)
+/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/static
+MBTI 的头像是指使用这个目录底下的这两个头像。使用这个目录底下的这两个头像，而不是。而不是自己生成的图像，把自己生成图片图像这个功能给我去掉，然后要用这两个这个文件夹底下的这两个的图片，那上传完之后也是要把这两个的图片上传上去的，用的是这一个文件夹的，确保头像是没有问题的，可以显示的相对路径。那把整个这个 NBTI 的这个生成 SVG，这个直接去掉。没有这个功能。
+![](images/2026-04-07-23-25-03.png)
\ No newline at end of file
diff --git a/开发文档/1、需求/修改/内容版块 20260406-1.plan copy.md b/开发文档/1、需求/修改/内容版块 20260406-1.plan copy.md
new file mode 100644
index 00000000..345de99b
--- /dev/null
+++ b/开发文档/1、需求/修改/内容版块 20260406-1.plan copy.md	
@@ -0,0 +1,12 @@
+
+---
+
+## 待排期
+
+| 项 | 状态 | 说明 |
+|:---|:---|:---|
+功能一：
+![](images/2026-04-07-18-42-56.png)
+然后其实还应该还有一个是啥呢？还有一个就是往后再弄的就是案例了，就合作过的案例。对呀，所以这一个上面写的底下这一个目录的名字就要改造一下嘛？改造一下，变成书的一个形式，就前端，后端，其实这个目录跟后端都得改造一下，对吧？对，那这个后前端的创业实验室一样的吗？就出名加上张杰，加上那个折叠展开跟这个是一样的吗？对吧？那点开完之后就是跟这个第一篇、第二篇是一样的吗？嗯，对吧？嗯。然后像卡路的 IP。跟这个每日的这一个都是一样，每日的这一个是按月份来区分的，嗯，是吧？然后它顺序的话跟后台的顺序要保持一致，就这个是书籍方面，就前端跟后端跟数据库都要做一下调整。包括他那个前面那个图标是可以改的吗？对吧？图标可以改的吗？名字也可以改吗？小程序这些都是跟这个后台的那个数据是保持一致的吗？是吧？![](images/2026-04-07-18-43-36.png)AI 应该用它的那个逻辑来做整个的那个编写吗？可以默认就是收放展开的一个形式，对，这个整个这个内容管理，让多本书变成多本书的那个内容管理的升级成多本书的内容管理的那个逻辑来做，然后要考虑所有的环节，包括这个尾声什么这一些都是放到这个缩，放到那个里面前端，后端跟数据库必须保持一致吗？
+
+然后还有那个小程序，这个后，那个目录，这个标签跟底下那些标签的文字是可以在小程序后台直接改的，它的名字是可以直接改吗？包括我的，对，找伙伴，我的首页这些都可以，后台都是可以直接改的，然后那个排序是跟后台的排序是一样，不要做成倒序的
diff --git a/开发文档/1、需求/修改/内容管理20260411.plan.md b/开发文档/1、需求/修改/内容管理20260411.plan.md
new file mode 100644
index 00000000..dd2d81a2
--- /dev/null
+++ b/开发文档/1、需求/修改/内容管理20260411.plan.md
@@ -0,0 +1,35 @@
+
+需要1:
+![](images/2026-04-11-17-34-28.png)
+![](images/2026-04-11-17-36-03.png)
+![](images/2026-04-11-17-35-26.png)那个去除9块9购买全章的这个。内容。开发文档。9块9跟增量的相关的这个内容。去除这一个，然后把这一个那个上滑，看20%，这个去掉。以阅读购买本章，这个一块钱凸显就可以了，就只有一个这一个图标，把这个，那购买的时候的这个按钮帮我确定一下。长大后。这个按钮支付的，这个弄清楚就支付的这一块，然后把9块9的增量跟相关的后台的这一个规则跟文字去掉
+
+相关的内容都去掉。那检查那个。这个就是要使用默认的末日的规则来操作，使用默认的规则来操作。这个就是现在看三小节的跳出365那个。看全章的这个三章之后才跳出，把这个规则加上，并且呈现在阅读第二小节的时候，有付款两次的时候，直接那个跳出来放在才有这个跟着一块钱一样的这个位置。
+
+---
+
+## 落实说明（2026-04-11）
+
+- 阅读页已登录付费墙：去掉「加入365读书会」大标题、「可先上滑…」及「已阅读约 xx%」行；主按钮仅突出「购买本章 ¥1」；「解锁全书（365读书会）」为第二按钮，去掉「省82%」及原 9.9 营销样式。
+- 展示「解锁全书」条件：`purchasedCount >= fullbook_show_threshold`（默认 **3**）**或**（已购 ≥2 且当前篇有上一篇，即非全书第一篇）。后台阈值默认已改为 3。
+- 未登录文案改为「登录后可支付 ¥{price} 购买本章…」，去掉预览百分比话术；`read_preview_ui` 默认键在 `chapter_preview.go` / 管理端模板中已同步为空或新文案。
+- 代码：`miniprogram/pages/read/read.js` + `read.wxml`；`soul-api/internal/handler/db.go`、`chapter_preview.go`；`soul-admin` 内容管理页阈值默认与模板。
+
+---
+
+## 闭环补充（2026-04-11 晚）
+
+- **付费墙三态统一**：未登录 / 已登录未购 / 朋友圈单页均使用 **`.paywall-marketing-box`**（与「购买本章」同款框）展示「解锁完整内容，分享得到 X% 收益」；底部一句营销统一为 **`read_preview_ui.shareTipLine`** 默认「转发给需要的人，一起学习还能赚佣金」；已解锁文末分享区与付费墙共用 `readUi.shareTipLine`，去掉旧版兜底长句。
+- **`beforeLoginHint`**：付费墙不再展示长段试读说明；`mpPagePopups` 兜底与 `db.go` 种子可为空；云端若仍存旧长文案，管理端 **小程序弹窗文案** 中 `beforeLoginHint` 可清空。
+- **365 与单章**：`revealMode=anchor` 时 365 锚点为主视觉，单章为次要样式；`chapter_read` 在未解锁试读时也会触发 modal 规则（配合 `getBrowseDistinctChapterCount` 与 `getReadCount` 取大）。
+- **验收**：管理端 `read_preview_ui` 与 mpConfig `pagePopupItems` 保存后，小程序拉章节即生效；发版前 `go build ./...`（soul-api）与小程序开发者工具预览阅读页三态。
+
+**状态：已按当前代码闭环，可 100% 验收。**
+
+---
+
+## 365 读书会定价（2026-04-11）
+
+- **产品语义**：`product_type` 仍为 `fullbook`（订单/权益字段不变），对客文案为 **「加入读书会（365读书会）」**，**¥365**；不再有 ¥9.9 全书价。
+- **默认价**：`site_settings.baseBookPrice` / `prices.fullbook` 默认 **365**；`getStandardPrice(fullbook)` **优先读 `site_settings.baseBookPrice`**，与小程序展示一致，再回落 `chapter_config.fullbookPrice`、默认 365。
+- **线上库**：若 `site_settings` 里仍为 9.9，请在管理端 **设置 → 站点与作者** 将「365读书会价格」改为 **365** 并保存。
diff --git a/开发文档/1、需求/已完成/20260308内容管理1.md b/开发文档/1、需求/已完成/20260308内容管理1.md
new file mode 100644
index 00000000..54d3f5c9
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308内容管理1.md
@@ -0,0 +1,20 @@
+修改五
+![](images/2026-03-08-17-15-30.png)
+![](images/2026-03-08-17-16-57.png)然后这一个小眼睛跟边际的功能重复了，这两个功能直接合并掉。直接合并掉，然后把这个。直接合并掉。然后在这个编辑章节里面，这个章节 ID 是可以修改的，修改完之后就直接到指定的目录里面去了。然后把这个章节，这个免费章节设为免费就可以了，把免费章节那个提示词给我去掉，然后在这个里面的话，内容这边的话是可以点击指定的位置直接插入图片的，并且这个图片是一个像飞书一样，是一个快的一个格式，我可以直接通过 API 插入图片，那在这个编辑章节里面。
+
+![](images/2026-03-08-17-17-25.png)你那个深度的去帮我把这个整个的那个内容的那个编辑的这个编辑框优化，深度的优化一下，直到符合我的需求，我可以通过 API 直接传入图片、传入格式，传入表格的一个形式。功能开发并且完善，让我可以那个直接通过接口的形式来更改这个整个文章，也可以那个可以上传到指定的那个发图片上传上去，并且可以编辑跟排版。这个功能深度的开放
+
+修改四
+![](images/2026-03-08-17-13-34.png)
+![](images/2026-03-08-17-14-04.png)人内容管理的里面的这个权重。权重是可以修改的，它的一个热度，权重的这个数值是可以修改的。在排行榜这边你是可以修改的，直接就可以修改掉。并且那个字顶置顶的那几条。置顶的那几条也是可以直接修改的，那小程序里面置顶的这个可以强制置顶，有个选项，我可以选择这个精选推荐这边跟首页的这个最新更新，这两个地方是可以直接按我的那个脱离算法，可以直接在后台配置的。在这个内容管理的后台直接可以配置。
+
+修改三
+![](images/2026-03-08-17-11-50.png)内容管理的小程序上面未付费前默认是20%，但是这个百分比是可以调成调整的，有一些这个那个显示的那个规则，显示的这个内容的那个规则也要在那个上方多一个标签，就是这个内容显示的那个规则要在上面显示清楚。处理清楚。那增加一个标签来处理这个问题
+
+修改二
+![](images/2026-03-08-17-10-32.png)然后这个拉移动的，这个小三点移动到哪里？就要位置要替换掉，现在位置还在这边，首页也显示是这个，比如2026每日派对干货，这个已经显示在上方，但是这里的话还是显示在下方位置显示是不正确的，你帮我把这个位置显示处理一下，并且以后这个目录整个的这个结构跟首页的那个小程序上面的那个结构的表保持是一致的。这边调整小程序后台只要一调整小程序相应的做调整。
+
+修改一
+![](images/2026-03-08-17-09-33.png)
+钩子设置直接删除掉，然后设置这个就是一个那个内容排行榜。内容排行榜就按这个内容的一个热度进行排行，按章节来排行，然后分页，每一页10个10小节做一个内容的排行榜，然后把每一章节的那个数据点击量这个做一个详细的一个排行，把购置车子这个去删除掉。
+
diff --git a/开发文档/1、需求/已完成/20260308内容管理2.md b/开发文档/1、需求/已完成/20260308内容管理2.md
new file mode 100644
index 00000000..f2e1a361
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308内容管理2.md
@@ -0,0 +1,26 @@
+
+功能五 #
+image.png![](images/2026-03-09-04-50-16.png)![](images/2026-03-09-04-51-03.png)
+同时可以加另外一个符号，就是减号，减号是直接可以跳转到链接和跳转到小程序，这个后台一样是可以配置的，有点类似于那个飞书的，有点类似于飞书的，公飞书的这个。标签词的这个功能，点击一下就跳转到那个相应的那个网页上面了。它可以编辑成网址，也点击跳转，也可以编辑成那个。也可以编辑成那个小程序，其他的或者其他的唤醒的这个格式，这个我们后台在内容管理的后台也增加这么一个标签。爱的也好，减号也好的，相应的那个功能都可以通过这个 API 接口直接传入进来的。然后这个相应的设置跟那个链接匹配的设置跟链接匹配放到排行榜的那个后面，比如我要艾特人的那个设置跟那个艾特人的链接，就放到排行榜后面的这个位置，然后全力的帮我开发一下，确保我整个功能可用
+
+
+功能四 @
+image.png![](images/2026-03-09-04-48-03.png)
+![](images/2026-03-09-04-49-01.png)
+机编辑章节里边的整个这个的内容不是 Markdown 的格式，这个是帮我找一下世界上最好的一个内容编辑器，帮我去 EUP 上面找一个最好的一个内容编辑器，并且这个内容编辑器可以快的形式直接插入，像飞书一样以快的形式直接插入。让我可以上传图片和格式，帮我尽可能的去优化一下这个整个的这个编辑器。然后这个编辑器里面的话，我可以插入链接，也可以艾特指定的人。加爱的是可以直接艾特指定的，我们这个设置好内容管理多一个人物列表，就人跟人，跟人的 ID 跟他的名字跟相应的字可以互相的列匹配的一个 ID，我点击这个 ID 就可以直接联系这个人。点一下，点一下这个 ID，存个宝，这边就会有人来添加，跟有人来添加这个用户的这么一个功能在文章里面去体现，你可以在标题，也可以在标题里面去体现这么一个 @ 的一个功能，这个符号。如果人名上加上这个符号@，就是实现这个功能。然后这个在编辑器里面可以有，也可以用代码直接实现
+
+
+功能三 文章排序
+![](images/2026-03-09-04-46-02.png)
+那个文章排名的算法是这样，这个。最近更新前30得分应该是30套一分，就是他的解释是这样，就最新更新的第一篇，比如今天的那最近当天的就30，昨天的就29，在前一天是28，一直循序渐进下去，然后阅读量前20也是一样，排名第一的阅读量就是20。第二就19，第三就是18，第47。20 19 18 17这种的方式付款，也是付款最多的，就20，第二就19，第三就18，是根据这个算出来的。
+
+
+功能二  置顶
+字典的这个功能是在那个章节跟搜索里面都是可以，都通用，都通用就是这个内容馆排行榜的字典的功能在章节里面也需要显示字典的这么一个功能。
+![](images/2026-03-09-04-42-08.png)
+
+
+功能一
+![](images/2026-03-09-04-36-17.png)
+![](images/2026-03-09-04-37-35.png)
+![](images/2026-03-09-04-38-20.png)那个章节管理后面跟的是内容排行榜，然后再到内容搜索。这道内容搜索。然后这个内容管理里面的话，包括内容排行榜这边的话，每一个章节它需要有一个。需要有一个可以点击就可以置顶的。对，一个功能在这个编辑章节里面点击出了就可以推送到在小程序首页的这么一个功能。这个在这个编辑章节里面就需要一个小程序的小灾，小程序直推的，在算法之外直推的一个功能。另外一方面的话是这个章节里面的这个。这个小杰里面的这个。热度这篇是可以编辑的。可以在这个编辑里面去修改编辑章节热度的这个值算法的这个。这个字。可以修改
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308内容管理3.md b/开发文档/1、需求/已完成/20260308内容管理3.md
new file mode 100644
index 00000000..907e6add
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308内容管理3.md
@@ -0,0 +1,14 @@
+完成这个所有的这三个需求，然后确保每一个填空的所有的数值都是可以保存的，然后你不着急帮我部署到服务器，先本地帮我做好把所有功能检测清晰可用
+功能三付款记录
+![](images/2026-03-09-05-25-52.png)
+付款季度这边的话，显示用户的名称 ID 太长了，那点击之后是可以直接跳转到这个 ID 里面的，那点击订单也是直接可以跳转到这个相应的订单里面。这个是那个内容管理里面的这个付款记录这个地方。
+
+功能二
+![](images/2026-03-09-05-22-19.png)
+![](images/2026-03-09-05-23-53.png)
+![](images/2026-03-09-05-24-19.png)内蒙古排行榜这边的话，操作的话应该是点击的是编辑文章，而不是付款记录，这应该放到这个内容的这个编辑里面。应该放到内容的编辑里面，章节的这个编辑里面。然后这个确保，并且确保这个章节 ID 修改成功。直接所有的那个参数修改，在数据库里面修改成功，这个一定要帮我确保清楚。所有的参数都可以正常确保成功，然后这个编辑器里面的话，那个增加这个井号跟 ad 的功能，而且要凸显，然后并且这个功能在咱们的这个内容管理的 API 接口要体现，嗯。链接和小程序都是# 并且 ad 跟那个链接和小程序点击是直接跳转过去的，然后它的颜色是突出的，那在文章里面显示的时候颜色是轻微突出。
+
+功能一
+![](images/2026-03-09-05-18-28.png)
+表哥列记标签的这么一个功能放到这个，这一块的功能放到章节管理跟内容管理，还有那个 ad，第四个标签就是 ad 那个。你的撸管。爱的相关人物的这么一个功能就相关。主人公功能就叫做主人公功能，把这个功能帮我列出来，弄到这个。如何弄到这个里面来？就是一个独立的一个功能，并且帮我把里面的这个人物列表编辑器内可以艾特的这个功能也放到编辑器里面，直接可以选择我，我直接可以选择相关已经配置好的那个已经配置好的人物跟配置好的一个链接，然后你现在帮我添加几个的这个链接，就是里面有提到的。比如卡洛，我们数据库里面的用户卡洛南风，对吧？还有远志这些已经提到的，并且那个超级个体如果成为超级个体，这个利表单也直接在这个里面数据帮我填写好已经是超级个体了，然后链接跟标题标签，比如神仙团队这些有提到的链接跟标签，你帮我写出来，帮我填写进去。
+编辑器副文本的那个编辑器里面，你把这两个 @ 跟人物列表的跟那个链接的。链接的这个是加上# 号的，这么加减号或者他已经是有家眷的这个功能就直接那个写上去，嗯。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308内容管理4.md b/开发文档/1、需求/已完成/20260308内容管理4.md
new file mode 100644
index 00000000..3d9bdb94
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308内容管理4.md
@@ -0,0 +1,10 @@
+
+不用直接部署，直接修改，用中文回复我
+
+需求一：
+需要存克宝这篇提供的整链接下全站的需要存克宝这篇提供的相关的那个功能跟技术也写上去，写到那个文档里面，然后把这个相关的这个内容，这几天，这两天。7号、8号、9号修改了内容跟完成的内容都到这个项目管理的进度里面。然后把整个这个项目上传到 Git Hub 上面，gitea 跟 GitHub 上面
+i git Hub 上面把这个打开这个落地推荐表的页面以及存课宝的页面发给我。直接打开，直接在浏览器打开这两个 GitHub 上面上传成功之后这两个页面
+
+功能一 
+![](images/2026-03-09-05-35-24.png)
+![](images/2026-03-09-05-36-51.png)这个主人公，这一个的话改一下，他这个就是链接的一一个功能，链接的一个功能。就是 ad 跟减号链接。链接人和事。链接 AI 跟这个名字应该改一下，链接 AI 跟事情。链接，AI，链接 AI 主人公，改成链接 AI。然后这里的话，主人公这边的话输入之后这个 ID 是可选项的，然后把那些默认 VIP 就默认到这个里面，这个变成一个标签，并且在那个副文本框是可以直接调取的。然后在小程序的前方也可以直接显示。然后这一个的话在主人公这个是属于 AI 列表，不叫主人公列表，这边就叫 AI 列表，然后这里面就写的是相应的等人物 ID，然后以及配置后端需要有一个配置，一个存客宝，哪一个存客宝的那个手机要么就是存克保指定的那个手。它配置跟纯克宝这边的那个计划是绑定的，捆绑的计划帮我把这个绑定的计划帮我艾特完之后，就是像我们首页链接卡洛一样，点击就直接可以那个添加过去，进到这个流量池里面来。然后这个点击的这个链接的这一个内容的流量词的列表有多少个人点击链接，它这里面有一个列表出来和链接出来这个列表底下，然后把这个上面像 VIP 跟那个几个刚刚提到的，上方提到的几个都优化迭代一下，把这个加上去。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴10.md b/开发文档/1、需求/已完成/20260308找伙伴10.md
new file mode 100644
index 00000000..b26ff90c
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴10.md
@@ -0,0 +1,16 @@
+
+
+收复所有的错误，深度的理解，修复所有的错误，确保没有错误的运行
+
+功能二
+image.png![](images/2026-03-08-16-48-36.png)
+伙伴里面的这个匹配记录还加载还是失败，帮我分析并且处理一下这个问题。
+
+功能一
+![](images/2026-03-08-16-47-03.png)
+![](images/2026-03-08-16-47-11.png)
+
+存客宝场景api '/Users/karuo/Downloads/api_v1 (1).md'这个文档的内容也放到这个，放在这个存克宝里面，并且他要完善的实现这所有的那个场景获客的相关的内容，并且保证整个项目是正常运作的，以及获客的效率
+
+这个存克保的这个功能，这标签是放到右上角，不是独立一个 type。然后这个找伙伴的这个里面的这一个，那个 AI 获客数据这里的话已提交线索跟有联系方式，这边是需要可以直接访问，那可以直接点击进入。点击进度，然后这个存克堡里面的相关的那个 TOKEN 和 API 的那个接口健全的东西是需要是可以直接使用的。需要是可以直接使用的，你把这个存克宝的那个。API 的那个格式，你帮我放到这个里面去。
+这个文档的内容也放到这个，放在这个存克宝里面，并且他要完善的实现这所有的那个场景获客的相关的内容，并且保证整个项目是正常运作的，以及获客的效率
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴4.md b/开发文档/1、需求/已完成/20260308找伙伴4.md
new file mode 100644
index 00000000..023e1019
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴4.md
@@ -0,0 +1,13 @@
+
+
+功能三 匹配池
+![](images/2026-03-08-10-31-24.png)
+匹配词里面的这个选择。匹配词里面的那个选，匹配词里面的这个选择，那可以，我可以点击的时候可以查看，比如我选匹配超级个体，我点击进去能看到具体有多少个人，然后完善资料用户有多少个人，然后全部无量词点击进去有多少人，这个是跟这个用户管理是打通的。
+
+功能二 匹配功能
+小伙伴的这个功能里的那个标签，首先第一个标签是那个数据统计，第二个标签的话就是那个找伙伴，第三个标签是资源对接，第四个标签是导师预约，第五个标签是团队招募，然后把匹配词合并到匹配到找伙伴，匹配词跟匹配记录都合并到找伙伴的这个标签内。然后导师预约的那个导师管理那个加入到那个导师预约里面。
+![](images/2026-03-08-10-30-34.png)
+
+功能一 团队协助
+这一个待开发这一块的话，是写成这个文档存刻保的，这个待开发的发在放到这个开发文档的文档里面，咱们的那个项目管理的这个文档里面跟其他项目做对接的，不用写到代码以后，像这种都不要写在代码里面。确定了。
+![](images/2026-03-08-10-28-11.png)
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴5.md b/开发文档/1、需求/已完成/20260308找伙伴5.md
new file mode 100644
index 00000000..8459c65b
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴5.md
@@ -0,0 +1,31 @@
+
+/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/开发文档/10、项目管理/项目落地推进表.md
+
+然后将这些所有的那个开发的进度文档以后，都是要在那个项目文档，让那个都要在这个项目管理里面实时的这个进度推进跟完成程度都要放到这个进度的推进表里面，确定整个的这个。整个的这个项目是正常的在运转正常的那个进度，然后把我们的对话，今天的一个对话和主要的那个修改的一个板块都到列成这个项目管理里面，清楚的知道开发的时候内容。检查所有的功能的完善性跟可行性，然后继续的全力的帮我检查清楚，然后最终那个完善这个着火的这个功能
+
+功能五 前后端
+![](images/2026-03-08-10-59-57.png)然后我刚才在直接在小伙伴这里填写了那个团队招募的这个板块，这个团队招募的这个板块甜甜姐填写了手机，但是这个填写的手机，但是后台并没有显示，是不是那个加入团队，加入项目改成加入团队，但这个里面并没有给我手机，并没有反馈到这里来检查一下这个具体的一些问题。到底什么原因？然后帮我查看清楚具体的一个原因。那每次匹配的过程当中，这些内容都需要的是能直接到后台，能直接看到这个匹配的手机号，以及相应的一些人。请小程序端跟这个后台端得是互通的
+
+
+功能四 
+![](images/2026-03-08-10-56-15.png)
+匹配记录放到前面，放到匹配词的设置的前面。
+![](images/2026-03-08-10-58-04.png)
+然后每一次匹配。每一次匹配的记录。抖音和用户匹配的用户跟记录都要放到这个相应的那个记录里面。都要放到相应的记录里面，并且这个发起人他是可以直接点击，可以点击和匹配到，可以点击直接看到这个链接的这个人的一个链接的一个形式，以及能看到发起人的一个手机号的一个这个联系方式。然后如果是多次的话，多次匹配到同一个，同比较短的时间，多次匹配到同一个人的情况，那你就直接的就把这个多次匹配的同一个人。多次匹配的同一个人合并成一个，并且有一个下拉可以直接看到匹配了多少个人。防止匹配记录列表非常的得多。队友发起的那个匹配到。
+
+
+功能三 匹配拉群，ai自动化添加和数据反馈
+
+然后把这个找伙伴这边那个，我们把指定的用户跟新增的用户做一个自动化的一个模块，比如他刚刚匹配清楚的话，就是那个存客宝这边就来负责帮他拉群，这个先检查一下存客宝的一个功能，负责来拉群，然后拉群完只有把他的那个信息推送上去。那匹配的同时，匹配成功的同时就是纯科宝来加他，如果不是好友就直接加他，然后直接拉取把这个功能实现一下，然后包括那个找伙伴资源对接、导师预约跟团队招募这几个都需要，然后需要一开官司拉群的开关，还是那个匹配的拉群的开关。还是直接加好友发信息的一个开关，然后加好友发信，加好友发止境指定的的消息也是可以直接在这个后台同存克宝这边的接口部来对接，然后如果没有这些接口，直接通知存克宝那边的开发团队来进行操作。
+
+功能二 找伙伴功能修复
+![](images/2026-03-08-10-46-02.png)
+![](images/2026-03-08-10-47-24.png)
+老伙伴的这个功能，点击查看用户进去，不是，点击进去又是 VIP 会员，超级个体，然后这个完善资料点击进去就是完善资料的用户全部流量词，应该百分之改一下到全部选择是全部用户，这几个分别要进去，然后用户的那个资料完善的要有这些，第二个选择要有这一些资料完善的才能在匹配池那个找伙伴里面去那个找到这些钥匙。实现这个功能在小程序上面的相应的这个功能就必须得实现。并且确保这个功能是可用的，帮我检查一下，确保是可用的
+这个功能前，在前端找伙伴匹配的时候，如果匹配过一次，嗯，就不要再匹配第二次了，就不要再出现就匹配过的当天匹配过一次的那就没有第二次了。这个确定清楚，这个功能要清晰一些
+小程序这端的那个创意合伙人改成找伙伴，小程序这端的那个创业合伙改成找伙伴的这个够名字。
+
+功能一 修复 添加
+这里的话点击测试这个手机号，还是没有加到这个计划里面，帮我 查清楚的一个问题，确定清楚这个问题。请确保前端这个功能是可用的，后台测试也是可以添加的，帮我深度的检查清楚这些，处理掉这些问题image.png
+![](images/2026-03-08-10-43-44.png)
+![](images/2026-03-08-10-44-05.png)
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴6.md b/开发文档/1、需求/已完成/20260308找伙伴6.md
new file mode 100644
index 00000000..c1d158d4
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴6.md
@@ -0,0 +1,16 @@
+拿着存克宝这边 API 显示的那个已存在的这个内容已存在，那这个已存在，像这里面的话只是不添加也要把这个表单添加到这个表单里面显示清楚，然后这个，嗯，下一步这里的话。把这些功能都给我完善清楚。
+
+功能三 客户资源
+![](images/2026-03-08-11-19-38.png)
+
+![](images/2026-03-08-11-20-02.png)
+就这个找伙伴的这一个功能，创业合伙这个要改成的就是找伙伴后台是修改什么样就是什么样的。然后这个团队招募这些图标跟那个相应的跟后台配置，后台配置是那个要相呼应是一样的创业合伙，这个叫找伙伴这个功能，然后点击加入到项目里面，填写手机号，得到后台上面去，后台也同时要显示这个标签，捆绑的同时要显示，比如说团队招募底下现在是没有添加任何的数据过来。这个有问题帮我检测一下，比如小程序这端跟这个跟后台不匹配，那其他的选项也是一样
+image.png![](images/2026-03-08-11-22-09.png)匹配记录，每一项里面都需要有匹配记录，然后也看一下这些匹配的那些相应的这些参数，帮我处理一下这个匹配的具体的一些数据。
+
+
+功能二 修复小程序匹配
+image.png![](images/2026-03-08-11-18-04.png)
+这里的话那个资源对接，跟那个导师预约，跟团队招募这三个的那个匹配完之后，现在在小程序匹配完之后，现在并没有入库。的材料并没有入库，帮我处理一下一个问题，让我可以在后台能直接看到这个，那个匹配完之后的这个用户的联系形式，以及他的一个能点击进去能看到用户的一个旅程。那。
+
+功能一
+![](images/2026-03-08-11-17-15.png)电池设置匹配词的那个来源是可以多多选的。可以同时选择两个，然后这个完整资料，完善资料的用户的话，这完善资料的用户点击进去不是全部用户，是真实有完善资料的，比如有名称、有头像，或者有其他的一些完善的一些材料，那基础的有这个应该是有手机号、有昵称、有头像的，然后有写业务需求的。就以跟线下，跟那个下面的那几个条件，符合这几个条件的一些用户的一个筛选，这是一个。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴7.md b/开发文档/1、需求/已完成/20260308找伙伴7.md
new file mode 100644
index 00000000..8ace0dfc
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴7.md
@@ -0,0 +1,12 @@
+
+功能三
+![](images/2026-03-08-11-32-34.png)
+![](images/2026-03-08-11-32-54.png)度的检查一下这个问题，这个点击链接卡路并没有到这个瘦的右上角，早卡路加好友这里的那个已获客，并没有增加这个正常的话以获客，我点击进去输入这里一定会增加，并且去添加的这里并没有增加。帮我分析一下这个问题，直接帮我处理掉
+
+功能二
+我在小程序匹配了好几次，就这里面的所有的总匹配次数，包含资源对接，导致预约团队高木只要有点击的都是会算在总匹配次数里面，并且可以看到具体的那个匹配的那个情况，然后匹配次数跟今日匹配，这些匹配用庸俗都是可以直接点击进去这些页面，帮我补全点。点击进去可以看得到。
+![](images/2026-03-08-11-31-27.png)
+
+功能一
+![](images/2026-03-08-11-30-23.png)
+人善知要用户指的是已经有那个从图片上传或者微信上传头像的，并且昵称不是叫微信用户的昵称的，有改过昵称的行为的，以及绑定信息有手机号的这一些，这个是完善资料的用户。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴8.md b/开发文档/1、需求/已完成/20260308找伙伴8.md
new file mode 100644
index 00000000..50e48b06
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴8.md
@@ -0,0 +1,20 @@
+检查所有的，把这一个尽全力的完善，并且测试这个功能可用，然后帮我完善这个整个的项目。并且测试这个项目的所有的功能可用。那个在本地先测试，不需要，先不要编译到那个服务器上面，直接在本地上进行修改和完善这些功能
+
+功能四
+![](images/2026-03-08-16-18-08.png)同时处理一下早早伙伴匹配记录加载失败的这个问题，然后在这里的话，那个纯客跑的配置放到这里，嗯，右上角的这里，从数据统计这里，把它接口联通测试这边给他移动过去。从接口连通测试跟存保的这个的场景，然后存保这边的获客的数据是可以直接点击进去的，以及可以看这个存保的这个那个接口的这个文档，这些都是可以要能点击进去，可以看得到相应的联系方式的。
+
+
+功能三
+image.png![](images/2026-03-08-16-14-58.png)![](images/2026-03-08-16-15-14.png)
+![](images/2026-03-08-16-15-31.png)那个加入项目有匹配，但是在后台那个团队招募这一个里面，并且并没有任何的数据，请帮我一定要处理一下这个问题，其他的板块也是出现这个情况。
+
+功能二 存客宝
+然后还有一个比较重要的一个功能，就是存克保这边的那个有匹配完之后存克保这里的相应的动作，在这个找伙伴功能的右上角，这里的话有一个存克保，这里的添加的是否添加成功和存车保相应的那个配置，还有存车保的那个接口的联通测试这几个板块都到小伙伴那找伙伴的右上角的那个标签功能里面。然后把存车保这里的各个场景获客以及相应的接口的数据，比如添加成功，是否有回复率等等的这一些参数都放到这个找伙伴的这个功能里面。如果这个功能根据这些文档的存，相应的文档不能是没有功能的话，直接给存稿这边的开发团队那个提需求，那尽可能的去搜索，并且帮我整理出这个需求出来，然后帮我继续往下去去执行。同时的数据统计的首页的数据对，在清晰一些，整个界面帮我清晰那个大气一点，那不要太太拥挤，分类清楚一点。分类跟那个东西补全一下
+/Users/karuo/Documents/开发/2、私域银行/cunkebao_v3
+![](images/2026-03-08-16-02-09.png)
+
+功能一  匹配机制
+![](images/2026-03-08-15-58-20.png)
+![](images/2026-03-08-15-59-01.png)
+![](images/2026-03-08-15-59-53.png)
+这个匹配记录里面的话，第一个的话是创业合伙的这一个板块是跟后台要相互呼应，这个是找伙伴，并且每一次匹配都需要到图片2的那个后台里面，真相应的那个板块后台。这里得有正常的显示，发起人跟匹配到这个得正常的显示上面的每一个板块都得是正常的显示出来，你先要阅读完图片这几个所有的板块，那也有匹配，就要记录次数以及匹配相应的那个功能，就要记录到这个里面，然后把这个。然后在这个。今日匹配。的那个数据，这一些匹配的都是一些和这个相关的一些数据，已经匹配的类型也是相关的那个数据。更重要的是就是有点击这个用户的那个数据匹配数据，就立即要在这个后台这边显示清楚了，不然现在一直都是空的，帮我看一下具体是什么情况。那一定要帮我处理掉这个问题
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308找伙伴9.md b/开发文档/1、需求/已完成/20260308找伙伴9.md
new file mode 100644
index 00000000..2f7a3fae
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴9.md
@@ -0,0 +1,25 @@
+
+
+收复所有的错误，深度的理解，修复所有的错误，确保没有错误的运行
+
+
+
+功能六
+![](images/2026-03-08-16-36-11.png)那个首页的找伙伴里面的创业合伙人这个功能显示的是找伙伴的这个功能，并且这些在这个标签的名字在后台都是可以设置的，设置他们名称这个是叫找伙伴的功能，图标跟名字都可以在后台配置。把这个名字帮我改一下，并且这个选项跟后台的找伙伴的功能的选项是一定要是相呼应的，点击就要确定好，你深度的帮我理解和检查清楚这个，帮我解决这些所有的问题
+
+功能五
+![](images/2026-03-08-16-34-58.png)的这几个选项都要可以添加的乘客宝的一个获客数据，就是不要写乘客宝，就是一个那个 AI 获客数据，那第一个的话是那个 AI 那个7KB 去掉就是已提交线索，就是三个，第二个有联系方式的就是三个。第一个的话是 AI 添加的程度，那点击进去的话就是看到 AI 添加的一个成功率以及回复率的这一些功能。然后把这个联系方式比例去掉，API 连接的这一个说明文档得可以点开，并且可以编辑这个 API 连接的这个文档。
+
+功能四
+![](images/2026-03-08-16-33-49.png)把这个匹配收收益，匹配收益这个也帮我把这个同时也在首页的数据概览上里面显示。
+
+功能三 
+这个后台各个的匹配记录帮我测试清楚，并且看一下后台真正的匹配的这些匹配记录，刚刚有匹配的记录之后，帮我加到这个匹配记录团队，招募也好，导师预约也好，资源对接也好，匹配记录务必不要显示的人人零条，务必要有相应的那个数据显示出来。也帮我测试一下那个，帮我加几个电话号码进去。
+
+功能二 存客宝
+image.png![](images/2026-03-08-16-32-02.png)所有的那个相应的接口跟功能跟场景获客的一个成功率的所有的东西不单单是测试，然后它也是一个独立的页面，不用，不是展开页。宝的描述跟需求，帮我把这个页面完善一下。阅读关于淳刻薄的所有描述跟需求，我们对话当中
+
+
+功能一
+![](images/2026-03-08-16-30-11.png)
+![](images/2026-03-08-16-31-01.png)小伙伴的这个页面的话，匹配记录加载失败，加载有问题，帮我处理一下这个加载失败的这一个问题。那个皮，那个匹配词设置的话，那个匹配词的选择，这个完善资料的用户点击进去只有3个人的，实际只有3个人，但点击进去有很多他是全部用户的一个列表，这个帮我解读一下。
diff --git a/开发文档/1、需求/已完成/20260308找伙伴功能.pdf b/开发文档/1、需求/已完成/20260308找伙伴功能.pdf
new file mode 100644
index 00000000..30c1bd22
Binary files /dev/null and b/开发文档/1、需求/已完成/20260308找伙伴功能.pdf differ
diff --git a/开发文档/1、需求/已完成/20260308找伙伴功能2.md b/开发文档/1、需求/已完成/20260308找伙伴功能2.md
new file mode 100644
index 00000000..1f7159c0
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴功能2.md
@@ -0,0 +1,36 @@
+# 需求文档标题
+
+> 创建日期：YYYY-MM-DD
+> 文档格式：Markdown（支持图片粘贴 + 预览）
+
+---
+
+## 一、背景与目标
+
+（在此输入文字，可直接粘贴图片）
+
+---
+
+## 二、功能点
+
+### 2.1 功能一
+
+
+
+示例图片引用：`![描述](./images/截图1.png)`
+
+### 2.2 功能二
+
+---
+
+## 三、补充说明
+
+（可继续粘贴图片和文字）
+
+---
+
+## 使用提示
+
+- **粘贴图片**：在 Cursor 中安装「Paste Image」扩展后，直接 Ctrl+V / Cmd+V 即可将剪贴板图片保存到 `images/` 并自动插入引用
+- **预览**：`Cmd+Shift+V` 或右侧「Open Preview」查看排版效果
+
diff --git a/开发文档/1、需求/已完成/20260308找伙伴功能3.md b/开发文档/1、需求/已完成/20260308找伙伴功能3.md
new file mode 100644
index 00000000..7dc91ae2
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308找伙伴功能3.md
@@ -0,0 +1,16 @@
+
+
+那个完成，并且帮我完整的完善这些功能，并且帮我那个整理清楚确保所有的功能是通的、可用的
+
+功能三 找伙伴-存客宝
+![](images/2026-03-08-10-21-19.png)
+然后这边存客宝的统计的话，就是这个匹配次数和匹配的用户和匹配的那个收益都写清楚，然后存客宝这边接口的一个一个的一些相应的这个功能测试完之后，比如这个接口这边的那个测试完之后，点击链接到卡洛，我点测试就可以添加一个测试的一个那个手机号。就我这个后台的这个用户的测试手机号，直接添加到这个指定的这个计划里面去所有的这个乘客宝接口联通测试这里有话都是需要去做这个方面的一个事情，并且我可以直接点击，然后那个包括那个匹配上报的这些功能。乘客那个找我们。那个，这个是属于那个数据统计匹配的数据统计，然后把纯科宝统计放到匹那个匹配词的那个前面，匹配词的标签前面，它是。然后把名字改成就是那个找伙伴统计，找伙伴的那个数据统计，然后把这个数据跟这几个标签做一个那个深度的一个融合，把这个数据统计的更清晰一些。然后这一些，把所有的这一些数据弄清楚，然后现有的能填充的数据已经有了，这个数据帮我完善清楚。
+
+功能二 点击获客
+这个匹配词是可以让我随机让我找到那个匹配的这个里面的这个功能的，就筛选这个用户跟这个用户管理是打通的，有一个标签的一个选择找伙伴的这个功能。然后。然后不管是资源对接，还是导师预约，还是团队招募，这里面有人点击了和填写手机号了，这一个都是直接显示在这个页面下面的，并且直接触发纯课宝的添加，并且有纯课宝这边添加的一个成功率，这个纯课宝留存个宝这边的那个接口了，来负责那个整个的一个功能的一些完善。就把这一个，然后现有的那些数据，现有的这些数据有相关的，就直接把这个相关的数据帮我那个分析，并且导入到这个内容里面来。老路上这个内容里面的，然后把这个。把这个。的匹配到，然后联系方式，然后这里面的那个字段，除了发起人匹配到跟联系方式这一些这几个选项里面的一些功能和内容，还是需要那个有实际的添加，纯推广那边要有反馈的那个数据添加到哪一个接口里面，由这个场景获客的那个接口，有场景获客的那个接口都需要那个完善。都需要回馈一下数据，然后这个如果当前现在改不了，要把这个需求需要协作的存好，协作的需求做一个登记和记录，到时候要发给存客宝去做修改。以后我像这类型的需要纯客房跟那个神射手协助的需求都需要这么去操作
+![](images/2026-03-08-10-17-14.png)![](images/2026-03-08-10-18-28.png)
+
+
+功能一 匹配池
+找伙伴的这个功能底下的话，要那个匹配的那个用户词要选择，可以选择那个超级个体付费1980的会员，然后也可以选择第二个选择的，这是一个流量词，第二个选择的流量词就是我们的那个在这边这里的话要写匹配那个词，里面要可以选择这一块。然后也可以选择那个完善程度的，比如已经完善了手机，那个手机密码，那不，手机，然后那个昵称和图标的用户，并且有写那个一人工写他的具体的一些业务的需求，完善的会员的材料的用户才可以去匹配掉，匹配到。他都吃完了，他都吃完了
+![](images/2026-03-08-10-08-47.png)
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260308用户管理.md b/开发文档/1、需求/已完成/20260308用户管理.md
new file mode 100644
index 00000000..1f7159c0
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308用户管理.md
@@ -0,0 +1,36 @@
+# 需求文档标题
+
+> 创建日期：YYYY-MM-DD
+> 文档格式：Markdown（支持图片粘贴 + 预览）
+
+---
+
+## 一、背景与目标
+
+（在此输入文字，可直接粘贴图片）
+
+---
+
+## 二、功能点
+
+### 2.1 功能一
+
+
+
+示例图片引用：`![描述](./images/截图1.png)`
+
+### 2.2 功能二
+
+---
+
+## 三、补充说明
+
+（可继续粘贴图片和文字）
+
+---
+
+## 使用提示
+
+- **粘贴图片**：在 Cursor 中安装「Paste Image」扩展后，直接 Ctrl+V / Cmd+V 即可将剪贴板图片保存到 `images/` 并自动插入引用
+- **预览**：`Cmd+Shift+V` 或右侧「Open Preview」查看排版效果
+
diff --git a/开发文档/1、需求/已完成/20260308用户管理2.md b/开发文档/1、需求/已完成/20260308用户管理2.md
new file mode 100644
index 00000000..0c619d29
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308用户管理2.md
@@ -0,0 +1,39 @@
+# 需求文档标题
+
+> 创建日期：YYYY-MM-DD
+> 文档格式：Markdown（支持图片粘贴 + 预览）
+
+---
+
+## 一、背景与目标
+
+（在此输入文字，可直接粘贴图片）
+
+
+
+---
+
+## 二、功能点
+
+### 2.1 功能一
+
+（文字 + 可粘贴的截图、原型图）
+
+示例图片引用：`![描述](./images/截图1.png)`
+
+### 2.2 功能二
+
+
+
+---
+
+## 三、补充说明
+
+（可继续粘贴图片和文字）
+
+---
+
+## 使用提示
+
+- **粘贴图片**：在 Cursor 中安装「Paste Image」扩展后，直接 Ctrl+V / Cmd+V 即可将剪贴板图片保存到 `images/` 并自动插入引用
+- **预览**：`Cmd+Shift+V` 或右侧「Open Preview」查看排版效果
diff --git a/开发文档/1、需求/已完成/20260308用户管理3.md b/开发文档/1、需求/已完成/20260308用户管理3.md
new file mode 100644
index 00000000..0c619d29
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260308用户管理3.md
@@ -0,0 +1,39 @@
+# 需求文档标题
+
+> 创建日期：YYYY-MM-DD
+> 文档格式：Markdown（支持图片粘贴 + 预览）
+
+---
+
+## 一、背景与目标
+
+（在此输入文字，可直接粘贴图片）
+
+
+
+---
+
+## 二、功能点
+
+### 2.1 功能一
+
+（文字 + 可粘贴的截图、原型图）
+
+示例图片引用：`![描述](./images/截图1.png)`
+
+### 2.2 功能二
+
+
+
+---
+
+## 三、补充说明
+
+（可继续粘贴图片和文字）
+
+---
+
+## 使用提示
+
+- **粘贴图片**：在 Cursor 中安装「Paste Image」扩展后，直接 Ctrl+V / Cmd+V 即可将剪贴板图片保存到 `images/` 并自动插入引用
+- **预览**：`Cmd+Shift+V` 或右侧「Open Preview」查看排版效果
diff --git a/开发文档/1、需求/已完成/20260314内容管理10.md b/开发文档/1、需求/已完成/20260314内容管理10.md
new file mode 100644
index 00000000..609bc1cc
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理10.md
@@ -0,0 +1,29 @@
+
+
+
+功能五：
+![](images/2026-03-15-13-48-10.png)这个 API 文档就整合到系统设置里面了，那系统设置放到正下方，退出登录的这个位置。跟退出登录这里保持一致，API 文档整合到系统设置里面。
+
+功能四：默认所有文章阅读比例
+帮我检查一下。没有这回事，除非自己设置
+完善一下这个编辑器的这个图片上传的功能，就是我的标点在哪？那个光标在哪，图片就上传到哪，并且得有一个进度以及这个链接编辑的功能，链接上传以及编辑的功能，这个得完善一下。默认预览比例是20%，这个只有唯一的默认的预览比例，唯一的一个条件没有，如果这文章属性没有改，就千万不要改，这个是只有唯一的一个条件。那个是前500个字，不是不要那个50%是怎么回事？确保所有的功能都是生效的，并且有微信。
+[](images/2026-03-15-13-45-21.png)
+
+
+功能四：内容api接口
+![](images/2026-03-15-13-41-54.png)这个内容 API 接口，API 文档是跟内容管理的 API 接口，这两个做一个整合，是用来那个使用这个内容的。那我以后传 MD 文档更新一下这个文章的时候，文章发送的那个不直接发送到数据库，而是通过接口发送到咱们的那个编辑器里面来。
+
+功能三：编辑器
+![](images/2026-03-15-13-42-55.png)
+那个上传的那个编辑器里面的得有一个进度条。上传视频和图片，如果上传比较慢，这个进度条也显示出来。
+![](images/2026-03-15-13-46-08.png)那个有文章有修改，要及时检测，如果检测到 ad 跟减号的时候，包括接口进来的时候都是一样有传数据，通过接口传数据检测到有 @跟 #号，就要直接跟咱们后台的这个那个功能和的这个参数相匹配，嗯。这个是内容方面的一个
+对，一个问题。
+
+功能二：热度分
+![](images/2026-03-15-13-38-39.png)
+![](images/2026-03-15-13-39-09.png)
+
+热度粉里面的那个热度那个不匹配。不匹配，那都分它，这个不在这个里面不匹配，那帮我修正一下这个热度分，以及这里面的那个编辑，这边插入链接旁边应该多一个 add 爱的指定人的一个列表，嗯，这个也没有，嗯，也帮我把这个完成一下。你帮我完成一下这个 @的放在这边，@的指定的人放到这个界面的下面。
+
+功能一：
+![](images/2026-03-15-13-35-04.png)热度的分数是按这三个维度阅读群众的底下这个算法叠加的，那这个阅读权重这里展示的应该是百分之几，10%、40%、50%，这个权重不是零点几，那这里面的分数这边热度是等于这几个值排序的值。那叠加出来的一个热度，这个排序特别注意一下。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260314内容管理11.md b/开发文档/1、需求/已完成/20260314内容管理11.md
new file mode 100644
index 00000000..53a9747b
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理11.md
@@ -0,0 +1,6 @@
+
+
+功能一：文章排名规则
+
+这个文章排名算法权重是有问题的。文章排名算法的权重是有问题的。这排名的算法应该是这一个。排名的算法。文章的这个排名算法是有问题的，文章的排名算法那个在上面的话就是直接就是第那个。首先是按排名来计算，就是现在有三个维度，一个是阅读权重，一个是那个新建的权重，一个是付款的权重，分别那个阅读的排名就是。三十分。阅读的排名都取排名的前30，比如阅读是30，那个全面的话是20篇，不是30篇。20篇，那阅读的话，20篇第一名就是20分，第二名19，第三名18，第四名17，第五名。石榴按照这种形式来进行，那个它排名之后的一个排分，第二个的话那个新新发表的排排分，那新发表的排分也是一样，最近新发表的是20分，然后第二发表的是19，第三37，第64，那个14，那16，第66。然后15 14这样，那付款的也是同理，从20 19 18开始。然后这里面的这个分数，这三个维度的分数排分。这是，然后默认排名的话是按这几个，然后这里面的话有一个是当他的这三个，每一篇文章有这三个维度加起来的总分数。加起来的总分数。就每一个排名的一个分数乘以相应的权重，相加起来的作为一个总分数，比如阅读和心度的权重跟付款的权重，它乘以那个权重的比例。然后就是他们文章加起来的总分数来进行排序，嗯。
+![](images/2026-03-15-14-00-57.png)并且检查好文章内的热度，分男的都分的一个，留存文章内的一个热度分。在数据库里面都可以添加这个热度分。得清晰，
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260314内容管理12.md b/开发文档/1、需求/已完成/20260314内容管理12.md
new file mode 100644
index 00000000..212f8899
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理12.md
@@ -0,0 +1,16 @@
+
+
+bug修复：
+image.png![](images/2026-03-15-19-53-08.png)这一句话不要显示在这边，在文章里面的。
+![](images/2026-03-15-19-53-58.png)头图像还是裂开的，帮我检查一下这个问题修复。并且这个后台的数据好像没有同步过来，嗯，小程序上没显示，帮我分析一下。
+
+
+![](images/2026-03-15-20-00-02.png)那个点击允许跳转到自己的这个指定那个小程序页面的时候，那个如果他就直接关闭的，帮我看一下问题是什么？什么问题直接帮我处理一下，有自动关闭的
+
+![](images/2026-03-15-20-01-17.png)的前端 点击小程序这个@，没有功能，没有实现功能，帮我看一下这个 ad 的功能没有实现。帮我处理一下。
+
+![](images/2026-03-15-20-01-58.png)
+这个头像获取微信头像之后，这个链接还是有问题，帮我检查并处理OSs 链接的一些情况以及 OSs 相关的功能，你帮我检查一下
+
+
+![](images/2026-03-15-20-04-09.png)这个点击小程序右上角的链接卡落，对，需要触发那个需要有字填写完善自己的微信号跟头像，微信号，手机号跟头像微信号跟手机号的其中一个和头像。点击完之后需要有这个。这个才能添加他吗？这种点击链接的都要完善自己的资料。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260314内容管理13.md b/开发文档/1、需求/已完成/20260314内容管理13.md
new file mode 100644
index 00000000..dfbca308
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理13.md
@@ -0,0 +1,21 @@
+
+
+
+
+功能四：派对ai
+这个咱们把这个派对 AI 以后都是用派对 AI 来开发这个一场秀的创意实验，然后让派对 AI 来发布那个复盘的一个那个内容，并且样式要符合飞书的样式，那这个派对 AI 的那个开发一场商业实验的时候，都用派对 AI 来做那个核心的一些工作。并且做实时的汇报，把复盘的东西发到这个创那个指定的这个群里面，所有的创业派对的这个项目，AI 的这个群里面，并且捆绑清楚。后要告诉派对，还当前发布小小程序，咱们对话过程当中发布小程序都是那个1.2.6的这一个版本，当前都是1.2.6的这个版本，并且是预览版，然后要申请到那个审核上面1.2.6的这个版本
+
+
+功能三：样式
+![](images/2026-03-15-22-27-57.png)
+![](images/2026-03-15-22-28-36.png)然后这个界面的上一篇，下一篇的这个宽度已经超出界面了，所有的那个按钮宽度不要超出这个界面。这个央视帮我修整一下。特别是那右下角这个地球的话，它是能直接实现点击分享到朋友圈的功能，并且复制文案就直接实现，那如果你不能实现，你就告诉我，不要让我再点击两次。
+
+功能二：支付问题修复
+![](images/2026-03-15-22-23-49.png)
+![](images/2026-03-15-22-24-45.png)
+分享里面的微信支付跟余额支付这个充值都有问题，都是显示充值失败，帮我检查一下到底是什么问题，直接帮我处理掉。这个充值接口检测清楚，然后把这个我的余额里面这个退款的按钮去掉，推广的按钮去掉。删除掉这个，不要有这个功能。
+
+功能一：分享
+![](images/2026-03-15-22-22-57.png)
+好友跟这个生成海报，这边的话和这个大夫分享这里的那个样式是一样的，图片在上面，然后下面是四个，下面是文字。然后第二个的话，右下角这个地球式的浮动的标签是分享到朋友圈的。那分享到朋友圈这里的话，自动就是生成文字，就可以直接粘贴，它要生成文字是生成那个营销的文字，关于这一篇文章的营销文字，每一篇文章都是一样，直接在可以粘贴到朋友圈里面。
+
diff --git a/开发文档/1、需求/已完成/20260314内容管理5.md b/开发文档/1、需求/已完成/20260314内容管理5.md
new file mode 100644
index 00000000..cc03f934
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理5.md
@@ -0,0 +1,22 @@
+
+功能三：
+然后完成的时候，那个我们现在完成之后用复盘的那个格式。复盘的格式有完成之后用复盘的格式放到。用复盘的格式发到这里，开这个卡洛创业派对开发资料的这个，然后这个。那这个发到这个上面来，每次生成复盘的格式都发到这个上面来。并且这个开发在那个创业派对开发的过程当中，都是和这个飞书的群复盘的，都是和飞书的群绑定的
+![](images/2026-03-15-09-03-58.png)的格式，参考这个格式，复盘的格式参考一下这个格式。
+https://open.feishu.cn/open-apis/bot/v2/hook/c558df98-e13a-419f-a3c0-7e428d15f494
+
+复盘：
+
+功能二：分享功能优化
+![](images/2026-03-15-09-01-19.png)
+然后这个点击分享到朋友圈这边的话是获得收，获得90%收益是要放到下方的，这个分享这里应该改成分享给好友，分享到朋友圈，替换成分享给好友。然后这里的话如果有看书拉到20%的位置的时候，有向下拉的行为的时候，这个就会跳出分享的90%收益。的一个小的一个提示。
+
+
+bug修复一：
+![](images/2026-03-15-08-58-59.png)
+![](images/2026-03-15-08-59-21.png)
+![](images/2026-03-15-08-59-41.png)
+这个内容管理里面的那个星星点点，跟下划线，去掉星星点点这类型的上传上去，下滑线去掉，然后看检查一下这个我们这个内容文档的那个格式，检查一下内容文档的这个格式，然后把这个直接去掉。把这些这个内容直接去掉，然后第二个的话只点击这里的话，像点击 add 咱们后台的这个 add 功能，点击 add 是无法添加，没有反应这个以及这个 add 自动解析的这一个问题要帮我处理一下点击 add 的这一个有爱的源自这一块。然后点击派对会员这边。点击派对会员。会早会提醒是无法找到那个小程序配置，帮我把这个也帮我看一下，优化一下，这是这方面内容的这方面的这一个功能。那个你要解析清楚，看一下我这个后台，这个编辑器的这个格式，我这样上传文本文档上去，那个格式跟图标跟那些东西得清晰进行转化，然后那个已经完成了这个 API 的相应的那个接口，直接用 API 的接口来进行那个上传。然后把这个 API 的东西更新一下，到我们那个上传文章的这个上面去。
+
+
+功能一：代付款让好友看免费
+就这个抖音副业的这一块还可以做一个事情，是什么？就抖音这副业的这一块还可以做一个事情，你现在你要给别人看嘛？别人看你觉得有趣，给别人看别人付钱，那你帮别人付钱，帮他代付解锁，让他能看你来付一块钱，帮他代付100，那他就可以打开看，他就不用付这一块钱了。然后那他是不是就会看了就有感觉的吗？就像流光一样，来，我给你付一块，你去发，然后帮他代付一块就可以了。那他是就会更用心的。看完之后别人觉得，哎，这个东西能做，还可以付个100吗？然后就发给100个人看，对，他也可以，这个就是付款余额，嗯。能不能提现？不能提。可以提现的，它可以充值，可以提现，充值就不能提了，比如说我充重庆小面，我充100，我还能提现吗？不能提了可以退款吗？不能提，9折。把葱的话就抽100还是9折抽，还是买就100吗？对，你这样充值就足够多了。对呀。是不是？
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260314内容管理6.md b/开发文档/1、需求/已完成/20260314内容管理6.md
new file mode 100644
index 00000000..f73d56f8
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理6.md
@@ -0,0 +1,34 @@
+
+
+功能七 api接口
+![](images/2026-03-15-10-04-37.png)
+最新更改的这个 API 接口相关的这个内容跟文章相关编辑的内容，API 接口主要是方便我在直接按这个的格式和需求的格式写相应的那个接口，传文章到这个内容管理里面，然后你把整个的这个内容管理的 API 结果帮我完善并且清晰一些，那界面做一些调整。那我可以直接上传文章时候，通过 API 接口文章图片各种的那个处理。no，no，no，完善这个 API 接口，然后以及我以后这个传授的这个文章的时候，都使用 API 接口来进行传输，那把这个相应的规则帮我整理清晰，并且可以用 AI 来操作
+
+
+功能六 内容搜索
+![](images/2026-03-15-10-02-49.png)然后这个内容搜索这里的话，优先搜索标题，然后再搜索内容。展示的那个顺序标题有包含的，就搜索前三个匹配的标题有包含的就前三个，那后边有包含那一个就是一个两。如果有3个标题跟这个关键字有出现的，就出优先出现最多3个，那后面再开始正常的一个搜索内容包含的这一个板块，这个内容搜索的这一块。
+
+功能五：#
+![](images/2026-03-15-10-00-09.png)
+![](images/2026-03-15-10-00-33.png)
+然后这个链接标签跟这个关联小程序这里的话得做那个清晰的一个标签，就是链接到小程序，我小程序可以直接获得这个页面链接标签这里的小程序的这个。这个页面我可以直接获取这个小程序的这里的一个页面路径，最简单的一个方式，那我可以直接获得小程序的那个页面路径，在这里能直接配置，不然现在配置的话是相当麻烦的，就我只要输入这个微信的那个页面，就可能自己解析或者获得整个小程序的那个相关的这个页面的。这么一个功能，完善一下这个功能，那然后把关联小程序的这个功能给我整合到。关联小程序的这个功能帮我整合到这个标链接标签的这个里面，你以一个最简洁的一个形式，看看这两个功能如何融合，简洁一些，帮我完成这个融合的这一部分，能让我在文章可以方便的那个直接使用那小程序这边的那个名称也是一样。可以让多个名称指向一个标签的 ID，
+我把这个标签里面的链接，小链接，标签链关联小程序跟链接标签这两个直接整合在一起了，就不要出现两个标签了，融合进去
+
+功能四：@好友功能的修复
+![](images/2026-03-15-09-56-46.png)
+![](images/2026-03-15-09-57-27.png)
+![](images/2026-03-15-09-57-54.png)
+![](images/2026-03-15-09-58-57.png)这个文章里面这个 ad 好友还是无法使用，帮我检查一下具体的一个问题，到底什么原因导致它无法使用？帮我处理一下，然后那个链接能和就后台的这个内容管理，这边链接能和事这里的话新建完之后。就这个 ad 的人有边编辑里面需要有一个那个。需要有一个。需要有一个功能，这个功能就是直接可以。直接可以编辑多个的，是可以有一个，那个在昵称下面是可以有个马甲的功能，是可以我相类似的人名都统一到这个人的人名页的下面。都能直接那个统一到这个人的底下，然后这个和存克瓦的功能要那个直接是打通的，然后并且能获得存克宝那边的相应的人功能。这个场景获客的那个计划可以获得他计划和那个直接绑定。然后在好友备注这里的话，这个备注的这里。备注了这个格式需要有一个参数是可以来源，他看哪一篇文章来的？是需要清洗或者做了哪一个动作来的？这里需要完善一下。
+
+
+功能三：充值功能
+这个大夫分享是可以直接跳出那个微信付款的，嗯。然后那个充值的页面的那个余额充值，这个去充值的点击一下，到后台需要有一个余额显示的那个地址在我的，咱们那个他有多少的余额？这里得有一个充值的一个入口，充值余额的入口在我的。的那个会员中心下面，嗯。以读章节跟推荐好友不是会员中心，在未会员中心，下面就是已读章节跟推荐好友跟我的。我的收益下面是我的余额，那点击进去又是一个就是充值的页面。然后这个是充值的那个收益的这一个功能。
+
+功能二：代付分享
+![](images/2026-03-15-09-54-15.png)
+的话，就是这个大夫分享是可以直接付款的，付款一块钱给这个付款一块钱给指定的人，发送推荐给指定的人，那这个指定的人就可以不用钱了，看的时候就可以直接不要钱了。那这个是代付分享的过程，然后如果你代付分享多个人的时候，你想代付分享到朋友圈的时候，这个是需要充值的，可以多发扣，就自动扣你的余额的这个账户，那这个就属于充值的，在我的里面跳到我的里面的一个充值的一个东西。把这个代付分享做一下。并且。能实现。
+
+功能一：分享到朋友圈
+![](images/2026-03-15-09-52-35.png)
+![](images/2026-03-15-09-52-53.png)
+文章里面这个下方，文章下方的这个右下角的这个分享的功能是分享到朋友圈。分享到朋友圈，就并且把这个朋友圈分享到朋友圈，要自动写一段文字分享，它是分享到朋友圈的功能，并且分享到朋友圈需要自动写一段文字。那他使用的是这里的分享朋友圈的那个功能。那帮我完善一下这个分享到朋友圈，然后第二个的话就是分。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260314内容管理7.md b/开发文档/1、需求/已完成/20260314内容管理7.md
new file mode 100644
index 00000000..3afd1541
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理7.md
@@ -0,0 +1,10 @@
+
+
+功能二：增加头像功能
+![](images/2026-03-15-10-38-24.png)
+然后看到这个书的那个规则里面需要添加一个在咱们那个规则配置里面看书这个功能，看书就是玩需要看完这个看书看到百分之，如果没有头像的话，第一次看头像跟昵称，看到第一本文章 ，的时候就需要设置图像跟昵称。付完费，的时候就要看到图片
+
+功能一：付费功能
+![](images/2026-03-15-10-31-25.png)
+优化做一个，每个文章都多一个编辑，这个是默认的话未付费，默认的话是20%。那其他文章编辑完之后是有一个百分之可以自定义的一个功能，编辑可看的幅度的百分比的一个功能。那这个同时在分享到朋友圈，同时是实现的，这个是内容的微付费预览，那确保帮我检查一下这个，那个分享的过程当中没有付费的也是看不到的，就要提要有付费的这么一个功能。付费的一个功能，那只有一个，所有的功能都只有一个入口未付费付款比例，那每一个章节都可以有这么一个功能。
+那顺便检查一下直接处理
diff --git a/开发文档/1、需求/已完成/20260314内容管理8.md b/开发文档/1、需求/已完成/20260314内容管理8.md
new file mode 100644
index 00000000..6040fde3
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理8.md
@@ -0,0 +1,23 @@
+
+
+
+
+
+
+
+功能三：首页内容排名
+那个小程序首页的这一个小程序首页的这一个最新更新增的这一个的话，第一个是最新更新的，不一定是第几场的排序，然后第二个的话默认显示那个三个，默认显示三个，然后底下的话就有一个有滑动，往下滑动，那么才显示出来有一个展开。变成10张，展开变成10张，那接下来多的就是按这个那个排名、那个热度排名来展示，再往下拉的话就按热度排名展示，所以它是前，整个规则是前三，前那个10篇是新的，然后只显示3天前，只显示5篇，不是3篇，只显示5篇。然后有一个下拉的小图标，可以点一下展示成十篇，然后如果还要往下看，下拉的时候就是按照热度的排名往下生成展示给展示出来。还有一个问题就是资源对接这边匹配半天匹配不上不动
+image.png![](images/2026-03-15-11-13-16.png)
+
+功能二：代付
+
+每一次那个有小程序的修改的时候，直接就是那个上传到小程序的那个版本，1.2.6的这个版本上面体验版直接就上传上去就行，更新了就直接上传，保持有小程序更新，就是执行这一个这个操作。然后那个。
+![](images/2026-03-15-11-06-59.png)
+然后这个代付分享的这一个底下有三行，分别是那个分别是分享给好友，然后代付分享，然后还有一个，最后一个是海报的功能，还是原来海报功能，刚刚那个分享到朋友圈的是属于嗯浮浮窗的这一个分享到朋友圈这个功能是属于浮浮窗这里面的这一个功能。不要搞混，混销混到分享到朋友圈的生成海报是固定到文章的右下方，那分享到朋友圈的是浮窗的这么一个功能。
+
+
+功能一：
+![](images/2026-03-15-11-02-38.png)
+这个可以新增一个 add 的栏，并且创建一个新的一个计划，直接在这里面直接 add，形成这个计划出来就艾特了等人的那个新增的那个计划。在后台直接新增这一个人，没有的情况下，在文章里面直接可以新增。
+
+我的余额显示到这个，那个第四方已读章节跟推荐好友我的收益后面新增一个就是我的余额，第十个这个就真实的显示真实的余额就可以了，以及充值的这个页面下面这个我的余额去掉，不要出现重复，直接转移到这个上面来。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260314内容管理9.md b/开发文档/1、需求/已完成/20260314内容管理9.md
new file mode 100644
index 00000000..e575ec5e
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260314内容管理9.md
@@ -0,0 +1,16 @@
+
+
+
+功能四：文章内容解锁问题
+加一个规则，就是那个20%是不能超过500个字，不是固定。前面还有一个规则，就是那个如果20%超过500个字，也是只显示500个字，默认的不一定是20%，是默认的这个百分比超过500个字。除非是手动测试的情况，不然都是默认就是不能超过。500个字。
+
+
+功能三：存客宝获取优化，迁移到前台
+![](images/2026-03-15-11-48-00.png)可把这边的 TOKEN 都连接上，那这里的话是跳到乘客保证这页面就不要了，尽可能的把乘客保证的参数配置都配置在咱们的这里的这一个里面，场景获客的这个功能都配置到这个里面，并且把这个列表跟获客情况都列清楚。每一条、每一个人链接的的有多少个人？多少的获客把这些参数跟数据都放到这个页面里面，可以直接看看得到，可以在这个新增一个这个编辑旁边新增一个按钮来看这个功能。
+
+功能二：
+![](images/2026-03-15-11-38-40.png)
+![](images/2026-03-15-11-39-07.png)a 内脏这个章节底下这个热度算法和第几名热度算法是有问题的，检查一下这个热度算法的一些情况，热度算法有问题，帮我处理一下这个热度算法相关的功能，然后包括这里的话热内容的排行榜都来排行，跟这个排名算法、排兵算法这一个没有生效。帮我处理一下这个问题。这一都没有生效，这个热度有问题帮我处理一下。
+
+![](images/2026-03-15-11-40-29.png)
+然后第二个的话就是编辑。编辑文章这里的话有一个那个热度分也是没有生效的，帮我全面的去检查一下，这个热度分也没有生效。然后编辑框这里增加一个 add 的功能，以及上传视频的一个功能，非上传视频支持上传视频的功能，视频的话上传到 OSS，阿里的那 OSS 上面。iOS 在后台直接可以配置用卡洛的那个卡洛 AI 拿那个 OS，然后检查一下 OS 的地址，在后台也可以直接配置，图片跟视频都传到 OS s 上面，阿里云的 OS s 上面
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315 用户管理2.md b/开发文档/1、需求/已完成/20260315 用户管理2.md
new file mode 100644
index 00000000..ffb9b6d9
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315 用户管理2.md	
@@ -0,0 +1,13 @@
+
+
+
+
+功能二：用户旅程
+![](images/2026-03-15-15-52-30.png)
+长沙现有的数据库的行为里面直接完善。直接完善，然后把这个用户旅程给我，帮我弄好写清楚。
+![](images/2026-03-15-15-53-00.png)确保用户旅程跟规则配置里面要有相应的数据，不要不是显示重新加载你这个数据得帮我显示出来，现在看不到直接帮我处理掉。
+
+
+功能一：![](images/2026-03-15-15-51-08.png)
+are if in 的算法，那个放到那个右上角这里，然后把这个里面咱们的相应的能计算的所有用户，关于用户行为能计算的和用户旅程能计算的都用 AI，你来整理一下，归类到 if、in 这三个维度来进行相应的那个 r，f。m 的估值的一个评分，以及它可以对接存客宝这边的一个算法进行估值的一个评分。那这个是 FM 的估值的一个形式。
+并且确保我这边估值的评分是有这个估值的评分的。然后并且这个算法可以按跟那个内容的排序形式一样，是可以做一个那个排名算法，就放到这个上面去 IFM 的估值的算法一样放到这个上面去，左右上角上面
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315内容功能13.md b/开发文档/1、需求/已完成/20260315内容功能13.md
new file mode 100644
index 00000000..bd267720
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315内容功能13.md
@@ -0,0 +1,7 @@
+
+
+
+
+功能一：
+![](images/2026-03-15-23-04-54.png)这里话是可以选择密钥，是选择存克宝。密钥同时是选择纯科宝的上面这个 API 获客的那个场景获客的计划，并且这个场景符合计划，可以搜索的，可以直接选择是哪个计划，选择完之后可以调用相应的参数直接覆盖掉，再存个把，那这里都快修复，存克宝密钥，这个直接关掉删除。不要这个按钮。
+![](images/2026-03-15-23-05-29.png)你可以调用存克宝的接口，里面调用相应的那个计划，然后直接可以选择下拉框，可以选择匹配，嗯，也可以直接新建。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315匹配功能1.md b/开发文档/1、需求/已完成/20260315匹配功能1.md
new file mode 100644
index 00000000..ff31c0ee
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315匹配功能1.md
@@ -0,0 +1,12 @@
+、
+
+
+功能二：填写手机
+能。使用匹配功能的话，一定要注册好手机号，一定要自己要注册手机号的那个田琪手机号和获得头像，那这个才能做匹配的功能，整体点匹配的功能
+![](images/2026-03-15-15-55-33.png)
+要确保后面提交的线索上面有那个手机或者微信号。
+
+功能一：
+![](images/2026-03-15-11-17-27.png)
+匹配功能右上角有一个那个设置的这个标签，帮我把它去掉右上角这个设置的标签去掉。
+所有的匹配功能。所有的匹配功能都是点一下开始匹配资源，然后默认填写好这个。但点匹配功能的时候，那个资源对接的时候就需要填一下自己的那个诉求完善资料，点击匹配自由完善资料。完善资料跟头像，那这个点击匹配默认都是那个3~10秒的时间再弹出来。
diff --git a/开发文档/1、需求/已完成/20260315数据统计1.md b/开发文档/1、需求/已完成/20260315数据统计1.md
new file mode 100644
index 00000000..90891adb
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315数据统计1.md
@@ -0,0 +1,12 @@
+
+
+功能一：数据统计
+功能四：
+这个网站上面的标签都需要有一个统计，然后在后台能实时能看到然后那个后台的那个小程序上面的美的标签的那个美的每一个点击标签的那个都做一次统计，看一下哪一个标签点击的统计的一个排行，那后台里面要看得到小程序上面每一个标签，每一这个动作的一个点击的排行，然后用按照我们分类的模块来进行分类。能知道每一个按钮的点击次数。以及这个是前端的，然后后端的也是一样，每一个按钮的按摩块的一个点击次数的一个统计。这个功能在数据概览的分类标签的功能底下。
+
+![](images/2026-03-15-11-54-06.png)然后在这充值就没有把充值赠送这个去掉，充值赠送的这一块去掉，然后这个里面的话是您能充值之后那个。可以直接申请退款的，那分别选择了金额就是。10块钱，30 50。1,000把100改成1,000，然后这个交易记录就是谁看看了这篇文章，他能看得到这个叫那个阅读那个消费记录，这个是我，我的余额，包括自己的一些交易记录也放上来。要确保这个接口，小程序是可以直接支付的。
+
+
+功能二：vip会员
+![](images/2026-03-15-12-00-17.png)
+那个卡路创业派对的这一个界面的。界面的话第一个解锁全部章节 VIP 默认就是加入会员就解锁全部章节，然后第二个的话，那个。链接资源和匹配，小伙伴放第一，社交权利就是匹配创业伙伴，然后第二个的话就是链接资源，第三个才是那个加入创业老板排行。第4个才是专属的那个。VIP 标识。然后内容的权利的话就是解锁全部章节一年，然后。加入那个创业项目团队。第三个的话就是每日纪要的阅读权限。美乐派那个派对纪要的阅读。然后第四个的话，就是那个。那个自己就是项目，自己下有机就是项目。认可的项目可加入那个文章，获得合作伙伴的内容权益，然后加入考诺的创业派对，改成加入考诺创业派对 VIP 会员。然后下面那句一字加入尊享那个去掉，删除掉。不要有下面这一句话。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315数据统计2.md b/开发文档/1、需求/已完成/20260315数据统计2.md
new file mode 100644
index 00000000..5dca4d0d
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315数据统计2.md
@@ -0,0 +1,14 @@
+
+
+功能二：
+![](images/2026-03-15-15-45-31.png)老伙伴包括 AI 拓客数据，这里的话有点多，找伙伴和 AI 混合数据统计，这一个变成简洁整合一些，简洁整合起来一些。那把这些用户数据统计这一个变得更简洁一点，然后。更简洁一点，功能性变得更有效一些。但做一些优化迭代的用户统计的这个地方，那我能一目了然知道整个网站的一个情况。那把 AI。
+
+
+![](images/2026-03-15-15-47-07.png)
+其他的几个数据统计也是一样，统计的数据。统计的数据集中在一页，然后简洁一点，数据清晰并且有关联性能描述整个的整个网站以及这个用户体验，体现在用户那个使用那整个踏盘的一个数据上面。
+
+功能一：统计
+![](images/2026-03-15-15-43-56.png)
+开户统计变成一个小标签，统计一下就可以了，代付统计的一个数值在那个收入里面。对，一个特殊的一个标签，然后里面统计的那个充值的余额在咱们的这个用户管理里面体现就可以了，还有多少余额就在用户管理底下，那提现有多少余额就好了，不要再不需要再额外在首页上面新增一个。
+
+![](images/2026-03-15-15-44-38.png)今日点击这里的话，显示的就是今日点击这个就是点击数量，但是这个是按月的统计的点击数量。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315用户管理1.md b/开发文档/1、需求/已完成/20260315用户管理1.md
new file mode 100644
index 00000000..234d95b1
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315用户管理1.md
@@ -0,0 +1,45 @@
+
+
+功能十：用户rfm估值
+![](images/2026-03-15-15-38-25.png)然后以各个的用户旅程跟用户习惯和标签和我们的那个 RF m 的那个估值的一个算法，对这个用户的 RF m 进行一个那个小程序上的一些估值，然后按我们的一个估值的把这个估值的一个估值的分值的一个形式。按这个的分类，同时把这个估值的算法放到用户管理的右上角，这个估值的一个算法 RFM 估值的算法放到这边，并且这一个有可以跟存那个神色手这边对接一整个的一个接口也帮我写清楚。
+
+
+功能九：全量优化
+然后全力思考这个用户，那个用户管理的整个的这个模块，然后看一下整个用户管理的模块的一个湿滑度，然后跟整个项目的一个方向帮我做一些在上面修改，并且保证所有的功能可用的情况下，那帮我做整体的一个。修改。整体的一个修改，并且。并且把这个。权力的思考，并且做整体的一个优化修改，在这方面叠加我的一些想法，以及那个帮我搜索最佳的一个方案策略，全网搜索一下，来帮我思考这个和我这个书的一个方向的一个优质的一个解决方案，那继续帮我优质和优化，并且在检测优化完之后检测没有任何 bug。前端后端以数据库是完善的情况下来做
+![](images/2026-03-15-15-38-44.png)碰到所有的错误，直接帮我解决掉，嗯。
+
+
+功能八：超级个体
+然后这个超级个体的列表，就是我们在超级个体是可以置顶到首页有四个位置，四个位置是超级个体，成为超级个体的话就可以直接在这个四个位置，那这个后台咱们是可以直接置顶的，只有四个位置不能超过四个。然后这4个的话是要成为 v 那个 VIP 会员才可以直接使用的。这超级个体的这一块，然后也可以去做字典。
+
+功能七：规则配置
+![](images/2026-03-15-15-32-18.png)体的那个规则配置里面，规则配置我们前期有设置的一些规则配置，比如它注册需要点击头像，并且这些规则配置需要在整个的网站上面做好锚点，一注册判断做好规则，它一有这个用户点击的什么内容，就需要执行什么操作，比如那个添加头像写名字。以及他需要是的各个的行为的一些规则配置。嗯，帮帮我把这个完善整个规则，并且把规则写清楚。嗯。把我们的规则写清楚，完善清楚，并且直接可以生效。设置好一定是可以生效的，跟咱们整个网站深度的理解一下。
+
+功能六：用户旅程
+![](images/2026-03-15-15-31-01.png)
+然后这里的整个的用户旅程的规则，就我们就用户旅程的这些说做所有的一个汇总，然后这边点击进去都是每一个旅程都是可以看到那个具体的一些客户点击进去有完善的，有多少的用户都能直接看到并且分类。然后这些整个行为有操作的，各个的行为锚点尽可能去丰富以及统计。这权利的去理解，并且帮我深度的那个和用户的旅程绑定和用锚点绑定。这里主要是统计用户的习惯用的这个用户旅程主要统计用户的习惯用以及这些用户的那个成交程的一些细节。
+
+
+功能五：标签体系
+![](images/2026-03-15-15-28-26.png)
+![](images/2026-03-15-15-29-05.png)用户标签体系的话是需要去清晰的去了解标签体系，嗯，添加这个用户有留存到的时候，实时推送到存客宝里面的标用户词的一个标签体系里面。那后面一个人的这个用户旅程，这里都需要有记录，从他的注册到他成为会员哥哥的那个用户旅程的标签，咱们整个的网站上面都需要把这个用户旅程的标签打清楚，然后从已经注册的只有一个用户旅程就要写上只有一个用户旅程，然后关系链路有匹配的就要写清楚关系链路的一个形式。这个是标签体系，嗯。
+
+功能四：
+
+能更新你一下这个开发的这个群开发的一个形式，开发的那个发送开发的时候一定要用这个派对 AI（/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/派对AI） 进行开发，把这个要加到派规则里面，默认的规则里面，然后这个派对 AI 开发的过程当中要把要绑定群，那这个群都固定做这个，如果用这售的开发的时候。都需要固定的把这个发到这个售的创业派对开发资料群里面。
+https://open.feishu.cn/open-apis/bot/v2/hook/c558df98-e13a-419f-a3c0-7e428d15f494
+使用派对 AI 来进行开发，默认的开发每一次都是需要派对 AI 优先领域卡罗 AI 来读取来使用，然后把复盘的格式都写上去。
+
+功能三：会员权限
+成为会员的这一个页面，那个可以。社交权利改成派对权利。你会员权利，比如派对权利改成会员权利那匹配。匹配次数是有1,980次匹配次数，然后还有链那个。一个那个书里面，那个整个的全年的可书里面解锁章节。新增张杰非争执张吗？解锁新那个张杰是那个。张杰队。解锁全部章节，这对，然后一个。加入创业项目，查看最新的项目，那个查看最新创业项目权限。查看最新创业项目，这个也是一个权利，然后一个。美，每日的专属团队，每日。纪要总结。然后。自营项目可参与匹配，小伙伴可参与到匹配。那个社交权利匹配创业伙伴，是那个加入创业伙伴词获得创业客资匹配的创意合伙人。然后每一个的话总结一下，不要超过四个字。这个是会员群里这块。
+‘那还有一个，每个权限都是要对齐的，那个派对权限，这里社交权限改成派对权利，这里头还有一个点是文内，文章内只要提到你的名字，别人你只要提到你的名字，有人就可以直接点击爱得到你的名字，就可以直接那个加到你，就可以直接 AI 来协助你。链接，你来协助链接跟你产生链接拉群，然后把这几个权利都帮我柔和一下，特别是标题，不要超过四个字描述清楚。然后这个有相应的功能，
+然后这个。支付1980元。那个成。几底下这个字？1980年那个加入创业，加那个。立即支付1980元。加入创业派对，这个 VIP 会员就不要写了，把这句话改一下。
+![](images/2026-03-15-15-23-04.png)
+
+
+功能二：首页
+![](images/2026-03-15-15-17-08.png)然后这个首页这里的话显示不是最新更新了，显示是那个。推荐。然后开始阅读，是要改成点击阅读。
+
+功能一：vip会员
+![](images/2026-03-15-15-14-34.png)
+这个 VIP 会员无法。这个 VIP 会员那个无法保存跟关闭，在后台这个用户详情里面无法保存跟关闭，帮我处理一下，并且检查这个所有的这个功能是否按照要求过来，要求来操作。那并且保证所有的功能是可以使用的，可以正常的使用，把整个的功能的一个链路帮我做好，做清楚并且检测清楚，然后帮我修复好。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315用户管理3.md b/开发文档/1、需求/已完成/20260315用户管理3.md
new file mode 100644
index 00000000..2c31dbc7
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315用户管理3.md
@@ -0,0 +1,32 @@
+
+
+功能一：标签别人以及bug修复
+![](images/2026-03-21-12-59-45.png)
+![](images/2026-03-21-13-00-50.png)
+就通过接口上来的这个文章的这个并没有自动解析井号神仙团队的这一个内容，嗯，它解析的一个形式的话是它，咱们在在后台，它匹配咱们后台的这个井号标签。这里，这个库如果有，在这个库里面就实现实行解析。嗯，四星解析。然后这个小程序这边的话是可以直接点击的。可以直接点击，然后可以去点击添加别名，就是链接标签这里可以点击添加别名。
+
+
+功能二：api接口文章
+![](images/2026-03-21-13-02-36.png)
+所有的接口它只有一个 API 的接口，然后我们这个 API 的接口的话是要选择一下，就是这个 API 的接口，是我通过写文章写，咱们写文章上传之前上传到数据库，现在的话是通过有 API 的接口上传的时候是上传到咱们这个文章里面的内容。要上传到编辑器里面，这编辑器里面的结构跟相应的东西，包括里面咱们在本地上传的图片也是通过编辑器里面的保存，比如上传那编辑器里面的那个 OSS 的服务器等等的这么一个继续保存的一些功能跟内容，这个是咱们编辑上传到文章得带图。指定的图片得做一些调节，到这个上传到这个文章里面，这个通过接口上传文章的图片也是上传到 Oasis 的那个上面去。把整个的这个 API 接口。写清楚。然后同时咱们这个本地上传到上传文章的这个接口，也是使用这个接口来来写，来写，来上传。文章，确保文章视频和图片，视频图片都可以上传到 VSS 上，通过接口
+
+功能三：后台拖拉
+![](images/2026-03-21-13-07-12.png)然后这个板块的话是它拖动，拖动完之后是没有写，没有显示的，那拖动不过去拖动到前面其他板块是一样的，但2026每日派对干货这个这种新增的板块拖过去就没有就不行，不能占用。然后第二个的话，这个这些图片就不要写1234。这个上面的这个一2这个图标，嗯，章节前面那个图标不要写12345，换个通用性的图标。
+
+功能四 用户后台头像裂了
+![](images/2026-03-21-13-08-21.png)不管你这里图片拼接是有问题的第一个途径，拼接是有问题的第二点，用户的话，会员用户是可以直接捆绑到，请把这个纠错让解决掉。就不管你。图片。第二点的话就是超级个体就需要完善资料付款，超级个体登录之后要完善他的那个材料，像这个 VIP 就是他头像跟名字跟手机号跟业务，这个得完善一下。
+
+功能五：界面数据调整
+![](images/2026-03-21-13-09-43.png)
+![](images/2026-03-21-13-09-55.png)那这个推广中心跟找伙伴这个功能变成在一页里面，一页里面就不要有多页，那这个数据以及咱们的整个人项目为主，把这些数据变得清晰、简洁、有观影性一些。
+
+功能六：获客
+![](images/2026-03-21-13-11-37.png)
+那首夜这边的话，像这个写的就是一个获客，后台获客，并且这个获客点击进去的功能是要保持是一那个去重的一个状态。Hawai 驱虫，并且这个霍克列表咱们是可以通过配置 Webhook，那个有新增的，就通过 Webhook 传到那个这个群里面去。这个 webhook 可以直接设置。
+写这一个是排成一行就行了，就不要用两行了，这个是这个宽度，就是自动的那个调整一行就行，自动的调整。
+
+功能七：分类标签统计
+![](images/2026-03-21-13-12-31.png)然后这个分类标签统计的话，像这种超级个体这样，这个是带 ID 的，里面应该是点击的哪一个超级个体的名字，超级个体的点击跟那个相关的一个东西就类似的，也帮我把这个分类标签统计，帮我那个重新的设计一下。
+
+功能六：标签
+![](images/2026-03-21-13-13-22.png)当这个关联小程序的这个功能应该跟那个链接标签的功能整合到一起，直接就是融合到这个里面，就减少一个关联小程序组织去整合到链接标签，那这个链接标签就可以设计别名了，并且点击这个标签的这个名字的时候，是可以直接编辑的。
diff --git a/开发文档/1、需求/已完成/20260315用户管理4.md b/开发文档/1、需求/已完成/20260315用户管理4.md
new file mode 100644
index 00000000..309fd7be
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315用户管理4.md
@@ -0,0 +1,19 @@
+
+
+
+功能一：客户数据查看
+![](images/2026-03-19-14-51-34.png)的时候，就是我，就我需要把所有的客资，那个客资放到那个首页的数据中心来，把所有的那些个那个超级个体以及从文章获取的客资的内容统一的能让我统一的能调取，能让销售能看得到整个的一个用户是谁，用户画像。并且用这些用户是可以点击并且能看到他联系方式的，那这个刻字的列表第一条就是联系方式
+
+功能二：获取@的优化
+![](images/2026-03-19-14-54-24.png)
+![](images/2026-03-19-14-54-56.png)
+功能是什么？就是这里的话有一些 ad，对吧？你到这边的话，首页的那一标签的那个 ad，ad 标签在这里面的链接人跟4的这边首页每个人都是可以进行一个置顶的，对，需要一个置顶的一个按钮，对吧？你把这些就他需要一个置顶的一个按钮，然后这个置顶的按钮是可以让我们的小程序上面实时的那个点击谁置顶就实时的去置顶谁的这一个。谁的这一个内容吗？你就实时的这个字典，那切成他自己的一个头像，这个是置顶的功能吗？那这个置顶的功能跟咱们超级个体艾特的功能是保持一致的吗？就是谁置顶那个就显示谁吗？
+
+功能三：存客宝场景bug
+![](images/2026-03-19-14-56-16.png)
+这里的话就纯克宝这边的那个场景，获客是显示离线的，正常情况我配置完之后是需要显示在线，如果解决不了这个问题的话，你就要做一个记录，然后跟那个纯克宝这边的开发人员做一个对接，让你尝试着去解决一下这个问题。如果接口有的话
+
+功能四：去重
+![](images/2026-03-19-14-59-01.png)
+
+是不是这点击进去之后，这个计划的管理就直接点击进去计划的管理的话，它这里的话是没有去重的，统一要去重，并且这里的话去重完之后要跟那个存克宝那边的那个场景获客是匹配的，那这里如果不匹配的情况下，这边应该多增加一个功能。就存克宝这边，克字已经重复了，已经有了，或者重复了，或者有计划，他需要反馈一条信息给我来完善这个表单，让我知道他具体的一个情况。那这个的话同时也要在这个客资的这个板块的这一个里面体现这个客户的在存客保里面的情况，并且能回掉他的那个数据吗？对，那如果你碰到问题，你就直接告诉我，这个要也是一样变成存客保的一个需求，嗯。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260315用户管理5-用户旅程.md b/开发文档/1、需求/已完成/20260315用户管理5-用户旅程.md
new file mode 100644
index 00000000..1963ba04
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260315用户管理5-用户旅程.md
@@ -0,0 +1,33 @@
+
+
+用户旅程
+然后做完所有的功能的时候，统一的去完善一下，并且是追问和思考清楚，把整个这个功能全部完善清楚。多思考一下，防止有一 bug，那检查所有的问题。
+
+
+
+功能一：用户修改
+![](images/2026-03-19-15-13-48.png)
+![](images/2026-03-19-15-14-18.png)小程序要改了，就我刚刚说的它的那个之前是用户点进去看的时候，它是不要求马上去看文章的时候，是不要求马上去修改资料的，但我觉得它只要有发起支付或者是一些相关的行为的时候，就应该要引导它去进入个人资料，引导引导页进行想跟昵称的修改。这是现在大部分 APP 他们都这么做的。对，还有补充的吗？然后把这个引导页弄完之后，我们还需要做一个东西是什么？就是我们在这个用户的规则里面可以做一些修改和锚点，在我们这个用户的规则里面直接规则配置里面直接变成一个    可配置，可生成的一个触发的一个规则。改这个规则的时候，把具体的实现方式给我一个不超过100个字的描述。并且告诉我你改了哪一些文件以及改变的方法，然后以复盘的形式发到那个飞书群里面
+
+
+功能二：推送信息
+![](images/2026-03-22-13-51-18.png)
+![](images/2026-03-22-13-51-33.png)到群里面的那个获客的信息也需要有一个至少最近的用户行为轨迹，就他点击的最近的5个地方，有用的这个5个地方，这个是用户行为轨迹的这一个5个地方的一个内容。然后把这个是关于获客通知的这一个功能。
+
+![](images/2026-03-22-13-52-25.png)
+![](images/2026-03-22-13-52-59.png)搜索整个程序，就是咱们这里的话，整个这个页面前面的，特别是超级个体这一块的那个会员体系，得把它完善一下，会员体系相应的材料在后端你要呈现出来并且能改，然后。珍惜所有的功能，有能用的功能就都迭代一下，然后尽可能的去自动化，包括它的那个用户旅程，就是它点击了什么什么位置，这个用户点击了什么位置，做一个那个记录，每个用户做一个记录和存储。没有一个优化迭代，然后把这个点击的行为和记录也记录下来
+
+
+功能三：规则配置
+![](images/2026-03-22-13-54-25.png)还有这里面的所有的那个规则配置都描述的形式都是比较利他的对一个形式，然后这边的话如果已经有做了相应的行为的用户，多说一下记录，不要让他每次都做一些相同的一个行为，已经做完了的用户就不要再显示了，在里面触发的事情完成就不要再显示了。然后把新增的需要完成
+的规则配置也配进去了，包括详细的配置按钮都配置进来，那都在这个规则配置里面。
+
+功能四：超级个体名片
+![](images/2026-03-22-13-55-56.png)然后这里的话，那个超级个体的名片就放到这个 VIP 的那个头像里面就行了。VIP 的头像里面显示。不对，这超级个体的那个名片跟那个会员中心放在同一个位置，然后那个。放在同一个位置，那不要放到，不是放到那个 VIP 里面了，放到跟会员中心一个位置。
+
+功能五：用户旅程
+![](images/2026-03-22-13-56-49.png)
+对，这个用户旅程的深度的一个理解，每一个用户旅程主要是观察每一个用户的一个用户旅程能清晰的知道全平台所有的用户旅程跟具体的一些动向跟行为的一个分析，这个最终想要达到的一个目的，针对这个页面的话。清晰的知道什么用户是有价值的一个评估，参与到评估体系里面的一个功能，所以这个用户旅程的这个界面怎么样去操作，并且能知道所有的一个用户的那个行为？帮我重新设计一下这个功能。
+
+
+那个也更新一下 skill，每一次对话执行完之后告诉我你的那个执行的那个总时间是多少，以及消耗的 TOKEN 是多少？更新一下卡尔维安的 skill。更新到卡罗拉的 skill 里面，这个是对话的一个优化。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260321 小程序.md b/开发文档/1、需求/已完成/20260321 小程序.md
new file mode 100644
index 00000000..025e6f8f
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321 小程序.md	
@@ -0,0 +1,16 @@
+**落地（代码，2026-03-22）**：① 我的页已解锁区提前、仅 `unlock-muted-teal` 图标、5 条+倒三角、倒序不变。② 规则引擎冷却关闭 + onShow VIP 引导间隔关闭 + 去掉 checkVip 内 3s 防抖。③ 订单 `product_name` 与轨迹章节标题后端 `sanitizeDisplayOneLine`；小程序 `cleanSingleLineField` 用于订单/目录兜底标题。④ **首页**：超级个体横滑**首位固定「卡若」**（`onLinkKaruo` 留资，与顶部「链接卡若」同链路）；列表过滤昵称「卡若」及历史误写「卡路」避免重复；顶部 Logo 英文改为中文「派」；精选列表去掉章节编号行（如 `1.1`）；区块副标「获客入口」。⑤ **会员展示名**：`formatVipMember` 对 `name` 再跑 `sanitizeDisplayOneLine`。
+
+**原文需求（口述整理，品牌统一为「卡若」）**：
+
+![](images/2026-03-21-22-58-44.png)
+![](images/2026-03-21-23-03-31.png)
+这一个的，这一个页面的话，把已解锁换成一个，换成放到前面，然后做一个解锁的图片就可以了，不要显示文字，简洁一点，不是那么突显的图片，然后这边最多就显示五篇，然后也是要超过就需要想看更多就需要点一个倒三角的一个展开。然后这个排序的话，嗯，在后台里面那正确的排序是倒序，有最新的显示才最前面。
+
+![](images/2026-03-21-23-00-16.png)
+![](images/2026-03-21-23-00-41.png)操作频繁，2分钟这个限制去掉。然后第二个的话，就是这里的话名字这边后台看一下到底是怎么回事和这个解析的这个编码它变成有自动回车了，这里的话应该自动，不是要通顺的，不是 a 的完之后就自动回车，这个帮我处理一下。
+
+
+![](images/2026-03-21-23-01-29.png)
+![](images/2026-03-21-23-02-49.png)然后首页这里的话，那个所有的标签的入口。首页这里的话也是获客的路径，也是跟**卡若**那边的获客路径，这个点击链接**卡若**这边的话是任何人都可以置顶到这个地方来，都可以点击，都可以在这个上面直接选任何超级个体都可以。那个点击可以链接，那现在默认的话就是**卡若**，在后台就是一个默认的话就是一个**卡若**的一个默认的一个状态，点击就直接添加并且配置好了。这个页面的名字放在图片的那个下面，然后把这个片里面那个英文相关的去掉。
+
+**状态**：本条需求已按上文「落地」全部闭环。
diff --git a/开发文档/1、需求/已完成/20260321 用户管理1.md b/开发文档/1、需求/已完成/20260321 用户管理1.md
new file mode 100644
index 00000000..d1f229e3
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321 用户管理1.md	
@@ -0,0 +1,28 @@
+## 实施进度（开发备忘）
+
+- [x] 用户管理 · 算法配置区：**默认折叠**，点击标题行展开 RFM 说明与分层徽章；**按 RFM 排序**始终外露。
+- [x] 开发环境 `/api-docs`：Vite 代理已排除 `/api-docs`，避免误转发后端 404（改代理后需重启 dev）。
+- [x] RFM 增强（首版）：后端 `/api/db/users/rfm` 已含推荐/轨迹/资料维度；管理端说明已对齐。
+- [x] 用户详情：行为轨迹时间线 + 类型汇总；OpenID/手机/微信标识绑定说明；轨迹接口返回中文标签与章节标题解析。
+- [ ] 用户资料完善：神射手接口对接与旅程/资料联动。
+- [ ] 获客列表：优化、重构、去重展示。
+
+---
+
+完成之后，对，所有的那个给一个功能都需要开始的时候，对，每个功能先搜索一下更好的一个营销大师的用户管理大师跟用户旅程评估的大师的角度来做一些管理跟体相应的每一个功能之前都做一些调研，然后来进行整个的一个优化
+
+功能一：rfm
+![](images/2026-03-21-22-41-29.png)那个所有的用户都有一个算法的 if 算法的一个分子，按照他们的几个标签，你按照他们标签和这个和行为轨迹来做一个用户的那个估值的一个评分，这网站独有的算法就放到这里搜索整个网站的一个算法，然后那个要折叠起来，在这个用户管理。这个不要展开折叠起来，反正你很难看。那能保证所有用户根据他的行为轨迹和点击，每个用户的点击爱好都需要做一个统计，能算到能知道他的一个行为轨迹。
+
+![](images/2026-03-21-22-42-05.png)
+![](images/2026-03-21-22-42-46.png)那个所有的用户的行为轨迹点击的补充一行，它的一个那个在咱们的用户详情里面，它的一个用户旅程多一个分类，就是它的所有的那个行为轨迹都能看得到，然后这个行为轨迹也是记录 IM 的估值里面，行为轨迹也是记录 IM 的估值里面。然后这个 用户的 ID 是以这个 open ID 为准。微信那个用户 ID 跟这个微信的 open ID 它是一个捆绑和他的手机号这三个是捆绑的关系，互相匹配的，一个一个的。
+
+rfm
+![](images/2026-03-21-22-44-44.png)然后这个用 if m 的估值从它的推荐几个维度推荐人数，还有它的用户旅程，推荐人数、消费频率，还有它的一些链接的关系链路等等，综合的网上思考一下网站所有的那个因素。那来做一个融合和整合，你思考全面一些，然后有可能的一个关键用户的那个推荐要弄清楚。
+
+功能二：用户补全
+![](images/2026-03-21-22-43-45.png)然后这一个用户的资料完善，就是调取这个神射手那边的接口之后，整个的这个资料完善之后，你清晰的知道这个用户。那我可以清晰的补全所有的用户资料，用户材料，并且可以详细的也连用户旅程跟用户信息都补全，然后你搜索一下互联网上有没有相应的一个解决方案？直接帮我处理掉这一个，把用户资料完善，这个写清楚。
+
+获取列表
+![](images/2026-03-21-22-46-49.png)这个获客列表的话，这做一些优化跟重构。并且做整合我驱虫展示。
+
diff --git a/开发文档/1、需求/已完成/20260321内容功能1.md b/开发文档/1、需求/已完成/20260321内容功能1.md
new file mode 100644
index 00000000..bd267720
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321内容功能1.md
@@ -0,0 +1,7 @@
+
+
+
+
+功能一：
+![](images/2026-03-15-23-04-54.png)这里话是可以选择密钥，是选择存克宝。密钥同时是选择纯科宝的上面这个 API 获客的那个场景获客的计划，并且这个场景符合计划，可以搜索的，可以直接选择是哪个计划，选择完之后可以调用相应的参数直接覆盖掉，再存个把，那这里都快修复，存克宝密钥，这个直接关掉删除。不要这个按钮。
+![](images/2026-03-15-23-05-29.png)你可以调用存克宝的接口，里面调用相应的那个计划，然后直接可以选择下拉框，可以选择匹配，嗯，也可以直接新建。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260321内容功能2.md b/开发文档/1、需求/已完成/20260321内容功能2.md
new file mode 100644
index 00000000..ca511721
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321内容功能2.md
@@ -0,0 +1,30 @@
+这些修改，所有的功能都不要修，现在所有的都不要修改小程序。小程序的界面不修改和小程序的这个功能不修改的情况下进行调整。
+
+
+功能一：功能合并
+![](images/2026-03-21-13-56-22.png)关联小程序管理跟这个合并在一起，然后去跟那个链接标签合并在一起，然后需要有一个那个。就关联小程序管理内容与那个管理小程序链接标签跟这个关联小程序管理两个功能合并到一个功能，然后这个标签可以设置这个别名，嗯，可以同时几个标签的名字都指向一个小程序，嗯，这个是设计一下。
+![](images/2026-03-21-13-57-06.png)
+![](images/2026-03-21-13-57-45.png)就是这个标签这边的话，小程序这里把那个 ID 也放上去，然后这里的话，那个类型这边的那个下拉小倒三角选择项之后的这个小程序，这个页面不要变成透明的，看不清楚。然后把底下的这个地方标签的数字等一下，标签的数字去掉。北走。
+
+
+功能二：
+![](images/2026-03-21-14-16-48.png)这一那个链接能跟市这边的话，获客详情这里要去重去掉全局的这个去重去掉，然后来源，获客的来源在什么地方？过来的以及时间要及时的刷新，多个客户添加的状态也要写清楚，这个是这个链接接农耕式的一个获客来源的这么一个功能。
+
+功能三：
+![](images/2026-03-21-14-18-05.png)然后存这个编辑人物里面的这个获客计划是有问题的，这个获客计划这个已经有多项了，并且是停用状态。然后这里的话标签显示，应该是显示这个获客计划，不是显示密钥。这个要写清楚。然后这个允许家人的时段默认是6点到晚上二十点，晚上22.00。讲完了，一起那个手机的下载密码
+
+功能四：获客计划
+![](images/2026-03-21-14-19-16.png)然后选择设备这一块的话，是需要一个多一个全选，以及这个设备的那个状态在这个页面要写清楚，然后找存课宝。
+![](images/2026-03-21-14-19-58.png)然后这里添加进去的名字就是这个人备注的名字，就这个手机号，加上这一个人是点击了哪一个事件来的那点击这加起来的整个不要超过10，那个后面的字不要超过6个字，手机号加后面的那个字，路口的标签的路口的字不要超过6个字，然后标签是下拉型的。这一个标签，这上面的统一的找一下。
+
+功能五：@ # 功能修改
+![](images/2026-03-21-14-20-47.png)然后这个标签，标签下面的话是这个标签会自动回车空格一行，帮我看一下是什么情况，帮它正常应该是那个横着的标签跟那个井号也都是一样，还有下面那个图标得改一下。这个图标现在是绿色的图标，应该是一个分享的图标。
+
+功能六：
+![](images/2026-03-21-14-21-10.png)
+个 API 的接口的页面统一只有一个入口，不要搞成几个入口。API 的接口，这个 API 也要能让我去获得这个相应的那个 API 的并且这个 API 的结文档是有个对外可以让 AI 调取的一个链接的。
+
+
+功能七：小程序分享
+![](images/2026-03-21-14-29-58.png)![](images/2026-03-21-14-30-08.png)
+![](images/2026-03-21-14-31-45.png)能发到朋友圈的，把小程序链接发到朋友圈的这一个链接，点击进去的时候，那个。那个点击进去的之后，这一个链接里面显示的这个内容。链接显示的内容。不是百分之。那个登录后应该是跟这个显，不是显示登录后继续阅读这一个的话，应该是选这个，应该是那个付款的那个链接，并且直接跳出付款的链接出来，字节跳出付款的链接出来。好字节跳出这个付款的链接，而不是登录，就跟我们这个程序上面看着20%百分比，跟咱们程序设置的是一样的，看到100%分之比，相应的百分之比进来，然后他点击完之后就直接跳转到小程序上面，然后第二个的话，这个这边分享的右下角小分享的这个按钮也是一样。也是一样，点击完之后就直接可以复制并且分享到朋友圈。他这个是直接登录并且付款，直接跳出付款的这么一个功能。然后尽可能的帮我解决并完善嗯的小程序，分享付款的朋友圈的这一部分的功能。并且今最后调试一下，不要出错了
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260321内容功能3.md b/开发文档/1、需求/已完成/20260321内容功能3.md
new file mode 100644
index 00000000..70251a0b
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321内容功能3.md
@@ -0,0 +1,23 @@
+
+
+功能一：![](images/2026-03-21-20-12-26.png)
+一定要被修改，然后这边选择的话是可以选择，并且那个编辑的这边主要选择的那个计划是纯克宝的 API 的计划，并且这里停用是可以直接编辑的，然后这个名字这边的这个纯克宝 API 获客的这个名字不是密钥，是显示是那个计划的真实死的一个名字。那家人是端尿得改清楚。
+
+![](images/2026-03-21-20-13-07.png)那这边的话，那个链接。链接个人的话，这边会员 ID 自己就是一个点击的一个链接，没有说会员的 ID 去掉，然后点击蓝分或者点击考入这个是直接跳转到这个会弹出会员的会员页。哪个会来 d 去掉。
+
+![](images/2026-03-21-20-14-07.png)然后这里你写的不完整，就关联小程序这一块的话，它是合并到链接标签的这个里面，然后把关联小程序这里可以直接在这边点击这个标签的名字，就可以直接配置了，就可以直接配置的，然后把这个配置的东西放好。人机票签字在上方就可以直接配置这个关联的小程序以及别名。
+![](images/2026-03-21-20-16-36.png)三角的 API 接口，那个 API 接口去掉，统一在系统里面，然后这边的话这个热度，我新写的这一篇热度前为什么是显示为0？就测试一下这个排名的一个东西，然后测试一下排名相应的功能，那自动的置顶这个就按正常的算法就可以了，不要自动置顶。
+![](images/2026-03-21-20-17-09.png)然后这边的话，界面的话就需要增加一个百分可预览的单独设置的一个百分比。
+
+![](images/2026-03-21-20-18-22.png)那个检测一下这个章节里面的这个自动解析的功能，艾特它就自动那个有存在后台有存在，那个我们的自动解在 IS 的 AI 的链接人和事的这一个地方，如果它的列表有出现这个规则，列表有出现就直接自动解析，并且解析的这个名字不要有空，不要有回车驱逐黑车。包括这个链接也是一样。
+
+
+另外一方面的话，这里的编辑跟图片跟附件，还有视频编辑，图片和视，附件和视频，这些都是可以都需要自动上传到 OS，都是保存在 OSS 里面。i always s 链接，特别是 API，咱们 API 上传的时候也是自动的去，嗯，插入到指定的那个文章的位置，不管图片附件还是视频都是一样，都是可以直接插入。
+
+
+![](images/2026-03-21-20-20-16.png)然后这里的话，这边这一个小节移动无效，拖拉的时候移动无效，不能自动排序，帮我检查并写修复这一个这一问题。
+
+
+![](images/2026-03-21-20-21-09.png)
+![](images/2026-03-21-20-22-04.png)
+然后这一个的话最多就显示那个6个，这边显示的话是应该是按文章这一章节是可以做排序的，多多一个排序功能，它是按文章的倒叙来排序，那最多的话是显示那个显示。那个五个小节倒叙应该是100，现在是，应该是129场，这种是排前面的倒叙倒着来，然后在小程序上面的话显示的话是那个。显示的话就是。这里5个小节，在小程序这边显示5个小节。那其他要看更多的，就要需要有一点一下这个下拉的往下看的那一个标签，往下看的一个标签，这个是展开之后的一个一个东西，然后已解锁这一个，那个换成一个图标，不要三个字，一个简洁一点的图标，这小程序上面的他这么一个功能。然后这里的话，页面的那个位置跟那个后台的这个位置得保持是排版，是顺序是一样的
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260321找伙伴1.md b/开发文档/1、需求/已完成/20260321找伙伴1.md
new file mode 100644
index 00000000..8e52831e
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321找伙伴1.md
@@ -0,0 +1,31 @@
+
+
+功能一：推广中心
+![](images/2026-03-21-14-59-39.png)这个推广中心的整个界面的话，那个有需求的所有的整个界面加那个和有重复在手数据概览跟其他板块重复统计的数据标签就去掉，留到整一夜的数据检显示里面，特别是绑定的那个管理的数据，详细的绑定关系的数据这一块。
+![](images/2026-03-21-15-03-30.png)那个推广中心这边推广设置跟咱们那个系统，是系统设置里面的那个的推广相关的，和那个分享相关的功能也同一套，这个推广的这个设置里面。然后这个代付请求跟咱们这个订单管理合并，把代付请求合并到订单管理里面。然后这个整个的这个推广设置的整个的界面再做一下优化。
+
+
+功能二：找伙伴优化
+![](images/2026-03-21-15-01-31.png)找伙伴这里的这个功能。找伙伴这里的功能，就这边的话，这个标签是可以直接改完之后，小程序这边的话要相应的去改掉它的名字，那导师预约里面的话，相应的这个小程序里面的导师预约功能，这个功能需要去做一个整理，包括整个的一个获客的一，整个的一个优化迭代界面变得更简洁一些。更清晰一些，那深度的去优化一下找伙伴的这一个功能页。
+
+![](images/2026-03-21-15-02-16.png)这边导师管理和其他的导师的管理，这边的话姓名这些一定是要在我们的那个会员的用户的管理里面有出现的，并且能直接跳转上去，导师的相应的资料就要放到这个里面，然后包括相应的配置统一都是用到会员管理里面。然后团队配置这边的话也跟存克宝那边是直接打通的。
+
+
+数据概览
+![](images/2026-03-21-15-04-47.png)首页列表底下的这个分类标签统计，这里就统一的，这个是在做数据开展，旁边做一个标签页，一个数据概览的飘屏，旁边多一个用户标签，点击统计的一个标签页。然后咱们这里的话还有一个。这边是5个。5个选项。就是5个标签，这个是自动化的，不要超过5个标签，然后3把30秒自动更新，这个规则也去掉。
+
+
+![](images/2026-03-21-15-07-25.png)然后咱们把这个链接人跟事这边的几个东西，就是一个。就是一个这个到跳转的这个内容去掉，然后这个获客数里面的这个获客数显示的里面要去重掉，然后 a 的指定的人这一个这个标签是跟咱们的会员用户是要相匹配的。就这几个的功能要修改一下，然后跟乘客把捆绑清楚，那整个这一个包括这个编辑点击进去的列页，帮我详细的测试一下所有的功能，前端、后端以及数据库。
+
+![](images/2026-03-21-15-08-05.png)继续优化这个分类标签统计的这一个功能
+![](images/2026-03-21-15-09-12.png)提到的那些超级个体的这一些点击，超级个体的需要有个点击的多少次？然后以及这个超级个体谁在看？谁在点击，点记录下来，从点击它获客，这个是超级个体的列表，这边从点击它有多少人点击多少人获客，以及他的在首页上的排序这一方面都得写清楚，把这个超级个体的。
+
+---
+
+**落地记录（持续补全）**
+
+- 推广中心：代付已并入「订单与代付」子 Tab；`?tab=settings` 可深链到推广设置；与系统设置「推广功能」开关文案互链。
+- 数据概览：超级个体统计含点击、独立访客、**获客(去重)**（依赖 `persons.user_id` 绑定）。
+- 链接人与事：`/api/db/persons` 支持 `userId` 绑定/解绑；内容中心列表展示会员 ID 并可跳转用户管理。
+- 规则：Soul 仓库 `.cursor/rules/soul-karuo-dialogue.mdc` + `soul-project-boundary.mdc`；卡若 `karuo-ai.mdc` 已写 Soul 子项目对齐复盘。
+- **未自动化项**：小程序首页超级个体排序规则、导师预约全量改版、团队配置与存客宝深度打通等需产品定规则后再迭代。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260321推广功能1.md b/开发文档/1、需求/已完成/20260321推广功能1.md
new file mode 100644
index 00000000..175b62d1
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321推广功能1.md
@@ -0,0 +1,37 @@
+
+
+
+功能一：
+![](images/2026-03-21-20-32-46.png)
+首页的这个推荐页的排序。推荐首页的推排序一定是以推荐的那个算法为准的，这里的话是连续这个最新推荐的这一个是那个当天的排序比较高，最高的这一个是放在这边，以当天的为主。
+![](images/2026-03-21-20-32-38.png)那个精选推荐的话，也是按照那个。按那个有置顶的一个排序，那最新新增这边显示的就是那个最新的，那个最新发布的为主，他就不计入算法，在这个最新更新新的里面就不计入算法了。
+
+
+功能二：我的功能
+![](images/2026-03-21-20-34-39.png)这个阅读统计这一块名字改一下，分别把这个我的代父跟这个我的订单那个移到这个地方，还是以这个标记移到这个地方，把以阅读章节跟阅读分钟去掉，换成这两个我的订单跟我的待付。
+
+
+功能三：会员权益
+![](images/2026-03-21-20-36-42.png)这个会员。会员权益是可以直接会员权益，那个可以。那个。会员权利做一下排序，要像创业派对的，就派对的权利，创业老板排行是第二个，匹配创业伙伴第一个，然后。那个。置顶，轮流置顶的权利。嗯，获客轮流置顶，这个是获客的那个权利，然后还有一个。那个。会员权利这边有一个赚钱的那个案例库。赚钱的案例库，然后还有一个那个。灰机药跟智能机要重复了，这个去掉一个，全部都是变成那个，每日总结。
+然后再补齐，最后再左边的那个会员权利，看看我们后台对会员，VIP 会员最佳的一个形式，也给我一个会员权利的保持，有四个，然后文字的话都是统一四个文字，四个字。
+
+功能四：超级个体界面调整
+![](images/2026-03-21-20-39-10.png)然后这个整个的这个超级个体的这个版面的话，是变成就一页，弄成一页就可以了，弄成一夜就可以了，然后把下面成为超级个体去掉，把这个一夜变成高级一点，整夜变成高级一点，特别基本信息等等，这一些变成那个方便是尽可能的高级以及方便。以及需求，这个需求放到，也把位置整个布局帮我改一下。优化一下这整个的布局，让我看起来能快速的链接这一个和匹配这一个人，那底下这个成为超级个体，变成。编程是那个。匹配，超级个体匹配，早就变成找伙伴了，这么一个找更多伙伴，那怎么一个程维超级个体？那超级个体旁边还有一个找更多伙伴，那把这个，这两个标签把它变得那个不要那么凸显，两个就横排的样式改一下，不要那么凸显。
+让这个页面紧凑一些，然后信息优化格式清晰、高级，让大家让那个看了是会有感觉这些付款的感觉。然后这边的话。好，点击是这个，嗯，联系方式点击展开，按照设计好的规则做数量限制。
+
+功能五：![](images/2026-03-21-20-41-32.png)
+![](images/2026-03-21-20-42-03.png)
+![](images/2026-03-21-20-43-21.png)然后这个分推广的过程当中，就是检查一下这个推广捆绑的链接，就是我发出去推推广之后，我发出去链接推广之后就需要跟我捆绑关系，但现在这个捆绑关系，对，特别是朋友圈这一块，我分享完之后分享到朋友圈里是需要捆绑关系的。比如这个7月的这个用户就需要捆绑跟卡洛捆绑囊，并且这个付了代付的6元的时候，发出去的代付6元的这一个代付的链接发出去之后也是要捆绑关系的，就捆绑到卡洛的这个关系下面。就绑定关系的一个管理。那这边绑定关系的管理，然后这里的话，那个绑定整个的是数据开来，第一，然后绑定管理，第二绑定管理就是看到了。那就是谁绑定的这个用户，确保这个是生效的，所有的小程序上发出去的链接的捆绑关系都是都必须生效以及捆绑关系的，所有的收益，捆绑关系的这个人的收益都得生效，确定好，包括检查清楚被捆绑的这一块的收益，像今天考录发出去的。有多少人点击这个卡路的这个绑定的这一个，点击它的文章的测试次数，得有一个看得到的地方。
+
+
+功能六 点击
+![](images/2026-03-21-20-45-12.png)然后这个推广中心主要的所有的都是跟点击转化相关，那这个界面再帮我做的那个简洁有效一些，然后把这个单粉产值计算清楚，就是多少，第一个是多少点击，然后第二个把那个独立用户跟人均点击去掉，就是第一个有多少人点击，第二个有多少的。的用户，第三个的话有多少个的？那个绑定关系绑定处罚关机关系，绑定第四个的话有多少的付款转化？推广相关的付款转化。然后把那个今日时时跟本月跟累计这三个捆绑，这三个统一成一个放到一起。然后这个每篇文章今日点击这一个去掉。
+
+![](images/2026-03-21-20-45-52.png)然后把全局这里绑定管理这边的话，分销商那个这一页面做一个优化，以你对整个项目的理解做一个优化，包括整个推广中心都做一个全面的一个优化。你先理解整个项目前端、后端管理端整体的做一个优化。
+
+
+![](images/2026-03-21-20-46-57.png)
+![](images/2026-03-21-20-47-22.png)找伙伴功能也做一个深度的一个优化。老婆，哥哥，我想资源对接和导师预约，在小程序上导师的一个预约和一个界面。进行一个管理，然后这个导师预约的这一个导师管理这边的话。导师管理这里的话，不要不是点击跳转，我们没有任何跳转的行为，点击就是到导师的这个里面地方，然后这个导师如果是导师的话，就新增一个标签，把导师这个那个是导师的相关的资料也写到这个姓名标签里面，这个用户的标签里面。
+
+![](images/2026-03-21-20-47-34.png)
+方面的几点几分点击这个都要做一些优化跟去重。然后那个点击的能看到的这个匹配到谁发起的人，他匹配到谁，谁是整个页面的清晰，根据整个项目帮我做一下优化迭代
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260321用户管理.md b/开发文档/1、需求/已完成/20260321用户管理.md
new file mode 100644
index 00000000..bd267720
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260321用户管理.md
@@ -0,0 +1,7 @@
+
+
+
+
+功能一：
+![](images/2026-03-15-23-04-54.png)这里话是可以选择密钥，是选择存克宝。密钥同时是选择纯科宝的上面这个 API 获客的那个场景获客的计划，并且这个场景符合计划，可以搜索的，可以直接选择是哪个计划，选择完之后可以调用相应的参数直接覆盖掉，再存个把，那这里都快修复，存克宝密钥，这个直接关掉删除。不要这个按钮。
+![](images/2026-03-15-23-05-29.png)你可以调用存克宝的接口，里面调用相应的那个计划，然后直接可以选择下拉框，可以选择匹配，嗯，也可以直接新建。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260323用户功能1.md b/开发文档/1、需求/已完成/20260323用户功能1.md
new file mode 100644
index 00000000..5cfb963a
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260323用户功能1.md
@@ -0,0 +1,27 @@
+
+
+## 落地说明（2026-03-23 续）
+
+- 首页超级个体右侧「获客入口」已移除（`index.wxml` / `index.js`）。
+- 无头像超级个体：后端展示筛选放宽（`vip.go`），配合既有 MBTI 映射头像与后台 `mbti_avatars` 配置。
+- 我的页：名片/VIP 按钮移至阅读/推荐/匹配/收益统计行下方，避免遮挡；推荐好友数以绑定后的 `earnings.referralCount` 为准。
+- 目录折叠、书名后台、审核模式隐藏等：沿用既有 `chapters.js` + 系统设置 `mpUi` / `features`（本轮未改逻辑则保持现状）。
+
+---
+
+功能一：头像功能
+![](images/2026-03-23-17-51-54.png)
+程序上面那个修改这个的自己，我的页面修改的这个，我的名片的这一个功能。对，放下面联系，不然在小程序里面被挡住了，那修改不了。
+
+
+![](images/2026-03-23-17-53-17.png)拿首页这边的那个超级个体的这一个，那个地方获客入口去掉，首页获客入口去掉，然后这个超级个体的头像用 MBTI16种性格，那个符合这16种性格的那个头像重新以这个风格重新生成一组，这一组的话是当那个我冷随机填写，如果有填写性格的话。自动把没有头像的就自动切换成相应的头像这一组头像的这么一个功能，这个在后台也是可以配置的头像组。你个头像组的话，咱们在后台有个配置的地方
+
+![](images/2026-03-23-17-54-27.png)然后这个钱那个目录里面这一些图标显示。那一个的话是。图标显示的话是跟后台的图标显示是一致的，而不是12345这个图标显示，然后第二个的话就是那个点击，可以那个点击一场 soul 的创业实验这本书的这个名字点击一下是可以把这些全部的折叠起来的，除了2026每日派对干货这个不折叠。其他都是可以折叠起来的。
+扩这个一长寿的创业实验场，这个名字也是可以修改的，在后台咱们可以管理，后台可以直接修改
+
+
+![](images/2026-03-23-17-57-25.png)有推荐的同时检测一下我的里面的那个推荐好友应该是正常绑定的数，已经跟捆绑的才是推荐好友，然后也检查一下这个绑定的那个机制，绑定完之后才是有推荐好友这个功能，才会显示的是真实的那个推荐好友。
+
+然后后台的话，小程序这边的功能模块都是可以被隐藏跟操作的，在后台系统设置里面，在小程序的这些整个的所有的页面的功能模块都是可以被隐藏跟操作的，把这个设置清楚，然后那个。为了过检测，把能隐藏的那个，过那个审核，把能隐藏的也都隐藏一下。能隐藏进，打开审核模式，能隐藏的也都隐藏一下
+
+https://open.feishu.cn/open-apis/bot/v2/hook/c558df98-e13a-419f-a3c0-7e428d15f494完成之后已复盘的格式以后都是以复盘的格式发到整体，完成之后以复盘的格式发到这个售的。霸道 soul 的那个。的这个群里面，开发群里面，并且要绑定这个开发的功能。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260323用户功能2.md b/开发文档/1、需求/已完成/20260323用户功能2.md
new file mode 100644
index 00000000..971dc7ad
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260323用户功能2.md
@@ -0,0 +1,22 @@
+
+
+## 落地说明（2026-03-23 续）
+
+- 编辑资料主路径：我的页点击昵称 → `profile-show` → 右上角编辑进入 `profile-edit`（减少与名片流割裂）。
+- 用户详情：头部与 Tab「用户信息」去重；行为轨迹展示中文动作 + `moduleLabel`（位置）；长串 target 默认不展示。
+- 规则配置列表：完整描述仍在 `<details>` 内，列表行仅显示字数提示，避免整段摊开。
+- 超级个体点击 Webhook：同一用户自然日留资 webhook 仍只推首条（`ckb.go` `webhookShouldSkip`）。
+
+---
+
+功能0，继续完成
+![](images/2026-03-23-18-13-16.png)把这个编辑资料和名片，这个是要在这个名片里面显示这个，这一个框是在名片里面的编辑里面去显示，直接就可以编辑，这边就不显示了。然后，嗯，接下来的话全亮去开发。群亮区开发那个整个所有的那个功能，然后最后给我反馈的那个是飞书的好看一点，那个屏那个名片的一个复盘格式。
+
+功能一：用户详情
+![](images/2026-03-23-18-06-39.png)
+整个的用户详情页要跟前端的那个互相匹配，把整个用户详情页做一个位置的一个重构。但他把去除重复，然后把位置变得更合理，重把基础设施跟用户资料完善这两个合并起来，然后把整个的那个布局变得更清晰，不要重复的太多，基础信息里面太长太多了，这个把它那个做一些清晰一点的那个。可以清晰一点的那个结构帮我重新设计一下
+
+![](images/2026-03-23-18-07-51.png)用户详情里面的那个全站的那个行为轨迹这边应该显示的是英文，这边要显示的是中文的一个位置的一个具体的显示中文的位置。然后同时这个中文的这个位置也是用户旅程的这个位置，也是要发到那个，到时候发到群里面也是按这个用户旅程的位置来操作。然后同一时间这个用户点击了某一个超级个体链接的时候，一天只能链接一个推送到群里面去，推送一次，一个不要推送太多次了，推送到 Webhook 上只能一次
+
+功能二：配置文件
+![](images/2026-03-23-18-10-33.png)测一下用户管理的整个网站的所有的那个规则配置，要把规则配置完善一下，包括规则配置里面的相应的那个点击的配置的那个内容，然后把整个的规则配置设置的更清晰一些。能描述文字不直接显示出来，
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260324内容管理1.md b/开发文档/1、需求/已完成/20260324内容管理1.md
new file mode 100644
index 00000000..6cd52569
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260324内容管理1.md
@@ -0,0 +1,10 @@
+
+
+
+功能一：![](images/2026-03-24-00-32-22.png)
+后台有心购买章节的用户也推到 wepop 里面了，并且备注好购买的哪个章节的一个行为，然后第二个的话绑定信息这里的话，嗯，这个链接重复了，只要显示一个就可以了。然后那个默认头像底下这个默认头像还提着这个也去掉。这个不要。
+
+
+![](images/2026-03-24-00-33-23.png)
+这个 mBTI 的头像库里面的所有的头像，所有的头像都用 AI 帮我生成这16个性格的头像，要跟他的那个性格是匹配的。分别是 it 这个冷面军师，这个底下这个 HTTP 等于什么？这个链接去掉。链接去掉这个，直接用 AI 来生成。这个生成的，你来直接来用 AI 生成好，放在这个上面，生成了这个头像要跟性格是一样的。向里面的 NTZ 指老头 NTP 是叫药水姐。Entz。大姐头 ENTP。i am f z 绿老头 and FP 小蝴蝶 even if 大保健去搜索一下这一组词，应该是叫这一组词第二个这一个，而不是像这个，你生成图片之后要写上这一这一个，这一这个词语用词还是要注意一下的。
+
diff --git a/开发文档/1、需求/已完成/20260406用户管理-超级个体重构.md b/开发文档/1、需求/已完成/20260406用户管理-超级个体重构.md
new file mode 100644
index 00000000..49c0cfdf
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260406用户管理-超级个体重构.md
@@ -0,0 +1,30 @@
+
+
+> **承接**：`-4` 已归档 `已完成/用户管理 20260406-2.plan.md`。  
+> 有下一批网关/观测需求时在此表排期；无则保持空模板。
+
+---
+
+## 待排期
+
+| 项 | 状态 | 说明 |
+|:---|:---|:---|
+![](images/2026-04-06-09-33-10.png)这个应，这个要更新一个 go购买的，购买状态的用户旅程的一个模块，用户旅程的模块放到里面，比如他购买的任何，包括我们新增的任何的那个收费项目，都要显示在这个购买的状态里面，那我知道所有的那个购买的人的那个收益，清晰的知道他的那个收益。
+
+功能二：
+/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/static
+
+用户的头像，用户的这个头像，NBTI 默认用这16个头像的，NBTI 默认就用这16个头像，直接就可以在后台是可以直接选择这个头像，没有，如果没有设置性格的话，就有设置性格就匹配性格，没有设置性格的话是随机选一张图片，男男的女的都可以。是可以选男版，可以选女版，分开把这个头像做优化迭代，然后把所有的这些会员，没有头像的会员全部设置一下
+
+功能三：
+![](images/2026-04-06-10-31-25.png)这个 BTI 的这个头像两版根据那个男的女的自由的去分配，有选择男的女的在，可以只有这两个版本，其他的版本全部删掉，那男的女的版本，然后确保它是显示可以显示出来，那我把那个 SVG 的格式改成那个 PNG 的格式。那把这个 NBT 这个头像库，这一个简洁一点的，弄得简洁一点，现在看稿件有点太复杂了，弄得简洁一些。
+![](images/2026-04-06-10-31-58.png)然后把用户，那个用户的里面去随机匹配用户列表，随机匹配，把这个没有的头像的这一些用户没有头像的随机匹配掉，然后购买状态这边要跟咱们有付款行为的都可以都要显示在这个购买状态里面，最近一次购买只显示这一个，不要显示未购买的状态。目标是确保有相应的那个头像和人设
+
+功能四：迁移
+![](images/2026-04-06-10-32-42.png)然后这个获客列表。霍克利，表帮我放到那个推广中心里面，并且整个页面重构的剪辑一些。
+
+功能五：
+![](images/2026-04-06-10-34-23.png)那个超级个体的一些那个获客情况跟那个超级个体的这个获客情况。在这个我的里面找一个比较一个不那么显眼的一个地方的页面，帮我做一个那个超级个体的一个获客情况，以及它的一个热度。这怎么一个界面在上面的一个功能？
+
+![](images/2026-04-06-10-37-33.png)
+![](images/2026-04-06-10-37-52.png)然后根据这整个的这个用户旅程总览这边的话，根据这整个的那个用户列表和这个用户目的是让我能清楚的知道所有的这个用户哪一个流量池好过什么用户流旅程哪个流量池，然后的整个用户的一个关系，目的是让我知道这一些客户的一个具体的一些详细的一个情况。然后以及表格行为表格一个分析，然后这些分析触发，最终得到这个用户估值的一整个分析的一个解决方案，然后通过用户里程来进行各个板块的分析，然后这个把这整个的用户里程的界面帮我做一些，做一下那个重构。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/20260406用户管理-首页入口融合.md b/开发文档/1、需求/已完成/20260406用户管理-首页入口融合.md
new file mode 100644
index 00000000..6bf3af39
--- /dev/null
+++ b/开发文档/1、需求/已完成/20260406用户管理-首页入口融合.md
@@ -0,0 +1,25 @@
+
+
+> **承接**：`-4` 已归档 `已完成/用户管理 20260406-2.plan.md`。  
+> 有下一批网关/观测需求时在此表排期；无则保持空模板。
+
+---
+
+## 待排期
+
+| 项 | 状态 | 说明 |
+|:---|:---|:---|
+功能一：
+
+这首夜路口默认的位置，这个。这个直接是要并到那个超级个体的那个目录底下的，直接就是并到超级个体的那个目录底下。超级的直接就是变成超级个体的，指定的超级个体的配置里面。而不是独立一项去做选择，就每一个超级个体都可以像做小检选择，然后把整个页面那个重构一下，简洁一点![](images/2026-04-06-04-17-32.png)
+然后这里首页的入口默认这个，就不要选这一个目录，就直接合并到这里，就不要再显示了。
+配置简洁一些，配置界面简洁一些，不要搞得这么复杂
+
+
+功能二：
+![](images/2026-04-06-05-53-15.png)这个搜索会员用户没有搜索到有问题，并不精确。嗯，搜索这个名字并不精确，没有搜索到，帮我处理一下这个问题，并且详细检查一下一系列的相关的可能出现的一个问题的一个处理。
+![](images/2026-04-06-05-54-12.png)然后这个超级，这个点击这边不精确点击，就是实际的点击，现在不可能只点击都放到这个流光底下的，其他的那个点击的情况你看一下到底是什么，什么什么情况，帮我修复一下这个点击的一个问题。点击了一个相关的问题。帮你，帮我处理一下。脑以及存克宝相关的这个配置。
+
+![](images/2026-04-06-05-55-07.png)然后还有一点的话，就是这个点，那个获客这里的话要需要和纯客保那边的获客是那个那协同的纯科宝那边具体的那个获客的数据就这里要能点击并获客，这里要可以点击展开。然后并且这个成员这里的话，也是需要能直接点击就打开这个会员的那个用户的相关的那个数据，这个需要跟那个前端的用户页，用户管理里面实际的那个用户是捆绑关系，超级个体也是归属于用户的用户列表里面的一种。
+
+![](images/2026-04-06-05-55-49.png)然后这个功能完善之后，在咱们的那个小程序这里要反映过来，小程序这边的话能直接显示并且配置清楚那个所有的点击的这个功能可以直接展开，包括超级个体里面的话。这个功能每个超级个体点点击上去的话，配置好都是可以使用这个的功能的。
\ No newline at end of file
diff --git a/开发文档/1、需求/已完成/README_需求文档格式说明.md b/开发文档/1、需求/已完成/README_需求文档格式说明.md
new file mode 100644
index 00000000..f403efe0
--- /dev/null
+++ b/开发文档/1、需求/已完成/README_需求文档格式说明.md
@@ -0,0 +1,75 @@
+# 需求文档格式说明
+
+> 本目录支持 **Markdown（.md）** 格式，可在 Cursor 中直接粘贴图片并预览。
+
+---
+
+## 为什么用 Markdown
+
+| 能力       | 说明                                             |
+|:-----------|:-------------------------------------------------|
+| 粘贴图片   | 配合扩展可 Ctrl+V / Cmd+V 直接粘贴剪贴板图片      |
+| 预览       | Cursor 内置 Markdown 预览，`Cmd+Shift+V` 即可    |
+| 版本管理   | 纯文本 + 图片文件，方便 Git 追踪                  |
+| 跨平台     | 任意编辑器可编辑，导出 PDF/HTML 也方便           |
+
+---
+
+## 使用方法
+
+### 1. 新建文档
+
+- 复制 `_模板_需求文档.md`，重命名为你的文档名（如 `20260308找伙伴功能.md`）
+- 或直接新建 `.md` 文件
+
+### 2. 粘贴图片
+
+**方式一：配合扩展（推荐）**
+
+1. 在 Cursor 中安装扩展：`Paste Image` 或 `Markdown Paste`
+2. 截屏或复制图片到剪贴板
+3. 在 `.md` 文件中按 `Ctrl+V`（Mac：`Cmd+V`）
+4. 扩展会自动将图片保存到 `images/` 并插入 `![描述](images/xxx.png)`
+
+**方式二：手动**
+
+1. 将图片放入本目录下的 `images/` 文件夹
+2. 在文档中插入：`![图片描述](./images/文件名.png)`
+
+### 3. 预览
+
+- **快捷键**：`Cmd+Shift+V`（Mac）或 `Ctrl+Shift+V`（Windows）
+- **右键**：编辑器内右键 → 「Open Preview」
+- 卡若AI 规则已配置 Markdown Preview Enhanced，可直接查看排版
+
+---
+
+## 目录约定
+
+```
+修改/
+├── README_需求文档格式说明.md   ← 本说明
+├── _模板_需求文档.md            ← 可复制的模板
+├── images/                      ← 粘贴的图片存放于此
+│   └── .gitkeep
+├── 20260308找伙伴功能.md        ← 你的需求文档
+└── *.pdf / *.pages              ← 仍可保留原格式作归档
+```
+
+---
+
+## 扩展安装（如需粘贴图片）
+
+在 Cursor 扩展市场搜索并安装其一：
+
+- **Paste Image**：`naumovs.paste-image`
+- **Markdown Paste**：支持粘贴图片并生成 Markdown 引用
+
+**Paste Image 路径配置**（可选）：在 `settings.json` 中添加，使图片保存到当前目录的 `images/` 下：
+
+```json
+{
+  "pasteImage.path": "${currentFileDir}/images",
+  "pasteImage.basePath": "${currentFileDir}"
+}
+```
diff --git a/开发文档/1、需求/已完成/images/2026-03-18-18-54-25.png b/开发文档/1、需求/已完成/images/2026-03-18-18-54-25.png
new file mode 100644
index 00000000..ab0bc882
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-18-18-54-25.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-12-59-45.png b/开发文档/1、需求/已完成/images/2026-03-21-12-59-45.png
new file mode 100644
index 00000000..037b2b75
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-12-59-45.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-00-50.png b/开发文档/1、需求/已完成/images/2026-03-21-13-00-50.png
new file mode 100644
index 00000000..9f84a7c9
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-00-50.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-02-36.png b/开发文档/1、需求/已完成/images/2026-03-21-13-02-36.png
new file mode 100644
index 00000000..625d1a9a
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-02-36.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-07-12.png b/开发文档/1、需求/已完成/images/2026-03-21-13-07-12.png
new file mode 100644
index 00000000..bcc5c8bf
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-07-12.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-08-21.png b/开发文档/1、需求/已完成/images/2026-03-21-13-08-21.png
new file mode 100644
index 00000000..25b84654
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-08-21.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-09-43.png b/开发文档/1、需求/已完成/images/2026-03-21-13-09-43.png
new file mode 100644
index 00000000..0961b971
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-09-43.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-09-55.png b/开发文档/1、需求/已完成/images/2026-03-21-13-09-55.png
new file mode 100644
index 00000000..eb6f1985
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-09-55.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-11-37.png b/开发文档/1、需求/已完成/images/2026-03-21-13-11-37.png
new file mode 100644
index 00000000..8d765f28
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-11-37.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-12-31.png b/开发文档/1、需求/已完成/images/2026-03-21-13-12-31.png
new file mode 100644
index 00000000..83129737
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-12-31.png differ
diff --git a/开发文档/1、需求/已完成/images/2026-03-21-13-13-22.png b/开发文档/1、需求/已完成/images/2026-03-21-13-13-22.png
new file mode 100644
index 00000000..ad9f0553
Binary files /dev/null and b/开发文档/1、需求/已完成/images/2026-03-21-13-13-22.png differ
diff --git a/开发文档/1、需求/索引.md b/开发文档/1、需求/索引.md
new file mode 100644
index 00000000..a85caff1
--- /dev/null
+++ b/开发文档/1、需求/索引.md
@@ -0,0 +1,25 @@
+# 1、需求 - 索引
+
+## 命名规则
+
+| 规则 | 说明 |
+|------|------|
+| **文件名** | `YYYY-MM-DD-需求.md` 或 `YYYY-MM-DD-简短描述.md` |
+| **主需求文件** | **日期最新的**需求文件为主，作为当前需求基准 |
+| **同步需求时** | 新建当日 `YYYY-MM-DD-需求.md` 或更新已有；更新本索引 |
+
+## 当前主需求文件
+
+**2026-03-20-需求.md**（日期最新）
+
+## 基准文档（常驻）
+
+| 文件 | 说明 |
+|------|------|
+| [以界面定需求](以界面定需求.md) | 界面级需求基准：小程序/管理端界面清单、主要接口、业务逻辑对齐 |
+
+## 归档
+
+| 目录 | 说明 |
+|------|------|
+| [archive/](archive/) | 专项需求、技术分析、已合并或过时文档 |
diff --git a/开发文档/1、需求/链接人与事-存客宝同步-需求规划.md b/开发文档/1、需求/链接人与事-存客宝同步-需求规划.md
new file mode 100644
index 00000000..5557b7c0
--- /dev/null
+++ b/开发文档/1、需求/链接人与事-存客宝同步-需求规划.md
@@ -0,0 +1,5 @@
+# 链接人与事 — 存客宝同步 需求规划
+
+> **正文已迁入归档**，避免与 `archive/` 双份维护。请以归档版为准（内容更完整，含同步需求汇总指引）。
+
+请阅读：**[archive/链接人与事-存客宝同步-需求规划.md](./archive/链接人与事-存客宝同步-需求规划.md)**
diff --git a/开发文档/1、需求/链接人与事-实现方案.md b/开发文档/1、需求/链接人与事-实现方案.md
new file mode 100644
index 00000000..c9a22364
--- /dev/null
+++ b/开发文档/1、需求/链接人与事-实现方案.md
@@ -0,0 +1,5 @@
+# 链接人与事 — 实现方案（综合分析）
+
+> **正文已迁入归档**。归档版本与代码迭代同步更及时（如列表字段、Dialog 交互等）。
+
+请阅读：**[archive/链接人与事-实现方案.md](./archive/链接人与事-实现方案.md)**
diff --git a/开发文档/1、需求/链接人与事-置顶与超级个体对应设计.md b/开发文档/1、需求/链接人与事-置顶与超级个体对应设计.md
new file mode 100644
index 00000000..a73871e1
--- /dev/null
+++ b/开发文档/1、需求/链接人与事-置顶与超级个体对应设计.md
@@ -0,0 +1,102 @@
+# 链接人与事 — @的人 与 超级个体 对应设计
+
+> 补充：置顶功能中「@的人」与「超级个体」的合理对应关系  
+> 创建日期：2026-03-20
+
+---
+
+## 一、现状与关系
+
+| 概念 | 数据来源 | 说明 |
+|------|----------|------|
+| **@的人** | `persons` 表 | 文章可 @ 提及，小程序点击可留资；有 token、name、user_id、ckb_api_key 等 |
+| **超级个体** | `users` + `orders` | 开通 VIP 的用户，首页「超级个体」横向滚动展示 |
+| **绑定关系** | `persons.user_id` | 超级个体开通后，`ensurePersonForUser` 自动创建 Person 并绑定 user_id |
+
+**已有逻辑**：
+- 超级个体开通成功 → 调用 `ensurePersonForUser(userId)` → 创建或复用 Person，`user_id` 指向该用户
+- Person.name 与 users.nickname 保持同步（ensurePersonForUser 会按 user_id 更新 name）
+- 手工在管理端添加的 Person 无 user_id（如卡若、南风等运营角色）
+
+---
+
+## 二、设计原则
+
+1. **一对一**：一个超级个体用户 ↔ 一个 @的人（Person），通过 `user_id` 唯一绑定
+2. **两种 Person 来源**：
+   - **超级个体**：有 `user_id`，开通时自动创建，昵称/头像随 users 表实时更新
+   - **手工添加**：无 `user_id`，运营在管理端手动创建，需在 Person 表维护 name、avatar
+3. **置顶候选**：两种 Person 都可被置顶，但**推荐置顶超级个体**（有 user_id），因头像/昵称无需额外维护
+
+---
+
+## 三、推荐设计方案
+
+### 3.1 头像与昵称来源（按 user_id 区分）
+
+| Person 类型 | nickname 来源 | avatar 来源 |
+|-------------|--------------|-------------|
+| 有 user_id（超级个体） | `users.nickname` | `users.avatar` |
+| 无 user_id（手工添加） | `persons.name` | `persons.avatar`（需新增字段） |
+
+**实现**：`GET /api/miniprogram/ckb/pinned-person` 返回时：
+- 若 Person 有 user_id → JOIN users 取 nickname、avatar（与「我的」页一致，用户可随时改）
+- 若无 user_id → 用 Person.name、Person.avatar
+
+### 3.2 置顶限制（两种策略）
+
+| 策略 | 说明 | 适用场景 |
+|------|------|----------|
+| **A：不限制** | 所有 Person 都可置顶 | 运营需要置顶「卡若」等非超级个体时 |
+| **B：仅超级个体** | 置顶时校验 `user_id` 非空 | 产品强约束「首页链接入口只能是超级个体」 |
+
+**推荐**：策略 A（不限制），管理端列表加「来源」列区分，运营按需选择。若产品后续要求「只能置顶超级个体」，再在 `PUT /api/db/persons/pin` 加校验即可。
+
+### 3.3 管理端展示增强
+
+| 改造 | 说明 |
+|------|------|
+| 列表加「来源」列 | 有 user_id 显示「超级个体」，无则显示「手工添加」 |
+| 置顶按钮 | 对所有 Person 开放；已置顶行显示「已置顶」标识 |
+| 超级个体行 | 可选展示「绑定用户」链接，便于运营跳转用户详情 |
+
+### 3.4 数据流示意
+
+```
+超级个体开通
+  → ensurePersonForUser(userId)
+  → 创建 Person(user_id=userId, name=nickname)
+  → 出现在「链接人与事」列表，来源=超级个体
+
+运营置顶该 Person
+  → pinned_person_token = token
+  → 小程序首页 GET pinned-person
+  → 有 user_id → JOIN users 取 nickname、avatar
+  → 展示「点击链接{昵称}」+ 头像
+```
+
+---
+
+## 四、与置顶功能技术分析的衔接
+
+| 原技术分析 | 本设计补充 |
+|------------|------------|
+| Person 表加 avatar 字段 | **仅对无 user_id 的 Person 必填**；有 user_id 时 avatar 来自 users，可不填 |
+| pinned-person 返回 nickname、avatar | **有 user_id 时从 users 表取**；无则从 Person 取 |
+| 管理端 PersonAddEditModal | 有 user_id 时 avatar 可只读展示（来自 users），或支持「同步用户头像」按钮 |
+
+---
+
+## 五、实施清单补充
+
+| 角色 | 补充任务 |
+|------|----------|
+| 后端 | pinned-person 接口：有 user_id 时 JOIN users 取 nickname、avatar；无则用 Person.name、Person.avatar |
+| 后端 | Person.avatar 仅对无 user_id 的 Person 必填（或管理端编辑时可选填） |
+| 管理端 | 列表加「来源」列：超级个体 / 手工添加 |
+| 产品 | 确认：置顶是否限制为「仅超级个体」；若否，保持当前设计 |
+
+---
+
+**创建时间**：2026-03-20  
+**关联**：`链接人与事-置顶功能-技术分析.md`（archive）
diff --git a/开发文档/1、需求/需求日志 b/开发文档/1、需求/需求日志
new file mode 100644
index 00000000..fb51815d
--- /dev/null
+++ b/开发文档/1、需求/需求日志
@@ -0,0 +1,9 @@
+20260223
+
+那个在我的里面，我的足迹里面最近阅读的这个章节要写清楚章节的那个名称，小杰的名称得写上去。然后这个。推广中心改成我的收益，然后把这个推广中心我的收益，然后上面显示的是我的收益有多少钱？把推广中心这一个我的收益改到这个界面，就名昵称的下方购买章节推荐函好友，然后那个带领收益，这个改成我的收益，然后把推广中心去掉，然后把账号设置。账号设置。也移到这个，我的那个资料的那个里面，这个界面上面。精选队推荐这边的话，首页上精选推荐，这里选择的是后端的那个文章的那个阅读量，文章的阅读量，然后把这个文章的相应的那个阅读做一个阅读的一个点击的一个记录，后台文章得有一个点击的一个记录。然后把手页里面的这个内容预览去掉，首页内容预览去掉，这个就是只有一个目录。只有一个目录，然后这边的话是一个那个。内容预览去掉，改成首页，上面改成那个有名字的，有填写名字的和联系方式的，是那个。创业老板排行，然后显示一排带头像、带图标、带名字的显示一排。四个显示一排是有名字跟图像，那后鼠标然后点击进去的话，就是它的一个详细材料，就优秀会员的一个板块。
+
+然后在一个主要就是他就是那个管理开发文档的用的，然后把整个那个开发文档直至保留这个10个目录。开发文档只有这4个目录，其他的文件文档就整合到这个10个目录底下，然后这个 skill 还需要整理的一个内容，就是把每一次我们对话提问的一个需求放到一个那个需求的表里面，那我知道每天这个更改的和我们对话的更改的那个季度的一个需求。把这个提示词对话的内容整理一下放到里面，那需要有具体的时间的节点往下去开发。
+
+在后台里面你新增一个会员的一个填写的一个表格，购买完之后会员的权利还可以被匹配，以及那个就一年365天的一个权利吗？然后这个365天的权利可以看所有的章节，然后可以有匹配所有的那些客户，我让别人能知道你的项目的一个业务情况。然后。这个就变成一个 VIP 的一个选项，也是在增加会员的话，就是头像就不一样，正常就是你的头像在我的里面，头像是灰色的，那会员 VIP 的一个框框是灰色的，那点击之后进去就是会变成那个 VIP 亮色的一个头像出来
+
+然后帮我把这一版那个。最终要实现这个小程序跟后端是匹配的，以及数据是匹配的一个情况，最终上传上去可以保证整个网站是可以正常使用，确保在正常使用的情况下来做优化和迭代。然后
\ No newline at end of file
diff --git a/开发文档/2、架构/Gin技术栈-Go1.25依赖清单.md b/开发文档/2、架构/Gin技术栈-Go1.25依赖清单.md
new file mode 100644
index 00000000..696456fc
--- /dev/null
+++ b/开发文档/2、架构/Gin技术栈-Go1.25依赖清单.md
@@ -0,0 +1,120 @@
+# Gin 技术栈依赖清单（适配 Go 1.25.7）
+
+**目标版本**：Go 1.25.7  
+**原则**：精简、高效、易上手、好用、安全；所有依赖均兼容 Go 1.25，无需更换或移除。
+
+---
+
+## 一、Go 版本说明
+
+- Go 1.25 于 2025 年 8 月发布，遵守 Go 1 兼容性承诺，现有主流库均可使用。
+- **Gin** 官方要求 Go 1.24+，1.25.7 满足要求。
+- **golang.org/x/\***（crypto、time 等）随 Go 工具链维护，支持当前稳定版。
+- 若某依赖未显式声明支持 1.25，只要其 `go.mod` 为 `go 1.21` 或更高，在 1.25 下均可正常编译使用。
+
+---
+
+## 二、依赖列表（均适配 Go 1.25.7）
+
+### 1. 核心与数据库
+
+| 依赖 | 版本建议 | 说明 |
+|------|----------|------|
+| `github.com/gin-gonic/gin` | 最新 v1.x | 要求 Go 1.24+，1.25.7 兼容。 |
+| `gorm.io/gorm` | 最新 v1.31.x | 无对高版本 Go 的限制。 |
+| `gorm.io/driver/mysql` | 最新 | 与 GORM 配套。 |
+
+### 2. 安全
+
+| 依赖 | 版本建议 | 说明 |
+|------|----------|------|
+| `github.com/unrolled/secure` | v1.17+ | 标准 net/http 中间件，兼容 Go 1.25。 |
+| `golang.org/x/crypto` | 最新 | 使用 `bcrypt` 等，随 Go 生态更新。 |
+| `golang.org/x/time` | 最新 | 使用 `rate` 限流，兼容 Go 1.25。 |
+
+### 3. 配置
+
+| 依赖 | 版本建议 | 说明 |
+|------|----------|------|
+| `github.com/joho/godotenv` | v1.5.x | 仅读 .env，无高版本 Go 要求。 |
+| 或 `github.com/caarlos0/env/v11` | v11.x | 解析 env 到结构体，兼容当前 Go。 |
+
+### 4. 跨域与鉴权
+
+| 依赖 | 版本建议 | 说明 |
+|------|----------|------|
+| `github.com/gin-contrib/cors` | v1.6+（务必 ≥1.6，修复 CVE） | 与 Gin 1.24+ / Go 1.25 兼容。 |
+| `github.com/golang-jwt/jwt/v5` | 最新 v5.x | 推荐 v5，与 Go 1.25 兼容。 |
+
+### 5. 接口文档（可选）
+
+| 依赖 | 版本建议 | 说明 |
+|------|----------|------|
+| `github.com/swaggo/swag/cmd/swag` | 最新（CLI 工具） | 代码生成，使用最新 CLI 即可。 |
+| `github.com/swaggo/gin-swagger` | 最新 | 与 Gin 配套。 |
+| `github.com/swaggo/files` | 最新 | Swagger UI 静态资源。 |
+
+### 6. 开发工具（仅开发环境）
+
+| 依赖 | 版本建议 | 说明 |
+|------|----------|------|
+| `github.com/cosmtrek/air` | 最新 | 热重载，与 Go 1.25 兼容。 |
+
+---
+
+## 三、无需更换或移除
+
+- 上述依赖在 Go 1.25.7 下**均无需更换或移除**。
+- 未列入的冗余依赖（如单独再引入 validator、Viper、zap 等）按此前「精简版」建议已不纳入，无需因 Go 1.25 再改。
+
+---
+
+## 四、推荐 go.mod 片段（Go 1.25）
+
+在项目根目录执行：
+
+```bash
+go mod init soul-server
+go mod edit -go=1.25
+```
+
+然后按需拉取依赖（示例）：
+
+```bash
+go get github.com/gin-gonic/gin
+go get gorm.io/gorm gorm.io/driver/mysql
+go get github.com/unrolled/secure
+go get golang.org/x/crypto golang.org/x/time
+go get github.com/gin-contrib/cors
+go get github.com/golang-jwt/jwt/v5
+go get github.com/joho/godotenv
+# 可选
+go get github.com/swaggo/gin-swagger github.com/swaggo/files
+# 开发
+go install github.com/cosmtrek/air@latest
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+
+---
+
+## 五、验证方式
+
+在 soul-server 目录下执行：
+
+```bash
+go mod tidy
+go build ./...
+```
+
+若通过，则当前依赖与 Go 1.25.7 兼容。若某库报错，优先升级该库至最新 minor/patch 再试。
+
+---
+
+## 六、小结
+
+| 项目 | 结论 |
+|------|------|
+| Go 1.25.7 | 支持，所有推荐依赖均适用。 |
+| 需要更换的依赖 | 无。 |
+| 需要移除的依赖 | 无（按本清单与精简原则已不包含不必要项）。 |
+| 建议 | 使用 `go 1.25`，定期 `go get -u ./...` 与 `go mod tidy` 保持依赖健康。 |
diff --git a/开发文档/2、架构/README.md b/开发文档/2、架构/README.md
new file mode 100644
index 00000000..0df9945f
--- /dev/null
+++ b/开发文档/2、架构/README.md
@@ -0,0 +1,21 @@
+# 2、架构
+
+> 描述 Soul 创业派对（小程序 + soul-admin + soul-api）的**系统边界、技术栈与业务链路**，不等同于接口细节（见 `5、接口`）或部署步骤（见 `8、部署`）。
+
+## 本目录文件
+
+| 文件 | 说明 |
+|------|------|
+| [系统与技术.md](./系统与技术.md) | 系统与技术总述 |
+| [soul-api技术栈.md](./soul-api技术栈.md) | 后端技术栈（Go/Gin/GORM 等） |
+| [链路与变现.md](./链路与变现.md) | 流量、付费与分销链路 |
+| [超级个体（用户模块方向）.md](./超级个体（用户模块方向）.md) | 超级个体与用户模块产品方向 |
+| [Gin技术栈-Go1.25依赖清单.md](./Gin技术栈-Go1.25依赖清单.md) | 依赖版本清单 |
+
+## 三端边界（摘要）
+
+- **小程序**：仅调用 `/api/miniprogram/*`（及少量与路由并行的公共配置，以代码 `router.go` 为准）。
+- **管理端 soul-admin**：`/api/admin/*`、`/api/db/*`。
+- **soul-api**：统一实现业务与鉴权；详见 [6、后端/后端开发规范.md](../6、后端/后端开发规范.md) 与仓库 `.cursor/skills/api-dev/SKILL.md`。
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/2、架构/soul-api技术栈.md b/开发文档/2、架构/soul-api技术栈.md
new file mode 100644
index 00000000..2a479f92
--- /dev/null
+++ b/开发文档/2、架构/soul-api技术栈.md
@@ -0,0 +1,54 @@
+# soul-api Go 技术栈
+
+## 语言与运行时
+
+- **Go 1.25**
+
+## Web 框架与 HTTP
+
+- **Gin**（`github.com/gin-gonic/gin`）：HTTP 路由与请求处理
+- **gin-contrib/cors**：跨域
+- **unrolled/secure**：安全头（HTTPS 重定向、HSTS 等，在 `middleware.Secure()` 中使用）
+
+## 数据层
+
+- **GORM**（`gorm.io/gorm`）：ORM
+- **GORM MySQL 驱动**（`gorm.io/driver/mysql`）：连接 MySQL
+- **go-sql-driver/mysql**：底层 MySQL 驱动（GORM 间接依赖）
+
+## 微信生态
+
+- **PowerWeChat**（`github.com/ArtisanCloud/PowerWeChat/v3`）：微信开放能力（小程序、支付、商家转账等）
+- **PowerLibs**（`github.com/ArtisanCloud/PowerLibs/v3`）：PowerWeChat 依赖
+
+## 配置与环境
+
+- **godotenv**（`github.com/joho/godotenv`）：从 `.env` 加载环境变量
+- 业务配置集中在 `internal/config`，通过 `config.Load()` 读取
+
+## 鉴权与安全
+
+- **golang-jwt/jwt/v5**：管理端 JWT 签发与校验（`internal/auth/adminjwt.go`）
+- 管理端路由使用 `middleware.AdminAuth()` 做 JWT 校验
+
+## 工具与间接依赖
+
+- **golang.org/x/time**：时间/限流相关（如 `rate`）
+- **gin-contrib/sse**：SSE（Gin 间接）
+- **bytedance/sonic**：JSON 编解码（Gin 默认）
+- **go-playground/validator**：请求体校验（Gin 的 `ShouldBindJSON` 等）
+- **redis/go-redis**：仅在依赖图中出现（PowerWeChat 等间接引入），项目代码中未直接使用 Redis
+
+## 项目结构（技术栈视角）
+
+| 层级     | 技术/约定 |
+|----------|------------|
+| 入口     | `cmd/server/main.go`，标准库 `net/http` + Gin |
+| 路由     | `internal/router`，Gin Group（`/api`、`/admin`、`/miniprogram` 等） |
+| 中间件   | CORS、Secure、限流（`middleware.RateLimiter`）、管理端 JWT |
+| 业务逻辑 | `internal/handler`，GORM + `internal/model` |
+| 数据访问 | `internal/database` 提供 `DB() *gorm.DB`，统一用 GORM |
+| 微信相关 | `internal/wechat`（小程序、支付、转账等封装） |
+| 开发工具 | `.air.toml` 热重载、Makefile |
+
+整体上是一个 **Gin + GORM + MySQL + 微信 PowerWeChat + JWT 管理端鉴权** 的 Go 后端，面向小程序与管理端 API。
diff --git a/开发文档/2、架构/系统与技术.md b/开发文档/2、架构/系统与技术.md
new file mode 100644
index 00000000..e244edb3
--- /dev/null
+++ b/开发文档/2、架构/系统与技术.md
@@ -0,0 +1,15 @@
+# 系统与技术（合并自 系统架构、技术选型与全景图、前后端架构分离策略、数据库）
+
+## 核心理念
+
+** separation**：内容与代码分离、前后端分离、静态与动态分离。架构围绕「省事」和「变现」。
+
+**技术栈**：Next.js 14/16 App Router、TypeScript、Tailwind、Shadcn UI、Zustand、MySQL/MongoDB、Vercel/宝塔部署。
+
+**内容即产品**：`book/` Markdown 为资产，Git 管理，文件系统读取。
+
+**数据库**：见 `数据库.md`，表结构、连接配置。
+
+## 前后端架构分离
+
+开发协作规范、API 边界、部署拆分策略。
diff --git a/开发文档/2、架构/超级个体（用户模块方向）.md b/开发文档/2、架构/超级个体（用户模块方向）.md
new file mode 100644
index 00000000..196d40d8
--- /dev/null
+++ b/开发文档/2、架构/超级个体（用户模块方向）.md
@@ -0,0 +1,49 @@
+一、超级个体（后台/产品模型）
+现状与问题
+
+超级个体在做「融合」，数据仍对不齐；功能落在 @ 列表 与配置里，还要再对。
+曾把超级个体与用户管理拆开讨论：超级个体本质是「用户」，不应当成和内容管理混放。
+@ 表示的是「一个人」，不是「文章解析」这个功能本身；解析是 @ 到人之后触发的链路。
+架构结论（卡若口径）
+
+以超级个体为核心做列表：at 相关能力归拢到超级个体；若一切以人为单位（webhook、存客宝等），可去掉重复的平行列表。
+用户模块只拆两类：普通用户 vs 超级个体，共用「一排属性」思路：
+普通用户：基本资料、用户旅程、行为/标签；另有 VIP 才开放的隐藏属性。
+超级个体：在「成为超级个体」后多开：营销获客（推群等）、存客宝自动添加配置、统计等。
+文章里 @ 人：只应对「可 @ 的超级个体」开放扩展能力；普通用户不能同等 @ 法。
+页面上所有组件 = 超级个体详情页的字段映射（含飞书绑定等字段的拉出）。
+交互/数据
+
+旧文章里已有 @ 人，融合时要避免「合二为一」导致 点击会员应进男方资料详情却跳错页 的问题。
+超级个体展示：OpenID 等英文改为纯中文；旧数据要单独处理。
+「找伙伴」：内容类型里新增 跳转小程序页面，需补路径下拉并把各路径写清楚。
+二、Soul 小程序（本场直接相关）
+与存客宝/老王侧打通
+老王：和 Soul 打通约 90%，可能 永平侧接口未上传，是否成功还不确定。
+文章 → 内容库：触发后新增到内容库（纪要里提到「第 8 条」到内容库）；需 内容库给永平接口。
+存客宝 key：收敛为 一个 key + 一份说明，不要多 key 碎片化。
+另提到 MBTI 深客对接、永平历史 API 等（与 Soul 获客链路相关）。
+三、书小程序（本场直接相关）
+运营场景（南风号等）
+
+微信号挂存客宝的目的：把小程序里的文章（如 139/140 场、从第一章起等）同步出去，让客户在私域里能点开，才有流量。
+需要 内容库：小程序后台审过的文章，按策略（从后往前、从中间推等）灌进内容库，再同步到销售朋友圈；生活类视频同步价值低，可不做。
+同步形态
+
+纪要明确：把小程序分享文案 + 小程序本体信息同步进内容库（类比过去「文章+图片进大库再挨个发」）。
+永平侧：老王 内容库已有接口 → 接口给永平；推送格式要 与真实小程序分享一致。
+运营要求：必须能发/同步小程序形态（后面尹晓辉等也要同样挂法），仅靠公众号不行（要点完能在后台体现获客）。
+四、整合方案（超级个体 × 双小程序 × 存客宝/飞书）
+方向	会议结论要点
+产品对象模型
+用户域以 超级个体为枢纽；@、获客配置、统计、飞书字段都挂在「人」上，减少平行列表。
+Soul 线
+Soul 侧与存客宝打通收尾看 永平接口与联调；文章进 内容库 与自动投放联动。
+书小程序线
+书小程序文章经审核 → 内容库 → 销售朋友圈/私域；与 Soul 共用「内容库 + 存客宝」思路。
+超级个体 × AI 通道
+卡若：书小程序上的超级个体也可以接一条通道，与飞书、微信等一样，接到统一 AI 对话/编排里，即可对话与操作（与「全平台通道」同一架构）。
+技术卡点（朋友圈小程序卡片）
+手机端发小程序「不好弄」；核心是 URL/文章 ID → 小程序卡片格式（参数、签名）。老王/永平 研究拼接规则；备选 H5/公众号被运营否决或不优先。
+工程要求
+推送考虑 定时、去重；模块化：文章只 @ 人，人再触发方法/属性，降低耦合。
\ No newline at end of file
diff --git a/开发文档/2、架构/链路与变现.md b/开发文档/2、架构/链路与变现.md
new file mode 100644
index 00000000..011a24b1
--- /dev/null
+++ b/开发文档/2、架构/链路与变现.md
@@ -0,0 +1,19 @@
+# 链路与变现（合并自 链路优化与运行指南、变现模块设计）
+
+## 链路总览
+
+```
+后台鉴权 → 进群（支付后跳转） → 营销策略（推广/活码/配置） → 支付（下单→回调→到账）
+```
+
+**运行**：`pnpm dev` 或 `pnpm build` + `node .next/standalone/server.js`，端口 3006。
+
+**配置**：`GET /api/config` 拉取配置，admin / key123456 鉴权，登出 `POST /api/admin/logout`。
+
+## 变现模块
+
+- **支付模块**：Order、PaymentProvider，微信/支付宝对接
+- **营销模块**：Campaign、MarketingService，弹窗、Banner、转化
+- **分销模块**：ReferralCode、ReferralService，邀请码、佣金计算
+
+详见原《链路优化与运行指南》《变现模块设计》。
diff --git a/开发文档/3、原型/README.md b/开发文档/3、原型/README.md
new file mode 100644
index 00000000..147f8247
--- /dev/null
+++ b/开发文档/3、原型/README.md
@@ -0,0 +1,11 @@
+# 3、原型
+
+> 原型与交互规范。**现行界面与字段以** [1、需求/以界面定需求.md](../1、需求/以界面定需求.md) **及代码为准**；原型文档用于早期对齐与评审。
+
+## 本目录文件
+
+| 文件 | 说明 |
+|------|------|
+| [原型设计规范.md](./原型设计规范.md) | 原型产出与标注约定 |
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/3、原型/原型设计规范.md b/开发文档/3、原型/原型设计规范.md
new file mode 100644
index 00000000..d3a604c6
--- /dev/null
+++ b/开发文档/3、原型/原型设计规范.md
@@ -0,0 +1,575 @@
+# 原型设计规范
+
+**我是卡若。**
+
+这个文档是写给设计师和前端开发看的。咱们的项目特点很明确：**移动端优先，iOS风格，极致阅读体验**。
+
+---
+
+## 一、设计原则
+
+### 1.1 移动端优先
+- 90%的用户是从微信、Soul、朋友圈进来的，都是手机
+- 设计稿必须先出手机版，再适配PC
+- 断点设置：375px (iPhone SE) / 414px (iPhone 14 Pro Max)
+
+### 1.2 iOS风格
+- 圆角：16px / 20px / 24px (统一使用这3个值)
+- 阴影：`box-shadow: 0 4px 12px rgba(0,0,0,0.08)`
+- 字体：San Francisco (iOS) / PingFang SC (安卓)
+- 间距：8px的倍数系统 (8 / 16 / 24 / 32 / 48)
+
+### 1.3 简洁至上
+- 每个页面只有1个主要操作按钮
+- 减少选择，降低决策成本
+- 文字能说清楚的，就别用图
+
+---
+
+## 二、核心页面原型
+
+### 2.1 首页 (Home)
+
+**功能目标**: 3秒内让用户知道这是什么书，并产生购买欲望
+
+**布局结构**:
+\`\`\`
+[Hero区域]
+- 书籍封面 (3D效果)
+- 标题：《一场Soul的创业实验》
+- 副标题：真实的商业案例库
+- 作者：卡若
+- 价格标签：¥9.9 (限时优惠)
+- 主按钮：立即阅读
+
+[数据统计卡片]
+- 已购买人数: 128人
+- 阅读人次: 1,234次
+- 好评率: 98%
+
+[最新章节快捷入口]
+- 横向滚动卡片
+- 每张卡片显示：章节号 + 标题 + 标签(免费/付费)
+
+[Soul派对群推广横幅]
+- 背景：渐变色
+- 文案：每天早上6-9点，Soul派对房不见不散
+- 按钮：加入派对
+
+[底部导航栏]
+- 首页 | 目录 | 我的
+\`\`\`
+
+**交互细节**:
+- 向下滚动时，顶部导航栏自动隐藏
+- 点击书籍封面，可放大预览
+- 点击"立即阅读"，跳转到目录页
+
+**设计稿尺寸**: 375x812 (iPhone X)
+
+---
+
+### 2.2 目录页 (Chapters)
+
+**功能目标**: 清晰展示书籍结构，引导用户阅读
+
+**布局结构**:
+\`\`\`
+[顶部]
+- 返回按钮
+- 标题：目录
+- 全书购买按钮
+
+[篇章结构]
+第一篇 | 真实的人
+  ├─ 第1章 | 人与人之间的底层逻辑
+  │   ├─ 1.1 自行车荷总... [免费]
+  │   ├─ 1.2 老墨... [1元] [锁]
+  │   └─ ...
+  ├─ 第2章 | 人性困境案例
+  │   └─ ...
+  
+第二篇 | 真实的行业
+  └─ ...
+\`\`\`
+
+**视觉设计**:
+- 篇章标题：粗体，16px，品牌色渐变
+- 章节标题：常规，14px，深灰色
+- 免费标签：绿色小标签
+- 付费标签：橙色小标签 + 锁图标
+- 定时解锁：灰色小标签 + 倒计时
+
+**交互细节**:
+- 点击免费章节，直接进入阅读
+- 点击付费章节，弹出购买弹窗
+- 点击已购买章节，进入阅读
+- 长按章节，可以分享给好友
+
+---
+
+### 2.3 阅读页 (Read)
+
+**功能目标**: 沉浸式阅读体验，零干扰
+
+**布局结构**:
+\`\`\`
+[顶部工具栏] (可隐藏)
+- 返回按钮
+- 进度条 (当前位置/总长度)
+- 目录按钮
+
+[正文区域]
+- 标题
+- 作者 + 发布时间
+- Markdown渲染内容
+  - 标题层级
+  - 段落
+  - 引用块
+  - 代码块
+  - 图片
+  - 列表
+
+[底部工具栏] (可隐藏)
+- 上一章
+- 目录按钮
+- 下一章
+- 分享按钮
+\`\`\`
+
+**视觉设计**:
+- 字体大小：16px (可调)
+- 行高：1.8
+- 段落间距：24px
+- 左右边距：24px
+- 背景：#FAFAFA (浅灰) 或 #1C1C1E (深色模式)
+
+**交互细节**:
+- 点击屏幕中央，显示/隐藏工具栏
+- 向上滚动，自动隐藏工具栏
+- 阅读到30%时，弹出"扫码解锁全文"弹窗
+- 阅读完成，自动跳转到下一章
+
+---
+
+### 2.4 我的页面 (My)
+
+**功能目标**: 用户中心 + 分销中心
+
+**布局结构**:
+\`\`\`
+[用户信息卡片]
+- 头像
+- 昵称
+- 手机号
+- 我的邀请码：REFXXXX (点击复制)
+
+[阅读统计]
+- 已购买章节: 12章
+- 阅读时长: 3小时28分
+- 阅读进度: 45%
+
+[分销中心] (重点突出)
+- 背景：渐变色卡片
+- 我的收益: ¥256.80
+- 待提现: ¥128.90
+- 已提现: ¥127.90
+- 推荐人数: 28人
+- 按钮：推广海报生成 | 立即提现
+
+[功能菜单]
+- 我的订单
+- 购买记录
+- 分享记录
+- 设置
+\`\`\`
+
+**交互细节**:
+- 点击邀请码，自动复制
+- 点击"推广海报生成"，生成专属海报
+- 点击"立即提现"，弹出提现弹窗
+
+---
+
+### 2.5 匹配书友页 (小程序独有)
+
+**功能目标**: 类Soul星球的匹配功能，增加社交属性
+
+**布局结构**:
+\`\`\`
+[星空背景]
+- Canvas动画
+- 星星闪烁效果
+- 星球漂浮效果
+
+[中央区域]
+- 星球图标 (旋转动画)
+- 按钮：开始匹配
+- 提示文字：当前在线 128 人
+
+[匹配中]
+- 光环扩散动画
+- 提示文字：正在寻找志同道合的书友...
+
+[匹配成功]
+- 用户头像
+- 昵称
+- 兴趣标签
+- 匹配度：85%
+- 共同兴趣：创业、私域运营、AI
+- 按钮：打个招呼
+
+[匹配历史]
+- 横向滚动
+- 显示最近10次匹配记录
+\`\`\`
+
+**视觉设计**:
+- 背景：深蓝色渐变 (#1A1A2E -> #16213E)
+- 星球：渐变色球体 + 光晕效果
+- 卡片：毛玻璃效果 + 圆角 + 阴影
+- 动画：流畅的过渡效果
+
+---
+
+## 三、组件设计规范
+
+### 3.1 按钮 (Button)
+
+**主按钮** (Primary):
+\`\`\`css
+background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+color: #FFFFFF;
+height: 48px;
+border-radius: 24px;
+font-size: 16px;
+font-weight: 600;
+\`\`\`
+
+**次按钮** (Secondary):
+\`\`\`css
+background: #FFFFFF;
+border: 1px solid #E5E7EB;
+color: #374151;
+height: 48px;
+border-radius: 24px;
+\`\`\`
+
+**文字按钮** (Text):
+\`\`\`css
+background: transparent;
+color: #667eea;
+text-decoration: underline;
+\`\`\`
+
+### 3.2 输入框 (Input)
+
+\`\`\`css
+height: 48px;
+border: 1px solid #E5E7EB;
+border-radius: 12px;
+padding: 0 16px;
+font-size: 14px;
+background: #FFFFFF;
+\`\`\`
+
+**聚焦状态**:
+\`\`\`css
+border-color: #667eea;
+box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
+\`\`\`
+
+### 3.3 卡片 (Card)
+
+\`\`\`css
+background: #FFFFFF;
+border-radius: 16px;
+box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+padding: 24px;
+\`\`\`
+
+**悬停效果**:
+\`\`\`css
+transform: translateY(-4px);
+box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+transition: all 0.3s ease;
+\`\`\`
+
+### 3.4 骨架屏 (Skeleton)
+
+\`\`\`css
+background: linear-gradient(
+  90deg,
+  #F3F4F6 25%,
+  #E5E7EB 50%,
+  #F3F4F6 75%
+);
+background-size: 200% 100%;
+animation: loading 1.5s infinite;
+border-radius: 8px;
+\`\`\`
+
+---
+
+## 四、弹窗设计
+
+### 4.1 支付弹窗
+
+**触发时机**: 用户点击"购买"按钮
+
+**内容**:
+\`\`\`
+[标题] 选择支付方式
+
+[支付方式列表]
+○ 微信支付 (推荐)
+○ 支付宝
+○ USDT (TRC20)
+○ PayPal
+
+[商品信息]
+- 商品：第1章 | 人与人之间的底层逻辑
+- 价格：¥1.00
+
+[按钮] 
+- 确认支付 (主按钮)
+- 取消 (次按钮)
+\`\`\`
+
+### 4.2 登录弹窗
+
+**触发时机**: 未登录用户点击购买或分享
+
+**内容**:
+\`\`\`
+[标题] 手机号登录
+
+[输入框]
+- 手机号输入框
+- 验证码输入框 (带倒计时按钮)
+
+[邀请码输入框] (可选)
+- 提示：填写邀请码，推荐人可获得佣金
+
+[按钮]
+- 登录 / 注册 (主按钮)
+- 暂不登录 (文字按钮)
+\`\`\`
+
+### 4.3 二维码弹窗
+
+**触发时机**: 阅读到30%或点击"加入派对"
+
+**内容**:
+\`\`\`
+[标题] 扫码加入Soul派对群
+
+[二维码图片]
+- 尺寸：200x200
+- 下方文字：长按识别二维码
+
+[按钮]
+- 我知道了
+\`\`\`
+
+---
+
+## 五、颜色规范
+
+### 5.1 主色调
+
+\`\`\`
+品牌主色 (Primary):
+- 主色：#667EEA
+- 深色：#5A67D8
+- 浅色：#7F9CF5
+
+辅助色 (Secondary):
+- 成功：#10B981 (绿色)
+- 警告：#F59E0B (橙色)
+- 错误：#EF4444 (红色)
+- 信息：#3B82F6 (蓝色)
+\`\`\`
+
+### 5.2 中性色
+
+\`\`\`
+文字颜色:
+- 标题：#111827 (深灰)
+- 正文：#374151 (中灰)
+- 辅助：#6B7280 (浅灰)
+
+背景颜色:
+- 主背景：#FFFFFF (白色)
+- 次背景：#F9FAFB (浅灰)
+- 卡片背景：#FFFFFF (白色)
+\`\`\`
+
+### 5.3 深色模式
+
+\`\`\`
+背景:
+- 主背景：#1C1C1E
+- 次背景：#2C2C2E
+- 卡片背景：#3A3A3C
+
+文字:
+- 标题：#FFFFFF
+- 正文：#E5E5EA
+- 辅助：#98989D
+\`\`\`
+
+---
+
+## 六、字体规范
+
+### 6.1 字体系统
+
+\`\`\`css
+font-family: 
+  -apple-system,           /* iOS */
+  BlinkMacSystemFont,      /* macOS */
+  'Segoe UI',              /* Windows */
+  'PingFang SC',           /* 中文简体 */
+  'Hiragino Sans GB',      /* macOS 中文 */
+  'Microsoft YaHei',       /* Windows 中文 */
+  sans-serif;
+\`\`\`
+
+### 6.2 字号规范
+
+\`\`\`
+特大标题：32px / 36px (权重: 700)
+大标题：24px / 28px (权重: 600)
+中标题：20px / 24px (权重: 600)
+小标题：18px / 22px (权重: 500)
+正文：16px / 24px (权重: 400)
+辅助文字：14px / 20px (权重: 400)
+小字：12px / 18px (权重: 400)
+\`\`\`
+
+---
+
+## 七、动画规范
+
+### 7.1 过渡动画
+
+\`\`\`css
+/* 标准过渡 */
+transition: all 0.3s ease;
+
+/* 快速过渡 */
+transition: all 0.15s ease;
+
+/* 慢速过渡 */
+transition: all 0.5s ease;
+\`\`\`
+
+### 7.2 加载动画
+
+**骨架屏**:
+\`\`\`css
+@keyframes loading {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+\`\`\`
+
+**旋转加载**:
+\`\`\`css
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+\`\`\`
+
+### 7.3 页面切换动画
+
+**滑动进入** (iOS风格):
+\`\`\`css
+@keyframes slideIn {
+  from {
+    transform: translateX(100%);
+    opacity: 0;
+  }
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
+}
+\`\`\`
+
+---
+
+## 八、响应式断点
+
+\`\`\`css
+/* 手机 (默认) */
+@media (max-width: 640px) { ... }
+
+/* 平板 */
+@media (min-width: 641px) and (max-width: 1024px) { ... }
+
+/* 桌面 */
+@media (min-width: 1025px) { ... }
+\`\`\`
+
+---
+
+## 九、设计交付规范
+
+### 9.1 设计稿命名
+
+\`\`\`
+格式：页面名称-设备-版本号.fig
+示例：
+- 首页-Mobile-v1.0.fig
+- 目录页-Mobile-v1.0.fig
+- 阅读页-Mobile-v1.0.fig
+\`\`\`
+
+### 9.2 切图规范
+
+\`\`\`
+命名：功能-类型-尺寸.png
+示例：
+- button-primary-normal@2x.png
+- icon-lock-24x24@2x.png
+- cover-book-400x600@2x.png
+\`\`\`
+
+### 9.3 标注规范
+
+- 所有间距必须标注
+- 字体大小和行高必须标注
+- 颜色使用十六进制色值
+- 圆角、阴影参数必须标注
+
+---
+
+## 十、参考案例
+
+### 10.1 iOS原生风格
+- **Settings App** (iOS系统设置)
+- **Apple Books** (苹果图书)
+- **Notion** (笔记应用)
+
+### 10.2 阅读类产品
+- **微信读书**
+- **得到App**
+- **小宇宙播客**
+
+### 10.3 社交匹配类
+- **Soul**
+- **探探**
+- **Tinder**
+
+---
+
+**总结**: 原型设计不是为了好看,是为了让用户"不用想就知道怎么做"。简洁、清晰、高效,这就是我们的设计原则。
+
+---
+
+**更新时间**: 2025年1月14日  
+**负责人**: 卡若  
+**设计工具**: Figma
diff --git a/开发文档/4、前端/02-AI分析-长图.png b/开发文档/4、前端/02-AI分析-长图.png
new file mode 100644
index 00000000..ec6b7929
Binary files /dev/null and b/开发文档/4、前端/02-AI分析-长图.png differ
diff --git a/开发文档/4、前端/03-数据市场-长图.png b/开发文档/4、前端/03-数据市场-长图.png
new file mode 100644
index 00000000..41e0d198
Binary files /dev/null and b/开发文档/4、前端/03-数据市场-长图.png differ
diff --git a/开发文档/4、前端/04-标签画像-长图.png b/开发文档/4、前端/04-标签画像-长图.png
new file mode 100644
index 00000000..cbe3fc19
Binary files /dev/null and b/开发文档/4、前端/04-标签画像-长图.png differ
diff --git a/开发文档/4、前端/05-估值模型-长图.png b/开发文档/4、前端/05-估值模型-长图.png
new file mode 100644
index 00000000..d25f099f
Binary files /dev/null and b/开发文档/4、前端/05-估值模型-长图.png differ
diff --git a/开发文档/4、前端/06-设置-长图.png b/开发文档/4、前端/06-设置-长图.png
new file mode 100644
index 00000000..e0822c3e
Binary files /dev/null and b/开发文档/4、前端/06-设置-长图.png differ
diff --git a/开发文档/4、前端/07-文档-长图.png b/开发文档/4、前端/07-文档-长图.png
new file mode 100644
index 00000000..98d0e15c
Binary files /dev/null and b/开发文档/4、前端/07-文档-长图.png differ
diff --git a/开发文档/4、前端/08-登录-长图.png b/开发文档/4、前端/08-登录-长图.png
new file mode 100644
index 00000000..fa2361fc
Binary files /dev/null and b/开发文档/4、前端/08-登录-长图.png differ
diff --git a/开发文档/4、前端/09-流量池-长图.png b/开发文档/4、前端/09-流量池-长图.png
new file mode 100644
index 00000000..1411eb44
Binary files /dev/null and b/开发文档/4、前端/09-流量池-长图.png differ
diff --git a/开发文档/4、前端/README.md b/开发文档/4、前端/README.md
new file mode 100644
index 00000000..7a1559b0
--- /dev/null
+++ b/开发文档/4、前端/README.md
@@ -0,0 +1,24 @@
+# 4、前端
+
+> 微信小程序（`miniprogram/`）与管理端（`soul-admin/`）相关说明。组件与页面以仓库代码为准。
+
+## 本目录文件
+
+| 文件 | 说明 |
+|------|------|
+| [前端架构.md](./前端架构.md) | 前端整体架构 |
+| [前端开发规范.md](./前端开发规范.md) | 开发规范 |
+| [当前小程序开发细则.md](./当前小程序开发细则.md) | 小程序细则 |
+| [模块详解.md](./模块详解.md) | 业务模块说明 |
+
+## 子目录 ui
+
+| 文件 | 说明 |
+|------|------|
+| [ui/01-概述与页面.md](./ui/01-概述与页面.md) | 概述与页面 |
+| [ui/02-组件与系统.md](./ui/02-组件与系统.md) | 组件与系统 |
+| [ui/03-部署与截图.md](./ui/03-部署与截图.md) | 部署与截图 |
+
+目录内其他 `.png` 为配图素材。
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/4、前端/ui/01-概述与页面.md b/开发文档/4、前端/ui/01-概述与页面.md
new file mode 100644
index 00000000..1f2020c4
--- /dev/null
+++ b/开发文档/4、前端/ui/01-概述与页面.md
@@ -0,0 +1,31 @@
+# 概述与页面（合并自 01-项目概述、02-页面功能说明）
+
+## 项目简介
+
+基于 Next.js 16 的知识付费+分销系统：电子书阅读与付费、创业伙伴匹配、90%高佣分销、用户中心。
+
+**技术栈**：Next.js 16 / React 19 / TypeScript / Tailwind / Zustand / shadcn/ui | 后端：Next.js API、MySQL、微信支付
+
+**项目结构**：app/（页面+API）、components/（ui + modules）、lib/（store、book-data）、book/
+
+## 核心功能模块
+
+| 模块 | 说明 | 路径 |
+|:---|:---|:---|
+| 首页 | 书籍介绍、购买入口 | `/` |
+| 目录 | 章节列表、付费状态 | `/chapters` |
+| 阅读 | 文章内容、购买弹窗 | `/read/[id]` |
+| 找伙伴 | 四种匹配类型 | `/match` |
+| 我的 | 个人中心、收益 | `/my` |
+| 分销中心 | 推广、提现 | `/my/referral` |
+| 管理后台 | 数据管理 | `/admin` |
+
+## 页面功能概要
+
+- **首页**：封面、简介、立即阅读/购买全书、底部导航
+- **目录页**：62章、折叠结构、免费/已购/未购状态
+- **阅读页**：文章渲染、付费墙、上下篇、分享
+- **找伙伴**：创业合伙/资源对接/导师/团队招募
+- **我的**：登录、个人信息、购买记录、推广中心
+
+**定价**：单章 ¥1，全书 ¥9.9，分销 90%
diff --git a/开发文档/4、前端/ui/02-组件与系统.md b/开发文档/4、前端/ui/02-组件与系统.md
new file mode 100644
index 00000000..521209c9
--- /dev/null
+++ b/开发文档/4、前端/ui/02-组件与系统.md
@@ -0,0 +1,31 @@
+# 组件与系统（合并自 03-09）
+
+## 组件清单
+
+**UI 基础**：Button、Card、Input、Label、Textarea、Switch、Tabs
+
+**业务模块**：AuthModal、PaymentModal、PosterModal、WithdrawalModal、AutoWithdrawModal、ChapterContent
+
+## API 接口
+
+基础路径 `/api`，主要模块：book、payment、referral、user、match、admin、config
+
+## 状态管理
+
+Zustand + localStorage，全局 store 含用户、购买、配置等
+
+## 分销系统
+
+推广中心、邀请码、绑定关系、90% 佣金、提现
+
+## 找伙伴
+
+创业合伙/资源对接/导师顾问/团队招募，匹配规则与配置
+
+## 支付系统
+
+微信/支付宝，PaymentModal 弹窗，支付回调与订单状态
+
+## 管理后台
+
+仪表盘、内容管理、用户管理、支付配置、二维码、提现审核、系统设置
diff --git a/开发文档/4、前端/ui/03-部署与截图.md b/开发文档/4、前端/ui/03-部署与截图.md
new file mode 100644
index 00000000..e5b208ba
--- /dev/null
+++ b/开发文档/4、前端/ui/03-部署与截图.md
@@ -0,0 +1,23 @@
+# 部署与截图（合并自 10-11）
+
+## 部署指南
+
+**环境**：Node >= 20，MySQL >= 8
+
+**本地开发**：`npm install` → `npm run dev` → http://localhost:3000
+
+**环境变量**：.env.local 配置 DATABASE_URL、CKB_API_KEY、WECHAT_*
+
+**生产构建**：`npm run build` → `npm start` 或 PM2
+
+## 设计规范（截图还原）
+
+**颜色**：主色 #00CED1，辅助色 gold/green/orange/red/purple，背景 #000/#1c1c1e
+
+**字体**：标题 18–24px，正文 14px，辅助 12px
+
+**圆角**：按钮 12px，卡片 16px，头像 50%
+
+**页面尺寸**：375×812（iPhone 标准）
+
+详见原 10-部署上线指南、11-页面截图与还原指南 完整内容。
diff --git a/开发文档/4、前端/前端开发规范.md b/开发文档/4、前端/前端开发规范.md
new file mode 100644
index 00000000..4f155cb0
--- /dev/null
+++ b/开发文档/4、前端/前端开发规范.md
@@ -0,0 +1,56 @@
+# 前端开发规范 (Frontend Specs) - 智能自生长文档
+
+> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“前端技术专家”角色，生成符合 iOS 风格的 React 代码。
+
+## 1. 基础上下文 (The Two Basic Files)
+### 1.1 角色档案：卡若 (Karuo)
+- **视觉标准**：像素级复刻 iOS (San Francisco, 1:1 间距, 弥散阴影)。
+- **体验标准**：无白屏 (Skeleton)，丝滑转场 (Transition)。
+
+### 1.2 技术栈
+- **核心**：React + Shadcn UI + Tailwind CSS。
+- **辅助**：Vant UI (移动端组件)。
+- **构建**：Vite / Next.js。
+
+## 2. 开发规范核心 (Master Content)
+### 2.1 视觉与风格 (iOS)
+- **字体**：San Francisco > PingFang SC。
+- **色彩**：
+  - 背景：`#F2F2F7` (Grouped Background)。
+  - 分割：`#C6C6C8`。
+  - 交互：`#007AFF` (System Blue)。
+- **细节**：
+  - 圆角：统一 `rounded-lg` 或 `rounded-xl`。
+  - 阴影：柔和弥散，非生硬投影。
+
+### 2.2 交互与性能 (Mandatory)
+- **骨架屏**：数据加载必须显示 Skeleton，严禁 Spinner。
+- **转场**：路由切换必须有动画。
+- **图片**：懒加载 + 失败占位。
+
+### 2.3 目录结构
+- `/src/components`: 原子组件。
+- `/scenarios/new`: 场景获客页。
+- `/src/hooks`: 逻辑复用。
+
+## 3. AI 协作指令 (Expanded Function)
+**角色**：你是我（卡若）的前端主程。
+**任务**：
+1.  **代码生成**：生成 React 组件代码，**必须**包含 Tailwind 类名。
+2.  **样式检查**：确保所有 UI 元素符合 iOS 规范（检查圆角、阴影、字体）。
+3.  **结构分析**：用 Mermaid 展示组件依赖。
+
+### 示例 Mermaid (组件结构)
+\`\`\`mermaid
+classDiagram
+    Page <|-- Header
+    Page <|-- Content
+    Page <|-- Footer
+    Content <|-- SkeletonLoader
+    Content <|-- DataList
+    DataList <|-- ListItem
+    class Page{
+        +state: loading
+        +effect: fetchData()
+    }
+\`\`\`
diff --git a/开发文档/4、前端/前端架构.md b/开发文档/4、前端/前端架构.md
new file mode 100644
index 00000000..2d2779b7
--- /dev/null
+++ b/开发文档/4、前端/前端架构.md
@@ -0,0 +1,94 @@
+# 前端架构
+
+**我是卡若。**
+
+前端就是项目的脸。用户不管是通过朋友圈、抖音还是私域进来，第一眼看到的就是这个页面。如果加载慢、长得丑、滑动卡，人家转头就走，我的流量就浪费了。
+
+所以，前端的核心目标只有一个：**极致的移动端阅读体验，像原生 App 一样丝滑。**
+
+## 1. 技术底座
+
+别跟我说什么技术先进，我要的是**稳**和**快**。
+
+-   **框架**: Next.js 14 (App Router) - 必须用最新的 App Router，路由管理更清晰。
+-   **语言**: TypeScript - 必须用 TS，类型安全，少出低级 Bug。
+-   **样式**: Tailwind CSS - 写样式最快，没有之一。配合 `globals.css` 做全局控制。
+-   **UI 组件库**: Shadcn UI (基于 Radix UI) + Vant UI (风格参考)。
+    -   *注意*：我们要像素级复刻 iOS 风格，字体用 San Francisco，圆角、阴影都要对齐。
+
+## 2. 目录结构（我的地盘）
+
+前端代码主要集中在 `app/` 和 `components/`。
+
+\`\`\`
+app/
+├── (routes)/               # 路由组，逻辑隔离
+│   ├── page.tsx            # 首页：封面、简介、购买按钮
+│   ├── chapters/           # 目录页：章节列表
+│   ├── read/[id]/          # 阅读页：核心体验区
+│   ├── my/                 # 个人中心：购买记录、分销
+│   ├── admin/              # 管理后台：给自己用的
+│   └── documentation/      # 文档生成：内部工具
+├── layout.tsx              # 全局布局：导航栏、SEO Meta
+├── globals.css             # 全局样式
+└── error.tsx               # 错误处理页面
+
+components/
+├── ui/                     # 通用组件 (Button, Input, Skeleton)
+├── modules/                # 业务模块组件 (新增)
+│   ├── auth/               # 认证模块 (AuthModal)
+│   ├── payment/            # 支付模块 (PaymentModal)
+│   ├── marketing/          # 营销模块 (QRCodeModal)
+│   └── referral/           # 分销模块 (ReferralShare)
+├── book-cover.tsx          # 书籍封面展示
+├── chapter-content.tsx     # 章节内容渲染器
+├── bottom-nav.tsx          # 底部导航栏 (手机端核心)
+└── theme-provider.tsx      # 主题管理 (深色/浅色模式)
+\`\`\`
+
+## 2.1 业务模块化 (Modularization)
+
+为了支持“云阿米巴”模式的快速迭代，我们将核心业务逻辑封装为独立模块：
+
+- **支付模块 (Payment)**: 统一管理微信、支付宝、USDT 等支付方式，支持整书/单章购买。
+- **营销模块 (Marketing)**: 负责引流（如二维码弹窗、倒计时Banner），连接私域流量池。
+- **分销模块 (Referral)**: 负责裂变传播（如分享按钮、返利计算），让用户帮我们卖书。
+- **认证模块 (Auth)**: 统一的用户登录与权限校验。
+
+这种设计允许我们在不修改页面核心逻辑的情况下，插拔不同的变现策略。
+
+## 3. 核心交互设计
+
+### 3.1 骨架屏 (Skeleton)
+**规则**：凡是需要加载数据的地方，必须先展示骨架屏。
+- 用户不能看白屏，哪怕等 0.5 秒，也要让他看到“东西正在来”的样子。
+- 强制引入 `Skeleton` 组件。
+
+### 3.2 路由动画 (Transition)
+**规则**：页面切换不能生硬地跳。
+- 使用 Framer Motion 或 CSS Transition。
+- 模拟 iOS 的滑动切换或淡入淡出。
+
+### 3.3 阅读体验
+- **字体**：针对不同设备优化，保证字号适中，行间距舒服（建议 1.6-1.8）。
+- **图片**：懒加载 (Lazy Load)，点击可放大预览。
+- **代码块**：虽然是书，但如果有代码，要有高亮和复制按钮。
+
+## 4. 数据获取 (Fetching)
+
+- **服务端组件 (Server Components)**：
+    - `page.tsx`, `read/[id]/page.tsx` 默认都是服务端组件。
+    - 直接在组件内 `await` 获取数据（通过 `lib/book-data.ts`），SEO 极佳。
+- **客户端组件 (Client Components)**：
+    - 需要交互的（点击、弹窗、状态变化），头部加 `'use client'`。
+    - 比如 `auth-modal.tsx`, `purchase-section.tsx`。
+
+## 5. 待办事项 (Todo)
+
+- [ ] 全局引入 Skeleton，替换掉所有的 `Loading...` 文字。
+- [ ] 检查所有页面的 Mobile 适配，在 Chrome 开发者工具里用 iPhone SE 和 iPhone 14 Pro Max 两个尺寸测。
+- [ ] 优化字体栈，确保在安卓上也不难看。
+
+---
+**总结**：
+前端不仅是写代码，是**做产品**。每一个像素的偏移都影响用户的信任感。把细节抠好，转化率自然就高了。
diff --git a/开发文档/4、前端/当前小程序开发细则.md b/开发文档/4、前端/当前小程序开发细则.md
new file mode 100644
index 00000000..1aad3fe1
--- /dev/null
+++ b/开发文档/4、前端/当前小程序开发细则.md
@@ -0,0 +1,160 @@
+# 当前小程序开发细则
+
+> 汇总当前 Soul 创业派对小程序的架构、经验与规划，便于新人上手与后续迭代。  
+> 最后整理：2026-02
+
+---
+
+## 一、概述与定位
+
+- **产品**：Soul 创业派对 — 微信小程序，内容为《一场 SOUL 的创业实验场》章节阅读 + 找伙伴 + 分销。
+- **技术**：原生微信小程序（非 uni-app / Taro），与 Next.js 后端同仓，接口统一走 `apiBase`（如 `https://soul.quwanzhi.com`）。
+- **核心能力**：章节阅读（免费/付费）、单章/全书支付、邀请码分销、找伙伴（匹配次数购买）、推广中心、我的订单/设置。
+
+---
+
+## 二、目录与页面结构
+
+### 2.1 目录结构（miniprogram/）
+
+```
+miniprogram/
+├── app.js / app.json / app.wxss     # 入口、全局配置、样式
+├── custom-tab-bar/                  # 自定义底部 tabBar
+├── pages/
+│   ├── index/         # 首页（推荐章节、已读统计）
+│   ├── chapters/      # 目录（全书章节列表）
+│   ├── read/          # 阅读页（核心：权限、支付、分享）
+│   ├── match/         # 找伙伴（匹配 + 购买次数）
+│   ├── my/            # 我的（入口：订单、推广、设置）
+│   ├── referral/      # 推广中心（邀请码、收益、海报）
+│   ├── purchases/     # 我的订单（当前为本地已购章节列表）
+│   ├── settings/      # 设置（提现、绑定账号等）
+│   ├── search/        # 搜索
+│   ├── about/         # 关于
+│   └── addresses/     # 地址（若启用）
+├── utils/
+│   ├── chapterAccessManager.js  # 章节权限与状态
+│   ├── readingTracker.js        # 阅读进度追踪
+│   ├── payment.js               # 旧支付封装（部分场景仍用）
+│   └── util.js
+└── assets/                       # 图标等静态资源
+```
+
+### 2.2 TabBar 与主要页面
+
+| Tab | 页面 | 说明 |
+|-----|------|------|
+| 首页 | pages/index/index | 推荐章节、已读/待读、入口到阅读 |
+| 目录 | pages/chapters/chapters | 全书章节列表 |
+| 找伙伴 | pages/match/match | 匹配 + 购买匹配次数 |
+| 我的 | pages/my/my | 已读/已购、推广中心、订单、设置 |
+
+非 Tab 页：阅读页 read、推广中心 referral、订单 purchases、设置 settings、搜索 search、关于 about。
+
+### 2.3 全局状态（app.js globalData）
+
+- `userInfo`：登录后用户信息（id、openId、nickname、purchasedSections、hasFullBook、referralCode、referralCount 等）。
+- `openId` / `isLoggedIn`：微信登录态。
+- `readSectionIds`：已读章节 ID 列表（有权限打开全文时打点）。
+- `pendingReferralCode`：待绑定推荐码（带 ref 进入时写入，登录后绑定）。
+- `apiBase`：后端 API 根地址。
+
+---
+
+## 三、核心流程与经验
+
+### 3.1 阅读与章节权限
+
+- **权威数据源**：章节是否可读以**服务端**为准（`/api/user/check-purchased`、`/api/user/purchase-status`），不依赖前端缓存做最终判断。
+- **权限状态**：设计上支持 `unknown / free / locked_not_login / locked_not_purchased / unlocked_purchased / error`（见《章节阅读付费标准流程设计》）；阅读页通过 `chapterAccessManager` 与 `determineAccessState` 等做状态判断。
+- **免费章节**：来自后端配置（如 `/api/db/config` 的 freeChapters），页面 onLoad 时拉取最新免费列表再判断；首帧可用本地默认 freeIds，拉取完成后需能刷新当前章状态，避免竞态误判。
+- **已读 vs 已购**：
+  - **已读**：仅统计“有权限打开并看到全文”的章节（`canAccess=true` 时 `app.markSectionAsRead(sectionId)`），存 `readSectionIds`。
+  - **已购**：来自服务端 `userInfo.purchasedSections`、`hasFullBook` 及 orders 表，用于付费墙与购买按钮展示。
+- **登录后防误解锁**：登录成功（含支付流程中登录）后必须 `refreshPurchaseFromServer()`，再对当前章节做 `recheckCurrentSectionAndRefresh()`（先拉最新免费列表，再请求 check-purchased），避免“刚登录”时误用旧缓存解锁付费章。
+- **内容接口**：当前 `GET /api/book/chapter/[id]` 不校验登录与购买，前端按 `canAccess` 控制展示全文或预览；若未来开放 Web/API，建议章节接口侧做鉴权。
+
+详见：`开发文档/8、部署/章节阅读付费标准流程设计.md`。
+
+### 3.2 支付流程（章节 + 找伙伴）
+
+- **统一入口**：章节支付 `pages/read/read.js` 调 `POST /api/miniprogram/pay`；找伙伴支付 `pages/match/match.js` 同样调该接口，传 `productType: 'match'`。
+- **订单先行**：支付前**必须先创建订单**并插入 `orders` 表（status=`created`），再调微信统一下单；即使插库失败也继续支付流程，避免用户卡在“创建订单失败”。
+- **请求体约定**：`openId`、`userId`、`productType`（section/fullbook/match）、`productId`、`amount`、`description`；**必须带 `referralCode`**（见下节）。
+- **支付成功**：依赖微信回调 `POST /api/miniprogram/pay/notify` 更新订单为 `paid`、解锁用户权限、分佣、清理同产品未支付订单；前端支付成功后调用 `refreshUserPurchaseStatus()` 再 `initSection()` 刷新当前页。
+- **兜底**：若回调丢失，依赖**订单状态同步定时任务**（如每 5 分钟调 `GET /api/cron/sync-orders`）查询微信侧状态并同步到本地 orders，保证最终一致。详见 `开发文档/8、部署/宝塔面板配置订单同步定时任务.md`。
+
+### 3.3 邀请码与分销（必传、必记）
+
+- **绑定逻辑**：带 `ref` 或 `referralCode` 的链接进入 → `app.js` 的 `handleReferralCode` 写入 `pendingReferralCode` 并**同步写入 `referral_code`**（`wx.setStorageSync('referral_code', refCode)`）；登录后调用 `/api/referral/bind` 完成绑定（30 天有效、可续期/抢夺）。
+- **支付必带邀请码**：章节支付、找伙伴支付创建订单时都要传 `referralCode`，来源为 `wx.getStorageSync('referral_code')`；后端据此（或先查 referral_bindings）写入订单的 `referrer_id` 与 **`referral_code`**（下单时使用的邀请码，便于对账与后台展示）。
+- **订单表字段**：`orders.referrer_id`（推荐人用户ID）、`orders.referral_code`（下单时邀请码）。若表尚未加字段，需执行 `scripts/add_orders_referrer_id.py`、`scripts/add_orders_referral_code.py`。
+- **推荐人 vs 邀请码**：全局只认「推荐人 = 用户ID」；邀请码仅用于解析出 referrer_id，不会混用。分佣以 `referral_bindings` 为准，不依赖订单上的 referrer_id。详见 `开发文档/8、部署/邀请码分销规则说明.md`。
+
+### 3.4 分享与落地
+
+- 阅读页分享：`onShareAppMessage` / `onShareTimeline` 带 `id=章节ID&ref=当前用户邀请码`，落地后 ref 写入 storage，绑定与订单归属同上。
+- 文章/章节分销与全局同一套：不按“哪篇文章带来”单独分成或统计，仅按“谁发的链接（ref=谁）”归属。
+
+---
+
+## 四、数据与接口约定
+
+### 4.1 关键接口
+
+| 接口 | 用途 |
+|------|------|
+| POST /api/miniprogram/login | 微信登录，返回 userInfo（含 purchasedSections、referralCode 等） |
+| GET /api/user/purchase-status | 拉取购买状态（已购章节、全书） |
+| GET /api/user/check-purchased | 校验指定章节/全书是否已购买 |
+| POST /api/miniprogram/pay | 创建订单 + 微信预支付，**需传 referralCode** |
+| POST /api/miniprogram/pay/notify | 微信支付回调（服务端） |
+| GET /api/cron/sync-orders | 订单状态同步（定时任务，需 secret） |
+| POST /api/referral/bind | 绑定推荐关系 |
+| GET /api/db/config | 免费章节等配置 |
+
+### 4.2 Storage 约定
+
+- `referral_code`：落地 ref 或 app 检测到 ref 时写入；支付时读取并传后端。
+- `pendingReferralCode` / `boundReferralCode`：待绑定/已绑定推荐码（app 层）。
+- `readSectionIds`：已读章节 ID 列表。
+- `openId`、用户信息等由 app 与登录逻辑维护。
+
+---
+
+## 五、已知问题与修复要点
+
+- **免费章节配置竞态**：onLoad 时若未 await 免费列表再 initSection，首帧可能用默认 freeIds 误判；建议先拉配置再判断当前章，或拉取完成后对当前页再刷一次权限。
+- **check-purchased 失败降级**：失败时应**保守**设为无权限（不信任本地缓存），避免误解锁。
+- **支付回调丢失**：必须部署订单同步定时任务（如宝塔 crontab 调 `/api/cron/sync-orders`），否则会出现“已扣款但订单仍 created、内容未解锁”。
+- **订单表缺字段**：新环境或老库需执行 `add_orders_referrer_id.py`、`add_orders_referral_code.py`，否则下单可能 fallback 成不写这两列（功能仍可用，但订单无推荐人/邀请码记录）。
+
+---
+
+## 六、部署与运维
+
+- **后端**：Next.js 部署至 soul.quwanzhi.com，小程序 `app.globalData.apiBase` 指向该域名。
+- **订单同步**：生产环境配置 crontab 每 5 分钟请求 `GET /api/cron/sync-orders?secret=YOUR_SECRET`（如宝塔定时任务），保证回调丢失时仍能同步为 paid 并解锁。见 `开发文档/8、部署/宝塔面板配置订单同步定时任务.md`。
+- **数据库**：orders 表需含 `referrer_id`、`referral_code`；若为已有表，执行上述两个 Python 迁移脚本。
+- **小程序发布**：按微信后台流程上传代码、提交审核；注意域名白名单、支付商户号与回调 URL 配置。
+
+---
+
+## 七、规划与待办（可选）
+
+- **我的订单页**：当前 `purchases` 页为本地已购章节列表；若需“真实订单列表+邀请码展示”，可对接 `GET /api/orders?userId=xxx` 并展示订单维度数据。
+- **阅读进度**：已设计阅读进度状态与 `readingTracker`、可上报服务端；是否全量接入与埋点可按产品需求推进。
+- **章节接口鉴权**：若开放 Web 或对外 API，建议在章节内容接口侧按用户与购买记录返回全文/预览，防止直连拿全文。
+- **按文章/章节维度的分销统计**：当前未实现；若需要“某章节带来的访问/订单数”，需在访问或订单上增加来源章节等字段并在报表中汇总。
+
+---
+
+## 八、相关文档索引
+
+| 文档 | 说明 |
+|------|------|
+| 开发文档/8、部署/邀请码分销规则说明.md | 分销规则、订单 referrer_id/referral_code、推荐人 vs 邀请码 |
+| 开发文档/8、部署/章节阅读付费标准流程设计.md | 阅读状态机、权限判断、阅读进度设计 |
+| 开发文档/4、前端/ui/06-分销系统说明.md | 分销规则与推广方式 |
+| 开发文档/4、前端/ui/08-支付系统说明.md | 支付方式与价格体系 |
diff --git a/开发文档/4、前端/模块详解.md b/开发文档/4、前端/模块详解.md
new file mode 100644
index 00000000..849bfcac
--- /dev/null
+++ b/开发文档/4、前端/模块详解.md
@@ -0,0 +1,721 @@
+# 前端模块详解 - Soul创业实验项目
+
+> **核心模块**: 首页、匹配、阅读、我的、支付、分销
+
+**我是卡若。**
+
+这里记录每个前端模块的实现细节,方便以后维护和扩展。
+
+---
+
+## 1. 首页模块
+
+**路径**: `/app/page.tsx`
+
+### 1.1 核心功能
+
+```typescript
+export default function HomePage() {
+  return (
+    <div className="min-h-screen">
+      {/* 1. 品牌标签 */}
+      <SoulBadge text="Soul · 派对房" />
+      
+      {/* 2. 书籍封面 */}
+      <BookCover src="/images/book-cover.jpg" />
+      
+      {/* 3. 核心数据 */}
+      <DataHighlights 
+        price="¥9.9"
+        cases="64个"
+        insights="100+"
+      />
+      
+      {/* 4. 作者信息 */}
+      <AuthorInfo 
+        name="卡若"
+        time="06:00-09:00"
+        platform="Soul派对房"
+      />
+      
+      {/* 5. 行动按钮 */}
+      <CTAButton text="立即阅读" />
+      
+      {/* 6. 寄语卡片 */}
+      <MessageCard />
+      
+      {/* 7. 章节列表 */}
+      <ChapterList chapters={bookData} />
+    </div>
+  )
+}
+```
+
+### 1.2 关键组件
+
+**书籍封面**:
+```typescript
+function BookCover({ src }: { src: string }) {
+  return (
+    <div className="relative w-64 h-96 mx-auto">
+      <Image
+        src={src}
+        alt="书籍封面"
+        fill
+        className="object-cover rounded-2xl shadow-2xl"
+        priority
+      />
+      {/* 3D效果 */}
+      <div className="absolute inset-0 bg-gradient-to-tr from-black/20 to-transparent rounded-2xl" />
+    </div>
+  )
+}
+```
+
+**数据亮点**:
+```typescript
+function DataHighlights({ price, cases, insights }: Props) {
+  return (
+    <div className="grid grid-cols-3 gap-4 p-6">
+      <div className="text-center">
+        <div className="text-3xl font-bold text-[var(--app-brand)]">
+          {price}
+        </div>
+        <div className="text-sm text-gray-400">全书价格</div>
+      </div>
+      <div className="text-center">
+        <div className="text-3xl font-bold text-[var(--app-brand)]">
+          {cases}
+        </div>
+        <div className="text-sm text-gray-400">商业案例</div>
+      </div>
+      <div className="text-center">
+        <div className="text-3xl font-bold text-[var(--app-brand)]">
+          {insights}
+        </div>
+        <div className="text-sm text-gray-400">商业洞察</div>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## 2. 匹配模块
+
+**路径**: `/app/match/page.tsx`
+
+### 2.1 核心功能
+
+```typescript
+export default function MatchPage() {
+  const [isMatching, setIsMatching] = useState(false)
+  const [matchResult, setMatchResult] = useState(null)
+  
+  const handleMatch = async () => {
+    setIsMatching(true)
+    // 模拟匹配过程
+    await new Promise(resolve => setTimeout(resolve, 2000))
+    setMatchResult({
+      name: '创业者小王',
+      mbti: 'ENTJ',
+      interests: ['私域运营', '内容创业'],
+      matchRate: 85
+    })
+    setIsMatching(false)
+  }
+  
+  return (
+    <div className="min-h-screen flex flex-col items-center justify-center">
+      {/* 星空背景 */}
+      <StarfieldBackground />
+      
+      {/* 中央星球 */}
+      <PlanetAnimation />
+      
+      {/* 标题 */}
+      <h1 className="text-2xl font-bold mb-8">
+        寻找创业合作伙伴
+      </h1>
+      
+      {/* 匹配按钮或结果 */}
+      {!matchResult ? (
+        <Button onClick={handleMatch} loading={isMatching}>
+          开始匹配
+        </Button>
+      ) : (
+        <MatchResultCard result={matchResult} />
+      )}
+      
+      {/* 快捷操作 */}
+      <QuickActions 
+        onAddWechat={() => {}}
+        onJoinGroup={() => {}}
+      />
+    </div>
+  )
+}
+```
+
+### 2.2 关键组件
+
+**星空背景**:
+```typescript
+function StarfieldBackground() {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  
+  useEffect(() => {
+    const canvas = canvasRef.current
+    const ctx = canvas?.getContext('2d')
+    if (!canvas || !ctx) return
+    
+    // 创建星星
+    const stars = Array.from({ length: 100 }, () => ({
+      x: Math.random() * canvas.width,
+      y: Math.random() * canvas.height,
+      radius: Math.random() * 2,
+      opacity: Math.random()
+    }))
+    
+    // 绘制动画
+    function animate() {
+      ctx.clearRect(0, 0, canvas.width, canvas.height)
+      stars.forEach(star => {
+        ctx.beginPath()
+        ctx.arc(star.x, star.y, star.radius, 0, Math.PI * 2)
+        ctx.fillStyle = `rgba(255, 255, 255, ${star.opacity})`
+        ctx.fill()
+      })
+      requestAnimationFrame(animate)
+    }
+    animate()
+  }, [])
+  
+  return <canvas ref={canvasRef} className="absolute inset-0" />
+}
+```
+
+---
+
+## 3. 阅读模块
+
+**路径**: `/app/read/[id]/page.tsx`
+
+### 3.1 核心功能
+
+```typescript
+export default async function ReadPage({ params }: Props) {
+  const { id } = params
+  const section = await getSection(id)
+  
+  if (!section) {
+    notFound()
+  }
+  
+  return (
+    <div className="max-w-3xl mx-auto p-6">
+      {/* 返回按钮 */}
+      <BackButton />
+      
+      {/* 章节标题 */}
+      <h1 className="text-3xl font-bold mb-4">
+        {section.title}
+      </h1>
+      
+      {/* 章节信息 */}
+      <SectionMeta 
+        chapter={section.chapter}
+        readTime="10分钟"
+      />
+      
+      {/* Markdown内容 */}
+      <MarkdownContent content={section.content} />
+      
+      {/* 章节导航 */}
+      <ChapterNavigation 
+        prev={section.prev}
+        next={section.next}
+      />
+      
+      {/* 分享按钮 */}
+      <ShareButton title={section.title} />
+    </div>
+  )
+}
+```
+
+### 3.2 Markdown渲染
+
+```typescript
+import { marked } from 'marked'
+
+function MarkdownContent({ content }: { content: string }) {
+  const html = marked(content)
+  
+  return (
+    <div 
+      className="prose prose-invert max-w-none"
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  )
+}
+
+// CSS样式
+.prose {
+  @apply text-gray-300 leading-relaxed;
+}
+
+.prose h1 {
+  @apply text-3xl font-bold text-white mt-8 mb-4;
+}
+
+.prose h2 {
+  @apply text-2xl font-bold text-white mt-6 mb-3;
+}
+
+.prose p {
+  @apply mb-4;
+}
+
+.prose ul {
+  @apply list-disc list-inside mb-4;
+}
+
+.prose code {
+  @apply bg-gray-800 px-2 py-1 rounded text-[var(--app-brand)];
+}
+```
+
+---
+
+## 4. 我的模块
+
+**路径**: `/app/my/page.tsx`
+
+### 4.1 核心功能
+
+```typescript
+export default function MyPage() {
+  const { user, isLoggedIn } = useStore()
+  
+  if (!isLoggedIn) {
+    return <LoginPrompt />
+  }
+  
+  return (
+    <div className="min-h-screen p-6">
+      {/* 用户信息卡片 */}
+      <UserCard user={user} />
+      
+      {/* 阅读统计 */}
+      <ReadingStats 
+        readChapters={user.purchasedSections.length}
+        totalChapters={64}
+        readTime="3小时"
+      />
+      
+      {/* 分销中心(重点突出) */}
+      <ReferralCenter 
+        code={user.referralCode}
+        earnings={user.earnings}
+        referralCount={user.referralCount}
+      />
+      
+      {/* 功能菜单 */}
+      <MenuList items={[
+        { icon: '📚', title: '我的购买', path: '/my/purchases' },
+        { icon: '💰', title: '收益管理', path: '/my/earnings' },
+        { icon: '📊', title: '推广数据', path: '/my/referral' },
+        { icon: '⚙️', title: '设置', path: '/my/settings' },
+      ]} />
+    </div>
+  )
+}
+```
+
+### 4.2 分销中心
+
+```typescript
+function ReferralCenter({ code, earnings, referralCount }: Props) {
+  return (
+    <div className="glass-card p-6 mb-6">
+      <h2 className="text-xl font-bold mb-4">分销中心</h2>
+      
+      {/* 收益概览 */}
+      <div className="grid grid-cols-2 gap-4 mb-6">
+        <div>
+          <div className="text-3xl font-bold text-[var(--app-brand)]">
+            ¥{earnings.toFixed(2)}
+          </div>
+          <div className="text-sm text-gray-400">累计收益</div>
+        </div>
+        <div>
+          <div className="text-3xl font-bold text-[var(--app-brand)]">
+            {referralCount}
+          </div>
+          <div className="text-sm text-gray-400">推荐人数</div>
+        </div>
+      </div>
+      
+      {/* 邀请码 */}
+      <div className="mb-4">
+        <label className="text-sm text-gray-400">我的邀请码</label>
+        <div className="flex items-center gap-2 mt-2">
+          <input
+            value={code}
+            readOnly
+            className="flex-1 bg-gray-800 px-4 py-2 rounded-lg"
+          />
+          <CopyButton text={code} />
+        </div>
+      </div>
+      
+      {/* 生成海报 */}
+      <Button onClick={() => generatePoster(code)} className="w-full">
+        生成推广海报
+      </Button>
+    </div>
+  )
+}
+```
+
+---
+
+## 5. 支付模块
+
+**路径**: `/components/payment-modal.tsx`
+
+### 5.1 核心流程
+
+```typescript
+export function PaymentModal({ 
+  isOpen, 
+  amount, 
+  type, 
+  onSuccess 
+}: Props) {
+  const [paymentMethod, setPaymentMethod] = useState<PaymentMethod>('alipay')
+  const [showQRCode, setShowQRCode] = useState(false)
+  const [isProcessing, setIsProcessing] = useState(false)
+  
+  // 发起支付
+  const handlePayment = async () => {
+    setShowQRCode(true)
+    
+    // 调用支付API
+    const order = await createOrder({
+      amount,
+      type,
+      paymentMethod
+    })
+    
+    // 展示支付二维码
+    showPaymentQRCode(order.qrCode)
+  }
+  
+  // 确认支付
+  const confirmPayment = async () => {
+    setIsProcessing(true)
+    
+    // 购买逻辑
+    const success = await purchaseItem(type)
+    
+    if (success) {
+      onSuccess()
+      // 自动跳转到读者群
+      openWechatGroup()
+    }
+    
+    setIsProcessing(false)
+  }
+  
+  return (
+    <Modal isOpen={isOpen}>
+      {!showQRCode ? (
+        <PaymentMethodSelection 
+          selected={paymentMethod}
+          onSelect={setPaymentMethod}
+          onConfirm={handlePayment}
+        />
+      ) : (
+        <QRCodeDisplay 
+          method={paymentMethod}
+          amount={amount}
+          onConfirm={confirmPayment}
+          isProcessing={isProcessing}
+        />
+      )}
+    </Modal>
+  )
+}
+```
+
+### 5.2 支付方式组件
+
+```typescript
+function PaymentMethodSelection({ selected, onSelect, onConfirm }: Props) {
+  const methods = [
+    {
+      id: 'wechat',
+      name: '微信支付',
+      icon: <WechatIcon />,
+      color: '#07C160'
+    },
+    {
+      id: 'alipay',
+      name: '支付宝',
+      icon: <AlipayIcon />,
+      color: '#1677FF'
+    },
+    {
+      id: 'usdt',
+      name: 'USDT (TRC20)',
+      icon: <BitcoinIcon />,
+      color: '#26A17B'
+    }
+  ]
+  
+  return (
+    <div className="space-y-4">
+      {methods.map(method => (
+        <button
+          key={method.id}
+          onClick={() => onSelect(method.id)}
+          className={`w-full p-4 rounded-xl flex items-center gap-4 ${
+            selected === method.id
+              ? 'glass-card-light border-[var(--app-brand)]'
+              : 'glass-card'
+          }`}
+        >
+          <div 
+            className="w-12 h-12 rounded-xl flex items-center justify-center"
+            style={{ backgroundColor: `${method.color}15`, color: method.color }}
+          >
+            {method.icon}
+          </div>
+          <span className="flex-1 text-left">{method.name}</span>
+          {selected === method.id && <CheckIcon />}
+        </button>
+      ))}
+      
+      <Button onClick={onConfirm} className="w-full">
+        确认支付
+      </Button>
+    </div>
+  )
+}
+```
+
+---
+
+## 6. 后台管理模块
+
+**路径**: `/app/admin/page.tsx`
+
+### 6.1 概览页面
+
+```typescript
+export default function AdminDashboard() {
+  const [stats, setStats] = useState<Stats | null>(null)
+  
+  useEffect(() => {
+    fetchStats()
+  }, [])
+  
+  async function fetchStats() {
+    const res = await fetch('/api/admin', {
+      headers: {
+        'Authorization': `Bearer ${getAdminToken()}`
+      }
+    })
+    const data = await res.json()
+    setStats(data)
+  }
+  
+  if (!stats) return <Loading />
+  
+  return (
+    <div className="p-6">
+      {/* 概览卡片 */}
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mb-8">
+        <StatCard 
+          title="总收入"
+          value={`¥${stats.payment.totalRevenue}`}
+          trend="+12.5%"
+        />
+        <StatCard 
+          title="总用户"
+          value={stats.users.totalUsers}
+          trend="+23"
+        />
+        <StatCard 
+          title="今日订单"
+          value={stats.payment.todayOrders}
+          trend="+5"
+        />
+        <StatCard 
+          title="分销推广者"
+          value={stats.referral.totalReferrers}
+          trend="+8"
+        />
+      </div>
+      
+      {/* 图表 */}
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <RevenueChart data={stats.revenueHistory} />
+        <UserGrowthChart data={stats.userGrowth} />
+      </div>
+    </div>
+  )
+}
+```
+
+### 6.2 内容管理
+
+```typescript
+function ContentManagement() {
+  const [chapters, setChapters] = useState([])
+  
+  return (
+    <div>
+      {/* 操作栏 */}
+      <div className="flex justify-between mb-6">
+        <h1 className="text-2xl font-bold">内容管理</h1>
+        <Button onClick={() => syncContent()}>
+          同步book目录
+        </Button>
+      </div>
+      
+      {/* 章节列表 */}
+      <Table>
+        <thead>
+          <tr>
+            <th>章节ID</th>
+            <th>标题</th>
+            <th>状态</th>
+            <th>价格</th>
+            <th>操作</th>
+          </tr>
+        </thead>
+        <tbody>
+          {chapters.map(chapter => (
+            <tr key={chapter.id}>
+              <td>{chapter.id}</td>
+              <td>{chapter.title}</td>
+              <td>
+                <Badge color={chapter.isFree ? 'green' : 'blue'}>
+                  {chapter.isFree ? '免费' : '付费'}
+                </Badge>
+              </td>
+              <td>¥{chapter.price}</td>
+              <td>
+                <Button size="sm" onClick={() => editChapter(chapter)}>
+                  编辑
+                </Button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </Table>
+    </div>
+  )
+}
+```
+
+---
+
+## 7. 通用组件库
+
+### 7.1 Button组件
+
+```typescript
+interface ButtonProps {
+  children: React.ReactNode
+  onClick?: () => void
+  loading?: boolean
+  disabled?: boolean
+  variant?: 'primary' | 'secondary' | 'ghost'
+  size?: 'sm' | 'md' | 'lg'
+}
+
+export function Button({
+  children,
+  onClick,
+  loading,
+  disabled,
+  variant = 'primary',
+  size = 'md'
+}: ButtonProps) {
+  const baseClasses = 'rounded-xl font-semibold transition-all'
+  
+  const variantClasses = {
+    primary: 'bg-[var(--app-brand)] text-white hover:opacity-90',
+    secondary: 'bg-[var(--app-bg-secondary)] text-white',
+    ghost: 'bg-transparent text-[var(--app-brand)] hover:bg-[var(--app-brand-light)]'
+  }
+  
+  const sizeClasses = {
+    sm: 'px-4 py-2 text-sm',
+    md: 'px-6 py-3 text-base',
+    lg: 'px-8 py-4 text-lg'
+  }
+  
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`}
+    >
+      {loading ? <Spinner /> : children}
+    </button>
+  )
+}
+```
+
+### 7.2 Modal组件
+
+```typescript
+export function Modal({ 
+  isOpen, 
+  onClose, 
+  children 
+}: ModalProps) {
+  if (!isOpen) return null
+  
+  return (
+    <div className="fixed inset-0 z-50 flex items-end sm:items-center justify-center">
+      {/* 背景蒙层 */}
+      <div 
+        className="absolute inset-0 bg-black/60 backdrop-blur-md"
+        onClick={onClose}
+      />
+      
+      {/* 内容区域 */}
+      <div className="relative w-full sm:max-w-md glass-card overflow-hidden safe-bottom">
+        {/* 顶部把手 (仅移动端) */}
+        <div className="flex justify-center pt-3 pb-2 sm:hidden">
+          <div className="w-9 h-1 rounded-full bg-gray-400" />
+        </div>
+        
+        {/* 关闭按钮 */}
+        <button
+          onClick={onClose}
+          className="absolute top-4 right-4 w-8 h-8 rounded-full bg-gray-800 flex items-center justify-center"
+        >
+          <X className="w-4 h-4" />
+        </button>
+        
+        {/* 内容 */}
+        <div className="p-6">
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+**总结**: 前端模块以**组件化**为核心,每个模块职责清晰,组件可复用。核心模块包括首页(展示)、匹配(社交)、阅读(内容)、我的(用户中心)、支付(变现)、后台(管理)。所有模块都遵循统一的设计规范和交互模式。
diff --git a/开发文档/5、接口/API接口完整文档.md b/开发文档/5、接口/API接口完整文档.md
new file mode 100644
index 00000000..e23fa1d5
--- /dev/null
+++ b/开发文档/5、接口/API接口完整文档.md
@@ -0,0 +1,640 @@
+# API接口完整文档 - Soul创业实验项目
+
+> **API风格**: RESTful | **版本**: v1.0 | **基础路径**: `/api`  
+> **说明**：本文档已整合原《API接口》内容，为项目唯一 API 参考。
+
+**我是卡若。**
+
+接口设计原则：**简单、清晰、易用**。
+
+---
+
+## 1. 接口总览
+
+### 1.1 接口分类
+
+| 模块 | 路径前缀 | 描述 |
+|------|---------|------|
+| 书籍内容 | `/api/book` | 章节列表、内容获取、同步 |
+| 支付系统 | `/api/payment` | 订单创建、支付回调、状态查询 |
+| 分销系统 | `/api/referral` | 邀请码、收益查询、提现 |
+| 用户系统 | `/api/user` | 登录、注册、信息更新 |
+| 匹配系统 | `/api/match` | 寻找匹配、匹配历史 |
+| 管理后台 | `/api/admin` | 内容/订单/用户/分销管理 |
+| 配置系统 | `/api/config` | 系统配置获取 |
+
+### 1.2 认证方式
+
+**用户认证** (可选):
+```
+Cookie: session_id=<session-id>
+```
+
+**管理员认证** (必需):
+```
+Authorization: Bearer admin-token-secret
+```
+
+---
+
+## 2. 书籍内容API
+
+### 2.1 获取所有章节
+
+**接口**: `GET /api/book/all-chapters`
+
+**请求**:
+```bash
+curl https://your-domain.com/api/book/all-chapters
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "part-1",
+      "number": "01",
+      "title": "真实的人",
+      "subtitle": "人性观察与社交逻辑",
+      "chapters": [
+        {
+          "id": "chapter-1",
+          "title": "人与人之间的底层逻辑",
+          "sections": [
+            {
+              "id": "1.1",
+              "title": "自行车荷总:一个行业做到极致是什么样",
+              "price": 1,
+              "isFree": true,
+              "filePath": "book/第一篇｜真实的人/...",
+              "unlockAfterDays": 0
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "total": 64
+}
+```
+
+### 2.2 获取单章内容
+
+**接口**: `GET /api/book/chapter/:id`
+
+**请求**:
+```bash
+curl https://your-domain.com/api/book/chapter/1.1
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "id": "1.1",
+    "title": "自行车荷总:一个行业做到极致是什么样",
+    "content": "# 章节内容...",
+    "chapter": "第1章｜人与人之间的底层逻辑",
+    "section": "第一篇｜真实的人",
+    "isFree": true,
+    "price": 1,
+    "prev": null,
+    "next": "1.2"
+  }
+}
+```
+
+### 2.3 同步章节
+
+**接口**: `POST /api/book/sync`
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/book/sync \
+  -H "Authorization: Bearer admin-token-secret"
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "同步完成",
+  "synced": 64,
+  "updated": 3
+}
+```
+
+---
+
+## 3. 支付API
+
+### 3.1 创建订单
+
+**接口**: `POST /api/payment/create-order`
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/payment/create-order \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userId": "user_123",
+    "type": "fullbook",
+    "amount": 9.9,
+    "paymentMethod": "alipay"
+  }'
+```
+
+**参数**:
+```typescript
+{
+  userId: string          // 用户ID
+  type: 'section' | 'fullbook'  // 订单类型
+  sectionId?: string      // 章节ID (章节购买时必需)
+  amount: number          // 支付金额
+  paymentMethod: 'wechat' | 'alipay' | 'usdt'  // 支付方式
+}
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "orderId": "order_1705230000000",
+    "amount": 9.9,
+    "qrCode": "https://qr.alipay.com/...",
+    "expireTime": "2026-01-14T11:00:00.000Z"
+  }
+}
+```
+
+### 3.2 支付回调 - 支付宝
+
+**接口**: `POST /api/payment/alipay/notify`
+
+**参数** (支付宝POST):
+```
+out_trade_no: "order_1705230000000"
+trade_status: "TRADE_SUCCESS"
+total_amount: "9.90"
+buyer_id: "2088xxx"
+sign: "..."
+```
+
+**响应**:
+```
+success
+```
+
+### 3.3 支付回调 - 微信
+
+**接口**: `POST /api/payment/wechat/notify`
+
+**参数** (微信XML):
+```xml
+<xml>
+  <return_code>SUCCESS</return_code>
+  <out_trade_no>order_1705230000000</out_trade_no>
+  <total_fee>990</total_fee>
+</xml>
+```
+
+**响应**:
+```xml
+<xml>
+  <return_code>SUCCESS</return_code>
+  <return_msg>OK</return_msg>
+</xml>
+```
+
+### 3.4 验证支付状态
+
+**接口**: `GET /api/payment/verify?orderId={orderId}`
+
+**请求**:
+```bash
+curl "https://your-domain.com/api/payment/verify?orderId=order_123"
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "orderId": "order_123",
+    "status": "completed",
+    "paidAt": "2026-01-14T10:30:00.000Z"
+  }
+}
+```
+
+---
+
+## 4. 分销API
+
+### 4.1 获取邀请码
+
+**接口**: `GET /api/referral/code`
+
+**认证**: 需要用户登录
+
+**请求**:
+```bash
+curl https://your-domain.com/api/referral/code \
+  -H "Cookie: session_id=xxx"
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "code": "REF1705230",
+    "url": "https://your-domain.com?ref=REF1705230"
+  }
+}
+```
+
+### 4.2 绑定推荐关系
+
+**接口**: `POST /api/referral/bind`
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/referral/bind \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userId": "user_123",
+    "referralCode": "REF1705229"
+  }'
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "绑定成功"
+}
+```
+
+### 4.3 查询收益
+
+**接口**: `GET /api/referral/earnings`
+
+**认证**: 需要用户登录
+
+**请求**:
+```bash
+curl https://your-domain.com/api/referral/earnings \
+  -H "Cookie: session_id=xxx"
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "total": 89.10,
+    "pending": 35.64,
+    "withdrawn": 53.46,
+    "referralCount": 10,
+    "recentOrders": [
+      {
+        "userId": "user_456",
+        "amount": 9.9,
+        "earnings": 8.91,
+        "createdAt": "2026-01-14T10:00:00.000Z"
+      }
+    ]
+  }
+}
+```
+
+### 4.4 申请提现
+
+**接口**: `POST /api/referral/withdraw`
+
+**认证**: 需要用户登录
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/referral/withdraw \
+  -H "Content-Type: application/json" \
+  -H "Cookie: session_id=xxx" \
+  -d '{
+    "amount": 50,
+    "method": "alipay",
+    "account": "13800138000",
+    "name": "王**"
+  }'
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "withdrawalId": "wd_123",
+    "amount": 50,
+    "status": "pending",
+    "estimatedTime": "1-3个工作日"
+  }
+}
+```
+
+---
+
+## 5. 用户API
+
+### 5.1 登录
+
+**接口**: `POST /api/user/login`
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/user/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "phone": "13800138000",
+    "code": "123456"
+  }'
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "user_123",
+      "phone": "****8000",
+      "nickname": "创业者小王",
+      "hasFullBook": false
+    },
+    "token": "session_token_xxx"
+  }
+}
+```
+
+### 5.2 注册
+
+**接口**: `POST /api/user/register`
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/user/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "phone": "13800138000",
+    "nickname": "创业者小王",
+    "referralCode": "REF1705229"
+  }'
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "user_1705230000000",
+      "phone": "****8000",
+      "nickname": "创业者小王",
+      "referralCode": "REF1705230"
+    },
+    "token": "session_token_xxx"
+  }
+}
+```
+
+---
+
+## 6. 匹配API
+
+### 6.1 寻找匹配
+
+**接口**: `POST /api/match/find`
+
+**认证**: 需要用户登录
+
+**请求**:
+```bash
+curl -X POST https://your-domain.com/api/match/find \
+  -H "Content-Type: application/json" \
+  -H "Cookie: session_id=xxx" \
+  -d '{
+    "mbti": "INTP",
+    "interests": ["私域运营", "内容创业"]
+  }'
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "matchId": "match_123",
+    "user": {
+      "nickname": "创业者小李",
+      "mbti": "ENTJ",
+      "interests": ["私域运营", "供应链"],
+      "matchRate": 85
+    },
+    "commonInterests": ["私域运营"]
+  }
+}
+```
+
+### 6.2 匹配历史
+
+**接口**: `GET /api/match/history`
+
+**认证**: 需要用户登录
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "matchId": "match_123",
+      "nickname": "创业者小李",
+      "matchRate": 85,
+      "createdAt": "2026-01-14T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+## 7. 管理后台API
+
+### 7.1 概览数据
+
+**接口**: `GET /api/admin`
+
+**认证**: 管理员Token
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "content": {
+      "totalChapters": 65,
+      "totalWords": 120000,
+      "publishedChapters": 60,
+      "draftChapters": 5
+    },
+    "payment": {
+      "totalRevenue": 12800.50,
+      "todayRevenue": 560.00,
+      "totalOrders": 128,
+      "todayOrders": 12
+    },
+    "referral": {
+      "totalReferrers": 45,
+      "activeReferrers": 28,
+      "totalCommission": 11520.45
+    },
+    "users": {
+      "totalUsers": 1200,
+      "purchasedUsers": 128,
+      "activeUsers": 456
+    }
+  }
+}
+```
+
+### 7.2 内容管理
+
+**接口**: `GET /api/admin/content`
+
+**接口**: `POST /api/admin/content` - 创建
+
+**接口**: `PUT /api/admin/content/:id` - 更新
+
+**接口**: `DELETE /api/admin/content/:id` - 删除
+
+### 7.3 订单管理
+
+**接口**: `GET /api/admin/payment?status=completed&page=1&limit=20`
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "orders": [
+      {
+        "id": "order_123",
+        "userId": "user_123",
+        "amount": 9.9,
+        "status": "completed",
+        "createdAt": "2026-01-14T10:00:00.000Z"
+      }
+    ],
+    "total": 128,
+    "page": 1,
+    "limit": 20
+  }
+}
+```
+
+---
+
+## 8. 错误码规范
+
+### 8.1 HTTP状态码
+
+| 状态码 | 含义 | 使用场景 |
+|--------|------|----------|
+| 200 | 成功 | 请求成功 |
+| 201 | 创建成功 | 资源创建成功 |
+| 400 | 请求错误 | 参数错误 |
+| 401 | 未授权 | 需要登录 |
+| 403 | 禁止访问 | 权限不足 |
+| 404 | 未找到 | 资源不存在 |
+| 500 | 服务器错误 | 内部错误 |
+
+### 8.2 业务错误码
+
+```typescript
+enum ErrorCode {
+  // 用户相关
+  USER_NOT_FOUND = 1001,
+  USER_ALREADY_EXISTS = 1002,
+  INVALID_PHONE = 1003,
+  INVALID_CODE = 1004,
+  
+  // 支付相关
+  ORDER_NOT_FOUND = 2001,
+  PAYMENT_FAILED = 2002,
+  INSUFFICIENT_BALANCE = 2003,
+  
+  // 分销相关
+  INVALID_REFERRAL_CODE = 3001,
+  WITHDRAWAL_FAILED = 3002,
+  INSUFFICIENT_EARNINGS = 3003,
+  
+  // 内容相关
+  CHAPTER_NOT_FOUND = 4001,
+  CHAPTER_NOT_PURCHASED = 4002,
+}
+```
+
+**错误响应格式**:
+```json
+{
+  "success": false,
+  "error": {
+    "code": 1001,
+    "message": "用户不存在",
+    "details": "用户ID: user_123"
+  }
+}
+```
+
+---
+
+## 9. 接口性能优化
+
+### 9.1 缓存策略
+
+**内容缓存**:
+```typescript
+// 章节内容缓存1小时
+res.setHeader('Cache-Control', 'public, max-age=3600')
+
+// 章节列表缓存10分钟
+res.setHeader('Cache-Control', 'public, max-age=600')
+```
+
+**ETag**:
+```typescript
+const etag = generateETag(content)
+res.setHeader('ETag', etag)
+
+if (req.headers['if-none-match'] === etag) {
+  return res.status(304).end()
+}
+```
+
+### 9.2 限流策略
+
+```typescript
+// 接口限流: 100次/分钟
+const limiter = {
+  '/api/book/all-chapters': { limit: 100, window: 60 },
+  '/api/payment/create-order': { limit: 10, window: 60 },
+  '/api/admin/*': { limit: 1000, window: 60 }
+}
+```
+
+---
+
+**总结**: API设计遵循RESTful规范,响应格式统一,错误处理清晰。所有接口都有明确的认证要求和错误处理。核心功能包括内容获取、支付流程、分销系统、用户管理、匹配功能。
diff --git a/开发文档/5、接口/README.md b/开发文档/5、接口/README.md
new file mode 100644
index 00000000..c7e72faf
--- /dev/null
+++ b/开发文档/5、接口/README.md
@@ -0,0 +1,18 @@
+# 5、接口
+
+> **Soul 创业实验项目** HTTP API 与相关配置文档。
+
+## 真源与分工
+
+| 文档 | 说明 |
+|------|------|
+| [**API接口完整文档.md**](./API接口完整文档.md) | Soul `/api` **主真源**（REST 模块划分、鉴权说明） |
+| [配置清单-完整版.md](./配置清单-完整版.md) | 环境变量与配置项 |
+| [在线支付对接文档.md](./在线支付对接文档.md) | 支付对接 |
+| [接口与提现.md](./接口与提现.md) | 提现与相关接口 |
+
+## 非本目录但易混淆
+
+- **存客宝「对外线索上报」OpenAPI**（第三方调存客宝）：见开发文档根目录 [api_v1.md](../api_v1.md) 文首说明；存客宝 **前端** 调自家后端见 [Cunkebao接口文档/](../Cunkebao接口文档/)。
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/5、接口/在线支付对接文档.md b/开发文档/5、接口/在线支付对接文档.md
new file mode 100644
index 00000000..27c8bf8c
--- /dev/null
+++ b/开发文档/5、接口/在线支付对接文档.md
@@ -0,0 +1,319 @@
+# 在线支付对接文档
+
+本文档根据当前项目中的支付相关代码与配置反向整理，供前端/第三方/运维对接使用。后端当前为 **soul-api（Go/Gin）**，支付业务逻辑可参考 **next-project** 中的实现。
+
+---
+
+## 一、概述
+
+- **支付方式**：微信支付（Native 扫码 / JSAPI 小程序·公众号 / H5）、支付宝（WAP / Web / 扫码）。
+- **对接入口**：统一走 soul-api 的 `/api` 前缀（如 `https://your-api.com/api/...`）。
+- **回调**：支付平台（微信/支付宝）会主动 POST 到服务端配置的 notify 地址，需公网可访问且返回约定格式。
+
+---
+
+## 二、接口清单（soul-api）
+
+| 方法 | 路径 | 说明 |
+|-----|------|------|
+| POST | `/api/payment/create-order` | 创建支付订单，返回支付参数（二维码/链接/JSAPI 参数等） |
+| GET  | `/api/payment/methods` | 获取可用支付方式列表 |
+| GET  | `/api/payment/query` | 按交易号查询支付状态（轮询用） |
+| GET  | `/api/payment/status/:orderSn` | 按订单号查询订单支付状态 |
+| POST | `/api/payment/verify` | 支付结果校验（可选） |
+| POST | `/api/payment/callback` | 通用支付回调（可选，与各平台 notify 二选一或并存） |
+| POST | `/api/payment/wechat/notify` | 微信支付异步通知 |
+| POST | `/api/payment/alipay/notify` | 支付宝异步通知 |
+| POST | `/api/payment/wechat/transfer/notify` | 微信转账/企业付款到零钱回调（若启用） |
+| GET/POST | `/api/miniprogram/pay` | 小程序下单（创建订单 + 返回微信支付参数） |
+| POST | `/api/miniprogram/pay/notify` | 小程序支付异步通知 |
+
+管理端（需鉴权）：
+
+| 方法 | 路径 | 说明 |
+|-----|------|------|
+| GET/POST/PUT/DELETE | `/api/admin/payment` | 支付相关配置管理 |
+
+---
+
+## 三、请求与响应约定
+
+以下格式以 next-project 中已实现逻辑为对接规范，soul-api 实现时应与之兼容。
+
+### 3.1 创建订单 `POST /api/payment/create-order`
+
+**请求体（JSON）**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| userId | string | 是 | 用户 ID |
+| type | string | 是 | 购买类型：`section`（单章） / `fullbook`（全书） |
+| sectionId | string | type=section 时 | 章节 ID，如 `1-1` |
+| sectionTitle | string | 建议 | 章节标题，用于展示与订单描述 |
+| amount | number | 是 | 金额（元），如 9.9 |
+| paymentMethod | string | 是 | 支付方式：`wechat` / `alipay` |
+| referralCode | string | 否 | 推荐人邀请码，用于分销 |
+
+**响应（JSON）**
+
+```json
+{
+  "code": 200,
+  "message": "订单创建成功",
+  "data": {
+    "orderSn": "20260209123456",
+    "tradeSn": "T2026020912000012345",
+    "userId": "user_xxx",
+    "type": "section",
+    "sectionId": "1-1",
+    "sectionTitle": "第一章",
+    "amount": 9.9,
+    "paymentMethod": "wechat",
+    "status": "created",
+    "createdAt": "2026-02-09T12:00:00.000Z",
+    "expireAt": "2026-02-09T12:30:00.000Z",
+    "paymentData": {
+      "type": "qrcode",
+      "payload": "weixin://wxpay/...",
+      "tradeSn": "T2026020912000012345",
+      "expiration": 1800
+    },
+    "gateway": "wechat_native"
+  }
+}
+```
+
+- **paymentData.type**：`qrcode`（二维码内容/链接）、`url`（跳转链接）、`json`（JSAPI 等参数对象）。
+- **paymentData.payload**：微信 Native 为二维码链接；支付宝 WAP 为支付 URL；JSAPI 为 `{ timeStamp, nonceStr, package, signType, paySign }` 等。
+- **gateway**：用于后续轮询时传 `gateway`，如 `wechat_native`、`alipay_wap`。
+
+**错误**：`code: 400` 表示缺少必要参数；`code: 500` 为服务器错误。
+
+---
+
+### 3.2 支付方式列表 `GET /api/payment/methods`
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "methods": [
+      {
+        "gateway": "wechat_native",
+        "name": "微信支付",
+        "icon": "wechat",
+        "enabled": true,
+        "available": true
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 3.3 查询支付状态（轮询）`GET /api/payment/query`
+
+**Query**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| tradeSn | string | 是 | 创建订单时返回的 tradeSn |
+| gateway | string | 否 | 指定网关，如 `wechat_native`、`alipay_wap`，不传则双通道查询 |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "tradeSn": "T2026020912000012345",
+    "status": "paid",
+    "platformSn": "4200001234567890",
+    "payAmount": 990,
+    "payTime": "2026-02-09T12:05:00.000Z",
+    "gateway": "wechat_native"
+  }
+}
+```
+
+- **status**：`paying` 未支付，`paid` 已支付，`closed` 已关闭/退款等。
+- **payAmount**：单位「分」。**payTime** 为支付完成时间。
+
+前端建议：每 3 秒轮询一次，最多约 60 次（约 3 分钟）；收到 `status: "paid"` 后停止轮询并更新订单/解锁内容。
+
+---
+
+### 3.4 按订单号查状态 `GET /api/payment/status/:orderSn`
+
+**路径参数**：`orderSn` 为创建订单返回的订单号。
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "orderSn": "20260209123456",
+    "status": "paid",
+    "paidAmount": 9.9,
+    "paidAt": "2026-02-09T12:05:00.000Z",
+    "paymentMethod": "wechat",
+    "tradeSn": "T2026020912000012345",
+    "productType": "section"
+  }
+}
+```
+
+- **status**：与业务一致：`created`、`paying`、`paid`、`closed`、`refunded` 等。
+
+---
+
+### 3.5 支付校验 `POST /api/payment/verify`
+
+**请求体**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | string | 订单号 |
+| paymentMethod | string | 支付方式 |
+| transactionId | string | 第三方交易号（可选） |
+
+**响应**：成功时 `code: 0`，失败时非 0；用于前端在回调不确定时的二次校验（具体逻辑由后端实现）。
+
+---
+
+## 四、支付平台异步通知（回调）
+
+对接方需在微信支付/支付宝商户后台配置「支付结果通知 URL」，且必须为 **公网 HTTPS**。当前项目约定路径如下（以 soul-api 域名为准）：
+
+| 支付方式 | 通知 URL | 说明 |
+|----------|----------|------|
+| 微信支付 | `https://your-api.com/api/payment/wechat/notify` | 统一下单/JSAPI/小程序等 |
+| 支付宝 | `https://your-api.com/api/payment/alipay/notify` | 异步 notify |
+| 微信转账 | `https://your-api.com/api/payment/wechat/transfer/notify` | 企业付款到零钱（若使用） |
+
+### 4.1 微信支付 notify
+
+- **方法**：POST  
+- **Content-Type**：`application/xml`  
+- **Body**：微信以 XML 推送，字段含 `return_code`、`result_code`、`out_trade_no`、`transaction_id`、`total_fee`、`time_end`、`sign` 等。  
+- **验签**：使用商户密钥对微信参数做 MD5 签名校验（见 next-project `lib/payment/wechat.ts` 中 `verifySign`）。  
+- **响应**：必须返回 XML，成功示例：  
+  `<xml><return_code><![CDATA[SUCCESS]]></return_code><return_msg><![CDATA[OK]]></return_msg></xml>`  
+  失败则返回 `return_code=FAIL`，否则微信会重试。
+
+**业务处理建议**（与 next-project 一致）：  
+1. 验签通过且 `result_code=SUCCESS` 后，用 `out_trade_no`（即本系统 tradeSn）查订单，更新为已支付、写入 `transaction_id`、`pay_time`。  
+2. 根据 `product_type` 开通全书或章节权限。  
+3. 若有推荐人，写分销表并更新 `pending_earnings`。  
+4. 响应必须在业务异常时仍返回成功 XML，避免微信重复通知。
+
+### 4.2 支付宝 notify
+
+- **方法**：POST  
+- **Content-Type**：`application/x-www-form-urlencoded`  
+- **Body**：表单键值对，含 `out_trade_no`、`trade_no`、`trade_status`、`total_amount`、`gmt_payment`、`sign` 等。  
+- **验签**：使用配置的 MD5 密钥校验（见 next-project `lib/payment/alipay.ts`）。  
+- **响应**：纯文本，成功返回 `success`，失败返回 `fail`。支付宝会多次重试直至收到 `success`。
+
+**业务处理**：与微信类似，以 `out_trade_no` 更新订单、开通权限、处理分销。
+
+---
+
+## 五、小程序支付
+
+### 5.1 下单 `GET/POST /api/miniprogram/pay`
+
+**请求体（JSON）**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| openId | string | 是 | 用户 openId |
+| productType | string | 是 | `section` / `fullbook` |
+| productId | string | 是 | 章节 ID 或 `fullbook` |
+| amount | number | 是 | 金额（元） |
+| description | string | 建议 | 订单描述 |
+| userId | string | 是 | 用户 ID |
+
+**响应**
+
+```json
+{
+  "success": true,
+  "data": {
+    "orderSn": "MP20260204123456789012",
+    "prepayId": "wx...",
+    "payParams": {
+      "timeStamp": "...",
+      "nonceStr": "...",
+      "package": "prepay_id=...",
+      "signType": "MD5",
+      "paySign": "..."
+    }
+  }
+}
+```
+
+小程序端用 `payParams` 调起 `wx.requestPayment`。
+
+### 5.2 小程序支付通知 `POST /api/miniprogram/pay/notify`
+
+与「微信支付 notify」同一套规范（XML 入参、XML 成功响应）。商户后台配置的「支付结果通知 URL」填 soul-api 的 `/api/miniprogram/pay/notify` 或统一使用 `/api/payment/wechat/notify` 均可，需与后端实现一致（按订单来源更新对应订单与权限）。
+
+---
+
+## 六、配置项
+
+### 6.1 管理端 / 配置接口
+
+- **GET /api/config**：返回全站配置，其中 **paymentMethods** 用于前端展示支付方式及微信/支付宝相关配置（如微信群二维码、商户信息等）。  
+- 支付开关、商户号、密钥等建议放在服务端环境变量或管理端「支付配置」中，不通过公开接口暴露密钥。
+
+### 6.2 环境变量（参考 next-project）
+
+后端若自实现支付，可参考以下变量（soul-api 当前未在 .env.example 中列出，对接时按需增加）：
+
+**微信**
+
+- `WECHAT_APPID` / `WECHAT_SERVICE_APPID`：公众号/服务号 AppID  
+- `WECHAT_APP_SECRET` / `WECHAT_SERVICE_SECRET`  
+- `WECHAT_MCH_ID`：商户号  
+- `WECHAT_MCH_KEY`：商户 API 密钥  
+
+**支付宝**
+
+- `ALIPAY_APP_ID` / `ALIPAY_PID`  
+- `ALIPAY_PRIVATE_KEY` / `ALIPAY_PUBLIC_KEY` 或 `ALIPAY_MD5_KEY`  
+- `ALIPAY_SELLER_EMAIL`  
+
+**应用**
+
+- `NEXT_PUBLIC_BASE_URL` 或等价「站点 base URL」：用于拼装 notify/return 地址。
+
+---
+
+## 七、订单与数据库（参考）
+
+- **orders 表**：`id`、`order_sn`、`user_id`、`open_id`、`product_type`、`product_id`、`amount`、`description`、`status`、`transaction_id`、`pay_time`、`referral_code`、`referrer_id`、`created_at`、`updated_at`。  
+- **status**：`created` → 创建，`paid` → 已支付，`expired`/`cancelled` 等由业务定义。  
+- 创建订单时可将 **tradeSn** 写入 `transaction_id`，支付回调里用微信/支付宝的「商户订单号」即 tradeSn 查单并更新为 `transaction_id`（平台交易号）、`pay_time`、`status=paid`。
+
+---
+
+## 八、错误与注意事项
+
+1. **签名**：所有微信/支付宝回调必须先验签再执行业务，否则存在伪造风险。  
+2. **幂等**：同一笔订单可能被多次通知，更新订单与佣金前应判断当前状态，避免重复加款。  
+3. **响应**：notify 接口必须在处理完（或确认可稍后处理）后按平台要求返回成功（微信 XML 成功、支付宝 `success`），再异步做后续逻辑，避免平台反复回调。  
+4. **金额**：微信为「分」，支付宝为「元」；内部建议统一用「分」存储，与 next-project 一致。  
+5. **soul-api 现状**：当前 payment/miniprogram 相关 handler 为占位实现（直接返回 success），完整逻辑需按本文档与 next-project 实现对齐后上线。
+
+---
+
+*文档根据项目代码反向整理，若与最新代码不一致，以实际仓库为准。*
diff --git a/开发文档/5、接口/接口与提现.md b/开发文档/5、接口/接口与提现.md
new file mode 100644
index 00000000..58cbe96b
--- /dev/null
+++ b/开发文档/5、接口/接口与提现.md
@@ -0,0 +1,11 @@
+# 接口与提现（合并自 接口定义规范、提现功能完整技术文档）
+
+## 接口规范
+
+RESTful，JSON 返回。基础 URL 开发 localhost:3000/api，生产 soul.quwanzhi.com/api。统一格式：`{ code, message, data }`。
+
+## 提现功能
+
+微信支付商家转账到零钱 API，签名算法、加解密、完整实现、测试验证。流程：用户申请 → 审核 → 调 API → 回调更新状态。
+
+详见原《接口定义规范》《提现功能完整技术文档》。
diff --git a/开发文档/5、接口/配置清单-完整版.md b/开发文档/5、接口/配置清单-完整版.md
new file mode 100644
index 00000000..1ca859a7
--- /dev/null
+++ b/开发文档/5、接口/配置清单-完整版.md
@@ -0,0 +1,205 @@
+# Soul创业实验 - API密钥与配置清单
+
+> 最后更新: 2026-01-25  
+> 维护人: 卡若  
+> ⚠️ 本文件包含敏感信息，请勿公开
+
+---
+
+## 一、企业信息
+
+| 项目 | 值 |
+|:---|:---|
+| **企业名称** | 泉州市卡若网络技术有限公司 |
+| **联系电话** | 15880802661 |
+| **微信号** | 28533368 |
+| **邮箱** | zhiqun@qq.com / zhengzhiqun@vip.qq.com |
+
+---
+
+## 二、微信生态
+
+### 2.1 小程序（Soul创业实验）
+
+| 项目 | 值 | 备注 |
+|:---|:---|:---|
+| **AppID** | `wxb8bbb2b10dec74aa` | 小程序ID |
+| **AppSecret** | `3c1fb1f63e6e052222bbcead9d07fe0c` | 小程序密钥 |
+| **支付绑定状态** | 🟡 审核中 | 2026-01-25 09:43:59 提交 |
+
+### 2.2 服务号（玩值）
+
+| 项目 | 值 | 备注 |
+|:---|:---|:---|
+| **AppID** | `wx7c0dbf34ddba300d` | 服务号AppID |
+| **AppSecret** | `f865ef18c43dfea6cbe3b1f1aebdb82e` | 服务号密钥 |
+| **支付绑定状态** | ✅ 已绑定 | 绑定AppID: wx3e31b068be59ddc1 |
+
+### 2.3 网站应用
+
+| 项目 | 值 |
+|:---|:---|
+| **AppID** | `wx432c93e275548671` |
+| **AppSecret** | `25b7e7fdb7998e5107e242ebb6ddabd0` |
+
+### 2.4 微信支付
+
+| 项目 | 值 | 备注 |
+|:---|:---|:---|
+| **商户号** | `1318592501` | 主体: 泉州市卡若网络技术有限公司 |
+| **API密钥(v2)** | `wx3e31b068be59ddc131b068be59ddc2` | 32位 |
+| **MP文件验证码** | `SP8AfZJyAvprRORT` | |
+| **支付回调地址** | `https://soul.quwanzhi.com/api/miniprogram/pay/notify` | |
+
+#### 已绑定AppID
+
+| AppID | 类型 | 状态 |
+|:---|:---|:---|
+| `wx3e31b068be59ddc1` | 服务号 | ✅ 已关联 |
+| `wxb8bbb2b10dec74aa` | 小程序 | 🟡 审核中 |
+
+---
+
+## 三、支付宝
+
+| 项目 | 值 |
+|:---|:---|
+| **PID** | `2088511801157159` |
+| **MD5密钥** | `lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp` |
+| **账户** | zhengzhiqun@vip.qq.com |
+
+---
+
+## 四、云服务
+
+### 4.1 腾讯云
+
+| 项目 | 值 |
+|:---|:---|
+| **APPID** | `1251077262` |
+| **SecretId** | `AKIDjc6yO3nPeOuK2OKsJPBBVbTiiz0aPNHl` |
+| **SecretKey** | *(见用户规则)* |
+
+### 4.2 阿里云
+
+| 项目 | 值 |
+|:---|:---|
+| **AccessKey ID** | `LTAI5t9zkiWmFtHG8qmtdysW` |
+| **AccessKey Secret** | `xxjXnZGLNvA2zDkj0aEBSQm3XZAaro` |
+
+---
+
+## 五、数据库
+
+### 5.1 腾讯云MySQL（生产环境）
+
+| 项目 | 值 |
+|:---|:---|
+| **主机** | `56b4c23f6853c.gz.cdb.myqcloud.com` |
+| **端口** | `14413` |
+| **数据库** | `soul_miniprogram` |
+| **用户名** | `cdb_outerroot` |
+| **密码** | `Zhiqun1984` |
+| **字符集** | `utf8mb4` |
+
+#### 数据库表
+
+| 表名 | 说明 |
+|:---|:---|
+| `users` | 用户表 |
+| `orders` | 订单表 |
+| `referral_bindings` | 推广绑定关系 |
+| `match_records` | 匹配记录 |
+| `system_config` | 系统配置 |
+| `chapters` | **章节内容表（新）** |
+
+### 5.2 卡若私域数据库（内网）
+
+| 项目 | 值 |
+|:---|:---|
+| **主机** | `10.88.182.62` |
+| **端口** | `3306` |
+| **用户名** | `root` |
+| **密码** | `Vtka(agu)-1` |
+
+---
+
+## 六、AI服务
+
+### 6.1 v0 API
+
+| 项目 | 值 |
+|:---|:---|
+| **API地址** | `https://api.v0.dev/v1` |
+| **API Key** | `v1:C6mw1SlvXsJdlO4VFEXSQEVf:519gA0DPqIMbjvfMh7CXf4B2` |
+| **默认模型** | `claude-opus` |
+
+---
+
+## 七、开发工具
+
+### 7.1 GitHub
+
+| 项目 | 值 |
+|:---|:---|
+| **Token** | `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` |
+
+---
+
+## 八、项目部署信息
+
+| 项目 | 值 |
+|:---|:---|
+| **域名** | `soul.quwanzhi.com` |
+| **协议** | HTTPS |
+| **服务器** | 宝塔面板 |
+| **部署方式** | GitHub Webhook 自动部署 |
+
+---
+
+## 九、邮箱账户
+
+| 邮箱 | 密码 |
+|:---|:---|
+| `zhiqun@qq.com` | `#vtk();1984` |
+| `zhengzhiqun@vip.qq.com` | `#vtk();1984` |
+| `15880802661@qq.com` | `#vtk();1984` |
+
+---
+
+## 十、配置代码引用
+
+### 小程序支付配置
+
+```typescript
+// lib/payment/wechat-miniprogram.ts
+const WECHAT_PAY_CONFIG = {
+  appId: 'wxb8bbb2b10dec74aa',        // 小程序AppID
+  appSecret: '3c1fb1f63e6e052222bbcead9d07fe0c', // 小程序AppSecret
+  mchId: '1318592501',                 // 商户号
+  mchKey: 'wx3e31b068be59ddc131b068be59ddc2', // API密钥(v2)
+  notifyUrl: 'https://soul.quwanzhi.com/api/miniprogram/pay/notify',
+}
+```
+
+### 数据库配置
+
+```typescript
+// lib/db.ts
+const DB_CONFIG = {
+  host: '56b4c23f6853c.gz.cdb.myqcloud.com',
+  port: 14413,
+  user: 'cdb_outerroot',
+  password: 'Zhiqun1984',
+  database: 'soul_miniprogram',
+  charset: 'utf8mb4',
+}
+```
+
+---
+
+## 更新日志
+
+| 日期 | 更新内容 |
+|:---|:---|
+| 2026-01-25 | 创建完整配置清单；小程序支付绑定申请中；章节表迁移完成 |
diff --git a/开发文档/6、后端/README.md b/开发文档/6、后端/README.md
new file mode 100644
index 00000000..a361e469
--- /dev/null
+++ b/开发文档/6、后端/README.md
@@ -0,0 +1,24 @@
+# 6、后端（soul-api）
+
+> `soul-api`（Go + Gin + GORM）相关文档。路由分组与鉴权以代码 `internal/router` 与 `.cursor/skills/api-dev/SKILL.md` 为准。
+
+## 本目录文件
+
+| 文件 | 说明 |
+|------|------|
+| [后端架构.md](./后端架构.md) | 服务架构与模块 |
+| [后端开发规范.md](./后端开发规范.md) | 编码、路由、响应约定 |
+| [内容创建问题修复说明.md](./内容创建问题修复说明.md) | 内容创建专项 |
+| [soul-admin与Mycontent-temp内容页对比.md](./soul-admin与Mycontent-temp内容页对比.md) | 管理端内容页对比 |
+
+## 算法与业务规则
+
+| 路径 | 说明 |
+|------|------|
+| [**算法/**](./算法/) | RFM、用户旅程阶段、找伙伴匹配与配额、存客宝留资同步（**一算法一文档**） |
+
+## 历史说明
+
+早期计划在本文档目录编写的《管理端鉴权设计》《miniprogram 接口补全说明》若未落盘，请以 **仓库 `.cursor/rules/soul-api.mdc`、Skill `api-dev`** 及 `5、接口/API接口完整文档.md` 为准。
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/6、后端/image.png b/开发文档/6、后端/image.png
new file mode 100644
index 00000000..b26ffbf4
Binary files /dev/null and b/开发文档/6、后端/image.png differ
diff --git a/开发文档/6、后端/soul-admin与Mycontent-temp内容页对比.md b/开发文档/6、后端/soul-admin与Mycontent-temp内容页对比.md
new file mode 100644
index 00000000..eb4fc624
--- /dev/null
+++ b/开发文档/6、后端/soul-admin与Mycontent-temp内容页对比.md
@@ -0,0 +1,53 @@
+# soul-admin 与 Mycontent-temp 内容管理页面对比
+
+> 目标：soul-admin 为功能基准，新建/编辑样式功能要一模一样。
+
+## 一、新建章节弹窗
+
+| 项目 | soul-admin | Mycontent-temp |
+|------|------------|---------------|
+| 弹窗宽度 | max-w-2xl | max-w-2xl |
+| 章节ID | ✅ | ✅ |
+| 价格 | ✅ | ✅ |
+| 文章类型（普通版/增值版） | ✅ | ❌ 无 |
+| 章节标题 | ✅ | ✅ |
+| 所属篇 | ✅ | ✅ |
+| 所属章 | ✅ | ✅ |
+| 内容 | Markdown Textarea | Markdown Textarea |
+| 免费 | ❌ 无 | ❌ 无 |
+| 最新新增 | ❌ 无 | ❌ 无 |
+| 小程序直推 | ❌ 无 | ❌ 无 |
+| 热度分 | ❌ 无 | ❌ 无 |
+
+**结论**：新建与编辑不一致。编辑有 RichEditor、免费、最新新增、置顶、热度分，新建用 Textarea 且缺这些字段。
+
+## 二、编辑章节弹窗
+
+| 项目 | soul-admin | Mycontent-temp |
+|------|------------|---------------|
+| 弹窗宽度 | max-w-4xl | max-w-4xl |
+| 内容 | RichEditor | RichEditor |
+| 文章类型 | ✅ | ❌ 无 |
+| 免费 | ✅ | ✅ |
+| 最新新增 | ✅ | ✅ |
+| 小程序直推 | ✅ | ✅ |
+| 热度分 | ✅ | ✅ |
+| 付款记录 | ✅ | ✅ |
+| editionStandard/editionPremium 读取 | ✅ | ❌ 无 |
+
+**结论**：soul-admin 编辑功能完整；Mycontent-temp 缺文章类型。
+
+## 三、执行项（soul-admin）✅ 已完成
+
+1. **新建弹窗**：与编辑弹窗样式功能统一 ✅
+   - 布局改为 max-w-4xl、flex flex-col
+   - 内容改为 RichEditor
+   - 补充：免费、最新新增、小程序直推、热度分、文章类型
+   - 字段顺序与编辑一致
+
+2. **文章详情**：内容区（RichEditor）处理完善 ✅
+   - 新建、编辑均使用 RichEditor，支持 @人物、#标签、图片上传
+
+3. **后端 db_book**：支持新建章节 Create ✅
+   - 新增 body 字段：PartID、PartTitle、ChapterID、ChapterTitle、HotScore
+   - 新建时 FirstOrCreate 逻辑：不存在则 Create，存在则 Updates
diff --git a/开发文档/6、后端/内容创建问题修复说明.md b/开发文档/6、后端/内容创建问题修复说明.md
new file mode 100644
index 00000000..a21ec1ea
--- /dev/null
+++ b/开发文档/6、后端/内容创建问题修复说明.md
@@ -0,0 +1,93 @@
+# 内容创建问题修复说明
+
+> 问题：souladmin 添加内容后显示「创建成功」，但目录和数据库未增加，前端也未显示。
+
+## 根因分析
+
+1. **两套后台数据源不一致**
+   - souladmin.quwanzhi.com 调用 soulapi.quwanzhi.com（Go API）
+   - soul.quwanzhi.com/admin 使用 Next.js API，list 此前仅从 bookData（静态）读取
+   - 新建章节写入数据库，但 list 不查库，导致新建内容不显示
+
+2. **PUT 创建未完整支持 partId/chapterId**
+   - 新建章节时 partId、chapterId、partTitle、chapterTitle 未正确写入数据库
+
+## 已做修复
+
+### 1. 修改 `/api/db/book` list 接口
+- **原逻辑**：仅从 bookData 读取
+- **现逻辑**：优先从数据库 chapters 表读取，再与 bookData 合并
+- **效果**：新建章节会立即出现在列表中
+
+### 2. 修改 PUT 接口支持新建章节
+- 支持 body 传入 `partId`、`chapterId`、`partTitle`、`chapterTitle`、`isFree`
+- 新建章节能正确写入数据库
+
+### 3. 在 book-data 中新增 9.15
+- 章节 ID: 9.15  
+- 标题: 第102场｜今年第一个红包你发给谁  
+- 文件: book/第四篇｜真实的赚钱/第9章｜我在Soul上亲访的赚钱案例/9.15 第102场｜今年第一个红包你发给谁.md  
+
+### 4. soul-admin 改用 soul.quwanzhi.com 作为 API
+- 修改 soul-admin 的 API 基址：soulapi → soul.quwanzhi.com
+- 在 Next.js 中为 souladmin.quwanzhi.com 配置 CORS
+
+## 部署步骤
+
+### 步骤 1：部署 soul 主站（小型宝塔）
+
+```bash
+cd /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验
+# 按 .cursorrules 中的流程执行
+pnpm build
+# 然后执行部署脚本
+```
+
+### 步骤 2：同步 9.15 到数据库
+
+部署后访问 soul.quwanzhi.com/admin，在内容管理页面点击「同步到数据库」，将包含 9.15 的 bookData 同步进库。
+
+### 步骤 3：部署修改后的 soul-admin（KR 宝塔）
+
+```bash
+# 将 一场soul的创业实验-永平 中的 soul-admin/dist 上传到 KR 宝塔
+cd /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平
+tar -czf soul-admin-dist.tar.gz soul-admin/dist
+sshpass -p 'Zhiqun1984' scp -P 22022 soul-admin-dist.tar.gz root@43.139.27.93:/tmp/
+sshpass -p 'Zhiqun1984' ssh -p 22022 root@43.139.27.93 "
+  cd /www/wwwroot/自营/soul-admin
+  rm -rf dist.bak
+  mv dist dist.bak 2>/dev/null || true
+  tar -xzf /tmp/soul-admin-dist.tar.gz -C .
+  rm /tmp/soul-admin-dist.tar.gz
+"
+```
+
+### 步骤 4：校验
+
+1. 打开 souladmin.quwanzhi.com/content  
+2. 新建章节，确认创建后列表中立即出现  
+3. 刷新 soul.quwanzhi.com 主站，确认新章节可读
+
+## 注意事项
+
+- souladmin 现改为调用 soul.quwanzhi.com，不再调用 soulapi（Go），需确保 soul 主站可用
+- 若仍需使用 Go API，需在 soul-api 源码中修复 list/create 逻辑
+
+---
+
+## 内容上传 API（供科室/Skill 调用）
+
+- **地址**：`POST /api/content/upload`
+- **Content-Type**：`application/json`
+- **Body 字段**：
+  - `title`（必填）：节标题
+  - `price`：定价，默认 1
+  - `content`：正文（Markdown 或 HTML）
+  - `format`：`markdown` | `html`，默认 `markdown`
+  - `images`：图片 URL 数组；正文中可用 `{{image_0}}`、`{{image_1}}` 占位，会替换为对应图片的 Markdown 图链
+  - `partId`、`partTitle`、`chapterId`、`chapterTitle`：归属篇/章，可选
+  - `isFree`：是否免费，默认 false
+  - `sectionId`：指定节 ID，不传则自动生成（如 `upload.标题slug.时间戳`）
+- **返回**：`{ success, id, message, title, price, isFree, wordCount }`
+- 写入数据库 `chapters` 表，list/目录会从库中读取并去重显示。
diff --git a/开发文档/6、后端/后端开发规范.md b/开发文档/6、后端/后端开发规范.md
new file mode 100644
index 00000000..75b360a1
--- /dev/null
+++ b/开发文档/6、后端/后端开发规范.md
@@ -0,0 +1,64 @@
+# 后端开发规范 (Backend Specs) - 智能自生长文档
+
+> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“Python 后端专家”角色，生成高效、规范的 FastAPI 代码。
+
+## 1. 基础上下文 (The Two Basic Files)
+### 1.1 角色档案：卡若 (Karuo)
+- **核心**：开发快、性能好、支持 AI。
+- **习惯**：优先使用异步 (`async/await`)，强制类型提示 (`Type Hints`)。
+
+### 1.2 技术栈
+- **语言**：Python 3.10+。
+- **框架**：FastAPI (Web), Pydantic (Validation), LangChain (AI)。
+- **数据**：Motor (Async Mongo), Redis。
+
+## 2. 开发规范核心 (Master Content)
+### 2.1 代码规范
+- **风格**：遵循 PEP 8，使用 Black 格式化。
+- **类型**：**强制 Type Hints** (如 `def get_user(id: int) -> User:`)。
+- **注释**：**强制中文注释**，解释“业务逻辑”与“AI 处理流程”。
+- **结构**：
+  - `app/routers`: 路由
+  - `app/models`: Pydantic 模型
+  - `app/services`: 业务逻辑
+  - `app/core`: 配置与工具
+
+### 2.2 AI 与安全规范
+- **AI 调用**：所有 LLM 调用必须封装在 Service 层，并包含重试机制与超时控制。
+- **安全**：
+  - **命令执行**：严禁使用 `os.system`，必须使用 `subprocess` 并校验参数。
+  - **SQL/NoSQL**：使用 ORM 或参数化查询，防止注入。
+
+### 2.3 异常与日志
+- **异常**：使用 FastAPI `HTTPException` 或自定义 Exception Handler。
+- **日志**：使用 `loguru` 或 Python 标准 `logging`，必须记录 Traceback。
+
+### 2.4 依赖管理
+- **工具**：`pip` 或 `poetry`。
+- **原则**：提交代码前更新 `requirements.txt` 或 `pyproject.toml`。
+
+## 3. AI 协作指令 (Expanded Function)
+**角色**：你是我（卡若）的 Python 架构师。
+**任务**：
+1.  **代码实现**：生成 FastAPI 的 Router/Model/Service 代码。
+2.  **AI 集成**：编写 LangChain 调用逻辑或向量检索代码。
+3.  **逻辑图解**：用 Mermaid 展示异步处理流程。
+
+### 示例 Mermaid (类图)
+\`\`\`mermaid
+classDiagram
+    class UserRouter {
+        +get_user()
+        +create_user()
+    }
+    class UserService {
+        +verify_token()
+        +process_ai_request()
+    }
+    class VectorStore {
+        +search_similarity()
+        +add_documents()
+    }
+    UserRouter --> UserService
+    UserService --> VectorStore
+\`\`\`
diff --git a/开发文档/6、后端/后端架构.md b/开发文档/6、后端/后端架构.md
new file mode 100644
index 00000000..16c5f9dd
--- /dev/null
+++ b/开发文档/6、后端/后端架构.md
@@ -0,0 +1,68 @@
+# 后端架构与业务逻辑
+
+**我是卡若。**
+
+后端不仅仅是读写数据库，它是**业务逻辑的翻译官**。
+
+我们要把“私域引流”、“内容分发”这些生意话术，翻译成代码逻辑。
+
+## 1. 核心业务模块
+
+### 1.1 内容服务 (Content Service)
+这是最基础的。
+-   **逻辑**:
+    -   扫描 `book/` 目录，生成目录树 (Tree)。
+    -   解析 Markdown，提取 Frontmatter (标题、日期、标签)。
+    -   **缓存策略**: 既然是读文件，IO 慢。要在内存里做一个 LRU 缓存，读取一次后由内存直接返回，直到文件发生变更。
+
+### 1.2 配置服务 (Config Service)
+我的微信号、群二维码、价格，这些东西会变，不能写死在代码里。
+-   **实现**:
+    -   一个 `config/settings.json` 文件（或者未来的 MongoDB `settings` 表）。
+    -   接口: `GET /api/config`。
+    -   前端拿到配置，动态展示微信号。
+
+### 1.3 引流服务 (Lead Service)
+这是赚钱的关键。
+-   **埋点逻辑**:
+    -   记录 `UserView` (用户看了哪章)。
+    -   记录 `UserClick` (用户点了“加微信”)。
+    -   虽然不存库，但可以先打到日志文件里，或者调一个飞书的 Webhook，实时通知我“有人对这章感兴趣”。
+
+## 2. 接口设计原则
+
+-   **RESTful**: 资源导向。`GET /articles`, `GET /articles/:id`。
+-   **统一响应体**:
+    \`\`\`typescript
+    interface ApiResponse<T> {
+      code: number; // 0 成功, >0 错误
+      data: T;
+      msg: string;
+    }
+    \`\`\`
+
+## 3. 目录结构 (后端专用)
+
+\`\`\`
+app/api/
+├── content/           # 内容相关
+├── config/            # 全局配置
+└── track/             # 埋点上报
+
+lib/
+├── content/
+│   ├── parser.ts      # Markdown 解析器
+│   └── cache.ts       # 内存缓存
+├── config/
+│   └── loader.ts      # 配置加载器
+└── db/                # 数据库连接 (预留)
+\`\`\`
+
+## 4. 扩展性预留
+
+-   **鉴权中间件**: 现在是裸奔，未来加 `middleware.ts` 拦截 `/admin` 开头的请求。
+-   **任务队列**: 未来如果生成文档太慢，就扔到 Redis 队列里异步处理。
+
+---
+**卡若说：**
+后端代码要写得像瑞士军刀一样，功能明确，结实耐用。
diff --git a/开发文档/6、后端/小程序支付参数.png b/开发文档/6、后端/小程序支付参数.png
new file mode 100644
index 00000000..16d1881b
Binary files /dev/null and b/开发文档/6、后端/小程序支付参数.png differ
diff --git a/开发文档/6、后端/算法/README.md b/开发文档/6、后端/算法/README.md
new file mode 100644
index 00000000..676013c6
--- /dev/null
+++ b/开发文档/6、后端/算法/README.md
@@ -0,0 +1,13 @@
+# 后端业务算法说明
+
+> **以代码为准**：实现变更时请同步更新本目录下对应文档。  
+> 代码位置：`soul-api/internal/handler/`（见下表）。
+
+| 文档 | 说明 | 主要代码 | HTTP 入口（管理端 / 公共） |
+|------|------|----------|---------------------------|
+| [算法-RFM用户价值分层.md](./算法-RFM用户价值分层.md) | RFM 与 RFM+ 综合分、分层档位 | `admin_rfm.go`、`db.go` | `GET /api/db/users/rfm`、`GET /api/db/users/rfm-single`；用户列表内嵌 RFM |
+| [算法-用户旅程阶段统计.md](./算法-用户旅程阶段统计.md) | 各阶段人数与按阶段拉用户 | `admin_rfm.go` | `GET /api/db/users/journey-stats`、`GET /api/db/users/journey-users` |
+| [算法-找伙伴匹配与配额.md](./算法-找伙伴匹配与配额.md) | 匹配池、选人逻辑、次数配额 | `match.go`、`user.go`（配额下发） | `POST /api/match/users`、`POST /api/miniprogram/match/users`、`GET /api/match/config` |
+| [算法-存客宝找伙伴留资同步.md](./算法-存客宝找伙伴留资同步.md) | 匹配结果推存客宝（非站内选人） | `ckb.go` | `POST /api/ckb/match`、`POST /api/miniprogram/ckb/match` |
+
+**说明**：口语中的「IFM」与本项目代码无对应实现；用户价值分层以 **RFM / RFM+** 为准（见 RFM 文档）。
diff --git a/开发文档/6、后端/算法/算法-RFM用户价值分层.md b/开发文档/6、后端/算法/算法-RFM用户价值分层.md
new file mode 100644
index 00000000..3490657a
--- /dev/null
+++ b/开发文档/6、后端/算法/算法-RFM用户价值分层.md
@@ -0,0 +1,67 @@
+# RFM 用户价值分层
+
+## 1. 目的
+
+对「有订单」用户做价值排序与分层（Are you good），供管理端 RFM 排行与用户列表展示。实现：`soul-api/internal/handler/admin_rfm.go`（及用户列表中的轻量版：`db.go`）。
+
+## 2. 订单口径
+
+参与聚合的订单需满足：
+
+```text
+orders.status IN ('paid', 'success', 'completed')
+```
+
+单笔金额汇总为 **Monetary（M）**，订单笔数为 **Frequency（F）**，最近一次订单时间为 **Recency（R）** 的起点。
+
+## 3. 子分归一化（0～100）
+
+在同一批计算中，先求全体用户的 `maxRecency`（天数）、`maxFreq`（笔数）、`maxMonetary`（金额）：
+
+- **R 分**：`rScore = (1 - recencyDays / maxRecency) * 100`（`maxRecency > 0` 时）
+- **F 分**：`fScore = frequency / maxFreq * 100`（`maxFreq > 0` 时）
+- **M 分**：`mScore = monetary / maxMonetary * 100`（`maxMonetary > 0` 时）
+
+推荐分、轨迹分同理按 `maxReferral`、`maxTrack` 归一化，且不超过 100（`min(ratio*100, 100)`）。
+
+## 4. 全量 RFM 排行：`GET /api/db/users/rfm`（RFM+ 六维）
+
+函数：`calcRFMScoreForUserExt`
+
+| 维度 | 权重 | 含义 |
+|------|------|------|
+| R | 25% | 距最近付费天数（越近越高） |
+| F | 20% | 付费订单笔数 |
+| M | 20% | 累计付费金额 |
+| 推荐人数 | 15% | `users.referral_count`（批内 max 归一化） |
+| 行为轨迹 | 10% | `user_tracks` 条数（批内 max 归一化） |
+| 资料完善 | 10% | `phone` / `mbti` / `industry` 中 **至少 2 项有值** 则记 100，否则 0 |
+
+最终：`total = 加权和`，`math.Round(total)`，范围约 0～100。
+
+## 5. 分层：`calcRFMLevel(score)`
+
+| 档位 | 条件 |
+|------|------|
+| S | score ≥ 85 |
+| A | score ≥ 70 |
+| B | score ≥ 50 |
+| C | score ≥ 30 |
+| D | score < 30 |
+
+## 6. 单用户：`GET /api/db/users/rfm-single?userId=`
+
+对有订单用户计算 **三维度 RFM**（`calcRFMScoreForUser`，不合并推荐/轨迹/资料），再套同一套 `calcRFMLevel`。无订单则返回 `rfm: null`（以实际 JSON 为准）。
+
+## 7. 与用户列表分页的差异（重要）
+
+管理端用户列表在 `db.go` 中对**当前页**用户调用 `calcRFMScoreForUser`（内部为 `calcRFMScoreForUserExt(..., rfmExtras{}, 0, 0)`）：
+
+- **仅使用 R、F、M 三维**（推荐、轨迹、资料权重为 0）。
+- 与 `GET /api/db/users/rfm` 的 **RFM+ 六维** 分数可能不一致。
+
+运营与产品对比「列表里的 RFM」与「RFM 排序页」时需注意上述差异。若需统一，属产品改动（需在列表接口批量拉轨迹/推荐并调 `calcRFMScoreForUserExt`）。
+
+## 8. 相关前端
+
+管理端用户列表 RFM 列与排序：`soul-admin` 中 `UsersPage.tsx`（`/api/db/users/rfm` 与列表接口切换）。
diff --git a/开发文档/6、后端/算法/算法-存客宝找伙伴留资同步.md b/开发文档/6、后端/算法/算法-存客宝找伙伴留资同步.md
new file mode 100644
index 00000000..84becbaa
--- /dev/null
+++ b/开发文档/6、后端/算法/算法-存客宝找伙伴留资同步.md
@@ -0,0 +1,33 @@
+# 存客宝：找伙伴留资同步
+
+## 1. 定位
+
+`CKBMatch` **不负责**站内匹配选人（见 [算法-找伙伴匹配与配额.md](./算法-找伙伴匹配与配额.md)）。本接口将用户提交的匹配相关留资 **转发到存客宝 HTTP API**，并配合本地线索表做去重与结果回写。
+
+实现：`soul-api/internal/handler/ckb.go` 中 `CKBMatch`。
+
+## 2. 路由
+
+- `POST /api/ckb/match`
+- `POST /api/miniprogram/ckb/match`
+
+## 3. 入参（JSON）
+
+包含但不限于：`matchType`、`phone`、`wechat`、`userId`、`nickname`、`matchedUser`（可为结构化对象）。**手机号与微信号至少填一个**，否则 400。
+
+## 4. 流程摘要
+
+1. `nickname` 默认 `"-"`。
+2. **5 分钟去重**：`existsUnifiedLeadRecent(..., match, userId, matchSource, phone, wechat, 5*time.Minute)`，其中 `matchSource = "match_" + matchType`。若命中，直接返回成功并带 `repeatedSubmit: true`。
+3. `ckbLeadSaveUnified` 写入统一线索记录，得到 `leadID`。
+4. 组装存客宝请求：`timestamp`、`source`（固定文案如「创业实验-找伙伴匹配」）、`tags`、`siteTags`、`remark`、`phone`/`wechatId`/`name`、`apiKey`、`sign`（`ckbSign`）。
+5. `portrait`：`type: 4`，`sourceData` 含 `action: match`、`matchType`、`matchLabel`、`userId`、`device`、`timestamp`；`uniqueId` 含手机、微信与时间戳拼接。
+6. `http.Post(ckbAPIURL, ...)`；网络错误或非 200 业务码时仍可能对用户返回「提交成功」，同时 `markLeadPushFailed` / `applyCkbLeadPushOutcome` 记录后台状态（与 `CKBJoin` 等一致的用户侧友好策略）。
+
+## 5. 配置
+
+`ckbAPIURL`、`ckbAPIKey` 等来自环境/配置（见 `ckb.go` 包级变量与部署说明），不在此重复。
+
+## 6. 运维提示
+
+日志关键字：`[CKBMatch]`。排查时对照存客宝返回 `code`/`message` 与本地线索表推送状态字段。
diff --git a/开发文档/6、后端/算法/算法-找伙伴匹配与配额.md b/开发文档/6、后端/算法/算法-找伙伴匹配与配额.md
new file mode 100644
index 00000000..7556b646
--- /dev/null
+++ b/开发文档/6、后端/算法/算法-找伙伴匹配与配额.md
@@ -0,0 +1,52 @@
+# 找伙伴：匹配与配额
+
+实现：`soul-api/internal/handler/match.go`；配额在用户信息等接口中下发参见 `user.go`。
+
+## 1. 接口
+
+- `POST /api/match/users`、`POST /api/miniprogram/match/users`：`MatchUsers`
+- `GET /api/match/config`、`GET /api/miniprogram/match/config`：匹配类型与 `match_config`
+
+## 2. 发起前校验
+
+1. 用户存在。
+2. 用户至少填写 **手机号或微信号**（其一非空），否则 `ERR_PROFILE_INCOMPLETE`。
+3. **配额**：若 `user.has_full_book` 为真，跳过配额；否则 `RemainToday <= 0` 则 `QUOTA_EXCEEDED`。
+
+## 3. 匹配次数配额 `GetMatchQuota`
+
+- **免费次数**：来自 `system_config.config_key = 'match_config'` 的 JSON 字段 `freeMatchLimit`；经 `normalizeFreeMatchLimit`：**大于 1 时按 1 生效**（终身免费匹配最多 1 次，不按自然日重置）。
+- **已购次数**：`orders` 中 `user_id` 匹配、`product_type = 'match'`、`status = 'paid'` 的笔数计为 `purchasedTotal`。
+- **已用次数**：`match_records` 全量条数相对免费额度超出部分，与已购对比取逻辑上的「已用已购」`purchasedUsed`，得 `purchasedRemain`、`freeRemain`（字段名 `freeRemainToday` / `remainToday` 为历史命名，语义为**当前剩余可匹配次数**）。
+- **今日统计**：`matchesUsedToday` 为当日 `match_records` 条数，仅作统计展示。
+
+## 4. 候选池 `poolSettings`（`match_config` JSON）
+
+从 `poolSettings` 读取：
+
+- `poolSource`：字符串或字符串数组，多选为 **并集**（OR）。取值示例：`vip`、`complete`、`all`。
+  - `vip`：`is_vip = 1 AND vip_expire_date > NOW()`
+  - `complete`：资料 SQL（手机号 + 非默认昵称 + 头像，见代码常量 `completeProfileSQL`）
+  - `all`：有手机或微信即可
+  - 若未配置有效 OR 条件，回退为仅 VIP。
+- `matchType == 'partner'`（找伙伴）且池子中 **不含** `vip` 与 `all` 时，**强制追加** VIP 条件。
+- 可选开关：`requirePhone`、`requireNickname`、`requireAvatar`、`requireBusiness`（供需字段非空）。
+
+## 5. 排除与排序、选人
+
+- 排除：**当天**已向之匹配过的 `matched_user_id`（`match_records`，发起者 `user_id`，`created_at >= CURDATE()`）。
+- 查询：`id != 发起者`，上述池子与过滤，`ORDER BY created_at DESC`，**LIMIT 20**。
+- **选人**：非真随机。若候选数 > 1：`idx = users[0].CreatedAt.Unix() % len(users)`，取 `users[idx]`（与列表首条创建时间相关）。
+
+## 6. 返回中的「匹配度」与兴趣点
+
+- `matchScore = 80 + (matchedUser.created_at.Unix() % 20)`：**展示用**，非相似度模型。
+- `commonInterests`：固定文案模板，非基于画像计算。
+
+## 7. 写库
+
+成功时写入 `match_records`（含 `matchType`，默认 `partner`，及请求体中的发起方 `phone`/`wechatId` 可选字段）。
+
+## 8. 与存客宝的关系
+
+站内选人逻辑仅在本文件描述。匹配完成后如需把线索推到存客宝，见 [算法-存客宝找伙伴留资同步.md](./算法-存客宝找伙伴留资同步.md)（`CKBMatch`）。
diff --git a/开发文档/6、后端/算法/算法-用户旅程阶段统计.md b/开发文档/6、后端/算法/算法-用户旅程阶段统计.md
new file mode 100644
index 00000000..e1a41508
--- /dev/null
+++ b/开发文档/6、后端/算法/算法-用户旅程阶段统计.md
@@ -0,0 +1,51 @@
+# 用户旅程阶段统计
+
+## 1. 说明
+
+本模块是**运营漏斗计数规则**：按固定 SQL 语义统计各阶段人数，并支持按阶段拉取用户列表。**不是**机器学习或推荐模型。
+
+实现：`soul-api/internal/handler/admin_rfm.go` 中 `DBUsersJourneyStats`、`DBUsersJourneyUsers`。
+
+与 **用户旅程触达规则**（`user_rules` 表、`model.UserRule`）区分：后者为管理端配置的触发条件 + 动作（弹窗等），由小程序拉取规则并标记完成；本文仅描述后端 **journey-stats / journey-users** 的统计定义。
+
+## 2. `GET /api/db/users/journey-stats`
+
+返回 `stats` 字典，键与含义如下（与代码一致）。
+
+| 键 | 统计含义 |
+|----|----------|
+| `register` | `users` 表总行数 |
+| `browse` | `user_tracks` 中 `action = 'view_chapter'` 的去重 `user_id` 数 |
+| `bind_phone` | `phone IS NOT NULL AND phone != ''` 的用户数 |
+| `first_pay` | 存在 `orders.status IN ('paid','success','completed')` 的去重 `user_id` 数 |
+| `fill_profile` | `mbti IS NOT NULL OR industry IS NOT NULL` 的用户数 |
+| `match` | `user_tracks` 中 `action = 'match'` 的去重 `user_id` 数 |
+| `vip` | `is_vip = 1` 的用户数 |
+| `distribution` | `referral_code` 非空 **且** `earnings > 0` 的用户数（注意：列表接口对 earnings 使用 `COALESCE`，与统计口径略有不同） |
+| `tip_pay` | 订单 `status IN ('paid','completed')` 且 `product_type = 'link_karuo_tip'` 的去重用户数 |
+| `balance_recharge` | 同上，`product_type = 'balance_recharge'` |
+| `match_pay` | 同上，`product_type = 'match'` |
+| `active_7d` | 最近 7 天内有任意 `user_tracks` 记录的去重 `user_id` |
+| `active_30d` | 最近 30 天同上 |
+| `register_7d` | `users.created_at` 在最近 7 天内的用户数 |
+
+## 3. `GET /api/db/users/journey-users?stage=&limit=`
+
+- `limit` 默认 20，最大 100。
+- `stage` 无效时返回 400。
+
+| stage | 用户范围 |
+|-------|----------|
+| `register` | 全部用户，`created_at DESC` |
+| `browse` | 出现过 `view_chapter` 的用户 |
+| `bind_phone` | 已绑手机 |
+| `first_pay` | 存在已支付类订单的用户 |
+| `fill_profile` | `mbti` 或 `industry` 有值 |
+| `match` | 出现过 `user_tracks.action = 'match'` |
+| `vip` | `is_vip = true` |
+| `distribution` | `referral_code` 非空且 `COALESCE(earnings,0) > 0` |
+| `tip_pay` | 购买过 `link_karuo_tip` 的用户 |
+| `balance_recharge` | 购买过 `balance_recharge` 的用户 |
+| `match_pay` | 购买过 `match` 商品的用户 |
+
+列表仅返回 `id`、`nickname`、`phone`、`createdAt`（RFC3339）。
diff --git a/开发文档/7、数据库/README.md b/开发文档/7、数据库/README.md
new file mode 100644
index 00000000..afa9562b
--- /dev/null
+++ b/开发文档/7、数据库/README.md
@@ -0,0 +1,14 @@
+# 7、数据库
+
+> MySQL 表设计与变更管理约定。具体表结构以 `soul-api/internal/model` 与迁移/SQL 为准。
+
+## 本目录文件
+
+| 文件 | 说明 |
+|------|------|
+| [数据库设计.md](./数据库设计.md) | 表结构设计说明 |
+| [数据库管理规范.md](./数据库管理规范.md) | 管理、备份与变更规范 |
+
+迁移与检查类说明另见 [8、部署/VIP功能-数据库迁移说明.md](../8、部署/VIP功能-数据库迁移说明.md)、[8、部署/代码逻辑和数据库最终检查清单.md](../8、部署/代码逻辑和数据库最终检查清单.md)。
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/7、数据库/数据库管理规范.md b/开发文档/7、数据库/数据库管理规范.md
new file mode 100644
index 00000000..ce5debae
--- /dev/null
+++ b/开发文档/7、数据库/数据库管理规范.md
@@ -0,0 +1,62 @@
+# 数据库管理规范 (DB Specs) - 智能自生长文档
+
+> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“DBA”角色，生成安全的 SQL/Mongo 脚本与 ER 图。
+
+## 1. 基础上下文 (The Two Basic Files)
+### 1.1 角色档案：卡若 (Karuo)
+- **核心**：数据无价，安全第一。
+- **选型**：Mongo (业务+向量) + MySQL (事务/辅助)。
+
+### 1.2 操作规范
+- **导入**：必须带 `--resumeFrom` 和 `--drop` (防止重复/中断)。
+- **命名**：`traffic_pools` (严禁 `traffic_words`)。
+
+## 2. 数据库规范核心 (Master Content)
+### 2.1 选型策略
+- **MongoDB**: 
+  - **业务数据**：用户、日志、流量池。
+  - **AI 向量**：存储 Embedding 向量 (Atlas Vector Search)。
+- **MySQL**: 强事务资金流水 (如需)。
+
+### 2.2 连接信息 (Internal)
+- **卡若私域**: 10.88.182.62:3306
+- **腾讯云**: 56b4c23f6853c...:14413
+- **Mongo**: (Env Config)
+
+### 2.3 集合命名
+- `users`: 用户
+- `scenarios`: 场景获客
+- `traffic_pools`: 流量池 (含 `embedding` 字段)
+- `orders`: 分润订单
+- `knowledge_base`: AI 知识库 (含 `embedding` 字段)
+
+### 2.4 AI 向量索引 (Vector Index)
+- **字段**：通常命名为 `embedding` 或 `vector`。
+- **索引类型**：使用 KNN 或 ANN 索引 (如 HNSW)。
+- **查询**：支持 `$vectorSearch` (Mongo Atlas) 或类似语义检索语法。
+
+### 2.5 安全与索引
+- **安全**：密码 Hash (Argon2), 手机号加密。
+- **常规索引**：`openid`, `mobile`, `inviter_id` 必建索引。
+
+## 3. AI 协作指令 (Expanded Function)
+**角色**：你是我（卡若）的 DBA。
+**任务**：
+1.  **脚本生成**：生成 MongoDB 聚合查询 (`aggregate`) 或 MySQL DDL/DML。
+2.  **向量配置**：生成向量索引的定义 JSON。
+3.  **结构可视化**：用 Mermaid 生成 ER 图。
+
+### 示例 Mermaid (ER图)
+\`\`\`mermaid
+erDiagram
+    User ||--o{ Order : places
+    User ||--o{ TrafficPool : owns
+    TrafficPool {
+        string content
+        array embedding "Vector[1536]"
+    }
+    Order {
+        string orderId
+        float amount
+    }
+\`\`\`
diff --git a/开发文档/7、数据库/数据库设计.md b/开发文档/7、数据库/数据库设计.md
new file mode 100644
index 00000000..3d4d6089
--- /dev/null
+++ b/开发文档/7、数据库/数据库设计.md
@@ -0,0 +1,708 @@
+# 数据库设计
+
+**我是卡若。**
+
+这个项目当前使用LocalStorage做数据持久化,但未来会切换到MongoDB。这个文档定义了完整的数据库设计方案。
+
+---
+
+## 一、数据库选型
+
+### 1.1 为什么选MongoDB?
+
+1. **文档型数据库**: 适合内容类产品,数据结构灵活
+2. **无Schema约束**: 快速迭代不需要频繁改表结构
+3. **JSON原生支持**: 前后端数据格式一致
+4. **横向扩展能力**: 支持未来大规模用户增长
+5. **向量搜索支持**: MongoDB Atlas支持向量检索(未来AI功能)
+
+### 1.2 当前方案 vs 未来方案
+
+**当前方案** (LocalStorage):
+\`\`\`javascript
+// 优点
+- 无需服务器
+- 开发调试方便
+- 适合MVP验证
+
+// 缺点
+- 数据仅存浏览器本地
+- 多设备无法同步
+- 数据容易丢失
+\`\`\`
+
+**未来方案** (MongoDB):
+\`\`\`javascript
+// 优点
+- 数据持久化存储
+- 多设备数据同步
+- 支持复杂查询
+- 支持事务(ACID)
+
+// 迁移计划
+1. 安装MongoDB驱动
+2. 创建数据库连接
+3. 逐步替换LocalStorage
+4. 添加数据迁移脚本
+\`\`\`
+
+---
+
+## 二、数据库连接配置
+
+### 2.1 本地开发环境
+
+\`\`\`bash
+# MongoDB本地安装
+brew install mongodb-community@6.0
+
+# 启动MongoDB
+brew services start mongodb-community@6.0
+
+# 连接字符串
+mongodb://localhost:27017/soul-experiment
+\`\`\`
+
+### 2.2 生产环境 (MongoDB Atlas)
+
+\`\`\`bash
+# 连接字符串
+mongodb+srv://<username>:<password>@cluster0.mongodb.net/soul-experiment?retryWrites=true&w=majority
+\`\`\`
+
+### 2.3 环境变量配置
+
+**.env.local**:
+\`\`\`bash
+# MongoDB配置
+MONGODB_URI=mongodb://localhost:27017/soul-experiment
+MONGODB_DB_NAME=soul-experiment
+
+# 或使用云数据库
+# MONGODB_URI=mongodb://10.88.182.62:3306/soul-experiment
+# MONGODB_USERNAME=root
+# MONGODB_PASSWORD=Vtka(agu)-1
+\`\`\`
+
+---
+
+## 三、数据模型设计
+
+### 3.1 用户集合 (users)
+
+**集合名称**: `users`
+
+**索引**:
+\`\`\`javascript
+{
+  phone: 1,           // 唯一索引
+  referralCode: 1,    // 唯一索引
+  referredBy: 1,      // 普通索引
+  createdAt: -1       // 降序索引
+}
+\`\`\`
+
+**文档结构**:
+\`\`\`javascript
+{
+  _id: ObjectId("65a1234567890abcdef12345"),
+  phone: "15880802661",                    // 手机号
+  nickname: "卡若",                         // 昵称
+  avatar: "https://cdn.example.com/avatar.jpg",  // 头像
+  openid: "wx_openid_xxx",                 // 微信openid
+  unionid: "wx_unionid_xxx",               // 微信unionid
+  
+  // 购买记录
+  purchasedSections: [                     // 已购章节
+    "1.1", "1.2", "3.3"
+  ],
+  hasFullBook: false,                      // 是否购买整本书
+  
+  // 分销数据
+  referralCode: "REFABC123",               // 推荐码
+  referredBy: "REFXYZ789",                 // 推荐人的码
+  referralCount: 28,                       // 推荐人数
+  earnings: 256.80,                        // 总收益(元)
+  pendingEarnings: 128.90,                 // 待提现(元)
+  withdrawnEarnings: 127.90,               // 已提现(元)
+  
+  // 阅读数据
+  readingTime: 12480,                      // 阅读时长(秒)
+  readingProgress: 45,                     // 阅读进度(%)
+  lastReadSection: "3.2",                  // 最后阅读章节
+  lastReadAt: ISODate("2025-01-14T12:00:00Z"),
+  
+  // 权限
+  isAdmin: false,                          // 是否管理员
+  isBanned: false,                         // 是否封禁
+  
+  // 时间戳
+  createdAt: ISODate("2025-01-01T00:00:00Z"),
+  updatedAt: ISODate("2025-01-14T12:00:00Z")
+}
+\`\`\`
+
+**查询示例**:
+\`\`\`javascript
+// 根据手机号查找用户
+db.users.findOne({ phone: "15880802661" })
+
+// 根据推荐码查找用户
+db.users.findOne({ referralCode: "REFABC123" })
+
+// 查找某推荐人的所有下级
+db.users.find({ referredBy: "REFABC123" })
+
+// 查找收益前10的推广者
+db.users.find({}).sort({ earnings: -1 }).limit(10)
+\`\`\`
+
+---
+
+### 3.2 订单集合 (orders)
+
+**集合名称**: `orders`
+
+**索引**:
+\`\`\`javascript
+{
+  orderId: 1,         // 唯一索引
+  userId: 1,          // 普通索引
+  status: 1,          // 普通索引
+  createdAt: -1       // 降序索引
+}
+\`\`\`
+
+**文档结构**:
+\`\`\`javascript
+{
+  _id: ObjectId("65a1234567890abcdef12345"),
+  orderId: "ORDER_1705200000_abc123",      // 订单号
+  userId: ObjectId("65a1234567890abcdef00001"),  // 用户ID
+  userPhone: "15880802661",                // 用户手机号
+  userNickname: "卡若",                     // 用户昵称
+  
+  // 订单信息
+  type: "section",                         // "section" | "fullbook"
+  sectionId: "1.1",                        // 章节ID(单章购买时)
+  sectionTitle: "自行车荷总...",            // 章节标题
+  amount: 1.00,                            // 金额(元)
+  
+  // 支付信息
+  paymentMethod: "wechat",                 // 支付方式
+  transactionId: "wx_pay_123456789",       // 第三方交易号
+  status: "completed",                     // "pending" | "completed" | "failed" | "refunded"
+  
+  // 分销信息
+  referralCode: "REFXYZ789",               // 推荐码
+  referrerUserId: ObjectId("65a1234567890abcdef00002"),  // 推荐人ID
+  referrerEarnings: 0.90,                  // 推荐人佣金(元)
+  
+  // 时间戳
+  createdAt: ISODate("2025-01-14T12:00:00Z"),  // 创建时间
+  paidAt: ISODate("2025-01-14T12:05:00Z"),     // 支付时间
+  expireAt: ISODate("2025-01-14T12:30:00Z"),   // 过期时间(30分钟)
+  updatedAt: ISODate("2025-01-14T12:05:00Z")
+}
+\`\`\`
+
+**查询示例**:
+\`\`\`javascript
+// 查找用户所有订单
+db.orders.find({ userId: ObjectId("65a...") }).sort({ createdAt: -1 })
+
+// 查找待支付订单
+db.orders.find({ status: "pending", expireAt: { $gt: new Date() } })
+
+// 统计今日收益
+db.orders.aggregate([
+  { $match: { 
+    status: "completed",
+    paidAt: { 
+      $gte: ISODate("2025-01-14T00:00:00Z"),
+      $lt: ISODate("2025-01-15T00:00:00Z")
+    }
+  }},
+  { $group: { 
+    _id: null, 
+    totalRevenue: { $sum: "$amount" },
+    totalOrders: { $sum: 1 }
+  }}
+])
+
+// 查找某推荐人的所有佣金记录
+db.orders.find({ 
+  referralCode: "REFABC123",
+  status: "completed"
+})
+\`\`\`
+
+---
+
+### 3.3 提现记录集合 (withdrawals)
+
+**集合名称**: `withdrawals`
+
+**索引**:
+\`\`\`javascript
+{
+  userId: 1,          // 普通索引
+  status: 1,          // 普通索引
+  createdAt: -1       // 降序索引
+}
+\`\`\`
+
+**文档结构**:
+\`\`\`javascript
+{
+  _id: ObjectId("65a1234567890abcdef12345"),
+  withdrawalId: "WD_1705200000_abc123",    // 提现单号
+  userId: ObjectId("65a1234567890abcdef00001"),  // 用户ID
+  userPhone: "15880802661",                // 用户手机号
+  userNickname: "卡若",                     // 用户昵称
+  
+  // 提现信息
+  amount: 100.00,                          // 提现金额(元)
+  method: "wechat",                        // "wechat" | "alipay"
+  account: "微信号或支付宝账号",
+  name: "真实姓名",
+  
+  // 状态
+  status: "pending",                       // "pending" | "completed" | "rejected"
+  rejectReason: "",                        // 拒绝原因
+  
+  // 时间戳
+  createdAt: ISODate("2025-01-14T12:00:00Z"),  // 申请时间
+  completedAt: ISODate("2025-01-14T14:00:00Z"), // 完成时间
+  updatedAt: ISODate("2025-01-14T14:00:00Z")
+}
+\`\`\`
+
+**查询示例**:
+\`\`\`javascript
+// 查找待审核提现
+db.withdrawals.find({ status: "pending" }).sort({ createdAt: 1 })
+
+// 查找用户提现记录
+db.withdrawals.find({ userId: ObjectId("65a...") }).sort({ createdAt: -1 })
+
+// 统计今日提现金额
+db.withdrawals.aggregate([
+  { $match: { 
+    status: "completed",
+    completedAt: { 
+      $gte: ISODate("2025-01-14T00:00:00Z"),
+      $lt: ISODate("2025-01-15T00:00:00Z")
+    }
+  }},
+  { $group: { 
+    _id: null, 
+    totalAmount: { $sum: "$amount" },
+    totalCount: { $sum: 1 }
+  }}
+])
+\`\`\`
+
+---
+
+### 3.4 章节内容集合 (sections)
+
+**集合名称**: `sections`
+
+**索引**:
+\`\`\`javascript
+{
+  sectionId: 1,       // 唯一索引
+  isFree: 1,          // 普通索引
+  createdAt: -1       // 降序索引
+}
+\`\`\`
+
+**文档结构**:
+\`\`\`javascript
+{
+  _id: ObjectId("65a1234567890abcdef12345"),
+  sectionId: "1.1",                        // 章节ID
+  
+  // 章节信息
+  title: "自行车荷总:一个行业做到极致是什么样",
+  content: "# 自行车荷总\n\n...",         // Markdown内容
+  summary: "本章讲述了...",                // 摘要
+  keywords: ["创业", "行业深耕"],         // 关键词
+  
+  // 层级关系
+  partId: "part-1",                       // 所属篇
+  partTitle: "真实的人",
+  chapterId: "chapter-1",                 // 所属章
+  chapterTitle: "人与人之间的底层逻辑",
+  
+  // 定价
+  price: 1,                               // 价格(元)
+  isFree: true,                           // 是否免费
+  unlockAfterDays: 0,                     // 定时解锁(天数)
+  
+  // 统计数据
+  viewCount: 1234,                        // 浏览次数
+  purchaseCount: 456,                     // 购买次数
+  avgReadingTime: 180,                    // 平均阅读时长(秒)
+  
+  // 文件信息
+  filePath: "book/_第一篇｜真实的人/...",
+  wordCount: 3580,                        // 字数
+  
+  // 发布状态
+  status: "published",                    // "draft" | "published"
+  publishedAt: ISODate("2025-01-01T00:00:00Z"),
+  
+  // 时间戳
+  createdAt: ISODate("2025-01-01T00:00:00Z"),
+  updatedAt: ISODate("2025-01-14T12:00:00Z")
+}
+\`\`\`
+
+**查询示例**:
+\`\`\`javascript
+// 获取所有免费章节
+db.sections.find({ isFree: true })
+
+// 获取最新发布的10章
+db.sections.find({ status: "published" })
+  .sort({ publishedAt: -1 })
+  .limit(10)
+
+// 按浏览量排序
+db.sections.find().sort({ viewCount: -1 }).limit(10)
+
+// 全文搜索(需创建文本索引)
+db.sections.createIndex({ 
+  title: "text", 
+  content: "text", 
+  keywords: "text" 
+})
+db.sections.find({ $text: { $search: "创业 私域" } })
+\`\`\`
+
+---
+
+### 3.5 阅读记录集合 (reading_logs)
+
+**集合名称**: `reading_logs`
+
+**索引**:
+\`\`\`javascript
+{
+  userId: 1,
+  sectionId: 1,
+  createdAt: -1
+}
+\`\`\`
+
+**文档结构**:
+\`\`\`javascript
+{
+  _id: ObjectId("65a1234567890abcdef12345"),
+  userId: ObjectId("65a1234567890abcdef00001"),
+  sectionId: "3.2",
+  
+  // 阅读数据
+  progress: 68,                            // 阅读进度(%)
+  readingTime: 180,                        // 阅读时长(秒)
+  scrollDepth: 75,                         // 滚动深度(%)
+  
+  // 设备信息
+  device: "iPhone 14 Pro",
+  browser: "Safari",
+  ip: "121.xxx.xxx.xxx",
+  
+  // 时间戳
+  createdAt: ISODate("2025-01-14T12:00:00Z")
+}
+\`\`\`
+
+---
+
+### 3.6 系统配置集合 (settings)
+
+**集合名称**: `settings`
+
+**文档结构**:
+\`\`\`javascript
+{
+  _id: "global_settings",
+  
+  // 分润配置
+  distributorShare: 90,                    // 推广者分成(%)
+  authorShare: 10,                         // 作者分成(%)
+  
+  // 定价配置
+  sectionPrice: 1,                         // 单章价格(元)
+  fullBookPrice: 9.9,                      // 整书价格(元)
+  
+  // 支付配置
+  paymentMethods: {
+    wechat: {
+      enabled: true,
+      appId: "wx432c93e275548671",
+      merchantId: "1318592501",
+      apiKey: "***"
+    },
+    alipay: {
+      enabled: true,
+      partnerId: "2088511801157159",
+      securityKey: "***"
+    }
+  },
+  
+  // 营销配置
+  partyGroupQrCode: "https://...",
+  bannerText: "每天早上6-9点，Soul派对房不见不散",
+  
+  // 时间戳
+  updatedAt: ISODate("2025-01-14T12:00:00Z")
+}
+\`\`\`
+
+---
+
+## 四、数据迁移方案
+
+### 4.1 LocalStorage to MongoDB
+
+**步骤1**: 导出LocalStorage数据
+\`\`\`javascript
+// 导出脚本 scripts/export-localstorage.js
+const fs = require('fs')
+
+const users = JSON.parse(localStorage.getItem('users') || '[]')
+const orders = JSON.parse(localStorage.getItem('all_purchases') || '[]')
+const settings = JSON.parse(localStorage.getItem('app_settings') || '{}')
+
+const exportData = { users, orders, settings }
+fs.writeFileSync('data-export.json', JSON.stringify(exportData, null, 2))
+\`\`\`
+
+**步骤2**: 导入MongoDB
+\`\`\`javascript
+// 导入脚本 scripts/import-mongodb.js
+const { MongoClient } = require('mongodb')
+const fs = require('fs')
+
+async function importData() {
+  const client = await MongoClient.connect(process.env.MONGODB_URI)
+  const db = client.db('soul-experiment')
+  
+  const data = JSON.parse(fs.readFileSync('data-export.json', 'utf8'))
+  
+  // 导入用户
+  await db.collection('users').insertMany(data.users)
+  
+  // 导入订单
+  await db.collection('orders').insertMany(data.orders)
+  
+  // 导入配置
+  await db.collection('settings').insertOne({
+    _id: 'global_settings',
+    ...data.settings
+  })
+  
+  client.close()
+  console.log('数据导入完成')
+}
+
+importData()
+\`\`\`
+
+---
+
+## 五、数据库操作封装
+
+### 5.1 用户操作
+
+\`\`\`typescript
+// lib/db/users.ts
+import { MongoClient, ObjectId } from 'mongodb'
+
+export async function createUser(userData: Partial<User>) {
+  const db = await getDatabase()
+  const result = await db.collection('users').insertOne({
+    ...userData,
+    referralCode: generateReferralCode(),
+    earnings: 0,
+    pendingEarnings: 0,
+    withdrawnEarnings: 0,
+    referralCount: 0,
+    purchasedSections: [],
+    hasFullBook: false,
+    createdAt: new Date(),
+    updatedAt: new Date()
+  })
+  return result.insertedId
+}
+
+export async function findUserByPhone(phone: string) {
+  const db = await getDatabase()
+  return await db.collection('users').findOne({ phone })
+}
+
+export async function updateUserEarnings(
+  userId: ObjectId, 
+  amount: number
+) {
+  const db = await getDatabase()
+  await db.collection('users').updateOne(
+    { _id: userId },
+    { 
+      $inc: { 
+        earnings: amount,
+        pendingEarnings: amount
+      },
+      $set: { updatedAt: new Date() }
+    }
+  )
+}
+\`\`\`
+
+### 5.2 订单操作
+
+\`\`\`typescript
+// lib/db/orders.ts
+export async function createOrder(orderData: Partial<Order>) {
+  const db = await getDatabase()
+  const orderId = `ORDER_${Date.now()}_${randomString()}`
+  
+  const result = await db.collection('orders').insertOne({
+    orderId,
+    ...orderData,
+    status: 'pending',
+    createdAt: new Date(),
+    expireAt: new Date(Date.now() + 30 * 60 * 1000), // 30分钟
+    updatedAt: new Date()
+  })
+  
+  return { orderId, _id: result.insertedId }
+}
+
+export async function completeOrder(orderId: string) {
+  const db = await getDatabase()
+  const order = await db.collection('orders').findOne({ orderId })
+  
+  if (!order) throw new Error('订单不存在')
+  
+  // 更新订单状态
+  await db.collection('orders').updateOne(
+    { orderId },
+    { 
+      $set: { 
+        status: 'completed',
+        paidAt: new Date(),
+        updatedAt: new Date()
+      }
+    }
+  )
+  
+  // 解锁内容
+  if (order.type === 'section') {
+    await db.collection('users').updateOne(
+      { _id: order.userId },
+      { $addToSet: { purchasedSections: order.sectionId } }
+    )
+  } else if (order.type === 'fullbook') {
+    await db.collection('users').updateOne(
+      { _id: order.userId },
+      { $set: { hasFullBook: true } }
+    )
+  }
+  
+  // 分配佣金
+  if (order.referralCode) {
+    const referrer = await db.collection('users').findOne({
+      referralCode: order.referralCode
+    })
+    
+    if (referrer) {
+      const commission = order.amount * 0.9  // 90%佣金
+      await updateUserEarnings(referrer._id, commission)
+      
+      // 记录佣金
+      await db.collection('orders').updateOne(
+        { orderId },
+        { $set: { 
+          referrerUserId: referrer._id,
+          referrerEarnings: commission 
+        }}
+      )
+    }
+  }
+}
+\`\`\`
+
+---
+
+## 六、数据备份策略
+
+### 6.1 自动备份
+
+\`\`\`bash
+# 每日凌晨3点自动备份
+0 3 * * * mongodump --uri="mongodb://localhost:27017/soul-experiment" --out="/backup/$(date +\%Y\%m\%d)"
+\`\`\`
+
+### 6.2 恢复数据
+
+\`\`\`bash
+# 恢复指定日期的备份
+mongorestore --uri="mongodb://localhost:27017/soul-experiment" --dir="/backup/20250114"
+\`\`\`
+
+---
+
+## 七、性能优化
+
+### 7.1 索引优化
+
+\`\`\`javascript
+// 创建复合索引
+db.orders.createIndex({ userId: 1, createdAt: -1 })
+db.orders.createIndex({ status: 1, expireAt: 1 })
+db.users.createIndex({ referralCode: 1 }, { unique: true })
+
+// 查看索引使用情况
+db.orders.find({ userId: ObjectId("...") }).explain("executionStats")
+\`\`\`
+
+### 7.2 查询优化
+
+\`\`\`javascript
+// 使用投影减少数据传输
+db.users.find(
+  { phone: "15880802661" },
+  { nickname: 1, referralCode: 1, earnings: 1 }
+)
+
+// 使用聚合管道优化复杂查询
+db.orders.aggregate([
+  { $match: { status: "completed" } },
+  { $lookup: {
+    from: "users",
+    localField: "userId",
+    foreignField: "_id",
+    as: "user"
+  }},
+  { $unwind: "$user" },
+  { $project: {
+    orderId: 1,
+    amount: 1,
+    "user.nickname": 1
+  }}
+])
+\`\`\`
+
+---
+
+**总结**: 数据库设计是系统的基石,合理的结构设计能让后续开发事半功倍。当前使用LocalStorage做MVP验证,未来切换MongoDB后,整个系统的可靠性和扩展性都会大幅提升。
+
+---
+
+**更新时间**: 2025年1月14日  
+**负责人**: 卡若  
+**数据库版本**: MongoDB 6.0+
diff --git a/开发文档/8、部署/API接入说明.md b/开发文档/8、部署/API接入说明.md
new file mode 100644
index 00000000..afa04eaf
--- /dev/null
+++ b/开发文档/8、部署/API接入说明.md
@@ -0,0 +1,610 @@
+# 小程序 API 接入说明
+
+## 📋 概述
+
+将 newpp 项目从静态数据（bookData.js）改为从真实 API 加载数据。
+
+---
+
+## 🎯 接入的 API
+
+### 1. 章节相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/book/chapters` | GET | 获取章节列表 | partId, status, page, pageSize |
+| `/api/book/chapter/[id]` | GET | 获取章节详情 | id（路径参数） |
+
+### 2. 用户相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/user/profile` | GET | 获取用户信息 | userId, openId |
+| `/api/user/profile` | POST | 更新用户信息 | userId, openId, nickname, avatar, phone, wechatId |
+
+### 3. 配置相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/db/config` | GET | 获取系统配置 | 无 |
+| `/api/match/config` | GET | 获取找伙伴配置 | 无 |
+
+### 4. 找伙伴相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/ckb/join` | POST | 加入匹配池 | type, wechat, description |
+| `/api/match/users` | GET | 获取匹配用户 | type |
+
+### 5. 推广相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/referral/data` | GET | 获取推广数据 | userId |
+| `/api/referral/bind` | POST | 绑定推荐人 | userId, referralCode |
+| `/api/referral/visit` | POST | 记录推广访问 | referralCode |
+
+### 6. 搜索相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/search` | GET | 搜索章节 | q（关键词） |
+
+### 7. 支付相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/payment/create-order` | POST | 创建订单 | userId, type, sectionId, amount, payMethod |
+| `/api/payment/status/[orderSn]` | GET | 查询订单状态 | orderSn（路径参数） |
+| `/api/payment/methods` | GET | 获取支付方式列表 | 无 |
+
+### 8. 提现相关
+
+| API | 方法 | 说明 | 参数 |
+|-----|------|------|------|
+| `/api/withdraw` | POST | 申请提现 | userId, amount, method, account, realName |
+
+---
+
+## 📁 文件结构
+
+```
+newpp/src/
+├── api/
+│   └── index.js              # ✅ API 集成层（封装所有 API）
+├── hooks/
+│   ├── useChapters.js        # ✅ 章节列表 Hook
+│   └── useChapterContent.js  # ✅ 章节内容 Hook
+├── adapters/
+│   ├── request.js            # ✅ 请求适配器（已有）
+│   └── storage.js            # ✅ 存储适配器（已有）
+├── data/
+│   └── bookData.js           # ⚠️ 静态数据（待废弃）
+└── pages/
+    ├── HomePage.jsx          # ⏳ 需要改用 useChapters
+    ├── ChaptersPage.jsx      # ⏳ 需要改用 useChapters
+    ├── ReadPage.jsx          # ⏳ 需要改用 useChapterContent
+    └── ...
+```
+
+---
+
+## 🔧 核心实现
+
+### 1. API 集成层
+
+**文件**：`newpp/src/api/index.js`
+
+**作用**：
+- 封装所有 API 请求
+- 统一处理错误和数据格式
+- 提供类型化的接口
+
+**示例**：
+
+```javascript
+import { request } from '../adapters/request'
+
+// 获取章节列表
+export async function getChapters(params = {}) {
+  const { partId, status = 'published', page = 1, pageSize = 100 } = params
+  const query = new URLSearchParams({ status, page: String(page), pageSize: String(pageSize) })
+  if (partId) query.append('partId', partId)
+  
+  const res = await request(`/api/book/chapters?${query.toString()}`)
+  return res
+}
+
+// 获取章节详情
+export async function getChapterById(id) {
+  const res = await request(`/api/book/chapter/${id}`)
+  return res
+}
+```
+
+---
+
+### 2. 章节列表 Hook
+
+**文件**：`newpp/src/hooks/useChapters.js`
+
+**功能**：
+1. ✅ 从 API 加载章节列表
+2. ✅ 缓存到本地（30分钟）
+3. ✅ 转换数据格式（API → bookData）
+4. ✅ 提供辅助函数
+
+**使用示例**：
+
+```javascript
+import { useChapters } from '../hooks/useChapters'
+
+export default function HomePage() {
+  const { bookData, loading, error, getTotalSectionCount, refresh } = useChapters()
+  
+  if (loading) return <div>加载中...</div>
+  if (error) return <div>错误: {error}</div>
+  
+  const totalSections = getTotalSectionCount()
+  
+  return (
+    <div>
+      <p>共 {totalSections} 章</p>
+      {bookData.map((part) => (
+        <div key={part.id}>
+          <h2>{part.title}</h2>
+          {/* ... */}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+### 3. 章节内容 Hook
+
+**文件**：`newpp/src/hooks/useChapterContent.js`
+
+**功能**：
+1. ✅ 从 API 加载章节详情
+2. ✅ 自动处理 loading 和 error
+3. ✅ 支持重新加载
+
+**使用示例**：
+
+```javascript
+import { useChapterContent } from '../hooks/useChapterContent'
+import { getPageQuery } from '../adapters/router'
+
+export default function ReadPage() {
+  const { id } = getPageQuery()
+  const { content, loading, error, reload } = useChapterContent(id)
+  
+  if (loading) return <div>加载中...</div>
+  if (error) return <div>错误: {error}</div>
+  if (!content) return <div>章节不存在</div>
+  
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.words} 字</p>
+      <div dangerouslySetInnerHTML={{ __html: content.content }} />
+    </div>
+  )
+}
+```
+
+---
+
+## 🔄 数据转换
+
+### API 返回格式
+
+```json
+{
+  "success": true,
+  "data": {
+    "list": [
+      {
+        "id": "1.1",
+        "part_id": "part-1",
+        "part_title": "真实的人",
+        "chapter_id": "chapter-1",
+        "chapter_title": "人与人之间的底层逻辑",
+        "section_title": "荷包：电动车出租的被动收入模式",
+        "content": "...",
+        "word_count": 1500,
+        "is_free": true,
+        "price": 0,
+        "sort_order": 1,
+        "status": "published"
+      }
+    ],
+    "total": 50,
+    "page": 1,
+    "pageSize": 100,
+    "totalPages": 1
+  }
+}
+```
+
+### bookData 格式
+
+```javascript
+[
+  {
+    id: 'part-1',
+    number: '01',
+    title: '真实的人',
+    subtitle: '人性观察与社交逻辑',
+    chapters: [
+      {
+        id: 'chapter-1',
+        title: '人与人之间的底层逻辑',
+        sections: [
+          {
+            id: '1.1',
+            title: '荷包：电动车出租的被动收入模式',
+            isFree: true,
+            price: 1,
+            wordCount: 1500,
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+### 转换函数
+
+```javascript
+function transformChapters(chapters) {
+  const partsMap = new Map()
+  
+  chapters.forEach((item) => {
+    // 确保 part 存在
+    if (!partsMap.has(item.part_id)) {
+      partsMap.set(item.part_id, {
+        id: item.part_id,
+        number: item.part_id.replace('part-', '').padStart(2, '0'),
+        title: item.part_title,
+        subtitle: '',
+        chapters: []
+      })
+    }
+    
+    const part = partsMap.get(item.part_id)
+    
+    // 查找或创建 chapter
+    let chapter = part.chapters.find((c) => c.id === item.chapter_id)
+    if (!chapter) {
+      chapter = {
+        id: item.chapter_id,
+        title: item.chapter_title,
+        sections: []
+      }
+      part.chapters.push(chapter)
+    }
+    
+    // 添加 section
+    chapter.sections.push({
+      id: item.id,
+      title: item.section_title,
+      isFree: item.is_free || false,
+      price: item.price || 1,
+      wordCount: item.word_count || 0,
+    })
+  })
+  
+  return Array.from(partsMap.values())
+}
+```
+
+---
+
+## 📦 缓存策略
+
+### 缓存位置
+
+- **小程序**：`wx.storage`
+- **Web**：`localStorage`
+
+### 缓存时长
+
+- **章节列表**：30分钟
+- **章节内容**：不缓存（内容可能更新）
+
+### 缓存格式
+
+```javascript
+{
+  data: [...], // 数据
+  timestamp: 1706940000000 // 时间戳
+}
+```
+
+### 缓存逻辑
+
+```javascript
+// 1. 尝试从缓存加载
+const cached = await storage.getItem(CACHE_KEY)
+if (cached) {
+  const { data, timestamp } = JSON.parse(cached)
+  if (Date.now() - timestamp < CACHE_DURATION) {
+    setBookData(data)
+    return
+  }
+}
+
+// 2. 从 API 加载
+const res = await getChapters({ status: 'published', pageSize: 1000 })
+const transformed = transformChapters(res.data.list)
+setBookData(transformed)
+
+// 3. 缓存数据
+await storage.setItem(CACHE_KEY, JSON.stringify({
+  data: transformed,
+  timestamp: Date.now()
+}))
+```
+
+---
+
+## 🔄 迁移步骤
+
+### Phase 1：创建 API 层 ✅
+
+- [x] 创建 `api/index.js`
+- [x] 创建 `hooks/useChapters.js`
+- [x] 创建 `hooks/useChapterContent.js`
+
+### Phase 2：更新页面组件
+
+#### 2.1 HomePage.jsx
+
+**Before**：
+
+```javascript
+import { getTotalSectionCount, bookData } from '../data/bookData'
+
+const totalSections = getTotalSectionCount()
+```
+
+**After**：
+
+```javascript
+import { useChapters } from '../hooks/useChapters'
+
+export default function HomePage() {
+  const { bookData, loading, getTotalSectionCount } = useChapters()
+  
+  if (loading) return <LoadingSpinner />
+  
+  const totalSections = getTotalSectionCount()
+  // ...
+}
+```
+
+#### 2.2 ChaptersPage.jsx
+
+**Before**：
+
+```javascript
+import { bookData } from '../data/bookData'
+```
+
+**After**：
+
+```javascript
+import { useChapters } from '../hooks/useChapters'
+
+export default function ChaptersPage() {
+  const { bookData, loading } = useChapters()
+  
+  if (loading) return <LoadingSpinner />
+  // ...
+}
+```
+
+#### 2.3 ReadPage.jsx
+
+**Before**：
+
+```javascript
+import { getSectionById } from '../data/bookData'
+
+const section = getSectionById(id)
+```
+
+**After**：
+
+```javascript
+import { useChapterContent } from '../hooks/useChapterContent'
+import { getPageQuery } from '../adapters/router'
+
+export default function ReadPage() {
+  const { id } = getPageQuery()
+  const { content, loading } = useChapterContent(id)
+  
+  if (loading) return <LoadingSpinner />
+  if (!content) return <NotFound />
+  // ...
+}
+```
+
+#### 2.4 SearchPage.jsx
+
+**Before**：
+
+```javascript
+import { getAllSections } from '../data/bookData'
+
+const results = getAllSections().filter(s => s.title.includes(keyword))
+```
+
+**After**：
+
+```javascript
+import { searchChapters } from '../api'
+
+export default function SearchPage() {
+  const [results, setResults] = useState([])
+  
+  const handleSearch = async (keyword) => {
+    const res = await searchChapters(keyword)
+    setResults(res.data || [])
+  }
+  // ...
+}
+```
+
+### Phase 3：集成到 Zustand Store
+
+```javascript
+// store/index.js
+import { getChapters } from '../api'
+
+const useStore = create(
+  persist(
+    (set, get) => ({
+      // ... 其他状态
+      
+      // ✅ 添加章节数据
+      bookData: [],
+      loadChapters: async () => {
+        const res = await getChapters({ status: 'published', pageSize: 1000 })
+        if (res.success) {
+          set({ bookData: transformChapters(res.data.list) })
+        }
+      },
+    }),
+    {
+      name: 'soul-party-storage',
+      storage: {/* ... */},
+    }
+  )
+)
+```
+
+### Phase 4：移除静态数据
+
+- [ ] 删除或重命名 `data/bookData.js`
+- [ ] 更新所有导入路径
+
+---
+
+## 🐛 错误处理
+
+### API 请求失败
+
+```javascript
+try {
+  const res = await getChapters()
+  if (!res.success) {
+    throw new Error(res.error || '请求失败')
+  }
+} catch (err) {
+  console.error('加载失败:', err)
+  setError(err.message)
+  
+  // ✅ 降级策略：使用缓存数据
+  const cached = await storage.getItem(CACHE_KEY)
+  if (cached) {
+    const { data } = JSON.parse(cached)
+    setBookData(data)
+  }
+}
+```
+
+### 网络超时
+
+```javascript
+// adapters/request.js
+export function request(url, options = {}) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 10000) // 10秒超时
+  
+  return fetch(fullUrl, {
+    ...options,
+    signal: controller.signal,
+  })
+    .finally(() => clearTimeout(timeout))
+}
+```
+
+---
+
+## 📊 性能优化
+
+### 1. 缓存策略
+
+- ✅ 章节列表缓存 30 分钟
+- ✅ 减少 API 调用次数
+- ✅ 提升加载速度
+
+### 2. 懒加载
+
+```javascript
+// 只在需要时加载章节内容
+useEffect(() => {
+  if (visible) {
+    loadContent()
+  }
+}, [visible])
+```
+
+### 3. 预加载
+
+```javascript
+// 预加载下一章内容
+useEffect(() => {
+  if (content && nextChapterId) {
+    // 延迟 2 秒预加载
+    const timer = setTimeout(() => {
+      getChapterById(nextChapterId)
+    }, 2000)
+    return () => clearTimeout(timer)
+  }
+}, [content, nextChapterId])
+```
+
+---
+
+## 🧪 测试清单
+
+### API 集成测试
+
+- [ ] 章节列表加载成功
+- [ ] 章节详情加载成功
+- [ ] 用户信息获取成功
+- [ ] 配置加载成功
+- [ ] 搜索功能正常
+- [ ] 错误处理正确
+
+### 缓存测试
+
+- [ ] 首次加载从 API 获取
+- [ ] 第二次加载从缓存读取
+- [ ] 缓存过期后重新加载
+- [ ] 缓存数据格式正确
+
+### 跨平台测试
+
+- [ ] Web 环境正常
+- [ ] 小程序环境正常
+- [ ] 数据格式一致
+
+---
+
+## 📚 相关文档
+
+1. [API 集成层代码](../newpp/src/api/index.js)
+2. [章节列表 Hook](../newpp/src/hooks/useChapters.js)
+3. [章节内容 Hook](../newpp/src/hooks/useChapterContent.js)
+
+---
+
+**总结**：API 集成层已完成，接下来需要更新各个页面组件，将静态数据改为从 API 加载。
diff --git a/开发文档/8、部署/DOCKER部署说明.md b/开发文档/8、部署/DOCKER部署说明.md
new file mode 100644
index 00000000..941c4a65
--- /dev/null
+++ b/开发文档/8、部署/DOCKER部署说明.md
@@ -0,0 +1,84 @@
+# soul-api Docker 部署说明
+
+> 当前实际部署以 **master.py（正式）** 和 **devloy.py（测试）** 为主。Docker 用于测试环境的 Runner 模式。详见 [部署总览](部署总览.md)。
+
+---
+
+## 一、测试环境 Runner 模式（推荐）
+
+容器内红蓝切换，宝塔 Nginx 固定 `proxy_pass http://127.0.0.1:9001`，无需改配置。
+
+### 1. 首次准备（服务器）
+
+```bash
+cd soul-api
+bash deploy/runner-init.sh
+```
+
+会构建 `soul-api-runner:latest` 并启动容器，使用 `network_mode: host`，容器内监听 9001。
+
+### 2. 部署新版本（本地）
+
+```powershell
+cd soul-api
+python devloy.py --mode runner
+```
+
+流程：本地 go build → 打包二进制 + .env.development + certs → 上传 → 容器内红蓝切换。
+
+### 3. 前置要求
+
+- 服务器已安装 Docker、Docker Compose
+- soul-api 目录有 `.env.development`、`certs/`（apiclient_cert.pem、apiclient_key.pem）
+- 宝塔站点 souldev.quwanzhi.com 的 `location /` 已配置 `proxy_pass http://127.0.0.1:9001`
+
+---
+
+## 二、测试环境 Docker 蓝绿模式（宿主机）
+
+宿主机双实例 8081/8082 轮流对外，需脚本自动修改 Nginx `proxy_pass` 端口。
+
+### 1. 环境变量
+
+```powershell
+$env:DEPLOY_DOCKER_PATH="/www/wwwroot/self/soul-dev"
+$env:DEPLOY_NGINX_CONF="/www/server/panel/vhost/nginx/souldev.quwanzhi.com.conf"
+```
+
+### 2. 执行
+
+```powershell
+cd soul-api
+python devloy.py --mode docker
+```
+
+流程：本地 go build → Dockerfile.local 打镜像 → 导出 tar.gz → 上传 → 服务器加载 → 蓝绿切换 → 修改 Nginx 并重载。
+
+---
+
+## 三、Docker 相关文件
+
+| 文件 | 用途 |
+|------|------|
+| deploy/Dockerfile.runner | Runner 容器镜像（Alpine + nginx + redis） |
+| deploy/docker-compose.runner.yml | Runner 容器编排 |
+| deploy/runner-init.sh | 首次构建并启动 Runner 容器 |
+| deploy/runner/entrypoint.sh | 容器入口，启动 nginx + 红蓝切换逻辑 |
+| deploy/runner/deploy.sh | 容器内部署脚本 |
+
+---
+
+## 四、正式环境（非 Docker）
+
+正式环境使用 **master.py** 部署 Go 二进制到宝塔，不走 Docker。详见 [部署总览](部署总览.md) 第三节。
+
+---
+
+## 五、健康检查
+
+```bash
+curl -s http://127.0.0.1:9001/health   # Runner 模式
+curl -s http://127.0.0.1:8080/health   # 正式环境
+```
+
+应返回 `{"status":"ok"}` 或 `{"success":true,...}`。
diff --git a/开发文档/8、部署/MCP-MySQL配置说明.md b/开发文档/8、部署/MCP-MySQL配置说明.md
new file mode 100644
index 00000000..5f5c1690
--- /dev/null
+++ b/开发文档/8、部署/MCP-MySQL配置说明.md
@@ -0,0 +1,401 @@
+# MCP MySQL 配置说明
+
+**日期**: 2026-02-04  
+**目的**: 通过 MCP (Model Context Protocol) 在 Cursor 中直接操作 Soul 小程序数据库
+
+---
+
+## ✅ 已配置的 MCP 服务
+
+### 1. Soul-MySQL（新增）
+**用途**: Soul 小程序生产数据库操作
+
+**配置文件**: `C:\Users\29195\.cursor\mcp.json`
+
+```json
+{
+  "Soul-MySQL": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@f4ww4z/mcp-mysql-server",
+      "--host",
+      "56b4c23f6853c.gz.cdb.myqcloud.com",
+      "--port",
+      "14413",
+      "--user",
+      "cdb_outerroot",
+      "--password",
+      "Zhiqun1984",
+      "--database",
+      "soul_miniprogram"
+    ],
+    "env": {}
+  }
+}
+```
+
+**数据库信息**:
+- **主机**: 56b4c23f6853c.gz.cdb.myqcloud.com（腾讯云 CDB）
+- **端口**: 14413
+- **用户**: cdb_outerroot
+- **密码**: Zhiqun1984
+- **数据库**: soul_miniprogram
+
+---
+
+## 🔧 使用方法
+
+### 1. 重启 Cursor
+配置文件修改后，需要**完全重启 Cursor** 才能生效：
+1. 关闭所有 Cursor 窗口
+2. 重新打开 Cursor
+3. 等待 MCP 服务启动
+
+### 2. 验证连接
+在 Cursor 中输入：
+```
+@Soul-MySQL 列出所有表
+```
+
+或使用工具调用：
+```javascript
+// 查询所有表
+user-MySQL-list_tables
+
+// 查看表结构
+user-MySQL-describe_table
+{
+  "table": "orders"
+}
+
+// 执行查询
+user-MySQL-query
+{
+  "sql": "SELECT * FROM orders LIMIT 10"
+}
+```
+
+---
+
+## 📊 可用的操作
+
+### 1. 查询数据（只读）
+```sql
+-- 查看最近订单
+SELECT * FROM orders 
+ORDER BY created_at DESC 
+LIMIT 10;
+
+-- 统计订单状态
+SELECT status, COUNT(*) as count, SUM(amount) as total
+FROM orders 
+GROUP BY status;
+
+-- 查看用户购买情况
+SELECT 
+  u.id, 
+  u.nickname, 
+  u.has_full_book,
+  COUNT(o.id) as order_count,
+  SUM(o.amount) as total_spent
+FROM users u
+LEFT JOIN orders o ON u.id = o.user_id AND o.status = 'paid'
+GROUP BY u.id, u.nickname, u.has_full_book
+ORDER BY total_spent DESC
+LIMIT 20;
+```
+
+### 2. 修改数据（慎重！）
+```sql
+-- 修复订单表 status 字段（关键修复）
+ALTER TABLE orders 
+MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') 
+DEFAULT 'created';
+
+-- 手动解锁用户章节
+UPDATE users 
+SET purchased_sections = JSON_ARRAY_APPEND(
+  COALESCE(purchased_sections, '[]'), '$', '1-1'
+)
+WHERE id = 'user_xxx';
+
+-- 手动补记订单
+INSERT INTO orders (
+  id, order_sn, user_id, open_id,
+  product_type, product_id, amount, description,
+  status, transaction_id, pay_time, created_at, updated_at
+) VALUES (
+  'MP20260204123456789012', 'MP20260204123456789012',
+  'user_xxx', 'oXXXX...', 'section', '1-1', 9.9,
+  '章节1-1购买', 'paid', 'wx_transaction_id',
+  NOW(), NOW(), NOW()
+);
+```
+
+### 3. 查看表结构
+```sql
+-- 查看表结构
+DESCRIBE orders;
+DESCRIBE users;
+DESCRIBE referral_bindings;
+
+-- 查看索引
+SHOW INDEX FROM orders;
+
+-- 查看表创建语句
+SHOW CREATE TABLE orders;
+```
+
+---
+
+## ⚠️ 重要提醒
+
+### 1. 生产数据库操作
+- ⚠️ 这是**生产数据库**，所有操作都会**直接影响线上服务**
+- ✅ 查询操作（SELECT）相对安全
+- ❌ 修改操作（UPDATE/DELETE/ALTER）**必须谨慎**
+- 💡 建议先在本地数据库测试
+
+### 2. 数据备份
+修改重要数据前，建议先备份：
+```sql
+-- 备份整个表
+CREATE TABLE orders_backup AS SELECT * FROM orders;
+
+-- 备份特定数据
+CREATE TABLE orders_backup_20260204 AS 
+SELECT * FROM orders WHERE DATE(created_at) = '2026-02-04';
+```
+
+### 3. 事务操作
+对于关联性强的修改，使用事务：
+```sql
+START TRANSACTION;
+
+-- 修改操作1
+UPDATE users SET has_full_book = TRUE WHERE id = 'user_xxx';
+
+-- 修改操作2
+INSERT INTO orders (...) VALUES (...);
+
+-- 确认无误后提交
+COMMIT;
+
+-- 或者出错时回滚
+-- ROLLBACK;
+```
+
+---
+
+## 🎯 常见操作场景
+
+### 场景1: 修复订单表状态字段
+```sql
+-- 1. 先查看当前定义
+SHOW CREATE TABLE orders;
+
+-- 2. 修改 ENUM 定义
+ALTER TABLE orders 
+MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') 
+DEFAULT 'created';
+
+-- 3. 验证修改
+DESCRIBE orders;
+```
+
+### 场景2: 查询用户支付问题
+```sql
+-- 查询特定用户的订单记录
+SELECT * FROM orders 
+WHERE user_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg'
+ORDER BY created_at DESC;
+
+-- 查询用户购买记录
+SELECT 
+  id, nickname, has_full_book, purchased_sections,
+  pending_earnings, earnings
+FROM users 
+WHERE id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg';
+
+-- 查询用户推荐关系
+SELECT * FROM referral_bindings
+WHERE referee_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg'
+   OR referrer_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg';
+```
+
+### 场景3: 统计数据分析
+```sql
+-- 今日订单统计
+SELECT 
+  COUNT(*) as total_orders,
+  SUM(CASE WHEN status = 'paid' THEN 1 ELSE 0 END) as paid_orders,
+  SUM(CASE WHEN status = 'paid' THEN amount ELSE 0 END) as total_revenue
+FROM orders 
+WHERE DATE(created_at) = CURDATE();
+
+-- 用户活跃度统计
+SELECT 
+  DATE(created_at) as date,
+  COUNT(DISTINCT user_id) as active_users,
+  COUNT(*) as total_orders,
+  SUM(amount) as revenue
+FROM orders 
+WHERE status = 'paid'
+  AND created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
+GROUP BY DATE(created_at)
+ORDER BY date DESC;
+
+-- 推广效果统计
+SELECT 
+  u.nickname as referrer,
+  COUNT(rb.id) as total_referrals,
+  SUM(CASE WHEN rb.status = 'converted' THEN 1 ELSE 0 END) as conversions,
+  SUM(rb.commission_amount) as total_commission
+FROM users u
+LEFT JOIN referral_bindings rb ON u.id = rb.referrer_id
+WHERE rb.id IS NOT NULL
+GROUP BY u.id, u.nickname
+ORDER BY total_commission DESC
+LIMIT 20;
+```
+
+### 场景4: 紧急数据修复
+```sql
+-- 手动解锁用户权限（用户支付但未解锁）
+START TRANSACTION;
+
+-- 1. 补记订单
+INSERT INTO orders (
+  id, order_sn, user_id, open_id,
+  product_type, product_id, amount, description,
+  status, transaction_id, pay_time, created_at, updated_at
+) VALUES (
+  'MANUAL_20260204_001', 'MANUAL_20260204_001',
+  'user_xxx', 'oXXXX...', 'section', '1-1', 9.9,
+  '手动补记-章节1-1购买', 'paid', 'manual_fix',
+  NOW(), NOW(), NOW()
+);
+
+-- 2. 解锁章节
+UPDATE users 
+SET purchased_sections = JSON_ARRAY_APPEND(
+  COALESCE(purchased_sections, '[]'), '$', '1-1'
+)
+WHERE id = 'user_xxx'
+  AND NOT JSON_CONTAINS(COALESCE(purchased_sections, '[]'), '"1-1"');
+
+-- 3. 如果有推荐人，分配佣金
+UPDATE users 
+SET pending_earnings = pending_earnings + (9.9 * 0.9)
+WHERE id = (SELECT referred_by FROM users WHERE id = 'user_xxx');
+
+-- 4. 更新推荐关系状态
+UPDATE referral_bindings 
+SET status = 'converted', 
+    conversion_date = NOW(),
+    commission_amount = 8.91,
+    order_id = 'MANUAL_20260204_001'
+WHERE referee_id = 'user_xxx' 
+  AND status = 'active';
+
+COMMIT;
+```
+
+---
+
+## 🔗 其他 MCP 服务
+
+### MySQL（本地）
+- **用途**: 本地 sass 数据库
+- **主机**: localhost:3306
+- **数据库**: sass
+
+### MongoDB
+- **用途**: 测试 MongoDB 连接
+- **连接**: mongodb://admin:admin123@192.168.1.201:27017/admin
+
+### Ollama
+- **用途**: 本地 AI 模型调用
+- **脚本**: C:\Users\29195\mcp_ollama_server.py
+
+---
+
+## 📝 MCP 工具列表
+
+使用 `@Soul-MySQL` 可以调用以下工具：
+
+| 工具名 | 功能 | 示例 |
+|--------|------|------|
+| `user-MySQL-connect_db` | 连接数据库 | 自动连接 |
+| `user-MySQL-query` | 执行 SELECT 查询 | `{"sql": "SELECT * FROM orders LIMIT 10"}` |
+| `user-MySQL-execute` | 执行 INSERT/UPDATE/DELETE | `{"sql": "UPDATE users SET ..."}` |
+| `user-MySQL-list_tables` | 列出所有表 | 无参数 |
+| `user-MySQL-describe_table` | 查看表结构 | `{"table": "orders"}` |
+
+---
+
+## 🚀 快速开始
+
+### 1. 检查订单表状态
+```
+@Soul-MySQL 执行查询：DESCRIBE orders;
+```
+
+### 2. 查看最近订单
+```
+@Soul-MySQL 查询最近10条订单记录
+```
+
+### 3. 修复订单表（如需要）
+```
+@Soul-MySQL 执行以下SQL：
+ALTER TABLE orders 
+MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') 
+DEFAULT 'created';
+```
+
+---
+
+## ⚡ 故障排查
+
+### 问题1: MCP 服务未启动
+**症状**: 输入 `@Soul-MySQL` 没有提示
+
+**解决**:
+1. 完全关闭 Cursor
+2. 检查 mcp.json 文件格式是否正确
+3. 重新打开 Cursor
+4. 查看 Cursor 输出日志
+
+### 问题2: 连接超时
+**症状**: 执行查询时提示连接超时
+
+**解决**:
+1. 检查网络连接
+2. 确认数据库服务器是否在线
+3. 检查防火墙/安全组配置
+4. 验证数据库账号密码
+
+### 问题3: 权限不足
+**症状**: 提示没有权限执行某些操作
+
+**解决**:
+1. 检查数据库用户权限
+2. 某些操作需要超级管理员权限
+3. 联系 DBA 授权
+
+---
+
+## 📚 相关文档
+
+- [支付订单完整修复方案](./支付订单完整修复方案.md)
+- [订单表状态字段修复说明](./订单表状态字段修复说明.md)
+- [支付订单未创建问题分析](./支付订单未创建问题分析.md)
+- [数据库设计](../7、数据库/数据库设计.md)
+
+---
+
+**现在你可以在 Cursor 中直接使用 `@Soul-MySQL` 来操作生产数据库了！** 🎉
+
+**记得重启 Cursor 使配置生效！**
diff --git a/开发文档/8、部署/README.md b/开发文档/8、部署/README.md
new file mode 100644
index 00000000..440b25b1
--- /dev/null
+++ b/开发文档/8、部署/README.md
@@ -0,0 +1,26 @@
+# 8、部署
+
+> soul-api / 小程序 / 管理端 的部署、运维、分销与支付专题。**入口**：[部署总览.md](./部署总览.md)。
+
+## 本目录文件（均已存在）
+
+| 文件 | 用途 |
+|------|------|
+| [**部署总览.md**](./部署总览.md) | **推荐入口**：导航与「等价内容」说明 |
+| [运行与部署.md](./运行与部署.md) | 运行方式与部署说明 |
+| [DOCKER部署说明.md](./DOCKER部署说明.md) | Docker |
+| [宝塔-Docker首次配置指南.md](./宝塔-Docker首次配置指南.md) | 宝塔 Docker |
+| [宝塔面板配置订单同步定时任务.md](./宝塔面板配置订单同步定时任务.md) | 定时任务 |
+| [自动化与Webhook.md](./自动化与Webhook.md) | Webhook |
+| [API接入说明.md](./API接入说明.md) | API 接入 |
+| [存客宝API-Key约定.md](./存客宝API-Key约定.md) | 存客宝 |
+| [支付接口清单.md](./支付接口清单.md) | 支付 |
+| [章节阅读付费标准流程设计.md](./章节阅读付费标准流程设计.md)、[阅读页标准流程改造说明.md](./阅读页标准流程改造说明.md) | 阅读付费 |
+| [分销与绑定流程图.md](./分销与绑定流程图.md)、[分销提现流程图.md](./分销提现流程图.md)、[邀请码分销规则说明.md](./邀请码分销规则说明.md) | 分销 |
+| [新分销逻辑-设计方案.md](./新分销逻辑-设计方案.md)、[新分销逻辑-部署步骤.md](./新分销逻辑-部署步骤.md)、[新分销逻辑-宝塔操作清单.md](./新分销逻辑-宝塔操作清单.md) | 新分销 |
+| [佣金计算逻辑检查.md](./佣金计算逻辑检查.md)、[佣金问题-快速诊断和修复.md](./佣金问题-快速诊断和修复.md) | 佣金 |
+| [VIP功能-数据库迁移说明.md](./VIP功能-数据库迁移说明.md)、[代码逻辑和数据库最终检查清单.md](./代码逻辑和数据库最终检查清单.md) | 迁移与检查 |
+| [MCP-MySQL配置说明.md](./MCP-MySQL配置说明.md)、[Soul-MySQL-MCP配置说明.md](./Soul-MySQL-MCP配置说明.md) | MCP |
+| [其它.md](./其它.md) | 杂项 |
+
+返回 [开发文档索引](../索引.md)。
diff --git a/开发文档/8、部署/Soul-MySQL-MCP配置说明.md b/开发文档/8、部署/Soul-MySQL-MCP配置说明.md
new file mode 100644
index 00000000..cbbad0e4
--- /dev/null
+++ b/开发文档/8、部署/Soul-MySQL-MCP配置说明.md
@@ -0,0 +1,84 @@
+# Soul-MySQL MCP 配置说明
+
+**配置文件**: `C:\Users\29195\.cursor\mcp.json`
+
+---
+
+## 为什么之前无法执行？
+
+### 原因 1：连接时没有带端口
+
+- 之前用 `--host`、`--port` 分开传参，部分 MCP 客户端在**运行时**调用 `connect_db` 时**只传 host/user/password/database，不传 port**。
+- 你的数据库在 **14413**，MySQL 默认是 **3306**，所以实际连的是错误端口 → 容易 **ETIMEDOUT** 或连不上。
+- 所以会出现「无法执行」或执行报错。
+
+### 原因 2：改用「连接串」才能带上端口
+
+- `@f4ww4z/mcp-mysql-server` 支持用**一条连接串**启动，格式里可以写清楚端口：
+  - `mysql://用户:密码@主机:端口/数据库名`
+- 这样 MCP 启动时就会用 **14413** 去连，不会再用默认 3306。
+
+---
+
+## 当前正确配置（连接串方式）
+
+在 `mcp.json` 里 Soul-MySQL 应类似：
+
+```json
+"Soul-MySQL": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@f4ww4z/mcp-mysql-server",
+    "mysql://cdb_outerroot:Zhiqun1984@56b4c23f6853c.gz.cdb.myqcloud.com:14413/soul_miniprogram"
+  ],
+  "env": {}
+}
+```
+
+含义：
+
+- **用户**: cdb_outerroot  
+- **密码**: Zhiqun1984  
+- **主机**: 56b4c23f6853c.gz.cdb.myqcloud.com  
+- **端口**: 14413（写在连接串里）  
+- **数据库**: soul_miniprogram  
+
+这样 MCP 会按 `主机:14413` 连接，不再用 3306。
+
+---
+
+## 使用前必做：重启 Cursor
+
+1. **完全退出 Cursor**（关掉所有窗口）。
+2. 再重新打开 Cursor。
+3. 等 MCP 列表里 Soul-MySQL 显示为已连接/可用。
+
+否则会继续用旧配置（不带端口），仍然无法执行。
+
+---
+
+## 若仍无法执行，可排查这些
+
+### 1. 本机网络/防火墙
+
+- 数据库在腾讯云，若你本机或公司网络**不允许访问外网 14413**，连接会超时。
+- 解决：在能访问该库的机器上跑 Cursor（或先做 SSH 隧道，把 14413 转到本机 3306，再在 mcp.json 里连 localhost:3306）。
+
+### 2. 腾讯云白名单
+
+- 腾讯云 MySQL 有「来源 IP 白名单」。
+- 你当前上网的 **公网 IP** 必须在白名单里，否则会被拒绝。
+- 解决：在腾讯云控制台 → 该 MySQL 实例 → 白名单里加上你当前的公网 IP。
+
+### 3. 密码含特殊字符
+
+- 若以后改了密码，且密码里有 `@`、`#`、`/` 等，需要做 **URL 编码** 再写进连接串，否则连接串会被解析错。
+
+---
+
+## 小结
+
+- **无法执行** 多半是：连库时**没带端口 14413** 或**网络/白名单**不通。
+- 已把 Soul-MySQL 改成**带端口的连接串**配置，并写进 `mcp.json`。
+- 修改后**务必重启 Cursor** 再试；若仍不行，按上面「若仍无法执行」逐项排查。
diff --git a/开发文档/8、部署/VIP功能-数据库迁移说明.md b/开发文档/8、部署/VIP功能-数据库迁移说明.md
new file mode 100644
index 00000000..66b09558
--- /dev/null
+++ b/开发文档/8、部署/VIP功能-数据库迁移说明.md
@@ -0,0 +1,49 @@
+# VIP 功能 - 数据库迁移说明
+
+> 2026-02-26 小橙同步。VIP 排序、角色、设置入口升级。
+
+---
+
+## 一、迁移脚本
+
+| 脚本 | 说明 |
+|------|------|
+| `soul-api/scripts/add-vip-activated-at.sql` | 新增 `users.vip_activated_at`（成为 VIP 时间，排序用） |
+| `soul-api/scripts/add-vip-roles-and-fields.sql` | 新建 `vip_roles` 表；新增 `users.vip_sort`、`users.vip_role` |
+| `soul-api/scripts/add-vip-profile-fields.sql` | 新增 `users.vip_name`、`vip_avatar`、`vip_project`、`vip_contact`、`vip_bio`（会员资料，与用户信息分离） |
+
+---
+
+## 二、执行顺序
+
+```bash
+# 1. vip_activated_at（若尚未执行）
+mysql -u user -p database < soul-api/scripts/add-vip-activated-at.sql
+
+# 2. vip_roles 表 + users 新字段
+mysql -u user -p database < soul-api/scripts/add-vip-roles-and-fields.sql
+
+# 3. 会员资料字段（若尚未执行；列已存在会报 Duplicate column，可忽略）
+mysql -u user -p database < soul-api/scripts/add-vip-profile-fields.sql
+```
+
+若 `vip_sort`、`vip_role` 已存在，对应 `ALTER` 会报错，可忽略或单独执行未执行过的语句。
+
+---
+
+## 三、功能说明
+
+| 字段/表 | 用途 |
+|---------|------|
+| `vip_activated_at` | 成为 VIP 时间：付款=订单 pay_time，手动=设置时 now；排序用（后付款/后设置在前） |
+| `vip_sort` | 手动排序，数字越小越靠前；NULL 时按 vip_activated_at |
+| `vip_role` | 角色：从 vip_roles 选或手动填写 |
+| `vip_roles` | 预设角色表（创始人、投资人、产品经理等），管理端可 CRUD |
+| `vip_name`、`vip_avatar`、`vip_project`、`vip_contact`、`vip_bio` | 会员资料（创业老板排行），与用户信息 phone/wechat_id 分离 |
+
+---
+
+## 四、管理端入口
+
+- **用户列表**：每行「设置 VIP」按钮（Crown 图标）→ SetVipModal
+- **VIP 角色**：侧栏「VIP 角色」→ `/vip-roles`，管理预设角色列表
diff --git a/开发文档/8、部署/代码逻辑和数据库最终检查清单.md b/开发文档/8、部署/代码逻辑和数据库最终检查清单.md
new file mode 100644
index 00000000..8f7cf88d
--- /dev/null
+++ b/开发文档/8、部署/代码逻辑和数据库最终检查清单.md
@@ -0,0 +1,363 @@
+# 代码逻辑和数据库最终检查清单 ✅
+
+## 📊 数据库修改（已完成）
+
+### 1. referral_bindings 表新增字段
+```sql
+✅ last_purchase_date DATETIME DEFAULT NULL
+✅ purchase_count INT DEFAULT 0
+✅ total_commission DECIMAL(10,2) DEFAULT 0.00
+✅ status ENUM('active', 'expired', 'cancelled') -- 新增 'cancelled'
+```
+
+### 2. 索引优化
+```sql
+✅ idx_status_expiry (status, expiry_date)
+✅ idx_referee_status (referee_id, status)
+✅ idx_referrer_status (referrer_id, status)
+✅ idx_purchase_count (purchase_count)
+```
+
+### 3. 数据库迁移执行状态
+- ✅ 已通过 `scripts/migrate_db_simple.py` 成功执行
+- ✅ 所有字段已添加
+- ✅ 所有索引已创建
+
+---
+
+## 🔧 核心API逻辑（已验证）
+
+### 1. `/api/referral/bind` - 绑定/切换推荐人 ✅
+
+**文件**: `app/api/referral/bind/route.ts`
+
+**关键逻辑**:
+```typescript
+✅ 从 referral_config 读取 bindingDays（不再硬编码 30 天）
+✅ 同一推荐人 → 续期（刷新 30 天）
+✅ 不同推荐人 → 立即切换（无需等待过期）
+   - 旧绑定标记为 'cancelled'
+   - 创建新绑定，expiry_date = NOW + bindingDays
+   - 更新 users.referral_count（旧 -1，新 +1）
+```
+
+**验证点**:
+- ✅ 绑定天数可配置
+- ✅ 切换逻辑正确（不检查 expiry_date）
+- ✅ 旧绑定正确标记为 'cancelled'
+- ✅ 新绑定正确创建
+- ✅ 推荐人数量正确更新
+
+---
+
+### 2. `/api/miniprogram/pay` - 创建支付订单 ✅
+
+**文件**: `app/api/miniprogram/pay/route.ts`
+
+**关键逻辑**:
+```typescript
+✅ 从 referral_config 读取 userDiscount（如 5 表示 5%）
+✅ 如果有 referralCode，计算折后价
+   finalAmount = amount * (1 - userDiscount / 100)
+   finalAmount = max(0.01, round(finalAmount, 2))
+✅ 微信支付使用 finalAmount（折后价）
+✅ 订单表记录 finalAmount（折后价）
+```
+
+**验证点**:
+- ✅ 折扣正确应用（原价 1.00，5% off = 0.95）
+- ✅ 最低金额保护（至少 0.01 元）
+- ✅ 金额精确到分（Math.round）
+- ✅ 订单表记录的是折后价
+
+---
+
+### 3. `/api/miniprogram/pay/notify` - 支付回调 ✅
+
+**文件**: `app/api/miniprogram/pay/notify/route.ts`
+
+**关键逻辑**:
+```typescript
+✅ 查找 status = 'active' 的绑定记录
+✅ 检查 expiry_date > NOW（过期不分佣）
+✅ 从 referral_config 读取 distributorShare
+✅ 计算佣金：commission = amount * distributorShare / 100
+✅ 更新 users.pending_earnings += commission
+✅ 更新 referral_bindings:
+   - last_purchase_date = NOW
+   - purchase_count += 1
+   - total_commission += commission
+   - status 保持 'active'（不再改为 'converted'）
+```
+
+**验证点**:
+- ✅ 只给 active 且未过期的绑定分佣
+- ✅ 佣金比例可配置
+- ✅ 支持多次购买分佣（不改 status）
+- ✅ 正确累加购买次数和佣金
+- ✅ 记录最后购买时间
+
+---
+
+### 4. `/api/withdraw` - 提现申请 ✅
+
+**文件**: `app/api/withdraw/route.ts`
+
+**关键逻辑**:
+```typescript
+✅ 从 referral_config 读取 minWithdrawAmount
+✅ 验证 amount >= minWithdrawAmount（不再硬编码 10 元）
+✅ 验证 amount <= pending_earnings
+```
+
+**验证点**:
+- ✅ 最低提现金额可配置
+- ✅ 金额验证逻辑正确
+
+---
+
+### 5. `/api/referral/data` - 分销数据统计 ✅
+
+**文件**: `app/api/referral/data/route.ts`
+
+**关键逻辑**:
+```typescript
+✅ 绑定统计:
+   - active: status = 'active' AND expiry_date > NOW
+   - converted: status = 'active' AND purchase_count > 0
+   - expired: status IN ('expired', 'cancelled') OR expiry_date <= NOW
+   
+✅ 已转化用户列表:
+   WHERE status = 'active' AND purchase_count > 0
+   ORDER BY last_purchase_date DESC
+   
+✅ 返回购买次数、累计佣金
+```
+
+**验证点**:
+- ✅ 不再查询 status = 'converted'
+- ✅ 使用 purchase_count 判断是否已购买
+- ✅ 返回新增的字段（purchase_count, total_commission）
+- ✅ 统计逻辑正确（包含 'cancelled' 状态）
+
+---
+
+## 🎯 管理后台（已验证）
+
+### 1. 推广设置页面 ✅
+
+**文件**: `app/admin/referral-settings/page.tsx`
+
+**配置项**:
+```typescript
+✅ distributorShare (分销比例, 0-100)
+✅ minWithdrawAmount (最低提现金额, 元)
+✅ bindingDays (绑定天数, 天)
+✅ userDiscount (好友优惠, 0-100)
+✅ enableAutoWithdraw (自动提现, boolean)
+```
+
+**验证点**:
+- ✅ 读取配置正确
+- ✅ 保存配置正确（Number/Boolean 转换）
+- ✅ 表单验证正确
+- ✅ 成功提示清晰
+
+---
+
+### 2. 管理后台菜单 ✅
+
+**文件**: `app/admin/layout.tsx`
+
+```typescript
+✅ 新增菜单项: "推广设置" → /admin/referral-settings
+✅ 图标: CreditCard
+✅ 位置: "用户管理" 和 "系统设置" 之间
+```
+
+---
+
+## 📱 小程序端（已完成）
+
+### 1. UI修改 ✅
+```xml
+✅ 删除"我的邀请码"卡片（miniprogram/pages/referral/referral.wxml）
+```
+
+### 2. 绑定逻辑 ✅
+```javascript
+✅ app.js 调用 /api/referral/bind（后端已实现立即切换）
+✅ 无需前端修改
+```
+
+### 3. 支付逻辑 ✅
+```javascript
+✅ pages/read/read.js 传递 referralCode（后端已实现折扣）
+✅ 无需前端修改
+```
+
+### 4. 数据展示 ✅
+```javascript
+✅ pages/referral/referral.js 调用 /api/referral/data
+✅ 后端已返回新字段（purchase_count, total_commission）
+✅ 无需前端修改
+```
+
+---
+
+## ⏰ 定时任务（已创建）
+
+### 1. 自动解绑脚本 ✅
+
+**文件**: `scripts/auto-unbind-expired-simple.js`
+
+**逻辑**:
+```javascript
+✅ 查找 status = 'active' AND expiry_date < NOW AND purchase_count = 0
+✅ 批量更新为 status = 'expired'
+✅ 输出详细日志
+```
+
+**部署**:
+```bash
+⏸️ 需在宝塔面板配置: 每天 03:00 执行
+   命令: cd /www/wwwroot/soul.quwanzhi.com && /www/server/nodejs/v20.11.0/bin/node scripts/auto-unbind-expired-simple.js >> logs/auto-unbind.log 2>&1
+```
+
+---
+
+## 🔍 业务逻辑验证
+
+### 场景1: 首次绑定 ✅
+```
+A 分享链接 → B 点击 → /api/referral/bind
+→ 创建新绑定（status = 'active', expiry_date = NOW + 30天）
+→ users.referral_count += 1
+```
+
+### 场景2: 切换推荐人 ✅
+```
+B 已绑定 A → B 点击 C 的链接 → /api/referral/bind
+→ 旧绑定（A-B）标记为 'cancelled'
+→ 创建新绑定（C-B, status = 'active', expiry_date = NOW + 30天）
+→ A.referral_count -= 1, C.referral_count += 1
+```
+
+### 场景3: 续期绑定 ✅
+```
+B 已绑定 A → B 再次点击 A 的链接 → /api/referral/bind
+→ 更新绑定（expiry_date = NOW + 30天）
+→ referral_count 不变
+```
+
+### 场景4: 首次购买 ✅
+```
+B 绑定 C（5天前）→ B 购买 1.00 元章节（有 5% 优惠）
+→ 实付 0.95 元
+→ C 获得佣金 0.95 * 90% = 0.855 元（四舍五入 0.86）
+→ referral_bindings: purchase_count = 1, total_commission = 0.86, last_purchase_date = NOW
+→ C.pending_earnings += 0.86
+→ 绑定保持 'active'
+```
+
+### 场景5: 多次购买 ✅
+```
+B 再次购买 1.00 元章节（还在 30 天内）
+→ 实付 0.95 元
+→ C 再获得佣金 0.86 元
+→ referral_bindings: purchase_count = 2, total_commission = 1.72, last_purchase_date = NOW
+→ C.pending_earnings += 0.86（累计 1.72）
+→ 绑定保持 'active'
+```
+
+### 场景6: 自动解绑 ✅
+```
+B 绑定 A（30 天前）→ B 从未购买 → 定时任务执行
+→ 查找: status = 'active' AND expiry_date < NOW AND purchase_count = 0
+→ 更新: status = 'expired'
+→ A.referral_count -= 1
+```
+
+### 场景7: 提现 ✅
+```
+C 有 pending_earnings = 15.00 元 → 申请提现 12.00 元
+→ 验证 amount >= minWithdrawAmount（默认 10）
+→ 验证 amount <= pending_earnings
+→ 创建提现记录
+→ C.pending_earnings -= 12.00 = 3.00
+```
+
+---
+
+## ✅ 最终确认
+
+### 代码逻辑
+- ✅ 所有 API 已适配新逻辑
+- ✅ 所有硬编码值已改为动态配置
+- ✅ 所有状态转换逻辑正确
+- ✅ 所有金额计算精确到分
+
+### 数据库
+- ✅ 所有字段已添加
+- ✅ 所有索引已创建
+- ✅ 数据类型正确
+- ✅ 默认值正确
+
+### 小程序
+- ✅ UI 已删除邀请码卡片
+- ✅ 绑定逻辑兼容后端
+- ✅ 支付逻辑兼容后端
+- ✅ 数据展示兼容后端
+
+### 管理后台
+- ✅ 推广设置页面已创建
+- ✅ 菜单已添加
+- ✅ 配置读写正确
+
+### 定时任务
+- ✅ 脚本已创建
+- ⏸️ 需在宝塔配置（部署时）
+
+---
+
+## 🚀 部署检查项
+
+部署前确认:
+- ✅ 代码已修改
+- ✅ 数据库已迁移
+- ✅ 本地测试通过
+
+部署后确认:
+- ⏸️ PM2 重启成功
+- ⏸️ 定时任务配置成功
+- ⏸️ 管理后台可访问 `/admin/referral-settings`
+- ⏸️ 小程序绑定/支付/分佣功能测试通过
+
+---
+
+## 📝 测试用例（可选）
+
+如需本地测试，运行:
+```bash
+node scripts/test-referral-flow.js
+```
+
+测试覆盖:
+- ✅ 首次绑定
+- ✅ 续期绑定
+- ✅ 切换绑定
+- ✅ 首次购买分佣
+- ✅ 多次购买分佣
+- ✅ 过期绑定不分佣
+
+---
+
+## ✅ 结论
+
+**所有代码逻辑和数据库修改已完成并验证，可以放心部署！**
+
+需要在宝塔面板配置的只有：
+1. 重启 PM2 服务（让新代码生效）
+2. 配置定时任务（自动解绑）
+
+参考文档: `开发文档/8、部署/新分销逻辑-宝塔操作清单.md`
diff --git a/开发文档/8、部署/佣金计算逻辑检查.md b/开发文档/8、部署/佣金计算逻辑检查.md
new file mode 100644
index 00000000..99d86591
--- /dev/null
+++ b/开发文档/8、部署/佣金计算逻辑检查.md
@@ -0,0 +1,307 @@
+# 佣金计算逻辑检查
+
+## 🔍 用户反馈
+
+**问题**: "推广者应该获取支付金额的90%，但却是10%"
+
+---
+
+## 📊 配置值流转
+
+### 1. 管理后台保存（/admin/referral-settings）
+
+**输入**: 
+```
+分销比例：90 (表示90%)
+```
+
+**保存代码**:
+```typescript
+const safeConfig = {
+  distributorShare: Number(config.distributorShare) || 0
+}
+// 保存到数据库：distributorShare = 90
+```
+
+**数据库存储**:
+```json
+{
+  "distributorShare": 90
+}
+```
+
+---
+
+### 2. 后端读取配置（/api/miniprogram/pay/notify）
+
+**读取代码**:
+```typescript
+const config = await getConfig('referral_config')
+const distributorShare = config.distributorShare / 100
+// 结果：90 / 100 = 0.9
+```
+
+**佣金计算**:
+```typescript
+const commission = Math.round(amount * distributorShare * 100) / 100
+// 例如：1元 * 0.9 = 0.9元
+```
+
+---
+
+### 3. 返回给小程序（/api/referral/data）
+
+**返回代码**:
+```typescript
+shareRate: Math.round(distributorShare * 100)
+// 结果：0.9 * 100 = 90
+```
+
+**小程序显示**:
+```xml
+你获得 {{shareRate}}% 收益
+<!-- 显示：你获得 90% 收益 -->
+```
+
+---
+
+## ⚠️ 可能的问题点
+
+### 问题1: 配置值保存错误
+
+**检查点**: 
+- 管理后台输入的是 90 还是 0.9？
+- 数据库实际保存的值是多少？
+
+**验证SQL**:
+```sql
+SELECT config_value FROM system_config WHERE config_key = 'referral_config';
+```
+
+**预期结果**:
+```json
+{
+  "distributorShare": 90
+}
+```
+
+**如果看到**:
+```json
+{
+  "distributorShare": 0.1  // ❌ 错误！应该是 90
+}
+```
+
+---
+
+### 问题2: 计算公式错误
+
+**检查点**: 是否有地方用错了公式？
+
+**错误示例**:
+```typescript
+// ❌ 错误：用了减法
+const commission = amount * (1 - distributorShare)
+// 1 * (1 - 0.9) = 0.1 元（10%）
+
+// ✅ 正确：直接乘
+const commission = amount * distributorShare
+// 1 * 0.9 = 0.9 元（90%）
+```
+
+---
+
+### 问题3: 除以100的位置错误
+
+**错误示例**:
+```typescript
+// ❌ 错误：没有除以100
+const distributorShare = config.distributorShare
+const commission = amount * distributorShare / 100
+// 1 * 90 / 100 = 0.9 元（看起来对，但下一步就错了）
+```
+
+**正确方式**:
+```typescript
+// ✅ 正确：先除以100
+const distributorShare = config.distributorShare / 100  // 90 → 0.9
+const commission = amount * distributorShare  // 1 * 0.9 = 0.9
+```
+
+---
+
+## 🧪 测试用例
+
+### 测试1: 购买1元（无折扣）
+
+**输入**:
+- 支付金额: 1.00元
+- distributorShare: 90
+
+**计算过程**:
+```typescript
+const distributorShare = 90 / 100 = 0.9
+const commission = 1.00 * 0.9 = 0.90元
+```
+
+**预期结果**: 推荐人获得 0.90元
+
+---
+
+### 测试2: 购买1元（5%折扣）
+
+**输入**:
+- 原价: 1.00元
+- 好友优惠: 5%
+- 实付: 0.95元
+- distributorShare: 90
+
+**计算过程**:
+```typescript
+const finalAmount = 1.00 * (1 - 0.05) = 0.95元
+const commission = 0.95 * 0.9 = 0.855 ≈ 0.86元
+```
+
+**预期结果**: 推荐人获得 0.86元
+
+---
+
+### 测试3: 如果配置错误保存为0.9
+
+**输入**:
+- 支付金额: 1.00元
+- distributorShare: 0.9 (❌ 错误的保存值)
+
+**计算过程**:
+```typescript
+const distributorShare = 0.9 / 100 = 0.009
+const commission = 1.00 * 0.009 = 0.009 ≈ 0.01元
+```
+
+**错误结果**: 推荐人只获得 0.01元（1%）❌
+
+---
+
+## 🔍 排查步骤
+
+### 步骤1: 检查数据库配置值
+
+**SQL查询**:
+```sql
+SELECT config_key, config_value 
+FROM system_config 
+WHERE config_key = 'referral_config';
+```
+
+**检查要点**:
+- `distributorShare` 应该是 **90**（不是 0.9）
+- 如果是其他值（如 10），说明保存时出错了
+
+---
+
+### 步骤2: 检查实际佣金记录
+
+**SQL查询**:
+```sql
+SELECT 
+  rb.referrer_id,
+  rb.referee_id,
+  rb.purchase_count,
+  rb.total_commission,
+  o.amount,
+  o.order_sn
+FROM referral_bindings rb
+JOIN orders o ON o.user_id = rb.referee_id AND o.status = 'paid'
+WHERE rb.purchase_count > 0
+ORDER BY rb.last_purchase_date DESC
+LIMIT 5;
+```
+
+**检查要点**:
+- 订单金额 1.00元 → 佣金应该约 0.90元
+- 如果佣金是 0.10元，说明计算错误
+
+---
+
+### 步骤3: 检查控制台日志
+
+**查看PM2日志**:
+```bash
+pm2 logs soul --lines 100 | grep "处理分佣"
+```
+
+**预期输出**:
+```
+[PayNotify] 处理分佣: {
+  amount: 0.95,
+  commission: 0.855,
+  shareRate: '90%'
+}
+```
+
+**如果看到**:
+```
+shareRate: '10%'  // ❌ 错误！
+```
+
+---
+
+## 🔧 可能的修复方案
+
+### 修复1: 如果配置值错误
+
+**检查数据库**:
+```sql
+SELECT config_value FROM system_config WHERE config_key = 'referral_config';
+```
+
+**如果显示**:
+```json
+{"distributorShare": 10}  // ❌ 错误
+```
+
+**手动修复**:
+```sql
+UPDATE system_config 
+SET config_value = '{"distributorShare":90,"minWithdrawAmount":10,"bindingDays":30,"userDiscount":5,"enableAutoWithdraw":false}'
+WHERE config_key = 'referral_config';
+```
+
+**或者在管理后台重新保存** 90%。
+
+---
+
+### 修复2: 如果计算公式错误
+
+**检查位置**: `app/api/miniprogram/pay/notify/route.ts` 第395行
+
+**当前代码**:
+```typescript
+const commission = Math.round(amount * distributorShare * 100) / 100
+```
+
+**验证**:
+- 如果 distributorShare = 0.9，commission = 0.9元 ✅
+- 如果 distributorShare = 0.009，commission = 0.009元 ❌
+
+---
+
+## 📝 诊断建议
+
+请提供以下信息以便诊断：
+
+1. **管理后台显示的值**:
+   - 进入 `/admin/referral-settings`
+   - 查看"分销比例"输入框中的值是多少？
+
+2. **实际佣金金额**:
+   - 用户A购买1元商品
+   - 推荐人B实际获得多少佣金？
+
+3. **小程序显示的比例**:
+   - 分销中心显示的是"你获得 xx% 收益"
+   - 这个 xx 是多少？
+
+---
+
+**根据你的反馈，我会立即定位并修复问题！**
diff --git a/开发文档/8、部署/佣金问题-快速诊断和修复.md b/开发文档/8、部署/佣金问题-快速诊断和修复.md
new file mode 100644
index 00000000..c4132559
--- /dev/null
+++ b/开发文档/8、部署/佣金问题-快速诊断和修复.md
@@ -0,0 +1,232 @@
+# 佣金计算问题 - 快速诊断和修复
+
+## 🚨 问题描述
+
+用户反馈："推广者应该获取支付金额的90%，但却是10%"
+
+---
+
+## 🔍 快速诊断
+
+### 方法1: 检查管理后台配置
+
+1. 登录管理后台：`https://soul.quwanzhi.com/admin`
+2. 进入「推广设置」页面：`/admin/referral-settings`
+3. 查看「分销比例」输入框中的数值
+
+**如果显示 10** → 配置错误，应该改为 **90**
+
+**如果显示 90** → 配置正确，问题在其他地方
+
+---
+
+### 方法2: 检查实际佣金
+
+1. 找一个推荐关系的订单
+2. 查看推荐人获得的佣金
+
+**示例**:
+- 用户B购买1元商品（无折扣）
+- 推荐人A应得：0.90元（90%）
+- 如果实际只得：0.10元 → 说明比例算反了
+
+---
+
+### 方法3: 检查小程序显示
+
+打开小程序「分销中心」，查看推广规则：
+
+**应该显示**:
+```
+好友成功付款后，你获得 90% 收益
+```
+
+**如果显示**:
+```
+好友成功付款后，你获得 10% 收益
+```
+
+→ 说明后端返回的 `shareRate` 值错误
+
+---
+
+## 🔧 修复方案
+
+### 修复1: 如果管理后台配置值错误
+
+**步骤**:
+1. 进入管理后台 `/admin/referral-settings`
+2. 将「分销比例」改为 **90**
+3. 点击「保存配置」
+4. 刷新小程序验证
+
+---
+
+### 修复2: 如果数据库配置值错误
+
+**手动修复SQL**:
+```sql
+-- 1. 查看当前配置
+SELECT config_value FROM system_config WHERE config_key = 'referral_config';
+
+-- 2. 如果 distributorShare 不是 90，手动更新
+UPDATE system_config 
+SET config_value = JSON_SET(
+  config_value, 
+  '$.distributorShare', 
+  90
+)
+WHERE config_key = 'referral_config';
+
+-- 3. 验证修改
+SELECT config_value FROM system_config WHERE config_key = 'referral_config';
+```
+
+---
+
+### 修复3: 如果计算公式错误
+
+**检查文件**: `app/api/miniprogram/pay/notify/route.ts`
+
+**第395行，当前代码应该是**:
+```typescript
+const commission = Math.round(amount * distributorShare * 100) / 100
+```
+
+**如果错误写成了**:
+```typescript
+// ❌ 错误1：算反了
+const commission = Math.round(amount * (1 - distributorShare) * 100) / 100
+
+// ❌ 错误2：没有先除100
+const distributorShare = config.distributorShare  // 90（没除100）
+const commission = amount * distributorShare / 100  // 1 * 90 / 100 = 0.9（看似对，但后续会错）
+```
+
+---
+
+## 🧪 验证步骤
+
+### 验证1: 手动计算
+
+假设配置 `distributorShare = 90`:
+
+```javascript
+// 读取配置
+const configValue = 90
+
+// 转换为小数
+const distributorShare = configValue / 100  // = 0.9
+
+// 计算佣金（购买1元）
+const commission = 1.00 * 0.9  // = 0.90元
+
+// 返回给小程序
+const shareRate = distributorShare * 100  // = 90
+```
+
+**预期**:
+- 购买1元 → 推荐人得 0.90元
+- 小程序显示：90% 返利
+
+---
+
+### 验证2: 查看实际订单
+
+**SQL查询**:
+```sql
+SELECT 
+  o.order_sn,
+  o.amount as 订单金额,
+  rb.total_commission as 累计佣金,
+  rb.purchase_count as 购买次数,
+  o.amount * 0.9 as 预期佣金90percent,
+  o.amount * 0.1 as 如果是10percent
+FROM orders o
+JOIN referral_bindings rb ON o.user_id = rb.referee_id
+WHERE o.status = 'paid'
+  AND rb.purchase_count > 0
+ORDER BY o.pay_time DESC
+LIMIT 5;
+```
+
+**对比**:
+- 如果 `total_commission ≈ 预期佣金90percent` → 计算正确
+- 如果 `total_commission ≈ 如果是10percent` → 计算错误（算反了）
+
+---
+
+## 🔍 代码审查
+
+### 关键代码1: 读取配置
+
+**文件**: `app/api/miniprogram/pay/notify/route.ts` 第357-360行
+
+```typescript
+const config = await getConfig('referral_config')
+if (config?.distributorShare) {
+  distributorShare = config.distributorShare / 100  // ✅ 应该是这样
+}
+```
+
+**如果错误写成**:
+```typescript
+distributorShare = config.distributorShare  // ❌ 没除100
+```
+
+---
+
+### 关键代码2: 计算佣金
+
+**文件**: `app/api/miniprogram/pay/notify/route.ts` 第395行
+
+```typescript
+const commission = Math.round(amount * distributorShare * 100) / 100
+// ✅ 正确：1 * 0.9 = 0.9
+```
+
+**如果错误写成**:
+```typescript
+const commission = Math.round(amount * (1 - distributorShare) * 100) / 100
+// ❌ 错误：1 * (1 - 0.9) = 0.1（算反了）
+```
+
+---
+
+### 关键代码3: 返回比例
+
+**文件**: `app/api/referral/data/route.ts` 第198行
+
+```typescript
+shareRate: Math.round(distributorShare * 100)
+// ✅ 正确：0.9 * 100 = 90
+```
+
+---
+
+## 🚀 立即检查
+
+请你帮我确认一下：
+
+### 问题1: 管理后台的配置值
+进入 `https://soul.quwanzhi.com/admin/referral-settings`，看看「分销比例」输入框中显示的是：
+- [ ] 90（正确）
+- [ ] 10（错误）
+- [ ] 0.9（错误）
+
+### 问题2: 小程序显示的比例
+打开小程序「分销中心」，查看推广规则显示的是：
+- [ ] "你获得 90% 收益"（正确）
+- [ ] "你获得 10% 收益"（错误）
+
+### 问题3: 实际佣金金额
+如果有测试订单，查看：
+- 购买金额：1.00元
+- 推荐人获得：_____ 元
+
+**如果是 0.90元** → 计算正确  
+**如果是 0.10元** → 计算错误
+
+---
+
+**请告诉我上述三个问题的实际情况，我会立即定位并修复！**
diff --git a/开发文档/8、部署/其它.md b/开发文档/8、部署/其它.md
new file mode 100644
index 00000000..ef1f24e7
--- /dev/null
+++ b/开发文档/8、部署/其它.md
@@ -0,0 +1,3 @@
+# 其它（合并自 宝塔配置检查、小程序上传复盘）
+
+宝塔配置检查说明、小程序上传复盘（版本 1.17、CLI 上传等）。详见原各文档。
diff --git a/开发文档/8、部署/分销与绑定流程图.md b/开发文档/8、部署/分销与绑定流程图.md
new file mode 100644
index 00000000..8fd78cee
--- /dev/null
+++ b/开发文档/8、部署/分销与绑定流程图.md
@@ -0,0 +1,383 @@
+# 分销与绑定流程图
+
+> 用流程图把「绑定」和「推荐人/邀请码」在系统中的用法讲清楚。  
+> 建议配合《邀请码分销规则说明》一起看。
+
+---
+
+## 一、概念速查
+
+| 名词 | 是什么 | 存哪儿 | 谁用 |
+|------|--------|--------|------|
+| **邀请码** | 一串码，如 `SOULABC123` | 每个用户一条：`users.referral_code` | 链接里 `ref=邀请码`，用来**认出**是谁推荐的 |
+| **推荐人** | 拿佣金的那个人（用户） | 用**用户ID**存：`referrer_id` | 绑定表、订单表、分佣都只认这个 ID |
+| **被推荐人** | 通过链接进来的访客/买家 | 用**用户ID**存：`referee_id` | 绑定表里「谁被谁推荐」 |
+
+关系：**邀请码** → 查 `users` 表 → 得到**推荐人用户ID**（referrer_id）。系统里所有「归属、分佣」只认 referrer_id，不直接认邀请码字符串。
+
+---
+
+## 二、整体流程总览（一图看懂）
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                          分销全流程：从分享到分佣                                  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  推广者 A（推荐人）                    访客/买家 B（被推荐人）                    系统
+
+        │                                      │                                  │
+        │  1. 分享带 ref 的链接                 │                                  │
+        │     ?ref=A的邀请码                    │                                  │
+        ├─────────────────────────────────────>│  2. 点击链接进入小程序/阅读页       │
+        │                                      ├─────────────────────────────────>│
+        │                                      │     app.js: 存 referral_code      │
+        │                                      │     可选: 记录访问 referral_visit  │
+        │                                      │                                  │
+        │                                      │  3. 登录（微信/手机号/getOpenId 拿到 user） │
+        │                                      ├─────────────────────────────────>│
+        │                                      │     登录成功即调 /api/referral/bind  │
+        │                                      │     入参: userId, referralCode    │
+        │                                      │                                  │
+        │                                      │                    4. 绑定逻辑    │
+        │                                      │                    referral_code  │
+        │                                      │                    → 查 users 得  │
+        │                                      │                    referrer_id=A │
+        │                                      │                    写 referral_   │
+        │                                      │                    bindings      │
+        │                                      │                    (referee=B,   │
+        │                                      │                     referrer=A)  │
+        │                                      │<─────────────────────────────────┤
+        │                                      │  绑定成功（new/renew/takeover）   │
+        │                                      │                                  │
+        │                                      │  5. 下单（章节/找伙伴）            │
+        │                                      │     POST /api/miniprogram/pay     │
+        │                                      │     body: referralCode(可选)      │
+        │                                      ├─────────────────────────────────>│
+        │                                      │                    6. 定推荐人    │
+        │                                      │                    先查 bindings │
+        │                                      │                    (referee=B)→A  │
+        │                                      │                    无则用 referral│
+        │                                      │                    Code 解析→A   │
+        │                                      │                    写 orders.     │
+        │                                      │                    referrer_id=A,│
+        │                                      │                    referral_code │
+        │                                      │<─────────────────────────────────┤
+        │                                      │  返回支付参数                     │
+        │                                      │                                  │
+        │                                      │  7. 调起微信支付                   │
+        │                                      ├───────────────────────────────> 微信
+        │                                      │  8. 用户付款成功                   │
+        │                                      │<───────────────────────────────  微信
+        │                                      │                                  │
+        │                                      │                    9. 支付回调    │
+        │                                      │                    POST .../notify│
+        │                                      │                    查 bindings    │
+        │                                      │                    (referee=B)→A  │
+        │                                      │                    佣金=金额×90%  │
+        │                                      │                    A.pending_     │
+        │                                      │                    earnings += 佣金│
+        │                                      │                    binding→      │
+        │                                      │                    converted     │
+        │                                      │                                  │
+        │  10. 推广者 A 看到待结算收益 +90%     │                                  │
+        │<─────────────────────────────────────│                                  │
+```
+
+---
+
+## 三、绑定流程（邀请码 → 推荐关系）
+
+绑定解决的是：**「谁（B）是通过谁（A）的链接来的」**，并写入 `referral_bindings`。
+
+**绑定规则（后端统一保证）：**
+- **不重复绑定**：被推荐人 B 已有**当前推荐人 A** 的有效绑定时，再次用 A 的邀请码调用 bind → **不新建记录**，只做**续期**（把过期时间再延长 30 天）。
+- **有时效**：每条绑定的有效期为 **30 天**（`expiry_date`）；分佣、下单定推荐人时只认「未过期」的绑定。
+- **超时可重新绑定**：超过 30 天未续期的绑定视为过期；此时 B 再通过**其他人 C** 的链接进来并登录 → 允许绑定到 C（旧绑定标记过期，新绑定 C，即「抢夺」）；若仍通过 A 的链接 → 续期 A 的绑定。
+
+**绑定从登录就开始**：只要前端拿到 userId（登录成功），就立刻用当前的 `pendingReferralCode` 调 `/api/referral/bind`，不等到下单。后端根据上述规则决定是**新绑定 / 续期 / 抢夺 / 拒绝**。
+
+```mermaid
+flowchart TB
+    subgraph 入口
+        A1["推广者 A 分享链接<br/>带 ref=A的邀请码"]
+        A2["访客 B 点击链接进入"]
+    end
+
+    subgraph 前端
+        B1["app.js: 检测到 ref"]
+        B2["写入 storage: referral_code + pendingReferralCode"]
+        B3["若已登录 → 立即调 bind"]
+        B4["若未登录 → 等任意登录成功后再调 bind"]
+        B5["登录含: login / loginWithPhone / getOpenId 拿到 user 时"]
+    end
+
+    subgraph 后端绑定API["POST /api/referral/bind"]
+        C1["入参: userId(B), referralCode"]
+        C2["用 referralCode 查 users 表 → 推荐人 A"]
+        C3["不能自己推荐自己"]
+        C4["查 B 是否已有有效绑定(active)"]
+        C5{"已有绑定?"}
+        C6["同一推荐人 A → 只续期，不重复绑定<br/>expiry = 当前+30天"]
+        C7["不同人且已过期(>30天) → 可重新绑定<br/>旧绑定过期，新绑定 A"]
+        C8["不同人且未过期 → 拒绝"]
+        C9["无绑定 / 续期 / 抢夺后 → 写 binding<br/>referrer_id=A, referee_id=B, expiry=+30天"]
+    end
+
+    A1 --> A2 --> B1 --> B2
+    B2 --> B3
+    B2 --> B4
+    B4 --> B5
+    B3 --> C1
+    B5 --> C1
+    C1 --> C2 --> C3 --> C4 --> C5
+    C5 -->|无| C9
+    C5 -->|有，同一人| C6 --> C9
+    C5 -->|有，另一人已过期| C7 --> C9
+    C5 -->|有，另一人未过期| C8
+```
+
+要点：
+- **绑定表**是「谁推荐了谁」的**唯一权威**；分佣只看这张表。
+- **已有绑定不重复**：同一推荐人再次绑只续期；**30 天**内不能换绑其他推荐人，超过 30 天可重新绑定（被新推荐人「抢夺」或原推荐人续期）。
+- **邀请码**只在「解析出推荐人是谁」时用，解析完得到的是 **referrer_id**（用户ID）。
+
+---
+
+## 四、下单时「推荐人」怎么定（写订单）
+
+创建订单时要把「这笔单算谁的推广」记在 `orders.referrer_id` 和 `orders.referral_code`。逻辑是：**先认绑定，再认邀请码**。
+
+```mermaid
+flowchart LR
+    subgraph 请求
+        R1["POST /api/miniprogram/pay"]
+        R2["body: userId(B), referralCode(可选)"]
+    end
+
+    subgraph 定推荐人
+        S1["查 referral_bindings"]
+        S2["WHERE referee_id = B<br/>AND status='active'<br/>AND expiry_date > NOW()"]
+        S3{"查到有效绑定?"}
+        S4["referrer_id = 绑定里的 referrer_id"]
+        S5["referrer_id = 用 referralCode<br/>查 users 得到的 id"]
+        S6["都无 → referrer_id = null"]
+    end
+
+    subgraph 写订单
+        T1["INSERT orders"]
+        T2["referrer_id = 上面得到的"]
+        T3["referral_code = 请求里的 referralCode<br/>或推荐人当前 users.referral_code"]
+    end
+
+    R1 --> R2 --> S1 --> S2 --> S3
+    S3 -->|是| S4
+    S3 -->|否，但有 referralCode| S5
+    S3 -->|否且无| S6
+    S4 --> T1
+    S5 --> T1
+    S6 --> T1
+    T1 --> T2 --> T3
+```
+
+结论：
+- **有绑定** → 订单的推荐人 = 绑定里的推荐人（与下单时传不传 referralCode 无关）。
+- **无绑定但传了 referralCode** → 用邀请码解析出推荐人，写入订单。
+- 订单上的 **referrer_id** 用于后台展示、对账；**分佣不看订单**，只看绑定表。
+
+---
+
+## 五、分佣流程（支付成功后）
+
+分佣**只看绑定表**，不看订单上的 referrer_id。
+
+```mermaid
+flowchart TB
+    subgraph 触发
+        P1["微信支付成功"]
+        P2["POST /api/miniprogram/pay/notify"]
+        P3["body: 订单号、金额、买家等"]
+    end
+
+    subgraph 回调逻辑
+        Q1["更新订单 status=paid"]
+        Q2["解锁用户权限(章节/全书)"]
+        Q3["查 referral_bindings"]
+        Q4["WHERE referee_id = 买家"]
+        Q5["AND status='active'"]
+        Q6["AND expiry_date > NOW()"]
+        Q7{"查到有效绑定?"}
+        Q8["取 referrer_id = 推广者 A"]
+        Q9["佣金 = 订单金额 × 90%"]
+        Q10["A.pending_earnings += 佣金"]
+        Q11["该绑定 status → converted"]
+        Q12["记录 commission_amount, order_id"]
+        Q13["不分佣"]
+    end
+
+    P1 --> P2 --> P3 --> Q1 --> Q2 --> Q3 --> Q4 --> Q5 --> Q6 --> Q7
+    Q7 -->|是| Q8 --> Q9 --> Q10 --> Q11 --> Q12
+    Q7 -->|否| Q13
+```
+
+要点：
+- 分佣**只认** `referral_bindings` 里「买家 → 有效绑定 → 推荐人」。
+- 订单里的 referrer_id / referral_code **不参与**分佣计算，只用于统计和展示。
+
+---
+
+### 什么情况下能拿到佣金（推广者视角）
+
+满足下面**全部**条件时，你（推广者）才能拿到这笔订单的佣金：
+
+1. **对方是通过你的链接进来的**  
+   对方点击的链接里带有你的邀请码（如 `?ref=你的邀请码`），进入小程序后系统会记下推荐码，并在登录时用于绑定。
+
+2. **对方已经绑定到你**  
+   对方完成登录后，系统成功调用了绑定接口（新绑定或续期），且当前存在一条「被推荐人 = 对方、推荐人 = 你」的绑定记录，且该绑定 **status = active**、**expiry_date > 当前时间**（在 30 天有效期内或已续期）。
+
+3. **对方在绑定有效期内下单并支付成功**  
+   对方在上述有效期内发起了购买（章节或全书），并完成微信支付；支付成功后，微信会回调我们的接口。
+
+4. **支付回调时仍能查到你的有效绑定**  
+   支付成功回调执行时，系统按「买家 = 对方」查 `referral_bindings`，能查到一条有效绑定且推荐人是你，才会把约 90% 的佣金计入你的待结算收益（pending_earnings），并把该绑定标记为已转化（converted）。
+
+**简单记**：你的链接 → 对方进来并登录绑定到你 → 有效期内对方付款 → 你拿佣金。
+
+---
+
+### 章节分享这块的分销收益方式
+
+章节页分享（读某一章时分享给好友/朋友圈）与首页、推广中心的分享**用同一套绑定与分佣规则**，只是落地页是「某一章」的阅读页。收益方式如下：
+
+1. **入口与绑定**  
+   你从阅读页分享出去的链接带 `ref=你的邀请码`（例如 `/pages/read/read?id=1.2&ref=你的邀请码`）。对方点进后进入**该章节**阅读页，系统记下推荐码；对方**登录**后即完成绑定（新绑定或续期）。绑定规则（30 天、不重复绑、超时可重绑）与其它分享入口一致。
+
+2. **收益比例**  
+   订单实付金额的**约 90%** 给推广者（与全书、其它章节一致，由 `referral_config.distributorShare` 配置）。对方买的是**这一章、别的章还是全书**，都按该笔订单金额 × 90% 计算佣金。
+
+3. **计佣次数（每个被推荐人只计一次）**  
+   系统在支付成功回调里会查「该买家」的**有效绑定**，有则给推荐人加佣金，并把这条绑定标记为**已转化（converted）**。  
+   因此：**同一个被推荐人在绑定有效期内，只有其「第一笔」支付会给你分佣**；该用户之后再买其它章节或全书，**不再**重复给你分佣（绑定已用掉）。
+
+4. **小结**  
+   **章节分享的收益**：你分享章节链接（带 ref）→ 对方进来并登录绑定到你 → 对方在有效期内**第一次**支付（可以是这一章、别的章或全书）→ 你获得**该笔订单金额的约 90%**；该用户后续订单不再给你分佣。
+
+---
+
+## 六、推荐人 vs 邀请码（怎么用、不混用）
+
+```mermaid
+flowchart LR
+    subgraph 入口
+        L1["链接 ref=SOULABC123"]
+    end
+
+    subgraph 解析
+        L2["邀请码 = SOULABC123"]
+        L3["users WHERE referral_code = ?"]
+        L4["推荐人 = 该用户的 id"]
+    end
+
+    subgraph 存储
+        M1["referral_bindings.referrer_id"]
+        M2["orders.referrer_id"]
+        M3["分佣发给谁"]
+    end
+
+    L1 --> L2 --> L3 --> L4
+    L4 --> M1
+    L4 --> M2
+    L4 --> M3
+
+    style L2 fill:#f9f,stroke:#333
+    style L4 fill:#9f9,stroke:#333
+```
+
+- **邀请码**：只在「从链接/请求里认出是谁」这一步用，用完就解析成 **referrer_id**。
+- **推荐人**：所有「归属、分佣、统计」都只用 **referrer_id**，不会把邀请码字符串当推荐人存。
+
+---
+
+## 七、表与字段关系简图
+
+```mermaid
+erDiagram
+    users ||--o{ referral_bindings : "referrer_id"
+    users ||--o{ referral_bindings : "referee_id"
+    users {
+        string id PK
+        string referral_code "自己的邀请码"
+    }
+    referral_bindings {
+        string referrer_id "推荐人(谁拿佣金)"
+        string referee_id "被推荐人(买家)"
+        string status "active|converted|expired"
+        timestamp expiry_date
+    }
+    orders {
+        string user_id "买家"
+        string referrer_id "推荐人ID(展示/对账)"
+        string referral_code "下单时邀请码(展示)"
+    }
+    referral_bindings ||--o{ orders : "分佣时关联"
+```
+
+- **绑定**：`referrer_id` = 推荐人，`referee_id` = 被推荐人；分佣只看这张表。
+- **订单**：`referrer_id`、`referral_code` 只做展示和对账，不参与分佣计算。
+
+---
+
+## 八、逻辑漏洞与注意点
+
+以下为与流程图、实现对照后容易出现的漏洞和设计注意点，便于排查与加固。
+
+### 8.1 严重：支付回调中买家身份不能信任客户端
+
+**问题**：支付回调（`/api/miniprogram/pay/notify`）里若**优先**使用请求体/attach 里的 `userId` 作为买家，则该 `userId` 来自**创建订单时客户端传入**的 `body.userId`。若被篡改（如传成他人 userId），会导致：
+- 订单归属、解锁权限记到错误用户；
+- 分佣按「错误买家」查绑定表，可能把佣金算到错误推荐人或不分佣。
+
+**正确做法**：**买家身份必须以微信回调中的 `openId` 为准**（微信侧不可伪造），用 `openId` 查 `users` 得到 `buyerUserId`；attach 中的 `userId` 仅作辅助或校验，不一致时以 openId 解析结果为准。
+
+**实现建议**：在 notify 中先 `buyerUserId = 由 openId 查 users 得到`；若查不到再回退到 attach.userId，并打日志告警。
+
+---
+
+### 8.2 设计缺口：先下单、后绑定会导致无分佣
+
+**问题**：流程图要求「先绑定、再下单」分佣才生效。若用户通过 A 的链接进入但**未调用** `/api/referral/bind`（未登录就下单、或 bind 失败/漏调），下单时传了 `referralCode`，订单上会有 `referrer_id=A`，但**分佣只看绑定表**，此时无绑定 → 不会给 A 分佣。
+
+**结论**：这是当前设计下的预期行为，不是 bug，但需要在产品/运营上保证「进入后尽快登录并完成绑定」，或在文档中明确写清：**只有存在有效绑定时支付成功才会分佣**。
+
+---
+
+### 8.3 重复回调与重复分佣
+
+**现状**：微信可能对同一笔支付多次回调。当前实现：
+- 订单状态已为 `paid` 时跳过订单更新；
+- 分佣时只取 `status='active'` 的绑定，且分佣后将该绑定置为 `converted`，同一买家不会再有第二条 active 绑定参与分佣。
+
+因此**不会重复加佣**。无需改流程图，实现已防护。
+
+---
+
+### 8.4 绑定表与 users.referred_by 双写
+
+**现状**：绑定 API 在「新绑定」或「抢夺」时会写 `users.referred_by`，与 `referral_bindings` 双写；「续期」只更新绑定表，不改 `referred_by`。  
+分佣、下单定推荐人**只读绑定表**；GET 查询「我的推荐人」等可能读 `users.referred_by`。只要绑定接口保证 new/takeover 时双写一致，则无逻辑漏洞。若以后有接口只改 `referred_by` 而不改绑定表，就会不一致，需避免。
+
+---
+
+### 8.5 小结
+
+| 类型       | 说明 |
+|------------|------|
+| 必须修     | 支付回调中买家身份以 openId 解析为准，不信任 attach.userId。 |
+| 文档/产品  | 明确「先绑定再下单才能分佣」；未绑定仅下单只记订单归属、不分佣。 |
+| 已防护     | 重复回调不会导致重复分佣。 |
+| 需长期一致 | 绑定表与 users.referred_by 在 new/takeover 时双写，避免单改其一。 |
+
+---
+
+若要把某一段改成「按步骤」的纯文字版或拆成多张图，可以说明要哪一段（绑定 / 下单 / 分佣 / 概念）。
diff --git a/开发文档/8、部署/分销提现流程图.md b/开发文档/8、部署/分销提现流程图.md
new file mode 100644
index 00000000..45835765
--- /dev/null
+++ b/开发文档/8、部署/分销提现流程图.md
@@ -0,0 +1,127 @@
+# 分销提现流程图
+
+## 一、整体流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                            小 程 序 端                                           │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  [用户] 推广中心 → 可提现金额 ≥ 最低额 → 点击「申请提现」
+       │
+       ▼
+  POST /api/miniprogram/withdraw  (WithdrawPost)
+       │ 校验：可提现余额、最低金额、用户 openId
+       ▼
+  写入 withdrawals：status = pending
+       │
+       ▼
+  提示「提现申请已提交，审核通过后将打款至您的微信零钱」
+
+─────────────────────────────────────────────────────────────────────────────────
+
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                            管 理 端 (soul-admin)                                  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  [管理员] 分销 / 提现审核 → GET /api/admin/withdrawals 拉列表
+       │
+       ├── 点「拒绝」 → PUT /api/admin/withdrawals { action: "reject" }
+       │                    ▼
+       │                status = failed，写 error_message
+       │
+       └── 点「通过」 → PUT /api/admin/withdrawals { action: "approve" }
+                            │
+                            ▼
+                       调 wechat.InitiateTransferByFundApp (FundApp 单笔)
+                            │
+            ┌───────────────┼───────────────┐
+            ▼               ▼               ▼
+       [微信报错]      [未返回单号]      [成功受理]
+            │               │               │
+            ▼               ▼               ▼
+       status=failed   status=failed   status=processing
+       返回报错信息     返回提示         写 detail_no,batch_no,batch_id
+                                       返回「已发起打款，微信处理中」
+
+─────────────────────────────────────────────────────────────────────────────────
+
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                            微 信 侧 与 回 调                                       │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  微信异步打款
+       │
+       ▼
+  打款结果 → POST /api/payment/wechat/transfer/notify (PaymentWechatTransferNotify)
+       │ 验签、解密，得到 out_bill_no / transfer_bill_no / state / fail_reason
+       │ 用 detail_no = out_bill_no 找到提现记录，且仅当 status 为 processing / pending_confirm 时更新
+       ▼
+  state=SUCCESS  → status = success
+  state=FAIL/CANCELLED → status = failed，写 fail_reason
+
+─────────────────────────────────────────────────────────────────────────────────
+
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                            可 选：主 动 同 步                                      │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  管理端 POST /api/admin/withdrawals/sync（可带 id 同步单条，或不带 id 同步所有）
+       │ 只处理 status IN (processing, pending_confirm)
+       │ FundApp 单笔：用 detail_no 调 QueryTransferByOutBill
+       ▼
+  按微信返回的 state 更新 status = success / failed（与回调逻辑一致）
+
+─────────────────────────────────────────────────────────────────────────────────
+
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                            小 程 序「我 的」- 待 确 认 收 款                        │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  [用户] 我的页 → 仅登录显示「待确认收款」区块
+       │
+       ▼
+  GET /api/miniprogram/withdraw/pending-confirm?userId=xxx  (WithdrawPendingConfirm)
+       │ 只返回 status IN (processing, pending_confirm) 的提现（审核通过后的）
+       ▼
+  展示列表：金额、日期、「确认收款」按钮
+       │
+       ▼
+  点击「确认收款」→ 需要 item.package + mchId + appId 调 wx.requestMerchantTransfer
+       │ 当前后端 list 里 package 为空，故会提示「请稍后刷新再试」
+       └─ 若后续接入微信返回的 package，可在此完成「用户确认收款」闭环
+```
+
+## 二、状态流转
+
+| 阶段         | 状态 (status)   | 含义 |
+|--------------|----------------|------|
+| 用户申请     | **pending**    | 待审核，已占可提现额度 |
+| 管理员通过   | **processing** | 已发起打款，微信处理中 |
+| 微信回调成功 | **success**    | 打款成功（已到账） |
+| 微信回调失败/拒绝 | **failed**  | 打款失败，写 fail_reason |
+| 预留         | **pending_confirm** | 待用户确认收款（当前流程未改此状态，仅接口可返回） |
+
+## 三、可提现与待确认口径
+
+- **可提现** = 累计佣金 − 已提现 − 待审核金额  
+  待审核金额 = 所有 status 为 `pending`、`processing`、`pending_confirm` 的提现金额之和。
+- **待确认收款列表**：仅包含 **审核已通过** 的提现，即 status 为 `processing` 或 `pending_confirm`，不包含 `pending`。
+
+## 四、主要接口与代码位置
+
+| 环节       | 接口/行为 | 代码位置 |
+|------------|-----------|----------|
+| 用户申请   | POST `/api/miniprogram/withdraw` | soul-api `internal/handler/withdraw.go` WithdrawPost |
+| 可提现计算 | referral/data、withdraw 校验 | `withdraw.go` computeAvailableWithdraw；`referral.go` 提现统计 |
+| 管理端列表 | GET `/api/admin/withdrawals` | `internal/handler/admin_withdrawals.go` AdminWithdrawalsList |
+| 管理端通过/拒绝 | PUT `/api/admin/withdrawals` | `admin_withdrawals.go` AdminWithdrawalsAction |
+| 微信打款   | FundApp 单笔 | soul-api `internal/wechat/transfer.go` InitiateTransferByFundApp |
+| 微信回调   | POST `/api/payment/wechat/transfer/notify` | `internal/handler/payment.go` PaymentWechatTransferNotify |
+| 管理端同步 | POST `/api/admin/withdrawals/sync` | `admin_withdrawals.go` AdminWithdrawalsSync |
+| 待确认列表 | GET `/api/miniprogram/withdraw/pending-confirm` | `withdraw.go` WithdrawPendingConfirm |
+
+## 五、说明
+
+- 当前实现：审核通过后直接调微信 FundApp 单笔打款，最终由**微信回调**或**管理端同步**把状态更新为 success/failed。
+- 「待确认收款」列表只展示已审核通过的记录；点击「确认收款」需后端下发的 `package` 才能调起 `wx.requestMerchantTransfer`，目前该字段为空，前端会提示「请稍后刷新再试」。若后续接入微信返回的 package，可在此完成用户确认收款闭环。
diff --git a/开发文档/8、部署/存客宝API-Key约定.md b/开发文档/8、部署/存客宝API-Key约定.md
new file mode 100644
index 00000000..030d68a6
--- /dev/null
+++ b/开发文档/8、部署/存客宝API-Key约定.md
@@ -0,0 +1,28 @@
+# 存客宝 API Key 约定
+
+## 约定说明
+
+存客宝（ckbapi.quwanzhi.com）不同业务使用**不同的 apiKey**，对接时需按场景选用，避免混用。
+
+| 场景 | 用途 | Key 来源 | 说明 |
+|------|------|----------|------|
+| **链接卡若** | 首页「链接卡若」留资，添加卡若为好友 | 环境变量 `CKB_LEAD_API_KEY` | 需在 .env 中配置；未配置时回退为下方「其他场景」的 key；请求方式为 **POST** + JSON（name, phone, wechatId, apiKey, timestamp, sign） |
+| **其他** | join（团队/资源/导师/合伙）、match（找伙伴匹配）等 | 代码常量 `ckbAPIKey` | 当前为 `fyngh-ecy9h-qkdae-epwd5-rz6kd` |
+
+## 配置示例
+
+- **链接卡若**（添加好友需用专用 key，示例）：
+  ```env
+  CKB_LEAD_API_KEY=2y4v5-rjhfc-sg5wy-zklkv-bg0tl
+  ```
+- 后续若有其他「添加某某为好友」类场景，由存客宝提供对应 key，再在配置或代码中单独挂接，**不要与链接卡若的 key 混用**。
+
+## 代码位置
+
+- soul-api：`internal/handler/ckb.go`
+  - 链接卡若：`CKBLead` 中读取 `config.Get().CkbLeadAPIKey`，有则用，无则用 `ckbAPIKey`
+  - join/match：统一使用 `ckbAPIKey`
+
+---
+
+记录时间：2025-03；原因：链接卡若需专用 key 才能正常添加好友，其他场景用另一 key。
diff --git a/开发文档/8、部署/宝塔-Docker首次配置指南.md b/开发文档/8、部署/宝塔-Docker首次配置指南.md
new file mode 100644
index 00000000..1b1b4374
--- /dev/null
+++ b/开发文档/8、部署/宝塔-Docker首次配置指南.md
@@ -0,0 +1,136 @@
+# soul-api 测试环境 - 宝塔 Docker 首次配置指南
+
+> 运行 `python devloy.py --mode runner` 前，在宝塔服务器上完成本指南的一次性配置。
+
+---
+
+## 一、devloy.py 会做什么（Runner 模式）
+
+在 soul-api 目录执行：
+
+```powershell
+python devloy.py --mode runner
+```
+
+会自动完成：
+
+1. 本地 go build 交叉编译 Linux 二进制
+2. 打包二进制 + .env.development + certs 为 tar.gz
+3. 通过 SSH 上传到服务器
+4. 上传到 Runner 容器内，执行红蓝切换
+5. 宝塔 Nginx 固定 `proxy_pass http://127.0.0.1:9001`，无需改配置
+
+---
+
+## 二、宝塔服务器一次性配置
+
+### 1. 安装 Docker 和 Docker Compose
+
+在宝塔终端或 SSH 执行：
+
+```bash
+curl -fsSL https://get.docker.com | sh
+systemctl enable docker
+systemctl start docker
+
+# Docker Compose
+curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+chmod +x /usr/local/bin/docker-compose
+```
+
+### 2. 首次启动 Runner 容器
+
+在服务器上（或通过 SSH 上传 soul-api 后）：
+
+```bash
+cd /path/to/soul-api
+bash deploy/runner-init.sh
+```
+
+会构建 `soul-api-runner:latest` 并启动容器，监听 9001。
+
+### 3. 配置 Nginx 站点
+
+在宝塔：**网站** → 找到 `souldev.quwanzhi.com`（若没有则新建站点）
+
+**设置** → **配置文件**，确保 `location /` 为反向代理：
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:9001;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+- Runner 模式固定 9001，无需 8081/8082
+- 删除或注释掉原来的 `root`、`index` 等静态配置，否则会 404
+
+保存后点击 **重载配置**。
+
+---
+
+## 三、本地环境变量（执行 devloy.py 前）
+
+| 变量 | 示例 | 说明 |
+|------|------|------|
+| DEPLOY_HOST | 43.139.27.93 | 宝塔服务器 IP |
+| DEPLOY_USER | root | SSH 用户名 |
+| DEPLOY_PASSWORD | xxx | SSH 密码 |
+| DEPLOY_SSH_PORT | 22022 | SSH 端口 |
+| DEPLOY_DOCKER_PATH | /www/wwwroot/self/soul-dev | 测试环境部署目录（Runner 模式也会用到） |
+
+PowerShell 示例：
+
+```powershell
+$env:DEPLOY_HOST="43.139.27.93"
+$env:DEPLOY_USER="root"
+$env:DEPLOY_PASSWORD="你的密码"
+$env:DEPLOY_DOCKER_PATH="/www/wwwroot/self/soul-dev"
+```
+
+**注意**：Runner 模式不需要 `DEPLOY_NGINX_CONF`（Nginx 固定 9001）。若用 `--mode docker` 蓝绿模式才需要。
+
+---
+
+## 四、首次部署前检查
+
+1. **soul-api 目录**：已有 `.env.development`（devloy 固定用测试环境配置）
+2. **certs/**：包含 `apiclient_cert.pem`、`apiclient_key.pem`
+3. **服务器**：已执行 `deploy/runner-init.sh`，Runner 容器在跑
+4. **宝塔**：souldev.quwanzhi.com 的 Nginx 已配置 `proxy_pass http://127.0.0.1:9001`
+
+---
+
+## 五、执行部署
+
+```powershell
+cd soul-api
+python devloy.py --mode runner
+```
+
+首次会构建并上传，之后每次有代码变更再执行即可，容器内红蓝切换、零停机。
+
+---
+
+## 六、常见问题
+
+### Nginx 404
+
+确认 `location /` 已改为 `proxy_pass http://127.0.0.1:9001`，且删除了 `root`、`index` 等静态配置。详见 [宝塔反向代理说明](宝塔反向代理说明.md)。
+
+### 健康检查超时
+
+```bash
+curl -s http://127.0.0.1:9001/health
+```
+
+若失败，检查 Runner 容器是否在跑：`docker ps | grep soul-api-runner`，以及 `.env` 中 DB_DSN、REDIS 等配置。
+
+### 正式与测试域名区分
+
+- **正式**：soulapi.quwanzhi.com → master.py → 8080
+- **测试**：souldev.quwanzhi.com → devloy.py --mode runner → 9001
diff --git a/开发文档/8、部署/宝塔面板配置订单同步定时任务.md b/开发文档/8、部署/宝塔面板配置订单同步定时任务.md
new file mode 100644
index 00000000..58f9a2af
--- /dev/null
+++ b/开发文档/8、部署/宝塔面板配置订单同步定时任务.md
@@ -0,0 +1,369 @@
+# 宝塔面板配置订单同步定时任务
+
+> 适用于：有宝塔面板的服务器  
+> 难度：⭐（非常简单，3 分钟搞定）
+
+---
+
+## 一、准备工作
+
+### 1. 生成安全密钥
+
+打开终端（本地电脑），执行：
+
+```bash
+# Windows PowerShell
+-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_})
+
+# 或手动生成一个 32 位随机字符串，例如：
+# 密钥已写死在代码里，见下文 URL
+```
+
+**接口使用的固定密钥**：`soul_cron_sync_orders_2026`（无需自己生成）
+
+---
+
+## 二、宝塔面板配置步骤
+
+### 步骤 1：登录宝塔面板
+
+1. 浏览器打开：`http://你的服务器IP:8888`
+2. 输入账号密码登录
+
+### 步骤 2：打开计划任务
+
+1. 左侧菜单点击 **"计划任务"**
+2. 点击右上角 **"添加任务"**
+
+### 步骤 3：配置任务（方案 A - 访问 URL，推荐）
+
+在弹出的对话框中填写：
+
+| 字段 | 填写内容 | 说明 |
+|------|---------|------|
+| **任务类型** | 选择 `访问URL` | 下拉框选择 |
+| **任务名称** | `订单状态同步` | 随便填，方便识别 |
+| **执行周期** | 选择 `N分钟` | 下拉框选择 |
+| **分钟选择** | 填 `5` | 表示每 5 分钟执行一次 |
+| **URL地址** | `https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026` | 密钥已写死在代码里，无需修改 |
+
+**完整 URL 示例**（密钥已写死在代码里，直接用即可）：
+```
+https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026
+```
+
+### 步骤 4：点击保存
+
+点击底部的 **"提交"** 或 **"确定"** 按钮。
+
+### 步骤 5：验证任务已添加
+
+在任务列表中应该能看到：
+- ✅ 任务名称：订单状态同步
+- ✅ 类型：访问URL
+- ✅ 周期：每 5 分钟
+- ✅ 状态：正常（绿色）
+
+---
+
+## 三、立即测试执行
+
+### 方法 1：宝塔面板手动执行
+
+1. 在任务列表中找到刚添加的任务
+2. 点击右侧的 **"执行"** 按钮
+3. 查看执行结果：
+   - 成功：显示 JSON 响应 `{"success":true,...}`
+   - 失败：显示错误信息
+
+### 方法 2：浏览器测试
+
+直接在浏览器打开：
+```
+https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET
+```
+
+**预期响应**（成功）：
+```json
+{
+  "success": true,
+  "message": "订单状态同步完成",
+  "total": 0,
+  "synced": 0,
+  "expired": 0,
+  "error": 0,
+  "duration": 123
+}
+```
+
+**如果响应 401 错误**：
+```json
+{
+  "success": false,
+  "error": "未授权访问"
+}
+```
+说明密钥不对，检查 URL 中的 `secret` 参数。
+
+---
+
+## 四、查看执行日志
+
+### 宝塔面板查看
+
+1. 计划任务列表
+2. 找到"订单状态同步"任务
+3. 点击右侧的 **"日志"** 按钮
+4. 查看最近的执行记录
+
+**正常日志示例**：
+```
+[2026-02-04 21:00:00] 开始执行
+[2026-02-04 21:00:01] 状态码: 200
+[2026-02-04 21:00:01] 响应: {"success":true,"synced":0,"expired":0}
+[2026-02-04 21:00:01] 执行完成
+```
+
+---
+
+## 五、配置环境变量（重要！）
+
+定时任务需要密钥验证，必须在项目中配置：
+
+### 方法 1：通过宝塔面板配置
+
+1. 左侧菜单 → **网站**
+2. 找到 `soul.quwanzhi.com` 网站
+3. 点击 **设置**
+4. 左侧选择 **"伪静态"** 或 **"配置文件"**（取决于宝塔版本）
+5. 找到 Node.js 项目的启动配置
+
+### 方法 2：在项目根目录创建 `.env.production`
+
+SSH 登录服务器：
+```bash
+ssh root@你的服务器IP
+
+cd /www/wwwroot/soul
+
+# 编辑 .env.production
+nano .env.production
+```
+
+添加以下内容：
+```bash
+# 定时任务密钥（与宝塔任务中的 secret 保持一致）
+# CRON_SECRET 已写死在代码，无需配置
+
+# 微信支付 API 密钥（从微信商户平台获取）
+WECHAT_API_KEY=你的32位API密钥
+```
+
+保存后重启项目：
+```bash
+pm2 restart soul
+```
+
+---
+
+## 六、方案 B：Shell 脚本（备选）
+
+如果不想用 URL 方式，也可以用 Shell 脚本：
+
+### 步骤 1：添加任务
+
+任务类型选择：`Shell 脚本`
+
+### 步骤 2：填写脚本
+
+```bash
+#!/bin/bash
+curl -X GET "https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET" >> /www/wwwlogs/cron_sync_orders.log 2>&1
+```
+
+### 步骤 3：设置执行周期
+
+- 类型：N分钟
+- 周期：5
+
+---
+
+## 七、方案 C：Python 脚本（高级）
+
+如果你想用 Python 脚本直接执行：
+
+### 步骤 1：确保 Python 环境
+
+```bash
+# SSH 登录服务器
+ssh root@你的服务器IP
+
+# 安装依赖
+pip3 install pymysql requests
+```
+
+### 步骤 2：上传脚本
+
+确保脚本已上传到服务器：
+```
+/www/wwwroot/soul/scripts/sync_order_status.py
+```
+
+### 步骤 3：宝塔添加任务
+
+- 任务类型：`Shell 脚本`
+- 脚本内容：
+  ```bash
+  cd /www/wwwroot/soul && python3 scripts/sync_order_status.py >> /www/wwwlogs/sync_orders.log 2>&1
+  ```
+- 执行周期：每 5 分钟
+
+---
+
+## 八、验证是否生效
+
+### 1. 创建测试订单
+
+```sql
+-- 通过宝塔面板 → 数据库 → soul_miniprogram → SQL窗口
+INSERT INTO orders (id, order_sn, user_id, open_id, product_type, product_id, amount, status, created_at, updated_at)
+VALUES ('TEST_SYNC', 'TEST_SYNC_001', 'test_user', 'test_openid', 'section', '1.2', 1.00, 'created', DATE_SUB(NOW(), INTERVAL 35 MINUTE), DATE_SUB(NOW(), INTERVAL 35 MINUTE));
+```
+
+### 2. 等待定时任务执行（最多 5 分钟）
+
+或手动执行：宝塔面板 → 计划任务 → 点击"执行"
+
+### 3. 查询订单状态
+
+```sql
+SELECT order_sn, status, created_at, updated_at 
+FROM orders 
+WHERE order_sn = 'TEST_SYNC_001';
+```
+
+**预期结果**：
+- 状态应该变为 `expired`（因为超过 30 分钟）
+
+### 4. 清理测试数据
+
+```sql
+DELETE FROM orders WHERE order_sn = 'TEST_SYNC_001';
+```
+
+---
+
+## 九、常见问题排查
+
+### Q1: 任务显示"执行失败"
+
+**可能原因**：
+1. URL 地址错误
+2. 密钥不对（401 错误）
+3. 服务器网络问题
+
+**解决方案**：
+1. 检查 URL 是否完整
+2. 检查 `secret` 参数是否与 `.env.production` 中一致
+3. 在浏览器中手动访问该 URL 测试
+
+### Q2: 返回 401 未授权
+
+**原因**：密钥不匹配
+
+**解决方案**：
+1. 密钥已写死，无需配置 `CRON_SECRET`
+2. 确认宝塔任务 URL 中的 `secret` 参数
+3. 确保两者完全一致
+4. 重启项目：`pm2 restart soul`
+
+### Q3: 返回 500 错误
+
+**可能原因**：
+1. 数据库连接失败
+2. 代码有 bug
+
+**解决方案**：
+1. 查看应用日志：`pm2 logs soul`
+2. 检查数据库是否正常
+3. 检查环境变量是否配置
+
+### Q4: 看不到执行日志
+
+**解决方案**：
+1. 宝塔面板 → 计划任务 → 点击任务右侧的"日志"
+2. 或查看自定义日志文件：
+   ```bash
+   tail -f /www/wwwlogs/cron_sync_orders.log
+   ```
+
+---
+
+## 十、监控与优化
+
+### 设置告警（可选）
+
+宝塔面板 → 监控 → 进程守护，添加监控项：
+- 监控类型：URL 监控
+- URL：`https://soul.quwanzhi.com/api/cron/sync-orders?secret=YOUR_SECRET`
+- 监控周期：5 分钟
+- 告警方式：邮件/企业微信
+
+### 调整执行频率
+
+根据实际情况调整：
+- **订单少**：10 分钟 / 15 分钟
+- **订单多**：3 分钟 / 5 分钟
+- **高峰期**：1 分钟（不推荐，增加服务器负载）
+
+---
+
+## 十一、配置清单（Checklist）
+
+完成以下步骤，确保定时任务正常运行：
+
+- [ ] 宝塔面板添加计划任务（访问 URL，密钥已写死：soul_cron_sync_orders_2026）
+- [ ] 配置 `.env.production` 中的 `WECHAT_API_KEY`（可选，用于查询微信订单状态）
+- [ ] 重启项目：`pm2 restart soul`
+- [ ] 手动执行测试（宝塔面板点击"执行"）
+- [ ] 验证响应正常（`{"success":true}`）
+- [ ] 查看日志确认任务执行
+- [ ] 创建测试订单验证（可选）
+- [ ] 清理测试数据（可选）
+
+---
+
+## 十二、最终配置示例
+
+### 宝塔计划任务配置
+
+```
+任务名称: 订单状态同步
+任务类型: 访问URL
+执行周期: N分钟 -> 5
+URL地址: https://soul.quwanzhi.com/api/cron/sync-orders?secret=soul_cron_sync_orders_2026
+```
+
+### 项目环境变量 `.env.production`（可选）
+
+密钥已写死，无需配置 `CRON_SECRET`。若需微信支付查询订单状态，可配置：
+
+```bash
+# 微信支付 API 密钥（从商户平台获取，用于同步时查询订单真实状态）
+WECHAT_API_KEY=YOUR_32_CHAR_API_KEY_HERE
+
+# 其他环境变量...
+DATABASE_URL=mysql://...
+```
+
+---
+
+## 完成！
+
+配置完成后，系统会：
+- ✅ 每 5 分钟自动检查未支付订单
+- ✅ 查询微信支付状态并同步
+- ✅ 超时订单自动标记为 expired
+- ✅ 支付成功订单自动解锁内容
+
+再也不用担心支付回调丢失导致用户无法解锁内容了！🎉
diff --git a/开发文档/8、部署/支付接口清单.md b/开发文档/8、部署/支付接口清单.md
new file mode 100644
index 00000000..a49505a1
--- /dev/null
+++ b/开发文档/8、部署/支付接口清单.md
@@ -0,0 +1,366 @@
+# 支付相关接口清单
+
+**日期**: 2026-02-04  
+**说明**: 所有支付相关后端API接口的完整清单
+
+---
+
+## ✅ 已创建的接口
+
+### 1. 小程序支付接口
+
+#### `/api/miniprogram/pay` (POST)
+**功能**: 创建支付订单并调用微信支付
+
+**文件**: `app/api/miniprogram/pay/route.ts`
+
+**请求参数**:
+```json
+{
+  "openId": "oXXXX...",
+  "productType": "section",  // 'section' | 'fullbook'
+  "productId": "1-1",
+  "amount": 9.9,
+  "description": "章节1-1",
+  "userId": "user_xxx"
+}
+```
+
+**返回**:
+```json
+{
+  "success": true,
+  "data": {
+    "orderSn": "MP20260204123456789012",
+    "prepayId": "wx...",
+    "payParams": {
+      "timeStamp": "...",
+      "nonceStr": "...",
+      "package": "prepay_id=...",
+      "signType": "MD5",
+      "paySign": "..."
+    }
+  }
+}
+```
+
+**关键逻辑**:
+- ✅ 插入订单到 `orders` 表 (status='created')
+- ✅ 检查是否已有该产品的已支付订单
+- ✅ 调用微信统一下单接口
+- ✅ 返回支付参数
+
+---
+
+#### `/api/miniprogram/pay/notify` (POST)
+**功能**: 接收微信支付回调通知
+
+**文件**: `app/api/miniprogram/pay/notify/route.ts`
+
+**请求**: 微信发送XML格式数据
+
+**返回**: XML格式响应
+
+**关键逻辑**:
+1. ✅ 验证签名
+2. ✅ 更新订单状态为 `paid`（或补记订单）
+3. ✅ 解锁用户权限
+4. ✅ 分配推荐佣金（90%）
+5. ✅ **清理相同产品的其他未支付订单**
+
+---
+
+### 2. 用户购买状态接口
+
+#### `/api/user/purchase-status` (GET)
+**功能**: 查询用户的购买状态
+
+**文件**: `app/api/user/purchase-status/route.ts`
+
+**请求**:
+```
+GET /api/user/purchase-status?userId=user_xxx
+```
+
+**返回**:
+```json
+{
+  "success": true,
+  "data": {
+    "hasFullBook": false,
+    "purchasedSections": ["1-1", "1-2"],
+    "purchasedCount": 2,
+    "earnings": 0,
+    "pendingEarnings": 0
+  }
+}
+```
+
+**查询逻辑**:
+```sql
+-- 1. 查询全书权限
+SELECT has_full_book FROM users WHERE id = ?
+
+-- 2. 查询已购章节（基于 orders 表）
+SELECT DISTINCT product_id 
+FROM orders 
+WHERE user_id = ? 
+  AND status = 'paid' 
+  AND product_type = 'section'
+```
+
+---
+
+#### `/api/user/check-purchased` (GET)
+**功能**: 检查用户是否已购买指定产品
+
+**文件**: `app/api/user/check-purchased/route.ts`
+
+**请求**:
+```
+GET /api/user/check-purchased?userId=user_xxx&type=section&productId=1-1
+```
+
+**返回**:
+```json
+{
+  "success": true,
+  "data": {
+    "isPurchased": true,
+    "reason": "section_order_exists"
+  }
+}
+```
+
+**可能的 reason 值**:
+- `has_full_book`: 用户已购买全书
+- `fullbook_order_exists`: 有全书的已支付订单
+- `section_order_exists`: 有该章节的已支付订单
+- `null`: 未购买
+
+**查询逻辑**:
+```sql
+-- 1. 检查全书权限
+SELECT has_full_book FROM users WHERE id = ?
+
+-- 2. 检查是否有该产品的已支付订单
+SELECT COUNT(*) as count
+FROM orders 
+WHERE user_id = ? 
+  AND product_type = ? 
+  AND product_id = ?
+  AND status = 'paid'
+```
+
+---
+
+### 3. 通用支付接口（未使用）
+
+#### `/api/payment/create-order` (POST)
+**功能**: 通用支付订单创建接口
+
+**文件**: `app/api/payment/create-order/route.ts`
+
+**说明**: 
+- ⚠️ 小程序实际使用的是 `/api/miniprogram/pay`
+- 这个接口是为 Web 端设计的通用支付接口
+- 支持多种支付方式（微信、支付宝、USDT）
+
+---
+
+#### `/api/payment/wechat/notify` (POST)
+**功能**: 通用微信支付回调
+
+**文件**: `app/api/payment/wechat/notify/route.ts`
+
+**说明**: 
+- ⚠️ 小程序实际使用的是 `/api/miniprogram/pay/notify`
+- 这个接口是为 Web 端设计的
+
+---
+
+## 📊 接口调用流程
+
+```
+【小程序支付流程】
+
+1. 用户点击购买
+   ↓
+2. 前端调用 /api/user/purchase-status
+   (查询是否已购买)
+   ↓
+3. 如果未购买，前端调用 /api/miniprogram/pay
+   (创建订单 + 获取支付参数)
+   ↓
+4. 小程序调起微信支付
+   ↓
+5. 用户完成支付
+   ↓
+6. 微信回调 /api/miniprogram/pay/notify
+   (更新订单 + 解锁权限 + 分配佣金 + 清理无效订单)
+   ↓
+7. 前端支付成功后调用 /api/user/purchase-status
+   (刷新用户购买状态)
+```
+
+---
+
+## 🔧 测试命令
+
+### 1. 测试查询购买状态
+
+```bash
+curl "http://localhost:30006/api/user/purchase-status?userId=user_xxx"
+```
+
+**预期结果**:
+```json
+{
+  "success": true,
+  "data": {
+    "hasFullBook": false,
+    "purchasedSections": [],
+    "purchasedCount": 0,
+    "earnings": 0,
+    "pendingEarnings": 0
+  }
+}
+```
+
+---
+
+### 2. 测试检查是否已购买
+
+```bash
+curl "http://localhost:30006/api/user/check-purchased?userId=user_xxx&type=section&productId=1-1"
+```
+
+**预期结果**:
+```json
+{
+  "success": true,
+  "data": {
+    "isPurchased": false,
+    "reason": null
+  }
+}
+```
+
+---
+
+### 3. 测试创建支付订单
+
+```bash
+curl -X POST http://localhost:30006/api/miniprogram/pay \
+  -H "Content-Type: application/json" \
+  -d '{
+    "openId": "oXXXX...",
+    "productType": "section",
+    "productId": "1-1",
+    "amount": 9.9,
+    "description": "测试章节",
+    "userId": "user_xxx"
+  }'
+```
+
+**预期结果**: 返回支付参数
+
+---
+
+## ⚠️ 常见错误
+
+### 1. "缺少 userId 参数"
+
+**原因**: 请求参数中未传递 userId
+
+**解决**: 确保 URL 参数或请求体中包含 userId
+
+---
+
+### 2. "用户不存在"
+
+**原因**: 数据库中找不到对应的用户记录
+
+**解决**: 
+1. 检查 userId 是否正确
+2. 确认用户已登录并创建了账号
+3. 查询数据库: `SELECT * FROM users WHERE id = 'user_xxx'`
+
+---
+
+### 3. "订单创建失败"
+
+**原因**: 
+- 数据库连接失败
+- 缺少必要字段
+- openId 格式错误
+
+**解决**: 
+1. 检查服务器日志
+2. 确认数据库连接正常
+3. 验证请求参数完整性
+
+---
+
+### 4. 接口404
+
+**原因**: 
+- Next.js 服务器未重启
+- 文件路径错误
+
+**解决**: 
+1. 重启 Next.js 服务器: `npm run dev`
+2. 检查文件是否存在于正确路径
+3. 清除 `.next` 缓存后重启
+
+---
+
+## 📝 数据库表结构
+
+### orders 表
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| `id` | VARCHAR | 订单ID（同 order_sn） |
+| `order_sn` | VARCHAR | 订单号 |
+| `user_id` | VARCHAR | 用户ID |
+| `open_id` | VARCHAR | 微信openId |
+| `product_type` | VARCHAR | 产品类型 (section/fullbook) |
+| `product_id` | VARCHAR | 产品ID |
+| `amount` | DECIMAL | 金额（元） |
+| `description` | TEXT | 订单描述 |
+| `status` | VARCHAR | 状态 (created/paid/expired) |
+| `transaction_id` | VARCHAR | 微信交易号 |
+| `pay_time` | DATETIME | 支付时间 |
+| `created_at` | DATETIME | 创建时间 |
+| `updated_at` | DATETIME | 更新时间 |
+
+---
+
+### users 表（购买相关字段）
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| `has_full_book` | BOOLEAN | 是否购买全书 |
+| `purchased_sections` | JSON | 已购章节列表 |
+| `earnings` | DECIMAL | 已结算收益 |
+| `pending_earnings` | DECIMAL | 待结算收益 |
+
+---
+
+## 🎉 接口状态总结
+
+| 接口 | 状态 | 用途 |
+|-----|------|------|
+| `/api/miniprogram/pay` | ✅ 已实现 | 创建支付订单 |
+| `/api/miniprogram/pay/notify` | ✅ 已实现 | 支付回调 |
+| `/api/user/purchase-status` | ✅ 已实现 | 查询购买状态 |
+| `/api/user/check-purchased` | ✅ 已实现 | 检查是否已购买 |
+| `/api/payment/create-order` | ⚠️ 未使用 | Web 端通用接口 |
+| `/api/payment/wechat/notify` | ⚠️ 未使用 | Web 端回调接口 |
+
+---
+
+**所有小程序支付相关接口已完成！** 🎉
+
+**重启 Next.js 服务器后生效**: `npm run dev`
diff --git a/开发文档/8、部署/新分销逻辑-宝塔操作清单.md b/开发文档/8、部署/新分销逻辑-宝塔操作清单.md
new file mode 100644
index 00000000..d3209e22
--- /dev/null
+++ b/开发文档/8、部署/新分销逻辑-宝塔操作清单.md
@@ -0,0 +1,299 @@
+# 新分销逻辑 - 宝塔面板操作清单
+
+## ✅ 已完成的准备工作
+
+- ✅ 数据库字段已添加（last_purchase_date, purchase_count, total_commission）
+- ✅ 代码已部署到服务器（/www/wwwroot/soul/dist）
+- ✅ 索引已创建
+
+---
+
+## 🔧 宝塔面板操作步骤
+
+### Step 1: 重启 Node.js 服务
+
+1. 登录宝塔面板：`http://你的服务器IP:8888`
+2. 左侧菜单 → **网站** → 找到 `soul.quwanzhi.com`
+3. 点击 **设置** → **Node项目** 标签
+4. 找到项目 `soul`
+5. 点击 **重启** 按钮
+6. 等待状态变为"运行中"
+
+**或者使用命令行**（如果有SSH权限）：
+```bash
+# 使用宝塔的pm2完整路径
+/www/server/nodejs/v16.20.2/bin/pm2 restart soul
+
+# 查看状态
+/www/server/nodejs/v16.20.2/bin/pm2 status
+
+# 查看日志
+/www/server/nodejs/v16.20.2/bin/pm2 logs soul --lines 50
+```
+
+---
+
+### Step 2: 验证服务是否正常
+
+#### 2.1 检查网站访问
+在浏览器打开：`https://soul.quwanzhi.com`
+
+**预期**：
+- ✅ 网站正常加载
+- ✅ 无404错误
+- ✅ 可以正常登录
+
+#### 2.2 检查新API是否生效
+
+打开浏览器控制台，访问：
+```
+https://soul.quwanzhi.com/api/db/config?key=referral_config
+```
+
+**预期返回**：
+```json
+{
+  "success": true,
+  "config": {
+    "distributorShare": 90,
+    "minWithdrawAmount": 10,
+    "bindingDays": 30,
+    "userDiscount": 5,
+    "enableAutoWithdraw": false
+  }
+}
+```
+
+#### 2.3 检查推广设置页面
+
+访问：`https://soul.quwanzhi.com/admin/referral-settings`
+
+**预期**：
+- ✅ 页面正常加载
+- ✅ 显示当前配置
+- ✅ 可以修改并保存
+
+---
+
+### Step 3: 配置自动解绑定时任务
+
+1. 宝塔面板 → 左侧菜单 → **计划任务**
+2. 点击 **添加计划任务**
+3. 填写以下信息：
+
+**任务配置**：
+```
+任务类型：Shell脚本
+任务名称：自动解绑过期推荐关系
+执行周期：每天 02:00（凌晨2点）
+脚本内容：
+cd /www/wwwroot/soul/dist && /www/server/nodejs/v16.20.2/bin/node scripts/auto-unbind-expired-simple.js >> /www/wwwroot/soul/logs/auto-unbind.log 2>&1
+```
+
+4. 点击 **添加**
+5. 任务创建后，点击 **执行** 按钮测试一次
+
+**预期日志**（如果没有过期记录）：
+```
+============================================================
+自动解绑定时任务
+执行时间: 2026/2/5 14:30:00
+============================================================
+✅ 已连接到数据库: soul_miniprogram
+✅ 无需解绑的记录
+============================================================
+任务完成
+============================================================
+```
+
+---
+
+### Step 4: 查看定时任务日志
+
+```bash
+# 方式1：SSH命令
+cat /www/wwwroot/soul/logs/auto-unbind.log
+
+# 方式2：宝塔面板
+计划任务 → 找到"自动解绑"任务 → 点击"日志"
+```
+
+---
+
+## 🧪 功能测试（小程序端）
+
+### 测试1：立即切换绑定
+
+1. **准备两个测试账号**：
+   - 账号A：作为推荐人A（获取推荐码 SOULA001）
+   - 账号C：作为推荐人C（获取推荐码 SOULC001）
+   - 账号B：作为购买者
+
+2. **测试步骤**：
+   ```
+   Step 1: A 分享文章链接给 B
+   Step 2: B 点击链接进入小程序（会自动绑定A）
+   Step 3: 查数据库验证绑定
+   Step 4: C 分享文章链接给 B
+   Step 5: B 点击C的链接（应该立即切换）
+   Step 6: 再次查数据库验证
+   ```
+
+3. **数据库验证SQL**：
+   ```sql
+   -- 查看B当前的绑定状态
+   SELECT 
+     referee_id, 
+     referrer_id, 
+     status, 
+     binding_date, 
+     expiry_date
+   FROM referral_bindings
+   WHERE referee_id = 'B的用户ID'
+   ORDER BY binding_date DESC;
+   ```
+
+   **预期结果**：
+   - 最新一条：`referrer_id = C的ID, status = active`
+   - 上一条：`referrer_id = A的ID, status = cancelled`
+
+---
+
+### 测试2：购买分佣
+
+1. **B 购买一篇文章（1元）**
+2. **查看分佣结果**：
+   ```sql
+   SELECT 
+     rb.referrer_id,
+     rb.purchase_count,
+     rb.total_commission,
+     rb.last_purchase_date,
+     u.pending_earnings
+   FROM referral_bindings rb
+   JOIN users u ON rb.referrer_id = u.id
+   WHERE rb.referee_id = 'B的用户ID' AND rb.status = 'active';
+   ```
+
+   **预期结果**（假设90%分成）：
+   ```
+   referrer_id: C的ID
+   purchase_count: 1
+   total_commission: 0.90
+   pending_earnings: 0.90
+   ```
+
+3. **B 再次购买**：
+   ```sql
+   -- 查询应显示
+   purchase_count: 2
+   total_commission: 1.80
+   pending_earnings: 1.80
+   ```
+
+---
+
+### 测试3：好友优惠（新功能）
+
+1. **后台设置好友优惠为 10%**
+   - 访问：`https://soul.quwanzhi.com/admin/referral-settings`
+   - 修改"好友优惠"为 `10`
+   - 保存
+
+2. **B 通过推荐链接购买**
+   - 原价 1.00 元的文章
+   - 支付时应显示 **0.90 元**（10% off）
+
+3. **验证佣金计算**：
+   - C 应获得佣金 = 0.90 × 90% = **0.81 元**
+   - 而不是 1.00 × 90% = 0.90 元
+
+---
+
+## 📊 后台监控
+
+### 查看绑定切换记录
+
+**SQL查询**：
+```sql
+-- 查看最近的绑定切换
+SELECT 
+  rb.referee_id,
+  rb.referrer_id,
+  rb.status,
+  rb.binding_date,
+  rb.purchase_count,
+  rb.total_commission
+FROM referral_bindings rb
+WHERE rb.status IN ('active', 'cancelled')
+ORDER BY rb.binding_date DESC
+LIMIT 20;
+```
+
+### 查看即将过期的绑定
+
+```sql
+-- 7天内即将过期且无购买的绑定
+SELECT 
+  rb.referee_id,
+  rb.referrer_id,
+  rb.binding_date,
+  rb.expiry_date,
+  DATEDIFF(rb.expiry_date, NOW()) as days_left,
+  rb.purchase_count
+FROM referral_bindings rb
+WHERE rb.status = 'active'
+  AND rb.expiry_date > NOW()
+  AND DATEDIFF(rb.expiry_date, NOW()) <= 7
+  AND rb.purchase_count = 0
+ORDER BY days_left ASC;
+```
+
+---
+
+## ⚠️ 常见问题
+
+### Q1: 点击新链接后没有切换？
+**检查**：
+- 宝塔面板 → Node项目 → 查看日志
+- 搜索 `[Referral Bind]` 关键词
+- 确认是否有报错
+
+### Q2: 购买后 purchase_count 还是 0？
+**检查**：
+- 查看支付回调日志：`pm2 logs soul | grep PayNotify`
+- 确认字段 `purchase_count` 是否存在
+- 执行SQL验证：`SHOW COLUMNS FROM referral_bindings;`
+
+### Q3: 定时任务没有执行？
+**检查**：
+- 宝塔面板 → 计划任务 → 找到任务 → 点击"执行"测试
+- 查看日志：`cat /www/wwwroot/soul/logs/auto-unbind.log`
+- 确认脚本路径正确：`ls -la /www/wwwroot/soul/dist/scripts/auto-unbind-expired-simple.js`
+
+---
+
+## 📝 部署后清理
+
+部署成功后，删除临时文件：
+
+```bash
+# 本地清理
+rm .env.migration
+```
+
+---
+
+## ✅ 完成检查清单
+
+- [ ] 数据库字段已添加
+- [ ] 代码已部署
+- [ ] PM2服务运行正常
+- [ ] 网站可以访问
+- [ ] 推广设置页面正常
+- [ ] 定时任务已配置
+- [ ] 功能测试通过
+
+---
+
+**下一步：执行上述测试验证，或告诉我遇到的任何问题！**
diff --git a/开发文档/8、部署/新分销逻辑-部署步骤.md b/开发文档/8、部署/新分销逻辑-部署步骤.md
new file mode 100644
index 00000000..9f65bfc9
--- /dev/null
+++ b/开发文档/8、部署/新分销逻辑-部署步骤.md
@@ -0,0 +1,537 @@
+# 新分销逻辑 - 部署步骤
+
+## 📋 部署前检查
+
+### 确认新逻辑
+- ✅ 点击谁的链接，立即绑定谁（无条件切换）
+- ✅ 购买时，佣金给当前推荐人
+- ✅ 30天内无购买 → 自动解绑
+- ✅ 方案A：购买后不重置30天
+
+### 备份数据
+```bash
+# 1. 备份数据库
+mysqldump -u root -p mycontent_db > backup_before_referral_$(date +%Y%m%d).sql
+
+# 2. 备份代码
+cd /www/wwwroot/soul
+tar -czf backup_code_$(date +%Y%m%d).tar.gz app/ lib/ scripts/
+```
+
+---
+
+## 🚀 部署步骤
+
+### Step 1: 数据库迁移
+
+#### 方式1：使用 Python 脚本（推荐）
+
+```bash
+# 1. 上传脚本到服务器
+cd /www/wwwroot/soul
+# 将 scripts/migrate_binding_fields.py 上传到服务器
+
+# 2. 确保环境变量正确（.env 文件）
+cat .env | grep DB_
+
+# 3. 执行迁移
+python3 scripts/migrate_binding_fields.py
+```
+
+**预期输出**：
+```
+==========================================================
+数据库迁移：referral_bindings 表字段升级
+==========================================================
+
+✅ 已连接到数据库: mycontent_db
+
+步骤 1: 添加新字段
+------------------------------------------------------------
+✅ 添加字段 last_purchase_date
+✅ 添加字段 purchase_count
+✅ 添加字段 total_commission
+
+步骤 2: 添加索引
+------------------------------------------------------------
+✅ 添加索引 idx_referee_status
+✅ 添加索引 idx_expiry_purchase
+
+步骤 3: 更新 status 枚举（添加 cancelled）
+------------------------------------------------------------
+✅ 更新 status 枚举类型
+
+步骤 4: 验证迁移结果
+------------------------------------------------------------
+✅ 字段 last_purchase_date 已存在
+✅ 字段 purchase_count 已存在
+✅ 字段 total_commission 已存在
+
+==========================================================
+✅ 迁移完成！
+==========================================================
+```
+
+#### 方式2：直接执行 SQL
+
+```bash
+# 连接数据库
+mysql -u root -p mycontent_db
+
+# 执行迁移SQL
+source scripts/migration-add-binding-fields.sql;
+
+# 验证字段
+SHOW COLUMNS FROM referral_bindings;
+```
+
+---
+
+### Step 2: 部署代码
+
+#### 本地构建
+```bash
+# 在本地项目目录
+cd e:\Gongsi\Mycontent
+
+# 构建
+pnpm build
+
+# 确认构建产物
+ls -la .next/standalone
+```
+
+#### 上传到服务器
+```bash
+# 使用 devlop.py（自动化部署）
+python devlop.py
+
+# 或手动上传
+# 1. 上传修改的文件：
+#    - app/api/referral/bind/route.ts
+#    - app/api/miniprogram/pay/notify/route.ts
+#    - scripts/auto-unbind-expired-simple.js
+```
+
+---
+
+### Step 3: 重启服务
+
+```bash
+# 重启 PM2
+pm2 restart soul
+
+# 查看日志确认启动正常
+pm2 logs soul --lines 50
+
+# 确认进程状态
+pm2 status
+```
+
+**预期输出**：
+```
+┌─────┬────────┬─────────┬──────┬─────┬──────────┐
+│ id  │ name   │ status  │ ↺    │ cpu │ memory   │
+├─────┼────────┼─────────┼──────┼─────┼──────────┤
+│ 0   │ soul   │ online  │ 0    │ 0%  │ 100.0mb  │
+└─────┴────────┴─────────┴──────┴─────┴──────────┘
+```
+
+---
+
+### Step 4: 配置定时任务
+
+#### 宝塔面板配置
+
+1. 登录宝塔面板
+2. 进入"计划任务"
+3. 添加 Shell 脚本任务
+
+**任务配置**：
+- **任务名称**：自动解绑过期推荐关系
+- **执行周期**：每天 02:00
+- **脚本内容**：
+  ```bash
+  cd /www/wwwroot/soul && node scripts/auto-unbind-expired-simple.js >> /www/wwwroot/soul/logs/auto-unbind.log 2>&1
+  ```
+
+#### 手动测试定时任务
+
+```bash
+# 进入项目目录
+cd /www/wwwroot/soul
+
+# 创建日志目录
+mkdir -p logs
+
+# 手动执行一次
+node scripts/auto-unbind-expired-simple.js
+
+# 查看日志
+cat logs/auto-unbind.log
+```
+
+**预期输出**（如果有过期记录）：
+```
+============================================================
+自动解绑定时任务
+执行时间: 2026/2/5 02:00:00
+============================================================
+
+✅ 已连接到数据库: mycontent_db
+
+步骤 1: 查询需要解绑的记录...
+------------------------------------------------------------
+找到 3 条需要解绑的记录
+
+步骤 2: 解绑明细
+------------------------------------------------------------
+1. 用户 user_abc123
+   推荐人: user_xyz789
+   绑定时间: 2026/1/5
+   过期时间: 2026/2/4 (已过期 1 天)
+   购买次数: 0
+   累计佣金: ¥0.00
+
+...
+
+步骤 3: 执行解绑操作...
+------------------------------------------------------------
+✅ 已成功解绑 3 条记录
+
+步骤 4: 更新推荐人统计...
+------------------------------------------------------------
+  - user_xyz789: -2 个绑定
+  - user_def456: -1 个绑定
+✅ 已更新 2 个推荐人的统计数据
+
+============================================================
+✅ 任务完成
+   - 解绑记录数: 3
+   - 受影响推荐人: 2
+============================================================
+```
+
+---
+
+## 🧪 功能测试
+
+### 测试用例1：立即切换绑定
+
+#### 准备工作
+```bash
+# 创建测试用户 A、B、C
+# A 推荐 B
+# C 也想抢 B
+```
+
+#### 测试步骤
+```bash
+# 1. A 推荐 B（新绑定）
+curl -X POST http://localhost:3006/api/referral/bind \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userId": "test_user_b",
+    "referralCode": "SOULA001",
+    "source": "miniprogram"
+  }'
+
+# 预期返回：
+# {
+#   "success": true,
+#   "message": "绑定成功",
+#   "action": "new",
+#   "expiryDate": "2026-03-07T...",
+#   "referrer": { "id": "test_user_a", "nickname": "用户A" }
+# }
+
+# 2. B 点击 C 的链接（立即切换）
+curl -X POST http://localhost:3006/api/referral/bind \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userId": "test_user_b",
+    "referralCode": "SOULC001",
+    "source": "miniprogram"
+  }'
+
+# 预期返回：
+# {
+#   "success": true,
+#   "message": "已切换推荐人",
+#   "action": "switch",
+#   "expiryDate": "2026-03-07T...",
+#   "referrer": { "id": "test_user_c", "nickname": "用户C" },
+#   "oldReferrerId": "test_user_a"
+# }
+
+# 3. 验证数据库
+mysql -u root -p mycontent_db -e "
+  SELECT referee_id, referrer_id, status, binding_date, expiry_date 
+  FROM referral_bindings 
+  WHERE referee_id = 'test_user_b' 
+  ORDER BY binding_date DESC LIMIT 2;
+"
+
+# 预期结果：
+# 记录1: referee=B, referrer=C, status=active (最新)
+# 记录2: referee=B, referrer=A, status=cancelled (旧)
+```
+
+---
+
+### 测试用例2：购买分佣（累加）
+
+#### 测试步骤
+```bash
+# 1. B 购买第1次（1元）
+# 触发支付回调 -> /api/miniprogram/pay/notify
+
+# 2. 查询分佣结果
+mysql -u root -p mycontent_db -e "
+  SELECT 
+    rb.referrer_id,
+    rb.purchase_count,
+    rb.total_commission,
+    u.pending_earnings
+  FROM referral_bindings rb
+  JOIN users u ON rb.referrer_id = u.id
+  WHERE rb.referee_id = 'test_user_b' AND rb.status = 'active';
+"
+
+# 预期结果：
+# referrer_id: test_user_c
+# purchase_count: 1
+# total_commission: 0.90 (假设90%分成)
+# pending_earnings: 0.90
+
+# 3. B 购买第2次（1元）
+# 再次触发支付回调
+
+# 4. 再次查询
+# 预期结果：
+# purchase_count: 2
+# total_commission: 1.80
+# pending_earnings: 1.80
+```
+
+---
+
+### 测试用例3：30天自动解绑
+
+#### 模拟测试（修改过期时间）
+```bash
+# 1. 手动修改绑定的过期时间（测试用）
+mysql -u root -p mycontent_db -e "
+  UPDATE referral_bindings 
+  SET expiry_date = '2026-02-04 00:00:00' 
+  WHERE referee_id = 'test_user_x' AND referrer_id = 'test_user_y';
+"
+
+# 2. 执行定时任务
+node scripts/auto-unbind-expired-simple.js
+
+# 3. 验证解绑
+mysql -u root -p mycontent_db -e "
+  SELECT referee_id, referrer_id, status, expiry_date, purchase_count
+  FROM referral_bindings 
+  WHERE referee_id = 'test_user_x';
+"
+
+# 预期结果：
+# status: expired（如果 purchase_count = 0）
+# status: active（如果 purchase_count > 0）
+```
+
+---
+
+## 🔍 监控与日志
+
+### 查看绑定切换日志
+```bash
+# PM2 日志
+pm2 logs soul | grep "Referral Bind"
+
+# 查找"立即切换"记录
+pm2 logs soul | grep "立即切换"
+```
+
+### 查看分佣日志
+```bash
+# 查看分佣成功记录
+pm2 logs soul | grep "分佣完成"
+
+# 查看累加情况
+pm2 logs soul | grep "purchaseCount"
+```
+
+### 定时任务日志
+```bash
+# 查看定时任务执行记录
+cat /www/wwwroot/soul/logs/auto-unbind.log
+
+# 实时监控
+tail -f /www/wwwroot/soul/logs/auto-unbind.log
+```
+
+---
+
+## 📊 数据统计
+
+### 查看当前绑定状态分布
+```sql
+SELECT 
+  status,
+  COUNT(*) as count,
+  SUM(purchase_count) as total_purchases,
+  SUM(total_commission) as total_commission
+FROM referral_bindings
+GROUP BY status;
+```
+
+### 查看切换频率最高的用户
+```sql
+SELECT 
+  referee_id,
+  COUNT(*) as binding_count,
+  GROUP_CONCAT(referrer_id ORDER BY binding_date DESC) as referrer_history
+FROM referral_bindings
+WHERE status IN ('active', 'cancelled')
+GROUP BY referee_id
+HAVING COUNT(*) > 1
+ORDER BY binding_count DESC
+LIMIT 10;
+```
+
+### 查看30天内即将过期的绑定
+```sql
+SELECT 
+  referee_id,
+  referrer_id,
+  binding_date,
+  expiry_date,
+  DATEDIFF(expiry_date, NOW()) as days_left,
+  purchase_count
+FROM referral_bindings
+WHERE status = 'active'
+  AND expiry_date > NOW()
+  AND DATEDIFF(expiry_date, NOW()) <= 7
+ORDER BY days_left ASC;
+```
+
+---
+
+## ⚠️ 回滚方案
+
+### 如果需要回滚到旧逻辑
+
+#### 1. 恢复数据库
+```bash
+# 停止服务
+pm2 stop soul
+
+# 恢复备份
+mysql -u root -p mycontent_db < backup_before_referral_20260205.sql
+
+# 重启服务
+pm2 start soul
+```
+
+#### 2. 恢复代码
+```bash
+# 方式1：Git回滚
+cd /www/wwwroot/soul
+git reset --hard <上一个commit>
+
+# 方式2：恢复备份
+tar -xzf backup_code_20260205.tar.gz
+
+# 重启
+pm2 restart soul
+```
+
+#### 3. 停用定时任务
+```bash
+# 宝塔面板 -> 计划任务 -> 停用或删除"自动解绑"任务
+```
+
+---
+
+## 📝 常见问题
+
+### Q1: 定时任务没有执行？
+**检查步骤**：
+1. 确认宝塔计划任务状态为"启用"
+2. 查看宝塔计划任务日志
+3. 手动执行测试：`node scripts/auto-unbind-expired-simple.js`
+4. 检查脚本权限：`chmod +x scripts/auto-unbind-expired-simple.js`
+
+### Q2: 绑定切换后，旧推荐人还能收到佣金？
+**原因**：可能是购买时的绑定查询逻辑有问题
+
+**检查**：
+```sql
+-- 查看 B 当前的绑定
+SELECT * FROM referral_bindings 
+WHERE referee_id = 'test_user_b' AND status = 'active';
+
+-- 应该只有1条 active 记录（最新的推荐人）
+```
+
+### Q3: purchase_count 字段不存在？
+**原因**：数据库迁移未成功
+
+**解决**：
+```bash
+# 重新执行迁移
+python3 scripts/migrate_binding_fields.py
+
+# 或手动添加
+mysql -u root -p mycontent_db -e "
+  ALTER TABLE referral_bindings 
+  ADD COLUMN purchase_count INT DEFAULT 0;
+"
+```
+
+### Q4: 如何验证新逻辑是否生效？
+**验证清单**：
+- [ ] 数据库有 `last_purchase_date`、`purchase_count`、`total_commission` 字段
+- [ ] 点击不同推荐链接会立即切换（无报错）
+- [ ] 购买后 `purchase_count` 会累加
+- [ ] 定时任务能正常执行
+
+---
+
+## ✅ 部署完成检查表
+
+- [ ] 数据库迁移成功
+- [ ] 代码部署完成
+- [ ] PM2 服务正常运行
+- [ ] 定时任务已配置
+- [ ] 测试用例1通过（立即切换）
+- [ ] 测试用例2通过（购买累加）
+- [ ] 日志正常输出
+- [ ] 备份文件已保存
+
+---
+
+## 📞 问题反馈
+
+如有问题，请提供：
+1. 错误日志（PM2日志或定时任务日志）
+2. 数据库状态（相关表的查询结果）
+3. 复现步骤
+
+**日志收集命令**：
+```bash
+# PM2日志
+pm2 logs soul --lines 100 > soul_logs.txt
+
+# 定时任务日志
+cat /www/wwwroot/soul/logs/auto-unbind.log > auto_unbind.log
+
+# 数据库状态
+mysql -u root -p mycontent_db -e "
+  SELECT * FROM referral_bindings LIMIT 10;
+  SHOW COLUMNS FROM referral_bindings;
+" > db_status.txt
+```
diff --git a/开发文档/8、部署/新分销逻辑设计方案.md b/开发文档/8、部署/新分销逻辑设计方案.md
new file mode 100644
index 00000000..ab546e3d
--- /dev/null
+++ b/开发文档/8、部署/新分销逻辑设计方案.md
@@ -0,0 +1,408 @@
+# 新分销逻辑设计方案
+
+## 📌 业务需求
+
+### 核心规则
+1. **动态绑定**：用户B点击谁的分享链接，立即绑定谁（无条件切换）
+2. **佣金归属**：B购买时，佣金给当前推荐人（最新绑定的那个人）
+3. **自动解绑**：绑定30天内，如果B既没点击其他链接，也没有任何购买 → 自动解绑
+
+### 场景示例
+```
+时间线：
+Day 0:  A推荐B → B注册 → B绑定A（30天有效期）
+Day 5:  B点击C的链接 → B立即切换绑定C（重新开始30天有效期）
+Day 10: B购买文章 → 佣金给C（当前推荐人）
+Day 35: 绑定C的30天到期，如果期间无购买 → 自动解绑
+```
+
+---
+
+## 🗄️ 数据库设计
+
+### 1. `referral_bindings` 表字段调整
+
+| 字段 | 类型 | 说明 | 新增/修改 |
+|------|------|------|-----------|
+| `id` | VARCHAR(64) | 主键 | - |
+| `referee_id` | VARCHAR(64) | 被推荐人（B） | - |
+| `referrer_id` | VARCHAR(64) | 推荐人（当前） | - |
+| `referral_code` | VARCHAR(20) | 推荐码 | - |
+| `status` | ENUM | active/converted/expired/cancelled | **新增 cancelled** |
+| `binding_date` | TIMESTAMP | 最后一次绑定时间 | - |
+| `expiry_date` | DATETIME | 过期时间（30天后） | - |
+| `last_purchase_date` | DATETIME | 最后一次购买时间 | **新增** |
+| `purchase_count` | INT | 购买次数 | **新增** |
+| `total_commission` | DECIMAL | 累计佣金 | **新增** |
+
+### 2. 新增字段的 SQL
+
+```sql
+-- 添加新字段
+ALTER TABLE referral_bindings 
+ADD COLUMN last_purchase_date DATETIME NULL COMMENT '最后一次购买时间',
+ADD COLUMN purchase_count INT DEFAULT 0 COMMENT '购买次数',
+ADD COLUMN total_commission DECIMAL(10,2) DEFAULT 0.00 COMMENT '累计佣金',
+ADD INDEX idx_expiry_status (expiry_date, status);
+
+-- 修改 status 枚举（如果需要）
+ALTER TABLE referral_bindings 
+MODIFY COLUMN status ENUM('active', 'converted', 'expired', 'cancelled') DEFAULT 'active';
+```
+
+---
+
+## 🔧 API 逻辑修改
+
+### 1. `/api/referral/bind` - 立即切换绑定
+
+**修改前逻辑（现有）：**
+```javascript
+if (existingBinding && expiryDate > now) {
+  return { error: '绑定有效期内无法更换' } // ❌ 阻止切换
+}
+```
+
+**修改后逻辑（新）：**
+```javascript
+// 查询B当前的绑定
+const existingBinding = await query(`
+  SELECT * FROM referral_bindings 
+  WHERE referee_id = ? AND status = 'active'
+`, [userId])
+
+if (existingBinding.length > 0) {
+  const current = existingBinding[0]
+  
+  // 情况1: 同一个推荐人 → 续期（刷新30天）
+  if (current.referrer_id === newReferrerId) {
+    await query(`
+      UPDATE referral_bindings 
+      SET expiry_date = DATE_ADD(NOW(), INTERVAL 30 DAY),
+          binding_date = NOW()
+      WHERE id = ?
+    `, [current.id])
+    return { success: true, action: 'renewed' }
+  }
+  
+  // 情况2: 不同推荐人 → 立即切换
+  else {
+    // 旧绑定标记为 cancelled
+    await query(`
+      UPDATE referral_bindings 
+      SET status = 'cancelled'
+      WHERE id = ?
+    `, [current.id])
+    
+    // 创建新绑定
+    await query(`
+      INSERT INTO referral_bindings 
+      (id, referee_id, referrer_id, referral_code, status, binding_date, expiry_date)
+      VALUES (?, ?, ?, ?, 'active', NOW(), DATE_ADD(NOW(), INTERVAL 30 DAY))
+    `, [newBindingId, userId, newReferrerId, referralCode])
+    
+    return { success: true, action: 'switched' }
+  }
+}
+```
+
+**关键变化**：
+- ✅ 删除"有效期内不能切换"的限制
+- ✅ 旧绑定标记为 `cancelled`（而不是 `expired`）
+- ✅ 立即创建新绑定，重新计算30天
+
+---
+
+### 2. `/api/miniprogram/pay/notify` - 支付回调更新
+
+**修改前逻辑（现有）：**
+```javascript
+// 更新绑定为 converted
+await query(`
+  UPDATE referral_bindings 
+  SET status = 'converted', 
+      conversion_date = NOW(),
+      commission_amount = ?
+  WHERE id = ?
+`, [commission, bindingId])
+```
+
+**修改后逻辑（新）：**
+```javascript
+// 查询B当前的绑定（active状态）
+const binding = await query(`
+  SELECT * FROM referral_bindings 
+  WHERE referee_id = ? AND status = 'active'
+  ORDER BY binding_date DESC LIMIT 1
+`, [userId])
+
+if (binding.length === 0) {
+  console.log('[PayNotify] 无有效绑定，跳过分佣')
+  return
+}
+
+const currentBinding = binding[0]
+const referrerId = currentBinding.referrer_id
+
+// 计算佣金
+const commission = amount * distributorShare
+
+// 更新绑定记录（累加购买次数和佣金）
+await query(`
+  UPDATE referral_bindings 
+  SET last_purchase_date = NOW(),
+      purchase_count = purchase_count + 1,
+      total_commission = total_commission + ?
+  WHERE id = ?
+`, [commission, currentBinding.id])
+
+// 更新推荐人收益
+await query(`
+  UPDATE users 
+  SET pending_earnings = pending_earnings + ?
+  WHERE id = ?
+`, [commission, referrerId])
+
+console.log('[PayNotify] 分佣成功:', {
+  referee: userId,
+  referrer: referrerId,
+  commission,
+  purchaseCount: currentBinding.purchase_count + 1
+})
+```
+
+**关键变化**：
+- ✅ 不再标记为 `converted`（保持 `active`）
+- ✅ 记录 `last_purchase_date`（用于判断是否有购买）
+- ✅ 累加 `purchase_count` 和 `total_commission`
+- ✅ 允许同一绑定多次购买分佣
+
+---
+
+### 3. 定时任务 - 自动解绑
+
+**新增文件**: `scripts/auto-unbind-expired.js`
+
+```javascript
+/**
+ * 自动解绑定时任务
+ * 每天凌晨2点运行（建议配置 cron）
+ * 
+ * 解绑条件：
+ * 1. 绑定超过30天（expiry_date < NOW）
+ * 2. 期间没有任何购买（purchase_count = 0）
+ */
+
+const { query } = require('../lib/db')
+
+async function autoUnbind() {
+  console.log('[AutoUnbind] 开始执行自动解绑任务...')
+  
+  try {
+    // 查询需要解绑的记录
+    const expiredBindings = await query(`
+      SELECT id, referee_id, referrer_id, binding_date, expiry_date
+      FROM referral_bindings
+      WHERE status = 'active'
+        AND expiry_date < NOW()
+        AND purchase_count = 0
+    `)
+    
+    if (expiredBindings.length === 0) {
+      console.log('[AutoUnbind] 无需解绑的记录')
+      return
+    }
+    
+    console.log(`[AutoUnbind] 找到 ${expiredBindings.length} 条需要解绑的记录`)
+    
+    // 批量更新为 expired
+    const ids = expiredBindings.map(b => b.id)
+    await query(`
+      UPDATE referral_bindings 
+      SET status = 'expired'
+      WHERE id IN (?)
+    `, [ids])
+    
+    console.log(`[AutoUnbind] ✅ 已解绑 ${expiredBindings.length} 条记录`)
+    
+    // 输出明细
+    expiredBindings.forEach(b => {
+      console.log(`  - ${b.referee_id} 解除与 ${b.referrer_id} 的绑定（绑定于 ${b.binding_date}）`)
+    })
+    
+  } catch (error) {
+    console.error('[AutoUnbind] ❌ 执行失败:', error)
+  }
+}
+
+// 如果直接运行此脚本
+if (require.main === module) {
+  autoUnbind().then(() => {
+    console.log('[AutoUnbind] 任务完成')
+    process.exit(0)
+  })
+}
+
+module.exports = { autoUnbind }
+```
+
+**部署方式（宝塔面板）**：
+1. 进入"计划任务" → 添加 Shell 脚本
+2. 执行周期：每天 02:00
+3. 脚本内容：
+   ```bash
+   cd /www/wwwroot/soul && node scripts/auto-unbind-expired.js
+   ```
+
+---
+
+## 📊 状态流转图
+
+```
+用户B的绑定状态流转：
+
+[无绑定]
+  ↓ (点击A的链接)
+[active - 绑定A] ← expiry_date = NOW + 30天
+  ↓ (点击C的链接)
+[active - 绑定C] ← 旧绑定变 cancelled，新绑定 expiry_date = NOW + 30天
+  ↓ (购买)
+[active - 绑定C] ← purchase_count++, last_purchase_date = NOW
+  ↓ (30天后，无购买)
+[expired] ← 自动解绑
+  ↓ (再次点击D的链接)
+[active - 绑定D] ← 重新绑定
+```
+
+**status 枚举说明**：
+- `active`: 当前有效绑定
+- `cancelled`: 被切换（用户点了其他人链接）
+- `expired`: 30天到期且无购买
+- `converted`: **不再使用**（在新逻辑中，购买不改变status）
+
+---
+
+## 🧪 测试用例
+
+### 用例1: 立即切换绑定
+
+```
+1. A推荐B → B注册
+   预期: referral_bindings 新增一条 (referee=B, referrer=A, status=active)
+
+2. B点击C的链接
+   预期: 
+   - 旧记录 (referrer=A) status → cancelled
+   - 新记录 (referrer=C) status = active, expiry_date = NOW + 30天
+
+3. B购买文章
+   预期: 
+   - 佣金给C（不是A）
+   - binding.purchase_count = 1
+   - binding.last_purchase_date = NOW
+```
+
+### 用例2: 30天无购买自动解绑
+
+```
+1. A推荐B → B注册
+   预期: binding (referee=B, referrer=A, expiry_date = NOW + 30天)
+
+2. 等待31天（模拟）
+   手动执行: node scripts/auto-unbind-expired.js
+   预期: binding.status → expired
+
+3. B点击C的链接
+   预期: 创建新绑定 (referrer=C)
+```
+
+### 用例3: 多次购买累加佣金
+
+```
+1. A推荐B → B绑定A
+2. B购买文章1（1元）
+   预期: A获得佣金 0.9元，binding.purchase_count = 1
+3. B购买文章2（1元）
+   预期: A再获得佣金 0.9元，binding.purchase_count = 2，total_commission = 1.8
+```
+
+---
+
+## ⚠️ 注意事项
+
+### 1. 边界情况处理
+
+**Q1: B多次点击同一个人的链接？**
+- A: 刷新 `expiry_date`（续期30天），不创建新记录
+
+**Q2: B在切换推荐人后的旧订单佣金？**
+- A: 历史佣金不变，只影响新订单
+
+**Q3: 用户注册时没有推荐码？**
+- A: 无绑定状态，等待首次点击分享链接
+
+### 2. 数据一致性
+
+- 使用事务保证绑定切换的原子性
+- 定时任务运行时间建议在凌晨低峰期
+- 建议添加 `idx_expiry_status` 索引优化查询
+
+### 3. 性能优化
+
+```sql
+-- 优化索引
+CREATE INDEX idx_referee_status ON referral_bindings(referee_id, status);
+CREATE INDEX idx_expiry_purchase ON referral_bindings(expiry_date, purchase_count);
+```
+
+---
+
+## 🚀 部署步骤
+
+### Step 1: 数据库迁移
+```bash
+# 执行 SQL 添加新字段
+mysql -u root -p mycontent_db < scripts/migration-add-binding-fields.sql
+```
+
+### Step 2: 修改 API 代码
+- ✅ 修改 `/api/referral/bind`（立即切换逻辑）
+- ✅ 修改 `/api/miniprogram/pay/notify`（累加购买次数）
+
+### Step 3: 部署定时任务
+- ✅ 创建 `scripts/auto-unbind-expired.js`
+- ✅ 宝塔面板配置 cron（每天02:00）
+
+### Step 4: 测试验证
+- ✅ 测试切换绑定流程
+- ✅ 测试购买分佣
+- ✅ 手动运行定时任务验证解绑
+
+---
+
+## 📈 后续优化建议
+
+1. **管理后台增强**
+   - 查看绑定切换历史（谁被谁抢走了）
+   - 统计推荐人的"流失率"（被切换走的比例）
+
+2. **用户端提示**
+   - 点击新链接时提示"即将切换推荐人"
+   - 显示当前绑定的推荐人信息
+
+3. **防刷机制**
+   - 限制同一用户短时间内频繁切换绑定
+   - 记录IP和设备指纹防止恶意刷绑定
+
+4. **数据分析**
+   - 统计平均绑定时长
+   - 分析哪些推荐人容易被"抢走"
+   - 优化推荐策略
+
+---
+
+## 🔗 相关文档
+
+- [分销与绑定流程图](./分销与绑定流程图.md)
+- [推广设置功能完整修复清单](./推广设置功能-完整修复清单.md)
+- [API接入说明](./API接入说明.md)
diff --git a/开发文档/8、部署/章节阅读付费标准流程设计.md b/开发文档/8、部署/章节阅读付费标准流程设计.md
new file mode 100644
index 00000000..75838da2
--- /dev/null
+++ b/开发文档/8、部署/章节阅读付费标准流程设计.md
@@ -0,0 +1,524 @@
+# 章节阅读与付费标准流程设计
+
+> 目标：规范阅读/付费流程，规避 bug，追踪阅读状态（是否读完），为后续数据分析/推荐提供基础。
+
+---
+
+## 一、核心问题与设计目标
+
+### 当前存在的风险点
+1. **权限判断时机不统一**：有些地方用本地缓存、有些用接口，可能不一致
+2. **登录前后状态切换**：未登录→登录、登录后免费列表变化，状态同步复杂
+3. **阅读进度无追踪**：只知道"是否打开过"，不知"是否读完"、"读到哪"
+4. **付费前重复校验**：支付前、登录后、initSection 多次请求 check-purchased
+5. **异常降级策略不统一**：网络失败时有些保守、有些用缓存，可能误解锁
+
+### 设计目标
+- **唯一权威数据源**：章节权限以服务端为准（users + orders 表）
+- **标准状态机**：章节状态、用户状态明确定义，流转有迹可循
+- **阅读进度追踪**：记录滚动进度、阅读时长、是否读完（≥90% 或到底部）
+- **统一异常处理**：网络失败、超时、服务端错误统一降级策略（保守+重试）
+- **流程可回溯**：关键节点打日志，便于排查 bug 和数据分析
+
+---
+
+## 二、标准状态机设计
+
+### 2.1 章节权限状态（ChapterAccessState）
+
+| 状态 | 说明 | 前端展示 |
+|------|------|----------|
+| `unknown` | 初始/加载中，尚未确定权限 | loading 骨架屏 |
+| `free` | 免费章节，无需登录/购买 | 全文 + 已读标记 |
+| `locked_not_login` | 付费章节 + 用户未登录 | 预览 + 登录按钮 |
+| `locked_not_purchased` | 付费章节 + 已登录但未购买 | 预览 + 购买按钮 |
+| `unlocked_purchased` | 付费章节 + 已购买（单章/全书） | 全文 + 已读标记 |
+| `error` | 权限校验失败（网络/服务端错误） | 预览 + 重试按钮 |
+
+### 2.2 阅读进度状态（ReadingProgressState）
+
+```javascript
+{
+  sectionId: '1.2',
+  status: 'reading' | 'completed' | 'abandoned',  // 阅读中 | 已完成 | 已放弃（30天未回）
+  progress: 75,           // 滚动进度百分比 0-100
+  duration: 360,          // 累计阅读时长（秒）
+  lastPosition: 1200,     // 上次滚动位置（px）
+  completedAt: null,      // 读完时间戳（达到90%+停留3s 或滑到底部）
+  firstOpenAt: 1738560000,// 首次打开时间戳
+  lastOpenAt: 1738563600  // 最后打开时间戳
+}
+```
+
+### 2.3 状态流转图
+
+```
+进入阅读页
+  ↓
+[unknown] 加载中
+  ↓
+拉取最新免费列表 + 用户登录状态
+  ↓
+  ├─ 免费章节 → [free] → 全文展示 → 记录阅读进度
+  ├─ 未登录 → [locked_not_login] → 预览 + 登录按钮
+  │     ↓ 登录成功
+  │     ├─ 章节已免费 → [free]
+  │     ├─ 已购买 → [unlocked_purchased]
+  │     └─ 未购买 → [locked_not_purchased]
+  ├─ 已登录未购买 → [locked_not_purchased] → 预览 + 购买按钮
+  │     ↓ 支付成功
+  │     └─ [unlocked_purchased] → 全文展示
+  └─ 已登录已购买 → [unlocked_purchased] → 全文展示 → 记录阅读进度
+
+网络/服务端错误 → [error] → 保守展示预览 + 重试按钮
+```
+
+---
+
+## 三、标准流程与接口调用顺序
+
+### 3.1 进入章节页标准流程
+
+```javascript
+async onLoad(options) {
+  const { id, ref } = options
+  
+  // 1. 初始化状态
+  this.setState({ accessState: 'unknown', loading: true })
+  
+  // 2. 处理推荐码（异步不阻塞）
+  if (ref) this.handleReferralCode(ref)
+  
+  // 3. 【关键】拉取最新配置（免费列表、价格等）- 串行等待
+  await this.fetchLatestConfig()
+  
+  // 4. 【关键】确定章节权限状态 - 串行等待
+  const accessState = await this.determineAccessState(id)
+  
+  // 5. 加载章节内容（全文或预览）
+  await this.loadChapterContent(id, accessState)
+  
+  // 6. 若有权限则初始化阅读追踪
+  if (['free', 'unlocked_purchased'].includes(accessState)) {
+    this.initReadingTracker(id)
+  }
+  
+  // 7. 加载上下章导航
+  this.loadNavigation(id)
+  
+  this.setState({ loading: false })
+}
+```
+
+### 3.2 determineAccessState 权限判断标准
+
+```javascript
+async determineAccessState(sectionId) {
+  try {
+    // 1. 检查是否免费（以服务端最新配置为准）
+    if (this.isFreeChapter(sectionId)) {
+      return 'free'
+    }
+    
+    // 2. 检查是否登录
+    const userId = app.globalData.userInfo?.id
+    if (!userId) {
+      return 'locked_not_login'
+    }
+    
+    // 3. 【权威接口】请求服务端校验是否已购买
+    const res = await app.request(
+      `/api/user/check-purchased?userId=${userId}&type=section&productId=${sectionId}`,
+      { timeout: 5000 }
+    )
+    
+    if (res.success && res.data?.isPurchased) {
+      // 同步更新本地缓存（仅作展示用，不作权限依据）
+      this.syncLocalPurchaseCache(sectionId, res.data)
+      return 'unlocked_purchased'
+    }
+    
+    return 'locked_not_purchased'
+    
+  } catch (error) {
+    console.error('[Access] 权限判断失败:', error)
+    // 网络/服务端错误 → 保守策略：视为无权限 + 可重试
+    return 'error'
+  }
+}
+```
+
+### 3.3 登录后重新校验标准流程
+
+```javascript
+async onLoginSuccess() {
+  wx.showLoading({ title: '更新状态中...' })
+  
+  try {
+    // 1. 刷新用户购买列表（全局状态）
+    await this.refreshUserPurchaseStatus()
+    
+    // 2. 重新拉取免费列表（可能刚改免费）
+    await this.fetchLatestConfig()
+    
+    // 3. 重新判断当前章节权限
+    const newAccessState = await this.determineAccessState(this.data.sectionId)
+    
+    // 4. 更新状态并刷新内容
+    this.setState({ 
+      accessState: newAccessState,
+      isLoggedIn: true 
+    })
+    
+    // 5. 若已解锁则初始化阅读追踪
+    if (['free', 'unlocked_purchased'].includes(newAccessState)) {
+      await this.loadChapterContent(this.data.sectionId, newAccessState)
+      this.initReadingTracker(this.data.sectionId)
+    }
+    
+    wx.hideLoading()
+    wx.showToast({ title: '登录成功', icon: 'success' })
+    
+  } catch (e) {
+    wx.hideLoading()
+    wx.showToast({ title: '状态更新失败，请重试', icon: 'none' })
+  }
+}
+```
+
+### 3.4 支付成功后刷新标准流程
+
+```javascript
+async onPaymentSuccess() {
+  wx.showLoading({ title: '确认购买中...' })
+  
+  try {
+    // 1. 等待服务端处理支付回调（1-2秒）
+    await this.sleep(2000)
+    
+    // 2. 刷新用户购买状态（从 orders 表拉取最新）
+    await this.refreshUserPurchaseStatus()
+    
+    // 3. 重新判断当前章节权限（应为 unlocked_purchased）
+    const newAccessState = await this.determineAccessState(this.data.sectionId)
+    
+    if (newAccessState !== 'unlocked_purchased') {
+      // 支付成功但权限未生效 → 可能回调延迟，再重试一次
+      await this.sleep(1000)
+      newAccessState = await this.determineAccessState(this.data.sectionId)
+    }
+    
+    // 4. 更新状态并重新加载全文
+    this.setState({ accessState: newAccessState })
+    await this.loadChapterContent(this.data.sectionId, newAccessState)
+    
+    // 5. 初始化阅读追踪
+    this.initReadingTracker(this.data.sectionId)
+    
+    wx.hideLoading()
+    wx.showToast({ title: '购买成功', icon: 'success' })
+    
+  } catch (e) {
+    wx.hideLoading()
+    wx.showModal({
+      title: '提示',
+      content: '购买成功，但内容加载失败，请返回重新进入',
+      showCancel: false
+    })
+  }
+}
+```
+
+---
+
+## 四、阅读进度追踪方案
+
+### 4.1 数据结构（本地 + 服务端）
+
+**本地存储**（实时更新，用于断点续读）：
+```javascript
+wx.setStorageSync('reading_progress', {
+  '1.2': { progress: 75, duration: 360, lastPosition: 1200, lastOpenAt: xxx },
+  '2.1': { progress: 30, duration: 120, lastPosition: 500, lastOpenAt: xxx }
+})
+```
+
+**服务端表**（定期上报，用于数据分析）：
+```sql
+CREATE TABLE reading_progress (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  user_id VARCHAR(50) NOT NULL,
+  section_id VARCHAR(20) NOT NULL,
+  progress INT DEFAULT 0,           -- 阅读进度 0-100
+  duration INT DEFAULT 0,           -- 累计时长（秒）
+  status ENUM('reading', 'completed', 'abandoned') DEFAULT 'reading',
+  completed_at DATETIME NULL,       -- 读完时间
+  first_open_at DATETIME NOT NULL,
+  last_open_at DATETIME NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY idx_user_section (user_id, section_id),
+  INDEX idx_user_status (user_id, status),
+  INDEX idx_completed (completed_at)
+);
+```
+
+### 4.2 追踪逻辑
+
+```javascript
+// 初始化阅读追踪器
+initReadingTracker(sectionId) {
+  const tracker = {
+    sectionId,
+    startTime: Date.now(),
+    lastScrollTime: Date.now(),
+    totalDuration: 0,
+    maxProgress: 0,
+    isCompleted: false,
+    scrollTimer: null
+  }
+  
+  this.readingTracker = tracker
+  
+  // 恢复上次阅读位置
+  this.restoreLastPosition(sectionId)
+  
+  // 监听滚动事件（节流）
+  this.watchScrollProgress()
+  
+  // 定期上报进度（每30秒）
+  this.startProgressReport()
+}
+
+// 监听滚动进度（节流 500ms）
+watchScrollProgress() {
+  let scrollTimer = null
+  
+  wx.onPageScroll((e) => {
+    if (scrollTimer) clearTimeout(scrollTimer)
+    
+    scrollTimer = setTimeout(() => {
+      const { scrollTop, scrollHeight, clientHeight } = this.getScrollInfo()
+      const progress = Math.min(100, Math.round((scrollTop / (scrollHeight - clientHeight)) * 100))
+      
+      // 更新最大进度
+      if (progress > this.readingTracker.maxProgress) {
+        this.readingTracker.maxProgress = progress
+        this.saveProgressLocal(progress, scrollTop)
+      }
+      
+      // 判断是否读完（≥90% 且停留3秒）
+      if (progress >= 90 && !this.readingTracker.isCompleted) {
+        this.checkCompletion(progress)
+      }
+    }, 500)
+  })
+}
+
+// 判断是否读完
+async checkCompletion(progress) {
+  // 停留3秒后标记为已读完
+  await this.sleep(3000)
+  
+  if (progress >= 90 && !this.readingTracker.isCompleted) {
+    this.readingTracker.isCompleted = true
+    this.readingTracker.completedAt = Date.now()
+    
+    // 立即上报完成状态
+    await this.reportCompletion()
+    
+    // 触发埋点/数据分析
+    this.trackEvent('chapter_completed', {
+      sectionId: this.data.sectionId,
+      duration: this.readingTracker.totalDuration
+    })
+  }
+}
+
+// 定期上报进度（每30秒，页面隐藏/卸载时也上报）
+startProgressReport() {
+  this.reportInterval = setInterval(() => {
+    this.reportProgressToServer()
+  }, 30000)
+  
+  // 页面隐藏/卸载时立即上报
+  wx.onHide(() => this.reportProgressToServer())
+  wx.onUnload(() => this.reportProgressToServer())
+}
+
+// 上报进度到服务端
+async reportProgressToServer() {
+  if (!this.readingTracker) return
+  
+  const now = Date.now()
+  const duration = Math.round((now - this.readingTracker.lastScrollTime) / 1000)
+  this.readingTracker.totalDuration += duration
+  this.readingTracker.lastScrollTime = now
+  
+  try {
+    await app.request('/api/user/reading-progress', {
+      method: 'POST',
+      data: {
+        userId: app.globalData.userInfo?.id,
+        sectionId: this.readingTracker.sectionId,
+        progress: this.readingTracker.maxProgress,
+        duration: this.readingTracker.totalDuration,
+        status: this.readingTracker.isCompleted ? 'completed' : 'reading'
+      }
+    })
+  } catch (e) {
+    console.warn('[Progress] 上报失败，下次重试')
+  }
+}
+```
+
+### 4.3 断点续读
+
+```javascript
+// 恢复上次阅读位置
+restoreLastPosition(sectionId) {
+  const progressData = wx.getStorageSync('reading_progress') || {}
+  const lastProgress = progressData[sectionId]
+  
+  if (lastProgress?.lastPosition) {
+    wx.pageScrollTo({
+      scrollTop: lastProgress.lastPosition,
+      duration: 300
+    })
+    
+    wx.showToast({ 
+      title: `已恢复到 ${lastProgress.progress}%`,
+      icon: 'none',
+      duration: 2000
+    })
+  }
+}
+```
+
+---
+
+## 五、异常处理与降级策略
+
+### 5.1 统一异常处理原则
+
+| 异常类型 | 降级策略 | 用户提示 |
+|---------|---------|---------|
+| 网络超时（>5s） | 保守策略：视为无权限，展示预览 + 重试按钮 | "网络连接超时，请重试" |
+| 服务端 500 | 同上 | "服务暂时不可用，请稍后重试" |
+| 权限接口返回 error | 同上 | "无法确认权限，请重试" |
+| 内容接口失败 | 尝试本地缓存 → 失败则重试3次 → 仍失败则提示 | "内容加载失败，已尝试 {n} 次" |
+| 支付成功但权限未生效 | 延迟1秒重试一次 → 仍失败则提示联系客服 | "购买成功，正在确认..." |
+
+### 5.2 重试机制
+
+```javascript
+async requestWithRetry(url, options, maxRetries = 3) {
+  let lastError = null
+  
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const res = await app.request(url, { ...options, timeout: 5000 })
+      return res
+    } catch (e) {
+      lastError = e
+      console.warn(`[Retry] 第 ${i+1} 次请求失败:`, url, e.message)
+      
+      if (i < maxRetries - 1) {
+        await this.sleep(1000 * (i + 1)) // 指数退避
+      }
+    }
+  }
+  
+  throw lastError
+}
+```
+
+---
+
+## 六、日志与埋点规范
+
+### 6.1 关键节点日志
+
+```javascript
+// 进入章节
+console.log('[Chapter] 进入章节', { sectionId, accessState, userId, timestamp })
+
+// 权限判断
+console.log('[Access] 权限判断', { sectionId, isFree, isLoggedIn, isPurchased, result: accessState })
+
+// 登录成功
+console.log('[Login] 登录成功', { userId, beforeState, afterState, timestamp })
+
+// 支付成功
+console.log('[Payment] 支付成功', { userId, productType, productId, amount, orderNo, timestamp })
+
+// 阅读完成
+console.log('[Reading] 阅读完成', { sectionId, duration, progress, timestamp })
+
+// 异常
+console.error('[Error] 异常', { type, message, stack, context })
+```
+
+### 6.2 数据埋点（可选，接入统计平台）
+
+```javascript
+// 章节打开
+trackEvent('chapter_open', { sectionId, accessState, source })
+
+// 章节解锁（登录/支付）
+trackEvent('chapter_unlocked', { sectionId, unlockMethod: 'login' | 'purchase' })
+
+// 阅读完成
+trackEvent('chapter_completed', { sectionId, duration, fromProgress })
+
+// 购买转化
+trackEvent('purchase_conversion', { productType, productId, amount, referralCode })
+```
+
+---
+
+## 七、实施步骤
+
+### 阶段一：重构权限判断（1-2天）
+1. 新增 `accessState` 字段和状态机逻辑
+2. 统一 `determineAccessState` 方法
+3. 修改 `onLoad`、`onLoginSuccess`、`onPaymentSuccess` 按标准流程
+4. 统一异常处理和重试机制
+
+### 阶段二：阅读进度追踪（2-3天）
+1. 创建 `reading_progress` 表（迁移脚本）
+2. 实现 `initReadingTracker`、`watchScrollProgress`、`checkCompletion`
+3. 实现本地存储 + 定期上报
+4. 实现断点续读
+
+### 阶段三：测试与优化（1-2天）
+1. 单元测试：各状态流转、异常降级
+2. 集成测试：登录、支付、阅读完整流程
+3. 边界测试：网络超时、服务端错误、并发操作
+4. 性能优化：节流、防抖、缓存策略
+
+### 阶段四：数据分析接入（可选）
+1. 对接统计平台（如微信小程序数据助手、神策、诸葛等）
+2. 配置关键指标看板：购买转化率、阅读完成率、平均阅读时长
+3. A/B 测试：不同付费墙文案、价格策略
+
+---
+
+## 八、预期收益
+
+- **bug 减少 80%+**：权限判断统一、异常处理标准化
+- **用户体验提升**：断点续读、进度可视化、明确的状态反馈
+- **数据驱动决策**：阅读完成率、购买转化漏斗分析、章节热度排行
+- **可扩展性**：状态机设计便于未来增加"试读 N 分钟"、"好友助力解锁"等玩法
+
+---
+
+## 附录：核心代码示例
+
+完整实现代码见配套文件：
+- `miniprogram/utils/chapterAccessManager.js` - 权限管理器
+- `miniprogram/utils/readingTracker.js` - 阅读追踪器
+- `app/api/user/reading-progress/route.ts` - 进度上报接口
+- `scripts/create_reading_progress_table.sql` - 数据表迁移
+
+以上为完整设计方案，建议先实施阶段一、二，验证效果后再进行阶段三、四。
diff --git a/开发文档/8、部署/自动化与Webhook.md b/开发文档/8、部署/自动化与Webhook.md
new file mode 100644
index 00000000..17a4f4ab
--- /dev/null
+++ b/开发文档/8、部署/自动化与Webhook.md
@@ -0,0 +1,3 @@
+# 自动化与 Webhook（合并自 Next.js自动化、WEBHOOK、GitHub Webhook 与宝塔、自动同步）
+
+Next.js 自动化部署流程、Vercel/宝塔 Webhook 配置、自动同步与分支策略。详见原各文档。
diff --git a/开发文档/8、部署/运行与部署.md b/开发文档/8、部署/运行与部署.md
new file mode 100644
index 00000000..28ac0ae8
--- /dev/null
+++ b/开发文档/8、部署/运行与部署.md
@@ -0,0 +1,17 @@
+# 运行与部署（合并自 运行指南、部署总览与线上部署）
+
+> **部署文档导航（推荐）**：[部署总览.md](./部署总览.md) — 含 soul-api、Docker、分销、Webhook、等价主题索引。
+
+## Soul 主站运行
+
+`pnpm install` → `pnpm dev`（端口 3000）或 `pnpm build` + `PORT=3006 node .next/standalone/server.js`
+
+**环境变量**：MYSQL_*、SKIP_DB、ADMIN_*
+
+## 线上部署
+
+**Web**：宝塔 42.194.232.22，路径 /www/wwwroot/soul，PM2 soul，端口 3006
+
+**小程序**：AppID wxb8bbb2b10dec74aa，private.key + 上传脚本
+
+**命令**：`python scripts/deploy_baota.py` 或 `开发文档/服务器管理/scripts/一键部署.py`
diff --git a/开发文档/8、部署/邀请码分销规则说明.md b/开发文档/8、部署/邀请码分销规则说明.md
new file mode 100644
index 00000000..df788156
--- /dev/null
+++ b/开发文档/8、部署/邀请码分销规则说明.md
@@ -0,0 +1,147 @@
+# 邀请码 / 分销规则说明
+
+**配置来源**: 数据库 `system_config.config_key = 'referral_config'`  
+**分佣逻辑**: `app/api/miniprogram/pay/notify/route.ts` 中 `processReferralCommission`
+
+> 📌 **流程图**：绑定与分销的完整流程（谁推荐谁、下单怎么写推荐人、分佣怎么算）见 → [分销与绑定流程图](./分销与绑定流程图.md)
+
+---
+
+## 一、分销规则（当前实现）
+
+### 1. 分成比例
+- **推广者分成**: 默认 **90%**（`referral_config.distributorShare = 90`）
+- **平台**: 10%
+- 可在管理后台或 `system_config.referral_config` 中修改
+
+### 2. 绑定规则
+- **绑定有效期**: 默认 **30 天**（`referral_config.bindingDays = 30`）
+- **一级分销**: 只算直接推荐人（`referral_bindings` 中 `referee_id` = 买家，`referrer_id` = 推广者）
+- **有效绑定**: `referral_bindings.status = 'active'` 且 `expiry_date > NOW()`
+
+### 3. 分佣触发
+- 用户**支付成功**后，回调 `POST /api/miniprogram/pay/notify`
+- 根据**买家 user_id** 查 `referral_bindings`（referee_id = 买家），取有效绑定的 `referrer_id`
+- 佣金 = 订单实付金额 × 90%，计入推广者 `users.pending_earnings`
+- 该绑定记录更新为 `status = 'converted'`，并记录 `commission_amount`、`order_id`
+
+### 4. 其他配置（referral_config）
+- **minWithdrawAmount**: 最小提现金额（默认 10 元）
+- **userDiscount**: 用户优惠比例（默认 5）
+
+---
+
+## 二、订单与邀请码
+
+### 问题
+- 下单接口 `POST /api/miniprogram/pay` 之前**未传邀请码/分销码**，订单表 **orders** 也没有推荐人字段，无法在订单上直接看到“是谁带来的”。
+
+### 处理方式（已实现）
+1. **orders 表增加字段**  
+   - `referrer_id`（VARCHAR(50) NULL）：下单时若存在有效绑定或邀请码，则写入推荐人 user_id。  
+   - `referral_code`（VARCHAR(20) NULL）：**下单时使用的邀请码**，直接记录在订单上便于对账与后台展示。  
+   - **迁移脚本**：`python scripts/add_orders_referrer_id.py`、`python scripts/add_orders_referral_code.py`（表已存在时各执行一次）。
+
+2. **下单时写推荐人与邀请码**  
+   - 创建订单时先按**买家 user_id** 查 `referral_bindings`（referee_id = 买家、有效且未过期），取 `referrer_id`。  
+   - 若未查到且请求体带了 `referralCode`，则用 `users.referral_code = referralCode` 解析出推荐人 id，写入 `orders.referrer_id`。  
+   - **邀请码**：优先存请求体里的 `referralCode`（用户章节支付时传的）；若未传但已有 `referrer_id`，则存该推荐人当前的 `users.referral_code`，保证订单上有一份当时使用的邀请码记录。
+
+3. **小程序传参**  
+   - 支付请求会传 `referralCode`：来自 `wx.getStorageSync('referral_code')`（落地页 ref 带入的“谁邀请了我”的邀请码），供后端解析推荐人并写入 `orders.referrer_id` 与 `orders.referral_code`。  
+   - **同步约定**：`app.js` 在检测到 `ref` / `referralCode` 时除写入 `pendingReferralCode` 外，会同步写入 `referral_code`；**章节支付**（`pages/read/read.js`）与**找伙伴支付**（`pages/match/match.js`）创建订单时都会带上 `referralCode`，保证两类订单都会记录邀请码。
+
+---
+
+## 三、订单表与分销逻辑（已实现）
+
+- **下单时**（`POST /api/miniprogram/pay`）：
+  1. 根据买家 user_id 查 `referral_bindings`（有效且未过期）取 `referrer_id`；
+  2. 若无绑定且请求带 `referralCode`，用 `users.referral_code` 解析出推荐人 id；
+  3. 插入 `orders` 时写入 `referrer_id`（需表已执行 `scripts/add_orders_referrer_id.py`）。
+- **支付成功回调**（`POST /api/miniprogram/pay/notify`）：
+  - 仍按 `referral_bindings` 查推荐人并发放佣金（90%），不依赖订单上的 referrer_id；
+  - 订单上的 `referrer_id` 用于统计、对账和展示。
+
+## 四、相关表与字段
+
+| 表 / 配置 | 说明 |
+|-----------|------|
+| **users** | referral_code（自己的邀请码）, referred_by（可选）, pending_earnings, earnings |
+| **referral_bindings** | referrer_id, referee_id, status(active/converted/expired), expiry_date, commission_amount, order_id |
+| **orders** | referrer_id（推荐人用户ID）, referral_code（下单时使用的邀请码，便于对账与展示） |
+| **system_config** | config_key = 'referral_config'，含 distributorShare、bindingDays 等 |
+
+---
+
+## 五、流程简述
+
+1. 用户 A 分享邀请码 / 带 ref 的链接，用户 B 通过该链接进入并完成绑定（写入 `referral_bindings`，referee_id=B，referrer_id=A）。
+2. 用户 B 下单支付：调用 `POST /api/miniprogram/pay`，后端根据 B 的 user_id 查有效绑定得到 A，写入 `orders.referrer_id = A`。
+3. 支付成功回调：`/api/miniprogram/pay/notify` 再根据 B 查绑定，给 A 结算 90% 佣金，更新 `referral_bindings` 与 `users.pending_earnings`。
+
+这样订单上就有邀请/分销关系（referrer_id），且分佣规则不变。
+
+---
+
+## 六、推荐人 vs 邀请码：会不会乱？
+
+**结论：不会乱。** 全局只认「推荐人 = 用户ID」，邀请码只用于解析出这个 ID。
+
+### 概念区分
+
+| 概念 | 含义 | 存储位置 | 用途 |
+|------|------|----------|------|
+| **邀请码** | 一串码（如 SOULABC123） | `users.referral_code`（每个用户一条） | 链接里带 `ref=邀请码`，用来**识别**是谁推荐的 |
+| **推荐人** | 拿佣金的那个人 | 用**用户ID** `referrer_id` 存 | 订单归属、分佣、统计都只认 ID，不认字符串 |
+
+- 邀请码 → 通过 `users WHERE referral_code = ?` 可唯一解析出 → **推荐人用户ID**。
+- 订单表、绑定表里存的都是 **referrer_id**，从不存邀请码字符串；展示时再用 referrer_id 去查昵称/邀请码即可。
+
+### 绑定与订单归属的优先级（唯一权威）
+
+1. **下单时**（`/api/miniprogram/pay`）  
+   - **先**查 `referral_bindings`：当前买家是否有有效绑定 → 得到 `referrer_id`。  
+   - **仅当没有绑定**时，才用请求体里的 `referralCode` 去 `users` 表解析出 `referrer_id`。  
+   - 最终写入订单的**只有** `orders.referrer_id`（用户ID），不会写邀请码。
+
+2. **分佣时**（支付成功回调）  
+   - 只查 `referral_bindings`（买家 → 有效绑定的推荐人），**不看**订单上的 referrer_id，也不看邀请码。  
+   - 佣金发给绑定表里的 `referrer_id`。
+
+因此：  
+- **绑定表** = 权威的「谁推荐了谁」；  
+- **订单上的 referrer_id** = 下单时根据「绑定表 + 兜底邀请码」算出来的结果，只用于展示/对账；  
+- **邀请码** = 仅作为入口参数，解析成 referrer_id 后就不再参与逻辑，不会和推荐人 ID 混用。
+
+### 前端 storage 说明（避免混用）
+
+- 落地页/分享带 `ref`：写入 `referral_code`（下划线），支付时读 `referral_code` 传给后端作兜底。  
+- App 层待绑定：`pendingReferralCode`；绑定成功后可选写 `boundReferralCode`。  
+- 绑定接口、支付接口请求体里统一用 **referralCode**（驼峰）。  
+
+只要后端始终用「绑定表优先、邀请码兜底」且只落库 referrer_id，全局绑定逻辑就不会乱。
+
+---
+
+## 七、文章/章节分销
+
+**结论：和全局分销是同一套逻辑，没有单独的「按文章维度」分销。**
+
+### 当前实现
+
+- **分享首页**：链接形如 `https://xxx/?ref=邀请码`，点击后 ref 写入 storage，绑定与订单归属按上文规则。
+- **分享某篇文章/章节**：  
+  - 小程序：`/pages/read/read?id=章节ID&ref=邀请码`（阅读页 `onShareAppMessage` / `onShareTimeline` 会带上当前用户邀请码）。  
+  - Web：`/view/read/章节ID?ref=邀请码`。  
+- 访客从**任意**带 ref 的链接进入（首页或某篇文章），都会：
+  1. 用 ref 解析出推荐人并完成绑定（`referral_bindings`）；
+  2. 之后该用户下单，订单归属与分佣都按**同一套**「绑定表优先、邀请码兜底」规则，与**从哪篇文章点进来**无关。
+
+也就是说：**文章/章节只决定落地页内容，不改变绑定与分佣规则**。谁发的链接（ref=谁），谁就是推荐人；买的是哪一章、哪本书，都按 90% 给该推荐人，没有「这篇文章单独分成」或「按章节统计推广效果」的单独逻辑。
+
+### 未实现的部分（若以后要做）
+
+- **按文章/章节维度的统计**：例如「通过《1.2 某某章》链接带来的访问/绑定/订单数」—— 当前未记录分享时的章节 id，无法区分。
+- **按文章的分成策略**：例如某章单独 95%、其他 90% —— 当前未实现，所有订单统一 90%。
+- 若需要「文章分销」统计或差异化分成，需要：在访问/绑定/订单上记录「来源章节」（如 `landing_section_id`），并在分佣或报表里按章节维度汇总。
diff --git a/开发文档/8、部署/阅读页标准流程改造说明.md b/开发文档/8、部署/阅读页标准流程改造说明.md
new file mode 100644
index 00000000..992ad6c4
--- /dev/null
+++ b/开发文档/8、部署/阅读页标准流程改造说明.md
@@ -0,0 +1,395 @@
+# 阅读页标准流程改造说明
+
+> 完成时间：2026-02-04  
+> 改造范围：`miniprogram/pages/read/read.js` 和 `read.wxml`
+
+---
+
+## 一、改造概述
+
+按照《章节阅读付费标准流程设计》，将阅读页重构为标准流程版本，引入状态机和工具类，规避现有 bug，支持阅读进度追踪。
+
+### 核心改动
+1. **引入工具类**：`chapterAccessManager`（权限管理）+ `readingTracker`（阅读追踪）
+2. **状态机管理**：用 `accessState` 枚举替代 `canAccess` 布尔值
+3. **标准流程**：统一 `onLoad`、`onLoginSuccess`、`onPaymentSuccess` 的处理逻辑
+4. **阅读追踪**：自动记录进度、时长、是否读完，支持断点续读
+5. **异常处理**：统一保守策略，网络异常时展示重试按钮，不误解锁
+
+---
+
+## 二、文件变更清单
+
+### 已修改文件
+- ✅ `miniprogram/pages/read/read.js` - 核心逻辑重构（已备份为 `read.js.backup`）
+- ✅ `miniprogram/pages/read/read.wxml` - UI 模板适配新状态
+
+### 新增工具类（已创建）
+- ✅ `miniprogram/utils/chapterAccessManager.js` - 权限管理器
+- ✅ `miniprogram/utils/readingTracker.js` - 阅读追踪器
+
+### 新增接口（已创建）
+- ✅ `app/api/user/reading-progress/route.ts` - 进度上报接口
+
+### 新增数据表（已创建）
+- ✅ `reading_progress` - 阅读进度表（已通过 Python 脚本创建）
+
+---
+
+## 三、核心改动详解
+
+### 1. 状态机设计（accessState）
+
+**旧代码**：用布尔值 `canAccess` 判断权限，状态不清晰
+```javascript
+// ❌ 旧代码
+canAccess: false  // 无法区分"未登录"还是"未购买"
+```
+
+**新代码**：用枚举 `accessState` 明确所有状态
+```javascript
+// ✅ 新代码
+accessState: 'unknown' | 'free' | 'locked_not_login' | 'locked_not_purchased' | 'unlocked_purchased' | 'error'
+```
+
+| 状态 | 含义 | UI 展示 |
+|------|------|---------|
+| `unknown` | 加载中 | loading 骨架屏 |
+| `free` | 免费章节 | 全文 + 阅读追踪 |
+| `locked_not_login` | 未登录 | 预览 + 登录按钮 |
+| `locked_not_purchased` | 未购买 | 预览 + 购买按钮 |
+| `unlocked_purchased` | 已购买 | 全文 + 阅读追踪 |
+| `error` | 网络异常 | 预览 + 重试按钮 |
+
+### 2. onLoad 标准流程
+
+**旧代码**：权限判断分散在 `initSection` 中，混杂内容加载
+```javascript
+// ❌ 旧代码
+async onLoad(options) {
+  const run = async () => {
+    await this.loadFreeChaptersConfig()
+    this.initSection(id)  // 权限判断 + 内容加载混在一起
+  }
+  run()
+}
+```
+
+**新代码**：流程清晰，职责分离
+```javascript
+// ✅ 新代码
+async onLoad(options) {
+  // 1. 拉取最新配置
+  const config = await accessManager.fetchLatestConfig()
+  
+  // 2. 确定权限状态
+  const accessState = await accessManager.determineAccessState(id, config.freeChapters)
+  
+  // 3. 加载内容
+  await this.loadContent(id, accessState)
+  
+  // 4. 如果有权限，初始化阅读追踪
+  if (canAccess) {
+    readingTracker.init(id)
+  }
+  
+  // 5. 加载导航
+  this.loadNavigation(id)
+}
+```
+
+### 3. 登录成功标准流程
+
+**旧代码**：复杂的 `recheckCurrentSectionAndRefresh`，多次请求
+```javascript
+// ❌ 旧代码
+async handleWechatLogin() {
+  await this.refreshPurchaseFromServer()    // 请求1
+  await this.recheckCurrentSectionAndRefresh()  // 内部又请求 check-purchased（请求2）
+  await this.initSection(sectionId)  // 又重复一次权限判断（请求3）
+}
+```
+
+**新代码**：统一 `onLoginSuccess`，流程简洁
+```javascript
+// ✅ 新代码
+async handleWechatLogin() {
+  const result = await app.login()
+  if (result) {
+    await this.onLoginSuccess()  // 标准流程
+  }
+}
+
+async onLoginSuccess() {
+  // 1. 刷新购买状态
+  await accessManager.refreshUserPurchaseStatus()
+  
+  // 2. 重新拉取免费列表
+  const config = await accessManager.fetchLatestConfig()
+  
+  // 3. 重新判断权限（1次请求）
+  const newAccessState = await accessManager.determineAccessState(sectionId, config.freeChapters)
+  
+  // 4. 如果已解锁，重新加载并追踪
+  if (canAccess) {
+    await this.loadContent(sectionId, newAccessState)
+    readingTracker.init(sectionId)
+  }
+}
+```
+
+### 4. 支付成功标准流程
+
+**旧代码**：直接调用 `refreshUserPurchaseStatus` + `initSection`
+```javascript
+// ❌ 旧代码
+await this.callWechatPay(paymentData)
+await this.refreshUserPurchaseStatus()
+this.initSection(this.data.sectionId)
+```
+
+**新代码**：统一 `onPaymentSuccess`，包含重试机制
+```javascript
+// ✅ 新代码
+await this.callWechatPay(paymentData)
+await this.onPaymentSuccess()
+
+async onPaymentSuccess() {
+  await this.sleep(2000)  // 等待回调
+  await accessManager.refreshUserPurchaseStatus()
+  
+  let newAccessState = await accessManager.determineAccessState(...)
+  
+  // 如果权限未生效，再重试一次
+  if (newAccessState !== 'unlocked_purchased') {
+    await this.sleep(1000)
+    newAccessState = await accessManager.determineAccessState(...)
+  }
+  
+  await this.loadContent(sectionId, newAccessState)
+  readingTracker.init(sectionId)
+}
+```
+
+### 5. 阅读进度追踪
+
+**旧代码**：只有进度条显示，无追踪
+```javascript
+// ❌ 旧代码
+onPageScroll(e) {
+  // 只计算进度条显示，不记录阅读状态
+  this.setData({ readingProgress: progress })
+}
+```
+
+**新代码**：集成 `readingTracker`，自动追踪
+```javascript
+// ✅ 新代码
+onPageScroll(e) {
+  // 只在有权限时追踪
+  if (!accessManager.canAccessFullContent(this.data.accessState)) {
+    return
+  }
+  
+  const scrollInfo = { scrollTop, scrollHeight, clientHeight }
+  
+  // 更新 UI 进度条
+  this.setData({ readingProgress: progress })
+  
+  // 更新追踪器（记录最大进度、判断是否读完）
+  readingTracker.updateProgress(scrollInfo)
+}
+
+// 页面隐藏时上报进度
+onHide() {
+  readingTracker.onPageHide()
+}
+
+// 页面卸载时清理
+onUnload() {
+  readingTracker.cleanup()
+}
+```
+
+### 6. 异常处理统一
+
+**旧代码**：异常时用本地缓存，可能误解锁
+```javascript
+// ❌ 旧代码
+catch (e) {
+  canAccess = hasFullBook || purchasedSections.includes(id)  // 危险：信任本地缓存
+}
+```
+
+**新代码**：异常时保守处理，展示 error 状态
+```javascript
+// ✅ 新代码
+catch (e) {
+  return 'error'  // 保守策略：无法确认权限时返回错误状态
+}
+
+// UI 上展示重试按钮
+<view class="article preview" wx:if="{{accessState === 'error'}}">
+  <view class="paywall">
+    <view class="paywall-icon">⚠️</view>
+    <text class="paywall-title">网络异常</text>
+    <view class="login-btn" bindtap="handleRetry">
+      <text>重新加载</text>
+    </view>
+  </view>
+</view>
+```
+
+---
+
+## 四、WXML 模板改动
+
+### 旧模板：基于 canAccess 布尔值
+```xml
+<!-- ❌ 旧模板 -->
+<view class="article" wx:if="{{!loading && canAccess}}">全文</view>
+<view class="article preview" wx:if="{{!loading && !canAccess}}">
+  <view class="paywall" wx:if="{{showPaywall}}">
+    <!-- 未登录和未购买混在一起，难以维护 -->
+  </view>
+</view>
+```
+
+### 新模板：基于 accessState 枚举
+```xml
+<!-- ✅ 新模板 -->
+<view class="loading-state" wx:if="{{accessState === 'unknown' && loading}}">骨架屏</view>
+
+<view class="article" wx:if="{{accessState === 'free' || accessState === 'unlocked_purchased'}}">
+  全文 + 导航
+</view>
+
+<view class="article preview" wx:if="{{accessState === 'locked_not_login'}}">
+  预览 + 登录按钮
+</view>
+
+<view class="article preview" wx:if="{{accessState === 'locked_not_purchased'}}">
+  预览 + 购买按钮
+</view>
+
+<view class="article preview" wx:if="{{accessState === 'error'}}">
+  预览 + 重试按钮
+</view>
+```
+
+---
+
+## 五、测试验证
+
+### 必测场景
+1. **免费章节**
+   - ✅ 进入后直接展示全文
+   - ✅ 滚动时追踪进度（检查 `reading_progress` 表）
+   - ✅ 读到 90% 停留 3 秒后标记为 completed
+
+2. **未登录打开付费章**
+   - ✅ 展示预览（20%）+ 登录按钮
+   - ✅ 点登录 → 登录成功 → 重新判断权限
+   - ✅ 若已购买则解锁，否则显示购买按钮
+
+3. **已登录未购买**
+   - ✅ 展示预览 + 购买按钮
+   - ✅ 点购买 → 支付成功 → 解锁全文
+   - ✅ 解锁后初始化阅读追踪
+
+4. **支付成功**
+   - ✅ 等待 2 秒后刷新权限
+   - ✅ 若未生效则再重试 1 次
+   - ✅ 解锁后展示全文并追踪
+
+5. **网络异常**
+   - ✅ 显示 error 状态 + 重试按钮
+   - ✅ 点重试重新判断权限
+   - ✅ 不误解锁内容
+
+6. **断点续读**
+   - ✅ 退出后重新进入，恢复到上次阅读位置
+   - ✅ Toast 提示"继续阅读 (75%)"
+
+7. **极端情况：登录后当前章节刚改免费**
+   - ✅ 登录时重新拉取免费列表
+   - ✅ 若已免费则直接解锁
+
+---
+
+## 六、数据验证
+
+### 检查 reading_progress 表
+```sql
+-- 查看最近上报的进度
+SELECT * FROM reading_progress 
+ORDER BY last_open_at DESC 
+LIMIT 10;
+
+-- 查看完成率
+SELECT 
+  section_id,
+  COUNT(*) as readers,
+  SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed,
+  ROUND(AVG(progress), 2) as avg_progress,
+  ROUND(AVG(duration)/60, 1) as avg_minutes
+FROM reading_progress
+GROUP BY section_id;
+```
+
+---
+
+## 七、回退方案
+
+如果新版本出现问题，可快速回退：
+
+```bash
+# 恢复旧版本
+cd miniprogram/pages/read/
+copy read.js.backup read.js
+
+# 重新部署小程序
+```
+
+---
+
+## 八、后续优化（可选）
+
+1. **性能优化**
+   - 减少登录后重复请求（当前：刷新购买状态 + check-purchased，可合并为一次）
+   - 阅读追踪节流优化（当前 500ms，可调整）
+
+2. **用户体验**
+   - 断点续读时平滑滚动
+   - 读完后推荐下一章
+
+3. **数据分析**
+   - 接入微信小程序数据助手
+   - 配置完成率、时长等看板
+
+---
+
+## 九、相关文档
+
+- 📖 设计文档：`开发文档/8、部署/章节阅读付费标准流程设计.md`
+- 📖 集成示例：`开发文档/8、部署/章节阅读页集成示例.md`
+- 📖 阅读逻辑分析：`开发文档/8、部署/阅读逻辑分析.md`
+
+---
+
+## 十、总结
+
+### 改造效果
+- ✅ **权限判断统一**：所有权限由 `accessManager` 统一管理，以服务端为准
+- ✅ **状态流转清晰**：6 种状态枚举，UI 与状态一一对应
+- ✅ **异常降级标准**：网络异常时保守处理，展示重试，不误解锁
+- ✅ **阅读追踪完整**：记录进度、时长、是否读完，支持断点续读
+- ✅ **bug 规避**：解决"登录后误解锁"、"支付后权限未生效"等问题
+
+### 预期收益
+- 📉 **bug 减少 80%+**（权限判断统一、异常处理标准化）
+- 📈 **数据驱动决策**（完成率、时长、活跃度分析）
+- 🎯 **用户体验提升**（断点续读、明确的状态反馈、流畅的流程）
+- 🔧 **可维护性提升**（代码结构清晰、职责分离、工具类复用）
+
+改造完成，可正式测试和部署！
diff --git a/开发文档/9、手册/使用手册提示词.md b/开发文档/9、手册/使用手册提示词.md
new file mode 100644
index 00000000..277059a4
--- /dev/null
+++ b/开发文档/9、手册/使用手册提示词.md
@@ -0,0 +1,48 @@
+# 使用手册提示词 (User Manual Prompt) - 智能自生长文档
+
+> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“技术文档专家”角色，生成小白也能看懂的操作手册。
+
+## 1. 基础上下文 (The Two Basic Files)
+### 1.1 角色档案：卡若 (Karuo)
+- **受众**：小白用户、合作方老板。
+- **风格**：大白话、傻瓜式、图文并茂。
+
+### 1.2 文档原则
+- **价值先行**：先说能赚多少钱，再说怎么操作。
+- **步骤清晰**：Step 1, 2, 3。
+
+## 2. 手册核心 (Master Content)
+### 2.1 功能介绍 (Value)
+- **话术**：不要说“分布式”，要说“账目自动同步，谁也改不了”。
+- **核心**：帮你自动分钱的工具。
+
+### 2.2 快速上手 (How-to)
+- **Step 1**: 登录与绑定 (截图)。
+- **Step 2**: 开启流量池 (核心操作)。
+- **Step 3**: 提现与分润 (钱)。
+
+### 2.3 常见问题 (Q&A)
+- **痛点**：如果不显示收益怎么办？
+- **解法**：点击刷新，检查网络。
+
+## 3. AI 协作指令 (Expanded Function)
+**角色**：你是我（卡若）的内容运营。
+**任务**：
+1.  **文档撰写**：根据功能描述，写出“傻瓜式”操作手册。
+2.  **话术优化**：将技术术语翻译成“老板听得懂的话”。
+3.  **用户旅程**：用 Mermaid 展示用户操作流程。
+
+### 示例 Mermaid (用户旅程)
+\`\`\`mermaid
+journey
+    title 合作方使用流程
+    section 注册
+      打开小程序: 5: 合作方
+      手机号登录: 4: 合作方
+    section 赚钱
+      开启流量池: 5: 合作方
+      查看今日收益: 5: 合作方
+    section 提现
+      申请提现: 4: 合作方
+      到账: 5: 合作方
+\`\`\`
diff --git a/开发文档/9、手册/全站捆绑分销体系-SCALE.md b/开发文档/9、手册/全站捆绑分销体系-SCALE.md
new file mode 100644
index 00000000..cc792c1a
--- /dev/null
+++ b/开发文档/9、手册/全站捆绑分销体系-SCALE.md
@@ -0,0 +1,157 @@
+# 全站捆绑分销体系 · SCALE（可复用规格）
+
+> **版本**：1.0  
+> **来源**：一场soul的创业实验-永平 实战提炼  
+> **用途**：作为全站消费捆绑 + 分销机制的可复用规格，可套用到其他网站、小程序、付费内容项目
+
+---
+
+## 一、核心理念
+
+**全站捆绑** = 用户通过谁的分享链接进入，即与谁建立 30 天有效期的「推荐关系」，该关系覆盖全站所有消费（章节、全书、找伙伴、会员等）。
+
+**分销体系** = 被推荐人支付成功 → 推荐人获得佣金（默认 90%）→ 支持提现。
+
+---
+
+## 二、核心规则（30 天捆绑）
+
+| 规则 | 说明 |
+|:---|:---|
+| **动态绑定** | 用户 B 点击谁的分享链接，立即绑定谁（无条件切换） |
+| **佣金归属** | B 购买时，佣金给当前推荐人（最新绑定的那个人） |
+| **30 天有效期** | 绑定日起 30 天内有效，可续期（同一推荐人再次点击则刷新 30 天） |
+| **自动解绑** | 绑定 30 天内，若 B 既没点击其他链接，也没有任何购买 → 自动解绑 |
+
+### 时间线示例
+
+```
+Day 0:  A 推荐 B → B 注册 → B 绑定 A（30 天有效期）
+Day 5:  B 点击 C 的链接 → B 立即切换绑定 C（重新开始 30 天有效期）
+Day 10: B 购买 → 佣金给 C（当前推荐人）
+Day 35: 绑定 C 的 30 天到期，若期间无购买 → 自动解绑
+```
+
+---
+
+## 三、数据库设计（最小可复用）
+
+### 3.1 referral_bindings（推荐绑定表）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | VARCHAR(64) | 主键 |
+| referee_id | VARCHAR(64) | 被推荐人（买家） |
+| referrer_id | VARCHAR(64) | 推荐人（拿佣金的人） |
+| referral_code | VARCHAR(20) | 推荐码 |
+| status | ENUM | active / cancelled / expired |
+| binding_date | TIMESTAMP | 最后一次绑定时间 |
+| expiry_date | DATETIME | 过期时间（30 天后） |
+| last_purchase_date | DATETIME | 最后一次购买时间 |
+| purchase_count | INT | 购买次数 |
+| total_commission | DECIMAL(10,2) | 累计佣金 |
+
+### 3.2 users（需扩展字段）
+
+| 字段 | 说明 |
+|------|------|
+| referral_code | 自己的邀请码 |
+| referred_by | 可选，首次推荐人 |
+| pending_earnings | 待结算佣金 |
+| earnings | 已结算佣金 |
+
+### 3.3 orders（需扩展字段）
+
+| 字段 | 说明 |
+|------|------|
+| referrer_id | 下单时的推荐人 user_id |
+| referral_code | 下单时使用的邀请码（对账/展示） |
+
+### 3.4 system_config（配置）
+
+- `config_key = 'referral_config'`
+- `distributorShare`：推广者分成比例（默认 90）
+- `bindingDays`：绑定有效期天数（默认 30）
+- `minWithdrawAmount`：最小提现金额（默认 10 元）
+
+---
+
+## 四、API 逻辑（关键接口）
+
+### 4.1 绑定接口 `POST /api/referral/bind`
+
+- **入参**：userId（被推荐人）, referralCode
+- **逻辑**：
+  - 同一推荐人 → 续期（刷新 30 天）
+  - 不同推荐人 → 旧绑定 status=cancelled，新绑定 active，expiry=NOW+30 天
+
+### 4.2 下单时定推荐人（创建订单前）
+
+1. 先查 `referral_bindings`（referee_id=买家，status=active，expiry_date>NOW）
+2. 无绑定则用请求体 `referralCode` 查 users 得 referrer_id
+3. 写入 `orders.referrer_id`、`orders.referral_code`
+
+### 4.3 支付成功回调（分佣）
+
+1. 查 `referral_bindings`（referee_id=买家，status=active）
+2. 取 referrer_id，佣金 = 订单金额 × distributorShare / 100
+3. 更新 `referral_bindings`：purchase_count++，total_commission+=佣金，last_purchase_date=NOW
+4. 更新 `users`：referrer 的 pending_earnings += 佣金
+5. **不**将 binding 改为 converted，保持 active，允许多次购买分佣
+
+### 4.4 自动解绑定时任务（每天 02:00）
+
+```sql
+UPDATE referral_bindings
+SET status = 'expired'
+WHERE status = 'active'
+  AND expiry_date < NOW()
+  AND purchase_count = 0
+```
+
+---
+
+## 五、概念区分（避免混乱）
+
+| 概念 | 含义 | 存储 | 用途 |
+|------|------|------|------|
+| **邀请码** | 一串码，如 SOULABC123 | users.referral_code | 链接 ref=邀请码，解析出推荐人 |
+| **推荐人** | 拿佣金的人 | referrer_id（用户ID） | 分佣、订单归属、统计 |
+| **绑定表** | 权威的「谁推荐了谁」 | referral_bindings | 分佣只看此表 |
+
+**优先级**：绑定表 > 邀请码兜底。订单 referrer_id 只做展示/对账，不参与分佣计算。
+
+---
+
+## 六、提现流程（配套）
+
+- 用户：可提现 = 累计佣金 − 已提现 − 待审核
+- 申请：POST /api/miniprogram/withdraw → status=pending
+- 管理端：通过 → 调微信商家转账 → status=processing
+- 微信回调：成功 → status=success；失败 → status=failed
+
+---
+
+## 七、复用 checklist（套用到新项目）
+
+- [ ] 建表：referral_bindings、users 扩展、orders 扩展、withdrawals
+- [ ] 配置：referral_config（分成比例、绑定天数、最低提现）
+- [ ] 绑定接口：/api/referral/bind（动态切换 + 30 天）
+- [ ] 下单逻辑：写 orders.referrer_id、referral_code
+- [ ] 支付回调：查绑定 → 分佣 → 累加 purchase_count
+- [ ] 定时任务：每天解绑 purchase_count=0 且过期的记录
+- [ ] 前端：分享链接带 ref=邀请码，登录后调 bind
+- [ ] 提现：用户申请 → 管理审核 → 微信打款
+
+---
+
+## 八、相关文档（本项目内）
+
+- [新分销逻辑设计方案](../8、部署/新分销逻辑设计方案.md)
+- [邀请码分销规则说明](../8、部署/邀请码分销规则说明.md)
+- [分销与绑定流程图](../8、部署/分销与绑定流程图.md)
+- [分销提现流程图](../8、部署/分销提现流程图.md)
+
+---
+
+*本 SCALE 可供任何有「全站消费 + 分销」需求的网站/小程序复用。*
diff --git a/开发文档/9、手册/写作与结构维护手册.md b/开发文档/9、手册/写作与结构维护手册.md
new file mode 100644
index 00000000..2e096fdc
--- /dev/null
+++ b/开发文档/9、手册/写作与结构维护手册.md
@@ -0,0 +1,43 @@
+# 写作与结构维护手册（Mycontent-book）
+
+## 1. 你改文档，我怎么理解
+
+你只要改这三类文件，我就能按规则做事：
+
+- `external/Mycontent-book/book/**/*.md`：正文内容
+- `external/Mycontent-book/1、soul 全部.txt`：素材源（不要随便改结构）
+- `external/1、开发模板/**`：需求、架构、部署的“标准答案”
+
+## 2. 章节怎么放（目录就是结构）
+
+- “篇”是一级目录
+- “章”是二级目录
+- “小节”是 `.md` 文件
+
+原则：尽量新增，不要频繁移动旧文件。
+
+## 3. 写作动作建议（减少冲突、减少噪音）
+
+- 一次改一篇/一章，写完再切下一个
+- 同一小节尽量集中修改，不要碎片化改一堆次
+
+## 4. 事实与数据怎么处理
+
+- 数值、时间、对话：以素材文件里的原文为准
+- 不确定就不写死，先把“素材引用段落”留在文档里
+
+## 5. 自动同步的最佳姿势
+
+- 开始写作前启动：`./scripts/autosync.sh`
+- 写作时正常保存即可
+- 停止同步：`Ctrl+C`
+
+## 6. 你想改规则怎么改
+
+你直接改开发模板里的对应文档：
+
+- 要改目标/范围：改 `1、需求/业务需求.md`
+- 要改结构/同步策略：改 `2、架构/系统架构.md` 或 `8、部署/自动同步与分支策略.md`
+- 要改跑站点方式：改 `8、部署/本地运行.md`
+
+我会按你最新文档执行。
diff --git a/开发文档/9、手册/手册索引.md b/开发文档/9、手册/手册索引.md
new file mode 100644
index 00000000..c17610bb
--- /dev/null
+++ b/开发文档/9、手册/手册索引.md
@@ -0,0 +1,26 @@
+# 手册与提示词索引
+
+> 本目录下所有手册与 AI 提示词统一入口。
+
+---
+
+## 手册
+
+| 文件 | 说明 |
+|:---|:---|
+| [写作与结构维护手册](./写作与结构维护手册.md) | 书籍写作与结构维护规范 |
+| [全站捆绑分销体系-SCALE](./全站捆绑分销体系-SCALE.md) | 30天捆绑+分销可复用规格，可套用到其他网站/小程序 |
+
+## 提示词（AI 协作）
+
+| 文件 | 说明 |
+|:---|:---|
+| [使用手册提示词](./使用手册提示词.md) | **小白操作手册**（卡若 / 技术文档专家角色，主入口） |
+| [提示词/落地方案提示词](./提示词/落地方案提示词.md) | 复盘、营销文章、卡若风格输出 |
+| [提示词/说明手册提示词](./提示词/说明手册提示词.md) | 系统说明、架构、接口、配置文档 |
+| [提示词/截图与Word文档导出工具需求说明](./提示词/截图与Word文档导出工具需求说明.md) | 截图 + Word 导出工具**产品需求**（非手册角色提示词） |
+| [提示词/README](./提示词/README.md) | 提示词子目录说明 |
+
+---
+
+**使用**：将对应 .md 文件拖入 AI 对话框，即可激活对应模板或角色。
diff --git a/开发文档/9、手册/提示词/README.md b/开发文档/9、手册/提示词/README.md
new file mode 100644
index 00000000..e8e4615f
--- /dev/null
+++ b/开发文档/9、手册/提示词/README.md
@@ -0,0 +1,9 @@
+# 9、手册 / 提示词
+
+| 文件 | 说明 |
+|------|------|
+| [落地方案提示词.md](./落地方案提示词.md) | 复盘、营销文章、卡若风格输出 |
+| [说明手册提示词.md](./说明手册提示词.md) | 系统说明、架构、接口、配置类文档 |
+| [截图与Word文档导出工具需求说明.md](./截图与Word文档导出工具需求说明.md) | 截图采集 + Word 导出类工具的产品需求（非手册角色提示词） |
+
+**卡若风格「小白操作手册」AI 角色**：请使用上级目录 [使用手册提示词.md](../使用手册提示词.md)。
diff --git a/开发文档/9、手册/提示词/截图与Word文档导出工具需求说明.md b/开发文档/9、手册/提示词/截图与Word文档导出工具需求说明.md
new file mode 100644
index 00000000..af7ef106
--- /dev/null
+++ b/开发文档/9、手册/提示词/截图与Word文档导出工具需求说明.md
@@ -0,0 +1,17 @@
+# 截图与 Word 文档导出工具需求说明
+
+> 原文件名 `使用手册提示词.md` 易与上级目录「卡若使用手册提示词」混淆，故改名。内容为**独立产品需求描述**，非卡若手册 AI 角色提示词。
+
+在这个应用程序中开发一个实用工具，目录名称为“/documentation”，只能用地址访问不要放到可以点击的地方，用于自动生成一套全面的文档集。
+
+该工具应能捕捉应用程序所有界面的屏幕截图，在文档生成器中使用iframe方式，保证每个页面加载成功的情况下，实现真实的截图功能，而不是使用占位图。
+
+系统应自动整理这些截图，将其与文档的相关部分关联起来。然后，该工具应将这些截图和相关文本汇编成一个可导出的Word文档（.docx）。
+
+Word文档应包含目录、与应用程序功能相对应的清晰标题和副标题，以及每张截图的说明文字。
+
+确保导出过程简化为一键生成，最大限度减少人工干预。
+
+生成的文档应反映所提供示例的结构和内容，融入应用程序的特定功能和特性，处理截图捕获或文档生成过程中的任何潜在错误，以确保准确性和完整性。
+
+最终输出应为适合分发给利益相关者和用户的专业质量文档。
diff --git a/开发文档/9、手册/提示词/落地方案提示词.md b/开发文档/9、手册/提示词/落地方案提示词.md
new file mode 100644
index 00000000..b0bbd29e
--- /dev/null
+++ b/开发文档/9、手册/提示词/落地方案提示词.md
@@ -0,0 +1,32 @@
+# 落地方案提示词
+
+> 用于记录「把需求落到代码/流程」的提示词。拖入 AI 即可按固定模板输出。
+
+---
+
+## 输出格式要求
+
+### 1. 复盘示例
+
+```markdown
+[私域云阿米巴模式落地复盘]（2025年Q2）  
+**目标&结果**：目标3个月内绑定15家合作方，实际完成18家（超20%）。  
+**过程**：5月启动流量测试...；6月上线私域系统...；7月现金分润验证...  
+**反思**：...  
+**总结**：...  
+**执行**：...
+```
+
+### 2. 营销文章结构
+
+- **I（兴趣）**：自问自答引发共鸣。
+- **S（故事/案例）**：真实经历描述。
+- **S（干货）**：可落地的步骤+数据。
+- **M（产品/概念）**：核心模式与优势。
+- **F（裂变）**：行动号召。
+
+### 3. 卡若风格文章要求
+
+- **结构**：自问自答 → 故事/反思（含数据）→ 行动指引。
+- **语言**：简洁直接，挑战传统。
+- **字数**：不低于 2000 字，数据需有据可查。
diff --git a/开发文档/9、手册/提示词/说明手册提示词.md b/开发文档/9、手册/提示词/说明手册提示词.md
new file mode 100644
index 00000000..260f4031
--- /dev/null
+++ b/开发文档/9、手册/提示词/说明手册提示词.md
@@ -0,0 +1,38 @@
+# 说明手册提示词
+
+> 用于记录「对外说明/交付手册」的提示词。面向内部开发、运维、系统管理员。
+
+---
+
+## 核心原则
+
+- **对象**：内部开发、运维、系统管理员。
+- **风格**：专业、严谨、逻辑缜密。
+- **口吻**：客观描述，无情绪色彩。
+
+## 内容结构
+
+### 1. 系统概述
+
+- 系统定位、核心能力、适用场景。
+
+### 2. 架构说明
+
+- **技术栈**：具体版本（如 React 18, Java 17）。
+- **架构图**：引用开发文档中的架构图。
+- **目录结构**：核心目录作用。
+
+### 3. 接口与数据
+
+- **API 规范**：RESTful，统一响应格式。
+- **数据字典**：核心表/集合字段与类型。
+
+### 4. 配置与环境
+
+- **环境变量**：必配 ENV 及含义。
+- **外部依赖**：Redis、第三方 API 等配置要求。
+
+## 格式要求
+
+- **代码块**：命令、配置、JSON 示例用 Markdown 代码块。
+- **表格**：参数说明、状态码用表格。
diff --git a/开发文档/Cunkebao接口文档/API接口清单.md b/开发文档/Cunkebao接口文档/API接口清单.md
new file mode 100644
index 00000000..8ca10c37
--- /dev/null
+++ b/开发文档/Cunkebao接口文档/API接口清单.md
@@ -0,0 +1,376 @@
+# Cunkebao 项目 API 接口清单
+
+> **说明**：Cunkebao 为前端项目，接口由后端提供。  
+> **基础 URL**：`VITE_API_BASE_URL`（默认 `/api`）  
+> **公共请求头**：`Authorization: Bearer {token}`，`Content-Type: application/json`（文件上传除外）
+
+---
+
+## 附录：响应格式约定
+
+| 场景 | 约定 |
+|------|------|
+| 成功 | `{ code: 200, success?: true, data: ..., msg? }` |
+| 401 | 需重新登录，跳转 `/login` |
+| 拦截器 | 返回 `res.data.data ?? res.data`，即优先使用 `data.data` |
+
+---
+
+## 一、认证模块 (Auth)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/auth/login` | POST | `{ username?, password?, phone?, code? }` | 密码登录 |
+| `/v1/auth/login-code` | POST | `{ phone?, code? }` | 验证码登录 |
+| `/v1/auth/code` | POST | `{ phone? }` | 发送验证码 |
+| `/v1/auth/logout` | POST | `{}` | 登出 |
+| `/v1/auth/user-info` | GET | - | 获取用户信息 |
+
+---
+
+## 二、用户与设置
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/user/editUserInfo` | PUT | body: 用户信息对象 | 编辑用户信息 |
+
+---
+
+## 三、仪表盘 / 首页 (Dashboard)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/dashboard` | GET | - | 仪表盘总览 |
+| `/v1/dashboard/device-stats` | GET | - | 设备统计 |
+| `/v1/dashboard/wechat-stats` | GET | - | 微信号统计 |
+| `/v1/dashboard/today-stats` | GET | - | 今日数据统计 |
+| `/v1/dashboard/plan-stats` | GET | query: `{ taskId?, ... }` | 获客场景统计 |
+| `/v1/dashboard/sevenDay-stats` | GET | - | 近 7 天统计 |
+| `/v1/dashboard/userInfoStats` | GET | - | 用户信息统计 |
+| `/v1/dashboard/friendRequestTaskStats` | GET | query: `{ taskId, startTime?, endTime? }` | 好友请求任务统计 |
+
+---
+
+## 四、工作台通用 (Workbench)
+
+> **type 含义**：1=自动点赞 3=群发 5=流量分发 6=通讯录导入
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/list` | GET | query: `{ type?, page?, limit?, keyword?, ... }` | 任务列表 |
+| `/v1/workbench/detail` | GET | query: `{ id }` | 任务详情 |
+| `/v1/workbench/create` | POST | body: `{ ...data, type? }` | 创建任务 |
+| `/v1/workbench/update` | POST | body: `{ ...data, type? }` | 更新任务 |
+| `/v1/workbench/delete` | DELETE | query/body: `{ id }` | 删除任务 |
+| `/v1/workbench/update-status` | POST | body: `{ id, status, type? }` | 更新任务状态 |
+| `/v1/workbench/copy` | POST | body: `{ id }` | 复制任务 |
+| `/v1/workbench/common-functions` | GET | - | 常用功能列表 |
+| `/v1/workbench/account-list` | GET | query: 分页等 | 工作台账号列表 |
+
+---
+
+## 五、自动点赞 (type=1)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/records` | GET | query: 分页、筛选 | 点赞记录 |
+| `/v1/workbench/like-records` | GET | query: 分页、筛选 | 点赞记录（另一实现） |
+
+---
+
+## 六、群发任务 (type=3)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/getJdSocialMedia` | GET | - | 京东社交媒体列表 |
+| `/v1/workbench/getJdPromotionSite` | GET | query: `{ id }` | 京东推广站点列表 |
+| `/v1/workspace/group-push/tasks` | POST | body: 任务数据 | 创建群发任务 |
+| `/v1/workspace/group-push/tasks/:id` | GET | - | 群发任务详情 |
+| `/v1/workspace/group-push/tasks/:id` | PUT | body: 任务数据 | 更新群发任务 |
+| `/v1/workspace/group-push/tasks/:id` | DELETE | - | 删除群发任务 |
+| `/v1/workspace/group-push/tasks/:id/copy` | POST | - | 复制群发任务 |
+
+**群发任务 body 示例**：`FormData`  
+- `name`, `startTime`, `endTime`, `dailyPushCount`, `pushOrder`, `isLoop`, `pushType`, `status`  
+- `contentGroups`, `wechatGroups`  
+- `socialMediaId?`, `promotionSiteId?`（京东联盟）
+
+---
+
+## 七、流量分发 (type=5)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/list?type=5` | GET | query: 分页等 | 流量分发任务列表 |
+| `/v1/workbench/transfer-friends` | GET | query: `{ workbenchId?, page?, limit?, keyword?, isRecycle? }` | 好友转移/分发记录 |
+
+---
+
+## 八、通讯录导入 (type=6)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/import-records` | GET | query: `{ workbenchId, page, limit, keyword? }` | 导入记录 |
+| `/v1/workbench/import-stats` | GET | - | 导入统计 |
+| `/v1/workbench/trigger-import` | POST | body: `{ taskId }` | 手动触发导入 |
+| `/v1/workbench/batch-operate` | POST | body: `{ taskIds, operation }` | 批量操作（start/stop/delete） |
+
+**创建通讯录导入任务 body 示例**：
+
+```ts
+{
+  name: string;
+  type: number; // 6
+  config: {
+    devices: number[];
+    poolGroups: number[];
+    num: number;
+    clearContact: number;
+    remarkType: number;
+    remark: string;
+    startTime: string;
+    endTime: string;
+  };
+}
+```
+
+---
+
+## 九、自动建群 / 群管理
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/created-groups-list` | GET | query: `{ workbenchId, page?, limit?, keyword? }` | 已建群列表 |
+| `/v1/workbench/created-group-detail` | GET | query: `{ workbenchId, groupId }` | 群详情 |
+| `/v1/workbench/sync-group-info` | POST | body: `{ workbenchId, groupId }` | 同步群信息 |
+| `/v1/workbench/modify-group-info` | POST | body: `{ workbenchId, groupId, chatroomName?, announce? }` | 修改群名称/公告 |
+| `/v1/workbench/quit-group` | POST | body: `{ workbenchId, groupId }` | 退出群 |
+| `/api/auto-group/detail/:id` | GET | - | 自动建群详情（备用） |
+
+---
+
+## 十、朋友圈同步 (type=1)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/workbench/moments-records` | GET | query: 分页、筛选 | 朋友圈同步记录 |
+
+---
+
+## 十一、设备 (Devices)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/devices` | GET | query: `{ page?, limit?, keyword? }` | 设备列表 |
+| `/v1/devices/:id` | GET | - | 设备详情 |
+| `/v1/devices/:id` | DELETE | - | 删除设备 |
+| `/v1/devices/:id/handle-logs` | GET | query: `{ page, limit }` | 设备操作日志 |
+| `/v1/devices/task-config` | POST | body: `{ deviceId, autoAddFriend?, autoReply?, momentsSync?, aiChat? }` | 更新任务配置 |
+| `/v1/device/groups` | GET | - | 设备组列表 |
+| `/v1/api/device/add` | POST | body: `{ accountId }` | 获取设备二维码 |
+| `/v1/api/device/add-by-imei` | POST | body: `{ imei, name }` | 通过 IMEI 添加设备 |
+| `/v1/devices/add-results` | GET | query: `{ accountId? }` | 设备添加结果（轮询） |
+| `/v1/wechats/related-device/:id` | GET | - | 设备关联微信账号 |
+
+---
+
+## 十二、微信号 / 微信账号 (Wechats)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/wechats` | GET | query: 分页等 | 微信号列表 |
+| `/v1/WechatAccount/detail` | GET | query: `{ id }` | 微信账号详情 |
+| `/v1/wechats/getWechatInfo` | GET | query: `{ wechatId }` | 微信信息 |
+| `/v1/wechats/overview` | GET | query: `{ wechatId }` | 概览 |
+| `/v1/wechats/moments` | GET | query: 分页等 | 朋友圈列表 |
+| `/v1/wechats/moments/export` | GET | query: `{ wechatId?, startTime?, endTime? }` | 朋友圈导出（blob） |
+| `/v1/wechats/transfer-friends` | POST | body: 参数对象 | 好友转移 |
+| `/v1/WechatFriend/friendlistData` | POST | body: 参数对象 | 好友列表 |
+| `/v1/WechatFriend/detail` | GET | query: `{ id }` | 好友详情 |
+| `/v1/friend/transfer` | POST | body: 参数对象 | 好友转移（另一实现） |
+| `/v1/friend` | GET | query: 分页等 | 好友列表 |
+
+---
+
+## 十三、客服 / 群成员 (Kefu)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/kefu/wechatChatroom/members` | GET | query: `{ groupId, page?, limit?, keyword? }` | 群成员列表 |
+| `/v1/kefu/accounts/list` | GET | - | 客服账号列表 |
+
+---
+
+## 十四、聊天群 (Chatroom)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/chatroom` | GET | query: 分页等 | 聊天群列表 |
+
+---
+
+## 十五、内容库 (Content Library)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/content/library/list` | GET | query: `{ page?, limit?, keyword?, formType:0 }` | 内容库列表 |
+| `/v1/content/library/detail` | GET | query: `{ id }` | 内容库详情 |
+| `/v1/content/library/create` | POST | body: `{ ...params, formType:0 }` | 创建内容库 |
+| `/v1/content/library/update` | POST | body: `{ id, ...data }` | 更新内容库 |
+| `/v1/content/library/delete` | DELETE | query/body: `{ id }` | 删除内容库 |
+| `/v1/content/library/update-status` | POST | body: `{ id, status }` | 更新内容库状态 |
+| `/v1/content/library/item-list` | GET | query: 分页、筛选 | 素材列表 |
+| `/v1/content/library/get-item-detail` | GET | query: `{ id }` | 素材详情（一种实现） |
+| `/v1/content/item/detail` | GET | query: `{ id }` | 素材详情（另一种实现） |
+| `/v1/content/library/create-item` | POST | body: 素材数据 | 创建素材 |
+| `/v1/content/item/create` | POST | body: 素材数据 | 创建素材（另一种实现） |
+| `/v1/content/library/update-item` | POST | body: 素材数据 | 更新素材 |
+| `/v1/content/item/update` | POST | body: `{ id, ...data }` | 更新素材（另一种实现） |
+| `/v1/content/library/delete-item` | DELETE | query/body: `{ id }` | 删除素材 |
+| `/v1/content/library/aiEditContent` | GET | query: AI 改写参数 | AI 改写（GET） |
+| `/v1/content/library/aiEditContent` | POST | body: 替换参数 | AI 替换（POST） |
+| `/v1/content/library/import-excel` | POST | body: `{ id, fileUrl }` | 导入 Excel 素材 |
+
+---
+
+## 十六、知识库 (Knowledge / AI)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/knowledge/init` | GET | - | 初始化 AI 功能 |
+| `/v1/knowledge/release` | GET | query: `{ id }` | 发布并应用 |
+| `/v1/knowledge/updateTypeStatus` | PUT | body: `{ id, status }` | 更新类型状态 |
+| `/v1/knowledge/typeList` | GET | query: `{ page?, limit?, keyword? }` | 知识库类型列表 |
+| `/v1/knowledge/addType` | POST | body: `{ name, description, label, prompt }` | 创建类型 |
+| `/v1/knowledge/editType` | POST | body: `{ id, name, description, label, prompt }` | 编辑类型 |
+| `/v1/knowledge/deleteType` | DELETE | query/body: `{ id }` | 删除类型 |
+| `/v1/knowledge/savePrompt` | POST | body: `{ promptInfo }` | 保存统一提示词 |
+| `/v1/knowledge/getList` | GET | query: `{ typeId, name?, label?, page?, limit? }` | 知识库素材列表 |
+| `/v1/knowledge/add` | POST | body: `{ typeId, name, label, fileUrl }` | 添加素材 |
+| `/v1/knowledge/delete` | DELETE | query/body: `{ id }` | 删除素材 |
+
+---
+
+## 十七、流量池 (Traffic Pool)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/traffic/pool` | GET | query: `{ page?, pageSize?, keyword?, addStatus?, deviceId?, packageId?, userValue? }` | 流量池列表 |
+| `/v1/traffic/pool/create` | POST | body: `{ name, description?, remarks?, filterConditions, userIds }` | 创建流量包 |
+| `/v1/traffic/pool/users/filter` | POST | body: `{ conditions, page?, pageSize? }` | 按条件筛选用户 |
+| `/v1/traffic/pool/users` | GET | query: 分页等 | 流量池用户列表 |
+| `/v1/traffic/pool/getPackage` | GET | query: `{ keyword?, limit?, page? }` | 流量池套餐列表 |
+| `/v1/traffic/pool/industries` | GET | - | 行业选项 |
+| `/v1/traffic/pool/addPackage` | POST | body: `{ type, addPackageId?, deviceId?, keyword?, packageId?, ... }` | 添加套餐 |
+
+---
+
+## 十八、算力 / 充值 (Tokens / Power / Recharge)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/tokens/statistics` | GET | - | 算力统计 |
+| `/v1/tokens/list` | GET | - | 套餐列表 |
+| `/v1/tokens/pay` | POST | body: `{ id?, price?, orderNo? }` | 购买/继续支付 |
+| `/v1/tokens/queryOrder` | GET | query: `{ orderNo }` | 查询订单状态 |
+| `/v1/tokens/orderList` | GET | query: `{ page?, limit?, keyword?, orderType?, status? }` | 订单列表 |
+| `/v1/tokens/allocate` | POST | body: `{ targetUserId, tokens, remarks? }` | 分配算力 |
+| `/v1/power/stats` | GET | - | 算力统计 |
+| `/v1/power/consumption-records` | GET | query: `{ page?, limit?, type?, status? }` | 消费记录 |
+| `/v1/power/buy-custom` | POST | body: `{ amount }` | 自定义购买算力 |
+| `/v1/kefu/tokensRecord/list` | GET | query: `{ page?, limit?, form?, type? }` | 算力使用明细（客服） |
+
+---
+
+## 十九、分销 (Distribution)
+
+### 管理端
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/distribution/channels/statistics` | GET | - | 渠道统计 |
+| `/v1/distribution/channels` | GET | query: `{ page?, limit?, keyword?, status? }` | 渠道列表 |
+| `/v1/distribution/channel` | POST | body: `{ name, phone?, wechatId?, remarks? }` | 创建渠道 |
+| `/v1/distribution/channel/:id` | PUT | body: 渠道信息 | 更新渠道 |
+| `/v1/distribution/channel/:id` | DELETE | - | 删除渠道 |
+| `/v1/distribution/channel/:id/status` | PUT | body: `{ status }` | 启用/禁用渠道 |
+| `/v1/distribution/channels/revenue-statistics` | GET | - | 资金统计 |
+| `/v1/distribution/channels/revenue-detail` | GET | query: `{ page?, limit?, keyword? }` | 渠道收益明细 |
+| `/v1/distribution/withdrawals` | GET | query: `{ page?, limit?, status?, date?, keyword? }` | 提现列表 |
+| `/v1/distribution/withdrawals/:id/review` | POST | body: `{ action, remark? }` | 审核提现 |
+| `/v1/distribution/withdrawals/:id/mark-paid` | POST | body: `{ payType, remark? }` | 标记已打款 |
+| `/v1/distribution/channel/generate-qrcode` | POST | body: `{ type }` | 生成渠道扫码二维码 |
+| `/v1/distribution/channel/generate-login-qrcode` | POST | body: `{ type? }` | 生成渠道登录二维码 |
+
+### 渠道端（前端）
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/frontend/distribution/user/home` | GET | query: `{ channelCode }` | 渠道首页 |
+| `/v1/frontend/distribution/user/revenue-records` | GET | query: `{ channelCode, page?, limit?, filterType?, date? }` | 收益记录 |
+| `/v1/frontend/distribution/user/withdrawal-records` | GET | query: `{ channelCode, page?, limit?, status?, payType?, date? }` | 提现记录 |
+
+---
+
+## 二十、场景与计划 (Scenarios / Plan)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/plan/scenes` | GET | query: 筛选参数 | 场景类型列表 |
+| `/v1/scenarios` | POST | body: 场景数据 | 创建场景 |
+| `/v1/scenarios/:id` | GET | - | 场景详情 |
+| `/v1/scenarios/:id` | PUT | body: 场景数据 | 更新场景 |
+| `/v1/scenarios/:id` | DELETE | - | 删除场景 |
+| `/v1/plan/list` | GET | query: `{ sceneId, page, limit }` | 计划列表 |
+| `/v1/plan/detail` | GET | query: `{ planId }` | 计划详情 |
+| `/v1/plan/create` | POST | body: 计划数据 | 创建计划 |
+| `/v1/plan/update` | PUT | body: 计划数据 | 更新计划 |
+| `/v1/plan/copy` | GET | query: `{ planId }` | 复制计划 |
+| `/v1/plan/delete` | DELETE | query: `{ planId }` | 删除计划 |
+| `/v1/plan/getWxMinAppCode` | GET | query: `{ taskId?, channelId?, channelCode? }` | 获取小程序码 |
+| `/v1/plan/getUserList` | GET | query: `{ planId, type }` | 获客用户列表 |
+
+---
+
+## 二十一、文件上传 (Upload)
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `/v1/attachment/upload` | POST | body: FormData，字段 `file` | 通用文件上传 |
+
+---
+
+## 二十二、触客宝（独立 request2）
+
+| 接口路径 | HTTP | 入参 | 说明 |
+|---------|------|------|------|
+| `{VITE_API_BASE_URL2}/token` | POST | FormData: `username`, `password` 等 | 触客宝登录 |
+| `{VITE_API_BASE_URL2}/api/account/self` | GET | - | 触客宝用户信息 |
+
+---
+
+## 二十三、备用/兼容接口（step.api.ts `/api` 前缀）
+
+> 可能为 mock 或兼容实现，实际使用以 `/v1` 为准。
+
+| 接口路径 | HTTP | 说明 |
+|---------|------|------|
+| `/api/scenarios/:id/plans` | GET | 计划列表 |
+| `/api/scenarios/plans/:id/copy` | POST | 复制计划 |
+| `/api/scenarios/plans/:id` | DELETE | 删除计划 |
+| `/api/scenarios/plans/:id/qrcode` | GET | 计划二维码 |
+| `/api/devices` | GET/POST | 设备列表/创建 |
+| `/api/devices/:id` | GET/PUT/DELETE | 设备增删改查 |
+| `/api/wechat-accounts` | GET/POST | 微信号列表/创建 |
+| `/api/wechat-accounts/:id` | GET/PUT/DELETE | 微信号增删改查 |
+| `/api/posters` | GET/POST | 海报列表/创建 |
+| `/api/posters/:id` | GET/PUT/DELETE | 海报增删改查 |
+| `/api/contents` | GET/POST | 内容列表/创建 |
+| `/api/contents/:id` | GET/PUT/DELETE | 内容增删改查 |
+| `/api/traffic-pools` | GET/POST | 流量池列表/创建 |
+| `/api/traffic-pools/:id` | GET/PUT/DELETE | 流量池增删改查 |
+| `/api/workspace/*` | 多种 | 工作台相关 |
+| `/api/orders` | 多种 | 订单相关 |
+| `/api/user/*` | 多种 | 用户相关 |
+| `/api/upload/*` | POST | 上传相关 |
+| `/api/system/*` | GET/PUT | 系统配置 |
diff --git a/开发文档/Cunkebao接口文档/README.md b/开发文档/Cunkebao接口文档/README.md
new file mode 100644
index 00000000..7f475e49
--- /dev/null
+++ b/开发文档/Cunkebao接口文档/README.md
@@ -0,0 +1,26 @@
+# Cunkebao 存客宝 - 接口文档目录
+
+> 整理时间：2026-03-19  
+> 说明：Cunkebao 为前端项目，接口由后端提供。基础 URL 来自 `VITE_API_BASE_URL`（默认 `/api`）。
+
+## 公共约定
+
+- **请求头**：`Authorization: Bearer {token}`，`Content-Type: application/json`（文件上传除外）
+- **响应格式**：`{ code: 200, success?: true, data: ..., msg? }`
+- **401**：需重新登录，跳转 `/login`
+
+## 文档列表
+
+| 文档 | 说明 |
+|------|------|
+| [API接口清单](API接口清单.md) | 全部接口路径、方法、入参与简要说明 |
+| [入参出参结构](入参出参结构.md) | 核心模块的请求/响应参数结构（含 TypeScript 类型） |
+
+## 工作台 type 含义
+
+| type | 模块 |
+|------|------|
+| 1 | 自动点赞 / 朋友圈同步 |
+| 3 | 群发任务 |
+| 5 | 流量分发 |
+| 6 | 通讯录导入 |
diff --git a/开发文档/Cunkebao接口文档/入参出参结构.md b/开发文档/Cunkebao接口文档/入参出参结构.md
new file mode 100644
index 00000000..d719c522
--- /dev/null
+++ b/开发文档/Cunkebao接口文档/入参出参结构.md
@@ -0,0 +1,530 @@
+# Cunkebao 入参 / 出参结构说明
+
+> 基于前端调用整理，后端实际实现可能略有差异。以实际对接为准。
+
+---
+
+## 一、公共请求
+
+### 1.1 请求头
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `Authorization` | 是 | `Bearer {token}`，登录后返回 |
+| `Content-Type` | 视情况 | `application/json`（JSON 请求）；FormData 上传时由浏览器自动设置 |
+
+### 1.2 分页参数（query 通用）
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `page` | number | 页码，从 1 开始 |
+| `limit` | number | 每页条数 |
+| `pageSize` | number | 部分接口使用，等同 limit |
+
+### 1.3 通用响应格式
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "msg": "成功",
+  "data": { /* 业务数据 */ }
+}
+```
+
+- 成功：`code === 200` 或 `success === true`
+- 401：需重新登录，跳转 `/login`
+- 前端拦截器：返回 `res.data.data ?? res.data`，优先取 `data.data`
+
+---
+
+## 二、认证模块 (Auth)
+
+### 2.1 密码登录 POST `/v1/auth/login`
+
+**请求 body：**
+```json
+{
+  "username": "string",  // 用户名（可选）
+  "password": "string"   // 密码（可选）
+}
+```
+
+### 2.2 验证码登录 POST `/v1/auth/login-code`
+
+**请求 body：**
+```json
+{
+  "phone": "string",   // 手机号
+  "code": "string"      // 验证码
+}
+```
+
+### 2.3 发送验证码 POST `/v1/auth/code`
+
+**请求 body：**
+```json
+{
+  "phone": "string"   // 手机号
+}
+```
+
+### 2.4 获取用户信息 GET `/v1/auth/user-info`
+
+无请求参数。
+
+---
+
+## 三、工作台 (Workbench)
+
+### 3.1 任务通用类型 type
+
+| 值 | 含义 |
+|----|------|
+| 1 | 自动点赞 |
+| 3 | 群发 |
+| 5 | 流量分发 |
+| 6 | 通讯录导入 |
+
+### 3.2 任务列表 GET `/v1/workbench/list`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| type | number | 否 | 任务类型 1/3/5/6 |
+| page | number | 否 | 页码 |
+| limit | number | 否 | 每页条数 |
+| keyword | string | 否 | 关键词搜索 |
+
+### 3.3 任务详情 GET `/v1/workbench/detail`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | string | 是 | 任务 ID |
+
+### 3.4 创建任务 POST `/v1/workbench/create`
+
+**Body：** 根据 type 不同结构不同，通用字段：
+- `type`: number
+- `name`: string
+- `config`: object（任务配置）
+
+### 3.5 更新任务 POST `/v1/workbench/update`
+
+**Body：** 同上，需包含 `id` 或任务标识。
+
+### 3.6 删除任务 DELETE `/v1/workbench/delete`
+
+**Query/Body：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | string | 是 | 任务 ID |
+
+### 3.7 更新任务状态 POST `/v1/workbench/update-status`
+
+**Body：**
+```json
+{
+  "id": "string",
+  "status": number,   // 0 关闭 1 开启
+  "type": number      // 可选，任务类型
+}
+```
+
+### 3.8 复制任务 POST `/v1/workbench/copy`
+
+**Body：**
+```json
+{
+  "id": "string"
+}
+```
+
+---
+
+## 四、通讯录导入 (type=6)
+
+### 4.1 通讯录导入任务配置 CreateContactImportTaskData
+
+**POST 创建任务：**
+```json
+{
+  "name": "string",
+  "type": 6,
+  "config": {
+    "devices": [1, 2],
+    "poolGroups": [1, 2],
+    "num": 100,
+    "clearContact": 0,
+    "remarkType": 0,
+    "remark": "",
+    "startTime": "09:00",
+    "endTime": "18:00"
+  }
+}
+```
+
+### 4.2 导入记录 GET `/v1/workbench/import-records`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| workbenchId | string | 是 | 工作台任务 ID |
+| page | number | 是 | 页码 |
+| limit | number | 是 | 每页条数 |
+| keyword | string | 否 | 关键词 |
+
+### 4.3 批量操作 POST `/v1/workbench/batch-operate`
+
+**Body：**
+```json
+{
+  "taskIds": ["string"],
+  "operation": "start" | "stop" | "delete"
+}
+```
+
+---
+
+## 五、流量分发 (type=5)
+
+### 5.1 好友转移/分发记录 GET `/v1/workbench/transfer-friends`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| workbenchId | string | 否 | 工作台 ID |
+| page | number | 否 | 页码 |
+| limit | number | 否 | 每页条数 |
+| keyword | string | 否 | 关键词 |
+| isRecycle | boolean | 否 | 是否回收站 |
+
+---
+
+## 六、群发 (type=3)
+
+### 6.1 群发任务表单 FormData
+
+```typescript
+{
+  name: string;
+  startTime: string;      // 允许推送开始时间
+  endTime: string;       // 允许推送结束时间
+  dailyPushCount: number;
+  pushOrder: number;     // 1: 按最早, 2: 按最新
+  isLoop: number;        // 0: 否, 1: 是
+  pushType: number;      // 0: 定时, 1: 立即
+  status: number;        // 0: 否, 1: 是
+  contentGroups: string[];
+  wechatGroups: string[];
+  socialMediaId?: string;   // 京东联盟
+  promotionSiteId?: string;
+}
+```
+
+### 6.2 创建群发任务 POST `/v1/workspace/group-push/tasks`
+
+**Body：** 群发任务对象（同上结构）。
+
+### 6.3 更新群发任务 PUT `/v1/workspace/group-push/tasks/:id`
+
+**Body：** 同上。
+
+### 6.4 复制群发任务 POST `/v1/workspace/group-push/tasks/:id/copy`
+
+无 body。
+
+---
+
+## 七、流量池 (Traffic Pool)
+
+### 7.1 流量池列表 GET `/v1/traffic/pool`
+
+**Query：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| page | number | 页码 |
+| pageSize | number | 每页条数 |
+| keyword | string | 关键词 |
+| addStatus | string | 添加状态 |
+| deviceId | string | 设备 ID |
+| packageId | string | 套餐 ID |
+| userValue | string | 用户价值：all/high/medium/low |
+
+### 7.2 创建流量包 POST `/v1/traffic/pool/create`
+
+**Body：**
+```json
+{
+  "name": "string",
+  "description": "string",
+  "remarks": "string",
+  "filterConditions": {},
+  "userIds": []
+}
+```
+
+### 7.3 按条件筛选用户 POST `/v1/traffic/pool/users/filter`
+
+**Body：**
+```json
+{
+  "conditions": {},
+  "page": number,
+  "pageSize": number
+}
+```
+
+### 7.4 添加套餐 POST `/v1/traffic/pool/addPackage`
+
+**Body：** 含 `type`、`addPackageId`、`deviceId`、`keyword`、`packageId` 等。
+
+---
+
+## 八、内容库 (Content Library)
+
+### 8.1 内容库列表 GET `/v1/content/library/list`
+
+**Query：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| page | number | 页码 |
+| limit | number | 每页条数 |
+| keyword | string | 关键词 |
+| formType | number | 固定 0 |
+
+### 8.2 创建内容库 POST `/v1/content/library/create`
+
+**Body：** `{ ...params, formType: 0 }`
+
+### 8.3 创建素材 POST `/v1/content/library/create-item` 或 `/v1/content/item/create`
+
+**Body：** 素材对象（文本、图片、视频等）。
+
+### 8.4 AI 改写 GET `/v1/content/library/aiEditContent`
+
+**Query：** AI 改写相关参数。
+
+### 8.5 导入 Excel POST `/v1/content/library/import-excel`
+
+**Body：**
+```json
+{
+  "id": "string",
+  "fileUrl": "string"
+}
+```
+
+---
+
+## 九、设备 (Devices)
+
+### 9.1 设备列表 GET `/v1/devices`
+
+**Query：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| page | number | 页码 |
+| limit | number | 每页条数 |
+| keyword | string | 关键词 |
+
+### 9.2 更新任务配置 POST `/v1/devices/task-config`
+
+**Body：**
+```json
+{
+  "deviceId": "string",
+  "autoAddFriend": boolean,
+  "autoReply": boolean,
+  "momentsSync": boolean,
+  "aiChat": boolean
+}
+```
+
+### 9.3 获取设备二维码 POST `/v1/api/device/add`
+
+**Body：**
+```json
+{
+  "accountId": "string"
+}
+```
+
+### 9.4 通过 IMEI 添加 POST `/v1/api/device/add-by-imei`
+
+**Body：**
+```json
+{
+  "imei": "string",
+  "name": "string"
+}
+```
+
+---
+
+## 十、算力 / 充值 (Tokens)
+
+### 10.1 购买/支付 POST `/v1/tokens/pay`
+
+**Body：**
+```json
+{
+  "id": "string",
+  "price": number,
+  "orderNo": "string"
+}
+```
+
+### 10.2 查询订单 GET `/v1/tokens/queryOrder`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| orderNo | string | 是 | 订单号 |
+
+### 10.3 订单列表 GET `/v1/tokens/orderList`
+
+**Query：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| page | number | 页码 |
+| limit | number | 每页条数 |
+| keyword | string | 关键词 |
+| orderType | string | 订单类型 |
+| status | string | 状态 |
+
+### 10.4 分配算力 POST `/v1/tokens/allocate`
+
+**Body：**
+```json
+{
+  "targetUserId": "string",
+  "tokens": number,
+  "remarks": "string"
+}
+```
+
+### 10.5 自定义购买算力 POST `/v1/power/buy-custom`
+
+**Body：**
+```json
+{
+  "amount": number
+}
+```
+
+---
+
+## 十一、知识库 / AI
+
+### 11.1 创建类型 POST `/v1/knowledge/addType`
+
+**Body：**
+```json
+{
+  "name": "string",
+  "description": "string",
+  "label": "string",
+  "prompt": "string"
+}
+```
+
+### 11.2 添加素材 POST `/v1/knowledge/add`
+
+**Body：**
+```json
+{
+  "typeId": "string",
+  "name": "string",
+  "label": "string",
+  "fileUrl": "string"
+}
+```
+
+### 11.3 知识库列表 GET `/v1/knowledge/getList`
+
+**Query：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| typeId | string | 类型 ID |
+| name | string | 名称 |
+| label | string | 标签 |
+| page | number | 页码 |
+| limit | number | 每页条数 |
+
+---
+
+## 十二、场景与计划 (Scenarios / Plan)
+
+### 12.1 计划列表 GET `/v1/plan/list`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| sceneId | string | 是 | 场景 ID |
+| page | number | 是 | 页码 |
+| limit | number | 是 | 每页条数 |
+
+### 12.2 计划详情 GET `/v1/plan/detail`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| planId | string | 是 | 计划 ID |
+
+### 12.3 获客用户列表 GET `/v1/plan/getUserList`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| planId | string | 是 | 计划 ID |
+| type | string | 是 | 类型 |
+
+### 12.4 好友请求任务统计 GET `/v1/dashboard/friendRequestTaskStats`
+
+**Query：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| taskId | string | 是 | 任务 ID |
+| startTime | string | 否 | 开始时间 |
+| endTime | string | 否 | 结束时间 |
+
+---
+
+## 十三、分销 (Distribution)
+
+### 13.1 创建渠道 POST `/v1/distribution/channel`
+
+**Body：**
+```json
+{
+  "name": "string",
+  "phone": "string",
+  "wechatId": "string",
+  "remarks": "string"
+}
+```
+
+### 13.2 渠道端收益记录 GET `/v1/frontend/distribution/user/revenue-records`
+
+**Query：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| channelCode | string | 渠道码 |
+| page | number | 页码 |
+| limit | number | 每页条数 |
+| filterType | string | 筛选类型 |
+| date | string | 日期 |
+
+---
+
+## 十四、文件上传
+
+### 14.1 通用上传 POST `/v1/attachment/upload`
+
+**Body：** `FormData`，字段名 `file`。
+
+---
+
+*文档维护：基于 Cunkebao 前端 `src/` 下 api 调用与 data 类型整理，后续若有后端 swagger/openapi 可做对照更新。*
diff --git a/开发文档/SKILL.md b/开发文档/SKILL.md
new file mode 100644
index 00000000..5a69fb92
--- /dev/null
+++ b/开发文档/SKILL.md
@@ -0,0 +1,84 @@
+# Soul创业派对 - 项目开发SKILL
+
+## 项目概述
+
+| 项目 | 值 |
+|------|-----|
+| 项目名 | Soul创业派对（一场Soul的创业实验） |
+| 小程序AppID | wxb8bbb2b10dec74aa |
+| 后端地址 | https://soul.quwanzhi.com |
+| 技术栈(前端) | 微信小程序原生 + 自定义TabBar |
+| 技术栈(后端) | Next.js App Router + MySQL |
+| 数据库 | 腾讯云MySQL |
+| 仓库 | github.com/fnvtk/Mycontent (yongpxu-soul分支) |
+
+## 开发文档目录索引
+
+```
+开发文档/
+├── 1、需求/        ← 需求文档、需求日志、TDD方案
+├── 2、架构/        ← 系统架构、技术选型、链路说明
+├── 3、原型/        ← 原型设计
+├── 4、前端/        ← 前端架构、UI截图
+├── 5、接口/        ← API接口文档、接口定义规范
+├── 6、后端/        ← 后端架构、修复说明
+├── 7、数据库/      ← 数据库设计、管理规范
+├── 8、部署/        ← 部署流程、宝塔配置、小程序上传
+├── 9、手册/        ← 使用手册、写作手册
+├── 10、项目管理/   ← 项目总览、运营报表、会议记录
+├── 小程序管理/     ← 小程序生命周期SKILL（独立）
+└── 服务器管理/     ← 服务器运维SKILL（独立）
+```
+
+## 需求日志管理规范
+
+- 每次对话的需求自动追加到 `1、需求/需求日志.md`
+- 格式：`| 日期 | 需求描述 | 状态 | 备注 |`
+- 状态：待开发 / 开发中 / 已完成 / 已取消
+- 每个版本上传后，将该批需求标记为「已完成」
+
+## 常用命令
+
+### 上传小程序
+```bash
+/Applications/wechatwebdevtools.app/Contents/MacOS/cli upload \
+  --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" \
+  --version "版本号" --desc "版本说明"
+```
+
+### 从GitHub同步miniprogram
+```bash
+cd /tmp && rm -rf Mycontent_soul_tmp
+git clone --depth 1 --branch yongpxu-soul https://github.com/fnvtk/Mycontent.git Mycontent_soul_tmp
+rsync -av --delete Mycontent_soul_tmp/miniprogram/ "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram/"
+rm -rf Mycontent_soul_tmp
+```
+
+### 数据库迁移
+```bash
+curl -X POST https://soul.quwanzhi.com/api/db/migrate -H 'Content-Type: application/json' -d '{}'
+```
+
+## 核心页面结构
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 首页 | pages/index/index | 精选推荐(阅读量)、创业老板排行 |
+| 目录 | pages/chapters/chapters | 章节列表 |
+| 找伙伴 | pages/match/match | 匹配动画 |
+| 我的 | pages/my/my | 用户信息、收益、VIP、账号设置 |
+| 阅读 | pages/read/read | 章节内容、付费墙 |
+| VIP | pages/vip/vip | VIP权益、购买、资料填写 |
+| 会员详情 | pages/member-detail/member-detail | 创业老板排行点击详情 |
+
+## 后端API模块
+
+| 模块 | 路径前缀 | 说明 |
+|------|---------|------|
+| VIP会员 | /api/vip/ | purchase、status、profile、members |
+| 书籍 | /api/book/ | chapters、hot、latest-chapters、search |
+| 用户 | /api/user/ | profile、update、track |
+| 支付 | /api/miniprogram/pay | 微信小程序支付 |
+| 推广 | /api/referral/ | bind、data、visit |
+| 提现 | /api/withdraw | 提现到微信零钱 |
+| 管理后台 | /api/admin/ | content、chapters、payment等 |
diff --git a/开发文档/api_v1.md b/开发文档/api_v1.md
new file mode 100644
index 00000000..50dbd72b
--- /dev/null
+++ b/开发文档/api_v1.md
@@ -0,0 +1,417 @@
+# 对外获客线索上报接口文档（V1）
+
+> **文档归属**：存客宝（第三方）**对外获客线索上报** OpenAPI 说明，**不是** Soul 小程序 / 管理端调用的 `/api/*` 文档。  
+> **Soul 全站 API 真源**：[5、接口/API接口完整文档.md](./5、接口/API接口完整文档.md)。  
+> **存客宝前端**调自家后端：[Cunkebao接口文档/README.md](./Cunkebao接口文档/README.md)。
+
+## 一、接口概述
+
+- **接口名称**：对外获客线索上报接口  
+- **接口用途**：供第三方系统向【存客宝】上报客户线索（手机号 / 微信号等），用于后续的跟进、标签管理和画像分析。  
+- **接口协议**：HTTP  
+- **请求方式**：`POST`  
+- **请求地址**： `https://ckbapi.quwanzhi.com/v1/api/scenarios`  
+
+> 具体 URL 以实际环境配置为准。
+
+- **数据格式**：
+  - 推荐：`application/json`
+  - 兼容：`application/x-www-form-urlencoded`
+- **字符编码**：`UTF-8`
+
+---
+
+## 二、鉴权与签名
+
+### 2.1 必填鉴权字段
+
+| 字段名      | 类型   | 必填 | 说明                                  |
+|-------------|--------|------|---------------------------------------|
+| `apiKey`    | string | 是   | 分配给第三方的接口密钥（每个任务唯一）|
+| `sign`      | string | 是   | 签名值                                |
+| `timestamp` | int    | 是   | 秒级时间戳（与服务器时间差不超过 5 分钟） |
+
+### 2.2 时间戳校验
+
+服务器会校验 `timestamp` 是否在当前时间前后 **5 分钟** 内：
+
+- 通过条件：`|server_time - timestamp| <= 300`
+- 超出范围则返回：`请求已过期`
+
+### 2.3 签名生成规则
+
+接口采用自定义签名机制。**签名字段为 `sign`，生成步骤如下：**
+
+假设本次请求的所有参数为 `params`，其中包括业务参数 + `apiKey` + `timestamp` + `sign` + 可能存在的 `portrait` 对象。
+
+#### 第一步：移除特定字段
+
+从 `params` 中移除以下字段：
+
+- `sign` —— 自身不参与签名  
+- `apiKey` —— 不参与参数拼接，仅在最后一步参与二次 MD5  
+- `portrait` —— 整个画像对象不参与签名（即使内部还有子字段）
+
+> 说明：`portrait` 通常是一个 JSON 对象，字段较多，为避免签名实现复杂且双方难以对齐，统一不参与签名。
+
+#### 第二步：移除空值字段
+
+从剩余参数中，移除值为：
+
+- `null`
+- 空字符串 `''`
+
+的字段，这些字段不参与签名。
+
+#### 第三步：按参数名升序排序
+
+对剩余参数按**参数名（键名）升序排序**，排序规则为标准的 ASCII 升序：
+
+```text
+例如： name, phone, source, timestamp
+```
+
+#### 第四步：拼接参数值
+
+将排序后的参数 **只取“值”**，按顺序直接拼接为一个字符串，中间不加任何分隔符：
+
+- 示例：  
+  排序后参数为：
+
+  ```text
+  name      = 张三
+  phone     = 13800000000
+  source    = 微信广告
+  timestamp = 1710000000
+  ```
+
+  则拼接：
+
+  ```text
+  stringToSign = "张三13800000000微信广告1710000000"
+  ```
+
+#### 第五步：第一次 MD5
+
+对上一步拼接得到的字符串做一次 MD5：
+
+\[
+\text{firstMd5} = \text{MD5}(\text{stringToSign})
+\]
+
+#### 第六步：拼接 apiKey 再次 MD5
+
+将第一步的结果与 `apiKey` 直接拼接，再做一次 MD5，得到最终签名值：
+
+\[
+\text{sign} = \text{MD5}(\text{firstMd5} + \text{apiKey})
+\]
+
+#### 第七步：放入请求
+
+将第六步得到的 `sign` 填入请求参数中的 `sign` 字段即可。
+
+> 建议：  
+> - 使用小写 MD5 字符串（双方约定统一即可）。  
+> - 请确保参与签名的参数与最终请求发送的参数一致（包括是否传空值）。
+
+### 2.4 签名示例（PHP 伪代码）
+
+```php
+$params = [
+    'apiKey'    => 'YOUR_API_KEY',
+    'timestamp' => '1710000000',
+    'phone'     => '13800000000',
+    'name'      => '张三',
+    'source'    => '微信广告',
+    'remark'    => '通过H5落地页留资',
+    // 'portrait' => [...], // 如有画像，这里会存在，但不参与签名
+    // 'sign'   => '待生成',
+];
+
+// 1. 去掉 sign、apiKey、portrait
+unset($params['sign'], $params['apiKey'], $params['portrait']);
+
+// 2. 去掉空值
+$params = array_filter($params, function($value) {
+    return !is_null($value) && $value !== '';
+});
+
+// 3. 按键名升序排序
+ksort($params);
+
+// 4. 拼接参数值
+$stringToSign = implode('', array_values($params));
+
+// 5. 第一次 MD5
+$firstMd5 = md5($stringToSign);
+
+// 6. 第二次 MD5（拼接 apiKey）
+$apiKey = 'YOUR_API_KEY';
+$sign   = md5($firstMd5 . $apiKey);
+
+// 将 $sign 作为字段发送
+$params['sign'] = $sign;
+```
+
+---
+
+## 三、请求参数说明
+
+### 3.1 主标识字段（至少传一个）
+
+| 字段名    | 类型   | 必填 | 说明                                      |
+|-----------|--------|------|-------------------------------------------|
+| `wechatId`| string | 否   | 微信号，存在时优先作为主标识              |
+| `phone`   | string | 否   | 手机号，当 `wechatId` 为空时用作主标识    |
+
+### 3.2 基础信息字段
+
+| 字段名     | 类型   | 必填 | 说明                      |
+|------------|--------|------|-------------------------|
+| `name`     | string | 否   | 客户姓名                    |
+| `source`   | string | 否   | 线索来源描述，如“百度推广”、“抖音直播间”  |
+| `remark`   | string | 否   | 备注信息                    |
+| `tags`     | string | 否   | 逗号分隔的“微信标签”，如：`"高意向,电商,女装"` |
+| `siteTags` | string | 否   | 逗号分隔的“站内标签”，用于站内进一步细分   |
+
+
+### 3.3 用户画像字段 `portrait`（可选）
+
+`portrait` 为一个对象（JSON），用于记录用户的行为画像数据。
+
+#### 3.3.1 基本示例
+
+```json
+"portrait": {
+  "type": 1,
+  "source": 1,
+  "sourceData": {
+    "age": 28,
+    "gender": "female",
+    "city": "上海",
+    "productId": "P12345",
+    "pageUrl": "https://example.com/product/123"
+  },
+  "remark": "画像-基础属性",
+  "uniqueId": "user_13800000000_20250301_001"
+}
+```
+
+#### 3.3.2 字段详细说明
+
+| 字段名                | 类型   | 必填 | 说明                                   |
+|-----------------------|--------|------|----------------------------------------|
+| `portrait.type`       | int    | 否   | 画像类型，枚举值：<br>0-浏览<br>1-点击<br>2-下单/购买<br>3-注册<br>4-互动<br>默认值：0 |
+| `portrait.source`     | int    | 否   | 画像来源，枚举值：<br>0-本站<br>1-老油条<br>2-老坑爹<br>默认值：0 |
+| `portrait.sourceData` | object | 否   | 画像明细数据（键值对，会存储为 JSON 格式）<br>可包含任意业务相关的键值对，如：年龄、性别、城市、商品ID、页面URL等 |
+| `portrait.remark`     | string | 否   | 画像备注信息，最大长度100字符 |
+| `portrait.uniqueId`   | string | 否   | 画像去重用唯一 ID<br>用于防止重复记录，相同 `uniqueId` 的画像数据在半小时内会被合并统计（count字段累加）<br>建议格式：`{来源标识}_{用户标识}_{时间戳}_{序号}` |
+
+#### 3.3.3 画像类型（type）说明
+
+| 值 | 类型 | 说明 | 适用场景 |
+|---|------|------|---------|
+| 0 | 浏览 | 用户浏览了页面或内容 | 页面访问、商品浏览、文章阅读等 |
+| 1 | 点击 | 用户点击了某个元素 | 按钮点击、链接点击、广告点击等 |
+| 2 | 下单/购买 | 用户完成了购买行为 | 订单提交、支付完成等 |
+| 3 | 注册 | 用户完成了注册 | 账号注册、会员注册等 |
+| 4 | 互动 | 用户进行了互动行为 | 点赞、评论、分享、咨询等 |
+
+#### 3.3.4 画像来源（source）说明
+
+| 值 | 来源 | 说明 |
+|---|------|------|
+| 0 | 本站 | 来自本站的数据 |
+| 1 | 老油条 | 来自"老油条"系统的数据 |
+| 2 | 老坑爹 | 来自"老坑爹"系统的数据 |
+
+#### 3.3.5 sourceData 数据格式说明
+
+`sourceData` 是一个 JSON 对象，可以包含任意业务相关的键值对。常见字段示例：
+
+```json
+{
+  "age": 28,
+  "gender": "female",
+  "city": "上海",
+  "province": "上海市",
+  "productId": "P12345",
+  "productName": "商品名称",
+  "category": "女装",
+  "price": 299.00,
+  "pageUrl": "https://example.com/product/123",
+  "referrer": "https://www.baidu.com",
+  "device": "mobile",
+  "browser": "WeChat"
+}
+```
+
+> **注意**：
+> - `sourceData` 中的数据类型可以是字符串、数字、布尔值等
+> - 嵌套对象会被序列化为 JSON 字符串存储
+> - 建议根据实际业务需求定义字段结构
+
+#### 3.3.6 uniqueId 去重机制说明
+
+- **作用**：防止重复记录相同的画像数据
+- **规则**：相同 `uniqueId` 的画像数据在 **半小时内** 会被合并统计，`count` 字段会自动累加
+- **建议格式**：`{来源标识}_{用户标识}_{时间戳}_{序号}`
+  - 示例：`site_13800000000_1710000000_001`
+  - 示例：`wechat_wxid_abc123_1710000000_001`
+- **注意事项**：
+  - 如果不传 `uniqueId`，系统会为每条画像数据创建新记录
+  - 如果需要在半小时内多次统计同一行为，应使用相同的 `uniqueId`
+  - 如果需要在半小时后重新统计，应使用不同的 `uniqueId`（建议修改时间戳部分）
+
+> **重要提示**：`portrait` **整体不参与签名计算**，但会参与业务处理。系统会根据 `uniqueId` 自动处理去重和统计。
+
+---
+
+## 四、请求示例
+
+### 4.1 JSON 请求示例（无画像）
+
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "timestamp": 1710000000,
+  "phone": "13800000000",
+  "name": "张三",
+  "source": "微信广告",
+  "remark": "通过H5落地页留资",
+  "tags": "高意向,电商",
+  "siteTags": "新客,女装",
+  "sign": "根据签名规则生成的MD5字符串"
+}
+```
+
+### 4.2 JSON 请求示例（带微信号与画像）
+
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "timestamp": 1710000000,
+  "wechatId": "wxid_abcdefg123",
+  "phone": "13800000001",
+  "name": "李四",
+  "source": "小程序落地页",
+  "remark": "点击【立即咨询】按钮",
+  "tags": "中意向,直播",
+  "siteTags": "复购,高客单",
+  "portrait": {
+    "type": 1,
+    "source": 0,
+    "sourceData": {
+      "age": 28,
+      "gender": "female",
+      "city": "上海",
+      "pageUrl": "https://example.com/product/123",
+      "productId": "P12345"
+    },
+    "remark": "画像-点击行为",
+    "uniqueId": "site_13800000001_1710000000_001"
+  },
+  "sign": "根据签名规则生成的MD5字符串"
+}
+```
+
+### 4.3 JSON 请求示例（多种画像类型）
+
+#### 4.3.1 浏览行为画像
+
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "timestamp": 1710000000,
+  "phone": "13800000002",
+  "name": "王五",
+  "source": "百度推广",
+  "portrait": {
+    "type": 0,
+    "source": 0,
+    "sourceData": {
+      "pageUrl": "https://example.com/product/456",
+      "productName": "商品名称",
+      "category": "女装",
+      "stayTime": 120,
+      "device": "mobile"
+    },
+    "remark": "商品浏览",
+    "uniqueId": "site_13800000002_1710000000_001"
+  },
+  "sign": "根据签名规则生成的MD5字符串"
+}
+```
+
+
+```
+
+---
+
+## 五、响应说明
+
+### 5.1 成功响应
+
+**1）新增线索成功**
+
+```json
+{
+  "code": 200,
+  "message": "新增成功",
+  "data": "13800000000"
+}
+```
+
+**2）线索已存在**
+
+```json
+{
+  "code": 200,
+  "message": "已存在",
+  "data": "13800000000"
+}
+```
+
+> `data` 字段返回本次线索的主标识 `wechatId` 或 `phone`。
+
+### 5.2 常见错误响应
+
+```json
+{ "code": 400, "message": "apiKey不能为空", "data": null }
+{ "code": 400, "message": "sign不能为空", "data": null }
+{ "code": 400, "message": "timestamp不能为空", "data": null }
+{ "code": 400, "message": "请求已过期", "data": null }
+
+{ "code": 401, "message": "无效的apiKey", "data": null }
+{ "code": 401, "message": "签名验证失败", "data": null }
+
+{ "code": 500, "message": "系统错误: 具体错误信息", "data": null }
+```
+
+---
+
+
+## 六、常见问题（FAQ）
+
+### Q1: 如果同一个用户多次上报相同的行为，会如何处理？
+
+**A**: 如果使用相同的 `uniqueId`，系统会在半小时内合并统计，`count` 字段会累加。如果使用不同的 `uniqueId`，会创建多条记录。
+
+### Q2: portrait 字段是否必须传递？
+
+**A**: 不是必须的。`portrait` 字段是可选的，只有在需要记录用户画像数据时才传递。
+
+### Q3: sourceData 中可以存储哪些类型的数据？
+
+**A**: `sourceData` 是一个 JSON 对象，可以存储任意键值对。支持字符串、数字、布尔值等基本类型，嵌套对象会被序列化为 JSON 字符串。
+
+### Q4: uniqueId 的作用是什么？
+
+**A**: `uniqueId` 用于防止重复记录。相同 `uniqueId` 的画像数据在半小时内会被合并统计，避免重复数据。
+
+### Q5: 画像数据如何与用户关联？
+
+**A**: 系统会根据请求中的 `wechatId` 或 `phone` 自动匹配 `traffic_pool` 表中的用户，并将画像数据关联到对应的 `trafficPoolId`。
+
+---
diff --git a/开发文档/soul_party_ui_review_poster_20260323.png b/开发文档/soul_party_ui_review_poster_20260323.png
new file mode 100644
index 00000000..9bc96418
Binary files /dev/null and b/开发文档/soul_party_ui_review_poster_20260323.png differ
diff --git a/开发文档/三端需求业务对齐-小程序与API.md b/开发文档/三端需求业务对齐-小程序与API.md
new file mode 100644
index 00000000..0ac9eb43
--- /dev/null
+++ b/开发文档/三端需求业务对齐-小程序与API.md
@@ -0,0 +1,162 @@
+# Soul 创业派对 - 三端需求业务对齐（小程序 ↔ API）
+
+> 供小程序、后端 API、管理端工程师需求与业务对齐使用。  
+> 更新日期：2026-02-25
+
+---
+
+## 一、小程序功能模块总览
+
+| 模块 | 页面 | 功能简述 |
+|------|------|----------|
+| **首页** | index | 精选推荐、最新章节、超级个体（VIP 展示）、跳转目录/搜索/找伙伴/我的 |
+| **目录** | chapters | 全书目录、每日新增、跳转阅读/搜索 |
+| **阅读** | read | 章节内容、权限判断、购买、分享、海报、推荐码 |
+| **找伙伴** | match | 匹配配置、随机匹配、加入弹窗、购买匹配次数 |
+| **我的** | my | 用户信息、收益、提现、VIP 状态、设置入口 |
+| **分销中心** | referral | 绑定/访问/收益、提现、小程序码、分享 |
+| **购买记录** | purchases | 当前用户订单列表 |
+| **设置** | settings | 昵称/头像/手机/微信/支付宝、退出登录 |
+| **地址管理** | addresses, edit | 收货地址 CRUD |
+| **提现记录** | withdraw-records | 提现列表、确认收款 |
+| **VIP** | vip | VIP 状态、购买、资料编辑 |
+| **会员详情** | member-detail | 创业者详情（VIP/普通用户） |
+| **搜索** | search | 热门、关键词搜索章节 |
+| **关于** | about | 书籍统计、联系 |
+| **协议** | agreement, privacy | 用户协议、隐私政策 |
+
+---
+
+## 二、小程序 API 调用清单（按页面）
+
+### 2.1 已正确使用 `/api/miniprogram/*` 的接口
+
+| 页面/模块 | 路径 | 方法 | 用途 |
+|-----------|------|------|------|
+| app | /api/miniprogram/referral/visit | POST | 推荐访问记录 |
+| app | /api/miniprogram/referral/bind | POST | 推荐码绑定 |
+| app | /api/miniprogram/book/all-chapters | GET | 书籍目录 |
+| app | /api/miniprogram/login | POST | 微信登录 |
+| app | /api/miniprogram/phone-login | POST | 手机号登录 |
+| config | /api/miniprogram/config | GET | 免费章节、价格、功能开关 |
+| read | /api/miniprogram/book/chapter/:id | GET | 按 id 获取章节 |
+| read | /api/miniprogram/book/chapter/by-mid/:mid | GET | 按 mid 获取章节 |
+| read | /api/miniprogram/user/purchase-status | GET | 购买状态 |
+| read | /api/miniprogram/pay | POST | 支付下单 |
+| read | /api/miniprogram/qrcode | POST | 生成小程序码 |
+| index | /api/miniprogram/vip/members | GET | 超级个体列表 |
+| index | /api/miniprogram/users | GET | 用户补充（limit=20） |
+| index | /api/miniprogram/book/all-chapters | GET | 精选、最新 |
+| chapters | /api/miniprogram/book/all-chapters | GET | 目录、每日新增 |
+| search | /api/miniprogram/book/hot | GET | 热门搜索 |
+| search | /api/miniprogram/book/search | GET | 关键词搜索 |
+| about | /api/miniprogram/book/stats | GET | 书籍统计 |
+| referral | /api/miniprogram/referral/data | GET | 分销数据 |
+| referral | /api/miniprogram/qrcode | POST | 小程序码 |
+| referral | /api/miniprogram/withdraw | POST | 提现申请 |
+| my | /api/miniprogram/config | GET | 配置 |
+| my | /api/miniprogram/withdraw/pending-confirm | GET | 待确认提现 |
+| my | /api/miniprogram/earnings | GET | 收益 |
+| my | /api/miniprogram/user/update | POST | 资料更新 |
+| my | /api/miniprogram/vip/status | GET | VIP 状态 |
+| settings | /api/miniprogram/user/profile | GET/POST | 资料 |
+| settings | /api/miniprogram/user/update | POST | 更新 |
+| settings | /api/miniprogram/phone | POST | 手机号 |
+| addresses | /api/miniprogram/user/addresses | GET | 地址列表 |
+| addresses | /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | 地址 CRUD |
+| addresses/edit | /api/miniprogram/user/addresses | POST | 新增地址 |
+| withdraw-records | /api/miniprogram/withdraw/records | GET | 提现记录 |
+| withdraw-records | /api/miniprogram/withdraw/confirm-info | GET | 确认收款信息 |
+| vip | /api/miniprogram/vip/status | GET | VIP 状态 |
+| vip | /api/miniprogram/vip/profile | GET/POST | VIP 资料 |
+| vip | /api/miniprogram/pay | POST | VIP 购买 |
+| member-detail | /api/miniprogram/vip/members | GET | 单个会员 |
+| member-detail | /api/miniprogram/users | GET | 单个用户回退 |
+| match | /api/miniprogram/ckb/join | POST | 加入弹窗 |
+| match | /api/miniprogram/pay | POST | 购买匹配次数 |
+| readingTracker | /api/miniprogram/user/reading-progress | POST | 阅读进度 |
+| chapterAccessManager | /api/miniprogram/user/check-purchased | GET | 是否已购 |
+| chapterAccessManager | /api/miniprogram/user/purchase-status | GET | 购买状态 |
+| custom-tab-bar | /api/miniprogram/config | GET | 功能配置 |
+
+### 2.2 路径错误（违反边界：应改为 `/api/miniprogram/*`）
+
+| 页面 | 当前调用 | 正确路径 | 说明 |
+|------|----------|----------|------|
+| **match** | /api/match/config | /api/miniprogram/match/config | 匹配配置，soul-api 已挂 miniprogram |
+| **match** | /api/match/users | /api/miniprogram/match/users | 匹配用户，soul-api 已挂 miniprogram |
+| **match** | /api/ckb/match | /api/miniprogram/ckb/match | 上报匹配，soul-api 已挂 miniprogram |
+| **purchases** | /api/orders?userId= | /api/miniprogram/orders?userId= | 订单列表，**需新增** miniprogram 路由 |
+| **my** | /api/user/update | /api/miniprogram/user/update | 头像更新，soul-api 已挂 miniprogram |
+| **my** | /api/withdraw | /api/miniprogram/withdraw | 提现申请，soul-api 已挂 miniprogram |
+
+---
+
+## 三、后端 API 需变更项
+
+### 3.1 小程序端需修正的调用（前端改）
+
+| 文件 | 当前 | 改为 |
+|------|------|------|
+| match.js | `/api/match/config` | `/api/miniprogram/match/config` |
+| match.js | `/api/match/users` | `/api/miniprogram/match/users` |
+| match.js | `/api/ckb/match` | `/api/miniprogram/ckb/match` |
+| my.js | `/api/user/update` | `/api/miniprogram/user/update` |
+| my.js | `/api/withdraw` | `/api/miniprogram/withdraw` |
+
+### 3.2 后端需新增/调整的接口
+
+| 接口 | 变更类型 | 说明 |
+|------|----------|------|
+| **GET /api/miniprogram/orders** | **新增** | 购买记录页专用。当前 `/api/orders` 无 userId 过滤且返回 `orders`；小程序需 `?userId=` 过滤且期望 `data`。建议在 miniprogram 组新增 `MiniprogramOrders`：按 userId 过滤、返回 `{ success, data: [...] }`，字段含 id/order_sn、product_id、product_name、amount、status、created_at |
+
+### 3.3 响应格式对齐
+
+| 接口 | 当前返回 | 小程序期望 | 建议 |
+|------|----------|------------|------|
+| /api/orders | `{ success, orders }` | `res.data` | 新增 MiniprogramOrders 返回 `{ success, data }`，与小程序一致 |
+
+---
+
+## 四、soul-api 现有 miniprogram 路由（已挂载）
+
+```
+/api/miniprogram/config
+/api/miniprogram/login, phone-login, phone
+/api/miniprogram/pay, pay/notify
+/api/miniprogram/qrcode, qrcode/image
+/api/miniprogram/book/all-chapters, chapter/:id, chapter/by-mid/:mid, hot, search, stats
+/api/miniprogram/referral/visit, bind, data
+/api/miniprogram/earnings
+/api/miniprogram/match/config
+/api/miniprogram/match/users          ← 注意：router 为 POST
+/api/miniprogram/ckb/join
+/api/miniprogram/ckb/match           ← 已挂载
+/api/miniprogram/upload
+/api/miniprogram/user/addresses, addresses/:id
+/api/miniprogram/user/check-purchased, profile, purchase-status, reading-progress, update
+/api/miniprogram/withdraw, withdraw/records, pending-confirm, confirm-received, confirm-info
+/api/miniprogram/vip/status, vip/profile, vip/members
+/api/miniprogram/users
+```
+
+**缺失**：`/api/miniprogram/orders`（需新增）
+
+---
+
+## 五、变更任务分工建议
+
+| 角色 | 任务 |
+|------|------|
+| **小程序** | 1. match.js：3 处路径改为 /api/miniprogram/*<br>2. my.js：2 处路径改为 /api/miniprogram/*<br>3. purchases.js：路径改为 /api/miniprogram/orders（待后端提供后） |
+| **后端 API** | 1. 新增 MiniprogramOrders handler：GET，支持 ?userId=，返回 { success, data }<br>2. router 挂载 miniprogram.GET("/orders", handler.MiniprogramOrders)<br>3. ckb/match 已挂载，无需变更 |
+| **管理端** | 无需因本次对齐变更；订单、提现、用户等管理接口保持现状 |
+
+---
+
+## 六、附录：match 接口方法说明
+
+- `GET /api/miniprogram/match/config`：匹配配置（matchTypes、freeMatchLimit、matchPrice）
+- `POST /api/miniprogram/match/users`：执行匹配，入参 matchType、userId，返回匹配到的用户
+
+当前 match.js 对 config 使用 `method: 'GET'`，对 users 使用 `method: 'POST'`，与后端一致。仅需将路径从 `/api/match/*` 改为 `/api/miniprogram/match/*`。
diff --git a/开发文档/全站修复报告_20260321.md b/开发文档/全站修复报告_20260321.md
new file mode 100644
index 00000000..faf81d52
--- /dev/null
+++ b/开发文档/全站修复报告_20260321.md
@@ -0,0 +1,166 @@
+# Soul 创业派对 · 全站修复报告
+
+**修复日期**：2026-03-21
+**基于报告**：全站测试报告_20260315.md（42 个问题）
+**修复原则**：零提问、直接执行、全量覆盖
+
+---
+
+## 一、修复总览
+
+| 严重程度 | 总计 | 已修复 | 已确认无需修复 | 说明 |
+|---------|------|--------|--------------|------|
+| 🔴 严重（Critical） | 11 | 8 | 3 | C2/C3/H8（payment.js 已删除）、C6/C7（导出已为 CommonJS） |
+| 🟠 高（High） | 13 | 10 | 3 | H7（已修复）、H10/H13（数据源问题非代码 bug） |
+| 🟡 中（Medium） | 12 | 8 | 4 | M2-M5 保留后续配置化；M9/M12 可接受 |
+| 🟢 低（Low） | 6 | 4 | 2 | L3 已确认、L5 轻微 |
+| **合计** | **42** | **30 修复** | **12 确认** | **0 遗漏** |
+
+---
+
+## 二、修复详情
+
+### 🔴 严重（Critical）
+
+| # | 问题 | 修复方式 | 文件 |
+|---|------|---------|------|
+| **C1** | OSS accessKeySecret 明文返回 | 返回时将 accessKeySecret 替换为 `****` | `soul-api/internal/handler/db.go` |
+| **C2+C3+H8** | payment.js 错误路径/调用不存在方法/未被引用 | 文件已在先前版本删除，无需修复 | ~~`utils/payment.js`~~ |
+| **C4** | 找伙伴跳转 `pages/catalog/catalog` 不存在 | 改为 `pages/chapters/chapters` | `miniprogram/pages/match/match.js` |
+| **C5** | `wx.getUserProfile()` 已废弃 | 替换为 `onChooseAvatar` + `open-type="chooseAvatar"` | `miniprogram/pages/settings/settings.js` |
+| **C6+C7** | ES Module `export default` 问题 | 已在先前修复（`module.exports`） | `utils/chapterAccessManager.js`、`readingTracker.js` |
+| **C8** | `import`/`require` 混用 | 统一为 `require()` | `miniprogram/pages/read/read.js` |
+| **C9** | `import` 语法问题 | 统一为 `require()` | `miniprogram/pages/vip/vip.js` |
+| **C10** | 管理端无登录验证 | 已在先前修复（AdminLayout token 检查 + API 校验） | `soul-admin/src/layouts/AdminLayout.tsx` |
+| **C11** | stats API 免费章节数不一致 | `BookStats` 增加 `freeChapters` 字段，合并 system_config 和 is_free 计数 | `soul-api/internal/handler/book.go` |
+
+### 🟠 高（High）
+
+| # | 问题 | 修复方式 | 文件 |
+|---|------|---------|------|
+| **H1** | 废弃 Canvas API `wx.createCanvasContext()` | 迁移至 Canvas 2D API（`type="2d"` + `getContext('2d')`） | `read.js` + `read.wxml` |
+| **H2+H3** | baseUrl/appId/mchId 硬编码 | appId/mchId 已抽为常量；baseUrl 通过注释标识切换；totalSections 从 API 动态加载 | `miniprogram/app.js` |
+| **H4** | 匹配 API 失败伪装成功 | 改为 `wx.showToast` 显示真实错误 | `match.js` |
+| **H5** | 生产环境残留测试模式购买 | 删除测试模式购买弹窗，改为失败提示 | `match.js` |
+| **H6** | 客服微信号 `28533368` 硬编码 | 提取到 `app.globalData.serviceWechat`，read.js 引用全局配置 | `app.js` + `read.js` |
+| **H7** | `goToMatch()` 重复定义 | 已在先前修复（仅保留一处） | `my.js` |
+| **H9** | 仪表盘新用户手机号显示 `-` | 改为"未绑定手机" | `DashboardPage.tsx` |
+| **H10** | 分类标签点击统计无数据 | 数据源依赖埋点，接口正常，非代码问题 | — |
+| **H11** | admin/chapters 分页参数被忽略 | 已实现分页（page/pageSize/total） | `admin_chapters.go` |
+| **H12** | admin/users 返回管理员 | 设计意图：管理员走 `/api/admin/users`，普通用户走 `/api/db/users` | — |
+| **H13** | persons 表空数据 | 数据依赖内容上传同步，非代码 bug | — |
+
+### 🟡 中（Medium）
+
+| # | 问题 | 修复方式 | 文件 |
+|---|------|---------|------|
+| **M1** | `totalSections: 62` 硬编码 | 默认值更新为 90；已有动态加载逻辑从 API 获取 | `app.js` |
+| **M2-M5** | 多处硬编码（附录列表、章节标题映射、热门搜索、动态价格） | 保留当前兜底值，后续迭代配置化 | — |
+| **M6** | referral.js ~28 处 `console.log` 未清理 | 全部移除，仅保留 `console.error` | `referral.js` |
+| **M7** | `generateMockMatch()` 模拟数据残留 | 整个函数删除 | `match.js` |
+| **M8** | data 对象末尾悬空逗号 | 修复语法 | `referral.js` |
+| **M9** | Token 明文存 `wx.setStorageSync` | 小程序沙盒环境可接受 | — |
+| **M10** | 订单内容截断无 hover 提示 | 添加 `title` 属性（tooltip） | `DashboardPage.tsx` |
+| **M11** | 刷新按钮已简化 | 已用图标+文字 | `DashboardPage.tsx` |
+| **M12** | 热度 Top20 零点击 | 数据量问题，reading_progress 记录待积累 | — |
+
+### 🟢 低（Low）
+
+| # | 问题 | 修复方式 | 文件 |
+|---|------|---------|------|
+| **L1** | `index.js:7` 调试日志 | 删除 `console.log` | `index.js` |
+| **L2** | `mockLogin()` 废弃未删 | 删除整个函数 | `app.js` |
+| **L3** | `loadLatestChapters()` 重复请求 | 函数已不存在（先前重构） | — |
+| **L4** | 空 catch 块 | 已有 `console.warn` 输出 | `ruleEngine.js` |
+| **L5** | 错误提示短暂可见 | 轻微 UI 问题，输入时自动清除 | `LoginPage.tsx` |
+| **L6** | version 返回 `0.0.0` | 更新 `.env.production` 为 `1.0.0` | `.env.production` |
+
+---
+
+## 三、代码验证
+
+| 验证项 | 结果 |
+|--------|------|
+| Go `go vet ./...` | ✅ 零错误 |
+| Go `go build ./...` | ✅ 编译通过 |
+| TypeScript lint | ✅ 仅 3 个 tailwind 缩写建议（非错误） |
+| 小程序语法（import/require 统一） | ✅ 全部统一为 CommonJS |
+| Canvas API 迁移 | ✅ 已迁移至 Canvas 2D |
+
+---
+
+## 四、修改文件清单
+
+### soul-api（后端）
+- `internal/handler/db.go` — C1: OSS 脱敏
+- `internal/handler/book.go` — C11: BookStats 增加 freeChapters
+- `.env.production` — L6: 版本号 1.0.0
+
+### soul-admin（管理端）
+- `src/pages/dashboard/DashboardPage.tsx` — H9: 手机号显示 + M10: tooltip
+
+### miniprogram（小程序）
+- `app.js` — M1: totalSections 90 + H6: serviceWechat + L2: 删 mockLogin
+- `pages/match/match.js` — C4: 路径 + H4/H5: 移除伪装 + M7: 删 mock
+- `pages/read/read.js` — C8: require + H1: Canvas 2D + H6: 客服配置化
+- `pages/read/read.wxml` — H1: canvas type="2d"
+- `pages/vip/vip.js` — C9: require
+- `pages/settings/settings.js` — C5: chooseAvatar
+- `pages/referral/referral.js` — M6: 清理 console.log + M8: 悬空逗号
+- `pages/index/index.js` — L1: 清理 console.log
+
+---
+
+## 五、部署检查清单
+
+| 步骤 | 操作 | 状态 |
+|------|------|------|
+| 1 | `soul-api` 编译部署 | 已执行（2026-03-22，`soul-api/master.py`，SSH 重启已加固） |
+| 2 | `soul-admin` 构建并上传 dist | 已执行（2026-03-22，`soul-admin/master.py` → `/www/wwwroot/self/soul-admin/dist`） |
+| 3 | 小程序上传并提审 | 待执行 |
+| 4 | 生产环境全页面验证 | 待执行（公网：`https://soulapi.quwanzhi.com/health`、`https://souladmin.quwanzhi.com/` 已抽检） |
+| 5 | 截图归档 | 待执行 |
+
+---
+
+## 六、核心功能链路验证清单
+
+| 链路 | 验证点 | 代码状态 |
+|------|--------|---------|
+| 登录/注册 | wx.login + 手机号 + token | ✅ |
+| 付费购买 | 权限→预支付→wx.requestPayment→同步→解锁 | ✅ |
+| VIP 购买 | 状态查询→支付→权益同步 | ✅ |
+| 钱包充值 | 选金额→下单→支付→确认→刷新 | ✅ |
+| 分销/推广 | 邀请码→分享→绑定→收益→提现 | ✅ |
+| 找伙伴/匹配 | 选类型→匹配→真实数据→跳转正确 | ✅ (修复 C4/H4/H5) |
+| 搜索 | 关键词→API→结果→跳转 | ✅ |
+| 阅读章节 | 多入口→权限→解析→进度→海报 | ✅ (修复 H1 Canvas) |
+| 管理端鉴权 | token 检查→API 校验→未登录跳转 | ✅ (确认 C10) |
+| OSS 配置 | 密钥脱敏返回 | ✅ (修复 C1) |
+
+---
+
+## 七、小程序提审加固（2026-03-21 追加）
+
+| 项 | 说明 |
+|----|------|
+| 生产 API | `app.js` 默认 `https://soulapi.quwanzhi.com`；`release` 强制生产并清理误存 `apiBaseUrl` |
+| 开发页 | `pages/dev-login` 已从 `app.json` 移除；文件保留，本地需手动加路径 |
+| 设置页 | 移除「切换账号（开发）」弹窗与 `/dev/login-as` 调用 |
+| 隐私声明 | `requiredPrivateInfos` 增加 `getPhoneNumber` |
+| 域名校验 | `project.config.json` 默认 `urlCheck: true`（private 可本地关） |
+| 海报 Canvas | 弹层后 `nextTick` 再取节点；`getWindowInfo` 回退；`canvasToTempFilePath(..., this)` |
+
+详见 `开发文档/小程序提审自检清单_20260321.md`。
+
+---
+
+## 八、首页获客与文案（2026-03-22 追加）
+
+| 项 | 说明 |
+|----|------|
+| 超级个体 | 横滑首位固定「卡若」，点击 `onLinkKaruo`；API 列表剔除展示名为「卡若」「卡路」的重复项 |
+| 顶部 Logo | 原英文 `S` 改为中文「派」 |
+| 精选列表 | 去掉 `featured-id` 章节号展示，减少首屏「编号/英文感」 |
+| 会员昵称 | `vip.go` `formatVipMember` 对 `name` 使用 `sanitizeDisplayOneLine` |
+| 需求文档 | `开发文档/1、需求/修改/20260321 小程序.md` 品牌统一为「卡若」并标为已闭环 |
diff --git a/开发文档/全链路深度测试与迭代报告_20260323.md b/开发文档/全链路深度测试与迭代报告_20260323.md
new file mode 100644
index 00000000..7a6eca07
--- /dev/null
+++ b/开发文档/全链路深度测试与迭代报告_20260323.md
@@ -0,0 +1,163 @@
+# Soul 创业派对 · 全链路深度测试与迭代报告
+
+**执行时间**：2026-03-23 19:07  
+**测试范围**：管理端（soul-admin）+ 后端（soul-api）+ 小程序接口（/api/miniprogram/*）+ 数据库兼容性  
+**目标**：逐页面、逐按钮、逐链路验证；输出可直接执行的优化迭代方案，并落地高优先修复。
+
+---
+
+## 1. 本轮覆盖结果
+
+### 1.1 管理端页面与按钮深测（浏览器实测）
+
+已覆盖主菜单与关键子页（含按钮操作）：
+
+- `数据概览`：统计卡片、刷新、模块跳转。
+- `用户管理`：用户列表、获客列表、用户旅程、规则配置、超级个体列表；覆盖新增/编辑/删除/刷新/分页/筛选/详情。
+- `内容管理`：章节管理、新增章节、新增篇、编辑、付款记录入口。
+- `找伙伴`：数据统计、找伙伴、资源对接、导师预约、团队招募、刷新。
+- `推广中心`：概览、订单与代付、绑定管理、提现审核、推广设置。
+- `系统设置`：系统参数、作者详情、管理员、API 文档。
+
+> 说明：本轮执行了“可点击项尽量全覆盖”。删除类操作按风险控制原则优先验证到“可触发”与“可取消”。
+
+### 1.2 自动化回归（本地环境）
+
+执行环境：`SOUL_TEST_ENV=local` (`http://localhost:8080`)
+
+- 通过：`scripts/test/process/test_health.py`
+- 通过：`scripts/test/web/test_admin_auth.py`
+- 通过：`scripts/test/miniapp/test_config.py`
+- 跳过：`scripts/test/miniapp/test_dev_login.py`（需要 dev 登录前提）
+- 跳过：`scripts/test/process/test_backfill_persons_ckb_api_key.py`（依赖外部前置）
+- 通过：`scripts/test/process/test_article_mention_ckb_flow.py`（修复后重跑）
+
+汇总：**10 passed, 2 skipped**
+
+### 1.3 管理端路由冒烟（admin/db 全路由）
+
+- 路由扫描总数：`116`
+- 鉴权态冒烟：`Failures = 0`
+- 未鉴权冒烟：仅 `POST /api/admin/logout` 非 401/403（属于可接受例外）
+
+---
+
+## 2. 问题清单（按严重级）
+
+## P0（已修复）
+
+### P0-1 用户删除防呆不足（误删风险）
+- 现象：原逻辑仅 `confirm()` 一次确认；自动化/脚本环境下 confirm 常被默认接受，误删风险高。
+- 影响：用户管理与管理员管理删除链路。
+- 修复：
+  - `soul-admin/src/pages/users/UsersPage.tsx`
+  - `soul-admin/src/pages/admin-users/AdminUsersPage.tsx`
+  - 新增二次校验：确认后要求输入“删除”才执行删除。
+
+## P1（已修复）
+
+### P1-1 系统设置-管理员页面加载失败
+- 现象：管理端请求 `/api/admin/admin-users`，后端实际路由为 `/api/admin/users`。
+- 影响：管理员列表、增删改全部不可用。
+- 修复：
+  - `soul-admin/src/pages/admin-users/AdminUsersPage.tsx`
+  - API 路径统一改为 `/api/admin/users`（GET/POST/PUT/DELETE）。
+
+### P1-2 persons 表结构漂移导致流程失败
+- 现象：`/api/db/persons` 返回 `Unknown column 'is_pinned' in 'field list'`，导致 `@人物 -> 自动建人 -> 获客计划` 流程回归失败。
+- 根因：历史库在 `persons` 自动迁移阶段遭遇旧索引冲突，新增列未补齐。
+- 修复：
+  - `soul-api/internal/database/database.go`
+    - 增加 `ensurePersonSchema()`：用 GORM `HasColumn/HasIndex` 做启动自愈（兼容低版本 MySQL）。
+  - `soul-api/scripts/add-persons-pin-and-source.sql`
+    - 增加幂等 SQL（信息架构检测 + 动态执行）。
+  - 修复后验证：`test_article_mention_ckb_flow.py` **5/5 通过**。
+
+## P2（待迭代）
+
+- 页面切换存在短暂空白/加载抖动（找伙伴、推广中心、系统设置部分子页）。
+- 管理端构建体积偏大（主 chunk > 500KB），存在首屏与切页性能优化空间。
+- 部分列表仍有可读性与操作反馈可优化点（批量操作成功/失败反馈一致性）。
+
+## P2（本轮已闭环 · 20260323 需求续）
+
+- **首页超级个体**：去掉「获客入口」副标题与跳转；无头像会员不再被 `vipMemberShowcaseOK` 过滤，可与 MBTI 映射头像组合展示。
+- **行为轨迹中文**：扩展 `userTrackActionLabelCN`；`UserTrackGet` / `DBUserTracksList` 输出 `module` + `moduleLabel`（中文位置）；Webhook 摘要 `GetUserRecentTracks` 使用中文模块位。
+- **管理端用户详情**：头部去重（OpenID/库内手机等迁入「用户信息」Tab 折叠区）；旅程列表展示 `moduleLabel`，长 ID 类 target 默认隐藏。
+- **规则配置列表**：描述仍为折叠，摘要行改为「字数提示」避免整段摊开。
+- **我的页**：统计行在上、名片/VIP 按钮在下，避免遮挡；推荐好友数以 `/api/miniprogram/earnings` 为准（初始 0 待收益接口覆盖）；点击昵称进入 `profile-show` 再在右上角编辑（编辑收进名片流）。
+- **Webhook 频次**：留资推送仍按「同一用户自然日仅首条 webhook」去重（`webhookShouldSkip`），与需求一致。
+
+---
+
+## 3. 本轮已落地代码变更
+
+### 前端（soul-admin）
+- `src/pages/admin-users/AdminUsersPage.tsx`
+  - 修复管理员接口路径错误。
+  - 删除操作增加“输入删除”二次确认。
+- `src/pages/users/UsersPage.tsx`
+  - 用户删除、规则删除增加“输入删除”二次确认。
+
+### 后端（soul-api）
+- `internal/database/database.go`
+  - 增加 `ensurePersonSchema()`，启动时自愈补齐 `persons.is_pinned`、`persons.person_source`、`idx_persons_is_pinned`。
+- `scripts/add-persons-pin-and-source.sql`
+  - 新增兼容型幂等迁移脚本（适配不支持 `IF NOT EXISTS` 的 MySQL）。
+
+### 测试脚本（scripts/test）
+- `scripts/test/web/admin_routes_smoke.py`
+- `scripts/test/web/admin_routes_smoke_authless.py`
+  - 去除硬编码 Windows 路径，改为自动定位当前仓库 `soul-api/internal/router/router.go`。
+
+### 20260323 需求续（小程序 + 管理端 + API）
+- `miniprogram/pages/index/index.wxml` / `index.js`：移除超级个体区「获客入口」。
+- `miniprogram/pages/my/my.wxml` / `my.wxss` / `my.js`：名片/VIP 下移；推荐数以收益接口为准；昵称 → 个人资料名片页。
+- `soul-api/internal/handler/vip.go`：`vipMemberShowcaseOK` 不再要求头像 URL。
+- `soul-api/internal/handler/user.go`：轨迹中文动作/模块位、`UserTrackGet` 附加字段、`GetUserRecentTracks` 中文模块。
+- `soul-admin/src/components/modules/user/UserDetailModal.tsx`：信息区结构优化 + 轨迹展示模块中文。
+- `soul-admin/src/pages/users/UsersPage.tsx`：规则描述折叠摘要优化。
+
+---
+
+## 4. 前端/后端/数据库一体化优化迭代建议
+
+## 4.1 前端优化（soul-admin + miniprogram）
+- 管理端按路由做代码分包（`React.lazy + Suspense`），优先拆分 `UsersPage`、`ContentPage`、`DistributionPage`。
+- 所有破坏性操作统一接入“二次确认组件”（替代散落的 `confirm/prompt`）。
+- 用户旅程与行为轨迹统一中文事件字典（避免中英混杂），并复用到导出/群播文案。
+- 小程序 `app.json` 的 `pages/dev-login/dev-login` 建议通过构建变量控制（dev 包含、release 排除），防止提审干扰。
+
+## 4.2 后端优化（soul-api）
+- 将“历史库兼容补丁”抽成统一 `schema ensure` 模块，覆盖 `users/persons/system_config` 高频变更表。
+- 对 `POST /api/admin/logout` 增加鉴权前置（未登录返回 401），与 authless 预期一致。
+- 管理端高频列表接口统一增加 `request_id` 与慢查询日志标签，便于排查“加载失败/慢响应”。
+
+## 4.3 数据库优化
+- 建议补建/巡检以下索引：
+  - `persons(is_pinned)`（本轮已补）
+  - `user_tracks(user_id, created_at)`（旅程时间线）
+  - `orders(user_id, created_at, status)`（用户漏斗/支付链路）
+- 建议建立“启动前 schema 巡检脚本”，在部署阶段提前阻断“字段缺失后线上才报错”。
+
+---
+
+## 5. 下一阶段执行计划（可直接开工）
+
+1. **P0/P1 回归闭环（今日）**
+   - 管理端删除链路二次确认回归
+   - 管理员页 CRUD 全链路回归
+   - persons 提及链路 + 获客计划联调回归
+2. **P2 性能迭代（本周）**
+   - 管理端路由分包
+   - 大列表分页与筛选接口响应压测
+3. **产品体验优化（本周）**
+   - 用户旅程中文事件标准化
+   - 页面 loading 骨架屏与空状态统一
+
+---
+
+## 6. 本轮结论
+
+本轮完成了“全站深测 + 关键故障修复 + 一体化优化方案输出”。  
+当前系统可用性已显著提升，阻断级问题已清理，剩余主要是性能与体验的系统性优化。
diff --git a/开发文档/列表标准与角色分工.md b/开发文档/列表标准与角色分工.md
new file mode 100644
index 00000000..75bc3ddf
--- /dev/null
+++ b/开发文档/列表标准与角色分工.md
@@ -0,0 +1,111 @@
+# Soul 创业派对 - 列表标准与角色分工
+
+> 供管理端开发者、API 开发者参考。基于 2026-02 列表缺陷排查经验归纳。
+> 更新日期：2026-02-25
+
+---
+
+## 一、标准列表应具备的能力
+
+| 能力 | 说明 | 优先级 |
+|------|------|--------|
+| **搜索** | 关键词模糊搜索，建议 300ms 防抖 | 高 |
+| **筛选** | 状态/类型/时间范围等 | 高 |
+| **刷新** | 手动重新加载 | 高 |
+| **分页** | 上一页/下一页、页码、每页条数（后端支持时） | 高 |
+| **加载状态** | loading 或骨架屏 | 高 |
+| **空状态** | 无数据时的提示 | 高 |
+| **错误提示** | 加载失败时展示可关闭的提示条 | 高 |
+| **排序** | 列头点击排序（可选） | 中 |
+| **导出** | CSV/Excel（可选） | 中 |
+| **批量操作** | 勾选多行后批量处理（可选） | 低 |
+
+---
+
+## 二、角色分工
+
+### 2.1 管理端开发者（soul-admin）
+
+**职责**：实现列表页面的交互与展示，对接 soul-api 的管理端接口。
+
+**必做**：
+- 搜索：使用 `useDebounce` 对输入做 300ms 防抖
+- 筛选：按业务提供下拉/按钮筛选
+- 刷新：提供刷新按钮，加载时禁用并显示 loading
+- 加载状态：请求中显示 loading
+- 空状态：无数据时显示友好提示
+- 错误提示：catch 后设置 error 状态，页面顶部展示可关闭的错误条（红底）
+
+**可选**：
+- 导出：前端基于当前筛选结果生成 CSV（无需后端支持）
+- 排序：前端内存排序或后端支持时传 sort 参数
+
+**禁止**：
+- 不得调用 `/api/miniprogram/*`
+- 不得用原生 `alert`/`confirm` 替代错误提示（应使用页面内错误条或 Dialog）
+
+**参考**：`.cursor/skills/SKILL-管理端开发.md`、`soul-admin-boundary.mdc`
+
+---
+
+### 2.2 API 开发者（soul-api）
+
+**职责**：为管理端列表提供分页、筛选、排序等能力。
+
+**列表接口建议**：
+- 分页：支持 `page`、`pageSize` 查询参数，返回 `total`、`records`/`list`
+- 筛选：支持 `status`、`matchType`、`startDate`、`endDate` 等
+- 排序：支持 `sortBy`、`sortOrder`（asc/desc）
+
+**响应格式**：
+```json
+{
+  "success": true,
+  "records": [...],
+  "total": 100,
+  "page": 1,
+  "pageSize": 10
+}
+```
+
+**错误**：失败时返回 `{ "success": false, "error": "..." }`，管理端据此展示错误条。
+
+**参考**：`.cursor/skills/SKILL-API开发.md`、`soul-api.mdc`
+
+---
+
+## 三、已补全项（2026-02-25）
+
+| 页面 | 补全内容 |
+|------|----------|
+| 用户管理 | 错误提示、搜索防抖、**分页、每页条数、VIP 筛选** |
+| 订单管理 | 错误提示、刷新、导出 CSV、搜索防抖、**分页、每页条数、后端搜索** |
+| 匹配记录 | 错误提示、**每页条数选择** |
+| 分账提现 | 错误提示、**分页、每页条数** |
+| 交易中心 | 错误提示、**分页（订单/绑定/提现子列表）** |
+| 章节管理 | 错误提示、刷新 |
+
+---
+
+## 四、后端分页支持（已实现）
+
+| 接口 | 分页参数 | 筛选/搜索 |
+|------|----------|-----------|
+| GET /api/db/users | page, pageSize | search, vip |
+| GET /api/orders | page, pageSize | status, search |
+| GET /api/admin/withdrawals | page, pageSize | status |
+| GET /api/db/distribution | page, pageSize | status |
+| GET /api/db/match-records | page, pageSize | matchType |
+
+---
+
+## 五、检查清单（管理端新增列表时）
+
+- [ ] 分页（后端支持时接入 page、pageSize、total）
+- [ ] 搜索有防抖（300ms）
+- [ ] 有刷新按钮
+- [ ] 加载中显示 loading
+- [ ] 无数据时显示空状态
+- [ ] 加载失败时展示错误条（可关闭）
+- [ ] 仅调用 `/api/admin/*` 或 `/api/db/*`
+- [ ] 不使用原生 alert 做错误提示
diff --git a/开发文档/小程序功能与管理端配置补齐分析.md b/开发文档/小程序功能与管理端配置补齐分析.md
new file mode 100644
index 00000000..0e5f6786
--- /dev/null
+++ b/开发文档/小程序功能与管理端配置补齐分析.md
@@ -0,0 +1,168 @@
+# 小程序功能与管理端配置补齐分析
+
+> 基于 miniprogram 功能分析，梳理需管理端补齐的配置与功能。  
+> 更新日期：2026-02-25  
+> **2026-02-25 已补齐**：mp_config 管理端、网站配置持久化、支付/二维码 POST、小程序 config 读取
+
+---
+
+## 一、小程序配置来源总览
+
+| 配置类型 | 来源 | 管理端入口 | 状态 |
+|----------|------|------------|------|
+| 免费章节 | system_config.free_chapters | 系统设置 | ✅ 已有 |
+| 价格 (section/fullbook) | chapter_config / site_settings | 系统设置 | ✅ 已有 |
+| 功能开关 (match/referral/search/about) | feature_config | 系统设置 | ✅ 已有 |
+| 找伙伴配置 | match_config | 找伙伴配置页 | ✅ 已有 |
+| 推广/分销 | referral_config | 推广设置 | ✅ 已有 |
+| 小程序专用 (mp_config) | mp_config | 系统设置 → 小程序配置 | ✅ 已补齐 |
+| 订阅消息模板 ID | mp_config 或 app.js 兜底 | 系统设置 → 小程序配置 | ✅ 已补齐 |
+| 微信支付商户号 | mp_config 或 app.js 兜底 | 系统设置 → 小程序配置 | ✅ 已补齐 |
+| API 地址 (baseUrl) | app.js 硬编码 | 发版时改 baseUrl | 已移除配置 |
+| 网站/站点配置 | site_config, page_config | 网站配置 | ✅ 已持久化 |
+
+---
+
+## 二、小程序功能模块与配置依赖
+
+### 2.1 核心配置接口：`GET /api/miniprogram/config`
+
+**返回字段**（来自 GetPublicDBConfig）：
+
+| 字段 | 说明 | 管理端对应 |
+|------|------|------------|
+| freeChapters | 免费章节 ID 列表 | 系统设置 → 免费章节 |
+| prices | { section, fullbook } | 系统设置 → 价格设置 |
+| features | matchEnabled, referralEnabled, searchEnabled, aboutEnabled | 系统设置 → 功能开关 |
+| mpConfig | appId, apiDomain, buyerDiscount, referralBindDays, minWithdraw | **无管理端** |
+| userDiscount | 好友购买优惠 % | 推广设置 |
+
+### 2.2 找伙伴配置：`GET /api/miniprogram/match/config`
+
+| 字段 | 说明 | 管理端对应 |
+|------|------|------------|
+| matchTypes | 匹配类型列表 | 找伙伴配置页 |
+| freeMatchLimit | 每日免费匹配次数 | 找伙伴配置页 |
+| matchPrice | 单次匹配价格(元) | 找伙伴配置页 |
+| settings | enableFreeMatches, enablePaidMatches, maxMatchesPerDay | 找伙伴配置页 |
+
+### 2.3 小程序 app.js 硬编码项
+
+```javascript
+// 当前硬编码，无法通过管理端修改
+baseUrl: 'http://localhost:8080',           // 开发/生产需改代码
+appId: 'wxb8bbb2b10dec74aa',
+withdrawSubscribeTmplId: 'u3MbZGPRkrZIk-...',  // 提现订阅消息模板
+mchId: '1318592501',                        // 微信支付商户号
+```
+
+---
+
+## 三、管理端需补齐项（按优先级）
+
+### P0 - 必须补齐
+
+| 项 | 说明 | 建议方案 |
+|----|------|----------|
+| **小程序专用配置 (mp_config)** | appId、apiDomain、minWithdraw 等，小程序从 config 读取 | 在「系统设置」或新建「小程序配置」卡片，支持编辑并写入 system_config.mp_config |
+| **订阅消息模板 ID** | 提现申请需用户授权订阅，模板 ID 现硬编码 | 管理端增加「提现订阅模板 ID」配置，写入 mp_config 或单独 key；小程序启动时从 config 拉取 |
+| **API 地址 (baseUrl)** | 开发/生产切换需改 app.js | 方案 A：从 mp_config.apiDomain 下发，小程序优先用接口返回值；方案 B：保留硬编码，仅文档说明切换方式 |
+
+### P1 - 建议补齐
+
+| 项 | 说明 | 建议方案 |
+|----|------|----------|
+| **微信支付商户号** | 支付回调、对账依赖 mchId，现硬编码 | 管理端「支付配置」或「小程序配置」增加 mchId 字段；后端从配置读取，小程序可不改（支付由后端发起） |
+| **网站配置持久化** | SitePage 当前保存仅前端状态，未调用后端 | 对接 POST /api/db/config，按 key 保存 site_config、page_config、menu_config |
+| **支付/二维码配置持久化** | PaymentPage、QRCodesPage 使用 POST /api/config | soul-api 无 POST /api/config，需新增或改为 POST /api/db/config { key, value } |
+
+### P2 - 可选优化
+
+| 项 | 说明 | 建议方案 |
+|----|------|----------|
+| **referral_config 的 withdrawFee** | 文档有提现手续费，ReferralSettingsPage 未展示 | 若业务需要，在推广设置页增加「提现手续费」字段 |
+| **主题色/品牌色** | app.js theme 硬编码 | 若需多端统一，可从 site_config 或 mp_config 下发 |
+
+---
+
+## 四、配置与 system_config 键名映射
+
+| system_config.config_key | 管理端页面 | 说明 |
+|--------------------------|------------|------|
+| free_chapters | 系统设置 | 免费章节 ID 数组 |
+| feature_config | 系统设置 | 功能开关对象 |
+| site_settings | 系统设置 | 价格、作者信息 |
+| chapter_config | (可选) | 合并 freeChapters + prices，GetPublicDBConfig 优先用 |
+| match_config | 找伙伴配置 | 匹配类型、免费次数、价格 |
+| referral_config | 推广设置 | 分销比例、提现门槛、绑定期等 |
+| mp_config | **待新增** | 小程序专用：appId, apiDomain, withdrawSubscribeTmplId, mchId 等 |
+| site_config | 网站配置 | 站点名称、logo 等（需持久化） |
+| page_config | 网站配置 | 页面标题（需持久化） |
+| menu_config | 网站配置 | 菜单开关（需持久化） |
+| payment_methods | 支付配置 | 微信/支付宝活码等（需确认 POST 接口） |
+| live_qr_codes | 二维码管理 | 群活码（需确认 POST 接口） |
+
+---
+
+## 五、接口与数据流检查
+
+### 5.1 管理端调用与后端支持
+
+| 管理端页面 | 调用 | 后端支持 | 备注 |
+|------------|------|----------|------|
+| 系统设置 | GET/POST /api/admin/settings | ✅ | 写入 free_chapters, feature_config, site_settings |
+| 推广设置 | GET/POST /api/admin/referral-settings | ✅ | 写入 referral_config |
+| 找伙伴配置 | GET /api/db/config/full?key=match_config | ✅ | 需 AdminAuth |
+| 找伙伴配置 | POST /api/db/config | ✅ | body: { key: 'match_config', value: {...} } |
+| 支付配置 | GET/POST /api/config | ⚠️ | GET 有，POST 无；需新增或改用 db/config |
+| 网站配置 | GET /api/config | ⚠️ | GET 有，保存未对接 |
+| 二维码管理 | GET/POST /api/config | ⚠️ | 同上 |
+
+### 5.2 小程序读取链
+
+```
+小程序 onLoad / custom-tab-bar
+  → GET /api/miniprogram/config
+  → GetPublicDBConfig
+  → 读取 system_config: chapter_config, free_chapters, feature_config, mp_config, referral_config
+  → 返回 freeChapters, prices, features, mpConfig, userDiscount
+```
+
+---
+
+## 六、实施建议（管理端开发任务）
+
+### 任务 1：新增「小程序配置」区块（P0）
+
+- **位置**：系统设置页新增卡片，或独立「小程序配置」页
+- **字段**：
+  - API 域名 (apiDomain)：如 `https://soulapi.quwanzhi.com`
+  - 小程序 AppID (appId)：如 `wxb8bbb2b10dec74aa`
+  - 提现订阅模板 ID (withdrawSubscribeTmplId)
+  - 微信支付商户号 (mchId)（可选，后端也可用 env）
+  - 最低提现金额 (minWithdraw)（可与 referral_config 同步）
+- **存储**：POST /api/admin/settings 扩展，或 POST /api/db/config { key: 'mp_config', value: {...} }
+- **小程序**：app.js 启动时请求 config，若 mp_config 存在则覆盖 baseUrl；withdrawSubscribeTmplId 从 config 取
+
+### 任务 2：网站配置持久化（P1）
+
+- SitePage 保存时调用 POST /api/db/config，按 key 分别保存 site_config、page_config、menu_config
+- 或扩展 AdminSettingsPost 支持 site_config 等
+
+### 任务 3：支付/二维码配置接口（P1）
+
+- 方案 A：新增 POST /api/admin/config，支持 payment_methods、live_qr_codes 等 key
+- 方案 B：PaymentPage、QRCodesPage 改为调用 POST /api/db/config，body: { key, value }
+
+---
+
+## 七、附录：小程序页面与配置使用
+
+| 页面 | 使用的配置 | 接口 |
+|------|------------|------|
+| custom-tab-bar | features.matchEnabled | GET /api/miniprogram/config |
+| 阅读 read | freeChapters, prices | GET /api/miniprogram/config (chapterAccessManager) |
+| 找伙伴 match | matchTypes, freeMatchLimit, matchPrice | GET /api/miniprogram/match/config |
+| 我的 my | features, 收益/提现规则 | GET /api/miniprogram/config, referral/data |
+| 分销 referral | shareRate, minWithdraw, bindingDays | GET /api/miniprogram/referral/data |
+| 支付流程 | mchId (后端), openId | app.js 硬编码 + 后端 env |
diff --git a/开发文档/小程序提审自检清单_20260321.md b/开发文档/小程序提审自检清单_20260321.md
new file mode 100644
index 00000000..419c3c15
--- /dev/null
+++ b/开发文档/小程序提审自检清单_20260321.md
@@ -0,0 +1,35 @@
+# 小程序提审自检清单（2026-03-21）
+
+上传审核前在开发者工具内逐项勾选；本清单与当前代码约定一致。
+
+## 一、环境与域名
+
+- [ ] **正式版 `envVersion=release`**：`app.js` 的 `initApiBaseUrl()` 会强制 `baseUrl=https://soulapi.quwanzhi.com`，并清除本地误存的非生产 `apiBaseUrl`。
+- [ ] **微信公众平台**：request 合法域名、socket 合法域名、uploadFile/downloadFile 合法域名已包含生产 API 与 OSS/CDN（含 `at.alicdn.com` 字体若使用）。
+- [ ] **`project.config.json`**：`urlCheck: true`（仓库默认）；本地调试可用 `project.private.config.json` 覆盖为 `false`，**勿把 private 里长期关校验的配置提交为唯一来源**。
+
+## 二、隐私与权限声明
+
+- [ ] `app.json` 已配置 `__usePrivacyCheck__: true`。`requiredPrivateInfos` 仅允许位置类（`chooseAddress` 等）；**勿**写入 `getPhoneNumber`（新版开发者工具/校验会拒绝上传）。手机号能力靠 `<button open-type="getPhoneNumber|agreePrivacyAuthorization">` + 公众平台「用户隐私保护指引」声明。
+- [ ] 头像使用 `open-type="chooseAvatar"` + `bindchooseavatar`，勿使用已回收的 `wx.getUserProfile` 拉头像。
+- [ ] 保存海报：`saveImageToPhotosAlbum` 需在用户拒绝授权时有引导（已实现 `openSetting`）。
+
+## 三、审核敏感能力
+
+- [ ] **勿在 `app.json` 的 `pages` 中注册** `dev-login` 等开发绕过登录页；需要本地调试时临时加回路径即可。
+- [ ] **勿在正式包保留**「切换账号 / login-as / 假登录」等入口（已从设置页移除）。
+- [ ] 支付/虚拟商品：提审期可开 `auditMode`（后端配置）隐藏支付相关 UI。
+
+## 四、功能与兼容性
+
+- [ ] Canvas 2D 海报：`generatePoster` 在弹层展示后 `nextTick`/短延迟再取节点；`wx.canvasToTempFilePath` 传入页面实例 `this`。
+- [ ] `wx.getWindowInfo` 不可用时回退 `getSystemInfoSync().pixelRatio`（阅读页海报已处理）。
+- [ ] 真机测：登录、目录、阅读、一键手机号、海报保存相册、分享。
+
+## 五、体验版与开发版
+
+- `env-switch` 仅在非 `release` 显示；develop/trial 可通过悬浮球或 storage `apiBaseUrl` 指向本地/测试服。
+
+---
+
+**本轮已落地代码**：生产默认 API、`release` 强制生产、移除 `dev-login` 注册、设置页移除开发切换账号、声明 `getPhoneNumber`、`urlCheck` 默认开启、阅读页海报 Canvas 时序与 `canvasToTempFilePath` 修正。
diff --git a/开发文档/小程序管理/SKILL.md b/开发文档/小程序管理/SKILL.md
new file mode 100644
index 00000000..4645ec85
--- /dev/null
+++ b/开发文档/小程序管理/SKILL.md
@@ -0,0 +1,1797 @@
+# 小程序管理技能 v3.0
+
+> 📅 创建日期：2026-01-25
+> 📅 更新日期：2026-01-25（v3.0 全能版）
+> 📋 通过微信开放平台API完整管理小程序的全生命周期：申请、认证、开发、审核、发布、运营
+> 🚀 支持多小程序管理、一键部署、自动认证检查、汇总报告
+
+---
+
+## 🎯 能力全景图
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                        小程序管理技能 v3.0 能力全景图                           ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                               ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                        🔧 工具整合层                                  │    ║
+║   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │    ║
+║   │  │ 微信开发者  │  │ miniprogram │  │ 开放平台    │  │ GitHub    │  │    ║
+║   │  │ 工具 CLI    │  │ -ci (npm)   │  │ API         │  │ Actions   │  │    ║
+║   │  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘  │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                    │                                          ║
+║                                    ▼                                          ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                        📦 核心功能层                                  │    ║
+║   │                                                                       │    ║
+║   │   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐          │    ║
+║   │   │ 多小程序 │    │ 项目    │    │ 一键    │    │ 汇总    │          │    ║
+║   │   │ 管理    │    │ 检查    │    │ 部署    │    │ 报告    │          │    ║
+║   │   └─────────┘    └─────────┘    └─────────┘    └─────────┘          │    ║
+║   │                                                                       │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                    │                                          ║
+║                                    ▼                                          ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                        🚀 部署流程                                    │    ║
+║   │                                                                       │    ║
+║   │    ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐  │    ║
+║   │    │ 检查 │ → │ 编译 │ → │ 上传 │ → │ 提审 │ → │ 审核 │ → │ 发布 │  │    ║
+║   │    │check │   │build │   │upload│   │audit │   │wait  │   │release│  │    ║
+║   │    └──────┘   └──────┘   └──────┘   └──────┘   └──────┘   └──────┘  │    ║
+║   │       │          │          │          │          │          │       │    ║
+║   │       ▼          ▼          ▼          ▼          ▼          ▼       │    ║
+║   │    自动化      自动化     自动化     自动化     等待      手动/自动  │    ║
+║   │                                                1-7天               │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                                                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 📊 命令速查表
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `mp_full.py report` | 生成所有小程序汇总报告 | `python3 mp_full.py report` |
+| `mp_full.py check` | 检查项目问题 | `python3 mp_full.py check soul-party` |
+| `mp_full.py auto` | 全自动部署（上传+提审） | `python3 mp_full.py auto soul-party` |
+| `mp_deploy.py list` | 列出所有小程序 | `python3 mp_deploy.py list` |
+| `mp_deploy.py add` | 添加新小程序 | `python3 mp_deploy.py add` |
+| `mp_deploy.py cert-status` | 查询认证状态 | `python3 mp_deploy.py cert-status soul-party` |
+| `mp_deploy.py cert-done` | 标记认证完成 | `python3 mp_deploy.py cert-done soul-party` |
+| `mp_deploy.py release` | 发布上线 | `python3 mp_deploy.py release soul-party` |
+
+---
+
+## 🎯 技能概述
+
+本技能用于通过API实现微信小程序的完整管理，包括：
+
+### 核心能力
+
+| 阶段 | 能力 | 说明 |
+|------|------|------|
+| **申请** | 快速注册小程序 | 复用公众号主体资质，无需300元认证费 |
+| **认证** | 企业认证管理 | 自动检查认证状态、提醒过期、材料管理 |
+| **配置** | 基础信息设置 | 名称、头像、介绍、类目管理 |
+| **开发** | 代码管理 | 上传代码、生成体验版 |
+| **审核** | 提审发布 | 提交审核、查询状态、撤回、发布 |
+| **运营** | 接口管理 | 域名配置、隐私协议、接口权限 |
+| **推广** | 小程序码 | 生成无限量小程序码 |
+| **数据** | 数据分析 | 访问数据、用户画像 |
+
+### v2.0 新增能力
+
+| 能力 | 命令 | 说明 |
+|------|------|------|
+| **多小程序管理** | `mp_deploy.py list` | 统一管理多个小程序 |
+| **一键部署** | `mp_deploy.py deploy <id>` | 编译→上传→提审一步完成 |
+| **认证管理** | `mp_deploy.py cert <id>` | 认证状态检查、材料管理 |
+| **快速上传** | `mp_deploy.py upload <id>` | 快速上传代码到开发版 |
+
+### 开源工具集成
+
+| 工具 | 用途 | 安装方式 |
+|------|------|----------|
+| **miniprogram-ci** | 微信官方CI工具 | `npm install miniprogram-ci -g` |
+| **微信开发者工具CLI** | 本地编译上传 | 安装开发者工具自带 |
+| **multi-mini-ci** | 多平台小程序上传 | GitHub开源 |
+
+---
+
+## 🚀 触发词
+
+- 管理小程序
+- 小程序申请
+- 小程序审核
+- 小程序发布
+- 上传小程序代码
+- 配置小程序域名
+- 生成小程序码
+- 查看小程序状态
+
+---
+
+## 🏗️ 技术架构
+
+### 管理方式对比
+
+| 方式 | 优点 | 缺点 | 适用场景 |
+|------|------|------|----------|
+| **微信后台手动操作** | 无需开发 | 效率低，无法批量 | 单个小程序 |
+| **微信开发者工具CLI** | 简单易用 | 功能有限 | 开发测试 |
+| **开放平台API（本方案）** | 功能完整、可自动化 | 需要开发 | 批量管理、自动化 |
+
+### 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          小程序管理引擎 v1.0                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                          第一层：认证层                               │   │
+│   │  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐       │   │
+│   │  │ 第三方平台    │    │  component_   │    │ authorizer_   │       │   │
+│   │  │ 认证信息      │ →  │  access_token │ →  │ access_token  │       │   │
+│   │  └───────────────┘    └───────────────┘    └───────────────┘       │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                      ↓                                       │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                          第二层：管理API层                            │   │
+│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │   │
+│   │  │ 注册    │ │ 配置    │ │ 代码    │ │ 审核    │ │ 运营    │       │   │
+│   │  │ 管理    │ │ 管理    │ │ 管理    │ │ 管理    │ │ 管理    │       │   │
+│   │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘       │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                      ↓                                       │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                          第三层：本地CLI层                            │   │
+│   │  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐       │   │
+│   │  │ mp_manager.py │    │  微信开发者    │    │  自动化脚本   │       │   │
+│   │  │ Python CLI    │    │  工具 CLI     │    │  Shell       │       │   │
+│   │  └───────────────┘    └───────────────┘    └───────────────┘       │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📋 前置条件
+
+### 1. 微信开放平台账号
+
+- 注册地址：https://open.weixin.qq.com/
+- 完成开发者资质认证（需企业资质）
+
+### 2. 创建第三方平台
+
+登录开放平台后台 → 管理中心 → 第三方平台 → 创建
+
+**必填信息**：
+- 平台名称
+- 服务类型（选择"平台型"可管理多个小程序）
+- 授权发起页域名
+- 消息与事件接收URL
+
+### 3. 获取关键凭证
+
+| 凭证 | 说明 | 获取方式 |
+|------|------|----------|
+| `component_appid` | 第三方平台AppID | 开放平台后台 |
+| `component_appsecret` | 第三方平台密钥 | 开放平台后台 |
+| `component_verify_ticket` | 验证票据 | 微信每10分钟推送 |
+| `component_access_token` | 平台调用凭证 | API获取，2小时有效 |
+| `authorizer_access_token` | 授权方调用凭证 | API获取，2小时有效 |
+
+---
+
+## 🔑 认证流程
+
+### 获取 component_access_token
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/component/api_component_token
+{
+    "component_appid": "你的第三方平台AppID",
+    "component_appsecret": "你的第三方平台密钥",
+    "component_verify_ticket": "微信推送的验证票据"
+}
+
+# 返回
+{
+    "component_access_token": "xxxx",
+    "expires_in": 7200
+}
+```
+
+### 获取预授权码
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/component/api_create_preauthcode
+{
+    "component_appid": "你的第三方平台AppID"
+}
+
+# 返回
+{
+    "pre_auth_code": "xxxx",
+    "expires_in": 600
+}
+```
+
+### 引导用户授权
+
+```
+https://mp.weixin.qq.com/cgi-bin/componentloginpage?
+component_appid=第三方平台AppID&
+pre_auth_code=预授权码&
+redirect_uri=授权回调地址&
+auth_type=1  # 1=仅小程序，2=仅公众号，3=两者都可
+```
+
+### 获取 authorizer_access_token
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/component/api_query_auth
+{
+    "component_appid": "第三方平台AppID",
+    "authorization_code": "授权回调返回的code"
+}
+
+# 返回
+{
+    "authorization_info": {
+        "authorizer_appid": "授权方AppID",
+        "authorizer_access_token": "授权方调用凭证",
+        "expires_in": 7200,
+        "authorizer_refresh_token": "刷新令牌"
+    }
+}
+```
+
+---
+
+## 📱 核心API接口
+
+### 一、小程序注册
+
+#### 1.1 复用公众号资质快速注册
+
+**前提**：已有认证的公众号
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/account/fastregister?access_token=ACCESS_TOKEN
+{
+    "ticket": "公众号扫码授权的ticket"
+}
+
+# 返回
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "appid": "新注册的小程序AppID",
+    "authorization_code": "授权码"
+}
+```
+
+**优势**：
+- 无需重新提交主体材料
+- 无需对公打款
+- 无需支付300元认证费
+
+**限制**：
+- 非个体户：每月可注册5个
+- 个体户：每月可注册1个
+
+#### 1.2 快速注册企业小程序
+
+**前提**：有企业营业执照
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/component/fastregisterminiprogram
+{
+    "name": "小程序名称",
+    "code": "统一社会信用代码",
+    "code_type": 1,  # 1=营业执照
+    "legal_persona_wechat": "法人微信号",
+    "legal_persona_name": "法人姓名",
+    "component_phone": "联系电话"
+}
+```
+
+---
+
+### 二、基础信息配置
+
+#### 2.1 获取基础信息
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/account/getaccountbasicinfo
+# 无请求参数
+
+# 返回
+{
+    "appid": "小程序AppID",
+    "account_type": 2,  # 2=小程序
+    "principal_type": 1,  # 1=企业
+    "principal_name": "主体名称",
+    "realname_status": 1,  # 1=已认证
+    "nickname": "小程序名称",
+    "head_image_url": "头像URL",
+    "signature": "简介"
+}
+```
+
+#### 2.2 修改名称
+
+```python
+# POST https://api.weixin.qq.com/wxa/setnickname?access_token=ACCESS_TOKEN
+{
+    "nick_name": "新名称",
+    "id_card": "管理员身份证号",
+    "license": "营业执照media_id",  # 需要先上传
+    "naming_other_stuff_1": "其他证明material_id"  # 可选
+}
+```
+
+#### 2.3 修改头像
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/account/modifyheadimage?access_token=ACCESS_TOKEN
+{
+    "head_img_media_id": "头像图片media_id",  # 需要先上传
+    "x1": 0, "y1": 0, "x2": 1, "y2": 1  # 裁剪区域
+}
+```
+
+#### 2.4 修改简介
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/account/modifysignature?access_token=ACCESS_TOKEN
+{
+    "signature": "新的简介内容"  # 4-120字
+}
+```
+
+---
+
+### 三、类目管理
+
+#### 3.1 获取可选类目
+
+```python
+# GET https://api.weixin.qq.com/cgi-bin/wxopen/getallcategories?access_token=ACCESS_TOKEN
+```
+
+#### 3.2 获取已设置类目
+
+```python
+# GET https://api.weixin.qq.com/cgi-bin/wxopen/getcategory?access_token=ACCESS_TOKEN
+```
+
+#### 3.3 添加类目
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/wxopen/addcategory?access_token=ACCESS_TOKEN
+{
+    "categories": [
+        {
+            "first": 1,     # 一级类目ID
+            "second": 2,    # 二级类目ID
+            "certicates": [ # 资质证明
+                {"key": "资质名称", "value": "media_id"}
+            ]
+        }
+    ]
+}
+```
+
+#### 3.4 删除类目
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/wxopen/deletecategory?access_token=ACCESS_TOKEN
+{
+    "first": 1,
+    "second": 2
+}
+```
+
+---
+
+### 四、域名配置
+
+#### 4.1 设置服务器域名
+
+```python
+# POST https://api.weixin.qq.com/wxa/modify_domain?access_token=ACCESS_TOKEN
+{
+    "action": "set",  # add/delete/set/get
+    "requestdomain": ["https://api.example.com"],
+    "wsrequestdomain": ["wss://ws.example.com"],
+    "uploaddomain": ["https://upload.example.com"],
+    "downloaddomain": ["https://download.example.com"],
+    "udpdomain": ["udp://udp.example.com"],
+    "tcpdomain": ["tcp://tcp.example.com"]
+}
+```
+
+#### 4.2 设置业务域名
+
+```python
+# POST https://api.weixin.qq.com/wxa/setwebviewdomain?access_token=ACCESS_TOKEN
+{
+    "action": "set",  # add/delete/set/get
+    "webviewdomain": ["https://web.example.com"]
+}
+```
+
+---
+
+### 五、隐私协议配置
+
+#### 5.1 获取隐私协议设置
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/component/getprivacysetting?access_token=ACCESS_TOKEN
+{
+    "privacy_ver": 2  # 1=当前版本，2=开发版本
+}
+```
+
+#### 5.2 设置隐私协议
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/component/setprivacysetting?access_token=ACCESS_TOKEN
+{
+    "privacy_ver": 2,
+    "setting_list": [
+        {
+            "privacy_key": "UserInfo",
+            "privacy_text": "用于展示用户头像和昵称"
+        },
+        {
+            "privacy_key": "Location",
+            "privacy_text": "用于获取您的位置信息以推荐附近服务"
+        },
+        {
+            "privacy_key": "PhoneNumber",
+            "privacy_text": "用于登录验证和订单通知"
+        }
+    ],
+    "owner_setting": {
+        "contact_email": "contact@example.com",
+        "contact_phone": "15880802661",
+        "notice_method": "弹窗提示"
+    }
+}
+```
+
+**常用隐私字段**：
+
+| privacy_key | 说明 |
+|-------------|------|
+| `UserInfo` | 用户信息（头像、昵称） |
+| `Location` | 地理位置 |
+| `PhoneNumber` | 手机号 |
+| `Album` | 相册 |
+| `Camera` | 相机 |
+| `Record` | 麦克风 |
+| `Clipboard` | 剪切板 |
+| `MessageFile` | 微信消息中的文件 |
+| `ChooseAddress` | 收货地址 |
+| `BluetoothInfo` | 蓝牙 |
+
+---
+
+### 六、代码管理
+
+#### 6.1 上传代码
+
+```python
+# POST https://api.weixin.qq.com/wxa/commit?access_token=ACCESS_TOKEN
+{
+    "template_id": 1,  # 代码模板ID
+    "ext_json": "{\"extAppid\":\"授权方AppID\",\"ext\":{}}",
+    "user_version": "1.0.0",
+    "user_desc": "版本描述"
+}
+```
+
+**注意**：需要先在第三方平台创建代码模板
+
+#### 6.2 获取体验版二维码
+
+```python
+# GET https://api.weixin.qq.com/wxa/get_qrcode?access_token=ACCESS_TOKEN&path=pages/index/index
+# 返回二维码图片
+```
+
+#### 6.3 获取已上传的代码页面列表
+
+```python
+# GET https://api.weixin.qq.com/wxa/get_page?access_token=ACCESS_TOKEN
+
+# 返回
+{
+    "errcode": 0,
+    "page_list": ["pages/index/index", "pages/my/my"]
+}
+```
+
+---
+
+### 七、审核管理
+
+#### 7.1 提交审核
+
+```python
+# POST https://api.weixin.qq.com/wxa/submit_audit?access_token=ACCESS_TOKEN
+{
+    "item_list": [
+        {
+            "address": "pages/index/index",
+            "tag": "电子书 阅读 创业",
+            "first_class": "教育",
+            "second_class": "在线教育",
+            "first_id": 1,
+            "second_id": 2,
+            "title": "首页"
+        }
+    ],
+    "preview_info": {
+        "video_id_list": [],
+        "pic_id_list": []
+    },
+    "version_desc": "版本说明",
+    "feedback_info": "反馈内容",
+    "feedback_stuff": "media_id"  # 反馈附件
+}
+```
+
+#### 7.2 查询审核状态
+
+```python
+# POST https://api.weixin.qq.com/wxa/get_auditstatus?access_token=ACCESS_TOKEN
+{
+    "auditid": 1234567890
+}
+
+# 返回
+{
+    "errcode": 0,
+    "status": 0,  # 0=审核成功，1=审核被拒，2=审核中，3=已撤回，4=审核延后
+    "reason": "拒绝原因",  # status=1时返回
+    "screenshot": "截图"
+}
+```
+
+#### 7.3 查询最新审核状态
+
+```python
+# GET https://api.weixin.qq.com/wxa/get_latest_auditstatus?access_token=ACCESS_TOKEN
+```
+
+#### 7.4 撤回审核
+
+```python
+# GET https://api.weixin.qq.com/wxa/undocodeaudit?access_token=ACCESS_TOKEN
+```
+
+**限制**：单个小程序每天只能撤回1次
+
+---
+
+### 八、发布管理
+
+#### 8.1 发布已审核通过的版本
+
+```python
+# POST https://api.weixin.qq.com/wxa/release?access_token=ACCESS_TOKEN
+{}  # 无请求参数
+
+# 返回
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+#### 8.2 版本回退
+
+```python
+# GET https://api.weixin.qq.com/wxa/revertcoderelease?access_token=ACCESS_TOKEN
+```
+
+**限制**：只能回退到上一个版本，且只能回退一次
+
+#### 8.3 获取可回退版本历史
+
+```python
+# GET https://api.weixin.qq.com/wxa/revertcoderelease?access_token=ACCESS_TOKEN&action=get_history_version
+```
+
+#### 8.4 分阶段发布
+
+```python
+# POST https://api.weixin.qq.com/wxa/grayrelease?access_token=ACCESS_TOKEN
+{
+    "gray_percentage": 10  # 灰度比例 1-100
+}
+```
+
+---
+
+### 九、小程序码生成
+
+#### 9.1 获取小程序码（有限制）
+
+```python
+# POST https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN
+{
+    "path": "pages/index/index?scene=123",
+    "width": 430,
+    "auto_color": false,
+    "line_color": {"r": 0, "g": 0, "b": 0},
+    "is_hyaline": false  # 是否透明背景
+}
+# 返回图片二进制
+```
+
+**限制**：每个path只能生成10万个
+
+#### 9.2 获取无限小程序码（推荐）
+
+```python
+# POST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN
+{
+    "scene": "user_id=123&from=share",  # 最长32字符
+    "page": "pages/index/index",  # 必须是已发布的页面
+    "width": 430,
+    "auto_color": false,
+    "line_color": {"r": 0, "g": 0, "b": 0},
+    "is_hyaline": false
+}
+# 返回图片二进制
+```
+
+**注意**：scene参数需要在小程序中用`onLoad(options)`解析
+
+#### 9.3 生成小程序短链接
+
+```python
+# POST https://api.weixin.qq.com/wxa/genwxashortlink?access_token=ACCESS_TOKEN
+{
+    "page_url": "pages/index/index?id=123",
+    "page_title": "页面标题",
+    "is_permanent": false  # 是否永久有效
+}
+
+# 返回
+{
+    "errcode": 0,
+    "link": "https://wxaurl.cn/xxxx"
+}
+```
+
+---
+
+### 十、接口权限管理
+
+#### 10.1 查询接口调用额度
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/openapi/quota/get?access_token=ACCESS_TOKEN
+{
+    "cgi_path": "/wxa/getwxacode"
+}
+
+# 返回
+{
+    "quota": {
+        "daily_limit": 100000,
+        "used": 500,
+        "remain": 99500
+    }
+}
+```
+
+#### 10.2 重置接口调用次数
+
+```python
+# POST https://api.weixin.qq.com/cgi-bin/clear_quota?access_token=ACCESS_TOKEN
+{
+    "appid": "小程序AppID"
+}
+```
+
+**限制**：每月只能重置10次
+
+---
+
+### 十一、数据分析
+
+#### 11.1 获取访问趋势
+
+```python
+# POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN
+{
+    "begin_date": "20260101",
+    "end_date": "20260125"
+}
+
+# 返回
+{
+    "list": [
+        {
+            "ref_date": "20260125",
+            "session_cnt": 1000,      # 打开次数
+            "visit_pv": 5000,         # 访问次数
+            "visit_uv": 800,          # 访问人数
+            "visit_uv_new": 100,      # 新用户数
+            "stay_time_uv": 120.5,    # 人均停留时长（秒）
+            "stay_time_session": 60.2 # 次均停留时长（秒）
+        }
+    ]
+}
+```
+
+#### 11.2 获取用户画像
+
+```python
+# POST https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN
+{
+    "begin_date": "20260101",
+    "end_date": "20260125"
+}
+```
+
+---
+
+## 🛠️ 快速使用
+
+### 方式一：使用Python管理脚本（推荐）
+
+```bash
+# 进入脚本目录
+cd /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/小程序管理/scripts
+
+# 安装依赖
+pip install httpx python-dotenv
+
+# 配置凭证
+cp .env.example .env
+# 编辑 .env 填入你的凭证
+
+# 使用命令行工具
+python mp_manager.py status    # 查看小程序状态
+python mp_manager.py audit     # 查看审核状态
+python mp_manager.py release   # 发布上线
+python mp_manager.py qrcode    # 生成小程序码
+```
+
+### 方式二：使用微信开发者工具CLI
+
+```bash
+# CLI路径
+CLI="/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
+
+# 打开项目
+$CLI -o "/path/to/miniprogram"
+
+# 编译
+$CLI build-npm --project "/path/to/miniprogram"
+
+# 预览（生成二维码）
+$CLI preview --project "/path/to/miniprogram" --qr-format image --qr-output preview.png
+
+# 上传代码
+$CLI upload --project "/path/to/miniprogram" --version "1.0.0" --desc "版本说明"
+
+# 提交审核
+$CLI submit-audit --project "/path/to/miniprogram"
+```
+
+### 方式三：直接调用API
+
+```python
+import httpx
+
+# 配置
+ACCESS_TOKEN = "你的access_token"
+BASE_URL = "https://api.weixin.qq.com"
+
+async def check_audit_status(auditid: int):
+    """查询审核状态"""
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{BASE_URL}/wxa/get_auditstatus?access_token={ACCESS_TOKEN}",
+            json={"auditid": auditid}
+        )
+        return resp.json()
+
+# 使用
+result = await check_audit_status(1234567890)
+print(result)
+```
+
+---
+
+## 📁 文件结构
+
+```
+小程序管理/
+├── SKILL.md                        # 技能说明文档（本文件）
+├── scripts/
+│   ├── mp_manager.py               # 小程序管理CLI工具
+│   ├── mp_api.py                   # API封装类
+│   ├── requirements.txt            # Python依赖
+│   └── .env.example                # 环境变量模板
+└── references/
+    ├── API接口速查表.md             # 常用API速查
+    ├── 隐私协议填写指南.md           # 隐私协议配置指南
+    └── 审核规范.md                  # 审核常见问题
+```
+
+---
+
+## ⚠️ 常见问题
+
+### Q1: 如何获取 component_verify_ticket？
+
+微信会每10分钟向你配置的"消息与事件接收URL"推送。你需要部署一个服务来接收并存储它。
+
+```python
+# 接收推送示例
+@app.post("/callback")
+async def receive_ticket(request: Request):
+    xml_data = await request.body()
+    # 解密并解析XML
+    # 提取 ComponentVerifyTicket
+    # 存储到Redis或数据库
+    return "success"
+```
+
+### Q2: 审核被拒常见原因？
+
+| 原因 | 解决方案 |
+|------|----------|
+| 类目不符 | 确保小程序功能与所选类目一致 |
+| 隐私协议缺失 | 配置完整的隐私保护指引 |
+| 诱导分享 | 移除"分享到群获取xx"等诱导文案 |
+| 虚拟支付 | iOS不能使用虚拟支付，需走IAP |
+| 内容违规 | 检查文案、图片是否合规 |
+| 功能不完整 | 确保所有页面功能正常 |
+
+### Q3: 审核需要多长时间？
+
+- 首次提审：1-7个工作日
+- 非首次：1-3个工作日
+- 加急审核：付费服务，24小时内
+
+### Q4: 如何提高审核通过率？
+
+1. **提交完整测试账号**：如需登录才能体验功能
+2. **录制操作视频**：复杂功能建议附上操作视频
+3. **详细的版本描述**：说明本次更新内容
+4. **完善隐私协议**：所有收集数据的接口都要说明用途
+
+### Q5: 代码模板是什么？
+
+第三方平台需要先将小程序代码上传到"草稿箱"，再添加到"代码模板库"。之后可以用这个模板批量部署到多个小程序。
+
+流程：开发完成 → 上传到草稿箱 → 添加到模板库 → 使用模板部署
+
+---
+
+## 🔗 官方文档
+
+- [微信开放平台文档](https://developers.weixin.qq.com/doc/oplatform/)
+- [第三方平台开发指南](https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/getting_started/how_to_read.html)
+- [小程序管理接口](https://developers.weixin.qq.com/doc/oplatform/openApi/OpenApiDoc/)
+- [代码管理接口](https://developers.weixin.qq.com/doc/oplatform/openApi/OpenApiDoc/miniprogram-management/code-management/commit.html)
+- [隐私协议开发指南](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/)
+
+---
+
+## 📊 当前项目配置
+
+### Soul派对小程序
+
+| 项目 | 配置值 |
+|------|--------|
+| **AppID** | `wxb8bbb2b10dec74aa` |
+| **项目路径** | `/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram` |
+| **API域名** | `https://soul.quwanzhi.com` |
+| **当前版本** | `1.0.13` |
+| **认证状态** | ⏳ 审核中（等待1-5工作日） |
+| **检查结果** | ✅ 8项通过 / ⚠️ 2项警告 / ❌ 0项错误 |
+| **可上传** | ✅ 是 |
+| **可发布** | ❌ 需等待认证通过 |
+
+### 快速命令
+
+```bash
+# 打开项目
+/Applications/wechatwebdevtools.app/Contents/MacOS/cli -o "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram"
+
+# 预览
+/Applications/wechatwebdevtools.app/Contents/MacOS/cli preview --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" --qr-format image --qr-output preview.png
+
+# 上传
+/Applications/wechatwebdevtools.app/Contents/MacOS/cli upload --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" --version "1.0.0" --desc "版本说明"
+```
+
+---
+
+## 🚀 全自动部署流程（v3.0）
+
+### 完整生命周期流程图
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                        小程序完整生命周期管理                                   ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                               ║
+║   阶段一：准备阶段                                                             ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                                                                       │    ║
+║   │    ┌──────────┐      ┌──────────┐      ┌──────────┐                  │    ║
+║   │    │ 注册小程序│  →   │ 企业认证  │  →   │ 配置项目  │                  │    ║
+║   │    │ (微信后台)│      │ (300元/年)│      │ (添加到管理)│                 │    ║
+║   │    └──────────┘      └──────────┘      └──────────┘                  │    ║
+║   │         │                  │                  │                       │    ║
+║   │         │                  │                  ▼                       │    ║
+║   │         │                  │         mp_deploy.py add                │    ║
+║   │         │                  ▼                                          │    ║
+║   │         │         等待审核 1-5 天                                      │    ║
+║   │         │         mp_deploy.py cert-done                             │    ║
+║   │                                                                       │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                    │                                          ║
+║                                    ▼                                          ║
+║   阶段二：开发阶段                                                             ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                                                                       │    ║
+║   │    ┌──────────┐      ┌──────────┐      ┌──────────┐                  │    ║
+║   │    │ 编写代码  │  →   │ 本地测试  │  →   │ 项目检查  │                  │    ║
+║   │    │ (开发者)  │      │ (模拟器)  │      │ mp_full   │                  │    ║
+║   │    └──────────┘      └──────────┘      └──────────┘                  │    ║
+║   │                                               │                       │    ║
+║   │                                               ▼                       │    ║
+║   │                                    mp_full.py check <id>             │    ║
+║   │                                    检查: 配置/域名/隐私/认证          │    ║
+║   │                                                                       │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                    │                                          ║
+║                                    ▼                                          ║
+║   阶段三：部署阶段（全自动）                                                    ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                                                                       │    ║
+║   │         mp_full.py auto <id> -v "1.0.0" -d "版本描述"                │    ║
+║   │                              │                                        │    ║
+║   │                              ▼                                        │    ║
+║   │    ┌──────────┐      ┌──────────┐      ┌──────────┐                  │    ║
+║   │    │ ① 检查   │  →   │ ② 上传   │  →   │ ③ 提审   │                  │    ║
+║   │    │ 项目问题  │      │ 代码到微信│      │ 提交审核  │                  │    ║
+║   │    └──────────┘      └──────────┘      └──────────┘                  │    ║
+║   │         │                  │                  │                       │    ║
+║   │         ▼                  ▼                  ▼                       │    ║
+║   │    自动检测           使用CLI/npm         已认证→API提审             │    ║
+║   │    配置/认证/域名      优先级选择          未认证→手动提审            │    ║
+║   │                                                                       │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                    │                                          ║
+║                                    ▼                                          ║
+║   阶段四：发布阶段                                                             ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                                                                       │    ║
+║   │    ┌──────────┐      ┌──────────┐      ┌──────────┐                  │    ║
+║   │    │ 等待审核  │  →   │ 审核通过  │  →   │ 发布上线  │                  │    ║
+║   │    │ 1-7工作日 │      │ 通知     │      │ release  │                  │    ║
+║   │    └──────────┘      └──────────┘      └──────────┘                  │    ║
+║   │                                               │                       │    ║
+║   │                                               ▼                       │    ║
+║   │                                    mp_deploy.py release <id>         │    ║
+║   │                                    或 微信后台点击发布                │    ║
+║   │                                                                       │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                    │                                          ║
+║                                    ▼                                          ║
+║   阶段五：运营阶段                                                             ║
+║   ┌─────────────────────────────────────────────────────────────────────┐    ║
+║   │                                                                       │    ║
+║   │    ┌──────────┐      ┌──────────┐      ┌──────────┐                  │    ║
+║   │    │ 数据分析  │      │ 汇总报告  │      │ 版本迭代  │                  │    ║
+║   │    │ mp_manager│      │ mp_full   │      │ 循环部署  │                  │    ║
+║   │    └──────────┘      └──────────┘      └──────────┘                  │    ║
+║   │         │                  │                  │                       │    ║
+║   │         ▼                  ▼                  ▼                       │    ║
+║   │    data命令          report命令         返回部署阶段                 │    ║
+║   │                                                                       │    ║
+║   └─────────────────────────────────────────────────────────────────────┘    ║
+║                                                                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+### 工具整合架构图
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│                           小程序管理工具整合架构                              │
+├────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐  │
+│   │                         用户命令层                                    │  │
+│   │   mp_full.py report  │  mp_full.py check  │  mp_full.py auto        │  │
+│   │   mp_deploy.py list  │  mp_deploy.py cert │  mp_manager.py status   │  │
+│   └─────────────────────────────────────────────────────────────────────┘  │
+│                                    │                                        │
+│                                    ▼                                        │
+│   ┌─────────────────────────────────────────────────────────────────────┐  │
+│   │                         Python 管理层                                 │  │
+│   │   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐         │  │
+│   │   │ mp_full.py    │   │ mp_deploy.py  │   │ mp_api.py     │         │  │
+│   │   │ 全能管理器    │   │ 部署工具      │   │ API封装       │         │  │
+│   │   │ • 检查        │   │ • 多小程序    │   │ • 认证        │         │  │
+│   │   │ • 报告        │   │ • 认证管理    │   │ • 审核        │         │  │
+│   │   │ • 自动部署    │   │ • 发布        │   │ • 发布        │         │  │
+│   │   └───────────────┘   └───────────────┘   └───────────────┘         │  │
+│   └─────────────────────────────────────────────────────────────────────┘  │
+│                                    │                                        │
+│                                    ▼                                        │
+│   ┌─────────────────────────────────────────────────────────────────────┐  │
+│   │                         外部工具层                                    │  │
+│   │   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐         │  │
+│   │   │ 微信开发者    │   │ miniprogram   │   │ 微信开放平台  │         │  │
+│   │   │ 工具 CLI      │   │ -ci (npm)     │   │ API           │         │  │
+│   │   │               │   │               │   │               │         │  │
+│   │   │ • 打开项目    │   │ • 上传代码    │   │ • 提交审核    │         │  │
+│   │   │ • 预览        │   │ • 预览        │   │ • 发布        │         │  │
+│   │   │ • 上传        │   │ • 构建npm     │   │ • 认证管理    │         │  │
+│   │   │ • 编译        │   │ • sourceMap   │   │ • 数据分析    │         │  │
+│   │   └───────────────┘   └───────────────┘   └───────────────┘         │  │
+│   │          │                    │                    │                 │  │
+│   │          ▼                    ▼                    ▼                 │  │
+│   │    优先级: 1            优先级: 2            优先级: 3               │  │
+│   │    (无需密钥)           (需要密钥)           (需要token)             │  │
+│   └─────────────────────────────────────────────────────────────────────┘  │
+│                                                                             │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 快速开始
+
+```bash
+# 进入脚本目录
+cd /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/小程序管理/scripts
+
+# 1. 查看已配置的小程序
+python3 mp_deploy.py list
+
+# 2. 添加新小程序（交互式）
+python3 mp_deploy.py add
+
+# 3. 检查认证状态
+python3 mp_deploy.py cert-status soul-party
+
+# 4. 一键部署
+python3 mp_deploy.py deploy soul-party
+
+# 5. 审核通过后发布
+python3 mp_deploy.py release soul-party
+```
+
+### 命令速查
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `list` | 列出所有小程序 | `python3 mp_deploy.py list` |
+| `add` | 添加新小程序 | `python3 mp_deploy.py add` |
+| `deploy` | 一键部署 | `python3 mp_deploy.py deploy soul-party` |
+| `upload` | 仅上传代码 | `python3 mp_deploy.py upload soul-party` |
+| `cert` | 提交认证 | `python3 mp_deploy.py cert soul-party` |
+| `cert-status` | 查询认证状态 | `python3 mp_deploy.py cert-status soul-party` |
+| `cert-done` | 标记认证完成 | `python3 mp_deploy.py cert-done soul-party` |
+| `release` | 发布上线 | `python3 mp_deploy.py release soul-party` |
+
+---
+
+## 📋 企业认证详解
+
+### 认证流程图
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      企业认证流程                              │
+├──────────────────────────────────────────────────────────────┤
+│                                                               │
+│   ┌─────────┐     ┌─────────┐     ┌─────────┐               │
+│   │ 准备    │ →   │ 提交    │ →   │ 审核    │               │
+│   │ 材料    │     │ 认证    │     │ 等待    │               │
+│   └─────────┘     └─────────┘     └─────────┘               │
+│        │               │               │                     │
+│        ↓               ↓               ↓                     │
+│   ┌─────────────────────────────────────────┐               │
+│   │ • 营业执照       • 微信后台上传    • 1-5工作日  │               │
+│   │ • 法人身份证     • 法人扫码验证    • 审核结果   │               │
+│   │ • 法人微信号     • 支付300元       • 通知       │               │
+│   └─────────────────────────────────────────┘               │
+│                                                               │
+│   ⚠️ 认证有效期：1年，到期需年审                               │
+│                                                               │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 认证材料清单
+
+| 材料 | 必需 | 说明 |
+|------|------|------|
+| 企业营业执照 | ✅ | 扫描件或照片，信息清晰 |
+| 法人身份证 | ✅ | 正反面照片 |
+| 法人微信号 | ✅ | 需绑定银行卡，用于扫码验证 |
+| 联系人手机号 | ✅ | 接收审核通知 |
+| 认证费用 | ✅ | 300元/年 |
+| 其他资质 | 可选 | 特殊行业需要（如医疗、金融） |
+
+### 认证状态说明
+
+| 状态 | 说明 | 下一步操作 |
+|------|------|------------|
+| `unknown` | 未知/未检查 | 运行 `cert-status` 检查 |
+| `pending` | 审核中 | 等待1-5个工作日 |
+| `verified` | 已认证 | 可以正常发布 |
+| `rejected` | 被拒绝 | 查看原因，修改后重新提交 |
+| `expired` | 已过期 | 需要重新认证（年审） |
+
+### 认证API（第三方平台）
+
+如果你有第三方平台资质，可以通过API代商家提交认证：
+
+```python
+# POST https://api.weixin.qq.com/wxa/sec/wxaauth?access_token=ACCESS_TOKEN
+{
+    "auth_type": 1,  # 1=企业
+    "auth_data": {
+        "name": "企业名称",
+        "code": "统一社会信用代码",
+        "legal_persona_wechat": "法人微信号",
+        "legal_persona_name": "法人姓名",
+        "legal_persona_idcard": "法人身份证号",
+        "component_phone": "联系电话"
+    }
+}
+```
+
+---
+
+## 🔧 GitHub开源工具推荐
+
+### 1. miniprogram-ci（官方）
+
+微信官方提供的CI工具，支持Node.js环境使用。
+
+**安装**：
+```bash
+npm install miniprogram-ci -g
+```
+
+**使用**：
+```javascript
+const ci = require('miniprogram-ci');
+
+const project = new ci.Project({
+  appid: 'wxb8bbb2b10dec74aa',
+  type: 'miniProgram',
+  projectPath: '/path/to/miniprogram',
+  privateKeyPath: '/path/to/private.key',
+  ignores: ['node_modules/**/*']
+});
+
+// 上传
+await ci.upload({
+  project,
+  version: '1.0.0',
+  desc: '版本描述',
+  setting: {
+    es6: true,
+    minify: true
+  }
+});
+```
+
+**获取私钥**：
+1. 登录小程序后台
+2. 开发管理 → 开发设置
+3. 小程序代码上传密钥 → 下载
+
+### 2. multi-mini-ci
+
+多平台小程序自动化上传工具。
+
+**GitHub**: https://github.com/Ethan-zjc/multi-mini-ci
+
+**支持平台**：
+- 微信小程序
+- 支付宝小程序
+- 百度小程序
+- 字节跳动小程序
+
+### 3. GitHub Actions集成
+
+在项目中创建 `.github/workflows/deploy.yml`：
+
+```yaml
+name: Deploy MiniProgram
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Upload to WeChat
+        env:
+          PRIVATE_KEY: ${{ secrets.MINIPROGRAM_PRIVATE_KEY }}
+        run: |
+          echo "$PRIVATE_KEY" > private.key
+          npx miniprogram-ci upload \
+            --pp ./dist \
+            --pkp ./private.key \
+            --appid wxb8bbb2b10dec74aa \
+            --uv "1.0.${{ github.run_number }}" \
+            -r 1 \
+            --desc "CI auto deploy"
+```
+
+---
+
+## 📁 完整文件结构（v3.0）
+
+```
+小程序管理/
+├── SKILL.md                        # 技能说明文档（本文件）
+├── scripts/
+│   ├── mp_full.py                  # 全能管理工具（推荐）⭐
+│   ├── mp_deploy.py                # 部署工具（多小程序管理）
+│   ├── mp_manager.py               # API管理工具（基础版）
+│   ├── mp_api.py                   # API封装类（Python SDK）
+│   ├── apps_config.json            # 多小程序配置文件
+│   ├── requirements.txt            # Python依赖
+│   ├── env_template.txt            # 环境变量模板
+│   └── reports/                    # 检查报告存放目录
+│       ├── summary_*.json          # 汇总报告
+│       └── report_*.json           # 项目报告
+└── references/
+    ├── API接口速查表.md             # 常用API速查
+    ├── 企业认证完整指南.md           # 认证操作指南
+    ├── 隐私协议填写指南.md           # 隐私协议配置指南
+    └── 审核规范.md                  # 审核常见问题
+```
+
+### 脚本功能对比
+
+| 脚本 | 功能 | 推荐场景 |
+|------|------|----------|
+| **mp_full.py** | 全能：检查+报告+自动部署 | 日常管理（推荐） |
+| **mp_deploy.py** | 多小程序管理+认证 | 多项目管理 |
+| **mp_manager.py** | API调用工具 | 高级操作 |
+| **mp_api.py** | Python SDK | 二次开发 |
+
+---
+
+## 📊 多小程序配置
+
+配置文件位于 `scripts/apps_config.json`：
+
+```json
+{
+  "apps": [
+    {
+      "id": "soul-party",
+      "name": "Soul派对",
+      "appid": "wxb8bbb2b10dec74aa",
+      "project_path": "/path/to/miniprogram",
+      "certification": {
+        "status": "verified",
+        "enterprise_name": "厦门智群网络科技有限公司"
+      }
+    },
+    {
+      "id": "another-app",
+      "name": "另一个小程序",
+      "appid": "wx1234567890",
+      "project_path": "/path/to/another",
+      "certification": {
+        "status": "pending"
+      }
+    }
+  ],
+  "certification_materials": {
+    "enterprise_name": "厦门智群网络科技有限公司",
+    "license_number": "统一社会信用代码",
+    "legal_persona_name": "法人姓名",
+    "component_phone": "15880802661"
+  }
+}
+```
+
+---
+
+## ⚡ 常见场景速查
+
+### 场景1：发布时提示"未完成微信认证"
+
+```bash
+# 1. 检查认证状态
+python3 mp_deploy.py cert-status soul-party
+
+# 2. 如果未认证，查看认证指引
+python3 mp_deploy.py cert soul-party
+
+# 3. 在微信后台完成认证后，标记完成
+python3 mp_deploy.py cert-done soul-party
+
+# 4. 重新部署
+python3 mp_deploy.py deploy soul-party
+```
+
+### 场景2：新建小程序并快速上线
+
+```bash
+# 1. 添加小程序配置
+python3 mp_deploy.py add
+
+# 2. 提交认证
+python3 mp_deploy.py cert my-new-app
+
+# 3. 在微信后台完成认证（1-5天）
+
+# 4. 认证通过后标记
+python3 mp_deploy.py cert-done my-new-app
+
+# 5. 一键部署
+python3 mp_deploy.py deploy my-new-app
+
+# 6. 审核通过后发布
+python3 mp_deploy.py release my-new-app
+```
+
+### 场景3：仅更新代码（不提审）
+
+```bash
+# 快速上传到开发版
+python3 mp_deploy.py upload soul-party -v "1.0.5" -d "修复xxx问题"
+```
+
+### 场景4：批量管理多个小程序
+
+```bash
+# 查看所有小程序
+python3 mp_deploy.py list
+
+# 检查所有认证状态
+for app in soul-party another-app third-app; do
+  echo "=== $app ==="
+  python3 mp_deploy.py cert-status $app
+done
+```
+
+---
+
+## 🔗 相关资源
+
+### 官方文档
+- [微信开放平台](https://developers.weixin.qq.com/doc/oplatform/)
+- [小程序CI工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/ci.html)
+- [第三方平台代认证](https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/product/weapp_wxverify.html)
+
+### 开源项目
+- [miniprogram-ci](https://www.npmjs.com/package/miniprogram-ci) - 官方CI工具
+- [multi-mini-ci](https://github.com/Ethan-zjc/multi-mini-ci) - 多平台上传
+- [uz-miniprogram-ci](https://github.com/uzhan/uz-miniprogram-ci) - 一键上传发布
+
+### 相关文章
+- [GitHub Actions集成小程序CI](https://idayer.com/use-github-actions-and-mp-ci-for-wechat-miniprogram-ci/)
+
+---
+
+## 🔥 实战经验库（持续更新）
+
+> 基于 Soul创业派对 项目开发过程中的真实问题和解决方案
+
+### 一、数据库与后端问题
+
+#### 1.1 后台初始化失败：Unknown column 'password' in 'field list'
+
+**问题现象**：后台用户管理显示"初始化失败"
+
+**根本原因**：数据库表结构缺少字段
+
+**解决方案**：创建数据库初始化API自动修复
+
+```typescript
+// app/api/db/init/route.ts
+// 自动检查并添加缺失字段
+const columnsToAdd = [
+  { name: 'password', type: 'VARCHAR(100)' },
+  { name: 'session_key', type: 'VARCHAR(100)' },
+  { name: 'referred_by', type: 'VARCHAR(50)' },
+  { name: 'is_admin', type: 'BOOLEAN DEFAULT FALSE' },
+]
+
+for (const col of columnsToAdd) {
+  // 检查列是否存在，不存在则添加
+  await query(`ALTER TABLE users ADD COLUMN ${col.name} ${col.type}`)
+}
+```
+
+**访问修复**：`curl https://your-domain.com/api/db/init`
+
+---
+
+#### 1.2 Column 'open_id' cannot be null
+
+**问题现象**：后台添加用户失败
+
+**根本原因**：数据库 `open_id` 字段设置为 NOT NULL，但后台添加用户时没有openId
+
+**解决方案**：
+```sql
+ALTER TABLE users MODIFY COLUMN open_id VARCHAR(100) NULL
+```
+
+**最佳实践**：openId允许为NULL，因为：
+- 后台手动添加的用户没有openId
+- 微信登录用户有openId
+- 两种用户需要共存
+
+---
+
+#### 1.3 AppID配置不一致
+
+**问题现象**：微信登录返回错误，或获取openId失败
+
+**根本原因**：项目中多个文件使用了不同的AppID
+
+**检查清单**：
+
+| 文件 | 配置项 | 正确值 |
+|:---|:---|:---|
+| `miniprogram/project.config.json` | appid | wxb8bbb2b10dec74aa |
+| `app/api/miniprogram/login/route.ts` | MINIPROGRAM_CONFIG.appId | wxb8bbb2b10dec74aa |
+| `app/api/wechat/login/route.ts` | APPID | wxb8bbb2b10dec74aa |
+| `app/api/withdraw/route.ts` | WECHAT_PAY_CONFIG.appId | wxb8bbb2b10dec74aa |
+
+**搜索命令**：
+```bash
+# 查找所有AppID配置
+rg "wx[a-f0-9]{16}" --type ts --type json
+```
+
+---
+
+#### 1.4 用户ID设计最佳实践
+
+**推荐方案**：使用 `openId` 作为用户主键
+
+```typescript
+// 微信登录创建用户
+const userId = openId  // 直接使用openId作为用户ID
+await query(`
+  INSERT INTO users (id, open_id, ...) VALUES (?, ?, ...)
+`, [userId, openId, ...])
+```
+
+**优势**：
+- 与微信官方标识一致
+- 便于追踪和管理
+- 后台显示更直观
+
+**兼容方案**：后台添加的用户使用 `user_` 前缀
+
+---
+
+### 二、前端与UI问题
+
+#### 2.1 Next.js Hydration错误
+
+**问题现象**：页面显示"哎呀，出错了"，控制台报 hydration 错误
+
+**根本原因**：服务端和客户端渲染结果不一致（如使用localStorage、zustand持久化）
+
+**解决方案**：添加mounted状态检查
+
+```tsx
+export default function AdminLayout({ children }) {
+  const [mounted, setMounted] = useState(false)
+
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  // 等待客户端mount后再渲染
+  if (!mounted) {
+    return <div>加载中...</div>
+  }
+
+  return <div>{children}</div>
+}
+```
+
+---
+
+#### 2.2 数据类型不匹配：toFixed() 报错
+
+**问题现象**：显示金额时报错 `toFixed is not a function`
+
+**根本原因**：数据库返回的 `DECIMAL` 字段是字符串类型
+
+**解决方案**：
+```tsx
+// ❌ 错误
+<div>{user.earnings.toFixed(2)}</div>
+
+// ✅ 正确
+<div>{parseFloat(String(user.earnings || 0)).toFixed(2)}</div>
+```
+
+**通用处理函数**：
+```typescript
+const formatMoney = (value: any) => {
+  return parseFloat(String(value || 0)).toFixed(2)
+}
+```
+
+---
+
+### 三、小程序开发问题
+
+#### 3.1 搜索功能：章节ID格式不一致
+
+**问题现象**：搜索结果跳转到阅读页404
+
+**根本原因**：
+- `book-chapters.json` 使用 `chapter-2`, `chapter-3` 格式
+- 阅读页使用 `1.1`, `1.2` 格式
+
+**解决方案**：从标题提取章节号
+
+```typescript
+// 从标题提取章节号（如 "1.1 荷包：..." → "1.1"）
+const sectionIdMatch = chapter.title?.match(/^(\d+\.\d+)\s/)
+const sectionId = sectionIdMatch ? sectionIdMatch[1] : chapter.id
+```
+
+---
+
+#### 3.2 搜索功能：敏感信息过滤
+
+**需求**：搜索结果不能显示用户手机号、微信号等
+
+**实现**：
+```typescript
+const cleanContent = content
+  .replace(/1[3-9]\d{9}/g, '***')           // 手机号
+  .replace(/微信[：:]\s*\S+/g, '微信：***')   // 微信号
+  .replace(/QQ[：:]\s*\d+/g, 'QQ：***')      // QQ号
+  .replace(/邮箱[：:]\s*\S+@\S+/g, '邮箱：***') // 邮箱
+```
+
+---
+
+#### 3.3 上下章导航：付费内容也需要显示
+
+**需求**：即使用户没有购买，也要显示上一篇/下一篇导航
+
+**实现**：将导航组件移到付费墙之外
+
+```html
+<!-- 付费墙 -->
+<view class="paywall">
+  <!-- 解锁按钮 -->
+</view>
+
+<!-- 章节导航 - 始终显示 -->
+<view class="chapter-nav">
+  <view class="nav-btn nav-prev" bindtap="goToPrev">上一篇</view>
+  <view class="nav-btn nav-next" bindtap="goToNext">下一篇</view>
+</view>
+```
+
+---
+
+#### 3.4 分销绑定：推广码捕获
+
+**需求**：用户通过分享链接进入时，自动绑定推广者
+
+**实现流程**：
+
+```javascript
+// app.js - onLaunch/onShow
+onLaunch(options) {
+  if (options.query && options.query.ref) {
+    wx.setStorageSync('referral_code', options.query.ref)
+    this.bindReferral(options.query.ref)
+  }
+}
+
+// 小程序码scene参数解析
+const scene = decodeURIComponent(options.scene)
+const params = new URLSearchParams(scene)
+const ref = params.get('ref')
+```
+
+**后端绑定**：
+```sql
+UPDATE users SET referred_by = ? WHERE id = ? AND referred_by IS NULL
+```
+
+---
+
+### 四、后台管理优化
+
+#### 4.1 菜单精简原则
+
+**优化前（9项）**：
+- 数据概览、网站配置、内容管理、用户管理、匹配配置、分销管理、支付配置、分账提现、二维码、系统设置
+
+**优化后（6项）**：
+- 数据概览、内容管理、用户管理、分账管理、支付设置、系统设置
+
+**精简原则**：
+1. 合并相似功能（分销管理 + 分账提现 → 分账管理）
+2. 移除低频功能（二维码、匹配配置 → 可在系统设置中配置）
+3. 核心功能优先
+
+---
+
+#### 4.2 用户绑定关系展示
+
+**需求**：查看用户的推广下线详情
+
+**实现API**：
+```typescript
+// GET /api/db/users/referrals?userId=xxx
+const referrals = await query(`
+  SELECT * FROM users WHERE referred_by = ?
+  ORDER BY created_at DESC
+`, [referralCode])
+```
+
+**展示信息**：
+- 绑定总数、已付费人数、免费用户
+- 累计收益、待提现金额
+- 每个绑定用户的状态（VIP/已付费/未付费）
+
+---
+
+### 五、分销与提现
+
+#### 5.1 自动分账规则
+
+| 配置项 | 值 | 说明 |
+|:---|:---|:---|
+| 分销比例 | 90% | 推广者获得订单金额的90% |
+| 结算方式 | 自动 | 用户付款后立即计入推广者账户 |
+| 提现方式 | 微信零钱 | 企业付款到零钱 |
+| 提现门槛 | 1元 | 累计收益≥1元可提现 |
+
+#### 5.2 提现流程
+
+```
+用户申请提现
+    ↓
+扣除账户余额，增加待提现金额
+    ↓
+管理员后台审核
+    ↓
+批准 → 调用微信企业付款API → 到账
+拒绝 → 返还用户余额
+```
+
+---
+
+### 六、开发规范
+
+#### 6.1 配置统一管理
+
+```typescript
+// lib/config.ts
+export const WECHAT_CONFIG = {
+  appId: process.env.WECHAT_APPID || 'wxb8bbb2b10dec74aa',
+  appSecret: process.env.WECHAT_APPSECRET || '...',
+  mchId: '1318592501',
+  apiKey: '...'
+}
+```
+
+**所有API文件统一引用此配置，避免硬编码**
+
+#### 6.2 数据库字段命名
+
+| 前端字段 | 数据库字段 | 说明 |
+|:---|:---|:---|
+| openId | open_id | 微信openId |
+| hasFullBook | has_full_book | 是否购买全书 |
+| referralCode | referral_code | 推广码 |
+| pendingEarnings | pending_earnings | 待提现收益 |
+
+**规则**：数据库使用snake_case，前端使用camelCase
+
+#### 6.3 错误处理模板
+
+```typescript
+export async function POST(request: Request) {
+  try {
+    const body = await request.json()
+    // 业务逻辑
+    return NextResponse.json({ success: true, data: ... })
+  } catch (error) {
+    console.error('[API名称] 错误:', error)
+    return NextResponse.json({ 
+      success: false, 
+      error: '用户友好的错误信息'
+    }, { status: 500 })
+  }
+}
+```
+
+---
+
+## 📌 问题排查清单
+
+### 小程序无法登录
+
+- [ ] 检查AppID是否正确（project.config.json vs 后端）
+- [ ] 检查AppSecret是否正确
+- [ ] 检查API域名是否已配置
+- [ ] 检查后端服务是否正常运行
+- [ ] 查看后端日志 `[MiniLogin]`
+
+### 后台显示异常
+
+- [ ] 运行 `/api/db/init` 初始化数据库
+- [ ] 检查数据库连接是否正常
+- [ ] 清除浏览器缓存（Cmd+Shift+R）
+- [ ] 查看浏览器控制台错误
+
+### 搜索功能无结果
+
+- [ ] 检查 `public/book-chapters.json` 是否存在
+- [ ] 检查章节文件路径是否正确（filePath字段）
+- [ ] 检查关键词编码（中文需URL编码）
+
+### 提现失败
+
+- [ ] 检查用户余额是否充足
+- [ ] 检查用户是否有openId
+- [ ] 检查微信商户API证书配置
+- [ ] 查看后端日志 `[Withdraw]`
+
+---
+
+**创建时间**：2026-01-25
+**更新时间**：2026-01-25
+**版本**：v3.1（新增实战经验库）
+**维护者**：卡若
diff --git a/开发文档/小程序管理/references/审核与认证.md b/开发文档/小程序管理/references/审核与认证.md
new file mode 100644
index 00000000..fd495184
--- /dev/null
+++ b/开发文档/小程序管理/references/审核与认证.md
@@ -0,0 +1,3 @@
+# 审核与认证（合并自 API速查、企业认证、审核规范、隐私协议）
+
+API 接口速查、企业认证完整指南、审核规范、隐私协议填写指南。详见原各文档。
diff --git a/开发文档/小程序管理/scripts/apps_config.json b/开发文档/小程序管理/scripts/apps_config.json
new file mode 100644
index 00000000..4dd89b79
--- /dev/null
+++ b/开发文档/小程序管理/scripts/apps_config.json
@@ -0,0 +1,41 @@
+{
+  "_comment": "小程序配置文件 - 支持管理多个小程序",
+  "default_version": "1.2.6",
+  "apps": [
+    {
+      "id": "soul-party",
+      "name": "Soul派对",
+      "appid": "wxb8bbb2b10dec74aa",
+      "project_path": "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验-永平/miniprogram",
+      "private_key_path": "",
+      "api_domain": "https://soul.quwanzhi.com",
+      "description": "一场SOUL的创业实验场",
+      "certification": {
+        "status": "pending",
+        "enterprise_name": "泉州市卡若网络技术有限公司",
+        "license_number": "",
+        "legal_persona_name": "",
+        "legal_persona_wechat": "",
+        "component_phone": "15880802661"
+      }
+    }
+  ],
+  "certification_materials": {
+    "_comment": "企业认证通用材料（所有小程序共用）",
+    "enterprise_name": "泉州市卡若网络技术有限公司",
+    "license_number": "",
+    "license_media_id": "",
+    "legal_persona_name": "",
+    "legal_persona_wechat": "",
+    "legal_persona_idcard": "",
+    "component_phone": "15880802661",
+    "contact_email": "zhiqun@qq.com"
+  },
+  "third_party_platform": {
+    "_comment": "第三方平台配置（用于代认证）",
+    "component_appid": "",
+    "component_appsecret": "",
+    "component_verify_ticket": "",
+    "authorized": false
+  }
+}
diff --git a/开发文档/小程序管理/scripts/env_template.txt b/开发文档/小程序管理/scripts/env_template.txt
new file mode 100644
index 00000000..eda84b02
--- /dev/null
+++ b/开发文档/小程序管理/scripts/env_template.txt
@@ -0,0 +1,35 @@
+# 微信小程序管理 - 环境变量配置
+# 复制此文件为 .env 并填入实际值
+
+# ==================== 方式一：AppID+AppSecret 自动获取 token（推荐） ====================
+# 与 soul-api/.env 中的 WECHAT_APPID、WECHAT_APPSECRET 一致
+WECHAT_APPID=wxb8bbb2b10dec74aa
+WECHAT_APPSECRET=你的小程序AppSecret
+
+# ==================== 方式二：直接使用 access_token ====================
+# 如果你已经有 access_token，直接填入即可（适合快速测试）
+# ACCESS_TOKEN=你的access_token
+
+# ==================== 方式二：使用第三方平台凭证 ====================
+# 如果你有第三方平台资质，填入以下信息可自动刷新token
+
+# 第三方平台 AppID
+COMPONENT_APPID=你的第三方平台AppID
+
+# 第三方平台密钥
+COMPONENT_APPSECRET=你的第三方平台密钥
+
+# 授权小程序 AppID（要管理的小程序）
+AUTHORIZER_APPID=wxb8bbb2b10dec74aa
+
+# 授权刷新令牌（从授权回调中获取）
+AUTHORIZER_REFRESH_TOKEN=授权时获取的refresh_token
+
+# ==================== 小程序项目路径 ====================
+# 用于 CLI 工具操作
+MINIPROGRAM_PATH=/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram
+
+# ==================== 可选配置 ====================
+# 隐私协议联系方式（用于快速配置）
+CONTACT_EMAIL=zhiqun@qq.com
+CONTACT_PHONE=15880802661
diff --git a/开发文档/小程序管理/scripts/mp_api.py b/开发文档/小程序管理/scripts/mp_api.py
new file mode 100644
index 00000000..6609c787
--- /dev/null
+++ b/开发文档/小程序管理/scripts/mp_api.py
@@ -0,0 +1,673 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+微信小程序管理API封装
+支持：注册、配置、代码管理、审核、发布、数据分析
+"""
+
+import os
+import json
+import time
+import httpx
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+from pathlib import Path
+
+# 尝试加载dotenv（可选依赖）
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # dotenv不是必需的
+
+
+@dataclass
+class MiniProgramInfo:
+    """小程序基础信息"""
+    appid: str
+    nickname: str
+    head_image_url: str
+    signature: str
+    principal_name: str
+    realname_status: int  # 1=已认证
+
+
+@dataclass
+class AuditStatus:
+    """审核状态"""
+    auditid: int
+    status: int  # 0=成功，1=被拒，2=审核中，3=已撤回，4=延后
+    reason: Optional[str] = None
+    screenshot: Optional[str] = None
+
+    @property
+    def status_text(self) -> str:
+        status_map = {
+            0: "✅ 审核成功",
+            1: "❌ 审核被拒",
+            2: "⏳ 审核中",
+            3: "↩️ 已撤回",
+            4: "⏸️ 审核延后"
+        }
+        return status_map.get(self.status, "未知状态")
+
+
+class MiniProgramAPI:
+    """微信小程序管理API"""
+    
+    BASE_URL = "https://api.weixin.qq.com"
+    
+    def __init__(
+        self,
+        component_appid: Optional[str] = None,
+        component_appsecret: Optional[str] = None,
+        authorizer_appid: Optional[str] = None,
+        access_token: Optional[str] = None,
+        appid: Optional[str] = None,
+        appsecret: Optional[str] = None
+    ):
+        """
+        初始化API
+        
+        Args:
+            component_appid: 第三方平台AppID
+            component_appsecret: 第三方平台密钥
+            authorizer_appid: 授权小程序AppID
+            access_token: 直接使用的access_token（如已获取）
+            appid: 小程序AppID（配合appsecret直接获取token）
+            appsecret: 小程序AppSecret（配合appid直接获取token）
+        """
+        self.component_appid = component_appid or os.getenv("COMPONENT_APPID")
+        self.component_appsecret = component_appsecret or os.getenv("COMPONENT_APPSECRET")
+        self.authorizer_appid = authorizer_appid or os.getenv("AUTHORIZER_APPID")
+        self._access_token = access_token or os.getenv("ACCESS_TOKEN")
+        self.appid = appid or os.getenv("WECHAT_APPID")
+        self.appsecret = appsecret or os.getenv("WECHAT_APPSECRET")
+        self._token_expires_at = 0
+        
+        self.client = httpx.Client(timeout=30.0)
+    
+    def _fetch_token_by_appsecret(self) -> str:
+        """通过 AppID + AppSecret 获取 access_token"""
+        if not self.appid or not self.appsecret:
+            return ""
+        url = f"{self.BASE_URL}/cgi-bin/token"
+        params = {
+            "grant_type": "client_credential",
+            "appid": self.appid,
+            "secret": self.appsecret
+        }
+        resp = self.client.get(url, params=params)
+        result = resp.json()
+        if result.get("errcode"):
+            raise APIError(result.get("errcode", -1), result.get("errmsg", "获取token失败"))
+        token = result.get("access_token", "")
+        expires_in = result.get("expires_in", 7200)
+        self.set_access_token(token, expires_in)
+        return token
+    
+    @property
+    def access_token(self) -> str:
+        """获取access_token，如果过期则刷新"""
+        if self._access_token and time.time() < self._token_expires_at:
+            return self._access_token
+        
+        # 方式1: AppID+AppSecret 直接获取（小程序自有，非第三方）
+        if self.appid and self.appsecret:
+            return self._fetch_token_by_appsecret()
+        
+        # 方式2: 已有 token 且未配置刷新
+        return self._access_token or ""
+    
+    def set_access_token(self, token: str, expires_in: int = 7200):
+        """手动设置access_token"""
+        self._access_token = token
+        self._token_expires_at = time.time() + expires_in - 300  # 提前5分钟过期
+    
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict] = None,
+        json_data: Optional[Dict] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """发起API请求"""
+        url = f"{self.BASE_URL}{path}"
+        
+        # 添加access_token
+        if params is None:
+            params = {}
+        if "access_token" not in params:
+            params["access_token"] = self.access_token
+        
+        if method.upper() == "GET":
+            resp = self.client.get(url, params=params, **kwargs)
+        else:
+            resp = self.client.post(url, params=params, json=json_data, **kwargs)
+        
+        # 解析响应
+        try:
+            result = resp.json()
+        except json.JSONDecodeError:
+            # 可能是二进制数据（如图片）
+            return {"_binary": resp.content}
+        
+        # 检查错误
+        if result.get("errcode", 0) != 0:
+            raise APIError(result.get("errcode"), result.get("errmsg", "Unknown error"))
+        
+        return result
+    
+    # ==================== 基础信息 ====================
+    
+    def get_basic_info(self) -> MiniProgramInfo:
+        """获取小程序基础信息"""
+        result = self._request("POST", "/cgi-bin/account/getaccountbasicinfo")
+        return MiniProgramInfo(
+            appid=result.get("appid", ""),
+            nickname=result.get("nickname", ""),
+            head_image_url=result.get("head_image_url", ""),
+            signature=result.get("signature", ""),
+            principal_name=result.get("principal_name", ""),
+            realname_status=result.get("realname_status", 0)
+        )
+    
+    def modify_signature(self, signature: str) -> bool:
+        """修改简介（4-120字）"""
+        self._request("POST", "/cgi-bin/account/modifysignature", json_data={
+            "signature": signature
+        })
+        return True
+    
+    # ==================== 域名配置 ====================
+    
+    def get_domain(self) -> Dict[str, List[str]]:
+        """获取服务器域名配置"""
+        result = self._request("POST", "/wxa/modify_domain", json_data={
+            "action": "get"
+        })
+        return {
+            "requestdomain": result.get("requestdomain", []),
+            "wsrequestdomain": result.get("wsrequestdomain", []),
+            "uploaddomain": result.get("uploaddomain", []),
+            "downloaddomain": result.get("downloaddomain", [])
+        }
+    
+    def set_domain(
+        self,
+        requestdomain: Optional[List[str]] = None,
+        wsrequestdomain: Optional[List[str]] = None,
+        uploaddomain: Optional[List[str]] = None,
+        downloaddomain: Optional[List[str]] = None
+    ) -> bool:
+        """设置服务器域名"""
+        data = {"action": "set"}
+        if requestdomain:
+            data["requestdomain"] = requestdomain
+        if wsrequestdomain:
+            data["wsrequestdomain"] = wsrequestdomain
+        if uploaddomain:
+            data["uploaddomain"] = uploaddomain
+        if downloaddomain:
+            data["downloaddomain"] = downloaddomain
+        
+        self._request("POST", "/wxa/modify_domain", json_data=data)
+        return True
+    
+    def get_webview_domain(self) -> List[str]:
+        """获取业务域名"""
+        result = self._request("POST", "/wxa/setwebviewdomain", json_data={
+            "action": "get"
+        })
+        return result.get("webviewdomain", [])
+    
+    def set_webview_domain(self, webviewdomain: List[str]) -> bool:
+        """设置业务域名"""
+        self._request("POST", "/wxa/setwebviewdomain", json_data={
+            "action": "set",
+            "webviewdomain": webviewdomain
+        })
+        return True
+    
+    # ==================== 隐私协议 ====================
+    
+    def get_privacy_setting(self, privacy_ver: int = 2) -> Dict[str, Any]:
+        """获取隐私协议设置"""
+        result = self._request("POST", "/cgi-bin/component/getprivacysetting", json_data={
+            "privacy_ver": privacy_ver
+        })
+        return result
+    
+    def set_privacy_setting(
+        self,
+        setting_list: List[Dict[str, str]],
+        contact_email: Optional[str] = None,
+        contact_phone: Optional[str] = None,
+        notice_method: str = "弹窗提示"
+    ) -> bool:
+        """
+        设置隐私协议
+        
+        Args:
+            setting_list: 隐私配置列表，如 [{"privacy_key": "UserInfo", "privacy_text": "用于展示头像"}]
+            contact_email: 联系邮箱
+            contact_phone: 联系电话
+            notice_method: 告知方式
+        """
+        data = {
+            "privacy_ver": 2,
+            "setting_list": setting_list
+        }
+        
+        owner_setting = {"notice_method": notice_method}
+        if contact_email:
+            owner_setting["contact_email"] = contact_email
+        if contact_phone:
+            owner_setting["contact_phone"] = contact_phone
+        data["owner_setting"] = owner_setting
+        
+        self._request("POST", "/cgi-bin/component/setprivacysetting", json_data=data)
+        return True
+    
+    # ==================== 类目管理 ====================
+    
+    def get_all_categories(self) -> List[Dict]:
+        """获取可选类目列表"""
+        result = self._request("GET", "/cgi-bin/wxopen/getallcategories")
+        return result.get("categories_list", {}).get("categories", [])
+    
+    def get_category(self) -> List[Dict]:
+        """获取已设置的类目"""
+        result = self._request("GET", "/cgi-bin/wxopen/getcategory")
+        return result.get("categories", [])
+    
+    def add_category(self, categories: List[Dict]) -> bool:
+        """
+        添加类目
+        
+        Args:
+            categories: 类目列表，如 [{"first": 1, "second": 2}]
+        """
+        self._request("POST", "/cgi-bin/wxopen/addcategory", json_data={
+            "categories": categories
+        })
+        return True
+    
+    def delete_category(self, first: int, second: int) -> bool:
+        """删除类目"""
+        self._request("POST", "/cgi-bin/wxopen/deletecategory", json_data={
+            "first": first,
+            "second": second
+        })
+        return True
+    
+    # ==================== 代码管理 ====================
+    
+    def commit_code(
+        self,
+        template_id: int,
+        user_version: str,
+        user_desc: str,
+        ext_json: Optional[str] = None
+    ) -> bool:
+        """
+        上传代码
+        
+        Args:
+            template_id: 代码模板ID
+            user_version: 版本号
+            user_desc: 版本描述
+            ext_json: 扩展配置JSON字符串
+        """
+        data = {
+            "template_id": template_id,
+            "user_version": user_version,
+            "user_desc": user_desc
+        }
+        if ext_json:
+            data["ext_json"] = ext_json
+        
+        self._request("POST", "/wxa/commit", json_data=data)
+        return True
+    
+    def get_page(self) -> List[str]:
+        """获取已上传代码的页面列表"""
+        result = self._request("GET", "/wxa/get_page")
+        return result.get("page_list", [])
+    
+    def get_qrcode(self, path: Optional[str] = None) -> bytes:
+        """
+        获取体验版二维码
+        
+        Args:
+            path: 页面路径，如 "pages/index/index"
+        
+        Returns:
+            二维码图片二进制数据
+        """
+        params = {"access_token": self.access_token}
+        if path:
+            params["path"] = path
+        
+        resp = self.client.get(f"{self.BASE_URL}/wxa/get_qrcode", params=params)
+        content = resp.content
+        # 检查是否为 JSON 错误响应
+        if content[:1] == b'{':
+            try:
+                err = json.loads(content)
+                if err.get("errcode"):
+                    raise APIError(err.get("errcode", -1), err.get("errmsg", "获取二维码失败"))
+            except json.JSONDecodeError:
+                pass
+        return content
+    
+    # ==================== 审核管理 ====================
+    
+    def submit_audit(
+        self,
+        item_list: Optional[List[Dict]] = None,
+        version_desc: Optional[str] = None,
+        feedback_info: Optional[str] = None
+    ) -> int:
+        """
+        提交审核
+        
+        Args:
+            item_list: 页面审核信息列表
+            version_desc: 版本说明
+            feedback_info: 反馈内容
+        
+        Returns:
+            审核单ID
+        """
+        data = {}
+        if item_list:
+            data["item_list"] = item_list
+        if version_desc:
+            data["version_desc"] = version_desc
+        if feedback_info:
+            data["feedback_info"] = feedback_info
+        
+        result = self._request("POST", "/wxa/submit_audit", json_data=data)
+        return result.get("auditid", 0)
+    
+    def get_audit_status(self, auditid: int) -> AuditStatus:
+        """查询审核状态"""
+        result = self._request("POST", "/wxa/get_auditstatus", json_data={
+            "auditid": auditid
+        })
+        return AuditStatus(
+            auditid=auditid,
+            status=result.get("status", -1),
+            reason=result.get("reason"),
+            screenshot=result.get("screenshot")
+        )
+    
+    def get_latest_audit_status(self) -> AuditStatus:
+        """查询最新审核状态"""
+        result = self._request("GET", "/wxa/get_latest_auditstatus")
+        return AuditStatus(
+            auditid=result.get("auditid", 0),
+            status=result.get("status", -1),
+            reason=result.get("reason"),
+            screenshot=result.get("screenshot")
+        )
+    
+    def undo_code_audit(self) -> bool:
+        """撤回审核（每天限1次）"""
+        self._request("GET", "/wxa/undocodeaudit")
+        return True
+    
+    # ==================== 发布管理 ====================
+    
+    def release(self) -> bool:
+        """发布已审核通过的版本"""
+        self._request("POST", "/wxa/release", json_data={})
+        return True
+    
+    def revert_code_release(self) -> bool:
+        """版本回退（只能回退到上一版本）"""
+        self._request("GET", "/wxa/revertcoderelease")
+        return True
+    
+    def get_revert_history(self) -> List[Dict]:
+        """获取可回退版本历史"""
+        result = self._request("GET", "/wxa/revertcoderelease", params={
+            "action": "get_history_version"
+        })
+        return result.get("version_list", [])
+    
+    def gray_release(self, gray_percentage: int) -> bool:
+        """
+        分阶段发布
+        
+        Args:
+            gray_percentage: 灰度比例 1-100
+        """
+        self._request("POST", "/wxa/grayrelease", json_data={
+            "gray_percentage": gray_percentage
+        })
+        return True
+    
+    # ==================== 小程序码 ====================
+    
+    def get_wxacode(
+        self,
+        path: str,
+        width: int = 430,
+        auto_color: bool = False,
+        line_color: Optional[Dict[str, int]] = None,
+        is_hyaline: bool = False
+    ) -> bytes:
+        """
+        获取小程序码（有限制，每个path最多10万个）
+        
+        Args:
+            path: 页面路径，如 "pages/index/index?id=123"
+            width: 宽度 280-1280
+            auto_color: 自动配置线条颜色
+            line_color: 线条颜色 {"r": 0, "g": 0, "b": 0}
+            is_hyaline: 是否透明背景
+        
+        Returns:
+            二维码图片二进制数据
+        """
+        data = {
+            "path": path,
+            "width": width,
+            "auto_color": auto_color,
+            "is_hyaline": is_hyaline
+        }
+        if line_color:
+            data["line_color"] = line_color
+        
+        resp = self.client.post(
+            f"{self.BASE_URL}/wxa/getwxacode",
+            params={"access_token": self.access_token},
+            json=data
+        )
+        return resp.content
+    
+    def get_wxacode_unlimit(
+        self,
+        scene: str,
+        page: Optional[str] = None,
+        width: int = 430,
+        auto_color: bool = False,
+        line_color: Optional[Dict[str, int]] = None,
+        is_hyaline: bool = False,
+        env_version: Optional[str] = None
+    ) -> bytes:
+        """
+        获取无限小程序码（推荐）
+        
+        Args:
+            scene: 场景值，最长32字符，如 "user_id=123&from=share"
+            page: 页面路径，必须是已发布的页面
+            width: 宽度 280-1280
+            auto_color: 自动配置线条颜色
+            line_color: 线条颜色 {"r": 0, "g": 0, "b": 0}
+            is_hyaline: 是否透明背景
+            env_version: release=正式版, trial=体验版, develop=开发版
+        
+        Returns:
+            二维码图片二进制数据
+        """
+        data = {
+            "scene": scene,
+            "width": width,
+            "auto_color": auto_color,
+            "is_hyaline": is_hyaline
+        }
+        if page:
+            data["page"] = page
+        if env_version:
+            data["env_version"] = env_version
+        if line_color:
+            data["line_color"] = line_color
+        
+        resp = self.client.post(
+            f"{self.BASE_URL}/wxa/getwxacodeunlimit",
+            params={"access_token": self.access_token},
+            json=data
+        )
+        return resp.content
+    
+    def gen_short_link(
+        self,
+        page_url: str,
+        page_title: str,
+        is_permanent: bool = False
+    ) -> str:
+        """
+        生成小程序短链接
+        
+        Args:
+            page_url: 页面路径，如 "pages/index/index?id=123"
+            page_title: 页面标题
+            is_permanent: 是否永久有效
+        
+        Returns:
+            短链接
+        """
+        result = self._request("POST", "/wxa/genwxashortlink", json_data={
+            "page_url": page_url,
+            "page_title": page_title,
+            "is_permanent": is_permanent
+        })
+        return result.get("link", "")
+    
+    # ==================== 数据分析 ====================
+    
+    def get_daily_visit_trend(self, begin_date: str, end_date: str) -> List[Dict]:
+        """
+        获取每日访问趋势
+        
+        Args:
+            begin_date: 开始日期 YYYYMMDD
+            end_date: 结束日期 YYYYMMDD
+        """
+        result = self._request(
+            "POST",
+            "/datacube/getweanalysisappiddailyvisittrend",
+            json_data={"begin_date": begin_date, "end_date": end_date}
+        )
+        return result.get("list", [])
+    
+    def get_user_portrait(self, begin_date: str, end_date: str) -> Dict:
+        """
+        获取用户画像
+        
+        Args:
+            begin_date: 开始日期 YYYYMMDD
+            end_date: 结束日期 YYYYMMDD
+        """
+        result = self._request(
+            "POST",
+            "/datacube/getweanalysisappiduserportrait",
+            json_data={"begin_date": begin_date, "end_date": end_date}
+        )
+        return result
+    
+    # ==================== API配额 ====================
+    
+    def get_api_quota(self, cgi_path: str) -> Dict:
+        """
+        查询接口调用额度
+        
+        Args:
+            cgi_path: 接口路径，如 "/wxa/getwxacode"
+        """
+        result = self._request("POST", "/cgi-bin/openapi/quota/get", json_data={
+            "cgi_path": cgi_path
+        })
+        return result.get("quota", {})
+    
+    def clear_quota(self, appid: Optional[str] = None) -> bool:
+        """重置接口调用次数（每月限10次）"""
+        self._request("POST", "/cgi-bin/clear_quota", json_data={
+            "appid": appid or self.authorizer_appid
+        })
+        return True
+    
+    def close(self):
+        """关闭连接"""
+        self.client.close()
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+class APIError(Exception):
+    """API错误"""
+    
+    ERROR_CODES = {
+        -1: "系统繁忙",
+        40001: "access_token无效",
+        40002: "grant_type不正确",
+        40013: "appid不正确",
+        40029: "code无效",
+        40125: "appsecret不正确",
+        41002: "缺少appid参数",
+        41004: "缺少appsecret参数",
+        42001: "access_token过期",
+        42007: "refresh_token过期",
+        45009: "调用超过限制",
+        61039: "代码检测任务未完成，请稍后再试",
+        85006: "标签格式错误",
+        85007: "页面路径错误",
+        85009: "已有审核版本，请先撤回",
+        85010: "版本输入错误",
+        85011: "当前版本不能回退",
+        85012: "无效的版本",
+        85015: "该账号已有发布中的版本",
+        85019: "没有审核版本",
+        85020: "审核状态异常",
+        85064: "找不到模板",
+        85085: "该小程序不能被操作",
+        85086: "小程序没有绑定任何类目",
+        87013: "每天只能撤回1次审核",
+        89020: "该小程序尚未认证",
+        89248: "隐私协议内容不完整",
+    }
+    
+    def __init__(self, code: int, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {self.ERROR_CODES.get(code, message)}")
+
+
+# 便捷函数
+def create_api_from_env() -> MiniProgramAPI:
+    """从环境变量创建API实例"""
+    return MiniProgramAPI()
+
+
+if __name__ == "__main__":
+    # 测试
+    api = create_api_from_env()
+    print("API初始化成功")
diff --git a/开发文档/小程序管理/scripts/mp_deploy.py b/开发文档/小程序管理/scripts/mp_deploy.py
new file mode 100644
index 00000000..bd3053ce
--- /dev/null
+++ b/开发文档/小程序管理/scripts/mp_deploy.py
@@ -0,0 +1,814 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+小程序一键部署工具 v2.0
+
+功能：
+- 多小程序管理
+- 一键部署上线
+- 自动认证提交
+- 认证状态检查
+- 材料有效性验证
+
+使用方法:
+    python mp_deploy.py list                    # 列出所有小程序
+    python mp_deploy.py add                     # 添加新小程序
+    python mp_deploy.py deploy <app_id>         # 上传 + 设为体验版（不提审）
+    python mp_deploy.py deploy <app_id> --submit # 上传 + 体验版 + 提交审核
+    python mp_deploy.py upload <app_id>         # 快速上传代码
+    python mp_deploy.py submit <app_id>         # 单独提交审核
+    python mp_deploy.py cert <app_id>           # 提交认证
+    python mp_deploy.py cert-status <app_id>    # 查询认证状态
+    python mp_deploy.py release <app_id>        # 发布上线
+"""
+
+import os
+import sys
+import json
+import subprocess
+import argparse
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, List, Any
+from dataclasses import dataclass, asdict
+
+# 加载环境变量（优先 scripts/.env，其次 soul-api/.env）
+def _load_env():
+    try:
+        from dotenv import load_dotenv
+        script_dir = Path(__file__).parent
+        load_dotenv(script_dir / ".env")
+        # 若未配置 WECHAT_APPSECRET，尝试从 soul-api 加载
+        if not os.getenv("WECHAT_APPSECRET"):
+            soul_env = script_dir.parent.parent.parent / "soul-api" / ".env"
+            if soul_env.exists():
+                load_dotenv(soul_env)
+    except ImportError:
+        pass
+
+_load_env()
+
+# 配置文件路径
+CONFIG_FILE = Path(__file__).parent / "apps_config.json"
+
+
+@dataclass
+class AppConfig:
+    """小程序配置"""
+    id: str
+    name: str
+    appid: str
+    project_path: str
+    private_key_path: str = ""
+    api_domain: str = ""
+    description: str = ""
+    certification: Dict = None
+    
+    def __post_init__(self):
+        if self.certification is None:
+            self.certification = {
+                "status": "unknown",
+                "enterprise_name": "",
+                "license_number": "",
+                "legal_persona_name": "",
+                "legal_persona_wechat": "",
+                "component_phone": ""
+            }
+
+
+class ConfigManager:
+    """配置管理器"""
+    
+    def __init__(self, config_file: Path = CONFIG_FILE):
+        self.config_file = config_file
+        self.config = self._load_config()
+    
+    def _load_config(self) -> Dict:
+        """加载配置"""
+        if self.config_file.exists():
+            with open(self.config_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        return {"apps": [], "certification_materials": {}, "third_party_platform": {}}
+    
+    def _save_config(self):
+        """保存配置"""
+        with open(self.config_file, 'w', encoding='utf-8') as f:
+            json.dump(self.config, f, ensure_ascii=False, indent=2)
+    
+    def get_apps(self) -> List[AppConfig]:
+        """获取所有小程序"""
+        return [AppConfig(**app) for app in self.config.get("apps", [])]
+    
+    def get_app(self, app_id: str) -> Optional[AppConfig]:
+        """获取指定小程序"""
+        for app in self.config.get("apps", []):
+            if app["id"] == app_id or app["appid"] == app_id:
+                return AppConfig(**app)
+        return None
+    
+    def add_app(self, app: AppConfig):
+        """添加小程序"""
+        apps = self.config.get("apps", [])
+        # 检查是否已存在
+        for i, existing in enumerate(apps):
+            if existing["id"] == app.id:
+                apps[i] = asdict(app)
+                self.config["apps"] = apps
+                self._save_config()
+                return
+        apps.append(asdict(app))
+        self.config["apps"] = apps
+        self._save_config()
+    
+    def update_app(self, app_id: str, updates: Dict):
+        """更新小程序配置"""
+        apps = self.config.get("apps", [])
+        for i, app in enumerate(apps):
+            if app["id"] == app_id:
+                apps[i].update(updates)
+                self.config["apps"] = apps
+                self._save_config()
+                return True
+        return False
+    
+    def get_cert_materials(self) -> Dict:
+        """获取通用认证材料"""
+        return self.config.get("certification_materials", {})
+    
+    def update_cert_materials(self, materials: Dict):
+        """更新认证材料"""
+        self.config["certification_materials"] = materials
+        self._save_config()
+
+
+class MiniProgramDeployer:
+    """小程序部署器"""
+    
+    # 微信开发者工具CLI路径
+    WX_CLI = "/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
+    
+    def __init__(self):
+        self.config = ConfigManager()
+    
+    def _check_wx_cli(self) -> bool:
+        """检查微信开发者工具是否安装"""
+        return os.path.exists(self.WX_CLI)
+    
+    def _run_cli(self, *args, project_path: str = None) -> tuple:
+        """运行CLI命令"""
+        cmd = [self.WX_CLI] + list(args)
+        if project_path:
+            cmd.extend(["--project", project_path])
+        
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+            return result.returncode == 0, result.stdout + result.stderr
+        except subprocess.TimeoutExpired:
+            return False, "命令执行超时"
+        except Exception as e:
+            return False, str(e)
+    
+    def list_apps(self):
+        """列出所有小程序"""
+        apps = self.config.get_apps()
+        
+        if not apps:
+            print("\n📭 暂无配置的小程序")
+            print("   运行 'python mp_deploy.py add' 添加小程序")
+            return
+        
+        print("\n" + "=" * 60)
+        print("  📱 小程序列表")
+        print("=" * 60)
+        
+        for i, app in enumerate(apps, 1):
+            cert_status = app.certification.get("status", "unknown")
+            status_icon = {
+                "verified": "✅",
+                "pending": "⏳",
+                "rejected": "❌",
+                "expired": "⚠️",
+                "unknown": "❓"
+            }.get(cert_status, "❓")
+            
+            print(f"\n  [{i}] {app.name}")
+            print(f"      ID: {app.id}")
+            print(f"      AppID: {app.appid}")
+            print(f"      认证: {status_icon} {cert_status}")
+            print(f"      路径: {app.project_path}")
+        
+        print("\n" + "-" * 60)
+        print("  使用方法:")
+        print("    python mp_deploy.py deploy <id>   一键部署")
+        print("    python mp_deploy.py cert <id>     提交认证")
+        print("=" * 60 + "\n")
+    
+    def add_app(self):
+        """交互式添加小程序"""
+        print("\n" + "=" * 50)
+        print("  ➕ 添加新小程序")
+        print("=" * 50 + "\n")
+        
+        # 收集信息
+        app_id = input("小程序ID（用于标识，如 my-app）: ").strip()
+        if not app_id:
+            print("❌ ID不能为空")
+            return
+        
+        name = input("小程序名称: ").strip()
+        appid = input("AppID（如 wx1234567890）: ").strip()
+        project_path = input("项目路径: ").strip()
+        
+        if not os.path.exists(project_path):
+            print(f"⚠️ 警告：路径不存在 {project_path}")
+        
+        api_domain = input("API域名（可选）: ").strip()
+        description = input("描述（可选）: ").strip()
+        
+        # 认证信息
+        print("\n📋 认证信息（可稍后配置）:")
+        enterprise_name = input("企业名称: ").strip()
+        
+        app = AppConfig(
+            id=app_id,
+            name=name,
+            appid=appid,
+            project_path=project_path,
+            api_domain=api_domain,
+            description=description,
+            certification={
+                "status": "unknown",
+                "enterprise_name": enterprise_name,
+                "license_number": "",
+                "legal_persona_name": "",
+                "legal_persona_wechat": "",
+                "component_phone": "15880802661"
+            }
+        )
+        
+        self.config.add_app(app)
+        print(f"\n✅ 小程序 [{name}] 添加成功！")
+    
+    def deploy(self, app_id: str, skip_cert_check: bool = False, submit_audit: bool = False):
+        """一键部署流程（默认只上传 + 设为体验版，不提交审核）"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            print("   运行 'python mp_deploy.py list' 查看所有小程序")
+            return False
+        
+        print("\n" + "=" * 60)
+        print(f"  🚀 一键部署: {app.name}")
+        print("=" * 60)
+        
+        steps = [
+            ("检查环境", self._step_check_env),
+            ("检查认证状态", lambda a: self._step_check_cert(a, skip_cert_check)),
+            ("编译项目", self._step_build),
+            ("上传代码", self._step_upload),
+        ]
+        if submit_audit:
+            steps.append(("提交审核", self._step_submit_audit))
+        
+        for step_name, step_func in steps:
+            print(f"\n📍 步骤: {step_name}")
+            print("-" * 40)
+            
+            success = step_func(app)
+            if not success:
+                print(f"\n❌ 部署中断于: {step_name}")
+                return False
+        
+        print("\n" + "=" * 60)
+        print("  🎉 部署完成！已上传并设为体验版")
+        print("=" * 60)
+        if not submit_audit:
+            print(f"\n  当前状态: 体验版（未提交审核）")
+            print(f"  下一步操作:")
+            print(f"    1. 扫码体验确认无问题")
+            print(f"    2. 需要提审时运行: python mp_deploy.py submit {app_id}")
+            print(f"    3. 或一键部署+提审: python mp_deploy.py deploy {app_id} --submit")
+        else:
+            print(f"\n  下一步操作:")
+            print(f"    1. 等待审核（通常1-3个工作日）")
+            print(f"    2. 审核通过后运行: python mp_deploy.py release {app_id}")
+        
+        return True
+    
+    def _step_check_env(self, app: AppConfig) -> bool:
+        """检查环境"""
+        # 检查微信开发者工具
+        if not self._check_wx_cli():
+            print("❌ 未找到微信开发者工具")
+            print("   请安装: https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html")
+            return False
+        print("✅ 微信开发者工具已安装")
+        
+        # 检查项目路径
+        if not os.path.exists(app.project_path):
+            print(f"❌ 项目路径不存在: {app.project_path}")
+            return False
+        print(f"✅ 项目路径存在")
+        
+        # 检查project.config.json
+        config_file = os.path.join(app.project_path, "project.config.json")
+        if os.path.exists(config_file):
+            with open(config_file, 'r') as f:
+                config = json.load(f)
+                if config.get("appid") != app.appid:
+                    print(f"⚠️ 警告: project.config.json中的AppID与配置不一致")
+                    print(f"   配置: {app.appid}")
+                    print(f"   文件: {config.get('appid')}")
+        
+        print("✅ 环境检查通过")
+        return True
+    
+    def _step_check_cert(self, app: AppConfig, skip: bool = False) -> bool:
+        """检查认证状态"""
+        if skip:
+            print("⏭️ 跳过认证检查")
+            return True
+        
+        cert_status = app.certification.get("status", "unknown")
+        
+        if cert_status == "verified":
+            print("✅ 已完成微信认证")
+            return True
+        
+        if cert_status == "pending":
+            print("⏳ 认证审核中")
+            print("   可选择:")
+            print("   1. 继续部署（未认证可上传，但无法发布）")
+            print("   2. 等待认证完成")
+            
+            choice = input("\n是否继续? (y/n): ").strip().lower()
+            return choice == 'y'
+        
+        if cert_status == "expired":
+            print("⚠️ 认证已过期，需要重新认证")
+            print("   运行: python mp_deploy.py cert " + app.id)
+            
+            choice = input("\n是否继续部署? (y/n): ").strip().lower()
+            return choice == 'y'
+        
+        # 未认证或未知状态
+        print("⚠️ 未完成微信认证")
+        print("   未认证的小程序可以上传代码，但无法发布上线")
+        print("   运行: python mp_deploy.py cert " + app.id + " 提交认证")
+        
+        choice = input("\n是否继续? (y/n): ").strip().lower()
+        return choice == 'y'
+    
+    def _step_build(self, app: AppConfig) -> bool:
+        """编译项目"""
+        print("📦 编译项目...")
+        
+        # 使用CLI编译
+        success, output = self._run_cli("build-npm", project_path=app.project_path)
+        
+        if not success:
+            # build-npm可能失败（如果没有npm依赖），不算错误
+            print("ℹ️ 编译完成（无npm依赖或编译失败，继续...）")
+        else:
+            print("✅ 编译成功")
+        
+        return True
+    
+    def _step_upload(self, app: AppConfig) -> bool:
+        """上传代码"""
+        # 使用配置的默认版本 1.2.6
+        version = self.config.config.get("default_version", "1.2.6")
+        desc = f"自动部署 - {datetime.now().strftime('%Y-%m-%d %H:%M')}"
+        
+        print(f"📤 上传代码...")
+        print(f"   版本: {version}")
+        print(f"   描述: {desc}")
+        
+        success, output = self._run_cli(
+            "upload",
+            "--version", version,
+            "--desc", desc,
+            project_path=app.project_path
+        )
+        
+        if not success:
+            print(f"❌ 上传失败")
+            print(f"   {output}")
+            
+            # 常见错误处理
+            if "login" in output.lower():
+                print("\n💡 提示: 请在微信开发者工具中登录后重试")
+            return False
+        
+        print("✅ 上传成功")
+        self._print_experience_guide(app)
+        return True
+    
+    def _print_experience_guide(self, app: AppConfig):
+        """打印体验版操作指引，并尝试自动获取体验版二维码"""
+        print("\n" + "=" * 50)
+        print("  📱 体验版操作指引")
+        print("=" * 50)
+        print("  1. 登录 https://mp.weixin.qq.com/")
+        print("  2. 版本管理 → 开发版本 → 选为体验版")
+        print("  3. 确认后即可扫码体验")
+        
+        # 尝试自动获取体验版二维码
+        qr_path = self._fetch_experience_qrcode(app)
+        if qr_path:
+            print(f"  4. 体验版二维码已保存: {qr_path}")
+        else:
+            print("  4. 体验版二维码在：版本管理 → 体验版")
+        print("=" * 50 + "\n")
+    
+    def _fetch_experience_qrcode(self, app: AppConfig) -> Optional[str]:
+        """自动获取体验版小程序码并保存到文件，返回保存路径或 None"""
+        try:
+            sys.path.insert(0, str(Path(__file__).parent))
+            from mp_api import MiniProgramAPI, APIError
+            
+            api = MiniProgramAPI()
+            if not api.access_token:
+                return None
+            
+            # 使用 getwxacodeunlimit + env_version=trial（自有小程序可用，无需第三方平台）
+            data = api.get_wxacode_unlimit(scene="v=trial", env_version="trial")
+            out_dir = Path(__file__).parent / "reports"
+            out_dir.mkdir(exist_ok=True)
+            qr_path = out_dir / f"体验版二维码_{app.id}_{datetime.now().strftime('%Y%m%d_%H%M')}.png"
+            qr_path.write_bytes(data)
+            
+            if sys.platform == "darwin":
+                subprocess.run(["open", str(qr_path)], capture_output=True)
+            return str(qr_path)
+        except Exception as e:
+            if os.getenv("WECHAT_APPSECRET") or os.getenv("WECHAT_APPID"):
+                print(f"  ⚠️ 获取二维码失败: {e}")
+            return None
+    
+    def _step_submit_audit(self, app: AppConfig) -> bool:
+        """提交审核"""
+        print("📝 提交审核...")
+        
+        # 使用CLI提交审核
+        success, output = self._run_cli(
+            "submit-audit",
+            project_path=app.project_path
+        )
+        
+        if not success:
+            if "未认证" in output or "认证" in output:
+                print("⚠️ 提交审核失败：未完成微信认证")
+                print("   代码已上传，但需要完成认证后才能提交审核")
+                print(f"   运行: python mp_deploy.py cert {app.id}")
+                return True  # 不算失败，只是需要认证
+            
+            print(f"❌ 提交审核失败")
+            print(f"   {output}")
+            return False
+        
+        print("✅ 审核已提交")
+        return True
+    
+    def submit_certification(self, app_id: str):
+        """提交企业认证"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return
+        
+        print("\n" + "=" * 60)
+        print(f"  📋 提交认证: {app.name}")
+        print("=" * 60)
+        
+        # 获取通用认证材料
+        materials = self.config.get_cert_materials()
+        cert = app.certification
+        
+        # 合并材料（小程序配置优先）
+        enterprise_name = cert.get("enterprise_name") or materials.get("enterprise_name", "")
+        
+        print(f"\n📌 认证信息:")
+        print(f"   小程序: {app.name} ({app.appid})")
+        print(f"   企业名称: {enterprise_name}")
+        
+        # 检查必要材料
+        missing = []
+        if not enterprise_name:
+            missing.append("企业名称")
+        if not materials.get("license_number"):
+            missing.append("营业执照号")
+        if not materials.get("legal_persona_name"):
+            missing.append("法人姓名")
+        
+        if missing:
+            print(f"\n⚠️ 缺少认证材料:")
+            for m in missing:
+                print(f"   - {m}")
+            
+            print(f"\n请先完善认证材料:")
+            print(f"   编辑: {self.config.config_file}")
+            print(f"   或运行: python mp_deploy.py cert-config")
+            return
+        
+        print("\n" + "-" * 40)
+        print("📋 认证方式说明:")
+        print("-" * 40)
+        print("""
+  【方式一】微信后台手动认证（推荐）
+  
+  1. 登录小程序后台: https://mp.weixin.qq.com/
+  2. 设置 → 基本设置 → 微信认证
+  3. 选择"企业"类型
+  4. 填写企业信息、上传营业执照
+  5. 法人微信扫码验证
+  6. 支付认证费用（300元/年）
+  7. 等待审核（1-5个工作日）
+
+  【方式二】通过第三方平台代认证（需开发）
+  
+  如果你有第三方平台资质，可以通过API代认证：
+  1. 配置第三方平台凭证
+  2. 获取授权
+  3. 调用认证API
+  
+  API接口: POST /wxa/sec/wxaauth
+        """)
+        
+        print("\n" + "-" * 40)
+        print("📝 认证材料清单:")
+        print("-" * 40)
+        print("""
+  必需材料:
+  ☐ 企业营业执照（扫描件或照片）
+  ☐ 法人身份证（正反面）
+  ☐ 法人微信号（用于扫码验证）
+  ☐ 联系人手机号
+  ☐ 认证费用 300元
+  
+  认证有效期: 1年
+  到期后需重新认证（年审）
+        """)
+        
+        # 更新状态为待认证
+        self.config.update_app(app_id, {
+            "certification": {
+                **cert,
+                "status": "pending",
+                "submit_time": datetime.now().isoformat()
+            }
+        })
+        
+        print("\n✅ 已标记为待认证状态")
+        print("   完成认证后运行: python mp_deploy.py cert-done " + app_id)
+    
+    def check_cert_status(self, app_id: str):
+        """检查认证状态"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return
+        
+        print("\n" + "=" * 60)
+        print(f"  🔍 认证状态: {app.name}")
+        print("=" * 60)
+        
+        cert = app.certification
+        status = cert.get("status", "unknown")
+        
+        status_info = {
+            "verified": ("✅ 已认证", "认证有效"),
+            "pending": ("⏳ 审核中", "请等待审核结果"),
+            "rejected": ("❌ 被拒绝", "请查看拒绝原因并重新提交"),
+            "expired": ("⚠️ 已过期", "需要重新认证（年审）"),
+            "unknown": ("❓ 未知", "请在微信后台确认状态")
+        }
+        
+        icon, desc = status_info.get(status, ("❓", "未知状态"))
+        
+        print(f"\n📌 当前状态: {icon}")
+        print(f"   说明: {desc}")
+        print(f"   企业: {cert.get('enterprise_name', '未填写')}")
+        
+        if cert.get("submit_time"):
+            print(f"   提交时间: {cert.get('submit_time')}")
+        
+        if cert.get("verify_time"):
+            print(f"   认证时间: {cert.get('verify_time')}")
+        
+        if cert.get("expire_time"):
+            print(f"   到期时间: {cert.get('expire_time')}")
+        
+        # 提示下一步操作
+        print("\n" + "-" * 40)
+        if status == "unknown" or status == "rejected":
+            print("👉 下一步: python mp_deploy.py cert " + app_id)
+        elif status == "pending":
+            print("👉 等待审核，通常1-5个工作日")
+            print("   审核通过后运行: python mp_deploy.py cert-done " + app_id)
+        elif status == "verified":
+            print("👉 可以发布小程序: python mp_deploy.py deploy " + app_id)
+        elif status == "expired":
+            print("👉 需要重新认证: python mp_deploy.py cert " + app_id)
+    
+    def mark_cert_done(self, app_id: str):
+        """标记认证完成"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return
+        
+        cert = app.certification
+        self.config.update_app(app_id, {
+            "certification": {
+                **cert,
+                "status": "verified",
+                "verify_time": datetime.now().isoformat(),
+                "expire_time": datetime.now().replace(year=datetime.now().year + 1).isoformat()
+            }
+        })
+        
+        print(f"✅ 已标记 [{app.name}] 认证完成")
+        print(f"   有效期至: {datetime.now().year + 1}年")
+    
+    def release(self, app_id: str):
+        """发布上线"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return
+        
+        print("\n" + "=" * 60)
+        print(f"  🎉 发布上线: {app.name}")
+        print("=" * 60)
+        
+        # 检查认证状态
+        if app.certification.get("status") != "verified":
+            print("\n⚠️ 警告: 小程序未完成认证")
+            print("   未认证的小程序无法发布上线")
+            
+            choice = input("\n是否继续尝试? (y/n): ").strip().lower()
+            if choice != 'y':
+                return
+        
+        print("\n📦 正在发布...")
+        
+        # 尝试使用CLI发布
+        success, output = self._run_cli("release", project_path=app.project_path)
+        
+        if success:
+            print("\n🎉 发布成功！小程序已上线")
+        else:
+            print(f"\n发布结果: {output}")
+            
+            if "认证" in output:
+                print("\n💡 提示: 请先完成微信认证")
+                print(f"   运行: python mp_deploy.py cert {app_id}")
+            else:
+                print("\n💡 提示: 请在微信后台手动发布")
+                print("   1. 登录 https://mp.weixin.qq.com/")
+                print("   2. 版本管理 → 审核版本 → 发布")
+    
+    def quick_upload(self, app_id: str, version: str = None, desc: str = None):
+        """快速上传代码"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return
+        
+        if not version:
+            version = self.config.config.get("default_version", "1.2.6")
+        if not desc:
+            desc = f"快速上传 - {datetime.now().strftime('%Y-%m-%d %H:%M')}"
+        
+        print(f"\n📤 上传代码: {app.name}")
+        print(f"   版本: {version}")
+        print(f"   描述: {desc}")
+        
+        success, output = self._run_cli(
+            "upload",
+            "--version", version,
+            "--desc", desc,
+            project_path=app.project_path
+        )
+        
+        if success:
+            print("✅ 上传成功")
+            self._print_experience_guide(app)
+        else:
+            print(f"❌ 上传失败: {output}")
+
+    def submit_review(self, app_id: str):
+        """单独提交审核（需先上传代码）"""
+        app = self.config.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return False
+        
+        print("\n" + "=" * 60)
+        print(f"  📝 提交审核: {app.name}")
+        print("=" * 60)
+        
+        return self._step_submit_audit(app)
+
+
+def print_header(title: str):
+    print("\n" + "=" * 50)
+    print(f"  {title}")
+    print("=" * 50)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="小程序一键部署工具 v2.0",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  python mp_deploy.py list                         列出所有小程序
+  python mp_deploy.py deploy soul-party            上传+体验版（不提审）
+  python mp_deploy.py deploy soul-party --submit   上传+体验版+提交审核
+  python mp_deploy.py upload soul-party            快速上传代码
+  python mp_deploy.py submit soul-party            单独提交审核
+  python mp_deploy.py cert soul-party              提交认证
+  python mp_deploy.py release soul-party           发布上线
+
+部署流程:
+  1. deploy      上传代码 + 设为体验版（默认不提审）
+  2. submit      确认体验无问题后，单独提交审核
+  3. release     审核通过后发布上线
+"""
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="子命令")
+    
+    # list
+    subparsers.add_parser("list", help="列出所有小程序")
+    
+    # add
+    subparsers.add_parser("add", help="添加新小程序")
+    
+    # deploy
+    deploy_parser = subparsers.add_parser("deploy", help="一键部署（上传+体验版，默认不提审）")
+    deploy_parser.add_argument("app_id", help="小程序ID")
+    deploy_parser.add_argument("--skip-cert", action="store_true", help="跳过认证检查")
+    deploy_parser.add_argument("--submit", action="store_true", help="上传后自动提交审核")
+    
+    # cert
+    cert_parser = subparsers.add_parser("cert", help="提交认证")
+    cert_parser.add_argument("app_id", help="小程序ID")
+    
+    # cert-status
+    cert_status_parser = subparsers.add_parser("cert-status", help="查询认证状态")
+    cert_status_parser.add_argument("app_id", help="小程序ID")
+    
+    # cert-done
+    cert_done_parser = subparsers.add_parser("cert-done", help="标记认证完成")
+    cert_done_parser.add_argument("app_id", help="小程序ID")
+    
+    # upload
+    upload_parser = subparsers.add_parser("upload", help="上传代码")
+    upload_parser.add_argument("app_id", help="小程序ID")
+    upload_parser.add_argument("-v", "--version", help="版本号")
+    upload_parser.add_argument("-d", "--desc", help="版本描述")
+    
+    # submit (单独提交审核)
+    submit_parser = subparsers.add_parser("submit", help="提交审核（需先上传代码）")
+    submit_parser.add_argument("app_id", help="小程序ID")
+    
+    # release
+    release_parser = subparsers.add_parser("release", help="发布上线")
+    release_parser.add_argument("app_id", help="小程序ID")
+    
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        return
+    
+    deployer = MiniProgramDeployer()
+    
+    commands = {
+        "list": lambda: deployer.list_apps(),
+        "add": lambda: deployer.add_app(),
+        "deploy": lambda: deployer.deploy(
+            args.app_id,
+            args.skip_cert if hasattr(args, 'skip_cert') else False,
+            submit_audit=args.submit if hasattr(args, 'submit') else False,
+        ),
+        "cert": lambda: deployer.submit_certification(args.app_id),
+        "cert-status": lambda: deployer.check_cert_status(args.app_id),
+        "cert-done": lambda: deployer.mark_cert_done(args.app_id),
+        "upload": lambda: deployer.quick_upload(args.app_id, getattr(args, 'version', None), getattr(args, 'desc', None)),
+        "submit": lambda: deployer.submit_review(args.app_id),
+        "release": lambda: deployer.release(args.app_id),
+    }
+    
+    cmd_func = commands.get(args.command)
+    if cmd_func:
+        cmd_func()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/开发文档/小程序管理/scripts/mp_full.py b/开发文档/小程序管理/scripts/mp_full.py
new file mode 100644
index 00000000..2a754a2a
--- /dev/null
+++ b/开发文档/小程序管理/scripts/mp_full.py
@@ -0,0 +1,555 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+小程序全能管理工具 v3.0
+
+整合能力：
+- 微信开发者工具CLI
+- miniprogram-ci (npm官方工具)
+- 微信开放平台API
+- 多小程序管理
+- 自动化部署+提审
+- 汇总报告生成
+
+使用方法:
+    python mp_full.py report              # 生成汇总报告
+    python mp_full.py check <app_id>      # 检查项目问题
+    python mp_full.py auto <app_id>       # 全自动部署（上传+提审）
+    python mp_full.py batch-report        # 批量生成所有小程序报告
+"""
+
+import os
+import sys
+import json
+import subprocess
+import argparse
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, List, Any
+from dataclasses import dataclass, asdict, field
+
+# 配置文件路径
+SCRIPT_DIR = Path(__file__).parent
+CONFIG_FILE = SCRIPT_DIR / "apps_config.json"
+REPORT_DIR = SCRIPT_DIR / "reports"
+
+
+@dataclass
+class CheckResult:
+    """检查结果"""
+    name: str
+    status: str  # ok, warning, error
+    message: str
+    fix_hint: str = ""
+
+
+@dataclass
+class AppReport:
+    """小程序报告"""
+    app_id: str
+    app_name: str
+    appid: str
+    check_time: str
+    checks: List[CheckResult] = field(default_factory=list)
+    summary: Dict = field(default_factory=dict)
+    
+    @property
+    def has_errors(self) -> bool:
+        return any(c.status == "error" for c in self.checks)
+    
+    @property
+    def has_warnings(self) -> bool:
+        return any(c.status == "warning" for c in self.checks)
+
+
+class MiniProgramManager:
+    """小程序全能管理器"""
+    
+    # 工具路径
+    WX_CLI = "/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
+    
+    def __init__(self):
+        self.config = self._load_config()
+        REPORT_DIR.mkdir(exist_ok=True)
+    
+    def _load_config(self) -> Dict:
+        if CONFIG_FILE.exists():
+            with open(CONFIG_FILE, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        return {"apps": []}
+    
+    def _save_config(self):
+        with open(CONFIG_FILE, 'w', encoding='utf-8') as f:
+            json.dump(self.config, f, ensure_ascii=False, indent=2)
+    
+    def get_app(self, app_id: str) -> Optional[Dict]:
+        for app in self.config.get("apps", []):
+            if app["id"] == app_id or app["appid"] == app_id:
+                return app
+        return None
+    
+    def _run_cmd(self, cmd: List[str], timeout: int = 120) -> tuple:
+        """运行命令"""
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+            return result.returncode == 0, result.stdout + result.stderr
+        except subprocess.TimeoutExpired:
+            return False, "命令执行超时"
+        except Exception as e:
+            return False, str(e)
+    
+    def _check_tool(self, tool: str) -> bool:
+        """检查工具是否可用"""
+        success, _ = self._run_cmd(["which", tool], timeout=5)
+        return success
+    
+    # ==================== 检查功能 ====================
+    
+    def check_project(self, app_id: str) -> AppReport:
+        """检查项目问题"""
+        app = self.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return None
+        
+        report = AppReport(
+            app_id=app["id"],
+            app_name=app["name"],
+            appid=app["appid"],
+            check_time=datetime.now().isoformat()
+        )
+        
+        project_path = app["project_path"]
+        
+        # 1. 检查项目路径
+        if os.path.exists(project_path):
+            report.checks.append(CheckResult("项目路径", "ok", f"路径存在: {project_path}"))
+        else:
+            report.checks.append(CheckResult("项目路径", "error", f"路径不存在: {project_path}", "请检查项目路径配置"))
+            return report  # 路径不存在，无法继续检查
+        
+        # 2. 检查project.config.json
+        config_file = os.path.join(project_path, "project.config.json")
+        if os.path.exists(config_file):
+            with open(config_file, 'r') as f:
+                config = json.load(f)
+            
+            if config.get("appid") == app["appid"]:
+                report.checks.append(CheckResult("AppID配置", "ok", f"AppID正确: {app['appid']}"))
+            else:
+                report.checks.append(CheckResult("AppID配置", "error", 
+                    f"AppID不匹配: 配置={app['appid']}, 文件={config.get('appid')}",
+                    "请修改project.config.json中的appid"))
+        else:
+            report.checks.append(CheckResult("项目配置", "error", "project.config.json不存在", "请确认这是有效的小程序项目"))
+        
+        # 3. 检查app.js
+        app_js = os.path.join(project_path, "app.js")
+        if os.path.exists(app_js):
+            with open(app_js, 'r') as f:
+                content = f.read()
+            
+            # 检查API域名
+            if "baseUrl" in content or "apiBase" in content:
+                if "https://" in content:
+                    report.checks.append(CheckResult("API域名", "ok", "已配置HTTPS域名"))
+                elif "http://localhost" in content:
+                    report.checks.append(CheckResult("API域名", "warning", "使用本地开发地址", "发布前请更换为HTTPS域名"))
+                else:
+                    report.checks.append(CheckResult("API域名", "warning", "未检测到HTTPS域名"))
+            
+            report.checks.append(CheckResult("入口文件", "ok", "app.js存在"))
+        else:
+            report.checks.append(CheckResult("入口文件", "error", "app.js不存在"))
+        
+        # 4. 检查app.json
+        app_json = os.path.join(project_path, "app.json")
+        if os.path.exists(app_json):
+            with open(app_json, 'r') as f:
+                app_config = json.load(f)
+            
+            pages = app_config.get("pages", [])
+            if pages:
+                report.checks.append(CheckResult("页面配置", "ok", f"共{len(pages)}个页面"))
+            else:
+                report.checks.append(CheckResult("页面配置", "error", "没有配置页面"))
+            
+            # 检查隐私配置
+            if app_config.get("__usePrivacyCheck__"):
+                report.checks.append(CheckResult("隐私配置", "ok", "已启用隐私检查"))
+            else:
+                report.checks.append(CheckResult("隐私配置", "warning", "未启用隐私检查", "建议添加 __usePrivacyCheck__: true"))
+        else:
+            report.checks.append(CheckResult("应用配置", "error", "app.json不存在"))
+        
+        # 5. 检查认证状态
+        cert_status = app.get("certification", {}).get("status", "unknown")
+        if cert_status == "verified":
+            report.checks.append(CheckResult("企业认证", "ok", "已完成认证"))
+        elif cert_status == "pending":
+            report.checks.append(CheckResult("企业认证", "warning", "认证审核中", "等待审核结果"))
+        elif cert_status == "expired":
+            report.checks.append(CheckResult("企业认证", "error", "认证已过期", "请尽快完成年审"))
+        else:
+            report.checks.append(CheckResult("企业认证", "warning", "未认证", "无法发布上线，请先完成认证"))
+        
+        # 6. 检查开发工具
+        if os.path.exists(self.WX_CLI):
+            report.checks.append(CheckResult("开发者工具", "ok", "微信开发者工具已安装"))
+        else:
+            report.checks.append(CheckResult("开发者工具", "error", "微信开发者工具未安装"))
+        
+        # 7. 检查miniprogram-ci
+        if self._check_tool("miniprogram-ci"):
+            report.checks.append(CheckResult("miniprogram-ci", "ok", "npm工具已安装"))
+        else:
+            report.checks.append(CheckResult("miniprogram-ci", "warning", "miniprogram-ci未安装", "运行: npm install -g miniprogram-ci"))
+        
+        # 8. 检查私钥
+        if app.get("private_key_path") and os.path.exists(app["private_key_path"]):
+            report.checks.append(CheckResult("上传密钥", "ok", "私钥文件存在"))
+        else:
+            report.checks.append(CheckResult("上传密钥", "warning", "未配置私钥", "在小程序后台下载代码上传密钥"))
+        
+        # 生成汇总
+        ok_count = sum(1 for c in report.checks if c.status == "ok")
+        warn_count = sum(1 for c in report.checks if c.status == "warning")
+        error_count = sum(1 for c in report.checks if c.status == "error")
+        
+        report.summary = {
+            "total": len(report.checks),
+            "ok": ok_count,
+            "warning": warn_count,
+            "error": error_count,
+            "can_deploy": error_count == 0,
+            "can_release": cert_status == "verified" and error_count == 0
+        }
+        
+        return report
+    
+    def print_report(self, report: AppReport):
+        """打印报告"""
+        print("\n" + "=" * 70)
+        print(f"  📊 项目检查报告: {report.app_name}")
+        print("=" * 70)
+        print(f"  AppID: {report.appid}")
+        print(f"  检查时间: {report.check_time}")
+        print("-" * 70)
+        
+        status_icons = {"ok": "✅", "warning": "⚠️", "error": "❌"}
+        
+        for check in report.checks:
+            icon = status_icons.get(check.status, "❓")
+            print(f"  {icon} {check.name}: {check.message}")
+            if check.fix_hint:
+                print(f"      💡 {check.fix_hint}")
+        
+        print("-" * 70)
+        s = report.summary
+        print(f"  📈 汇总: 通过 {s['ok']} / 警告 {s['warning']} / 错误 {s['error']}")
+        
+        if s['can_release']:
+            print("  🎉 状态: 可以发布上线")
+        elif s['can_deploy']:
+            print("  📦 状态: 可以上传代码，但无法发布（需完成认证）")
+        else:
+            print("  🚫 状态: 存在错误，请先修复")
+        
+        print("=" * 70 + "\n")
+    
+    def save_report(self, report: AppReport):
+        """保存报告到文件"""
+        filename = f"report_{report.app_id}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+        filepath = REPORT_DIR / filename
+        
+        with open(filepath, 'w', encoding='utf-8') as f:
+            json.dump(asdict(report), f, ensure_ascii=False, indent=2)
+        
+        return filepath
+    
+    # ==================== 自动化部署 ====================
+    
+    def auto_deploy(self, app_id: str, version: str = None, desc: str = None, submit_audit: bool = True) -> bool:
+        """全自动部署：编译 → 上传 → 提审"""
+        app = self.get_app(app_id)
+        if not app:
+            print(f"❌ 未找到小程序: {app_id}")
+            return False
+        
+        print("\n" + "=" * 70)
+        print(f"  🚀 全自动部署: {app['name']}")
+        print("=" * 70)
+        
+        # 1. 先检查项目
+        print("\n📋 步骤1: 检查项目...")
+        report = self.check_project(app_id)
+        if report.has_errors:
+            print("❌ 项目存在错误，无法部署")
+            self.print_report(report)
+            return False
+        print("✅ 项目检查通过")
+        
+        # 2. 准备版本信息
+        if not version:
+            version = datetime.now().strftime("%Y.%m.%d.%H%M")
+        if not desc:
+            desc = f"自动部署 - {datetime.now().strftime('%Y-%m-%d %H:%M')}"
+        
+        print(f"\n📦 步骤2: 上传代码...")
+        print(f"   版本: {version}")
+        print(f"   描述: {desc}")
+        
+        # 3. 上传代码
+        success = self._upload_code(app, version, desc)
+        if not success:
+            print("❌ 代码上传失败")
+            return False
+        print("✅ 代码上传成功")
+        
+        # 4. 提交审核
+        if submit_audit:
+            print(f"\n📝 步骤3: 提交审核...")
+            cert_status = app.get("certification", {}).get("status", "unknown")
+            
+            if cert_status != "verified":
+                print(f"⚠️ 认证状态: {cert_status}")
+                print("   未认证的小程序无法提交审核")
+                print("   代码已上传到开发版，请在微信后台手动提交")
+                print("\n" + "-" * 40)
+                print("👉 下一步操作:")
+                print("   1. 完成企业认证")
+                print("   2. 在微信后台提交审核")
+                print("   3. 审核通过后发布上线")
+            else:
+                # 尝试通过API提交审核
+                audit_success = self._submit_audit_via_api(app)
+                if audit_success:
+                    print("✅ 审核已提交")
+                else:
+                    print("⚠️ 自动提审失败，请在微信后台手动提交")
+                    print("   登录: https://mp.weixin.qq.com/")
+                    print("   版本管理 → 开发版本 → 提交审核")
+        
+        # 5. 生成报告
+        print(f"\n📊 步骤4: 生成报告...")
+        report_file = self.save_report(report)
+        print(f"✅ 报告已保存: {report_file}")
+        
+        print("\n" + "=" * 70)
+        print("  🎉 部署完成！")
+        print("=" * 70)
+        
+        return True
+    
+    def _upload_code(self, app: Dict, version: str, desc: str) -> bool:
+        """上传代码（优先使用CLI）"""
+        project_path = app["project_path"]
+        
+        # 方法1：使用微信开发者工具CLI
+        if os.path.exists(self.WX_CLI):
+            cmd = [
+                self.WX_CLI, "upload",
+                "--project", project_path,
+                "--version", version,
+                "--desc", desc
+            ]
+            success, output = self._run_cmd(cmd, timeout=120)
+            if success:
+                return True
+            print(f"   CLI上传失败: {output[:200]}")
+        
+        # 方法2：使用miniprogram-ci
+        if self._check_tool("miniprogram-ci") and app.get("private_key_path"):
+            cmd = [
+                "miniprogram-ci", "upload",
+                "--pp", project_path,
+                "--pkp", app["private_key_path"],
+                "--appid", app["appid"],
+                "--uv", version,
+                "-r", "1",
+                "--desc", desc
+            ]
+            success, output = self._run_cmd(cmd, timeout=120)
+            if success:
+                return True
+            print(f"   miniprogram-ci上传失败: {output[:200]}")
+        
+        return False
+    
+    def _submit_audit_via_api(self, app: Dict) -> bool:
+        """通过API提交审核（需要access_token）"""
+        # 这里需要access_token才能调用API
+        # 目前返回False，提示用户手动提交
+        return False
+    
+    # ==================== 汇总报告 ====================
+    
+    def generate_summary_report(self):
+        """生成所有小程序的汇总报告"""
+        apps = self.config.get("apps", [])
+        
+        if not apps:
+            print("📭 暂无配置的小程序")
+            return
+        
+        print("\n" + "=" * 80)
+        print("  📊 小程序管理汇总报告")
+        print(f"  生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        print("=" * 80)
+        
+        all_reports = []
+        
+        for app in apps:
+            report = self.check_project(app["id"])
+            if report:
+                all_reports.append(report)
+        
+        # 打印汇总表格
+        print("\n┌" + "─" * 78 + "┐")
+        print(f"│ {'小程序名称':<20} │ {'AppID':<25} │ {'状态':<10} │ {'可发布':<8} │")
+        print("├" + "─" * 78 + "┤")
+        
+        for report in all_reports:
+            status = "✅ 正常" if not report.has_errors else "❌ 错误"
+            can_release = "✅" if report.summary.get("can_release") else "❌"
+            print(f"│ {report.app_name:<20} │ {report.appid:<25} │ {status:<10} │ {can_release:<8} │")
+        
+        print("└" + "─" * 78 + "┘")
+        
+        # 统计
+        total = len(all_reports)
+        ok_count = sum(1 for r in all_reports if not r.has_errors and not r.has_warnings)
+        warn_count = sum(1 for r in all_reports if r.has_warnings and not r.has_errors)
+        error_count = sum(1 for r in all_reports if r.has_errors)
+        can_release = sum(1 for r in all_reports if r.summary.get("can_release"))
+        
+        print(f"\n📈 统计:")
+        print(f"   总计: {total} 个小程序")
+        print(f"   正常: {ok_count} | 警告: {warn_count} | 错误: {error_count}")
+        print(f"   可发布: {can_release} 个")
+        
+        # 问题清单
+        issues = []
+        for report in all_reports:
+            for check in report.checks:
+                if check.status == "error":
+                    issues.append((report.app_name, check.name, check.message, check.fix_hint))
+        
+        if issues:
+            print(f"\n⚠️ 问题清单 ({len(issues)} 个):")
+            print("-" * 60)
+            for app_name, check_name, message, hint in issues:
+                print(f"  [{app_name}] {check_name}: {message}")
+                if hint:
+                    print(f"      💡 {hint}")
+        else:
+            print(f"\n✅ 所有小程序状态正常")
+        
+        # 待办事项
+        print(f"\n📋 待办事项:")
+        for report in all_reports:
+            cert_status = "unknown"
+            for check in report.checks:
+                if check.name == "企业认证":
+                    if "审核中" in check.message:
+                        cert_status = "pending"
+                    elif "已完成" in check.message:
+                        cert_status = "verified"
+                    elif "未认证" in check.message:
+                        cert_status = "unknown"
+                    break
+            
+            if cert_status == "pending":
+                print(f"   ⏳ {report.app_name}: 等待认证审核结果")
+            elif cert_status == "unknown":
+                print(f"   📝 {report.app_name}: 需要完成企业认证")
+        
+        print("\n" + "=" * 80)
+        
+        # 保存汇总报告
+        summary_file = REPORT_DIR / f"summary_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+        summary_data = {
+            "generated_at": datetime.now().isoformat(),
+            "total_apps": total,
+            "summary": {
+                "ok": ok_count,
+                "warning": warn_count,
+                "error": error_count,
+                "can_release": can_release
+            },
+            "apps": [asdict(r) for r in all_reports]
+        }
+        with open(summary_file, 'w', encoding='utf-8') as f:
+            json.dump(summary_data, f, ensure_ascii=False, indent=2)
+        
+        print(f"📁 报告已保存: {summary_file}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="小程序全能管理工具 v3.0",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  python mp_full.py report                生成汇总报告
+  python mp_full.py check soul-party      检查项目问题
+  python mp_full.py auto soul-party       全自动部署（上传+提审）
+  python mp_full.py auto soul-party -v 1.0.13 -d "修复问题"
+
+流程说明:
+  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+  │  检查   │ → │  编译   │ → │  上传   │ → │  提审   │ → │  发布   │
+  │ check   │    │  build  │    │ upload  │    │  audit  │    │ release │
+  └─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘
+
+工具整合:
+  • 微信开发者工具CLI - 本地编译上传
+  • miniprogram-ci    - npm官方CI工具
+  • 开放平台API       - 审核/发布/认证
+"""
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="子命令")
+    
+    # report
+    subparsers.add_parser("report", help="生成汇总报告")
+    
+    # check
+    check_parser = subparsers.add_parser("check", help="检查项目问题")
+    check_parser.add_argument("app_id", help="小程序ID")
+    
+    # auto
+    auto_parser = subparsers.add_parser("auto", help="全自动部署")
+    auto_parser.add_argument("app_id", help="小程序ID")
+    auto_parser.add_argument("-v", "--version", help="版本号")
+    auto_parser.add_argument("-d", "--desc", help="版本描述")
+    auto_parser.add_argument("--no-audit", action="store_true", help="不提交审核")
+    
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        return
+    
+    manager = MiniProgramManager()
+    
+    if args.command == "report":
+        manager.generate_summary_report()
+    
+    elif args.command == "check":
+        report = manager.check_project(args.app_id)
+        if report:
+            manager.print_report(report)
+            manager.save_report(report)
+    
+    elif args.command == "auto":
+        manager.auto_deploy(
+            args.app_id,
+            version=args.version,
+            desc=args.desc,
+            submit_audit=not args.no_audit
+        )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/开发文档/小程序管理/scripts/mp_manager.py b/开发文档/小程序管理/scripts/mp_manager.py
new file mode 100644
index 00000000..197f780d
--- /dev/null
+++ b/开发文档/小程序管理/scripts/mp_manager.py
@@ -0,0 +1,558 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+微信小程序管理命令行工具
+
+使用方法:
+    python mp_manager.py status     # 查看小程序状态
+    python mp_manager.py audit      # 查看审核状态
+    python mp_manager.py release    # 发布上线
+    python mp_manager.py qrcode     # 生成小程序码
+    python mp_manager.py domain     # 查看/配置域名
+    python mp_manager.py privacy    # 配置隐私协议
+    python mp_manager.py data       # 查看数据分析
+"""
+
+import os
+import sys
+import argparse
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# 添加当前目录到路径
+sys.path.insert(0, str(Path(__file__).parent))
+
+from mp_api import MiniProgramAPI, APIError, create_api_from_env
+
+
+def print_header(title: str):
+    """打印标题"""
+    print("\n" + "=" * 50)
+    print(f"  {title}")
+    print("=" * 50)
+
+
+def print_success(message: str):
+    """打印成功信息"""
+    print(f"✅ {message}")
+
+
+def print_error(message: str):
+    """打印错误信息"""
+    print(f"❌ {message}")
+
+
+def print_info(message: str):
+    """打印信息"""
+    print(f"ℹ️  {message}")
+
+
+def cmd_status(api: MiniProgramAPI, args):
+    """查看小程序状态"""
+    print_header("小程序基础信息")
+    
+    try:
+        info = api.get_basic_info()
+        print(f"\n📱 AppID: {info.appid}")
+        print(f"📝 名称: {info.nickname}")
+        print(f"📄 简介: {info.signature}")
+        print(f"🏢 主体: {info.principal_name}")
+        print(f"✓ 认证状态: {'已认证' if info.realname_status == 1 else '未认证'}")
+        
+        if info.head_image_url:
+            print(f"🖼️  头像: {info.head_image_url}")
+        
+        # 获取类目
+        print("\n📂 已设置类目:")
+        categories = api.get_category()
+        if categories:
+            for cat in categories:
+                print(f"   - {cat.get('first_class', '')} > {cat.get('second_class', '')}")
+        else:
+            print("   (未设置类目)")
+        
+    except APIError as e:
+        print_error(f"获取信息失败: {e}")
+
+
+def cmd_audit(api: MiniProgramAPI, args):
+    """查看审核状态"""
+    print_header("审核状态")
+    
+    try:
+        status = api.get_latest_audit_status()
+        print(f"\n🔢 审核单ID: {status.auditid}")
+        print(f"📊 状态: {status.status_text}")
+        
+        if status.reason:
+            print(f"\n❗ 拒绝原因:")
+            print(f"   {status.reason}")
+        
+        if status.screenshot:
+            print(f"\n📸 问题截图: {status.screenshot}")
+        
+        if status.status == 0:
+            print("\n👉 下一步: 运行 'python mp_manager.py release' 发布上线")
+        elif status.status == 1:
+            print("\n👉 请根据拒绝原因修改后重新提交审核")
+        elif status.status == 2:
+            print("\n👉 审核中，请耐心等待（通常1-3个工作日）")
+            print("   可运行 'python mp_manager.py audit' 再次查询")
+        
+    except APIError as e:
+        print_error(f"获取审核状态失败: {e}")
+
+
+def cmd_submit(api: MiniProgramAPI, args):
+    """提交审核"""
+    print_header("提交审核")
+    
+    version_desc = args.desc or input("请输入版本说明: ").strip()
+    if not version_desc:
+        print_error("版本说明不能为空")
+        return
+    
+    try:
+        # 获取页面列表
+        pages = api.get_page()
+        if not pages:
+            print_error("未找到页面，请先上传代码")
+            return
+        
+        print(f"\n📄 检测到 {len(pages)} 个页面:")
+        for p in pages[:5]:
+            print(f"   - {p}")
+        if len(pages) > 5:
+            print(f"   ... 还有 {len(pages) - 5} 个")
+        
+        # 确认提交
+        confirm = input("\n确认提交审核? (y/n): ").strip().lower()
+        if confirm != 'y':
+            print_info("已取消")
+            return
+        
+        auditid = api.submit_audit(version_desc=version_desc)
+        print_success(f"审核已提交，审核单ID: {auditid}")
+        print("\n👉 运行 'python mp_manager.py audit' 查询审核状态")
+        
+    except APIError as e:
+        print_error(f"提交审核失败: {e}")
+
+
+def cmd_release(api: MiniProgramAPI, args):
+    """发布上线"""
+    print_header("发布上线")
+    
+    try:
+        # 先检查审核状态
+        status = api.get_latest_audit_status()
+        if status.status != 0:
+            print_error(f"当前审核状态: {status.status_text}")
+            print_info("只有审核通过的版本才能发布")
+            return
+        
+        print(f"📊 审核状态: {status.status_text}")
+        
+        # 确认发布
+        confirm = input("\n确认发布上线? (y/n): ").strip().lower()
+        if confirm != 'y':
+            print_info("已取消")
+            return
+        
+        api.release()
+        print_success("🎉 发布成功！小程序已上线")
+        
+    except APIError as e:
+        print_error(f"发布失败: {e}")
+
+
+def cmd_revert(api: MiniProgramAPI, args):
+    """版本回退"""
+    print_header("版本回退")
+    
+    try:
+        # 获取可回退版本
+        history = api.get_revert_history()
+        if not history:
+            print_info("没有可回退的版本")
+            return
+        
+        print("\n📜 可回退版本:")
+        for v in history:
+            print(f"   - {v.get('user_version', '?')}: {v.get('user_desc', '')}")
+        
+        # 确认回退
+        confirm = input("\n确认回退到上一版本? (y/n): ").strip().lower()
+        if confirm != 'y':
+            print_info("已取消")
+            return
+        
+        api.revert_code_release()
+        print_success("版本回退成功")
+        
+    except APIError as e:
+        print_error(f"版本回退失败: {e}")
+
+
+def cmd_qrcode(api: MiniProgramAPI, args):
+    """生成小程序码"""
+    print_header("生成小程序码")
+    
+    # 场景选择
+    print("\n选择类型:")
+    print("  1. 体验版二维码")
+    print("  2. 小程序码（有限制，每个path最多10万个）")
+    print("  3. 无限小程序码（推荐）")
+    
+    choice = args.type or input("\n请选择 (1/2/3): ").strip()
+    
+    output_file = args.output or f"qrcode_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
+    
+    try:
+        if choice == "1":
+            # 体验版二维码
+            path = args.path or input("页面路径 (默认首页): ").strip() or None
+            data = api.get_qrcode(path)
+            
+        elif choice == "2":
+            # 小程序码
+            path = args.path or input("页面路径: ").strip()
+            if not path:
+                print_error("页面路径不能为空")
+                return
+            data = api.get_wxacode(path)
+            
+        elif choice == "3":
+            # 无限小程序码
+            scene = args.scene or input("场景值 (最长32字符): ").strip()
+            if not scene:
+                print_error("场景值不能为空")
+                return
+            page = args.path or input("页面路径 (需已发布): ").strip() or None
+            data = api.get_wxacode_unlimit(scene, page)
+            
+        else:
+            print_error("无效选择")
+            return
+        
+        # 保存文件
+        with open(output_file, "wb") as f:
+            f.write(data)
+        
+        print_success(f"小程序码已保存: {output_file}")
+        
+        # 尝试打开
+        if sys.platform == "darwin":
+            os.system(f'open "{output_file}"')
+        
+    except APIError as e:
+        print_error(f"生成小程序码失败: {e}")
+
+
+def cmd_domain(api: MiniProgramAPI, args):
+    """查看/配置域名"""
+    print_header("域名配置")
+    
+    try:
+        # 获取当前配置
+        domains = api.get_domain()
+        webview_domains = api.get_webview_domain()
+        
+        print("\n🌐 服务器域名:")
+        print(f"   request: {', '.join(domains.get('requestdomain', [])) or '(无)'}")
+        print(f"   wsrequest: {', '.join(domains.get('wsrequestdomain', [])) or '(无)'}")
+        print(f"   upload: {', '.join(domains.get('uploaddomain', [])) or '(无)'}")
+        print(f"   download: {', '.join(domains.get('downloaddomain', [])) or '(无)'}")
+        
+        print(f"\n🔗 业务域名:")
+        print(f"   webview: {', '.join(webview_domains) or '(无)'}")
+        
+        # 是否要配置
+        if args.set_request:
+            print(f"\n配置 request 域名: {args.set_request}")
+            api.set_domain(requestdomain=[args.set_request])
+            print_success("域名配置成功")
+        
+    except APIError as e:
+        print_error(f"域名配置失败: {e}")
+
+
+def cmd_privacy(api: MiniProgramAPI, args):
+    """配置隐私协议"""
+    print_header("隐私协议配置")
+    
+    try:
+        # 获取当前配置
+        settings = api.get_privacy_setting()
+        
+        print("\n📋 当前隐私设置:")
+        setting_list = settings.get("setting_list", [])
+        if setting_list:
+            for s in setting_list:
+                print(f"   - {s.get('privacy_key', '?')}: {s.get('privacy_text', '')}")
+        else:
+            print("   (未配置)")
+        
+        owner = settings.get("owner_setting", {})
+        if owner:
+            print(f"\n📧 联系方式:")
+            if owner.get("contact_email"):
+                print(f"   邮箱: {owner['contact_email']}")
+            if owner.get("contact_phone"):
+                print(f"   电话: {owner['contact_phone']}")
+        
+        # 快速配置
+        if args.quick:
+            print("\n⚡ 快速配置常用隐私项...")
+            
+            default_settings = [
+                {"privacy_key": "UserInfo", "privacy_text": "用于展示您的头像和昵称"},
+                {"privacy_key": "Location", "privacy_text": "用于获取您的位置信息以推荐附近服务"},
+                {"privacy_key": "PhoneNumber", "privacy_text": "用于登录验证和订单通知"},
+            ]
+            
+            api.set_privacy_setting(
+                setting_list=default_settings,
+                contact_email=args.email or "contact@example.com",
+                contact_phone=args.phone or "15880802661"
+            )
+            print_success("隐私协议配置成功")
+        
+    except APIError as e:
+        print_error(f"隐私协议配置失败: {e}")
+
+
+def cmd_data(api: MiniProgramAPI, args):
+    """查看数据分析"""
+    print_header("数据分析")
+    
+    # 默认查询最近7天
+    end_date = datetime.now().strftime("%Y%m%d")
+    begin_date = (datetime.now() - timedelta(days=7)).strftime("%Y%m%d")
+    
+    if args.begin:
+        begin_date = args.begin
+    if args.end:
+        end_date = args.end
+    
+    try:
+        print(f"\n📊 访问趋势 ({begin_date} ~ {end_date}):")
+        
+        data = api.get_daily_visit_trend(begin_date, end_date)
+        if not data:
+            print("   (暂无数据)")
+            return
+        
+        # 统计汇总
+        total_pv = sum(d.get("visit_pv", 0) for d in data)
+        total_uv = sum(d.get("visit_uv", 0) for d in data)
+        total_new = sum(d.get("visit_uv_new", 0) for d in data)
+        
+        print(f"\n📈 汇总数据:")
+        print(f"   总访问次数: {total_pv:,}")
+        print(f"   总访问人数: {total_uv:,}")
+        print(f"   新用户数: {total_new:,}")
+        
+        print(f"\n📅 每日明细:")
+        for d in data[-7:]:  # 只显示最近7天
+            date = d.get("ref_date", "?")
+            pv = d.get("visit_pv", 0)
+            uv = d.get("visit_uv", 0)
+            stay = d.get("stay_time_uv", 0)
+            print(f"   {date}: PV={pv}, UV={uv}, 人均停留={stay:.1f}秒")
+        
+    except APIError as e:
+        print_error(f"获取数据失败: {e}")
+
+
+def cmd_quota(api: MiniProgramAPI, args):
+    """查看API配额"""
+    print_header("API配额")
+    
+    common_apis = [
+        "/wxa/getwxacode",
+        "/wxa/getwxacodeunlimit",
+        "/wxa/genwxashortlink",
+        "/wxa/submit_audit",
+        "/cgi-bin/message/subscribe/send"
+    ]
+    
+    try:
+        for cgi_path in common_apis:
+            try:
+                quota = api.get_api_quota(cgi_path)
+                daily_limit = quota.get("daily_limit", 0)
+                used = quota.get("used", 0)
+                remain = quota.get("remain", 0)
+                
+                print(f"\n📌 {cgi_path}")
+                print(f"   每日限额: {daily_limit:,}")
+                print(f"   已使用: {used:,}")
+                print(f"   剩余: {remain:,}")
+            except APIError:
+                pass
+        
+    except APIError as e:
+        print_error(f"获取配额失败: {e}")
+
+
+def cmd_cli(api: MiniProgramAPI, args):
+    """使用微信开发者工具CLI"""
+    print_header("微信开发者工具CLI")
+    
+    cli_path = "/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
+    project_path = args.project or os.getenv("MINIPROGRAM_PATH", "")
+    
+    if not project_path:
+        project_path = input("请输入小程序项目路径: ").strip()
+    
+    if not os.path.exists(project_path):
+        print_error(f"项目路径不存在: {project_path}")
+        return
+    
+    if not os.path.exists(cli_path):
+        print_error("未找到微信开发者工具，请先安装")
+        return
+    
+    print(f"\n📂 项目路径: {project_path}")
+    print("\n选择操作:")
+    print("  1. 打开项目")
+    print("  2. 预览（生成二维码）")
+    print("  3. 上传代码")
+    print("  4. 编译")
+    
+    choice = input("\n请选择: ").strip()
+    
+    if choice == "1":
+        os.system(f'"{cli_path}" -o "{project_path}"')
+        print_success("项目已打开")
+    
+    elif choice == "2":
+        output = f"{project_path}/preview.png"
+        os.system(f'"{cli_path}" preview --project "{project_path}" --qr-format image --qr-output "{output}"')
+        if os.path.exists(output):
+            print_success(f"预览二维码已生成: {output}")
+            os.system(f'open "{output}"')
+        else:
+            print_error("生成失败，请检查开发者工具是否已登录")
+    
+    elif choice == "3":
+        version = input("版本号 (如 1.0.0): ").strip()
+        desc = input("版本说明: ").strip()
+        os.system(f'"{cli_path}" upload --project "{project_path}" --version "{version}" --desc "{desc}"')
+        print_success("代码上传完成")
+    
+    elif choice == "4":
+        os.system(f'"{cli_path}" build-npm --project "{project_path}"')
+        print_success("编译完成")
+    
+    else:
+        print_error("无效选择")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="微信小程序管理工具",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  python mp_manager.py status           查看小程序状态
+  python mp_manager.py audit            查看审核状态
+  python mp_manager.py submit -d "修复xxx问题"  提交审核
+  python mp_manager.py release          发布上线
+  python mp_manager.py qrcode -t 3 -s "id=123"  生成无限小程序码
+  python mp_manager.py domain           查看域名配置
+  python mp_manager.py privacy --quick  快速配置隐私协议
+  python mp_manager.py data             查看数据分析
+  python mp_manager.py cli              使用开发者工具CLI
+"""
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="子命令")
+    
+    # status
+    subparsers.add_parser("status", help="查看小程序状态")
+    
+    # audit
+    subparsers.add_parser("audit", help="查看审核状态")
+    
+    # submit
+    submit_parser = subparsers.add_parser("submit", help="提交审核")
+    submit_parser.add_argument("-d", "--desc", help="版本说明")
+    
+    # release
+    subparsers.add_parser("release", help="发布上线")
+    
+    # revert
+    subparsers.add_parser("revert", help="版本回退")
+    
+    # qrcode
+    qr_parser = subparsers.add_parser("qrcode", help="生成小程序码")
+    qr_parser.add_argument("-t", "--type", choices=["1", "2", "3"], help="类型：1=体验版，2=小程序码，3=无限小程序码")
+    qr_parser.add_argument("-p", "--path", help="页面路径")
+    qr_parser.add_argument("-s", "--scene", help="场景值（类型3时使用）")
+    qr_parser.add_argument("-o", "--output", help="输出文件名")
+    
+    # domain
+    domain_parser = subparsers.add_parser("domain", help="查看/配置域名")
+    domain_parser.add_argument("--set-request", help="设置request域名")
+    
+    # privacy
+    privacy_parser = subparsers.add_parser("privacy", help="配置隐私协议")
+    privacy_parser.add_argument("--quick", action="store_true", help="快速配置常用隐私项")
+    privacy_parser.add_argument("--email", help="联系邮箱")
+    privacy_parser.add_argument("--phone", help="联系电话")
+    
+    # data
+    data_parser = subparsers.add_parser("data", help="查看数据分析")
+    data_parser.add_argument("--begin", help="开始日期 YYYYMMDD")
+    data_parser.add_argument("--end", help="结束日期 YYYYMMDD")
+    
+    # quota
+    subparsers.add_parser("quota", help="查看API配额")
+    
+    # cli
+    cli_parser = subparsers.add_parser("cli", help="使用微信开发者工具CLI")
+    cli_parser.add_argument("-p", "--project", help="小程序项目路径")
+    
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        return
+    
+    # 创建API实例
+    try:
+        api = create_api_from_env()
+    except Exception as e:
+        print_error(f"初始化API失败: {e}")
+        print_info("请检查 .env 文件中的配置")
+        return
+    
+    # 执行命令
+    commands = {
+        "status": cmd_status,
+        "audit": cmd_audit,
+        "submit": cmd_submit,
+        "release": cmd_release,
+        "revert": cmd_revert,
+        "qrcode": cmd_qrcode,
+        "domain": cmd_domain,
+        "privacy": cmd_privacy,
+        "data": cmd_data,
+        "quota": cmd_quota,
+        "cli": cmd_cli,
+    }
+    
+    cmd_func = commands.get(args.command)
+    if cmd_func:
+        try:
+            cmd_func(api, args)
+        finally:
+            api.close()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113301.json b/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113301.json
new file mode 100644
index 00000000..628d5a38
--- /dev/null
+++ b/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113301.json
@@ -0,0 +1,76 @@
+{
+  "app_id": "soul-party",
+  "app_name": "Soul派对",
+  "appid": "wxb8bbb2b10dec74aa",
+  "check_time": "2026-01-25T11:33:01.054516",
+  "checks": [
+    {
+      "name": "项目路径",
+      "status": "ok",
+      "message": "路径存在: /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram",
+      "fix_hint": ""
+    },
+    {
+      "name": "AppID配置",
+      "status": "ok",
+      "message": "AppID正确: wxb8bbb2b10dec74aa",
+      "fix_hint": ""
+    },
+    {
+      "name": "API域名",
+      "status": "ok",
+      "message": "已配置HTTPS域名",
+      "fix_hint": ""
+    },
+    {
+      "name": "入口文件",
+      "status": "ok",
+      "message": "app.js存在",
+      "fix_hint": ""
+    },
+    {
+      "name": "页面配置",
+      "status": "ok",
+      "message": "共9个页面",
+      "fix_hint": ""
+    },
+    {
+      "name": "隐私配置",
+      "status": "warning",
+      "message": "未启用隐私检查",
+      "fix_hint": "建议添加 __usePrivacyCheck__: true"
+    },
+    {
+      "name": "企业认证",
+      "status": "warning",
+      "message": "认证审核中",
+      "fix_hint": "等待审核结果"
+    },
+    {
+      "name": "开发者工具",
+      "status": "ok",
+      "message": "微信开发者工具已安装",
+      "fix_hint": ""
+    },
+    {
+      "name": "miniprogram-ci",
+      "status": "ok",
+      "message": "npm工具已安装",
+      "fix_hint": ""
+    },
+    {
+      "name": "上传密钥",
+      "status": "warning",
+      "message": "未配置私钥",
+      "fix_hint": "在小程序后台下载代码上传密钥"
+    }
+  ],
+  "summary": {
+    "total": 10,
+    "ok": 7,
+    "warning": 3,
+    "error": 0,
+    "can_deploy": true,
+    "can_release": false
+  }
+}
\ No newline at end of file
diff --git a/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113423.json b/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113423.json
new file mode 100644
index 00000000..60ca8c23
--- /dev/null
+++ b/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113423.json
@@ -0,0 +1,76 @@
+{
+  "app_id": "soul-party",
+  "app_name": "Soul派对",
+  "appid": "wxb8bbb2b10dec74aa",
+  "check_time": "2026-01-25T11:34:23.760802",
+  "checks": [
+    {
+      "name": "项目路径",
+      "status": "ok",
+      "message": "路径存在: /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram",
+      "fix_hint": ""
+    },
+    {
+      "name": "AppID配置",
+      "status": "ok",
+      "message": "AppID正确: wxb8bbb2b10dec74aa",
+      "fix_hint": ""
+    },
+    {
+      "name": "API域名",
+      "status": "ok",
+      "message": "已配置HTTPS域名",
+      "fix_hint": ""
+    },
+    {
+      "name": "入口文件",
+      "status": "ok",
+      "message": "app.js存在",
+      "fix_hint": ""
+    },
+    {
+      "name": "页面配置",
+      "status": "ok",
+      "message": "共9个页面",
+      "fix_hint": ""
+    },
+    {
+      "name": "隐私配置",
+      "status": "ok",
+      "message": "已启用隐私检查",
+      "fix_hint": ""
+    },
+    {
+      "name": "企业认证",
+      "status": "warning",
+      "message": "认证审核中",
+      "fix_hint": "等待审核结果"
+    },
+    {
+      "name": "开发者工具",
+      "status": "ok",
+      "message": "微信开发者工具已安装",
+      "fix_hint": ""
+    },
+    {
+      "name": "miniprogram-ci",
+      "status": "ok",
+      "message": "npm工具已安装",
+      "fix_hint": ""
+    },
+    {
+      "name": "上传密钥",
+      "status": "warning",
+      "message": "未配置私钥",
+      "fix_hint": "在小程序后台下载代码上传密钥"
+    }
+  ],
+  "summary": {
+    "total": 10,
+    "ok": 8,
+    "warning": 2,
+    "error": 0,
+    "can_deploy": true,
+    "can_release": false
+  }
+}
\ No newline at end of file
diff --git a/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113434.json b/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113434.json
new file mode 100644
index 00000000..83e19c8e
--- /dev/null
+++ b/开发文档/小程序管理/scripts/reports/report_soul-party_20260125_113434.json
@@ -0,0 +1,76 @@
+{
+  "app_id": "soul-party",
+  "app_name": "Soul派对",
+  "appid": "wxb8bbb2b10dec74aa",
+  "check_time": "2026-01-25T11:34:28.854418",
+  "checks": [
+    {
+      "name": "项目路径",
+      "status": "ok",
+      "message": "路径存在: /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram",
+      "fix_hint": ""
+    },
+    {
+      "name": "AppID配置",
+      "status": "ok",
+      "message": "AppID正确: wxb8bbb2b10dec74aa",
+      "fix_hint": ""
+    },
+    {
+      "name": "API域名",
+      "status": "ok",
+      "message": "已配置HTTPS域名",
+      "fix_hint": ""
+    },
+    {
+      "name": "入口文件",
+      "status": "ok",
+      "message": "app.js存在",
+      "fix_hint": ""
+    },
+    {
+      "name": "页面配置",
+      "status": "ok",
+      "message": "共9个页面",
+      "fix_hint": ""
+    },
+    {
+      "name": "隐私配置",
+      "status": "ok",
+      "message": "已启用隐私检查",
+      "fix_hint": ""
+    },
+    {
+      "name": "企业认证",
+      "status": "warning",
+      "message": "认证审核中",
+      "fix_hint": "等待审核结果"
+    },
+    {
+      "name": "开发者工具",
+      "status": "ok",
+      "message": "微信开发者工具已安装",
+      "fix_hint": ""
+    },
+    {
+      "name": "miniprogram-ci",
+      "status": "ok",
+      "message": "npm工具已安装",
+      "fix_hint": ""
+    },
+    {
+      "name": "上传密钥",
+      "status": "warning",
+      "message": "未配置私钥",
+      "fix_hint": "在小程序后台下载代码上传密钥"
+    }
+  ],
+  "summary": {
+    "total": 10,
+    "ok": 8,
+    "warning": 2,
+    "error": 0,
+    "can_deploy": true,
+    "can_release": false
+  }
+}
\ No newline at end of file
diff --git a/开发文档/小程序管理/scripts/reports/summary_20260125_113255.json b/开发文档/小程序管理/scripts/reports/summary_20260125_113255.json
new file mode 100644
index 00000000..88ed994a
--- /dev/null
+++ b/开发文档/小程序管理/scripts/reports/summary_20260125_113255.json
@@ -0,0 +1,88 @@
+{
+  "generated_at": "2026-01-25T11:32:55.447833",
+  "total_apps": 1,
+  "summary": {
+    "ok": 0,
+    "warning": 1,
+    "error": 0,
+    "can_release": 0
+  },
+  "apps": [
+    {
+      "app_id": "soul-party",
+      "app_name": "Soul派对",
+      "appid": "wxb8bbb2b10dec74aa",
+      "check_time": "2026-01-25T11:32:55.428736",
+      "checks": [
+        {
+          "name": "项目路径",
+          "status": "ok",
+          "message": "路径存在: /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram",
+          "fix_hint": ""
+        },
+        {
+          "name": "AppID配置",
+          "status": "ok",
+          "message": "AppID正确: wxb8bbb2b10dec74aa",
+          "fix_hint": ""
+        },
+        {
+          "name": "API域名",
+          "status": "ok",
+          "message": "已配置HTTPS域名",
+          "fix_hint": ""
+        },
+        {
+          "name": "入口文件",
+          "status": "ok",
+          "message": "app.js存在",
+          "fix_hint": ""
+        },
+        {
+          "name": "页面配置",
+          "status": "ok",
+          "message": "共9个页面",
+          "fix_hint": ""
+        },
+        {
+          "name": "隐私配置",
+          "status": "warning",
+          "message": "未启用隐私检查",
+          "fix_hint": "建议添加 __usePrivacyCheck__: true"
+        },
+        {
+          "name": "企业认证",
+          "status": "warning",
+          "message": "认证审核中",
+          "fix_hint": "等待审核结果"
+        },
+        {
+          "name": "开发者工具",
+          "status": "ok",
+          "message": "微信开发者工具已安装",
+          "fix_hint": ""
+        },
+        {
+          "name": "miniprogram-ci",
+          "status": "ok",
+          "message": "npm工具已安装",
+          "fix_hint": ""
+        },
+        {
+          "name": "上传密钥",
+          "status": "warning",
+          "message": "未配置私钥",
+          "fix_hint": "在小程序后台下载代码上传密钥"
+        }
+      ],
+      "summary": {
+        "total": 10,
+        "ok": 7,
+        "warning": 3,
+        "error": 0,
+        "can_deploy": true,
+        "can_release": false
+      }
+    }
+  ]
+}
\ No newline at end of file
diff --git a/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_1109.png b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_1109.png
new file mode 100644
index 00000000..0657cb3f
Binary files /dev/null and b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_1109.png differ
diff --git a/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_1856.png b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_1856.png
new file mode 100644
index 00000000..a4319976
Binary files /dev/null and b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_1856.png differ
diff --git a/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2022.png b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2022.png
new file mode 100644
index 00000000..449703d8
Binary files /dev/null and b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2022.png differ
diff --git a/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2300.png b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2300.png
new file mode 100644
index 00000000..460c4255
Binary files /dev/null and b/开发文档/小程序管理/scripts/reports/体验版二维码_soul-party_20260315_2300.png differ
diff --git a/开发文档/小程序管理/scripts/requirements.txt b/开发文档/小程序管理/scripts/requirements.txt
new file mode 100644
index 00000000..29b7c9d3
--- /dev/null
+++ b/开发文档/小程序管理/scripts/requirements.txt
@@ -0,0 +1,7 @@
+# 微信小程序管理工具依赖
+
+# HTTP客户端
+httpx>=0.25.0
+
+# 环境变量管理
+python-dotenv>=1.0.0
diff --git a/开发文档/服务器管理/SKILL.md b/开发文档/服务器管理/SKILL.md
new file mode 100644
index 00000000..8bce80cd
--- /dev/null
+++ b/开发文档/服务器管理/SKILL.md
@@ -0,0 +1,314 @@
+---
+name: 服务器管理
+description: 宝塔服务器统一管理与自动化部署。触发词：服务器、宝塔、部署、上线、发布、Node项目、SSL证书、HTTPS、DNS解析、域名配置、端口、PM2、Nginx、MySQL数据库、服务器状态。涵盖多服务器资产管理、Node.js项目一键部署、SSL证书管理、DNS配置、系统诊断等运维能力。
+---
+
+# 服务器管理
+
+让 AI 写完代码后，无需人工介入，自动把项目「变成一个在线网站」。
+
+---
+
+## 快速入口（复制即用）
+
+### 服务器资产
+
+| 服务器 | IP | 配置 | 用途 | 宝塔面板 |
+|--------|-----|------|------|----------|
+| **小型宝塔** | 42.194.232.22 | 2核4G 5M | 主力部署（Node项目） | https://42.194.232.22:9988/ckbpanel |
+| **存客宝** | 42.194.245.239 | 2核16G 50M | 私域银行业务 | https://42.194.245.239:9988 |
+| **kr宝塔** | 43.139.27.93 | 2核4G 5M | 辅助服务器 | https://43.139.27.93:9988 |
+
+### 凭证速查
+
+```bash
+# SSH连接（小型宝塔为例）
+ssh root@42.194.232.22
+密码: Zhiqun1984
+
+# 宝塔面板登录（小型宝塔）
+地址: https://42.194.232.22:9988/ckbpanel
+账号: ckb
+密码: zhiqun1984
+
+# 宝塔API密钥
+小型宝塔: hsAWqFSi0GOCrunhmYdkxy92tBXfqYjd
+存客宝:   TNKjqDv5N1QLOU20gcmGVgr82Z4mXzRi
+kr宝塔:   qcWubCdlfFjS2b2DMT1lzPFaDfmv1cBT
+```
+
+---
+
+## 一键操作
+
+### 1. 检查服务器状态
+
+```bash
+# 运行快速检查脚本
+python3 /Users/karuo/Documents/个人/卡若AI/01_系统管理/服务器管理/scripts/快速检查服务器.py
+```
+
+### 2. 部署 Node 项目（标准流程）
+
+```bash
+# 1. 压缩项目（排除无用目录）
+cd /项目路径
+tar --exclude='node_modules' --exclude='.next' --exclude='.git' \
+    -czf /tmp/项目名_update.tar.gz .
+
+# 2. 上传到服务器
+sshpass -p 'Zhiqun1984' scp /tmp/项目名_update.tar.gz root@42.194.232.22:/tmp/
+
+# 3. SSH部署
+ssh root@42.194.232.22
+cd /www/wwwroot/项目名
+rm -rf app components lib public styles *.json *.js *.ts *.mjs *.md .next
+tar -xzf /tmp/项目名_update.tar.gz
+pnpm install
+pnpm run build
+rm /tmp/项目名_update.tar.gz
+
+# 4. 宝塔面板重启项目
+# 【网站】→【Node项目】→ 找到项目 → 点击【重启】
+```
+
+### 3. SSL证书检查/修复
+
+```bash
+# 检查所有服务器SSL证书状态
+python3 /Users/karuo/Documents/个人/卡若AI/01_系统管理/服务器管理/scripts/ssl证书检查.py
+
+# 自动修复过期证书
+python3 /Users/karuo/Documents/个人/卡若AI/01_系统管理/服务器管理/scripts/ssl证书检查.py --fix
+```
+
+### 4. 常用诊断命令
+
+```bash
+# 检查端口占用
+ssh root@42.194.232.22 "ss -tlnp | grep :3006"
+
+# 检查PM2进程
+ssh root@42.194.232.22 "/www/server/nodejs/v22.14.0/bin/pm2 list"
+
+# 测试HTTP响应
+ssh root@42.194.232.22 "curl -I http://localhost:3006"
+
+# 检查Nginx配置
+ssh root@42.194.232.22 "nginx -t"
+
+# 重载Nginx
+ssh root@42.194.232.22 "nginx -s reload"
+
+# DNS解析检查
+dig soul.quwanzhi.com +short @8.8.8.8
+```
+
+---
+
+## 端口配置表（小型宝塔 42.194.232.22）
+
+| 端口 | 项目名 | 类型 | 域名 | 状态 |
+|------|--------|------|------|------|
+| 3000 | cunkebao | Next.js | mckb.quwanzhi.com | ✅ |
+| 3001 | ai_hair | NestJS | ai-hair.quwanzhi.com | ✅ |
+| 3002 | kr_wb | Next.js | kr_wb.quwanzhi.com | ✅ |
+| 3003 | hx | Vue | krjzk.quwanzhi.com | ⚠️ |
+| 3004 | dlmdashboard | Next.js | dlm.quwanzhi.com | ✅ |
+| 3005 | document | Next.js | docc.quwanzhi.com | ✅ |
+| 3006 | soul | Next.js | soul.quwanzhi.com | ✅ |
+| 3015 | 神射手 | Next.js | kr-users.quwanzhi.com | ⚠️ |
+| 3018 | zhaoping | Next.js | zp.quwanzhi.com | ✅ |
+| 3021 | is_phone | Next.js | is-phone.quwanzhi.com | ✅ |
+| 3031 | word | Next.js | word.quwanzhi.com | ✅ |
+| 3036 | ymao | Next.js | ymao.quwanzhi.com | ✅ |
+| 3043 | tongzhi | Next.js | touzhi.lkdie.com | ✅ |
+| 3045 | 玩值大屏 | Next.js | wz-screen.quwanzhi.com | ✅ |
+| 3050 | zhiji | Next.js | zhiji.quwanzhi.com | ✅ |
+| 3051 | zhiji1 | Next.js | zhiji1.quwanzhi.com | ✅ |
+| 3055 | wzdj | Next.js | wzdj.quwanzhi.com | ✅ |
+| 3305 | AITOUFA | Next.js | ai-tf.quwanzhi.com | ✅ |
+| 9528 | mbti | Vue | mbtiadmin.quwanzhi.com | ✅ |
+
+### 端口分配原则
+
+- **3000-3099**: Next.js / React 项目
+- **3100-3199**: Vue 项目
+- **3200-3299**: NestJS / Express 后端
+- **3300-3399**: AI相关项目
+- **9000-9999**: 管理面板 / 特殊用途
+
+---
+
+## 核心工作流程
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Node项目一键部署流程                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   START                                                                     │
+│     │                                                                       │
+│     ▼                                                                       │
+│  ┌──────────────────┐                                                      │
+│  │ 1. 压缩本地代码  │  排除 node_modules, .next, .git                      │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 2. 上传到服务器  │  scp 到 /tmp/                                         │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 3. 清理旧文件    │  保留 .env 等配置文件                                 │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 4. 解压新代码    │  tar -xzf                                             │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 5. 安装依赖      │  pnpm install                                         │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 6. 构建项目      │  pnpm run build                                       │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 7. 宝塔面板重启  │  Node项目 → 重启                                       │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌──────────────────┐                                                      │
+│  │ 8. 验证访问      │  curl https://域名                                     │
+│  └────────┬─────────┘                                                      │
+│           │                                                                 │
+│           ▼                                                                 │
+│        SUCCESS                                                              │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 操作优先级矩阵
+
+| 操作类型 | 优先方式 | 备选方式 | 说明 |
+|---------|---------|---------|------|
+| 查询信息 | ✅ 宝塔API | SSH | API稳定 |
+| 文件操作 | ✅ 宝塔API | SSH | API支持 |
+| 配置Nginx | ✅ 宝塔API | SSH | API可读写 |
+| 重载服务 | ⚠️ SSH | - | API无接口 |
+| 上传代码 | ⚠️ SSH/scp | - | 大文件 |
+| 添加项目 | ❌ 宝塔界面 | - | API不稳定 |
+
+---
+
+## 常见问题速查
+
+### Q1: 外网无法访问（ERR_EMPTY_RESPONSE）
+
+**原因**: 腾讯云安全组只开放443端口
+
+**解决**: 
+1. 必须配置SSL证书
+2. Nginx配置添加443监听
+
+### Q2: Node项目启动失败（Could not find production build）
+
+**原因**: 使用 `npm run start` 但未执行 `npm run build`
+
+**解决**: 先 `pnpm run build` 再重启
+
+### Q3: 端口冲突（EADDRINUSE）
+
+**解决**:
+```bash
+# 检查端口占用
+ss -tlnp | grep :端口号
+
+# 修改package.json中的端口
+"start": "next start -p 新端口"
+```
+
+### Q4: DNS被代理劫持
+
+**现象**: 本地DNS解析到198.18.x.x
+
+**解决**: 
+- 关闭代理软件
+- 或用手机4G网络测试
+
+### Q5: 宝塔与PM2冲突
+
+**原因**: 同时使用root用户PM2和宝塔PM2
+
+**解决**: 
+- 停止所有独立PM2: `pm2 kill`
+- 只使用宝塔界面管理
+
+---
+
+## 安全约束
+
+### 绝对禁止
+
+- ❌ 输出完整密码/密钥到聊天
+- ❌ 执行危险命令（rm -rf /, reboot等）
+- ❌ 跳过验证步骤
+- ❌ 使用独立PM2（避免与宝塔冲突）
+
+### 必须遵守
+
+- ✅ 操作前检查服务器状态
+- ✅ 操作后验证结果
+- ✅ 生成操作报告
+
+---
+
+## 相关脚本
+
+| 脚本 | 功能 | 位置 |
+|------|------|------|
+| `快速检查服务器.py` | 一键检查所有服务器状态 | `./scripts/` |
+| `一键部署.py` | 根据配置文件部署项目 | `./scripts/` |
+| `ssl证书检查.py` | 检查/修复SSL证书 | `./scripts/` |
+
+---
+
+## 相关文档
+
+| 文档 | 内容 | 位置 |
+|------|------|------|
+| `宝塔API接口文档.md` | 宝塔API完整接口说明 | `./references/` |
+| `端口配置表.md` | 完整端口分配表 | `./references/` |
+| `常见问题手册.md` | 问题解决方案大全 | `./references/` |
+| `部署配置模板.md` | JSON配置文件模板 | `./references/` |
+| `系统架构说明.md` | 完整架构图和流程图 | `./references/` |
+
+---
+
+## 历史对话整理
+
+### kr_wb白板项目部署（2026-01-23）
+
+- 项目类型: Next.js
+- 部署位置: /www/wwwroot/kr_wb
+- 域名: kr_wb.quwanzhi.com
+- 端口: 3002
+- 遇到问题: AI功能401错误（API密钥未配置）
+- 解决方案: 修改 lib/ai-client.ts，改用 SiliconFlow 作为默认服务
+
+### soul项目部署（2026-01-23）
+
+- 项目类型: Next.js
+- 部署位置: /www/wwwroot/soul
+- 域名: soul.quwanzhi.com
+- 端口: 3006
+- 部署流程: 压缩→上传→解压→安装依赖→构建→PM2启动→配置Nginx→配置SSL
diff --git a/开发文档/服务器管理/Windows-macOS虚拟机安装指南.md b/开发文档/服务器管理/Windows-macOS虚拟机安装指南.md
new file mode 100644
index 00000000..68ad3caa
--- /dev/null
+++ b/开发文档/服务器管理/Windows-macOS虚拟机安装指南.md
@@ -0,0 +1,157 @@
+# Windows 上运行 macOS 虚拟机 - GitHub 方案汇总
+
+> **重要说明**：**macOS 无法在 Docker 中运行**。Docker 只能运行 Linux 容器。本方案使用 **WSL2 + QEMU/KVM 虚拟机**，在 Windows 上虚拟出一台「Mac」。
+>
+> **用途**：仅用于演示、测试、学习。请遵守 Apple 软件许可协议。
+>
+> **环境**：Windows 10/11 + WSL2 + Ubuntu，通过 QEMU/KVM 运行 macOS 虚拟机。
+
+---
+
+## 一、GitHub 方案概览
+
+| 项目 | Stars | 适用场景 | Windows 支持 |
+|------|-------|----------|-------------|
+| [OneClick-macOS-Simple-KVM](https://github.com/notAperson535/OneClick-macOS-Simple-KVM) | 877 | **推荐** 一键安装，适合 Windows | ✅ 支持 |
+| [OSX-KVM](https://github.com/kholia/OSX-KVM) | 23k | 成熟方案，支持 Monterey/Ventura/Sonoma | ⚠️ 需 WSL2 |
+| [dortania/OpenCore-Install-Guide](https://github.com/dortania/OpenCore-Install-Guide) | 4.1k | 官方 OpenCore 安装指南 | 通用 |
+| [Elymac/Hackintosh](https://github.com/Elymac/Hackintosh) | 3 | Windows 下制作 macOS 安装盘 | 物理机安装 |
+
+**结论**：在 Windows 上做演示/测试，优先用 **OneClick-macOS-Simple-KVM**（WSL2 + QEMU/KVM）。
+
+---
+
+## 二、前置要求
+
+- Windows 10 或更高
+- 8GB+ 内存（建议 16GB）
+- CPU 支持虚拟化（BIOS 中开启 VT-x/AMD-V）
+- **AMD Ryzen/EPYC**：需 Windows 11 才支持嵌套虚拟化
+
+---
+
+## 三、全自动安装步骤（PowerShell + WSL2）
+
+> 也可使用项目提供的脚本：`开发文档/服务器管理/scripts/macOS-VM-安装-步骤1-WSL.ps1` 和 `macOS-VM-安装-步骤2-克隆与检查.ps1`（步骤 1 需管理员权限）。
+
+### 步骤 1：安装 WSL2（管理员 PowerShell）
+
+```powershell
+wsl --install
+```
+
+安装完成后**重启电脑**。若未自动安装 Ubuntu，再执行：
+
+```powershell
+wsl --install Ubuntu
+```
+
+### 步骤 2：进入 WSL 并克隆项目
+
+重启后打开 **Ubuntu** 终端，执行（将 `WINDOWS_USER_NAME` 换成你的 Windows 用户名）：
+
+```bash
+cd /mnt/c/users/WINDOWS_USER_NAME/Documents
+sudo apt update && sudo apt install -y git cpu-checker
+git clone https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git
+cd OneClick-macOS-Simple-KVM
+```
+
+### 步骤 3：检查虚拟化
+
+```bash
+kvm-ok
+```
+
+应输出 `KVM acceleration can be used`。
+
+- **Intel**：`cat /sys/module/kvm_intel/parameters/nested` 应为 `Y`
+- **AMD**：`cat /sys/module/kvm_amd/parameters/nested` 应为 `Y` 或 `1`
+
+若为 `N`，见文末「故障排查」。
+
+### 步骤 4：首次设置并启动
+
+```bash
+./setup.sh
+```
+
+出现 QEMU 窗口后按 `Ctrl+C` 停止，再执行：
+
+```bash
+sudo HEADLESS=1 ./basic.sh
+```
+
+### 步骤 5：用 VNC 连接
+
+1. 下载 [VNC Viewer](https://www.realvnc.com/en/connect/download/viewer/)
+2. 连接地址：`localhost:5900`
+3. 在虚拟机内完成 macOS 安装向导
+
+---
+
+## 四、日常启动（非首次）
+
+每次启动虚拟机只需：
+
+```bash
+cd /mnt/c/users/WINDOWS_USER_NAME/Documents/OneClick-macOS-Simple-KVM
+sudo HEADLESS=1 ./basic.sh
+```
+
+然后用 VNC 连接 `localhost:5900`。
+
+**注意**：不要关闭运行 `basic.sh` 的终端，否则虚拟机会关闭。
+
+---
+
+## 五、故障排查
+
+### 1. nested 返回 N，但 kvm-ok 正常
+
+在 Windows 用户目录创建/编辑 `.wslconfig`（路径：`C:\Users\WINDOWS_USER_NAME\.wslconfig`）：
+
+```ini
+[wsl2]
+nestedVirtualization=true
+kernel=C:\\Users\\WINDOWS_USER_NAME\\bzImage
+debugConsole=true
+pageReporting=true
+kernelCommandLine=intel_iommu=on iommu=pt kvm.ignore_msrs=1 kvm-intel.nested=1 kvm-intel.ept=1 kvm-intel.emulate_invalid_guest_state=0 kvm-intel.enable_shadow_vmcs=1 kvm-intel.enable_apicv=1
+```
+
+保存后执行 `wsl --shutdown`，再重新打开 WSL。
+
+### 2. AMD 处理器提示 "Your CPU does not support KVM extensions"
+
+Windows 10 对 AMD Ryzen/EPYC 的嵌套虚拟化支持有限，需升级到 **Windows 11**。
+
+### 3. 获取 Windows 用户名
+
+PowerShell 中执行：
+
+```powershell
+$env:USERNAME
+```
+
+---
+
+## 六、相关链接
+
+- [OneClick 官方文档 - Windows 安装](https://oneclick-macos-simple-kvm.notaperson535.is-a.dev/docs/windows-install)
+- [Dortania OpenCore 安装指南](https://dortania.github.io/OpenCore-Install-Guide/)
+- [OSX-KVM 项目](https://github.com/kholia/OSX-KVM)
+
+---
+
+---
+
+## 七、一键脚本
+
+- **macOS-VM-安装-简化版.bat**：双击运行，自动完成克隆、安装依赖、执行 setup
+- 若 setup.sh 提示选择 macOS 版本，输入 `7` 选 Sonoma 或 `6` 选 Ventura
+- 出现 QEMU 窗口后按 Ctrl+C，再执行 `sudo HEADLESS=1 ./basic.sh`，用 VNC 连接 localhost:5900
+
+---
+
+*文档生成时间：2026-03-09*
diff --git a/开发文档/服务器管理/references/运维参考.md b/开发文档/服务器管理/references/运维参考.md
new file mode 100644
index 00000000..fc781c96
--- /dev/null
+++ b/开发文档/服务器管理/references/运维参考.md
@@ -0,0 +1,3 @@
+# 运维参考（合并自 宝塔api、常见问题、端口配置、系统架构、部署配置）
+
+宝塔 API、常见问题、端口配置、系统架构说明、部署配置模板。详见原各文档。
diff --git a/开发文档/服务器管理/scripts/lobster_macos_vm.py b/开发文档/服务器管理/scripts/lobster_macos_vm.py
new file mode 100644
index 00000000..3c0adbda
--- /dev/null
+++ b/开发文档/服务器管理/scripts/lobster_macos_vm.py
@@ -0,0 +1,163 @@
+"""
+lobster_macos_vm.py
+
+“龙虾” 一键脚本：在 Windows 10/11 上，通过 WSL2 + Ubuntu-24.04 + QEMU/KVM
+和 OneClick-macOS-Simple-KVM 自动准备 macOS 虚拟机（Ventura）。
+
+使用方式（在 Windows PowerShell 中）：
+
+    python C:\\Users\\<USERNAME>\\Mycontent\\macos-vm\\lobster_macos_vm.py
+
+注意：
+- 需要管理员权限安装 WSL2（如果此前未安装）。
+- 脚本不会替你点 macOS 图形安装向导，只会把虚拟机和 VNC 端口拉起来。
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run(cmd, check=True):
+    """在 Windows Shell 中运行命令，并在失败时抛异常。"""
+    print(f"[lobster] RUN: {cmd}")
+    result = subprocess.run(cmd, shell=True)
+    if check and result.returncode != 0:
+        raise RuntimeError(f"命令执行失败（exit {result.returncode}）：{cmd}")
+    return result.returncode
+
+
+def ensure_wsl_installed():
+    """检测 WSL 是否可用，不负责安装（安装通常需要手工 + 重启）。"""
+    try:
+        subprocess.run("wsl -l -v", shell=True, check=True,
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except subprocess.CalledProcessError:
+        print(
+            "[lobster] 检测到 WSL 尚未可用，请以管理员权限运行：wsl --install，然后重启电脑后再运行本脚本。"
+        )
+        sys.exit(1)
+
+
+def ensure_ubuntu_distro():
+    """确保存在 Ubuntu-24.04 发行版（不强制版本号，只要有 Ubuntu 即可继续）。"""
+    proc = subprocess.run(
+        "wsl -l -v", shell=True, capture_output=True, text=True, check=False
+    )
+    if proc.returncode != 0:
+        print(proc.stdout)
+        print(proc.stderr)
+        raise RuntimeError("wsl -l -v 执行失败，无法检测发行版。")
+
+    lines = proc.stdout.splitlines()
+    ubuntu_exists = any("Ubuntu" in line for line in lines)
+    if not ubuntu_exists:
+        print(
+            "[lobster] 未发现 Ubuntu 发行版，请以管理员权限运行：\n"
+            "    wsl --install -d Ubuntu-24.04 --web-download\n"
+            "安装完成、重启并完成 Ubuntu 初始化后，再运行本脚本。"
+        )
+        sys.exit(1)
+
+
+def wsl_path(win_path: Path) -> str:
+    """将 Windows 路径转换为 WSL 路径（简单 C: -> /mnt/c 映射）。"""
+    drive = win_path.drive.replace(":", "").lower()
+    rel = win_path.as_posix().split(":/")[-1] if ":/" in win_path.as_posix() else win_path.as_posix().split(":")[-1]
+    # 去掉开头的 /
+    if rel.startswith("/"):
+        rel = rel[1:]
+    return f"/mnt/{drive}/{rel.replace(' ', '\\ ')}"
+
+
+def run_in_wsl(bash_script: str):
+    """把一段 bash 脚本送进 WSL 执行。"""
+    cmd = f"wsl -e bash -lc \"set -e; {bash_script}\""
+    return run(cmd)
+
+
+def main():
+    username = os.environ.get("USERNAME") or os.environ.get("USER")
+    if not username:
+        raise RuntimeError("无法获取当前 Windows 用户名（USER/USERNAME）。")
+
+    # 1. 检查 WSL / Ubuntu
+    print("[lobster] 第 1 步：检查 WSL / Ubuntu 环境...")
+    ensure_wsl_installed()
+    ensure_ubuntu_distro()
+
+    # 2. 创建固定目录 C:\Users\<USERNAME>\Mycontent\macos-vm
+    base_dir = Path(f"C:/Users/{username}/Mycontent/macos-vm")
+    base_dir.mkdir(parents=True, exist_ok=True)
+    print(f"[lobster] 使用目录：{base_dir}")
+
+    wsl_base = wsl_path(base_dir)
+
+    # 3. 在 WSL 中下载 OneClick 源码 zip 并解压
+    print("[lobster] 第 2 步：下载 OneClick 源码 zip 并解压...")
+    bash_download = f"""
+cd {wsl_base}
+sudo apt-get update -qq
+sudo apt-get install -y curl unzip
+rm -rf OneClick-macOS-Simple-KVM OneClick.zip
+curl -L --retry 8 --retry-delay 2 --connect-timeout 20 --max-time 900 \\
+  -o OneClick.zip \\
+  https://codeload.github.com/notAperson535/OneClick-macOS-Simple-KVM/zip/refs/heads/master
+unzip -q OneClick.zip
+mv OneClick-macOS-Simple-KVM-master OneClick-macOS-Simple-KVM
+"""
+    run_in_wsl(bash_download)
+
+    # 4. 安装 QEMU / Python / cpu-checker，并检查 KVM
+    print("[lobster] 第 3 步：安装 QEMU / Python / cpu-checker，并检查 KVM...")
+    bash_deps = f"""
+cd {wsl_base}/OneClick-macOS-Simple-KVM
+sudo apt-get update -qq
+sudo apt-get install -y qemu-system qemu-utils python3 python3-pip cpu-checker
+kvm-ok || true
+"""
+    run_in_wsl(bash_deps)
+
+    # 5. 下载 macOS Ventura 恢复镜像并生成 BaseSystem.img / macOS.qcow2
+    print("[lobster] 第 4 步：下载 macOS Ventura 恢复镜像并生成 BaseSystem.img...")
+    bash_fetch = f"""
+cd {wsl_base}/OneClick-macOS-Simple-KVM
+chmod +x *.sh *.py || true
+[ -f macOS.qcow2 ] || qemu-img create -f qcow2 macOS.qcow2 64G
+python3 fetch-macOS-v2.py -s ventura
+[ -f RecoveryImage.dmg ] && mv RecoveryImage.dmg BaseSystem.dmg || true
+qemu-img convert BaseSystem.dmg -O raw BaseSystem.img
+ls -lah BaseSystem.* macOS.qcow2
+"""
+    run_in_wsl(bash_fetch)
+
+    # 6. 启动虚拟机（HEADLESS + VNC 5900）
+    print("[lobster] 第 5 步：启动 macOS 虚拟机（HEADLESS + VNC: localhost:5900）...")
+    bash_start = f"""
+cd {wsl_base}/OneClick-macOS-Simple-KVM
+sudo HEADLESS=1 ./basic.sh
+"""
+    # 不阻塞当前 PowerShell：用 wslrelay/wsl 后台端口监听，由用户自己关
+    subprocess.Popen(
+        f"wsl -e bash -lc \"{bash_start}\"",
+        shell=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+    print("\n[lobster] 已尝试启动 macOS 虚拟机。")
+    print("请确保已经安装 VNC Viewer（如 RealVNC）。")
+    print("在 VNC Viewer 中连接：localhost:5900")
+    print("随后在图形界面中完成磁盘抹盘和 macOS 安装向导即可。")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\n[lobster] 收到中断，已停止。")
+    except Exception as e:
+        print(f"\n[lobster] 发生错误：{e}")
+        sys.exit(1)
+
diff --git a/开发文档/服务器管理/scripts/macOS-VM-setup-auto.sh b/开发文档/服务器管理/scripts/macOS-VM-setup-auto.sh
new file mode 100644
index 00000000..7909e746
--- /dev/null
+++ b/开发文档/服务器管理/scripts/macOS-VM-setup-auto.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+# 全自动 macOS 虚拟机安装脚本 - 无交互
+# 在 WSL Ubuntu 中运行
+
+set -e
+cd "$(dirname "$0")"
+
+echo "=== 安装依赖 ==="
+export DEBIAN_FRONTEND=noninteractive
+sudo apt-get update -qq
+sudo apt-get install -y qemu-system qemu-utils python3 python3-pip
+
+echo "=== 创建虚拟磁盘 ==="
+[ -f macOS.qcow2 ] || qemu-img create -f qcow2 macOS.qcow2 64G
+
+echo "=== 下载 macOS Ventura 恢复镜像（约 6GB，请耐心等待）==="
+python3 fetch-macOS-v2.py -s ventura 2>/dev/null || python3 fetch-macOS-v2.py -s catalina
+
+echo "=== 转换镜像 ==="
+[ -f RecoveryImage.dmg ] && mv RecoveryImage.dmg BaseSystem.dmg
+qemu-img convert BaseSystem.dmg -O raw BaseSystem.img
+
+echo "=== 完成。启动虚拟机请执行: sudo HEADLESS=1 ./basic.sh ==="
+echo "=== 然后用 VNC Viewer 连接 localhost:5900 ==="
diff --git a/开发文档/服务器管理/scripts/macOS-VM-一键安装.ps1 b/开发文档/服务器管理/scripts/macOS-VM-一键安装.ps1
new file mode 100644
index 00000000..75d516b0
--- /dev/null
+++ b/开发文档/服务器管理/scripts/macOS-VM-一键安装.ps1
@@ -0,0 +1,51 @@
+# macOS 虚拟机 - 一键安装脚本（全自动，无交互）
+# 说明：macOS 无法在 Docker 中运行，本脚本使用 WSL2 + QEMU/KVM 虚拟机方案
+# 运行方式：PowerShell 中执行 .\macOS-VM-一键安装.ps1
+
+$ErrorActionPreference = "Continue"
+$docPath = "C:\Users\$env:USERNAME\Documents"
+$repoPath = "$docPath\OneClick-macOS-Simple-KVM"
+$wslPath = "/mnt/c/Users/$env:USERNAME/Documents/OneClick-macOS-Simple-KVM" -replace '\\','/'
+
+Write-Host "`n=== macOS 虚拟机一键安装（全自动）===" -ForegroundColor Cyan
+Write-Host "目标: $repoPath`n" -ForegroundColor Gray
+
+# 1. 克隆项目
+if (-not (Test-Path "$repoPath\.git")) {
+    Write-Host "[1/5] 克隆 OneClick-macOS-Simple-KVM..." -ForegroundColor Yellow
+    wsl -d Ubuntu-24.04 -e bash -c "cd /mnt/c/Users/$env:USERNAME/Documents; git clone https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git 2>&1"
+} else {
+    Write-Host "[1/5] 项目已存在" -ForegroundColor Green
+}
+
+# 2. 安装依赖
+Write-Host "`n[2/5] 安装 QEMU、Python 等依赖..." -ForegroundColor Yellow
+wsl -d Ubuntu-24.04 -e bash -c "cd $wslPath; export DEBIAN_FRONTEND=noninteractive; sudo apt-get update -qq; sudo apt-get install -y qemu-system qemu-utils python3 python3-pip 2>&1 | tail -5"
+
+# 3. 检查 KVM
+Write-Host "`n[3/5] 检查虚拟化..." -ForegroundColor Yellow
+wsl -d Ubuntu-24.04 -e bash -c "kvm-ok 2>&1"
+
+# 4. 生成并执行 bash 脚本
+$shContent = @'
+cd PLACEHOLDER_WSLPATH
+chmod +x *.sh *.py 2>/dev/null
+test -f macOS.qcow2 || qemu-img create -f qcow2 macOS.qcow2 64G
+python3 fetch-macOS-v2.py -s ventura 2>/dev/null || python3 fetch-macOS-v2.py -s catalina
+test -f RecoveryImage.dmg && mv RecoveryImage.dmg BaseSystem.dmg
+qemu-img convert BaseSystem.dmg -O raw BaseSystem.img
+echo done
+'@ -replace 'PLACEHOLDER_WSLPATH', $wslPath
+$shFile = Join-Path $env:TEMP "macos-vm-setup-$PID.sh"
+$shContent | Out-File -FilePath $shFile -Encoding ASCII
+$wslShPath = "/mnt/" + $shFile.Substring(0,1).ToLower() + ($shFile.Substring(2) -replace '\\','/')
+
+Write-Host "`n[4/5] 下载 macOS Ventura 恢复镜像（约 6GB，需 10-30 分钟）..." -ForegroundColor Yellow
+wsl -d Ubuntu-24.04 -e bash $wslShPath
+Remove-Item $shFile -ErrorAction SilentlyContinue
+
+# 5. 启动虚拟机
+Write-Host "`n[5/5] 启动 macOS 虚拟机..." -ForegroundColor Yellow
+Write-Host "VNC: localhost:5900" -ForegroundColor Cyan
+$vmCmd = 'cd ' + $wslPath + '; sudo HEADLESS=1 ./basic.sh'
+wsl -d Ubuntu-24.04 -e bash -c $vmCmd
diff --git a/开发文档/服务器管理/scripts/macOS-VM-安装-步骤1-WSL.ps1 b/开发文档/服务器管理/scripts/macOS-VM-安装-步骤1-WSL.ps1
new file mode 100644
index 00000000..9dfb33d4
--- /dev/null
+++ b/开发文档/服务器管理/scripts/macOS-VM-安装-步骤1-WSL.ps1
@@ -0,0 +1,13 @@
+# macOS 虚拟机安装 - 步骤 1：安装 WSL2
+# 需以管理员身份运行 PowerShell
+# 执行后需重启电脑，再运行 步骤2
+
+$ErrorActionPreference = "Stop"
+
+Write-Host "=== macOS 虚拟机安装 - 步骤 1/2 ===" -ForegroundColor Cyan
+Write-Host "正在安装 WSL2..." -ForegroundColor Yellow
+
+wsl --install
+
+Write-Host "`nWSL 安装完成。请重启电脑，然后运行 步骤2 脚本。" -ForegroundColor Green
+Write-Host "若未自动安装 Ubuntu，重启后可执行: wsl --install Ubuntu" -ForegroundColor Gray
diff --git a/开发文档/服务器管理/scripts/macOS-VM-安装-步骤2-克隆与检查.ps1 b/开发文档/服务器管理/scripts/macOS-VM-安装-步骤2-克隆与检查.ps1
new file mode 100644
index 00000000..94863d3e
--- /dev/null
+++ b/开发文档/服务器管理/scripts/macOS-VM-安装-步骤2-克隆与检查.ps1
@@ -0,0 +1,44 @@
+# macOS 虚拟机安装 - 步骤 2：克隆项目并检查环境
+# 在重启后运行，会启动 WSL 并执行克隆与检查
+# 需先完成步骤 1 并重启
+
+$ErrorActionPreference = "Stop"
+$winUser = $env:USERNAME
+$targetDir = "C:\Users\$winUser\Documents\OneClick-macOS-Simple-KVM"
+
+Write-Host "=== macOS 虚拟机安装 - 步骤 2/2 ===" -ForegroundColor Cyan
+Write-Host "Windows 用户: $winUser" -ForegroundColor Gray
+Write-Host "目标目录: $targetDir`n" -ForegroundColor Gray
+
+# 生成临时脚本并执行
+$shPath = "$env:TEMP\macos-vm-setup.sh"
+$shContent = @"
+cd /mnt/c/users/$winUser/Documents
+sudo apt update -qq && sudo apt install -y git cpu-checker 2>/dev/null
+if [ -d OneClick-macOS-Simple-KVM ]; then
+  echo '项目已存在，进入目录...'
+  cd OneClick-macOS-Simple-KVM
+else
+  git clone https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git
+  cd OneClick-macOS-Simple-KVM
+fi
+echo ''
+echo '=== 虚拟化检查 ==='
+kvm-ok 2>/dev/null || echo 'kvm-ok 未通过，请检查 BIOS 虚拟化设置'
+echo ''
+echo '=== 下一步 ==='
+echo '在 WSL Ubuntu 终端中执行:'
+echo '  cd /mnt/c/users/$winUser/Documents/OneClick-macOS-Simple-KVM'
+echo '  ./setup.sh'
+echo ''
+echo '出现 QEMU 窗口后按 Ctrl+C，再执行:'
+echo '  sudo HEADLESS=1 ./basic.sh'
+echo ''
+echo '然后下载 VNC Viewer，连接 localhost:5900'
+"@
+$shContent | Out-File -FilePath $shPath -Encoding ASCII
+$wslPath = '/mnt/' + $shPath.Substring(0,1).ToLower() + $shPath.Substring(2) -replace '\\', '/'
+wsl bash $wslPath
+Remove-Item $shPath -ErrorAction SilentlyContinue
+
+Write-Host "`n完成。请按上述提示在 WSL 中继续操作。" -ForegroundColor Green
diff --git a/开发文档/服务器管理/scripts/macOS-VM-安装-简化版.bat b/开发文档/服务器管理/scripts/macOS-VM-安装-简化版.bat
new file mode 100644
index 00000000..3c149f68
--- /dev/null
+++ b/开发文档/服务器管理/scripts/macOS-VM-安装-简化版.bat
@@ -0,0 +1,27 @@
+@echo off
+chcp 65001 >nul
+echo === macOS 虚拟机安装（WSL2+QEMU，非 Docker）===
+echo.
+echo [1] 克隆项目...
+wsl -d Ubuntu-24.04 -e bash -c "cd /mnt/c/Users/29195/Documents && (test -d OneClick-macOS-Simple-KVM && echo already exists || git clone https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git) 2>&1"
+if not exist "C:\Users\29195\Documents\OneClick-macOS-Simple-KVM\.git" (
+    echo 克隆失败，请检查网络
+    pause
+    exit /b 1
+)
+
+echo.
+echo [2] 安装依赖...
+wsl -d Ubuntu-24.04 -e bash -c "cd /mnt/c/Users/29195/Documents/OneClick-macOS-Simple-KVM && sudo apt-get update -qq && sudo apt-get install -y qemu-system qemu-utils python3 python3-pip"
+
+echo.
+echo [3] 检查 KVM...
+wsl -d Ubuntu-24.04 -e bash -c "kvm-ok"
+
+echo.
+echo [4] 下载 macOS 并配置（约 6GB，需 10-30 分钟）...
+wsl -d Ubuntu-24.04 -e bash -c "cd /mnt/c/Users/29195/Documents/OneClick-macOS-Simple-KVM && chmod +x *.sh *.py && ./setup.sh"
+
+echo.
+echo 完成后请用 VNC Viewer 连接 localhost:5900
+pause
diff --git a/开发文档/服务器管理/scripts/ssl证书检查.py b/开发文档/服务器管理/scripts/ssl证书检查.py
new file mode 100644
index 00000000..4ac56952
--- /dev/null
+++ b/开发文档/服务器管理/scripts/ssl证书检查.py
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+SSL证书检查脚本
+===============
+用途：检查所有服务器的SSL证书状态
+
+使用方法：
+python3 ssl证书检查.py
+python3 ssl证书检查.py --fix  # 自动修复过期证书
+"""
+
+import sys
+import time
+import hashlib
+import requests
+import urllib3
+from datetime import datetime
+
+# 禁用SSL警告
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+# 服务器配置
+服务器列表 = {
+    "小型宝塔": {
+        "面板地址": "https://42.194.232.22:9988",
+        "密钥": "hsAWqFSi0GOCrunhmYdkxy92tBXfqYjd"
+    },
+    "存客宝": {
+        "面板地址": "https://42.194.245.239:9988",
+        "密钥": "TNKjqDv5N1QLOU20gcmGVgr82Z4mXzRi"
+    },
+    "kr宝塔": {
+        "面板地址": "https://43.139.27.93:9988",
+        "密钥": "qcWubCdlfFjS2b2DMT1lzPFaDfmv1cBT"
+    }
+}
+
+def 生成签名(api_key: str) -> tuple:
+    """生成宝塔API签名"""
+    now_time = int(time.time())
+    sign_str = str(now_time) + hashlib.md5(api_key.encode('utf-8')).hexdigest()
+    request_token = hashlib.md5(sign_str.encode('utf-8')).hexdigest()
+    return now_time, request_token
+
+def 获取证书列表(面板地址: str, 密钥: str) -> dict:
+    """获取SSL证书列表"""
+    now_time, request_token = 生成签名(密钥)
+    
+    url = f"{面板地址}/ssl?action=GetCertList"
+    data = {
+        "request_time": now_time,
+        "request_token": request_token
+    }
+    
+    try:
+        response = requests.post(url, data=data, timeout=10, verify=False)
+        return response.json()
+    except Exception as e:
+        return {"error": str(e)}
+
+def 获取网站列表(面板地址: str, 密钥: str) -> dict:
+    """获取网站列表"""
+    now_time, request_token = 生成签名(密钥)
+    
+    url = f"{面板地址}/data?action=getData&table=sites"
+    data = {
+        "request_time": now_time,
+        "request_token": request_token,
+        "limit": 100,
+        "p": 1
+    }
+    
+    try:
+        response = requests.post(url, data=data, timeout=10, verify=False)
+        return response.json()
+    except Exception as e:
+        return {"error": str(e)}
+
+def 检查服务器证书(名称: str, 配置: dict) -> dict:
+    """检查单台服务器的证书状态"""
+    print(f"\n检查服务器: {名称}")
+    print("-" * 40)
+    
+    try:
+        # 获取网站列表
+        网站数据 = 获取网站列表(配置["面板地址"], 配置["密钥"])
+        
+        if "error" in 网站数据:
+            print(f"   ❌ API错误: {网站数据['error']}")
+            return {"error": 网站数据['error']}
+        
+        网站列表 = 网站数据.get("data", [])
+        
+        if not 网站列表:
+            print("   ⚠️  没有找到网站")
+            return {"网站数": 0}
+        
+        print(f"   📊 共 {len(网站列表)} 个网站")
+        
+        # 统计
+        已配置SSL = 0
+        未配置SSL = 0
+        
+        for 网站 in 网站列表:
+            网站名 = 网站.get("name", "未知")
+            ssl状态 = 网站.get("ssl", 0)
+            
+            if ssl状态:
+                已配置SSL += 1
+                状态标识 = "🔒"
+            else:
+                未配置SSL += 1
+                状态标识 = "🔓"
+            
+            print(f"      {状态标识} {网站名}")
+        
+        print(f"\n   统计: 已配置SSL {已配置SSL} 个, 未配置 {未配置SSL} 个")
+        
+        return {
+            "网站数": len(网站列表),
+            "已配置SSL": 已配置SSL,
+            "未配置SSL": 未配置SSL
+        }
+        
+    except Exception as e:
+        print(f"   ❌ 检查失败: {e}")
+        return {"error": str(e)}
+
+def main():
+    自动修复 = "--fix" in sys.argv
+    
+    print("=" * 60)
+    print("               SSL证书状态检查报告")
+    print(f"               {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("=" * 60)
+    
+    总统计 = {
+        "服务器数": 0,
+        "网站总数": 0,
+        "已配置SSL": 0,
+        "未配置SSL": 0
+    }
+    
+    for 服务器名称, 配置 in 服务器列表.items():
+        结果 = 检查服务器证书(服务器名称, 配置)
+        
+        if "error" not in 结果:
+            总统计["服务器数"] += 1
+            总统计["网站总数"] += 结果.get("网站数", 0)
+            总统计["已配置SSL"] += 结果.get("已配置SSL", 0)
+            总统计["未配置SSL"] += 结果.get("未配置SSL", 0)
+    
+    print("\n" + "=" * 60)
+    print("                     汇总统计")
+    print("=" * 60)
+    print(f"   服务器数量: {总统计['服务器数']}")
+    print(f"   网站总数:   {总统计['网站总数']}")
+    print(f"   已配置SSL:  {总统计['已配置SSL']} 🔒")
+    print(f"   未配置SSL:  {总统计['未配置SSL']} 🔓")
+    print("=" * 60)
+    
+    if 自动修复 and 总统计['未配置SSL'] > 0:
+        print("\n⚠️  --fix 模式需要手动在宝塔面板配置SSL证书")
+        print("   建议使用通配符证书 *.quwanzhi.com")
+
+if __name__ == "__main__":
+    main()
diff --git a/开发文档/服务器管理/scripts/一键部署.py b/开发文档/服务器管理/scripts/一键部署.py
new file mode 100644
index 00000000..a5660e18
--- /dev/null
+++ b/开发文档/服务器管理/scripts/一键部署.py
@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+一键部署脚本
+============
+用途：根据配置文件一键部署Node项目到宝塔服务器
+
+使用方法：
+python3 一键部署.py 项目名称 本地项目路径
+
+示例：
+python3 一键部署.py soul /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验
+"""
+
+import sys
+import os
+import subprocess
+import time
+
+# 默认服务器配置
+默认配置 = {
+    "服务器IP": "42.194.232.22",
+    "SSH用户": "root",
+    "SSH密码": "Zhiqun1984",
+    "服务器根目录": "/www/wwwroot"
+}
+
+def 执行命令(命令: str, 显示输出: bool = True) -> tuple:
+    """执行shell命令"""
+    result = subprocess.run(命令, shell=True, capture_output=True, text=True)
+    if 显示输出 and result.stdout:
+        print(result.stdout)
+    if result.stderr and "Warning" not in result.stderr:
+        print(f"错误: {result.stderr}")
+    return result.returncode, result.stdout
+
+def 部署项目(项目名称: str, 本地路径: str):
+    """执行部署流程"""
+    服务器路径 = f"{默认配置['服务器根目录']}/{项目名称}"
+    压缩文件 = f"/tmp/{项目名称}_update.tar.gz"
+    
+    print(f"\n{'='*60}")
+    print(f"开始部署: {项目名称}")
+    print(f"本地路径: {本地路径}")
+    print(f"服务器路径: {服务器路径}")
+    print(f"{'='*60}\n")
+    
+    # 步骤1: 压缩项目
+    print("📦 步骤1: 压缩项目文件...")
+    排除项 = "--exclude='node_modules' --exclude='.next' --exclude='.git' --exclude='android' --exclude='out'"
+    压缩命令 = f"cd '{本地路径}' && tar {排除项} -czf {压缩文件} ."
+    code, _ = 执行命令(压缩命令, False)
+    if code != 0:
+        print("❌ 压缩失败")
+        return False
+    
+    # 获取文件大小
+    大小 = os.path.getsize(压缩文件) / 1024 / 1024
+    print(f"   ✅ 压缩完成，大小: {大小:.2f} MB")
+    
+    # 步骤2: 上传到服务器
+    print("\n📤 步骤2: 上传到服务器...")
+    上传命令 = f"sshpass -p '{默认配置['SSH密码']}' scp -o StrictHostKeyChecking=no {压缩文件} {默认配置['SSH用户']}@{默认配置['服务器IP']}:/tmp/"
+    code, _ = 执行命令(上传命令, False)
+    if code != 0:
+        print("❌ 上传失败")
+        return False
+    print("   ✅ 上传完成")
+    
+    # 步骤3-6: SSH远程执行
+    print("\n🔧 步骤3-6: 服务器端操作...")
+    
+    SSH前缀 = f"sshpass -p '{默认配置['SSH密码']}' ssh -o StrictHostKeyChecking=no {默认配置['SSH用户']}@{默认配置['服务器IP']}"
+    
+    # 清理旧文件
+    清理命令 = f"{SSH前缀} 'cd {服务器路径} && rm -rf app components lib public styles *.json *.js *.ts *.mjs *.md .next 2>/dev/null || true'"
+    执行命令(清理命令, False)
+    print("   ✅ 清理旧文件")
+    
+    # 解压
+    解压命令 = f"{SSH前缀} 'cd {服务器路径} && tar -xzf /tmp/{项目名称}_update.tar.gz'"
+    执行命令(解压命令, False)
+    print("   ✅ 解压新代码")
+    
+    # 安装依赖
+    print("\n📚 安装依赖 (这可能需要几分钟)...")
+    安装命令 = f"{SSH前缀} 'export PATH=/www/server/nodejs/v22.14.0/bin:$PATH && cd {服务器路径} && npm install --legacy-peer-deps 2>&1'"
+    执行命令(安装命令, True)
+    
+    # 构建
+    print("\n🏗️  构建项目...")
+    构建命令 = f"{SSH前缀} 'export PATH=/www/server/nodejs/v22.14.0/bin:$PATH && cd {服务器路径} && npm run build 2>&1'"
+    执行命令(构建命令, True)
+    
+    # 重启PM2
+    print("\n🔄 重启服务...")
+    重启命令 = f"{SSH前缀} 'export PATH=/www/server/nodejs/v22.14.0/bin:$PATH && pm2 restart {项目名称} 2>&1'"
+    执行命令(重启命令, True)
+    
+    # 清理临时文件
+    清理临时命令 = f"{SSH前缀} 'rm -f /tmp/{项目名称}_update.tar.gz'"
+    执行命令(清理临时命令, False)
+    os.remove(压缩文件)
+    
+    print(f"\n{'='*60}")
+    print("✅ 部署完成！")
+    print(f"{'='*60}")
+    print("\n⚠️  请在宝塔面板手动重启项目：")
+    print(f"   1. 登录 https://42.194.232.22:9988/ckbpanel")
+    print(f"   2. 进入【网站】→【Node项目】")
+    print(f"   3. 找到 {项目名称}，点击【重启】")
+    
+    return True
+
+def main():
+    if len(sys.argv) < 3:
+        print("用法: python3 一键部署.py <项目名称> <本地项目路径>")
+        print("\n示例:")
+        print("  python3 一键部署.py soul /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验")
+        print("  python3 一键部署.py kr_wb /Users/karuo/Documents/开发/4、小工具/whiteboard")
+        sys.exit(1)
+    
+    项目名称 = sys.argv[1]
+    本地路径 = sys.argv[2]
+    
+    if not os.path.exists(本地路径):
+        print(f"❌ 本地路径不存在: {本地路径}")
+        sys.exit(1)
+    
+    确认 = input(f"\n确认部署 {项目名称} 到服务器? (y/n): ")
+    if 确认.lower() != 'y':
+        print("已取消部署")
+        sys.exit(0)
+    
+    部署项目(项目名称, 本地路径)
+
+if __name__ == "__main__":
+    main()
diff --git a/开发文档/服务器管理/scripts/快速检查服务器.py b/开发文档/服务器管理/scripts/快速检查服务器.py
new file mode 100644
index 00000000..5667788c
--- /dev/null
+++ b/开发文档/服务器管理/scripts/快速检查服务器.py
@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+快速检查服务器状态
+==================
+用途：一键检查所有服务器的基本状态
+
+使用方法：
+python3 快速检查服务器.py
+"""
+
+import time
+import hashlib
+import requests
+import urllib3
+
+# 禁用SSL警告
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+# 服务器配置
+服务器列表 = {
+    "小型宝塔": {
+        "面板地址": "https://42.194.232.22:9988",
+        "密钥": "hsAWqFSi0GOCrunhmYdkxy92tBXfqYjd"
+    },
+    "存客宝": {
+        "面板地址": "https://42.194.245.239:9988",
+        "密钥": "TNKjqDv5N1QLOU20gcmGVgr82Z4mXzRi"
+    },
+    "kr宝塔": {
+        "面板地址": "https://43.139.27.93:9988",
+        "密钥": "qcWubCdlfFjS2b2DMT1lzPFaDfmv1cBT"
+    }
+}
+
+def 生成签名(api_key: str) -> tuple:
+    """生成宝塔API签名"""
+    now_time = int(time.time())
+    sign_str = str(now_time) + hashlib.md5(api_key.encode('utf-8')).hexdigest()
+    request_token = hashlib.md5(sign_str.encode('utf-8')).hexdigest()
+    return now_time, request_token
+
+def 获取系统信息(面板地址: str, 密钥: str) -> dict:
+    """获取系统基础统计信息"""
+    now_time, request_token = 生成签名(密钥)
+    
+    url = f"{面板地址}/system?action=GetSystemTotal"
+    data = {
+        "request_time": now_time,
+        "request_token": request_token
+    }
+    
+    try:
+        response = requests.post(url, data=data, timeout=10, verify=False)
+        return response.json()
+    except Exception as e:
+        return {"error": str(e)}
+
+def 检查单台服务器(名称: str, 配置: dict) -> dict:
+    """检查单台服务器状态"""
+    try:
+        系统信息 = 获取系统信息(配置["面板地址"], 配置["密钥"])
+        
+        if isinstance(系统信息, dict) and "error" not in 系统信息 and 系统信息.get("status") != False:
+            return {
+                "名称": 名称,
+                "状态": "✅ 正常",
+                "CPU": f"{系统信息.get('cpuRealUsed', 'N/A')}%",
+                "内存": f"{系统信息.get('memRealUsed', 'N/A')}%",
+                "磁盘": f"{系统信息.get('diskPer', 'N/A')}%"
+            }
+        else:
+            return {
+                "名称": 名称,
+                "状态": "❌ API错误",
+                "错误": str(系统信息)
+            }
+    except Exception as e:
+        return {
+            "名称": 名称,
+            "状态": "❌ 连接失败",
+            "错误": str(e)
+        }
+
+def main():
+    print("=" * 60)
+    print("                 服务器状态检查报告")
+    print("=" * 60)
+    print()
+    
+    for 名称, 配置 in 服务器列表.items():
+        结果 = 检查单台服务器(名称, 配置)
+        print(f"📦 {结果['名称']}")
+        print(f"   状态: {结果['状态']}")
+        if "CPU" in 结果:
+            print(f"   CPU: {结果['CPU']} | 内存: {结果['内存']} | 磁盘: {结果['磁盘']}")
+        if "错误" in 结果:
+            print(f"   错误: {结果['错误'][:50]}...")
+        print()
+    
+    print("=" * 60)
+
+if __name__ == "__main__":
+    main()
diff --git a/开发文档/章节拖拽排序-后台说明.md b/开发文档/章节拖拽排序-后台说明.md
new file mode 100644
index 00000000..e5dfd3c6
--- /dev/null
+++ b/开发文档/章节拖拽排序-后台说明.md
@@ -0,0 +1,74 @@
+# 章节拖拽排序 - 后台处理说明
+
+## 一、后台已实现
+
+### 1. 接口
+
+- **路径**：`PUT /api/db/book`
+- **鉴权**：需登录管理端（AdminAuth）
+
+**请求体**（拖拽排序时）：
+```json
+{
+  "action": "reorder",
+  "ids": ["1.1", "2.3", "3.1", ...]
+}
+```
+
+- `ids`：所有 section 的 id，按新的排序顺序排列
+- 后端会依次将每条记录的 `sort_order` 更新为 0、1、2、…
+
+### 2. 代码位置
+
+- `soul-api/internal/handler/db_book.go`：`DBBookAction` 中 `http.MethodPut` 分支，约第 196–206 行
+
+---
+
+## 二、数据库必须支持
+
+### 1. `sort_order` 列
+
+`chapters` 表必须有 `sort_order` 列，否则 `UPDATE sort_order` 会报错。
+
+**检查**：
+```sql
+SHOW COLUMNS FROM chapters LIKE 'sort_order';
+```
+
+**若不存在，执行迁移**：
+```bash
+cd e:\Gongsi\Mycontent
+node .cursor/scripts/db-exec/run.js -f soul-api/scripts/add-sort-order-to-chapters.sql
+```
+
+或手动执行：
+```sql
+ALTER TABLE chapters ADD COLUMN sort_order INT DEFAULT 0;
+```
+
+### 2. 现有数据处理
+
+若已有数据且 `sort_order` 为 NULL 或未设置，可先按当前顺序初始化：
+```sql
+SET @i = 0;
+UPDATE chapters SET sort_order = (@i := @i + 1) ORDER BY id;
+```
+
+---
+
+## 三、排查“无法拖拽”
+
+| 现象 | 可能原因 | 处理方式 |
+|------|----------|----------|
+| 拖不起来 | 拖拽手柄太小、浏览器兼容性 | 点击左侧 ⋮⋮ 后按住再拖动 |
+| 拖到目标没反应 | 未触发 drop | 确认拖到其他 section 行再松手 |
+| 松手后弹“排序失败” | 1. `sort_order` 列不存在<br>2. 鉴权失败 401<br>3. 接口异常 | 1. 执行迁移脚本<br>2. 确认已登录管理端<br>3. 查看 soul-api 日志和浏览器控制台 |
+
+---
+
+## 四、快速验证
+
+1. 执行迁移（若 `sort_order` 不存在）
+2. 重启 soul-api
+3. 在管理端登录后打开「内容管理 → 章节管理」
+4. 用 ⋮⋮ 拖拽某一节到另一位置，松手后应刷新并显示新顺序
diff --git a/开发文档/索引.md b/开发文档/索引.md
new file mode 100644
index 00000000..0849dcf2
--- /dev/null
+++ b/开发文档/索引.md
@@ -0,0 +1,207 @@
+# Soul 创业派对 - 开发文档索引
+
+> **以代码为准**：需求或实现变更时同步更新本文档与对应章节 README。最后更新：2026-04-07
+
+---
+
+## 一、目录总览
+
+| 目录 | 用途 |
+|------|------|
+| [1、需求](./1、需求/) | 主需求、界面基准、已完成碎片、修改草稿、归档 |
+| [2、架构](./2、架构/) | 系统与技术栈、链路、超级个体方向 |
+| [3、原型](./3、原型/) | 原型设计规范 |
+| [4、前端](./4、前端/) | 小程序与管理端前端架构、细则、UI 分册 |
+| [5、接口](./5、接口/) | Soul `/api` 文档、支付、配置清单 |
+| [6、后端](./6、后端/) | 后端规范、架构、迁移说明、**算法/** |
+| [7、数据库](./7、数据库/) | 设计与管理规范 |
+| [8、部署](./8、部署/) | 部署总览、Docker、宝塔、分销、Webhook、MCP |
+| [9、手册](./9、手册/) | 手册正文与 AI 提示词 |
+| [10、项目管理](./10、项目管理/) | 协作说明、[过程稿归档](./10、项目管理/archive/过程稿/) |
+| [Cunkebao接口文档](./Cunkebao接口文档/) | 存客宝（Cunkebao）前端项目接口 |
+| [小程序管理](./小程序管理/) | 小程序审核与认证等 |
+| [服务器管理](./服务器管理/) | 运维参考、虚拟机指南 |
+
+---
+
+## 二、根目录散落文件
+
+| 文件 | 归属 |
+|------|------|
+| [README.md](./README.md) | 开发文档总入口 |
+| [SKILL.md](./SKILL.md) | 开发文档相关 Skill 说明 |
+| [api_v1.md](./api_v1.md) | **存客宝对外线索上报**接口（非 Soul `/api`）；见文内说明 |
+| [三端需求业务对齐-小程序与API.md](./三端需求业务对齐-小程序与API.md) | 需求 / 对齐 |
+| [小程序功能与管理端配置补齐分析.md](./小程序功能与管理端配置补齐分析.md) | 需求 / 分析 |
+| [列表标准与角色分工.md](./列表标准与角色分工.md) | 协作规范 |
+| [章节拖拽排序-后台说明.md](./章节拖拽排序-后台说明.md) | 功能说明 |
+
+### 过程记录（已迁入归档时见 `10、项目管理/archive/过程稿/`）
+
+历史验收、飞书推送摘录等若已从根目录移走，请在该归档目录查找。
+
+---
+
+## 三、1、需求
+
+| 文件/路径 | 用途 |
+|-----------|------|
+| [索引.md](./1、需求/索引.md) | 主需求文件规则 |
+| [以界面定需求.md](./1、需求/以界面定需求.md) | 界面级需求基准 |
+| [2026-03-20-需求.md](./1、需求/2026-03-20-需求.md) | 当前主需求清单 |
+| [AI剪辑分发功能需求.md](./1、需求/AI剪辑分发功能需求.md) | 专项 |
+| [链接人与事-*.md](./1、需求/) | 根下部分为 **跳转 stub**，正文在 `archive/` |
+| [已完成/](./1、需求/已完成/) | 按日期拆分的已完成需求正文 |
+| [archive/](./1、需求/archive/) | 链接人与事等归档与线框图 |
+
+---
+
+## 四、2、架构
+
+| 文件 | 用途 |
+|------|------|
+| [README.md](./2、架构/README.md) | 本目录索引 |
+| [系统与技术.md](./2、架构/系统与技术.md) | 系统与技术总述 |
+| [soul-api技术栈.md](./2、架构/soul-api技术栈.md) | 后端技术栈 |
+| [链路与变现.md](./2、架构/链路与变现.md) | 业务链路 |
+| [超级个体（用户模块方向）.md](./2、架构/超级个体（用户模块方向）.md) | 用户模块方向 |
+| [Gin技术栈-Go1.25依赖清单.md](./2、架构/Gin技术栈-Go1.25依赖清单.md) | Go/Gin 依赖 |
+
+---
+
+## 五、3、原型
+
+| 文件 | 用途 |
+|------|------|
+| [README.md](./3、原型/README.md) | 本目录索引 |
+| [原型设计规范.md](./3、原型/原型设计规范.md) | 原型规范 |
+
+---
+
+## 六、4、前端
+
+| 文件/路径 | 用途 |
+|-----------|------|
+| [README.md](./4、前端/README.md) | 本目录索引 |
+| [前端架构.md](./4、前端/前端架构.md) | 架构 |
+| [前端开发规范.md](./4、前端/前端开发规范.md) | 规范 |
+| [当前小程序开发细则.md](./4、前端/当前小程序开发细则.md) | 小程序细则 |
+| [模块详解.md](./4、前端/模块详解.md) | 模块说明 |
+| [ui/](./4、前端/ui/) | 概述、组件、部署与截图 |
+
+---
+
+## 七、5、接口
+
+| 文件 | 用途 |
+|------|------|
+| [README.md](./5、接口/README.md) | 本目录索引 |
+| [API接口完整文档.md](./5、接口/API接口完整文档.md) | **Soul 项目 API 主真源** |
+| [配置清单-完整版.md](./5、接口/配置清单-完整版.md) | 配置项清单 |
+| [在线支付对接文档.md](./5、接口/在线支付对接文档.md) | 支付 |
+| [接口与提现.md](./5、接口/接口与提现.md) | 提现相关接口说明 |
+
+---
+
+## 八、6、后端
+
+| 文件/路径 | 用途 |
+|-----------|------|
+| [README.md](./6、后端/README.md) | 本目录索引 |
+| [后端架构.md](./6、后端/后端架构.md) | soul-api 架构 |
+| [后端开发规范.md](./6、后端/后端开发规范.md) | 编码与路由约定 |
+| [内容创建问题修复说明.md](./6、后端/内容创建问题修复说明.md) | 专项修复说明 |
+| [soul-admin与Mycontent-temp内容页对比.md](./6、后端/soul-admin与Mycontent-temp内容页对比.md) | 管理端内容页对比 |
+| [**算法/**](./6、后端/算法/) | RFM、旅程统计、找伙伴匹配、存客宝留资 |
+
+---
+
+## 九、7、数据库
+
+| 文件 | 用途 |
+|------|------|
+| [README.md](./7、数据库/README.md) | 本目录索引 |
+| [数据库设计.md](./7、数据库/数据库设计.md) | 表结构设计 |
+| [数据库管理规范.md](./7、数据库/数据库管理规范.md) | 管理规范 |
+
+---
+
+## 十、8、部署
+
+| 文件 | 用途 |
+|------|------|
+| [README.md](./8、部署/README.md) | 本目录文件列表 |
+| [**部署总览.md**](./8、部署/部署总览.md) | **部署入口导航** |
+| [运行与部署.md](./8、部署/运行与部署.md) | 运行与部署说明 |
+| [DOCKER部署说明.md](./8、部署/DOCKER部署说明.md) | Docker |
+| [宝塔-Docker首次配置指南.md](./8、部署/宝塔-Docker首次配置指南.md) | 宝塔 + Docker |
+| [自动化与Webhook.md](./8、部署/自动化与Webhook.md) | Webhook |
+| [分销与绑定流程图.md](./8、部署/分销与绑定流程图.md)、[分销提现流程图.md](./8、部署/分销提现流程图.md) | 分销流程 |
+| [新分销逻辑-*.md](./8、部署/)、[佣金*.md](./8、部署/)、[邀请码分销规则说明.md](./8、部署/邀请码分销规则说明.md) | 分销与佣金专题 |
+| [支付接口清单.md](./8、部署/支付接口清单.md)、[章节阅读付费标准流程设计.md](./8、部署/章节阅读付费标准流程设计.md)、[阅读页标准流程改造说明.md](./8、部署/阅读页标准流程改造说明.md) | 支付与阅读 |
+| [存客宝API-Key约定.md](./8、部署/存客宝API-Key约定.md) | 存客宝密钥 |
+| [API接入说明.md](./8、部署/API接入说明.md) | API 接入 |
+| [MCP-MySQL配置说明.md](./8、部署/MCP-MySQL配置说明.md)、[Soul-MySQL-MCP配置说明.md](./8、部署/Soul-MySQL-MCP配置说明.md) | MCP |
+| [VIP功能-数据库迁移说明.md](./8、部署/VIP功能-数据库迁移说明.md)、[代码逻辑和数据库最终检查清单.md](./8、部署/代码逻辑和数据库最终检查清单.md) | 迁移与检查 |
+| [宝塔面板配置订单同步定时任务.md](./8、部署/宝塔面板配置订单同步定时任务.md)、[其它.md](./8、部署/其它.md) | 运维杂项 |
+
+> 历史上计划单独编写的《宝塔反向代理说明》《提现功能完整技术文档》《订阅消息》《商家转账》若未落盘，请在 [部署总览.md](./8、部署/部署总览.md) 中按「等价内容」指向现有文档或 `5、接口`、`soul-api` 代码注释。
+
+---
+
+## 十一、9、手册
+
+| 文件/路径 | 用途 |
+|-----------|------|
+| [手册索引.md](./9、手册/手册索引.md) | 手册与提示词总索引 |
+| [写作与结构维护手册.md](./9、手册/写作与结构维护手册.md) | 书籍写作规范 |
+| [全站捆绑分销体系-SCALE.md](./9、手册/全站捆绑分销体系-SCALE.md) | 分销规格 |
+| [使用手册提示词.md](./9、手册/使用手册提示词.md) | **卡若风格操作手册** AI 角色（主入口） |
+| [提示词/](./9、手册/提示词/) | 落地方案、说明手册、截图/Word 工具需求等 |
+
+---
+
+## 十二、10、项目管理
+
+| 文件/路径 | 用途 |
+|-----------|------|
+| [README.md](./10、项目管理/README.md) | 本目录说明 |
+| [闭环与文档同步-2026-04-07.md](./10、项目管理/闭环与文档同步-2026-04-07.md) | **需求与开发文档对齐后的闭环结论与待办** |
+| [存客宝协作需求.md](./10、项目管理/存客宝协作需求.md) | 协作需求 |
+| [项目管理提示词.md](./10、项目管理/项目管理提示词.md) | 项目管理向 AI 提示词 |
+| [archive/过程稿/](./10、项目管理/archive/过程稿/) | 飞书推送摘录、全站修复报告、提审清单等**过程稿** |
+
+---
+
+## 十三、Cunkebao 与小程序/服务器管理
+
+| 路径 | 用途 |
+|------|------|
+| [Cunkebao接口文档/README.md](./Cunkebao接口文档/README.md) | 存客宝前端接口目录说明 |
+| [Cunkebao接口文档/API接口清单.md](./Cunkebao接口文档/API接口清单.md) | 接口清单 |
+| [Cunkebao接口文档/入参出参结构.md](./Cunkebao接口文档/入参出参结构.md) | 类型与结构 |
+| [小程序管理/SKILL.md](./小程序管理/SKILL.md) | 小程序管理 Skill |
+| [服务器管理/SKILL.md](./服务器管理/SKILL.md) | 服务器管理 Skill |
+
+---
+
+## 十四、仓库内其他文档入口
+
+| 路径 | 用途 |
+|------|------|
+| `scripts/test/功能测试流程.md` | 若仓库内已提供则补充链接（当前仓库可无此路径） |
+| [soul-api/文档索引.md](../soul-api/文档索引.md) | 后端指向本开发文档 |
+| [miniprogram/README.md](../miniprogram/README.md) | 小程序项目说明 |
+
+---
+
+## 十五、场景速查
+
+| 场景 | 推荐文档 |
+|------|----------|
+| 新增/变更功能 | [以界面定需求.md](./1、需求/以界面定需求.md) → [2026-03-20-需求.md](./1、需求/2026-03-20-需求.md) |
+| Soul API | [5、接口/API接口完整文档.md](./5、接口/API接口完整文档.md) |
+| RFM / 找伙伴规则 | [6、后端/算法/](./6、后端/算法/) |
+| 部署 | [8、部署/部署总览.md](./8、部署/部署总览.md) |
+| 存客宝前端 | [Cunkebao接口文档/](./Cunkebao接口文档/) |
+| 对外线索上报（非 Soul） | [api_v1.md](./api_v1.md) |