Kaotings/www_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: Kaotings:feat/chip-resources
Branches Tags
Kaotings:main
Kaotings:feat/chip-resources
...
pull from: Kaotings:main
Branches Tags
Kaotings:feat/chip-resources
Kaotings:main

1 Commits
feat/chip- ... main

Author SHA1 Message Date
2570050763@qq.com
631fce55b3 docs: 更新 README 至 V1 全阶段完成并上线的实际状态 
- 修正过时的“TTS/CMS 未接入”描述，补充 Phase 0-5 状态表
- 新增架构拓扑、目录结构、路由速查与本地开发命令
- 补全文档索引（Phase 5 报告、生产部署记录、部署/运维/验收等）
 2026-09-17 20:08:04 +08:00
1 changed files with 102 additions and 20 deletions
Show Stats Expand all files Collapse all files

112
README.md
View File

@ -1,22 +1,104 @@
# 考町科技官网暨 AI 工具平台
当前阶段：Phase 2 用户认证与权益基础已完成，TTS 生成和 CMS 尚未接入。
考町科技（KAOTINGS）公司官网 + AI 工具平台 V1。公司以蓝牙周边、音频及智能硬件为主业，官网承担品牌展示、产品介绍和客户联系；AI Lab 首个工具为文本转语音（TTS），提供从注册登录到生成、保存、回放、下载的完整闭环。
- [产品与技术规划（含分阶段工作清单）](docs/V1_PLAN.md)
## 当前状态
**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)
- [局域网测试环境](docs/TEST_ENVIRONMENT.md)
- [Phase 0 现状审计](docs/AUDIT.md)
- [Phase 0 现状审计](docs/AUDIT.md) · [技术决策](docs/DECISIONS.md) · [后续执行计划](docs/EXECUTION_PLAN.md)
- [TTS 接口契约](docs/API_CONTRACT.md)
- [技术决策](docs/DECISIONS.md)
- [后续执行计划](docs/EXECUTION_PLAN.md)
- [Phase 1 阶段报告](docs/phase-1-report.md)
- [Phase 2 阶段报告](docs/phase-2-report.md)
- [Phase 3 阶段报告](docs/phase-3-report.md)
- [Phase 4 CMS 阶段报告](docs/phase-4-report.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)
项目根目录：`E:\RD\Kaotings\www_site`，以本次新仓库为准。
实施从规划书 Phase 0 开始，先核实工程和测试环境，再按阶段推进。
- [局域网测试环境](docs/TEST_ENVIRONMENT.md)
- [品牌素材与设计参考清单](docs/ASSETS.md)