# 考町科技官网暨 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/来源限制后解除。

## 架构

```text
浏览器
 └─ 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/`

## 目录结构

```text
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 管理员 |

## 本地开发

```bash
# 官网
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（含分阶段工作清单）](docs/V1_PLAN.md)
- [Word 规划书](docs/考町科技官网暨AI工具平台_V1.1.docx)
- [Phase 0 现状审计](docs/AUDIT.md) · [技术决策](docs/DECISIONS.md) · [后续执行计划](docs/EXECUTION_PLAN.md)
- [TTS 接口契约](docs/API_CONTRACT.md)
- [阶段报告](docs/phase-1-report.md)：Phase 1 · [Phase 2](docs/phase-2-report.md) · [Phase 3](docs/phase-3-report.md) · [Phase 4 CMS 与管理](docs/phase-4-report.md) · [Phase 5 集成与上线准备](docs/phase-5-report.md)
- [生产部署记录](docs/production-deployment-2026-09-12.md)（09-10 / 09-11 / 09-12 共三份）
- [部署说明](docs/DEPLOYMENT.md) · [运维方案](docs/OPERATIONS.md) · [验收标准](docs/ACCEPTANCE.md)
- [短信验证配置](docs/sms-verification.md) · [CMS 管理员恢复](docs/cms-admin-recovery.md)
- [TTS 上游资料请求清单](docs/TTS_UPSTREAM_REQUEST.md)
- [局域网测试环境](docs/TEST_ENVIRONMENT.md)
- [品牌素材与设计参考清单](docs/ASSETS.md)