# 小医系统整改计划

> 版本：v1.0  
> 编制时间：2026-04-28 14:12  
> 编制依据：《建档流程与架构分析报告》  
> 状态：待审批

---

## 一、问题汇总

### 1.1 问题来源

根据《建档流程与架构分析报告》（2026-04-28），共识别出 **7 个问题**：

| 编号 | 问题 | 严重级别 | 状态 |
|------|------|----------|------|
| P001 | user_index.json 同步风险 | 🔴 严重 | 待修复 |
| P002 | 渠道激活依赖用户主动发消息 | 🔴 严重 | 待修复 |
| P003 | 档案目录结构不统一 | ⚠️ 中等 | 待修复 |
| P004 | 活动名称映射维护成本高 | ⚠️ 中等 | 待修复 |
| P005 | SESSION_STATE 文件分散 | ⚠️ 中等 | 待修复 |
| P006 | 文档版本管理不规范 | ℹ️ 低 | 待修复 |
| P007 | 测试档案未清理 | ℹ️ 低 | 待修复 |

### 1.2 新增问题（本次发现）

| 编号 | 问题 | 严重级别 | 状态 |
|------|------|----------|------|
| P008 | 云部署脚本硬编码 contactId（越权风险） | 🔴 严重 | 待修复 |

---

## 二、整改计划总览

### 2.1 整改阶段划分

| 阶段 | 时间 | 目标 | 问题数量 |
|------|------|------|----------|
| **第一阶段：紧急修复** | 第 1 周 | 解决严重级别问题 | 3 个（P001, P002, P008） |
| **第二阶段：中期优化** | 第 2-3 周 | 解决中等级别问题 | 3 个（P003, P004, P005） |
| **第三阶段：长期完善** | 第 4-6 周 | 解决低级别问题 + 架构升级 | 2 个（P006, P007）+ 2 个新增 |

---

### 2.2 整改任务清单

| 任务 ID | 关联问题 | 任务名称 | 优先级 | 预计工时 | 责任角色 |
|---------|----------|----------|--------|----------|----------|
| T001 | P001 | 增强 user_index.json 同步脚本健壮性 | P0 | 4 小时 | 开发 |
| T002 | P002 | 增加渠道状态监控机制 | P0 | 4 小时 | 开发 |
| T003 | P008 | 修复云部署脚本越权问题 | P0 | 2 小时 | 开发 |
| T004 | P003 | 统一档案目录结构 | P1 | 8 小时 | 开发 |
| T005 | P004 | 优化活动名称映射管理 | P1 | 6 小时 | 开发 + 运营 |
| T006 | P005 | 统一 SESSION_STATE 文件位置 | P1 | 4 小时 | 开发 |
| T007 | P006 | 规范文档版本管理 | P2 | 4 小时 | 文档 |
| T008 | P007 | 清理测试档案 | P2 | 2 小时 | 运维 |
| T009 | - | 引入数据库存储（长期） | P2 | 40 小时 | 开发 |
| T010 | - | 建立自动化测试体系 | P2 | 20 小时 | 测试 |

---

## 三、详细整改方案

### 3.1 第一阶段：紧急修复（第 1 周）

---

#### 任务 T001：增强 user_index.json 同步脚本健壮性

**关联问题：** P001 — user_index.json 同步风险

**问题描述：**
- 档案创建后依赖脚本同步到 user_index.json
- subprocess 调用可能超时或失败
- 失败后没有回滚机制
- 导致数据不一致

**整改目标：**
- 同步成功率达到 99.9%
- 失败时自动回滚
- 增加监控告警

**技术方案：**

```python
# 修改 skills/user-onboard/scripts/sync_user_index.py

def call_update_script(contact_id, *args):
    """调用 update_user_index.py（增加重试机制）"""
    max_retries = 3
    for attempt in range(max_retries):
        try:
            cmd = ["python3", str(UPDATE_SCRIPT), contact_id] + list(args)
            result = subprocess.run(
                cmd,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
                universal_newlines=True,
                timeout=10,
                env=env
            )
            if result.returncode == 0:
                return True
            else:
                if attempt == max_retries - 1:
                    return False
                time.sleep(1)  # 重试前等待
        except Exception as e:
            if attempt == max_retries - 1:
                return False
            time.sleep(1)
    return False
```

**修改文件清单：**
- `skills/user-onboard/scripts/sync_user_index.py`
- `skills/user-onboard/scripts/archive.py`
- `skills/user-onboard/scripts/verify_user.py`

