www_site/docs/V1_PLAN.md

# 考町科技官网暨 AI 工具平台 V1 产品与技术规划书

版本：V1.1  
日期：2026-09-08  
品牌：考町科技 / KAOTINGS  
项目根目录：`E:\RD\Kaotings\www_site`  
用途：产品范围确认、技术实施、阶段验收及 Codex 开发依据。

## 1. 文档基线与执行原则

本版将注册、登录、普通用户、VIP 用户、管理员、账户中心、TTS 历史和额度管理正式纳入 V1，取代此前将用户体系放到后续阶段的安排。官网定位、品牌风格、结构化 CMS、独立 TTS 工具、现有推理 API 复用、安全代理、部署边界及先审计后分阶段开发的方向继续保留。

来源说明：本文件依据《技术选型建议》原对话可读取的已确认规划及本次 V1.1 要求重建。原 V1.0 DOCX/Markdown 文件正文未能取得，故不宣称逐字保留或完成原文件逐项差异核对。本文对执行所需的状态机、接口、额度一致性等作了明确补充；未确认的参数在第 15 章列出。

### 1.1 强制约束

- 唯一项目根目录为 `E:\RD\Kaotings\www_site`；该路径为本次用户新建并指定的 Git 仓库，取代此前的 `kts_site` 路径约束；不从其他工程自动迁移或覆盖文件。
- 先审计当前目录、版本控制、已有页面和 TTS 接口，再确定新增及重构位置。现有子目录与业务资产不得因新目录建议被删除或强制重排。
- 官网首先展示蓝牙周边、音频与智能硬件；AI/TTS 属于 AI Lab。
- 保留已打通的 TTS 服务，由业务层适配调用；网站改造不包含推理模型重写。
- 用户 Role 与会员 Plan 必须分离：`role=user/admin`，`plan=free/vip`。禁止设计 `role=vip`。
- V1 必须交付可用用户闭环，不能以预留字段或静态界面替代注册、登录、历史、额度和管理功能。
- 本文中的路径与接口是目标规划；现状、版本及性能均需审计和测试确认，不视为已有实现。

### 1.2 V1.1 变更映射

| 项目 | V1.1 要求 | 对应章节 |
| --- | --- | --- |
| 用户体系 | 注册、登录、退出、账户状态与个人中心 | 3、5、6 |
| 权限与会员 | Role/Plan 分离，VIP 生效与到期 | 5、8 |
| 验证扩展 | 邮箱和手机验证字段、挑战流程与服务适配 | 6、8、9 |
| TTS 用户闭环 | 任务归属、历史、再次播放、下载、额度 | 8、10 |
| 管理后台 | 用户、套餐状态、额度、任务和使用量 | 5、9 |
| 工程交付 | 认证优先于 TTS 正式接入，新增安全与一致性验收 | 13、14 |

## 2. 产品定位与目标

考町科技首先是一家蓝牙周边、音频及智能硬件技术公司。官网承担品牌展示、产品介绍、技术能力表达和客户联系；AI 工具平台承载可实际使用的在线能力，V1 从文本转语音开始。

首页应使访客迅速理解公司做什么、有哪些产品、如何联系；TTS 工具应使用户完成从注册登录到生成、保存、回放和下载的完整流程；后台应使运营人员独立维护产品内容和基础用户权益。

V1 的完成目标是“公司官网可展示、产品内容可维护、TTS 可使用、用户数据有归属、权限和成本可控制、系统可部署维护”。不以页面数量或装饰复杂度作为完成标准。

## 3. V1 范围与信息架构

### 3.1 正式交付范围

| 模块 | V1 必须交付 |
| --- | --- |
| 官网 | 首页、产品中心、产品详情、技术能力展示、关于我们、联系我们、基础 SEO、响应式布局 |
| CMS | 产品、媒体、公司信息、联系方式、首页精选、SEO；草稿、预览、发布、下架、排序 |
| AI Lab | 首页轻量入口；TTS 独立工作台；未来工具入口结构可扩展 |
| 认证 | 注册、登录、退出、密码安全存储、会话、账户启停、验证状态预留 |
| 账户 | 基本资料、验证状态、会员状态、有效期、额度、TTS 历史入口 |
| TTS | 文本、字数、音色、支持的参数、提交状态、错误恢复、历史、回放、下载、额度 |
| 管理 | 用户查询与禁用、VIP 设置与到期、额度调整、TTS 任务及使用统计、操作审计 |
| 平台 | HTTPS、安全代理、限流、私有音频存储、数据库迁移、备份、日志与部署说明 |

### 3.2 页面与路由

| 路由 | 页面用途 | 访问要求 |
| --- | --- | --- |
| `/` | 公司首页，产品为主体，AI Lab 轻量入口 | 公开 |
| `/products` | 产品分类、列表与精选 | 公开；只展示已发布内容 |
| `/products/[slug]` | 统一模板产品详情 | 公开；草稿仅授权预览 |
| `/#technology` | Bluetooth、Audio、Embedded、AI 技术说明 | V1 默认首页锚点 |
| `/about` | 公司介绍与能力 | 公开 |
| `/contact` | 正式联系方式 | 公开 |
| `/tts` | 文本转语音工作台 | 可浏览；生成、历史、音频访问须登录 |
| `/login` | 邮箱与密码登录 | 未登录用户 |
| `/register` | 邮箱与密码注册 | 未登录用户 |
| `/account` | 资料、会员、额度、历史 | 当前登录用户 |
| `/admin` | 业务管理入口 | role=admin |
| `/admin/users` | 用户与会员、额度管理 | role=admin |
| `/admin/tts` | TTS 任务、使用与失败情况 | role=admin |
| `/cms` | 内容管理后台，具体挂载方式由审计确定 | 获授权 CMS 管理员 |

AI Lab 在 V1 可直接连接 `/tts`，无需为单个工具强制增加空的聚合页。新闻、案例、招聘、解决方案独立栏目、第三方登录、在线支付、自动订阅续费、开放 API Key、多租户、复杂权限系统、自由拖拽建站、Kubernetes 和复杂 GPU 调度不列入 V1 必交付。保留后续扩展位置，不构建空壳功能。

