依据真实企业外包需求文档（28 项功能清单：Android 客户端 / Web 运营后台 / 配套服务端）搭建的端到端可运行原型：
- Android 客户端：原生 Kotlin，覆盖启动、瀑布流、下载设壁纸、会员与广告解锁、工单客服全流程；
- 后端服务：Python FastAPI + MySQL，24 张表、70+ 接口；
- Web 运营后台：壁纸 / 广告 / 商品 / 工单 / 发布 / 权限等 19 个管理模块。
本项目采用 AI 辅助编码方式开发，用途是在正式外包开发前做技术排雷与试错验证：用低成本原型把需求里"能不能做、怎么做好、有什么坑"提前验证清楚，把结论沉淀下来供业务方决策。
| 待验证问题 | 验证方式与结论 |
|---|---|
| 一键设壁纸能否用 uni-app 实现 | 验证 uni-app 无官方 API、plus.android 反射不可靠后，确定客户端采用原生 Kotlin，避免上线后返工 |
| nvue / HBuilderX 调试基座是否可用 | 复现 Vue3 + nvue 编译与白屏问题并定位根因，给出明确取舍结论 |
| 支付 / 短信 / 广告能否在本地联调 | 无平台账号也能跑通全流程：采用模拟通道 + 配置开关，下单 → 回调验签 → 幂等 → 权益发放逻辑全部真实落地，拿到甲方账号即可切真实 |
| 后端契约与数据安全 | 密码 PBKDF2 哈希存储、token 鉴权、支付幂等、操作日志、角色权限；沉淀"先备份再动库"等数据事故教训 |
| 上架合规顺序 | 客户端按"同意隐私政策后才进入主流程"设计，广告类 SDK 接入点后置，避免隐私合规返工 |
完整踩坑记录（现象 → 原因 → 规避方式，共 20 条）见 PITFALLS.md。
- 启动：隐私确认 → 远程配置拉取 → 维护检查 → 开屏广告（模拟）→ 首页
- 壁纸：真实后端内容的双列瀑布流（分页 / 下拉刷新）、标签展示、广告卡
- 下载：未登录强制登录 → 权益校验 → 存相册 → 一键设壁纸（桌面 / 锁屏目标选择）
- 会员与广告：会员门槛、看广告解锁（模拟激励）、商品选择 + 微信/支付宝（模拟支付）
- 账号：密码注册登录 + 验证码登录（模拟短信）；登录失败 / 任务中断自动恢复
- 个人页：会员状态、我的订单、问题反馈、在线客服（异步工单）、设置
- 账号体系：密码（PBKDF2）/ 验证码登录、token 鉴权
- 交易：商品、下单、支付回调（幂等）、权益自动发放
- 客服：工单创建 / 回复 / 转派 / 状态流转
- 配置与发布：客户端远程配置、版本发布 / 审批 / 回滚
- 运营数据：24 张表覆盖用户 / 会员 / 壁纸 / 标签 / 素材 / 首页 / 广告 / 商品 / 订单 / 权益 / 工单 / 权限 / 日志
- 工作台、内容管理（壁纸 / 素材 / 标签）、页面运营（首页版本 / 热度）、广告配置（版位 / 活动 / URL 白名单）、交易中心（商品 / 订单 / 权益）、用户与客服、发布管理、系统管理（账号 / 角色权限 / 配置 / 操作日志）
- 所有写操作留痕，权限按角色控制
Android 演示环境实拍（支付 / 短信 / 广告均为模拟通道，画面为本地联调数据；以下截图展示客户端核心功能闭环）。
| 场景 | 截图 |
|---|---|
| 开屏广告 |  |
| 瀑布流壁纸展示 |  |
| 一键设置壁纸 |  |
| 看广告 / 捆绑套餐 / 开通会员下载 |  |
| 问题反馈 |  |
- 客户端：Kotlin、Retrofit、Coil、Material Components、SwipeRefreshLayout
- 后端：Python、FastAPI、SQLAlchemy 2.0、PyMySQL
- 数据库：MySQL（本地独立实例）
- 运营后台：原生 HTML / CSS / JavaScript（由 FastAPI 直接托管，无独立前端工程）
.
├── app/ # Android 客户端（Kotlin）
├── backend/
│ ├── main.py # 后端入口（客户端接口 + 托管运营后台）
│ ├── admin.py # 运营后台接口
│ ├── models.py # 数据库模型（24 张表）
│ ├── static/admin/ # 运营后台前端页面
│ ├── tests/ # 冒烟测试（v1 回归 + v2 全链路）
│ ├── migrations/ # 数据库变更脚本
│ └── API_CONTRACT.md # 接口契约 / 数据库字典 / 错误码
└── server/ # 本地运行环境（不入库）
前置依赖：Python 3.9+、JDK 17、Android SDK；后端使用本机 MySQL 实例（见 backend/README.md，端口与账号可改 backend/config.py）。
# 1) 后端（自动建表并写入演示数据）
cd backend
.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8080
# 2) Web 运营后台（浏览器打开）
http://127.0.0.1:8080/admin
# 演示账号：admin / admin123（仅本地演示，上线前必须修改）
# 3) Android 客户端（模拟器）
./gradlew :app:assembleDebug
# 模拟器访问宿主机后端地址 http://10.0.2.2:8080/（真机需改用局域网 IP 或 USB 反向代理）
# 4) 后端测试
cd backend
.venv/bin/python tests/smoke_test.py # 原有接口回归
.venv/bin/python tests/smoke_test_v2.py # 新增全链路（验证码/订单/工单/后台）- 支付、短信、广告均为模拟通道：代码已预留接入点与配置开关（
MOCK_PAYMENT / MOCK_SMS / MOCK_AD），需平台账号后切换； - 壁纸为演示种子图，未接入版权素材与对象存储 / CDN；
- 微信小程序拉起需在开放平台配置 AppId 与签名（
WechatConfig.kt）； - 未实现壁纸裁剪与进程被杀后的下载任务恢复。
- 接口契约（数据库字典、错误码、模拟/真实切换说明）：
backend/API_CONTRACT.md - 技术排雷记录（选型验证、Android/后端/运营台踩坑与规避）：
PITFALLS.md - 内部开发记录与外包需求差距清单因含企业内部信息，不随本仓库公开。