Skill: smxtx/complex-app-dev-principles (version 1.0.0)

--- name: complex-app-dev-principles description: 复杂APP模块化开发技能，遵循五大核心原则进行科学、有序、可控的APP开发。适用于从零开始开发复杂APP或重构现有项目。 version: 1.0.0 author: Matrix Agent tags: [APP开发, 模块化开发, 敏捷开发, 确认制开发, 复杂APP] trigger_keywords: [APP开发, 复杂APP, 移动应用开发, 模块开发, 开发原则, I漫剧] --- # 复杂APP开发原则技能 ## 何时使用此技能 当用户需要以下场景时激活此技能： 1. **从头开发I漫剧APP** - 从需求分析到最终交付的完整流程 2. **重构现有APP项目** - 按模块化原则重新组织代码结构 3. **制定APP开发规范** - 建立团队统一的开发流程标准 4. **模块化开发咨询** - 获取模块划分、数据共享、测试策略等指导 5. **开发流程审计** - 检查现有开发流程是否符合规范 --- ## 核心开发原则 ### 原则1：建立科学的开发流程 理解和建立APP实现最终功能须经历的步骤，从而建立包含若干必须功能模块的科学先进的开发流程。 **实施要点：** - 分析APP最终功能需求 - 拆解功能为独立的必须模块 - 建立模块间的依赖关系和调用顺序 - 制定每个模块的开发标准和验收标准 ### 原则2：模块独立与数据共享 各功能模块独立打包，并按使用逻辑相互联系，各模块生成的数据可在各模块间顺畅共享和理解识别。 **实施要点：** - 每个功能模块独立开发、独立测试 - 定义统一的数据接口规范 - 建立模块间数据共享机制 - 确保数据格式在各模块间可被正确识别和处理 ### 原则3：开发者确认与代码锁定 开发过程中设置开发者确认功能，一经开发者确认，须锁定确认前的所有模块功能及相应代码，清除其他无效或与现确认功能不相一致的代码。 **实施要点：** - 每个模块完成后必须经过开发者确认 - 确认后的模块代码进入锁定状态 - 自动清除与已确认功能不一致的冗余代码 - 锁定记录可追溯，便于问题回溯 ### 原则4：顺序测试调试 开发流程从前往后对功能模块逐一测试调试，期间不涉及其他模块，一经开发者确认方进入下一模块。 **实施要点：** - 按流程顺序依次测试各功能模块 - 当前模块测试期间不引入其他模块干扰 - 开发者确认通过后才能进入下一模块 - 记录每个模块的测试结果和问题 ### 原则5：全局测试与最终锁定 全部模块测试确认后，测试全局，并按开发者意见不断完善修正，最后锁定。 **实施要点：** - 所有模块联调，进行全局功能测试 - 根据开发者反馈进行优化修正 - 最终全面验收后锁定全部代码 - 生成开发完成报告和交付物清单 --- ## 功能模块参考框架（I漫剧APP） ### 基础模块层（Layer 1） | 模块名称 | 功能描述 | 优先级 | |---------|---------|--------| | 用户认证模块 | 注册、登录、权限管理、OAuth第三方登录 | P0 | | 内容管理模块 | 漫剧内容的上传、编辑、审核、版本控制 | P0 | | 用户画像模块 | 用户行为数据收集与分析、偏好建模 | P1 | ### 业务模块层（Layer 2） | 模块名称 | 功能描述 | 优先级 | |---------|---------|--------| | 播放引擎模块 | 漫剧内容的播放、控制、缓存、画质切换 | P0 | | 互动社区模块 | 评论、点赞、分享、弹幕、话题讨论 | P1 | | 推荐算法模块 | 个性化内容推荐、冷启动、热榜 | P1 | ### 支撑模块层（Layer 3） | 模块名称 | 功能描述 | 优先级 | |---------|---------|--------| | 消息通知模块 | 推送、提醒、站内信、系统通知 | P2 | | 支付结算模块 | 付费内容、会员订阅、虚拟货币 | P2 | | 数据分析模块 | 运营数据统计、报表、AB测试 | P2 | ### 公共模块（Infrastructure） | 模块名称 | 功能描述 | 优先级 | |---------|---------|--------| | 日志记录模块 | 系统运行日志、用户行为日志 | P0 | | 配置管理模块 | 应用配置、热更新、开关控制 | P1 | | 异常处理模块 | 全局异常捕获与处理、容灾降级 | P0 | --- ## 开发流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 开发阶段流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ [1.需求分析] → [2.模块设计] → [3.模块开发] → [4.模块测试] │ │ ↓ ↓ ↓ ↓ │ │ └────────────────┴──────────────┴──────────────┘ │ │ ↓ │ │ [5.开发者确认] │ │ ↓ │ │ ┌────────────────┬───────────────┬────────────────┐ │ │ ↓ ↓ ↓ ↓ │ │ [6.模块联调] ← [循环至所有模块确认] → [7.联调测试] → [8.全局测试] │ │ ↓ │ │ [9.最终锁定] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 阶段详细说明 | 阶段 | 输入 | 输出 | 验收标准 | |-----|------|------|---------| | 1.需求分析 | 产品需求文档、用户故事 | 功能清单、优先级排序 | 需求覆盖完整、无遗漏 | | 2.模块设计 | 功能清单 | 模块划分图、接口定义、数据字典 | 模块边界清晰、依赖关系明确 | | 3.模块开发 | 模块设计文档 | 可运行代码、单元测试 | 代码符合规范、测试通过 | | 4.模块测试 | 模块代码 | 测试报告、缺陷列表 | 功能完整、无阻塞缺陷 | | 5.开发者确认 | 测试报告 | 确认签字、代码锁定 | 开发者审核通过 | | 6-8.联调测试 | 已锁定模块 | 集成测试报告 | 全流程跑通、性能达标 | | 9.最终锁定 | 测试报告 | 发布版本、交付清单 | 验收通过、代码冻结 | --- ## 代码锁定机制 ### 锁定规则 1. **单模块锁定**：单个模块开发测试完成后，开发者确认即锁定 2. **级联锁定**：后续模块依赖已锁定模块时，不得修改已锁定模块 3. **解锁流程**：如需修改已锁定模块，必须走解锁审批流程 ### 锁定检查清单 - [ ] 模块代码已提交到指定分支 - [ ] 所有单元测试通过 - [ ] 开发者审核签字 - [ ] 依赖此模块的其他模块已记录 - [ ] 锁定记录已创建 --- ## 数据共享规范 ### 接口设计原则 ``` ┌─────────────┐ 接口契约 ┌─────────────┐ │ 模块A │ ←───────────────→ │ 模块B │ │ │ 统一数据格式 │ │ └─────────────┘ └─────────────┘ ``` ### 数据格式标准 - 使用JSON作为模块间数据交换格式 - 关键字段必须包含：`id`、`type`、`timestamp`、`version` - 敏感数据需加密传输 ### 共享数据示例 ```json { "id": "unique_identifier", "type": "data_type", "timestamp": "2026-03-24T03:52:44Z", "version": "1.0.0", "payload": {} } ``` --- ## 参考资源 | 资源类型 | 路径 | 说明 | |---------|------|------| | 模块设计模板 | `references/module_design_template.md` | 模块设计文档模板 | | 接口定义规范 | `references/api_specification.md` | API接口设计规范 | | 测试用例模板 | `references/test_case_template.md` | 测试用例编写规范 | | 交付清单模板 | `references/delivery_checklist.md` | 项目交付检查清单 | --- ## 脚本工具 | 脚本名称 | 用途 | 命令 | |---------|------|------| | `validate_structure.py` | 验证项目目录结构 | `python scripts/validate_structure.py` | | `generate_module.py` | 生成模块骨架代码 | `python scripts/generate_module.py <module_name>` | | `lock_module.sh` | 锁定指定模块 | `bash scripts/lock_module.sh <module_name>` | --- ## 版本变更记录 | 版本 | 日期 | 变更内容 | |-----|------|---------| | 1.0.0 | 2026-03-24 | 初始版本，定义五大核心原则和模块框架 |