普通用户账户并非后续功能。邮箱验证码、手机短信验证的真实发送渠道与强制验证可后置；手机号登录、短信登录及自助忘记密码流程在渠道接入后启用，不能显示虚假的发送成功。

## 4. 品牌与视觉设计规范

### 4.1 品牌基准

素材已入库：正式 Logo 原档位于 `assets/brand/source/`；品牌规范参考为 `docs/design/references/kaotings-brand-guidelines.png`；当前首页视觉基准为 `docs/design/references/kaotings-homepage-approved-reference.png`。完整来源与使用规则见 `docs/ASSETS.md`。此前最终改色稿未取得的缺口已解除；历史 Nexora 紫色稿仅作过程归档。

品牌参考图明确标注：橙 `#FF6A00`、蓝 `#1677FF`、青 `#00D1E6`、白 `#F5F7FA`、深灰 `#1A1D21`、极暗背景 `#0D0F12`。作为 UI 设计变量基线；正式 Logo 保留原档颜色，不因 UI 色值而重新着色。图中的产品及文案为视觉示意，真实产品资料另行核实。按规划实现功能，不自动加入效果图中的搜索或轮播；不以整张截图替代真实网页。


使用考町科技 / KAOTINGS 的正式 Logo 和橙、蓝、青品牌体系。最终视觉以原讨论中第四版改色方向为基准：深色、克制、大留白、产品导向。采用 Linear 式层级与节奏原则，形成自己的品牌表达。历史示例中的 Nexora、紫色主视觉和以 TTS 为首页主体的方案不作为本版内容。

| 设计项 | 实施要求 |
| --- | --- |
| 背景 | 近黑与深灰分层，以参考图 #0D0F12 为页面背景基线；避免满页渐变 |
| 正文 | 近白主文字、清晰灰色辅助文字；实际对比度需验证 |
| 品牌橙 | 主要品牌强调和关键行动；少量使用 |
| 品牌蓝 | 技术信息、链接与交互反馈 |
| 品牌青 | AI Lab 或辅助状态点缀；避免与蓝、橙同时争抢视觉 |
| 精确色值 | 采用本节列出的参考图标注色值；Logo 保留原档填色，区分 UI 规范与原档颜色 |
| 产品图 | 真实、干净的产品静物图；不依赖烟雾、山石和夸张灯光 |
| 组件 | 共用字体、按钮、圆角、间距、边框、图标和焦点样式 |
| 动效 | 轻量反馈；尊重减少动效设置；不阻碍阅读和操作 |

### 4.2 页面节奏

首页顺序为：导航 → 公司主张和一件代表产品 → 精选产品 → 简洁技术能力 → AI Lab / Text to Speech 入口 → 公司简介与联系 → 页脚。每屏突出一个重点，产品数量少时正常留白，不虚构统计、客户、认证、新闻或产品。

首页不放完整 TTS 文本框、参数面板和播放器，不采用商城式密集产品卡墙。导航的登录或账户入口保持轻量。公司主张可暂用“连接技术与日常。”，正式上线文案与真实产品资料一起确认。

TTS 页面沿用品牌，但提高信息密度：桌面端文本与参数分区，结果和历史清晰呈现；移动端按输入、参数、生成、播放、历史依次排列。所有页面包含加载、空状态、错误、禁用和键盘焦点状态，不能仅用颜色表示成功或失败。

## 5. 用户、会员与管理员能力

### 5.1 Role 与 Plan

Role 决定管理权限；Plan 决定 TTS 权益。普通用户为 `role=user, plan=free`；VIP 用户为 `role=user, plan=vip`；管理员为 `role=admin, plan=free/vip`。管理员身份不隐含无限额度或自动 VIP。

| 能力 | 普通用户 | VIP 用户 | 管理员 |
| --- | --- | --- | --- |
| 浏览官网与产品 | 支持 | 支持 | 支持 |
| TTS 生成与自己历史 | 按 free 权益 | 按 vip 权益 | 按自身 Plan 权益 |
| 自己音频回放、下载 | 支持 | 支持 | 支持 |
| 查看自己额度和套餐 | 支持 | 支持 | 支持 |
| 查看其他用户基础信息 | 不允许 | 不允许 | 允许，敏感字段按需脱敏 |
| 禁用用户、调整套餐和额度 | 不允许 | 不允许 | 允许并记录审计 |
| 查看全站任务和使用统计 | 不允许 | 不允许 | 允许 |
| CMS 内容编辑发布 | 不允许 | 不允许 | 需获 CMS 后台授权 |

VIP V1 由管理员人工授予与撤销，支持生效时间、到期时间和原因。到期后恢复 free 有效权益，历史记录保持可查；新任务按提交时生效权益判断。管理员修改套餐不得直接篡改既有消费记录。

### 5.2 账户中心

账户中心展示邮箱、手机号（可为空）、验证状态、账号状态、会员等级、有效期、额度周期、已用、冻结和剩余额度，并提供退出和 TTS 历史入口。修改密码应校验当前密码并撤销其他会话。

第一阶段未接通验证渠道时，邮箱/手机号保持未验证状态，页面如实说明。未经证明的新联系方式不能用作找回密码或敏感操作凭据；联系方式变更及找回密码应待验证渠道完成后开放。

### 5.3 管理后台

- 用户管理：分页、按邮箱/手机号/状态筛选、查看注册和最近登录时间、禁用与恢复。
- 会员管理：查看有效 Plan、授予或撤销 VIP、设置有效期、记录原因和操作者。
- 额度管理：查看周期与流水、增加或减少可用额度；修改必须事务化且记录调整原因，不能造成负可用额度。
- TTS 管理：按用户、状态、时间筛选任务；查看音色、计量、耗时、错误码、任务重试和结算状态；默认不展开完整输入文本。
- 使用统计：任务数、成功/失败数、计量消耗及用户维度汇总；统计来自服务端记录。
- 管理安全：不能禁用或降级最后一个可用管理员；角色变更必须审计。初始管理员由受控初始化建立，注册接口不得接受 admin 权限。

## 6. 注册、登录与认证安全