**验收标准：**
- [ ] 同步脚本增加重试机制（最多 3 次）
- [ ] 同步失败时回滚 user_index.json 修改
- [ ] 增加同步日志（记录每次同步结果）
- [ ] 同步失败时通知 owner

**风险评估：**
- 风险等级：低
- 影响范围：user_index.json 同步流程
- 回滚方案：保留旧版本脚本，可随时切换

---

#### 任务 T002：增加渠道状态监控机制

**关联问题：** P002 — 渠道激活依赖用户主动发消息

**问题描述：**
- tutu-aggchat 通道需要用户主动发消息才能激活
- 新用户添加后不发消息 → 无法发送欢迎词
- 员工建档后不发消息 → 无法接收工单通知

**整改目标：**
- 实时掌握渠道激活状态
- 未激活用户 24 小时内提醒
- 欢迎流程执行率提升到 95%

**技术方案：**

```bash
# 新增脚本：scripts/check_channel_status.sh

#!/bin/bash
# 渠道状态监控脚本

USER_INDEX="/home/admin/.openclaw/workspace/user_index.json"
OUTPUT_FILE="/home/admin/.openclaw/workspace/logs/channel_status_$(date +%Y%m%d).json"

# 读取所有 contactId
contactIds=$(cat "$USER_INDEX" | jq -r 'keys[]')

results=()
for contactId in $contactIds; do
    # 调用 tutu API 检查渠道状态
    status=$(curl -s -X POST "https://tutu-gateway.lovebenefits.com/tutu-api/api/jkzl/mcp/chat/contact/status" \
        -H "Content-Type: application/json" \
        -d "{\"tenant\":\"jkzl\",\"contactId\":\"$contactId\"}" | jq -r '.status')
    
    if [ "$status" != "active" ]; then
        results+=("{\"contactId\":\"$contactId\",\"status\":\"inactive\"}")
    fi
done

# 输出结果
echo "{\"timestamp\":\"$(date -Iseconds)\",\"unactivated\":[$(IFS=,; echo "${results[*]}")]}" > "$OUTPUT_FILE"
```

**新增文件清单：**
- `scripts/check_channel_status.sh`
- `logs/channel_status/` 目录

**修改文件清单：**
- `HEARTBEAT.md`（增加渠道检查任务）

**验收标准：**
- [ ] 渠道状态监控脚本可正常运行
- [ ] 每日生成未激活用户列表
- [ ] 未激活用户 24 小时内发送提醒
- [ ] 运营人员可查看未激活用户列表

**风险评估：**
- 风险等级：中
- 影响范围：渠道管理流程
- 依赖：tutu-aggchat API 支持

---

#### 任务 T003：修复云部署脚本越权问题

**关联问题：** P008 — 云部署脚本硬编码 contactId

**问题描述：**
- `update-reports.sh` 硬编码 owner 的 contactId（7v1xmj9q）
- 非 owner 用户可操作 owner 的资源
- 违反数据隔离原则

**整改目标：**
- 部署使用当前用户的 contactId
- 增加权限检查
- 记录部署审计日志

**技术方案：**

```bash
# 修改 scripts/update-reports.sh

# 从环境变量或会话标识获取当前用户 contactId
CONTACT_ID="${DEPLOY_CONTACT_ID:-}"

if [ -z "$CONTACT_ID" ]; then
    # 尝试从会话标识解析
    CONTACT_ID=$(python3 -c "
import os
# 从环境变量或会话标识获取
session_key = os.environ.get('SESSION_KEY', '')
if ':' in session_key:
    contact_id = session_key.split(':')[-1]
    print(contact_id)
")
fi

if [ -z "$CONTACT_ID" ]; then
    echo "❌ 错误：无法获取当前用户 contactId"
    echo "请设置环境变量 DEPLOY_CONTACT_ID 或从会话中自动获取"
    exit 1
fi

# 权限检查
ROLE=$(python3 -c "
import json
user_index = json.load(open('/home/admin/.openclaw/workspace/user_index.json'))
info = user_index.get('$CONTACT_ID', {})
print(info.get('role', 'unknown'))
")

if [ "$ROLE" = "owner" ]; then
    echo "👤 当前用户：$CONTACT_ID (owner)"
elif [ "$ROLE" = "employee" ]; then
    echo "👤 当前用户：$CONTACT_ID (employee)"
else
    echo "👤 当前用户：$CONTACT_ID (other-contacts)"
fi

# 记录审计日志
echo "{\"timestamp\":\"$(date -Iseconds)\",\"contactId\":\"$CONTACT_ID\",\"role\":\"$ROLE\",\"action\":\"deploy\",\"project\":\"$PROJECT_NAME\"}" >> ~/.openclaw/cloud-deploy-audit.log
```