path: references/api_specification.md
content: # API接口设计规范

## 1. 概述

本文档定义了I漫剧APP模块间API接口的设计标准，确保各模块间的数据能够顺畅共享和理解识别。

## 2. 通用规范

### 2.1 数据格式
- 所有接口统一使用 **JSON** 格式
- 响应编码为 **UTF-8**
- 时间格式使用 **ISO 8601** 标准

### 2.2 标准响应格式

```json
{
    "code": 0,
    "message": "success",
    "data": {},
    "request_id": "uuid",
    "timestamp": "2026-03-24T03:52:44Z"
}
```

| 字段 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0表示成功 |
| message | string | 状态信息 |
| data | object | 业务数据 |
| request_id | string | 请求追踪ID |
| timestamp | string | 响应时间戳 |

### 2.3 错误码定义

| 错误码 | 说明 | 处理建议 |
|-------|------|---------|
| 0 | 成功 | - |
| 1001 | 参数错误 | 检查输入参数 |
| 1002 | 认证失败 | 重新登录 |
| 2001 | 资源不存在 | 检查资源ID |
| 3001 | 权限不足 | 申请权限 |
| 5000 | 系统错误 | 联系技术支持 |

## 3. 模块间数据共享标准

### 3.1 数据包标准格式

```json
{
    "id": "数据包唯一标识",
    "type": "数据类型",
    "source_module": "来源模块",
    "target_module": "目标模块（可选）",
    "version": "数据版本",
    "timestamp": "生成时间",
    "signature": "数据签名（可选）",
    "payload": {
        "key": "value"
    }
}
```