### 6.1 V1 可用流程

注册：输入邮箱与密码 → 服务端规范化邮箱并校验格式、密码和唯一性 → 建立 active 用户，role=user、plan=free、验证字段为 false → 建立默认额度账户 → 跳转登录 → 登录后进入原目标页面或 `/account`。

登录：校验账号、密码、状态及限流 → 建立可撤销会话 → 更新 last_login_at → 返回当前用户公开资料。密码错误和账号不存在使用统一失败提示。禁用账户不得新登录；已登录账户在下一次受保护请求时失效。

密码采用成熟库进行自适应加盐哈希，实施基线选用 Argon2id；具体成本经部署环境测试确定。密码原文、password_hash、会话令牌与验证码不得进入 API 响应、日志或 CMS。

默认使用服务端可撤销的不透明会话，浏览器通过 Secure、HttpOnly、SameSite Cookie 持有会话标识；服务端保存令牌摘要、过期和撤销信息。全站 HTTPS；Cookie 设置明确 Path、有效期和范围，避免跨子域泛发。退出撤销当前会话，修改密码撤销其他会话。

对于 Cookie 认证的写操作，落实 CSRF 防护和 Origin 校验；服务端逐接口校验权限、账号状态及资源归属。页面隐藏按钮不构成授权。登录后跳转仅接受站内允许路径，防止开放重定向。

### 6.2 邮箱与短信验证预留

抽象 VerificationService 与 EmailSender/SmsSender，统一支持 purpose、channel、目标联系方式、用户或注册上下文、过期时间、尝试次数、发送频率和一次性消费状态。

后续验证流程：请求发送 → 校验频率和用途 → 建立短期挑战 → 发送渠道实际成功后返回通用受理结果 → 提交验证码 → 校验摘要、有效期、次数和绑定目标 → 原子消费 → 更新对应 verified 字段。验证码只存摘要；短验证码应采用带服务端密钥的摘要方案，避免离线穷举。重发使旧挑战失效。

用途区分注册验证、绑定联系方式、修改联系方式、找回密码；不同用途和目标的验证码不能互用。设置 `EMAIL_VERIFICATION_REQUIRED`、`PHONE_VERIFICATION_REQUIRED` 及发送渠道开关，默认第一阶段均不强制验证。渠道未配置时接口返回明确的功能未启用状态，不生成假验证成功结果；未来开启强制验证时提供存量账户补验流程。

### 6.3 防滥用要求

注册、登录、验证码、TTS 提交分别实施 IP 与用户/标识维度限流。未验证用户也必须受额度、文本长度、并发和频率约束。错误提示不泄露系统内部细节；秘密配置只在服务端注入。生产环境不启用公开调试接口。

## 7. 技术架构与模块边界

延续原规划的技术方向：Next.js + TypeScript + Tailwind 构建网站；Payload CMS 管理内容；FastAPI 承担用户、权益、任务、限流和 TTS 代理；PostgreSQL 持久化；Redis 支撑限流及轻量任务协调；MinIO 或 S3 兼容存储保存音频；继续调用现有 TTS API。具体版本在 Phase 0 审计后固定，本文不假定当前仓库已具备这些组件。

```text
浏览器
  └─ HTTPS → 反向代理 / 同源入口
       ├─ 官网页面、/tts、/account → Next.js
       ├─ /api/v1/* → FastAPI 业务层
       │    ├─ PostgreSQL：账户、权益、任务、额度流水
       │    ├─ Redis：限流、任务协调
       │    └─ Worker → 内部现有 TTS API → 私有音频存储
       └─ /cms → Payload CMS → 独立内容 schema/database
```

官网与 CMS 可在同一代码仓库并部署；业务身份由 FastAPI 统一负责，避免 Next.js 与 FastAPI 各自维护一套用户与额度规则。Next.js 如设置 BFF，仅转发或服务页面，不重复计费与权限决策。

CMS 管内容，程序控制设计。CMS 与业务库可以共用 PostgreSQL 实例，但分 schema/database 与数据库账号，各自负责迁移。CMS 后台使用独立管理会话且仅开放给受控管理员；不得让普通用户注册自动获得 CMS 编辑权限。后续如做统一登录，应单独实现身份映射，不能共享明文密码或直接绕过 CMS 授权。

V1 任务采用持久化任务表加轻量 Worker；Redis 可用于队列通知，数据库任务记录为恢复依据。不在 Web 请求进程里运行不可恢复的长时任务；服务重启后可找回待处理和超时任务。

## 8. 数据模型

以下为逻辑模型。主键统一使用 UUID 或等效不可预测标识；时间使用 UTC 存储并明确展示时区。金额、自动支付与完整订阅订单模型不在 V1 实现范围。

### 8.1 User 与认证模型

| User 字段 | 类型/约束 | 用途 |
| --- | --- | --- |
| id | UUID，主键 | 用户标识 |
| email | 可空、规范化后唯一；V1 注册必填 | 邮箱登录；为后续手机注册允许空值 |
| phone | 可空、规范化后唯一 | 预留手机号；统一国际号码格式 |
| password_hash | 非空字符串，V1 密码账户必需 | 密码哈希；未来无密码账户另设约束 |
| role | enum user/admin，默认 user | 管理权限 |
| plan | enum free/vip，默认 free | 当前会员配置，服务端维护 |
| status | enum active/disabled，默认 active | 账户使用状态 |
| email_verified | boolean，默认 false | 邮箱验证状态 |
| phone_verified | boolean，默认 false | 手机验证状态 |
| created_at | UTC timestamp，非空 | 注册时间 |
| updated_at | UTC timestamp，非空 | 修改时间 |
| last_login_at | UTC timestamp，可空 | 最近成功登录时间 |

约束：至少存在 email 或 phone；空字符串转换为空值；采用明确的邮箱规范化规则且不随意删除加号别名或点号；唯一性由数据库保证。verified=true 必须对应当前联系方式的有效验证结果。客户端提交的 role、plan、status、verified 字段一律不能通过注册或普通资料接口写入。

