www_site/docs/DECISIONS.md

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，不能称为已部署环境。

D-07 统一打包部署和版本核对

• 后续部署禁止依赖逐个文件的 pscp/手工覆盖；必须使用保留目录结构的统一归档包或等效同步方案，至少完整包含 app/、components/、lib/、public/ 和运行配置。
• 部署包必须携带构建提交号和文件清单；解包后先核对目录、关键源码哈希和提交号，再执行安装与构建。
• 构建时注入 NEXT_PUBLIC_BUILD_COMMIT 或等效版本变量，启动后通过页面版本标识、构建产物和 CSS 资源核对实际提供版本。
• 重启前后必须确认监听进程的 PID、工作目录、启动命令和 .next 构建时间，避免旧进程继续提供旧构建。
• 部署失败或版本核对不一致时停止切换，不以 HTTP 200 作为版本生效的唯一证据。
• 当前 Phase 1 已用版本标识临时验证；统一归档部署脚本、原子切换和自动核对列为后续部署基础设施任务。

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 切换都必须作为明确授权的运维动作单独执行。