Cheng Zhou
f9a9f7eafe
- 删除 .ctms-env：环境名由 .env 的 COMPOSE_PROJECT_NAME 反推 (ctms_detect_env)，健康检查地址改存 .env 的 CTMS_BASE_URL - prepare_env_file 由“已存在则整体跳过”改为逐项探测补全： 身份类缺失补目标值、密钥类缺失/空才生成、已有值一律不动 - resolve_effective_config 放宽为“冲突才致命”：身份类缺失交给 补全，仅 COMPOSE_PROJECT_NAME/ENV 与目标环境冲突时报错停止 (防止覆盖后孤立旧环境容器) - 新增 ctms_env_has_key 区分“键缺失”与“键存在但空值” (dev 的 LOGIN_RSA_PRIVATE_KEY= 是合法空值) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CTMS 项目快速上手
交互安装入口
- 推荐执行
./install.sh，通过键盘↑/↓选择安装、更新、卸载、资源状态等操作；该入口不接受命令行参数。 - 菜单顶部会常驻显示当前 CTMS 容器部署状态，包括已检测到的环境、Compose 项目和容器运行数量。
- 底层脚本位于
scripts/：install.sh、update.sh、uninstall.sh、status.sh；状态脚本使用docker compose stats --no-stream采集资源快照并美化展示。
生产部署
- 生产入口：
docker-compose.yaml - 初始化方式：
docker compose run --rm backend-init - 启动方式：
docker compose up -d --build - 运行拓扑：
nginx、backend、db - 对外入口：
nginx提供前端静态资源，并同域反代后端 API - 数据库 schema 来源：Alembic migration，不再依赖
database/init.sql - 默认无任何业务预置数据；生产初始化只确保固定管理员
admin@huapont.cn / admin123存在 - 生产环境必须配置
LOGIN_RSA_PRIVATE_KEY；登录密码传输使用 RSA-OAEP 包裹 AES-GCM 密钥，数据库仍只保存 bcrypt 哈希 - 浏览器端加密依赖 WebCrypto 安全上下文；生产访问必须使用 HTTPS，本地
localhost例外 - 当前 challenge 缓存在后端进程内，默认最多保留 1000 个；多实例或多 worker 部署需改为共享缓存或启用粘性会话
- 验证方式：
docker compose configcurl -i http://127.0.0.1:8888/curl -i http://127.0.0.1:8888/health
账号与注册
- 初始化管理员：
admin@huapont.cn / admin123（通过生产初始化命令显式创建） - 自助注册：前端
/register提交邮箱、密码、姓名、角色（CRA/PV/IMP/PM）、部门，状态为 PENDING。 - 管理员审核：
/admin/user-approval列表查看待审核，支持通过/拒绝；仅 ACTIVE 用户可登录。 - 更多账号：管理员也可在
/admin/users直接创建 ACTIVE 账号，再在项目成员中赋予角色。
角色权限概要（前端操作级提示，后端仍最终裁决）
- ADMIN：全权限
- PM：里程碑/任务维护、参与者状态、AE 创建/关闭、Issue 创建/关闭、Finance 创建/审批/支付、IMP 交易、FAQ 维护
- CRA：任务/参与者/AE/Data Query 创建，参与者状态更新，Finance 创建/提交，其他只读
- PV：AE 创建/关闭，Issue 创建/关闭，其余只读
- IMP：IMP 交易/产品/批次维护，其余只读
- 普通成员（无项目角色）：仅浏览
访问方式
- 前端：
http://localhost:8888 - 后端 API：同域
/api/v1/* nginx负责托管前端静态资源，并将/api与/health转发到backend
仓库治理文档
- 分支治理规范：
docs/branch-governance.md - 分支环境安装配置：
docs/guides/branch-environment-installation.md - 发布检查清单：
docs/guides/release-checklist.md
本地配置
- 本地编辑器配置（如
.vscode/）不纳入版本库。 - 前端环境变量请使用
frontend/.env，可从frontend/.env.example复制。 - 根目录
.env不作为当前默认启动流程的提交配置文件。 - Postman 本地环境请基于
docs/postman/local.postman_environment.example.json自行复制，不提交个人环境文件。 - 文档入口见
docs/README.md；当前约束集中在分支治理、发布清单和治理审计文档，操作手册集中在docs/guides/，历史交付记录集中在docs/reports/与docs/plans/。
常用流程
- 用管理员账号登录前端（默认
admin@huapont.cn / admin123）。 - 进入左侧导航「账号治理」「项目治理」进行用户、项目、中心等全局管理；或在“项目列表”选择项目后进入项目内工作区。
- Dashboard 查看进度、待办；左侧导航进入“里程碑”“任务”等页面。
- 退出登录或切换项目可通过顶部右侧下拉。
管理员全局治理（前端入口）
- 账号治理：
/admin/users（新建/编辑/启用禁用用户，重置密码需二次确认） - 项目治理：
/admin/projects（创建/编辑项目，成员配置 PM/CRA，中心管理） - 中心管理：
/admin/projects/:projectId/sites（中心创建/编辑、CRA 绑定、启用停用）
ADMIN 具备所有 PM 权限，项目内操作与 PM 同步放行。
注意
- 登录使用邮箱 + 密码，前端会先获取登录公钥并加密提交；未审核/已拒绝/已停用账号无法登录。
- 令牌与当前项目上下文保存在浏览器 LocalStorage 中，清除后需重新登录/选择项目。
- 若后端重启，确认数据库容器仍健康，前端会弹出错误提示。