Session：id、user_id、token_hash、created_at、expires_at、revoked_at、last_seen_at，必要时保存脱敏设备信息。VerificationChallenge：id、user_id（可空）、channel、purpose、target、code_digest、expires_at、attempt_count、consumed_at、created_at。

### 8.2 会员、额度与审计

| 实体 | 核心字段 | 规则 |
| --- | --- | --- |
| PlanPolicy | code=free/vip、period_limit、max_text_length、max_concurrency、rate_limit、allowed_voices、version | 权益配置版本化，具体值上线前确定 |
| MembershipGrant | id、user_id、plan、starts_at、expires_at、revoked_at、created_by、reason | V1 人工会员记录；不允许重叠生效的 VIP 授权 |
| QuotaAccount | id、user_id、period_start/end、limit_snapshot、adjustment、used、reserved、version | 每用户每周期唯一；余额事务化更新 |
| UsageRecord | id、user_id、task_id、quota_account_id、type、amount、idempotency_key、created_at | 类型 reserve/consume/release/adjust；流水不可覆盖 |
| AdminAuditLog | id、actor_id、action、target_type/id、before/after、reason、created_at | 套餐、权限、禁用、额度调整留痕；不写秘密 |

User.plan 由会员服务维护；读取有效权益时同时检查授权生效、撤销与过期，定时任务同步缓存字段，不能仅信任过时 plan 值。普通注册不得创建 VIP 授权。

默认计量为提交文本的 Unicode 码点数，空白和标点计入，先规范化换行、不做暗中截断；若现有服务另有计量要求，在 Phase 0 固化计量函数并让前后端共用口径。额度周期默认 UTC 自然月；界面显示明确起止时间。

可用额度 = 周期基础额度 + 管理调整 − 已用 − 冻结。接收任务时原子冻结，音频成功持久化后转为消费，失败时释放。重新播放、下载不扣生成额度。任务跨周期完成时结算回原冻结周期。套餐切换由服务重新计算当前周期上限并记录差额，保留已用和冻结；降级后的新增可用额度最低为零，不追回已完成任务。

### 8.3 TTS 数据模型

| 实体 | 核心字段 |
| --- | --- |
| TTSVoice | id、provider_voice_id、name、language、description、enabled、supported_parameters、allowed_plans |
| TTSTask | id、user_id、text、text_length、voice_id、parameters、status、provider_task_id、idempotency_key、request_hash、policy_version、quota_account_id、reserved_amount、error_code、attempt_count、created_at、started_at、finished_at |
| AudioFile | id、task_id、owner_id、storage_key、mime_type、size_bytes、duration_ms、checksum、created_at、expires_at、status |

关系：User 一对多 MembershipGrant、Session、QuotaAccount、TTSTask；TTSTask 关联 UsageRecord 与 AudioFile；AudioFile 的 owner_id 必须与任务 user_id 一致。历史按 user_id + created_at 索引查询，任务扫描按 status + updated_at 建索引；同用户 idempotency_key 唯一。

原始文本和音频属于用户私有数据，业务日志默认只记录长度与任务 ID。保存期限配置化，在 UI 显示；音频过期时保留必要任务元信息并明确标记无法回放。V1 默认不对普通用户开放跨账户资源访问。

### 8.4 CMS 内容模型

Product：id、name、slug（唯一）、category、summary、description、cover、gallery、features、specs、applications、faq、cta、seo_title、seo_description、status、sort_order、featured、published_at、created_at、updated_at。

SiteSettings：品牌名称、Logo 深浅底版本、导航、页脚、联系方式、公司介绍与基础 SEO。HomeContent：公司主张、说明、精选产品、技术能力及 AI Lab 文案。Media：文件、类型、尺寸、替代文本和用途。News/Case 保留未来模型方向，不强制建设空栏目。

产品模板顺序：Hero → 产品介绍 → 核心优势 → 规格 → 应用场景 → 图片/视频 → FAQ → CTA。字段可选时隐藏空模块；运营编辑内容而非任意 HTML 或布局代码。

## 9. 业务 API 与安全代理

对外统一前缀 `/api/v1`，默认同源访问。以下为目标契约，现有推理服务接口由适配层映射；不要求底层 TTS 改名或重写。

| 方法与路径 | 功能 | 授权 |
| --- | --- | --- |
| POST `/auth/register` | 邮箱密码注册 | 公开、限流 |
| POST `/auth/login` | 登录并设置 Cookie | 公开、限流 |
| POST `/auth/logout` | 撤销会话 | 当前用户 |
| GET `/auth/me` | 当前用户公开资料 | 当前用户 |
| POST `/auth/password/change` | 校验旧密码后改密 | 当前用户 |
| POST `/auth/verification/send` | 验证挑战发送预留 | 按用途与开关控制 |
| POST `/auth/verification/confirm` | 一次性验证 | 按用途与开关控制 |
| GET `/account/usage` | 周期、已用、冻结、剩余 | 当前用户 |
| GET `/tts/voices` | 可用音色和参数 | 可公开安全元数据 |
| POST `/tts/tasks` | 创建任务，返回 202 与 task_id | 登录、限流、额度与并发校验 |
| GET `/tts/tasks` | 当前用户分页历史 | 当前用户 |
| GET `/tts/tasks/{id}` | 状态与结果元数据 | 任务所有者或授权管理员 |
| GET `/tts/tasks/{id}/audio` | 受控播放或短期签名地址 | 同上 |
| GET `/tts/tasks/{id}/download` | 受控下载 | 同上 |
| GET `/admin/users` | 用户分页查询 | admin |
| PATCH `/admin/users/{id}/status` | 禁用/恢复 | admin，审计 |
| PUT `/admin/users/{id}/membership` | 设置/撤销 VIP | admin，审计 |
| POST `/admin/users/{id}/quota-adjustments` | 幂等额度调整 | admin，审计 |
| GET `/admin/tts/tasks` | 全站任务查询 | admin |
| GET `/admin/usage` | 使用统计 | admin |

所有响应只包含所需字段；失败统一包含 error.code、message、request_id。至少区分未登录、无权限、账号禁用、参数错误、额度不足、限流、上游不可用、任务失败和音频过期。HTTP 状态语义明确；限流返回重试提示。

