# 技术侧实施清单

## 目标

本文档将技术侧方案拆成可执行清单，按优先级和阶段推进，适合直接排期。

## 第一阶段：可公开部署

### 1. 安全整改

- [ ] 将数据库配置迁移到环境变量
- [ ] 新增 `.env.example`
- [ ] 删除代码中的默认数据库密码
- [ ] 移除默认 `admin/admin`
- [ ] 引入 `bcrypt` 或 `argon2`
- [ ] 增加管理员初始化脚本
- [ ] 限制 `CORS` 来源
- [ ] 生产环境启用 `secure cookie`

### 2. 基础工程化

- [ ] 编写 `Dockerfile`
- [ ] 编写 `docker-compose.yml`
- [ ] 配置 MySQL 容器
- [ ] 配置 Redis 容器
- [ ] 规范数据卷目录
- [ ] 编写部署说明文档

### 3. 日志与健康检查

- [ ] 新增统一日志格式
- [ ] 为请求生成 `request_id`
- [ ] 增加 `/api/health`
- [ ] 记录 TTS 请求耗时
- [ ] 记录异常日志

## 第一阶段验收标准

- [ ] 项目可通过 `docker compose up` 启动
- [ ] 无敏感配置硬编码
- [ ] 默认无弱口令管理员
- [ ] 健康检查可返回数据库和 TTS 状态

## 第二阶段：可控试运营

### 4. 数据结构升级

- [ ] 新增 `plan`
- [ ] 新增 `user_plan`
- [ ] 新增 `usage_daily`
- [ ] 新增 `tts_request_log`
- [ ] 新增 `audio_cache_index`

### 5. 配额和限流

- [ ] 定义免费版默认配额
- [ ] 定义 Pro 版默认配额
- [ ] 接口增加单次文本长度限制
- [ ] 接口增加每日字符限制
- [ ] 登录接口增加限流
- [ ] 生成接口增加限流

### 6. 用量统计

- [ ] 每次生成记录请求日志
- [ ] 每次成功生成累计 `usage_daily`
- [ ] 增加用户用量查询接口
- [ ] 增加后台基础统计接口

### 7. 缓存增强

- [ ] 统一缓存 key 规则
- [ ] 缓存写入时同步索引表
- [ ] 缓存命中时更新命中次数
- [ ] 增加缓存命中率统计

## 第二阶段验收标准

- [ ] 免费用户超额后会被正确拦截
- [ ] 后台可看到今日生成量
- [ ] 系统可统计缓存命中率
- [ ] 日志可追踪一次生成请求

## 第三阶段：可收费运营

### 8. 异步任务队列

- [ ] 选型 `RQ` 或 `Celery`
- [ ] 增加 `async_task`
- [ ] 长文本改为异步任务
- [ ] 返回 `task_id`
- [ ] 提供任务状态查询接口
- [ ] 失败任务支持重试

### 9. 管理员后台完善

- [ ] 增加仪表盘统计页
- [ ] 增加套餐管理页
- [ ] 增加用户套餐分配能力
- [ ] 增加 TTS 日志查看页
- [ ] 增加任务查看与重试页
- [ ] 增加缓存概览页

### 10. 监控与告警

- [ ] 采集 CPU、内存、磁盘指标
- [ ] 采集队列长度
- [ ] 采集错误率
- [ ] 搭建 Grafana 面板
- [ ] 增加基础告警规则

## 第三阶段验收标准

- [ ] 长文本不会阻塞主接口
- [ ] 管理员可查看任务状态和失败原因
- [ ] 系统可以看到资源占用和错误趋势

## 推荐工期

### 第 1 周

- 安全整改
- `.env` 改造
- 基础日志

### 第 2 周

- Docker 化
- 健康检查
- 部署文档

### 第 3 周

- 数据表扩展
- 配额和限流
- 用量统计

### 第 4 周

- 缓存索引
- 后台统计
- 基础运营能力

### 第 5-6 周

- 异步任务
- 管理后台增强

### 第 7-8 周

- 监控告警
- 压测与问题修复

## 风险提示

### 需要优先避免的问题

- 一边收费一边仍然使用弱密码体系
- 没有配额就开放大量生成
- 没有日志导致问题无法排查
- 没有缓存索引导致缓存失控

## 总结

技术实施建议先做“安全、部署、配额、日志”，再做“缓存、统计、后台”，最后做“任务队列和监控”。这个顺序能保证你尽快得到一个可公开、可控、可收费的系统，而不是先把架构做重。