2570050763@qq.com
631fce55b3
- 修正过时的“TTS/CMS 未接入”描述，补充 Phase 0-5 状态表 - 新增架构拓扑、目录结构、路由速查与本地开发命令 - 补全文档索引（Phase 5 报告、生产部署记录、部署/运维/验收等）
105 lines
5.9 KiB
Markdown
105 lines
5.9 KiB
Markdown
# 考町科技官网暨 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)
|