代理仅允许配置中的 TTS 主机与端点，禁止把用户传入 URL 作为请求目标。限制文本长度、音色和参数范围、响应大小及超时。上游密钥、内部地址、模型路径和堆栈不返回浏览器。服务间使用独立凭据；跨机器通过受控私网或加密通道访问。

## 10. TTS 完整业务流程

1. 用户浏览 `/tts`，未登录时可查看说明和界面；点击生成进入登录，文本草稿如需暂存应明确只在本机短期保留。
2. 登录后拉取有效 Plan、额度、音色和参数范围，展示文本计数及本次预计消耗。
3. 提交文本、音色、参数与幂等键。服务端重新校验用户状态、资源权益、长度、频率与并发。
4. 在数据库事务中建立 queued 任务并冻结额度，再通知 Worker；事务失败不派发任务。
5. Worker 原子领取任务、写入运行租约，调用内部 TTS API。浏览器通过轮询任务状态获知排队或生成进度。
6. 成功后校验音频并写入私有存储，登记 AudioFile；在事务内将任务置为 succeeded，并将冻结转为实际消费。
7. 返回结果元信息；用户可立即播放或下载。刷新页面后仍能从历史定位任务，历史支持分页和状态显示。
8. 失败则记明确错误码并释放冻结额度；前端保留输入以便用户新建任务重试。再次生成属于新任务并重新计量。

### 10.1 状态与一致性

任务状态为 queued → running → succeeded/failed。上游超时但是否生成成功不明时，暂处 running 并标记待核对，先按 provider_task_id 查询；超过处理期限后终结失败并释放。终结后收到的迟到结果不得再次扣费，按清理策略处理孤立音频。

同幂等键和同请求返回原任务；同键不同请求返回冲突。Worker 重复投递、响应丢失与进程重启均不得重复结算。上游不支持幂等时，不能无条件自动重试不确定的生成请求。设置最大重试次数、运行租约和对账任务，发现过期冻结需根据真实任务状态处理。

音频对象采用私有桶和不可预测的 storage_key。回放和下载首先校验身份与归属；可由业务层流式输出，或签发短期 URL。对象过期或删除时给出可理解提示，不能暴露内部路径。再次播放与下载原音频不触发推理和额度扣减。

## 11. CMS 发布、SEO 与内容维护

CMS 必须实现新增产品、上传媒体、填写结构化内容、草稿预览、发布和下架。发布后刷新或失效对应缓存，使列表与详情按一致状态展示；下架内容不得继续通过公共内容 API 或站点地图泄露，草稿预览凭据短期有效。

官网具备页面 title、description、语义化标题、图片 alt、canonical、sitemap、robots 与友好 404。用户账户、TTS 历史、管理后台和预览页面不被索引，也不能仅靠 robots 保护隐私。

媒体上传限制文件类型、尺寸和大小，校验实际内容；富文本按允许规则渲染并防止脚本注入。CMS 只保存内容配置，不允许上传执行代码。联系方式以已确认内容为准；V1 可直接展示电话、邮箱等，无需为占位联系表单引入不必要后端。

## 12. 部署与运维

### 12.1 网络与服务

以单站点、少量服务为 V1 部署起点，使用可复现容器配置或等效进程管理。反向代理可采用 Nginx 或 Caddy，Phase 0 结合现有环境固定其一。公网应用入口仅 80/443，80 跳转 HTTPS；运维入口另行限制来源。

TTS 原服务端口保留内部使用，不面向公网。数据库、Redis、Worker、对象存储管理端和内部 TTS 均位于受限网络。同机可绑定回环地址；跨机只接受指定业务端访问。不能用“换一个子域名”代替真正关闭裸端口。

### 12.2 配置与存储

分别管理开发、测试、生产配置。配置至少覆盖数据库、Redis、TTS 内部地址和凭据、对象存储、会话有效期、限流、PlanPolicy、任务超时、音频保留期、邮件/短信开关。提供不含秘密的示例配置，生产密钥不得提交 Git 或带入前端构建。

数据库和音频使用持久卷或外部服务，不能依赖容器临时目录。备份包含业务库、CMS 库和必要对象文件；形成备份保留与恢复演练记录。部署前执行兼容迁移并备份，回滚需同时考虑数据库结构，禁止直接运行破坏性降级。

### 12.3 监控与故障处理

监控网站与 API 健康、任务排队/耗时/失败率、上游可用性、数据库与存储空间、额度冻结异常、登录失败和限流。统一 request_id/task_id 关联日志，不记录密码、令牌、验证码和完整用户文本。

关闭 TTS 公网裸端口前先验证业务代理联通，并安排切换窗口；验证外网无法绕过业务鉴权调用推理服务。准备应用回滚、任务恢复、额度对账和存储恢复操作说明。

## 13. 项目组织与开发阶段

### 13.1 目录规划

```text
E:\RD\Kaotings\www_site
├─ apps/web/            官网页面、TTS、账户和管理界面（建议）
├─ services/api/        用户、权益、任务与代理（建议）
├─ services/worker/     任务执行（可与 API 共享包）
├─ packages/            共用类型与设计规范（按需）
├─ infra/               部署、反向代理、示例配置
└─ docs/
   ├─ V1_PLAN.md
   ├─ AUDIT.md
   ├─ API_CONTRACT.md
   └─ DEPLOYMENT.md
```

以上为逻辑组织建议，不是立即移动现有文件的命令。本次已核实新仓库根目录仅有 `.git`，尚无提交和业务代码。此前在 `kts_site` 下发现的 `KT26-0903_Big-TTS` 不属于本仓库，不自动复制；现有推理服务通过接口接入。

### 13.2 阶段、产物与完成条件