### 3.2 必填字段

| 字段 | 说明 | 验证规则 |
|-----|------|---------|
| id | 全局唯一标识 | UUID v4 |
| type | 数据类型 | 符合命名规范 |
| version | 数据格式版本 | 语义化版本 |
| timestamp | 时间戳 | ISO 8601 |

### 3.3 命名规范

| 类型 | 规范 | 示例 |
|-----|------|------|
| 模块名 | 小写+下划线 | user_auth |
| 数据类型 | 小写+下划线 | user_profile |
| 接口名 | 动词+名词 | get_user_info |
| 字段名 | 小写+下划线 | user_id |

## 4. 接口设计模板

### 4.1 请求接口

```
POST /api/v1/{module}/{resource}
```

### 4.2 响应接口

```
GET /api/v1/{module}/{resource}/{id}
```

## 5. 版本管理

- 接口版本号使用URL路径管理
- 主版本号变更需评估兼容性
- 建议保持向后兼容

## 6. 安全性要求

- 敏感数据必须加密传输
- 接口调用需携带认证Token
- 记录完整的调用日志


path: scripts/lock_module.sh
content: #!/bin/bash
# I漫剧APP开发技能 - 模块锁定脚本
# 用于锁定已确认的模块代码

set -e

MODULE_NAME=$1
LOCK_DIR=".locks"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")

if [ -z "$MODULE_NAME" ]; then
    echo "用法: bash lock_module.sh <模块名称>"
    exit 1
fi

# 创建锁定记录目录
mkdir -p "$LOCK_DIR"

# 创建锁定记录文件
LOCK_FILE="$LOCK_DIR/${MODULE_NAME}_${TIMESTAMP}.lock"

cat > "$LOCK_FILE" << EOF
{
    "module": "$MODULE_NAME",
    "locked_at": "$(date -Iseconds)",
    "locked_by": "${USER:-developer}",
    "status": "locked",
    "reason": "开发者确认通过"
}
EOF

# 创建符号链接指向最新锁定
ln -sf "$LOCK_FILE" "$LOCK_DIR/${MODULE_NAME}_latest.lock"

echo "✓ 模块 '$MODULE_NAME' 已锁定"
echo "  锁定记录: $LOCK_FILE"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)