本文档从项目起源到当前 v2.0 实现进行完整逆向梳理，包含架构分析、不稳定根因诊断、v3.0 高可用方案和迁移路线图。 共 10 章 + 2 附录，覆盖 18 张数据库表、40+ API 端点、全部业务规则。
1. 文档概要
编写目的：本 PRD 从项目第一天沟通到当前 v2.0 实现进行完整逆向梳理。全景回顾架构冻结、问题诊断、重构蓝图。
| 对比维度 | v2.0（当前） | v3.0（目标） |
|---|---|---|
| 架构 | FastAPI + 单机 | 公司高可用架构 |
| 数据库 | SQLite WAL | 待定 |
| 部署 | uvicorn --workers 4 | 高可用集群 |
| 监控 | 无 | Prometheus + 告警 |
| 容灾 | systemd 3s 重启 | 待定 |
2. 项目全历程时间线
Phase 0 概念期（2026-04 初）：老张提出"做一套客户经营的东西"。战略方向：「双向奔赴的智能体经济」。
Phase 1 client-journey 技能诞生（2026-04-05）：基于文件的客户关系管理，9 阶段（stranger → bonded → lost）。
Phase 2 支付与商业化的到来（2026-04 中旬）：引入 SQLite 数据库，建立订单/推荐/佣金体系。两级分销、33 天提现等待期、保证金模式 ¥599。
Phase 3 从 skill 演化为独立服务（2026-04-29）：拆分为独立项目。FastAPI + uvicorn --workers 4 + systemd + Nginx。
Phase 4 v2.0 实体模型升级（2026-05）：引入 person_id（unionId）解决跨企微应用 contactId 不统一问题。
3-4. 架构与组件
| 文件 | 行数 | 稳定性 |
|---|---|---|
| order_db.py | ~1200 | ⚠️ refund 逻辑冗余 |
| order_manager.py | ~1000 | ⚠️ 新旧混合 |
| app.py | ~960 | ⚠️ 页面与 API 混用 |
| jkzl_payment.py | ~400 | ✅ 稳定 |
| wechat_pay.py | ~200 | ⚠️ 证书未就绪 |
5-7. 数据模型与业务规则
18 张表：orders, referrals, commissions, payment_logs, user_accounts, account_transactions, deployments, trial_lifecycle, social_connections, client_journey, client_product_journey, referral_qualifications, persons, agents, wecom_accounts, person_wecom_relations, referral_relations, 资格变更历史
| 产品 | 月付 | 保证金 | 退款上限 | 直接佣金 |
|---|---|---|---|---|
| AI助手（个人版） | ¥599 | ¥599 | 满60人退¥600 | ¥120/月 |
| AI助手企业版 | ¥990 | ¥990 | 满99人退¥990 | ¥200/月 |
| 小薇健康管家 | ¥99/月 | ¥99 | — | ¥20/月 |
8. 已知问题与不稳定点
| 等级 | 问题 | 影响 |
|---|---|---|
| 🔴 严重 | SQLite 并发写锁 | 写冲突导致 500 |
| 🔴 严重 | 单点故障 | 单服务器全量不可用 |
| 🟡 中 | JKZL 回调字段未确认 | 支付回调兼容性风险 |
| 🟡 中 | 幂等性不足 | 重试导致订单状态异常 |
| 🟡 中 | 无监控告警 | 宕机不通知任何人 |
| 🟡 中 | systemd 路径错误 | 重启可能失败 |
9. v3.0 高可用架构方案
总体架构：负载均衡 → 无状态应用层（5 模块：order/account/social/journey/payment）→ 数据层（DB + 缓存 + 队列）→ 观测层
关键建议：当前数据量不大（orders ~200 条），可以先确保 HA 而非先迁移数据库。优先解决：单点故障 + 并发写锁 + 备份。
10. 迁移路线图
| Phase | 时间 | 核心任务 |
|---|---|---|
| Phase 1 止血 | 1-2 天 | SQLite 参数调优 + 自动备份 + 路径修复 + Nginx 上线 + 回调确认 |
| Phase 2 HA 迁移 | 1-2 周 | 容器化 + HA 对接 + 5 模块拆分 + OpenAPI 文档 |
| Phase 3 观测 | 1 周 | Prometheus + 告警 + 日志 + 幂等性 + 事务优化 |
| Phase 4 扩展 | 2-4 周 | SDK + 统一 payment + 结算自动化 + DB 迁移 |
版本：v3.0-draft | 生成：2026-05-26 | 用途：下一版本重构参考