| 阶段 | 工作与交付物 | 完成条件 |
| --- | --- | --- |
| Phase 0 现状审计 | 检查项目规则、Git、目录、框架、页面、依赖、TTS API、部署和品牌素材；输出 AUDIT.md、保留/新增/重构清单及接口事实 | 明确真实代码位置、已有能力和缺口；不在本阶段改业务代码 |
| Phase 1 视觉与官网骨架 | 设计变量、导航页脚、首页、产品模板、关于和联系、TTS 与账户界面结构 | 桌面/移动端层级清晰，品牌和产品主次符合第 4 章 |
| Phase 2 账户与权益基础 | 业务库迁移、注册登录退出、会话、Role/Plan、账户页、额度结构、验证服务抽象 | 用户闭环可用；越权与禁用生效；未配置验证渠道不伪造验证 |
| Phase 3 TTS 产品闭环 | 现有 API 适配、Worker、任务持久化、额度冻结结算、私有音频、历史回放下载、代理安全 | 完成正常与失败流程；重复请求和重启不重复扣费 |
| Phase 4 CMS 与基础管理 | 产品编辑发布、缓存刷新、媒体、用户管理、VIP 与额度调整、TTS 查看、审计 | 运营可新增发布产品；管理员可完成本版基础管理操作 |
| Phase 5 集成与上线准备 | 安全检查、真实上游联调、响应式与可访问性、备份恢复、部署和回滚说明、验收记录 | 第 14 章必需项通过；实际上线按项目发布安排执行 |

测试环境已由用户建立：局域网虚拟机 `192.168.199.22`，登录用户名 `flym`。系统、资源、SSH 连通性及依赖尚待实测。访问密码不写入仓库、文档或示例配置。开发根目录为 Windows 新仓库，服务器部署目录在环境审计后确定。

测试环境从 Phase 1 开始持续部署验证：Phase 0 核实服务器系统、资源、网络、现有服务和部署条件；Phase 1 部署官网骨架并确定固定访问入口；Phase 2–4 每阶段更新测试版本，使用独立测试数据与秘密配置；Phase 5 执行完整部署、恢复与发布演练。测试认证流程前配置可信 HTTPS。服务器就绪不等于项目已部署，部署结果必须实际验证。

每阶段汇报完成项、验证结果、剩余问题和下一阶段范围。不得用 Mock 成功替代真实 TTS 联调，不得因开发顺序将用户系统和 CMS 从 V1 交付中移除。以下工作包为阶段执行清单；上表用于总览。

### 13.3 Phase 0：现状审计与实施基线

进入条件：能够读取项目根目录。此阶段只读取工程并输出文档，不修改业务代码、不移动现有目录、不更改线上服务。

| 编号 | 具体工作 | 交付与完成判定 |
| --- | --- | --- |
| P0-01 | 读取项目规则，检查 Git 根、分支、未提交变更、目录和已有启动说明；确认现有 TTS 服务的接入边界 | AUDIT.md 记录真实路径及现状，区分网站、业务层与推理服务 |
| P0-02 | 检查框架、依赖、页面、组件、接口、配置与持久化；列出可复用资产和缺口 | 每项标记保留、新增或重构，不凭规划推断已有功能 |
| P0-03 | 核对现有 TTS 文档或实现，记录请求/响应、音色、参数、鉴权、同步或异步、超时和幂等支持 | API_CONTRACT.md 包含脱敏样例、失败语义和适配边界；真实调用测试移至获授权的联调环境 |
| P0-04 | 盘点 Logo、第四版改色稿、产品图与文案；确认域名、部署拓扑和当前裸端口情况 | 素材清单及网络现状图；未取得素材明确列为缺口 |
| P0-05 | 固定目录落点、兼容版本、数据归属、会话方案、任务方案、CMS 挂载方式 | DECISIONS.md 记录选择、依据与限制，明确迁移负责人模块 |
| P0-06 | 列出额度、并发、超时、保留期等配置和实施依赖 | EXECUTION_PLAN.md 按本文工作编号建立待办，产品未定值单独列出 |

退出条件：能够说明每个模块在哪里实现、复用什么、接什么接口、如何验证；影响后续工作的缺口已有明确处理办法。缺少真实产品素材不阻止账户基础开发，但不允许将占位素材视为上线内容。工期在审计后按实际缺口估算，本文不预设未经评估的天数。

### 13.4 Phase 1：设计系统与官网页面

进入条件：Phase 0 的工程落点与素材基线明确。

| 编号 | 具体工作 | 交付与完成判定 |
| --- | --- | --- |
| P1-01 | 建立品牌色、灰阶、字体、间距、按钮、输入框、焦点和响应式变量 | 共享样式及基础组件，颜色来源可追溯 |
| P1-02 | 实现导航、页脚、移动导航、登录/账户入口及通用页面容器 | 所有目标页面可导航，无断链和横向溢出 |
| P1-03 | 实现首页 Hero、精选产品、技术能力、AI Lab 入口及公司联系区 | 蓝牙与硬件是视觉主体，首页不嵌完整 TTS 工作台 |
| P1-04 | 实现产品列表、产品详情模板、关于和联系页面 | 结构化数据驱动；可用本地数据适配器，Phase 4 切换 CMS 时不重写布局 |
| P1-05 | 实现 TTS、登录、注册、账户和管理页面的布局与状态组件 | 明确区分视觉预览与真实功能；注册和生成不能假成功 |
| P1-06 | 完成公开页基础 SEO、404、键盘操作和移动端检查 | 页面标题、层级与主要交互通过检查，形成页面截图和检查记录 |

交付物：可运行官网骨架、共享组件、产品模板、页面预览及 docs/phase-1-report.md。退出条件：公开页面和视觉规范可复用；动态认证、生成与后台业务仍须分别在后续阶段验收。

### 13.5 Phase 2：用户认证与权益基础

进入条件：页面骨架可运行，数据库和业务 API 的实现位置已经确定。

