88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Home
|
||
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Home
|
||
wiki_revision: 07c26be93a044570206347fefe1f9a491c6a426a
|
||
synchronized_at: 2026-08-26T12:37:06Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# chorus 文档中心
|
||
|
||
chorus 是从 cmhub 设计中抽取并用 Go 重写的独立生图生文服务：用户提交提示词（可带原图）得到图片或文本，运营在管理端配置上游并查看生成记录。Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源，Wiki 是长期文档事实来源，Git 记录代码与镜像。
|
||
|
||
当前处于 **MVP-0：安全、可观测地跑通单上游闭环**。文档基线由工单 [#1](https://git.ilapage.cn/OPC/chorus/issues/1) 更新；这不表示产品功能已经开工。
|
||
|
||
## 第一次阅读
|
||
|
||
1. [项目档案](Project-Profile.-)：固定 go-admin 来源、工具链、目录和安全边界。
|
||
2. [产品需求总览](Product-Requirements-Overview.-)：MVP 分期、UI 状态和验收。
|
||
3. [架构与代码地图](Architecture-and-Code-Map.-)：同步/worker 路径、租约 CAS、代码生成边界。
|
||
4. [业务规则与术语](Business-Rules-and-Glossary.-)：数据、状态、SSRF、身份和排除范围。
|
||
5. [本地开发与验证](Local-Development-and-Verification.-)：目标环境、隔离库、测试策略。
|
||
6. [常见修改指南](Common-Changes.-)：修改步骤和停止条件。
|
||
7. [故障排查](Troubleshooting)：按证据定位环境、队列、上游和生成器问题。
|
||
8. [部署与运维](Deployment-and-Operations.-)：生产迁移、服务、健康、备份和回退。
|
||
9. [开发工作流](Development-Workflow.-)：建单、确认、实施、验收与关闭。
|
||
|
||
## 五分钟开始
|
||
|
||
```powershell
|
||
git status --short --branch
|
||
python dev_scripts/harness.py check --strict
|
||
python -m unittest discover -s tests -v
|
||
$env:GITEA_URL = "https://git.ilapage.cn"
|
||
python dev_scripts/harness.py sync --check
|
||
```
|
||
|
||
MVP-0 产品代码落地且环境达到 Go 1.26.5/MySQL 8.0 后，再执行 `go build ./...`、`go vet ./...`、`go test ./...` 和 `go run ./portal`。当前本机版本差距见本地开发页，不能把无法执行的命令记为通过。
|
||
|
||
## 简单修改从哪里开始
|
||
|
||
| 想做什么 | 先读 | 主要验证 |
|
||
|---|---|---|
|
||
| 改纯显示文案 | Common-Changes、模板 | 375/768/1024 最小界面检查 |
|
||
| 改默认 prompt template | Business-Rules | mock 生成并核对 rendered_prompt |
|
||
| 加 ProviderModel | Common-Changes | mock 协议 + SSRF；真实测试仅单次人工触发 |
|
||
| 排查生成失败 | Troubleshooting | attempts/error/lease 时间线 |
|
||
| 使用 go-admin 生成 CRUD | Architecture、Local-Development | migration → 隔离库 → 导表 → 生成差异审查 |
|
||
| 改长期文档 | 对应 Wiki、Common-Changes | 回读 revision + sync --check |
|
||
| 部署或回退 | Deployment-and-Operations | 迁移、健康、dev-tools、备份证据 |
|
||
| 更新需求 | Product-Requirements | 状态、工单、原型和验收入口 |
|
||
|
||
retryable、SSRF、密钥、迁移、租约/CAS、身份权限、点数写入、AutoMigrate、代码生成副作用、删除/清理和不可逆操作都不是简单修改。
|
||
|
||
## 事实来源
|
||
|
||
| 信息 | 事实来源 |
|
||
|---|---|
|
||
| 单次任务需求、变化、实现、测试、提交和验收 | Gitea 工单 |
|
||
| 长期需求导航 | Product-Requirements-Overview |
|
||
| 架构、规则、开发、排错和部署等长期文档 | Gitea Wiki |
|
||
| 生产数据库结构和配置种子 | `migrations/` 可逆 SQL |
|
||
| 源码和固定版本资料 | chorus Git；外部来源提交记录在 Project-Profile |
|
||
| 已确认界面与交互 | 可访问且版本明确的线上设计源；本地 `prototypes/` 仅保存明确要求导出的快照 |
|
||
| 离线核心文档 | Git 中的 `docs/` Wiki 只读镜像 |
|
||
|
||
`D:\github\goadmin` 是已审查来源，不是运行时事实来源。线上 Wiki 已初始化；长期文档必须先改 Wiki、回读 revision，再同步镜像。
|
||
|
||
## 项目入口
|
||
|
||
- [Gitea 工单](https://git.ilapage.cn/OPC/chorus/issues)
|
||
- [产品需求总览](Product-Requirements-Overview.-)
|
||
- [部署与运维](Deployment-and-Operations.-)
|
||
- [代码仓库](https://git.ilapage.cn/OPC/chorus)
|
||
- [新项目文档初始化](New-Project-Documentation-Setup.-)
|
||
- [交付文档指南](Delivery-Documentation-Guide.-)
|
||
- [可选任务快照模板（兼容）](Task-Archive-Template.-)
|
||
|
||
## 同步原则
|
||
|
||
```text
|
||
修改 Wiki → 在线回读 revision → 导出 docs → 校验差异 → 提交镜像
|
||
```
|
||
|
||
- `wiki-docs.json` 显式映射核心和项目专用页面；仅在长期文档变化时同步。默认不创建任务归档，专项快照和导出必须由用户或项目专用规则明确要求。
|
||
- 带 `generated: true` 的文件不得手工编辑；有未提交镜像修改时同步停止。
|
||
- 页面删除、重命名和事实源变化必须先更新工单并确认。
|
||
- 凭据、个人数据、真实 prompt、生成文件和生产数据不得进入文档、工单或原型。
|