**修改文件清单：**
- `skills/cloud-deploy/scripts/update-reports.sh`
- `skills/cloud-deploy/scripts/deploy.sh`

**新增文件清单：**
- `~/.openclaw/cloud-deploy-audit.log`（审计日志）

**验收标准：**
- [ ] 移除硬编码的 contactId
- [ ] 自动获取当前用户 contactId
- [ ] 增加权限检查（记录角色）
- [ ] 记录部署审计日志
- [ ] 非 owner 用户只能部署到自己的 namespace

**风险评估：**
- 风险等级：高（安全相关）
- 影响范围：云部署功能
- 回滚方案：保留旧版本脚本

---

### 3.2 第二阶段：中期优化（第 2-3 周）

---

#### 任务 T004：统一档案目录结构

**关联问题：** P003 — 档案目录结构不统一

**问题描述：**
- 不同用户的档案目录结构存在差异
- 旧格式使用手机号作为目录名
- 增加维护成本

**整改目标：**
- 所有档案使用统一格式（contactId 作为目录名）
- 迁移旧格式档案
- 更新同步脚本

**修改文件清单：**
- `skills/user-onboard/scripts/sync-all-to-user-index.py`
- `skills/user-onboard/scripts/archive.py`

**新增文件清单：**
- `scripts/migrate-legacy-archives.sh`
- `docs/archive-migration-plan.md`

**验收标准：**
- [ ] 所有档案目录使用 contactId 作为目录名
- [ ] 旧格式档案迁移完成
- [ ] 同步脚本支持新格式
- [ ] 迁移日志记录完整

---

#### 任务 T005：优化活动名称映射管理

**关联问题：** P004 — 活动名称映射维护成本高

**问题描述：**
- 映射表位置分散（config/ + AGENTS.md）
- 新活动上线需手动更新多处
- 容易遗漏或过时

**整改目标：**
- 统一映射表位置
- 增加映射表验证脚本
- 支持运营人员自助更新

**修改文件清单：**
- `config/activity-name-mapping.json`（统一格式）
- `skills/activity-reg-link/SKILL.md`（读取统一映射表）
- `AGENTS.md`（移除内嵌映射表，引用配置文件）

**新增文件清单：**
- `scripts/validate-activity-mapping.py`（映射表验证脚本）
- `docs/activity-mapping-guide.md`（运营人员更新指南）

**验收标准：**
- [ ] 映射表统一位置（仅 config/activity-name-mapping.json）
- [ ] 增加映射表验证脚本
- [ ] AGENTS.md 引用配置文件
- [ ] 运营人员可自助更新

---

#### 任务 T006：统一 SESSION_STATE 文件位置

**关联问题：** P005 — SESSION_STATE 文件分散

**问题描述：**
- SESSION_STATE 文件分布在多个位置
- 加载逻辑复杂
- 容易加载错误文件

**整改目标：**
- 统一 SESSION_STATE 文件位置
- 制定加载优先级规则
- 增加降级处理

**修改文件清单：**
- `skills/memory-continuity/SKILL.md`
- `skills/user-onboard/scripts/check_contactId.py`

**新增文件清单：**
- `memory/sessions/` 目录
- `docs/session-state-migration.md`

**验收标准：**
- [ ] SESSION_STATE 文件统一位置
- [ ] 兼容旧位置（自动迁移）
- [ ] 加载优先级规则明确
- [ ] 文件不存在时降级处理

---

### 3.3 第三阶段：长期完善（第 4-6 周）

---

#### 任务 T007：规范文档版本管理

**关联问题：** P006 — 文档版本管理不规范

**整改目标：**
- 所有核心文档增加版本号
- 统一更新时间格式
- 增加变更日志

**新增文件清单：**
- `CHANGELOG.md`（变更日志）
- `docs/documentation-standards.md`（文档规范）

**验收标准：**
- [ ] 所有核心文档增加版本号
- [ ] 统一更新时间格式（ISO 8601）
- [ ] 增加变更日志

---

#### 任务 T008：清理测试档案

**关联问题：** P007 — 测试档案未清理

**整改目标：**
- 清理所有测试档案
- 测试档案使用独立目录
- 同步脚本自动跳过测试目录

