二次开发总览
交付包是一套完整的 TypeScript monorepo，不是只能换 Logo 的页面主题。你可以修改前后端、数据模型、权限、任务和部署方式，也可以把它扩展成面向特定行业的社区产品。
选择你的开发方式
| 方式 | 适合谁 | 从哪里开始 |
|---|---|---|
| 人工二次开发 | 熟悉 TypeScript、React、Node.js、PostgreSQL 和 Docker 的开发者或团队 | 继续阅读本页，先建立私有 Git 仓库，再按 contract → API → Web → Mock → 文档的顺序修改 |
| AI 协作二次开发 | 希望让 Codex、Claude Code 等代码 Agent 负责分析、实现、测试或部署的人 | 阅读 AI 二次开发指南，让 AI 先遵守仓库根目录 AGENTS.md |
两种方式使用同一套代码边界和验收标准。AI 可以减少查找与机械修改的工作，但不能跳过权限、迁移、数据安全、Mock 对齐和回滚检查。
第一次修改建议
先在完整 Mock 中修改站点名称、首页文案或一个不涉及数据库的展示组件，跑通“建立分支 → 修改 → 测试 → 浏览器走查 → 合并”的完整过程，再开始支付、权限或数据模型改造。
先建立自己的 Git 仓库
压缩包不包含 .git。解压并完成首次验证后，建议立即建立私有仓库：
git init
git add .
git commit -m "chore: import community template"
git tag template-import-v1不要把 .env、.secrets/、数据库备份、上传文件或私钥加入 Git。允许员工或外部开发者参与时，应只授予必要权限并明确保密义务。
代码结构
| 目录 | 作用 |
|---|---|
apps/space | 社区 Web、路由、页面和用户交互 |
apps/auth | 登录、注册、账户和 SSO 前端 |
apps/template-docs | 产品、部署和扩展文档站 |
services/auth | Session、OAuth 2.0、OIDC 和账户服务 |
services/space-api | 社区业务 API、数据库迁移与 Provider 接入 |
services/community-template-worker | 通用定时任务与维护任务 |
packages/space-contract | 前后端共享的数据结构和校验规则 |
packages/template-core | 模块开关、Provider 和路由能力模型 |
packages/brand | 品牌叙事生成与共享品牌文案 |
config/community-template.json | 唯一的站点身份、模块与 Provider 配置入口 |
修改现有功能
- 先修改共享 contract，再修改 API 与页面，避免前后端各自定义字段。
- 数据结构变化必须新增迁移，不要回写已经发布的迁移文件。
- 权限判断必须同时覆盖页面入口和 API；隐藏导航不等于关闭接口。
- 为正常、无权限、空数据和失败状态增加测试。
- 运行
pnpm typecheck && pnpm test && pnpm build。
人工开发的标准流程
- 从干净的产品分支创建功能分支，写清楚目标、用户角色、数据变化和回滚方式。
- 用
pnpm dev:community-template在fullMock 场景复现当前行为。 - 先更新共享 contract、配置 schema 或迁移，再修改 API、Web、后台和 Mock。
- 至少覆盖正常、无权限、功能关闭、空数据和失败五类状态。
- 使用桌面与 390px 移动视口检查导航、表格、图片、弹窗和错误提示。
- 合并前运行相关包测试、完整类型检查、生产构建和
pnpm ops:template:preflight。
只修改前端显示而不检查真实接口，会留下可以直接调用的越权入口；只修改真实 API 而不更新 Mock，会让本地演示和交付文档逐渐失真。
增加一个新模块
新增模块通常需要同步处理：
- 在
packages/template-core增加模块键、路由和配置校验。 - 在
packages/space-contract增加请求、响应与权限结构。 - 在
services/space-api增加迁移、service、routes 和错误映射。 - 在
apps/space增加页面、导航、空状态和管理入口。 - 在 Worker 中增加任务时，必须提供幂等键、dry-run 和失败重试边界。
- 在 Mock 中增加可重置的虚构数据与至少一条完整交互路径。
- 在文档中说明开关、Provider、环境变量、备份和回滚影响。
品牌与身份
站点名称从 config/community-template.json 读取，并用于主站、Auth UI、邮件和支付标题。生产域名、包名、SMTP 发件人和对象存储地址只能由部署者在 .env 中配置。
修改品牌后执行：
pnpm --filter @zaowu/template-core validate:config -- config/community-template.json
pnpm typecheck接收后续版本
每个发行压缩包都是不可变快照。推荐保留三个 Git 引用：
template-import-v1：首次收到的原始版本。template-import-v2：新版本解压后形成的临时导入分支。- 你的产品分支：保存自己的功能和品牌修改。
升级时先在独立分支导入新版本，查看 git diff template-import-v1..template-import-v2，再把变更合并到产品分支。先处理迁移和配置差异，再处理业务代码；验证通过后才切换生产版本。不要通过覆盖 .env 或重建持久卷解决冲突。
如果使用 AI 协助升级，把旧模板标签、新模板标签、产品分支和允许修改的范围同时提供给 AI；不要只说“同步最新版”。AI 应先输出冲突清单和迁移风险，获得确认后再合并有歧义的业务改动。
许可边界
源码修改、委托开发、客户部署和衍生产品的许可范围以根目录 LICENSE 为准。生产域名、Logo、账号、数据和 Secret 不属于源码许可内容。