# Phase 0 技术决策

日期：2026-09-08  
范围：P0-05；以下决策用于进入 Phase 1 的实施边界。未有实测依据的版本、容量和产品值明确标为待确认。

## 1. 已固定决策

### D-01 项目根目录和迁移边界

- 唯一实施根目录为 `E:\RD\Kaotings\www_site`。
- 不从 `kts_site` 或任何外部旧工程复制页面、代码、TTS 服务或配置。
- Phase 0 不移动、删除或重排现有文档和素材；业务目录在实际需要的阶段新增。

依据：V1.1 第 1.1、13.1、16 章及当前 Git 审计。

### D-02 代码组织

- Phase 1 Web 暂使用仓库根目录 App Router，承载官网、TTS 工作台、账户和业务管理页面；在 API/CMS/Worker 进入同仓库前不为单一 Web 应用增加额外 monorepo 层。后续若引入多应用，再迁入 `apps/web`，保持页面和组件边界不变。
- 业务 API 使用 `services/api`，统一负责身份、权限、权益、额度、任务和上游代理。
- Worker 使用 `services/worker`，以持久化任务表为恢复依据。
- CMS 采用同仓库独立落点 `apps/cms`，内容授权和 schema 与业务身份隔离。
- `packages` 仅在出现实际跨应用共享时创建，不为未来功能预建空壳。
- `infra` 保存部署、反向代理和无秘密示例配置。

这是一项新增落点决策，不代表目录已经存在。CMS 是否同机部署由测试机运行时和资源验证决定，但权限边界不改变。

### D-03 数据归属和持久化

- 业务数据库由 API 负责：用户、Session、Role/Plan、会员授权、额度账户/流水、TTS 任务、审计和任务关联音频元数据。
- CMS 数据由 Payload 负责，使用独立 schema 或数据库账号；CMS 迁移不得覆盖业务迁移。
- PostgreSQL 可以共用同一实例，但不共用迁移职责或数据库账号。当前测试机尚未安装或提供 PostgreSQL。
- 音频使用私有 S3 兼容对象存储（优先评估 MinIO 或已有兼容服务）；浏览器不得直接获得永久公开 URL。
- 原始文本和音频是用户私有数据；默认日志只保留任务 ID、长度、状态和耗时等脱敏信息。

### D-04 认证与授权

- API 是唯一业务身份权威；Next.js 不复制认证、额度或权限决策。
- 使用服务端可撤销的不透明会话，浏览器持有 `Secure`、`HttpOnly`、`SameSite` Cookie。
- Role 固定为 `user/admin`，Plan 固定为 `free/vip`，两者不合并。
- CSRF 和 Origin 校验由 API 对 Cookie 写操作实施；服务端逐接口检查账号状态、权限和资源归属。
- CMS 使用独立管理会话/授权；普通业务注册不能自动得到 CMS 权限。
- 初始管理员通过受控初始化建立，注册接口不能接受角色、套餐、状态或验证字段。

### D-05 任务和额度

- 任务采用数据库持久化状态 `queued -> running -> succeeded/failed`，Worker 使用租约和可恢复扫描。
- Redis 只用于限流、轻量协调或通知，不作为任务唯一事实来源。
- 接收任务时事务化冻结额度；音频持久化成功后转消费；失败释放；重播/下载不扣生成额度。
- 同一用户幂等键与请求绑定；同键不同请求返回冲突。上游不支持幂等时，不对结果不明的请求盲目自动重试。
- TTS 上游只能通过固定配置的适配器访问，用户输入不得控制请求 URL。

### D-06 代理和网络边界

- 浏览器只访问同源 HTTPS 业务入口；不直接访问 TTS、数据库、Redis 或对象存储管理端。
- TTS 上游保持内部服务边界；现有上游不重写，业务层做适配和安全代理。
- 外部入口目标为 80/443，80 跳转 HTTPS；实际反向代理产品尚未安装，Nginx/Caddy 在 Phase 1 选定。
- 测试机目前仅开放/监听 SSH，不能称为已部署环境。

## 2. 尚未固定且不能虚构的事项

| 事项 | 当前处理 | 固定条件 |
| --- | --- | --- |
| Next.js/TypeScript/Tailwind 版本 | 待定 | Phase 1 选定版本并完成本地构建 |
| FastAPI/Python 依赖版本 | 待定 | Phase 2 建模前完成兼容性验证 |
| Payload 版本和 CMS 集成方式 | 待定 | 确认 Node 运行时和独立内容库方案 |
| PostgreSQL/Redis/对象存储版本 | 待定 | 测试机服务方案和持久卷确定后固定 |
| Nginx 或 Caddy | 待定 | 以 HTTPS、同源代理和运维能力验证为准 |
| TTS 协议、音色、参数和超时 | 待定 | 授权上游联调后写入契约 |
| 免费/VIP 额度和并发 | 待定 | 产品负责人提供值，配置版本化 |
| 音频/文本/日志/备份保留期 | 待定 | 产品和隐私要求确认后固定 |
| 域名、证书、备份位置 | 待定 | 环境负责人提供并验证 |

## 3. 模块责任边界

| 模块 | 责任 | 不负责 |
| --- | --- | --- |
| `apps/web` | 页面、表单、状态展示、同源 API 调用、可访问性 | 认证权威、额度扣减、上游密钥 |
| `services/api` | 认证、授权、权益、额度、任务 API、TTS 代理、资源归属 | 页面渲染、直接执行不可恢复长任务 |
| `services/worker` | 领取任务、调用适配器、音频校验/存储、结算/释放、恢复 | 浏览器会话和 CMS 权限 |
| `apps/cms` | 产品、媒体、首页内容、SEO 草稿/发布 | 业务用户密码、TTS 权益和额度 |
| `infra` | 运行配置、代理、迁移/备份/回滚说明 | 业务规则和秘密提交 |

## 4. 变更规则

如果真实 TTS 接口、服务器权限或版本兼容性与本文冲突，先新增差异记录并更新本文件，不以临时绕过方式破坏身份隔离、额度一致性或私网边界。任何服务器安装、扩容、开放端口和 HTTPS 切换都必须作为明确授权的运维动作单独执行。