**新增文件清单：**
- `test-contacts/` 目录（测试档案专用）
- `scripts/cleanup-test-archives.sh`

**验收标准：**
- [ ] 所有测试档案清理完成
- [ ] 测试档案使用独立目录
- [ ] 同步脚本自动跳过测试目录

---

#### 任务 T009：引入数据库存储（长期）

**整改目标：**
- 使用 SQLite/PostgreSQL 替代文件存储
- 提高数据一致性
- 支持复杂查询

**新增文件清单：**
- `database/schema.sql`
- `database/db.py`（数据库操作封装）

---

#### 任务 T010：建立自动化测试体系

**整改目标：**
- 建立自动化测试框架
- 核心功能测试覆盖率 > 80%

**新增文件清单：**
- `tests/` 目录
- `tests/test_user_onboard.py`
- `.github/workflows/ci.yml`（CI 配置）

---

## 四、风险评估

### 4.1 风险矩阵

| 风险 | 可能性 | 影响 | 风险等级 | 缓解措施 |
|------|--------|------|----------|----------|
| 数据迁移丢失 | 低 | 高 | ⚠️ 中 | 迁移前完整备份 |
| 同步脚本故障 | 中 | 高 | ⚠️ 中 | 保留旧版本，灰度发布 |
| 渠道 API 变更 | 低 | 中 | ℹ️ 低 | 抽象 API 接口层 |
| 测试覆盖不足 | 中 | 中 | ℹ️ 低 | 分阶段增加测试 |

### 4.2 回滚方案

| 任务 | 回滚方案 |
|------|----------|
| T001 | 保留旧版 sync_user_index.py，可随时切换 |
| T002 | 关闭渠道监控任务，不影响现有功能 |
| T003 | 恢复硬编码 contactId，重新部署 |
| T004 | 保留旧目录结构，手动恢复 |
| T005 | 恢复 AGENTS.md 内嵌映射表 |
| T006 | 恢复旧 SESSION_STATE 位置 |
| T009 | 保留文件存储，双写模式过渡 |

---

## 五、验收标准

### 5.1 第一阶段验收（第 1 周末）

- [ ] P001: user_index.json 同步成功率 > 99.9%
- [ ] P002: 渠道监控脚本正常运行
- [ ] P008: 云部署脚本无硬编码 contactId

### 5.2 第二阶段验收（第 3 周末）

- [ ] P003: 所有档案目录使用 contactId
- [ ] P004: 映射表统一位置
- [ ] P005: SESSION_STATE 文件统一位置

### 5.3 第三阶段验收（第 6 周末）

- [ ] P006: 所有核心文档有版本号
- [ ] P007: 测试档案清理完成
- [ ] T009: 数据库存储上线（可选）
- [ ] T010: 自动化测试覆盖率 > 80%

---

## 六、资源需求

### 6.1 人力资源

| 角色 | 人数 | 工时 |
|------|------|------|
| 开发工程师 | 1-2 | 80 小时 |
| 测试工程师 | 1 | 20 小时 |
| 文档工程师 | 0.5 | 10 小时 |
| 运营人员 | 0.5 | 6 小时 |

---

## 七、审批流程

| 阶段 | 审批人 | 状态 | 日期 |
|------|--------|------|------|
| 计划编制 | 小医 | ✅ 已完成 | 2026-04-28 |
| 技术评审 | 待指定 | ⏳ 待审批 | - |
| 产品评审 | 高祖峰 | ⏳ 待审批 | - |
| 最终批准 | 高祖峰 | ⏳ 待审批 | - |

---

## 八、附录

### A. 相关文件清单

| 文件 | 说明 | 位置 |
|------|------|------|
| 建档流程与架构分析报告.md | 分析报告原文 | docs/architecture-analysis/ |
| issue-tracker-20260427.md | 问题执行清单 | docs/ |
| history-issues-tracker.md | 历史问题追踪 | docs/ |

### B. 术语表

| 术语 | 说明 |
|------|------|
| contactId | tutu-aggchat 分配的用户短 ID（8 位） |
| user_index.json | 全局用户索引文件 |
| SESSION_STATE | 会话状态文件 |
| tutu-aggchat | 企业微信聚合聊天通道 |

---

_整改计划版本：v1.0_  
_编制时间：2026-04-28 14:12_  
_编制依据：《建档流程与架构分析报告》_  
_状态：待审批_  
_保存位置：/home/admin/.openclaw/workspace/docs/architecture-analysis/整改计划-v1.0.md_