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 --build backend-init
• 启动方式：docker compose up -d --build
• 运行拓扑：nginx、backend、db、onlyoffice
• 对外入口：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 config
  • curl -i http://127.0.0.1:8888/
  • curl -i http://127.0.0.1:8888/health
  • curl -i http://127.0.0.1:8888/readyz

账号与注册

• 初始化管理员：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 与 /readyz 转发到 backend

macOS 桌面端开发

• 桌面端约束集中在 AGENTS.md：Tauri 在线客户端，不内嵌后端、不保存本地业务权威数据、不做离线同步；在线辅助缓存必须遵守 docs/desktop-local-cache-plan.md。
• 开发启动：进入 frontend/ 后执行 npm run desktop:dev。
• 生产构建：进入 frontend/ 后执行 npm run desktop:build；DMG 构建执行 npm run desktop:bundle:dmg。
• 首次启动桌面端会要求配置 CTMS 服务端地址，并在保存前检查 ${serverUrl}/health。
• 生产或非本地服务地址必须使用 HTTPS；本地开发允许 http://localhost 或 http://127.0.0.1。
• Web 与桌面端共用产品版本；执行 npm run version:set -- <version> 统一升级，执行 npm run version:check 检查漂移。
• 桌面端与 Web 端从同一发布标签和 Git 提交构建，具体流程见 docs/guides/client-release.md。

ONLYOFFICE 标准组件

• ./install.sh 或 bash scripts/install.sh dev|main|release 默认生成独立 JWT、持久化实例标识并启动 Document Server，不再需要额外启用 Compose profile。
• bash scripts/onlyoffice-dev-up.sh 仅保留为开发环境重建、健康验证和密钥轮换入口；普通安装无需再执行。
• 默认镜像、字体、安全配置和生产许可要求见 docs/guides/onlyoffice-preview.md。

仓库治理文档

• 分支治理规范：docs/branch-governance.md
• 分支维护中文 SOP：docs/guides/branch-maintenance-sop-zh.md
• 分支环境安装配置：docs/guides/branch-environment-installation.md
• 发布检查清单：docs/guides/release-checklist.md
• 系统监测简易运维：docs/guides/system-monitoring-operations.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/。

常用流程

1. 用管理员账号登录前端（默认 admin@huapont.cn / admin123）。
2. 进入左侧导航「账号治理」「项目治理」进行用户、项目、中心等全局管理；或在“项目列表”选择项目后进入项目内工作区。
3. Dashboard 查看进度、待办；左侧导航进入“里程碑”“任务”等页面。
4. 退出登录或切换项目可通过顶部右侧下拉。

管理员全局治理（前端入口）

• 账号治理：/admin/users（新建/编辑/启用禁用用户，重置密码需二次确认）
• 项目治理：/admin/projects（创建/编辑项目，成员配置 PM/CRA，中心管理）
• 中心管理：/admin/projects/:projectId/sites（中心创建/编辑、CRA 绑定、启用停用）

ADMIN 具备所有 PM 权限，项目内操作与 PM 同步放行。

注意

• 登录使用邮箱 + 密码，前端会先获取登录公钥并加密提交；未审核/已拒绝/已停用账号无法登录。
• 令牌与当前项目上下文保存在浏览器 LocalStorage 中，清除后需重新登录/选择项目。
• 若后端重启，确认数据库容器仍健康，前端会弹出错误提示。