From 631fce55b36ef7883591228ea4e9ec7004f94c9d Mon Sep 17 00:00:00 2001 From: "2570050763@qq.com" <2570050763@qq.com> Date: Thu, 17 Sep 2026 20:08:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E8=87=B3?= =?UTF-8?q?=20V1=20=E5=85=A8=E9=98=B6=E6=AE=B5=E5=AE=8C=E6=88=90=E5=B9=B6?= =?UTF-8?q?=E4=B8=8A=E7=BA=BF=E7=9A=84=E5=AE=9E=E9=99=85=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修正过时的“TTS/CMS 未接入”描述，补充 Phase 0-5 状态表 - 新增架构拓扑、目录结构、路由速查与本地开发命令 - 补全文档索引（Phase 5 报告、生产部署记录、部署/运维/验收等） --- README.md | 122 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 102 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 553b816..c5b5d73 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,104 @@ -# 考町科技官网暨 AI 工具平台 - -当前阶段：Phase 2 用户认证与权益基础已完成，TTS 生成和 CMS 尚未接入。 - -- [产品与技术规划（含分阶段工作清单）](docs/V1_PLAN.md) -- [Word 规划书](docs/考町科技官网暨AI工具平台_V1.1.docx) -- [局域网测试环境](docs/TEST_ENVIRONMENT.md) -- [Phase 0 现状审计](docs/AUDIT.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/来源限制后解除。 + +## 架构 + +```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/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/ASSETS.md) +- [局域网测试环境](docs/TEST_ENVIRONMENT.md) +- [品牌素材与设计参考清单](docs/ASSETS.md)