| 编号 | 具体工作 | 交付与完成判定 |
| --- | --- | --- |
| P2-01 | 建立 User、Session、PlanPolicy、MembershipGrant、QuotaAccount、UsageRecord、VerificationChallenge 和审计模型迁移 | 开发库可全新初始化，唯一约束与默认权限正确 |
| P2-02 | 实现邮箱密码注册、登录、退出、当前用户、改密及可撤销会话 | 从注册到登录账户页为真实闭环，哈希和令牌不泄露 |
| P2-03 | 实现权限检查、账号禁用检查、CSRF、站内跳转校验和认证限流 | 普通用户不能访问管理接口；失效会话被拒绝 |
| P2-04 | 实现有效 Plan 计算、VIP 到期判断、额度周期与余额读取 | role/plan 分离；到期不依赖重新登录；账户正确显示已用、冻结和可用 |
| P2-05 | 完成账户页、密码修改、验证状态与历史入口 | 数据来自当前账户；历史可显示真实空状态，待 Phase 3 接入 |
| P2-06 | 实现验证服务接口、渠道适配契约、功能开关与挑战消费逻辑 | 可用测试适配器验证过期和单次消费；生产未接渠道明确返回未启用 |
| P2-07 | 建立受控管理员初始化及服务层权限、会员、额度调整能力 | 无公共自助提权入口；操作校验与审计服务可供 Phase 4 管理界面调用 |

交付物：数据库迁移、认证接口、可用账户页、权益服务及 docs/phase-2-report.md。退出条件：第 14.2 节与本阶段有关的认证、权限、会员计算和验证预留检查通过；后台操作界面在 Phase 4 完成。

### 13.6 Phase 3：TTS 接入、任务与额度闭环

进入条件：真实认证、用户归属和权益服务可用；具备可访问的联调 TTS 服务及测试额度配置。

| 编号 | 具体工作 | 交付与完成判定 |
| --- | --- | --- |
| P3-01 | 建立音色、任务、音频模型与现有 TTS 适配器 | 不重写推理服务；参数范围和错误映射与真实接口一致 |
| P3-02 | 实现任务创建、幂等键、文本校验、用户限流、并发控制和额度冻结 | 提交与冻结事务一致；同键不同内容返回冲突 |
| P3-03 | 实现 Worker 领取、租约、超时、结果核对和有限重试 | 任务持久化，进程重启不会丢失任务或盲目重复调用 |
| P3-04 | 实现音频校验、私有存储、成功消费、失败释放和异常对账 | 音频落盘后才标记成功；结算与释放不重复执行 |
| P3-05 | 接通工作台输入、参数、提交、轮询、结果和错误恢复 | 真实生成音频可播放，刷新后任务状态保持 |
| P3-06 | 完成自己的分页历史、任务详情、回放、下载和额度刷新 | 回放下载不扣额度；跨用户资源访问被拒绝 |
| P3-07 | 验证重复请求、额度争用、上游失败、存储失败、跨周期和重启恢复 | 有具体测试结果与修复记录，不能仅凭正常路径通过 |

交付物：可用 TTS 全流程、内部服务适配、Worker、私有文件访问及 docs/phase-3-report.md。退出条件：第 14.3 节通过，真实上游联调完成；尚未关闭的生产裸端口必须记录为 Phase 5 上线阻断项。

### 13.7 Phase 4：CMS 与业务管理后台

进入条件：官网模板稳定，用户、权益和任务服务已可运行。

| 编号 | 具体工作 | 交付与完成判定 |
| --- | --- | --- |
| P4-01 | 配置 Payload、独立内容存储边界和受控 CMS 管理账户 | 普通业务账户无 CMS 权限，迁移与业务库互不覆盖 |
| P4-02 | 实现 Product、Media、SiteSettings、HomeContent 字段、校验和编辑 | 运营可填完整产品资料；媒体和富文本通过安全限制 |
| P4-03 | 实现草稿、预览、发布、下架和缓存更新；替换本地内容适配器 | 不改模板即可新增产品；公共接口不泄露草稿 |
| P4-04 | 完成用户列表、筛选、详情、禁用和恢复界面与接口 | 权限由服务端执行，最后一个可用管理员受到保护 |
| P4-05 | 完成 VIP 授予、撤销、到期时间和额度调整操作 | 展示操作结果；必须填原因；重复提交不重复调整 |
| P4-06 | 完成任务查询、使用汇总、失败信息与审计查看 | 可按用户和时间追溯；默认不展示完整输入文本 |
| P4-07 | 做运营端到端演练 | 完成“发布产品”和“处理用户/VIP/额度/任务”两套实际操作记录 |

交付物：可操作 CMS、业务管理后台、简要运营说明及 docs/phase-4-report.md。退出条件：内容发布闭环和基础管理能力全部可用，第 14.1、14.2 节相关项目通过。

### 13.8 Phase 5：集成验收与上线准备

进入条件：Phase 1–4 功能完成，正式素材和生产配置已有明确值。

| 编号 | 具体工作 | 交付与完成判定 |
| --- | --- | --- |
| P5-01 | 全站联调，验证注册、生成、下载、VIP、管理员和 CMS 的完整用户路径 | 第 14 章逐项记录通过、失败或阻断，不用笼统“测试通过”代替 |
| P5-02 | 配置 HTTPS、反向代理、私网、服务凭据与持久卷 | 测试环境能按部署说明复现；浏览器不直接接触内部端点 |
| P5-03 | 验证代理通路后形成生产裸端口收回方案，在授权发布窗口实施并外网复测 | 绕过业务层的推理入口关闭，管理端和数据服务不可公开访问 |
| P5-04 | 完成数据库、CMS、音频备份与恢复，验证 Worker 重启和额度对账 | 保存恢复演练记录和异常处置步骤 |
| P5-05 | 检查越权、CSRF、限流、敏感日志、草稿、音频授权及真实负载 | 关键安全缺陷清零；性能结果对照 Phase 0 固定的目标 |
| P5-06 | 完成移动端、键盘可访问性、空状态、错误提示、SEO 和正式内容检查 | 不存在假联系方式、占位资质和未接通却提示成功的功能 |
| P5-07 | 整理发布包、配置示例、迁移顺序、回滚方案及运维说明 | DEPLOYMENT.md、OPERATIONS.md、ACCEPTANCE.md 可直接使用 |

交付物：可发布版本、验收矩阵、部署与回滚材料及 docs/phase-5-report.md。上线准备完成与实际上线分开记录；未执行生产发布时不得声称已经上线。涉及真实环境变更时按已授权发布范围执行。

### 13.9 阶段跟踪与范围控制

