57 lines
5.2 KiB
Markdown
57 lines
5.2 KiB
Markdown
# 项目文档导航
|
||
|
||
> `cmhub` 项目文档总览。agent 真正开始编程时，以 [`00-ai-start-here.md`](00-ai-start-here.md) 为工作入口。
|
||
|
||
## 一句话定位
|
||
|
||
`cmhub` 是一个**自助用户端 + 计费型 AI 能力网关 + 运营后台**三合一服务：终端用户自助注册、扫码充值、管理 API Key；用户的程序用 API Key 调用把 `cmbot` 的「生成标题」「生成图片」能力封装成的 HTTP API，按点数计费；运营用 django-admin 管理用户、点数与记录。
|
||
|
||
## 文档导航
|
||
|
||
- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
|
||
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。
|
||
- [`../progress.md`](../progress.md)：执行历史流水，只追加记录任务执行、验证、阻塞和决策。
|
||
- [一页汇报版 / 电梯陈述](project-onepager.md)：最短版本，用于口头汇报或投影。
|
||
- [项目介绍（给管理层）](project-brief.md)：面向决策与汇报的业务视角概览，非技术执行文档。
|
||
- [AI 开发入口](00-ai-start-here.md)：每次开始工作的入口、阅读顺序和任务领取规则。
|
||
- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
|
||
- [需求](02-requirements.md)：要什么、用户故事、验收标准（含资金风险）。
|
||
- [技术栈](03-tech-stack.md)：Django + DRF + django-admin 及运行命令。
|
||
- [架构设计](04-architecture.md)：系统结构、计费时序、数据模型、关键风险和开发顺序。
|
||
- [编码规则](05-coding-rules.md)：硬性约束，含资金/点数安全专项（第 8 节）。
|
||
- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
|
||
- [Phase 0 骨架审核](phase-0-review.md)：T-001~003 代码审核结论与修补清单（P1/P2/P3），对应任务 T-004。
|
||
- [Phase 1 AI 层审核](phase-1-review.md)：T-101~104 代码审核结论与修补清单（P1/P2/P3），对应任务 T-105；重点提示图片同步风险未退与 `parameters` 越权计费隐患。
|
||
- [Phase 2 计费核心审核](phase-2-review.md)：T-201~203 代码审核结论（资金安全逐条核对）与加固清单（**零 P1**，P2/P3），对应任务 T-204。
|
||
- [Phase 3 对外 API 与充值审核](phase-3-review.md)：T-301~305 代码审核结论（鉴权/回调/幂等/入账逐条核对）与优化建议，对应任务 T-306；**P1 提示 `image_url` SSRF 上线前必修**。
|
||
- [Phase 4 用户端审核](phase-4-review.md)：T-501~504 代码审核结论（注册不送点/越权/CSRF/明文只显一次/到账以回调为权威逐条核对）与优化建议（**零 P1**，P2/P3），对应任务 T-505。
|
||
- [MVP 完整验收报告](mvp-acceptance.md)：T-402 对 `02-requirements.md` P0 验收项的逐项结论、测试证据和已知限制。
|
||
- [部署 / 运行文档](deployment.md)：T-403 生产部署步骤、宝塔 / Nginx / Gunicorn 配置、静态文件、共享 cache、图片超时与上线检查。
|
||
- [API 合约](api.md)：对外接口、支付回调、AI 调用模块合约、错误码。
|
||
- [桌面端版本检查接口对接文档](client-release-api-integration.md)：`GET /api/v1/client/releases/latest` 的请求 demo、响应结构、客户端处理和排查清单。
|
||
- [内容安全与本地敏感词过滤](moderation.md)：T-604 的 prompt 敏感词过滤设计、时序、缓存和验收口径。
|
||
- [路由与页面结构](routes.md)：API 路由与 django-admin 后台职责。
|
||
- [品牌基线 Brand Tokens](brand.md)：配色/字体/logo/术语/语气的单一真相源（含可复制 CSS 变量）；首页、portal、桌面端统一引用，对应任务 T-606。
|
||
- [环境变量与配置](env.md)：Django、数据库、AI 密钥加密、支付、对象存储等配置项。
|
||
- [当前实现状态](current-state.md)：可覆盖的当前快照、可运行命令、下一步任务。
|
||
- [已有项目接入清单](adoption-checklist.md)：把模板补进已有代码库时的迁移步骤。
|
||
- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查。
|
||
- [方法对照表](method-map.md)：失败模式 → 首要修复 → 工件。
|
||
- [评审评分表](evaluator-rubric.md)：单次会话输出的结构化评审。
|
||
- [质量文档](quality-document.md)：代码库长期健康度追踪。
|
||
- [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1)：标准启动与验证入口（按操作系统二选一）；换命令只改脚本顶部三个变量。
|
||
|
||
## 任务 / 进度 / 当前状态
|
||
|
||
- `06-tasks.md` 维护任务看板：任务 ID、依赖、验收要点和状态。
|
||
- `../progress.md` 维护执行进度：每轮做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。
|
||
- `current-state.md` 维护当前快照：当前目录、可运行命令、已完成摘要和下一个可领取任务。
|
||
|
||
## 维护原则
|
||
|
||
- 需求变化先改文档，再改代码。
|
||
- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`，执行过程追加到 `../progress.md`。
|
||
- API、数据模型、计费时序、错误码一旦在文档中定稿，代码不得另起一套。
|
||
- 涉及点数/资金的改动，先读 `05-coding-rules.md` 第 8 节与 `04-architecture.md` 第四节。
|
||
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
|