www_site/README.md

考町科技官网暨 AI 工具平台

考町科技（KAOTINGS）公司官网 + AI 工具平台 V1。公司以蓝牙周边、音频及智能硬件为主业，官网承担品牌展示、产品介绍和客户联系；AI Lab 首个工具为文本转语音（TTS），提供从注册登录到生成、保存、回放、下载的完整闭环。

当前状态

V1 全部 5 个阶段已完成并上线生产（域名 www.kaotings.com，测试/生产服务器 192.168.199.22，发布目录 /home/flym/releases/，发布与回滚记录见 docs/production-deployment-*.md）。

阶段	内容	状态
Phase 0	现状审计（docs/AUDIT.md、docs/DECISIONS.md）	✅ 完成
Phase 1	设计系统与官网骨架（首页、产品、关于、联系、TTS/账户界面）	✅ 完成
Phase 2	用户认证与权益基础（注册、登录、会话、Role/Plan、额度结构、验证抽象）	✅ 完成
Phase 3	TTS 产品闭环（任务持久化、额度冻结/结算、Worker、私有音频、历史回放下载）	✅ 完成
Phase 4	CMS（Payload）与业务管理后台（用户/VIP/额度/TTS/审计）	✅ 完成
Phase 5	集成验收、异常矩阵、备份恢复、部署与回滚说明	✅ 完成

已上线能力要点：

• 注册强制邮箱验证（腾讯企业邮 SMTP），图形验证码防爆破；短信验证（阿里云号码认证 PNVS）已实现、当前未启用，配置见 docs/sms-verification.md。
• TTS 上游地址与 API Key 支持管理后台配置（DB 优先于 env，保存前探测），任务采用幂等键 + 租约 + 超时恢复，结算保证额度不变式。
• CMS 独立库独立管理员，产品 draft/published/unpublished 状态流，官网产品列表经 CMS_PUBLIC_API_URL 拉取已发布内容（未配置时回退本地占位数据，仅限开发）。
• 已知阻断项：上游 TTS 服务仍走公网 HTTP（见 docs/phase-5-report.md §4），需上游提供 HTTPS/来源限制后解除。

架构

浏览器
 └─ Caddy（HTTPS :443，:80 跳转）
     ├─ /api/*   → FastAPI 业务 API（127.0.0.1:8000）
     │                ├─ PostgreSQL 业务库 kaotings（用户/会话/额度/TTS 任务）
     │                ├─ 进程内 asyncio Worker → 内部 TTS API → 私有音频目录
     │                └─ SMTP（邮箱验证码）/ 阿里云 PNVS（短信，未启用）
     ├─ /cms/*   → Payload CMS（127.0.0.1:3001，独立库 kaotings_cms）
     └─ 其余     → Next.js 官网（127.0.0.1:3000）

• 前端：Next.js 16 + React 19 + Tailwind CSS 4 + TypeScript（App Router）
• 业务 API：FastAPI + psycopg 3 + Argon2id + httpx（services/api/app/main.py）
• 内容管理：Payload CMS（apps/cms）
• 部署：Caddy 反代 + 3 个 systemd 服务（kaotings-web / kaotings-cms / kaotings-api）+ 发布目录软链切换，见 infra/

目录结构

app/            官网页面（/、/products、/tts、/login、/register、/account、/admin/*）
components/     共享组件（导航、页脚、认证表单、账户面板、admin/* 管理界面）
lib/            内容适配器（CMS 拉取/本地回退）、管理端 API 客户端
services/api/   FastAPI 业务 API（app/ 代码、migrations/ 迁移、tests/ 故障注入测试）
apps/cms/       Payload CMS 应用（collections/ 内容模型、migrations/）
infra/          Caddy 配置、systemd 单元、运维脚本（备份、告警、上游探测）
assets/brand/   正式品牌素材（使用规则见 docs/ASSETS.md）
docs/           规划、审计、契约、阶段报告、部署与运维文档

路由

路由	页面	访问要求
/、/products、/products/[slug]、/about、/contact	官网公开页	公开
/tts	TTS 工作台（生成/历史/回放/下载）	浏览公开，生成与历史须登录
/login、/register、/account	认证与账户中心	未登录 / 当前用户
/admin、/admin/users、/admin/tts	业务管理后台	role=admin
/cms/admin	CMS 内容管理	受控 CMS 管理员

本地开发

# 官网
npm install
npm run dev        # http://localhost:3000
npm run typecheck
npm run build      # 生产构建；生产环境需设 CMS_PUBLIC_API_URL

# 业务 API
cd services/api
pip install -r requirements.txt
cp .env.example .env   # 配置 DATABASE_URL、CSRF_SECRET 等
python -m app.migrate  # 执行 migrations/
# 受控初始化管理员（凭据只从进程环境变量注入，不覆盖已存在账户）：
#   ADMIN_EMAIL=... ADMIN_PASSWORD=... python -m app.init_admin
uvicorn app.main:app --host 127.0.0.1 --port 8000

# CMS（独立应用，默认端口 3001）
cd apps/cms
npm install
npm run dev

生产部署、发布/回滚流程见 docs/DEPLOYMENT.md，音频/数据库备份恢复与告警见 docs/OPERATIONS.md。

文档索引

• 产品与技术规划 V1.1（含分阶段工作清单）
• Word 规划书
• Phase 0 现状审计 · 技术决策 · 后续执行计划
• TTS 接口契约
• 阶段报告：Phase 1 · Phase 2 · Phase 3 · Phase 4 CMS 与管理 · Phase 5 集成与上线准备
• 生产部署记录（09-10 / 09-11 / 09-12 共三份）
• 部署说明 · 运维方案 · 验收标准
• 短信验证配置 · CMS 管理员恢复
• TTS 上游资料请求清单
• 局域网测试环境
• 品牌素材与设计参考清单