diff --git a/README.md b/README.md index 0e75329..3e0224f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 考町科技官网暨 AI 工具平台 -当前阶段:Phase 1 设计系统与官网骨架已完成,真实业务服务尚未接入。 +当前阶段:Phase 2 用户认证与权益基础已完成,TTS 生成和 CMS 尚未接入。 - [产品与技术规划(含分阶段工作清单)](docs/V1_PLAN.md) - [Word 规划书](docs/考町科技官网暨AI工具平台_V1.1.docx) @@ -10,6 +10,7 @@ - [技术决策](docs/DECISIONS.md) - [后续执行计划](docs/EXECUTION_PLAN.md) - [Phase 1 阶段报告](docs/phase-1-report.md) +- [Phase 2 阶段报告](docs/phase-2-report.md) 项目根目录:`E:\RD\Kaotings\www_site`,以本次新仓库为准。 diff --git a/docs/EXECUTION_PLAN.md b/docs/EXECUTION_PLAN.md index 9d60fb8..2a330a5 100644 --- a/docs/EXECUTION_PLAN.md +++ b/docs/EXECUTION_PLAN.md @@ -53,13 +53,15 @@ Phase 1 当前可在本地继续开发,也可在测试机仅部署官网骨架 ### Phase 2:认证与权益基础 -- `P2-01` 建立 User、Session、PlanPolicy、MembershipGrant、QuotaAccount、UsageRecord、VerificationChallenge 和审计迁移。 -- `P2-02` 实现真实注册、登录、退出、当前用户、改密和可撤销会话。 -- `P2-03` 实现权限、账号禁用、CSRF、站内跳转校验和认证限流。 -- `P2-04` 实现有效 Plan、VIP 到期、额度周期和余额读取。 -- `P2-05` 完成账户页和真实空历史状态。 -- `P2-06` 实现验证服务抽象、开关、挑战过期和一次性消费;未接渠道返回未启用。 -- `P2-07` 建立受控管理员初始化及服务层管理、会员、额度调整能力。 +- `P2-01` 已完成:版本化迁移和 User、Session、PlanPolicy、MembershipGrant、QuotaAccount、UsageRecord、VerificationChallenge、审计表已建立。 +- `P2-02` 已完成:真实注册、登录、退出、当前用户、改密和可撤销会话已验证。 +- `P2-03` 已完成:权限、账号禁用、CSRF、Origin、同源入口和认证限流已实现并测试。 +- `P2-04` 已完成:有效 Plan、VIP 到期、额度周期和余额读取已实现;正式额度值仍待产品确认。 +- `P2-05` 已完成:账户页读取真实 API,支持账户、额度、退出和改密;TTS 历史保留真实空状态。 +- `P2-06` 已完成:验证服务抽象、开关、挑战过期和一次性消费已实现;未接渠道返回未启用。 +- `P2-07` 已完成:受控管理员初始化及服务层用户、会员、额度调整能力已部署并测试。 + +交付物:数据库迁移、认证接口、可用账户页、权益服务、测试部署和 `docs/phase-2-report.md`。TTS 生成、CMS 和完整管理界面仍分别属于 Phase 3/4。 ### Phase 3:TTS 与额度闭环 diff --git a/docs/phase-2-report.md b/docs/phase-2-report.md new file mode 100644 index 0000000..395d990 --- /dev/null +++ b/docs/phase-2-report.md @@ -0,0 +1,97 @@ +# Phase 2 用户认证与权益基础报告 + +日期:2026-09-08 +范围:P2-01 至 P2-07 +状态:核心认证、会话、权益、额度基础和受控管理员能力已完成并部署测试环境;真实邮箱/短信渠道和 TTS 未接入。 + +## 1. 实现内容 + +### P2-01 数据模型和迁移 + +- `services/api/migrations/001_initial.sql` 建立版本化初始化脚本。 +- 已创建 `users`、`sessions`、`plan_policies`、`membership_grants`、`quota_accounts`、`usage_records`、`verification_challenges`、`admin_audit_logs` 和 `schema_migrations`。 +- PostgreSQL 使用 UUID、UTC 时间、唯一约束、Role/Plan 检查约束和审计字段。 +- 当前无旧数据库,未执行数据迁移。 + +### P2-02 认证与会话 + +- 邮箱密码注册、登录、退出、当前用户和密码修改已实现。 +- 密码使用 Argon2id 哈希;密码原文、哈希、会话令牌和验证码不进入响应或日志。 +- 会话使用服务端可撤销不透明 Cookie,Cookie 配置 `HttpOnly`、`SameSite=Lax`、HTTPS 环境 `Secure`。 +- 改密后撤销其他会话;禁用账户不能新登录。 + +### P2-03 权限和防护 + +- `role=user/admin` 与 `plan=free/vip` 分离,注册请求不能写入角色、套餐或状态。 +- Origin 校验、CSRF Cookie/Header 校验和服务端资源权限检查已实现。 +- 登录和注册具备当前 API 进程内限流;多进程/多节点限流待 Redis 阶段替换。 +- 普通用户访问管理接口返回 `403`。 + +### P2-04 会员和额度基础 + +- 有效 VIP 由未撤销且在有效期内的 `MembershipGrant` 判断;过期后权益计算回到 free,不依赖重新登录。 +- 额度账户按 UTC 自然月建立,返回周期、上限、调整、已用、冻结和可用额度。 +- 当前环境策略默认值为 free `10000`、vip `100000` 周期单位,仅用于测试基础,不代表正式产品定值。 +- TTS 生成、消费、冻结和释放仍留在 Phase 3,本阶段不实现生成业务。 + +### P2-05 账户中心 + +- `/account` 已改为读取真实 `/api/v1/auth/me` 和 `/api/v1/account/usage`。 +- 支持显示邮箱、角色、计划、验证状态、额度周期、已用、冻结和可用额度。 +- 支持退出和修改密码;未登录、加载和错误状态有明确提示。 + +### P2-06 验证流程预留 + +- `VerificationChallenge`、用途、渠道、过期、尝试次数、摘要和一次性消费结构已建立。 +- 验证确认成功会更新对应 `email_verified` 或 `phone_verified`,挑战过期/重复/错误会拒绝。 +- 邮件和短信开关默认关闭;当前发送接口明确返回 `503 VERIFICATION_NOT_ENABLED`,没有伪造发送成功。 + +### P2-07 受控管理员初始化 + +- `services/api/app/init_admin.py` 只接受进程环境中的 `ADMIN_EMAIL`、`ADMIN_PASSWORD`,拒绝覆盖已有邮箱。 +- 测试管理员已受控初始化,邮箱为 `mu.blank@gmail.com`;密码原文未写入仓库、配置文件或日志。 +- 管理服务接口支持用户查询、VIP/Plan 授予、额度调整、禁用/恢复和审计记录。 +- 最后一个可用管理员不能被禁用。 + +## 2. 测试结果 + +测试入口:`https://192.168.199.22/`。测试使用临时账户,密码未记录。 + +| 测试 | 结果 | +| --- | --- | +| PostgreSQL 迁移 | 通过,`001_initial.sql` 已应用 | +| API 健康检查 | 通过,数据库状态 `ok` | +| 注册 | `201` | +| 登录并设置 Cookie | `200` | +| 当前用户 | `200` | +| 额度读取 | `200` | +| 修改密码 | `200` | +| 验证发送未启用 | `503` | +| 退出 | `204` | +| 退出后访问当前用户 | `401` | +| 普通用户访问管理接口 | `403` | +| 管理员查询用户 | `200` | +| 管理员授予 VIP | `200` | +| 管理员额度调整 | `200` | +| 管理员禁用用户 | `200` | +| 被禁用用户登录 | `403` | +| 管理员恢复用户 | `200` | + +## 3. 测试环境部署 + +- PostgreSQL `16.15`:业务数据库 `kaotings`,业务账号 `kaotings_app`,仅监听 `127.0.0.1:5432`。 +- API:FastAPI/Uvicorn,systemd 服务 `kaotings-api`,仅监听 `127.0.0.1:8000`。 +- Web:Next.js,systemd 服务 `kaotings-web`,仅监听 `127.0.0.1:3000`。 +- HTTPS:Caddy `2.6.2`,systemd 服务 `caddy`,监听 TCP `80/443`,使用 `tls internal`,`/api/*` 反代 API,其余请求反代 Web。 +- 自动重启:API、Web、Caddy 均由 systemd 管理并设置 `Restart=always`;PostgreSQL 使用系统服务。 +- 测试 HTTPS 根证书已导入当前开发机用户受信任根证书存储;根证书和私钥不进入 Git。 +- Redis、TTS、CMS、对象存储未安装或启动,符合本阶段范围。 +- 发布包保留完整目录结构;当前构建版本为 `4e40019`。 + +## 4. 安全和待办 + +- `/etc/kaotings/api.env` 为 root-only `0600`,包含数据库密码和 CSRF 密钥,不在仓库。 +- 当前测试策略值、管理员密码和临时测试账户不作为生产配置。 +- 邮件/SMS 真实服务、找回密码和强制验证仍待后续渠道接入。 +- Cookie、HTTPS 和认证已验证;完整生产限流、备份恢复和外部安全复测属于后续验收。 +- API 与 Web 已用统一保留目录结构的发布归档部署,避免逐文件传输错位。