每个工作包使用未开始、进行中、受阻、已完成四种状态。完成记录包含工作编号、实际产物、验证证据和遗留问题；“界面存在”“字段已建”“用模拟数据跑通”不能代替相应业务闭环。

阶段报告至少包括：本阶段目标、完成的工作编号、代码/文档产物、验证结果、阻断项和下一阶段入口条件。报告是执行记录，不要求每个常规工作包都重复请求用户确认；已授权范围内且依赖满足时继续实施。

缺少某项依赖时先推进不依赖该项的工作；不得将依赖缺失标为功能完成。身份隔离、额度一致性、真实 TTS 接入和私网安全未通过时，不得进入生产上线。新增需求进入变更清单，注明影响的阶段和验收项，避免执行中持续扩充 V1。

## 14. 验收标准

### 14.1 产品与内容

- 官网一眼可识别蓝牙、音频与智能硬件定位；首页 TTS 为轻量入口，完整工具位于 `/tts`。
- 桌面和移动端布局无横向溢出；导航、文本输入、音色选择、播放器与账户操作可用，键盘可访问关键操作。
- CMS 新建真实产品并发布后，列表和详情正确展示；草稿与下架内容不能通过公共页面/API 被访问；修改 SEO 和媒体后生效。
- 页面没有冒充真实数据的产品、新闻、联系方式和资质占位内容。

### 14.2 用户、会员和安全

- 可用邮箱与密码注册、登录、退出并进入 `/account`；重复邮箱受数据库唯一约束保护，密码不以明文保存。
- role 仅有 user/admin、plan 仅有 free/vip；伪造注册参数不能成为 VIP 或管理员。
- 普通用户和 VIP 均不能访问管理接口，不能通过猜测任务 ID 读取其他用户文本、历史或音频。
- 管理员可以禁用并恢复用户、授予/撤销 VIP、设置到期时间和调整额度，所有操作带原因并可审计。
- VIP 到期在下一次权益检查时降为 free 有效权益；不依赖用户重新登录，也不依赖定时任务准时运行。
- 退出、禁用与改密后的会话撤销按第 6 章生效；CSRF 和越权请求被拒绝。
- 邮箱和手机号字段及验证状态存在；未接渠道时保持 false，预留流程有功能开关，验证码确认支持一次性消费与超时设计。

### 14.3 TTS 与额度

- 使用真实现有 TTS API 完成生成、结果持久化、刷新后历史查询、再次播放与下载。
- 超长文本、非法音色、无额度与并发超限被服务端拒绝，浏览器修改参数不能绕过规则。
- 两个并发请求争用最后一份额度时最多一个成功冻结；不存在负余额和超额提交。
- 相同幂等键重复提交仅创建一个任务；重复完成通知、Worker 重启和重试不重复消费。
- 上游失败、存储失败及超时终结后，冻结额度按规则释放；成功任务准确消费，跨周期任务回原周期结算。
- 回放和下载不新建生成任务、不扣生成额度；音频过期有清晰状态。
- 后台任务与使用统计可追溯到用户、任务、消费流水和对应音频。

### 14.4 部署与交付

- 外部测试确认推理裸端口、数据库和 Redis 不可公开访问；浏览器只使用受控 HTTPS 业务入口。
- 构建产物与 API 响应无上游密钥、密码哈希和内部地址泄露；私有音频桶无匿名列举能力。
- 按部署文档可启动系统并执行迁移；服务重启后账户、历史、音频和额度仍可用。
- 完成至少一次备份恢复演练和任务异常恢复检查，记录问题与结果。
- 提交实现说明、示例配置、迁移、测试结果、部署和回滚说明。容量目标在 Phase 0 明确后按代表性负载测试，不预先承诺未经测量的并发或时延。

## 15. 实施前需固定的参数与后续演进

### 15.1 Phase 0 决策清单

| 事项 | 本版处理 |
| --- | --- |
| 现有 TTS 协议 | 核实认证、音色、参数、同步/异步、结果格式、超时与幂等能力 |
| 正式品牌素材 | 确认 Logo 文件、第四版改色稿及精确色值，不重新发散方向 |
| 免费/VIP 额度 | 确定每周期字符数、单次长度、频率、并发和音色差异；配置化 |
| 会员期限 | V1 人工授予，明确默认期限；不自动开通付费续订 |
| 保留与清理 | 确认原始文本、音频、日志、审计和备份保留期限，形成用户可见说明 |
| 部署环境 | 确认域名、服务器、私网连接、对象存储和备份位置 |
| CMS 授权 | 明确管理人员及初始化方式，保持业务用户与内容权限隔离 |
| 验证渠道 | V1 第一阶段不强制验证；未来确定邮件/SMS 服务后启用真实流程 |

技术审计可自行确定兼容版本、模块组织和迁移实现；涉及额度、素材、保存期限等产品配置应记录采用值与依据。未确定生产配置不得隐含无限额度、永久保存或公开桶。

后续按实际需求扩展：邮件/短信验证与找回密码、手机号登录、第三方登录、在线支付和订单、自动订阅、开放开发者 API、多工具 AI Lab、新闻案例栏目、更细权限和更大规模任务调度。扩展继续沿用用户归属、Role/Plan 分离、业务 API 与推理服务分层。

## 16. Codex 执行交接

以本文为 V1.1 产品与技术基线，仅在 `E:\RD\Kaotings\www_site` 内实施。第一步读取该目录适用的项目规则并完成 Phase 0 审计，输出当前结构、可复用资产、TTS 接口事实、缺口及分阶段修改方案；此阶段不修改业务代码，不自动导入其他目录的旧工程。

进入实现阶段后按 Phase 1–5 推进。用户体系是 V1 正式交付，不得降级为后续事项；严格采用 role=user/admin、plan=free/vip；保留邮箱与手机验证扩展点；TTS 必须具备归属、历史、回放、下载、额度与管理闭环。官网保持蓝牙、音频和智能硬件主体定位，CMS 管内容，现有 TTS 服务经业务层安全代理访问。

以第 14 章验收用例作为完成依据。实现与本文出现冲突时，先记录差异、影响和拟采用方案；不得以简化为由删除已确认的 V1 功能。