COMPLETE PROJECT HANDBOOK

Aiteone 3.11.1
超级详细项目说明

面向项目所有者、产品经理、运营人员、开发维护人员和部署管理员的统一说明。本文档定义当前功能、业务规则、系统边界、部署方式、质量状态与后续方向。

Version 3.11.1Build 20260906.312Schema 48Stable Package

01 · 项目摘要

产品名称

Aiteone，由 81ON 品牌与域名理念延伸而来。

服务对象

球类活动参与者、活动组织者、俱乐部和平台运营团队。

客户端

响应式 H5/PC、微信小程序和平台总后台。

部署形态

Docker Compose，支持 Mac 本机与 1Panel 生产部署。

Aiteone 不是单纯的报名表。它覆盖活动发现、发布、报名、候补、提醒、签到、名单、公平分组、分享、相册、复盘、运动履历、俱乐部私域运营和平台治理。当前版本为模块化单体架构：保持业务边界清晰，同时避免过早拆分微服务带来的部署和数据一致性成本。

3.11.1 的发布性质

这是 3.11 系列补丁版本。数据库沿用 schema 48，不新增破坏性迁移；重点改善信息架构、步骤导航、空状态、组织工作台、活动详情快速跳转、名单管理模式和说明站交付。

02 · 产品定位与核心原则

要解决的问题

  • 参与者不知道附近有哪些适合自己、仍可报名的活动。
  • 组织者重复发布相似活动、维护名单、催报名、分组和通知，负担过重。
  • 微信群消息易丢失，活动、成员、照片和历史无法结构化沉淀。
  • 俱乐部缺少独立品牌、成员治理、固定活动、公告与数据工具。
  • 平台运营缺少跨用户、活动、俱乐部、内容、媒体和安全的统一后台。

设计原则

方便

高频动作优先；低频设置折叠；草稿自动恢复；空页面也给出下一步。

公平

分组兼顾出场次数、搭档和对手重复、水平、到场状态与场地条件。

可解释

推荐显示距离、时间、兴趣或关注原因；权限和失败提示说明具体原因。

可运营

页面、字典、开关、广告、内容、角色、媒体和备份尽量由后台治理。

数据边界

俱乐部和活动采用对象级权限，不因分享链接或前端隐藏而越权。

渐进复杂

普通参与者看到简单流程，组织者与管理员按权限展开高级能力。

03 · 三类核心角色与实际价值

角色最常见任务Aiteone 提供的价值成功指标
活动参与者找活动、判断是否适合、报名、到场、看照片个性推荐、清楚详情、名单、提醒、日历、相册和履历报名转化、到场率、复参与率
活动组织者发布、招募、审批、分组、通知、复盘草稿、复制、模板、待办、名单、分组图、分享转化发布耗时、满员率、管理处理时长
俱乐部管理者成员、固定活动、公告、群运营与留存独立空间、邀请、审批、标签、计划、相册、数据看板入会率、活跃会员、复参与率
平台运营者治理用户、活动、内容、媒体与风险运营工作台、360°、配置、审计、备份和恢复稳定性、内容质量、处理时效

04 · 端到端业务流程

发现

首页日历或发现地图按位置、时间、兴趣、关注和可报名状态展示。

判断

阅读日期时间、地点、天气、名额、费用、水平、成员和介绍。

报名

完善可识别身份，提交备注，进入确认、审核或候补。

参加

收到提醒、加入手机日历、签到、查看名单和分组。

分享

微信、朋友圈、LINE、链接与二维码生成独立渠道标识。

记录

活动成员上传照片视频，收藏、下载、举报与授权公开精选。

复盘

确认到场、费用、总结、亮点、下次计划并通知成员。

沉淀

个人运动日历、俱乐部相册、点评和统计形成长期关系。

状态原则

报名区分待审核、确认、候补、取消申请、已取消；活动区分草稿、未开报名、可报名、已满、报名关闭、已结束、已取消；相册区分未开放、开放、锁定、归档；这些状态由 API 统一计算，客户端不自行猜测。

05 · 功能总表

业务域主要能力H5小程序后台
身份账户邮箱注册登录、找回密码、微信免注册、Google、绑定身份、会话完整微信身份＋邮箱密码设置用户、会话、安全
个人资料头像裁剪、昵称、性别、年龄段、城市、位置、偏好、专项水平完整完整字典、编辑、360°
首页日历周/月、今天、节假日、天气、五类范围、单天活动、个性推荐完整完整文案、节假日、广告
发现活动、俱乐部、场馆、本地生活、地图聚合、筛选、优先模式完整完整内容 CRUD、导入、审核、合并
发布三步表单、草稿、模板、复制、封面、富文本、翻译、分享完整完整活动辅助编辑
报名规则、审核、候补、备注、取消申请、提醒、日历完整完整统计与审计
名单与分组资料、到场、每组人数、场地、轮次、重排、锁定、分享图完整完整活动关系查询
俱乐部独立页、成员、邀请、公告、活动、模板、计划、群通知、相册完整管理移动高频管理平台治理
活动相册照片视频、实况兼容、收藏、下载、精选、审核、分享、举报完整完整媒体治理
运动日历周/月/年次数时长、状态、项目、场地、相册、个人补录完整完整用户关联查看
运营后台用户、活动、俱乐部、发现、内容、消息、媒体、备份、安全PC 优先不提供完整

06 · 俱乐部业务域详解

单一 AppID，多俱乐部独立空间

所有俱乐部运行在同一平台和小程序中，但拥有独立 slug、分享页面、品牌、颜色、成员、公告、活动、相册、邀请和运营数据。这样无需为每个俱乐部维护独立小程序，同时保留相对独立的私域体验。

访问者、会员、组织者三种首页

  • 访客：先理解俱乐部定位、地区、运动、常见时间、会员权益和加入政策。
  • 会员：优先看到下一场、自己的安排、公告、日历、相册和群入口。
  • 组织者：优先看到入会审批、报名待办、今日活动、固定计划、群通知和临时成员。

加入与治理

支持自由加入、需要审批、仅邀请、暂停招募；邀请可设置用途、有效期、次数和是否绕过审批。管理员可以添加标签、拒绝或拉黑特定用户。临时成员独立保存，不创建虚假平台账号，后续预留认领与合并。

减少群主工作量

  • 俱乐部活动模板和类似 Excel 的快捷活动列表。
  • 固定活动计划按周、双周或四周生成可检查草稿。
  • 群通知中心生成招募、提醒、变更、满员候补和活动后文案。
  • 公告日历、微信群码有效期、管理员微信和专属二维码。
  • 数据看板关注会员活跃、报名、到场、复参与和发现入会。
重要权限

成为俱乐部会员不等于活动管理员。活动管理仍由创建者、被任命协管和有权限的俱乐部管理员共同决定。

07 · 活动相册、复盘与运动日历

独立媒体空间

活动相册使用独立 Docker volume，与普通头像、封面和富文本媒体分离。照片、视频、Live Photo 兼容图、缩略图和处理状态保存在相册领域，不与普通媒体清理逻辑混淆。

参与者权利

上传者可以收藏、下载允许的内容、申请删除、举报、控制公开精选授权。管理员不能在没有上传者授权时把成员照片直接公开展示。

复盘闭环

组织者确认到场和费用，填写总结、亮点、下次计划和成员通知。复盘自动保存草稿，可引用相册精选内容；发布后形成俱乐部和个人长期记录。

运动日历统计

平台活动按报名、到场、组织和取消状态统计。个人补录独立标识，只进入个人次数和时长，不计入平台报名、组织者业绩或活动转化。

08 · H5、PC 与微信小程序

一致的业务，不强求完全相同的页面

两端共享 API、状态、权限和核心能力。H5 适合宽屏编辑、批量管理、俱乐部表格和平台后台；小程序适合浏览、报名、地图、现场名单、签到、分组、上传与通知。

当前同步原则

  • 同一活动在两端显示相同报名状态、容量、专项水平和可见范围。
  • 活动发布的基础、报名、封面、相册、联系和翻译字段保持兼容。
  • 发现栏目、运动字典、页面文案、功能开关来自同一公开配置。
  • 名单查看权限和管理权限严格分开。
  • 俱乐部 H5 提供完整低频配置，小程序保留现场和日常高频操作。

微信限制的产品处理

头像昵称必须由用户主动选择；位置采用主动选择和东京降级；订阅提醒每次由用户授权；朋友圈使用微信开放的分享能力，不能由服务器静默发布。

09 · 技术架构

1Panel / HTTPS
↓
Caddy Gateway
↙　　　　　　　　　↘
Vinext H5/PC　　Node.js API
　　　　　　　　　　　　↓
PostgreSQL 17　　Worker / Volumes

组件

Web

React/TypeScript，Vinext 生产构建，响应式 H5、PC 用户端与总后台。

Mini Program

微信原生 WXML/WXSS/JavaScript，共享请求、展示、文案和可读性工具。

API

Node.js 服务，承载认证、业务规则、权限、媒体、分享与运营接口。

Worker

提醒、邮件、订阅消息、视频处理、备份校验和失败重试。

Database

PostgreSQL 17，启动时按 schema_migrations 顺序执行幂等迁移。

Gateway

Caddy 统一 Web/API/媒体路由、请求体限制、安全头和静态缓存。

为什么暂不拆微服务

当前业务高度关联，单体事务能更可靠地维护报名、名额、候补、权限、相册和审计一致性。模块化单体也更适合单台 1Panel 服务器的部署与维护。等团队、流量和独立扩缩容需求明确后再拆分。

10 · 数据、迁移与持久化

Schema

当前数据库版本为 48。迁移文件位于 api/sql，按编号执行，设计为可重复启动。新版本不能通过手工修改 schema_migrations 跳过失败迁移。

四类持久数据

数据Docker volume用途外网访问
数据库{project}_postgres_data全部结构化业务数据不开放
普通媒体{project}_media_uploads头像、封面、富文本、品牌图/uploads/*
活动相册{project}_album_uploads活动照片、视频和派生文件受令牌保护的 /album-media/*
系统备份{project}_system_backups数据库与媒体完整备份仅后台授权下载

数据一致性

报名容量、候补转正、取消审批、活动复制幂等、俱乐部计划草稿、消息清空撤销和备份恢复都在服务端维护，避免仅靠前端状态。

11 · 权限、安全与隐私设计

  • Cookie 会话支持 Secure、有效期和强制失效。
  • CSRF、防伪请求与 CORS 白名单保护 H5 写操作。
  • 密码使用安全散列；找回密码令牌有时效和单次使用限制。
  • 真实 IP 从可信代理链解析，不直接信任客户端伪造 Forwarded 头。
  • 用户、活动、俱乐部、相册和联系方式采用对象级权限。
  • 发布者联系方式加密存储，查看与复制留痕，举报可触发冻结。
  • 富文本进行服务端清洗，限制标签、属性和图片来源。
  • 普通上传、相册照片、相册视频和备份导入使用不同容量限制。
  • 平台高风险操作记录操作者、对象、原因、前后值、IP 和时间。
  • 位置失败可降级，签到不长期保存参与者精确坐标。
隐私条款是业务能力，不是装饰文字

后台可管理版本、摘要、正文和启用状态。微信头像、昵称、常用位置和相册使用应在用户主动操作前给出用途说明。

12 · 平台总后台

后台采用统一运营工作台，不同岗位只显示被授权模块。主要区域如下：

运营总览

平台状态、待办、业务指标、趋势和失败任务。

用户中心

头像列表、筛选排序、360°、登录、IP、媒体和审计。

活动中心

高级筛选、辅助编辑、推荐、访问、二维码和转化。

俱乐部中心

空间、成员、活动、邀请、公告、相册和治理。

发现运营

地点录入、地图选点、导入、审核、重复合并和质量。

内容设置

页面文案、Logo、功能开关、运动、类型、水平和专项标准。

日历与广告

日本节假日、详细介绍、赞助投放和统计。

数据与安全

媒体、相册、备份、恢复、会话、登录和审计。

后台岗位

权限配置、个人保存视图和高风险动作约束。

13 · 环境变量与第三方依赖

配置组关键项说明
实例COMPOSE_PROJECT_NAME, HTTP_PORT决定容器、网络、volume 前缀和宿主端口
版本APP_VERSION, BUILD_ID当前应为 3.11.1 / 20260906.312
数据库POSTGRES_USER/PASSWORD/DB升级同一实例必须沿用
加密CONTACT_ENCRYPTION_KEY长期保存，不能随意更换
域名PUBLIC_BASE_URL, CORS_ORIGIN生产使用 HTTPS；多域名以逗号分隔
微信MINI APP_ID/SECRET, reminder keys登录、订阅和小程序码
OAuthGOOGLE_CLIENT_ID/SECRET, WECHAT_WEB未配置的入口由后台关闭
邮件SMTP_*找回密码、验证和提醒
地图天气Google, Apple, Open-Meteo留空可使用 OSM 与免费天气降级
容量MAX_UPLOAD, ALBUM_*, MAX_BACKUP普通媒体、相册与备份分别限制
安装包不包含生产 .env

交付包只包含示例环境文件。微信 Secret、Google Secret、SMTP 密码、数据库密码和管理员密码必须在服务器单独填写。

14 · 部署拓扑与安装

推荐生产路径

/opt/aiteone/Aiteone
COMPOSE_PROJECT_NAME=aiteone
HTTP_PORT=8100
PUBLIC_BASE_URL=https://app.81on.com

首次安装

unzip Aiteone-3.11.1-build-20260906.312-1Panel.zip
cd Aiteone
cp .env.1panel.example .env
nano .env
./scripts/preflight.sh
docker compose up -d --build --wait
./scripts/smoke-test.sh http://127.0.0.1:8100

反向代理

1Panel 网站启用证书后代理到本机回环端口。备份导入需设置 1100MB、关闭代理请求缓冲并放宽超时；/uploads/ 返回跨来源媒体头。前端静态指纹资源缓存一年且 immutable，HTML 和公开配置避免长期缓存。

15 · 备份、恢复与升级原则

备份

完整备份同时包含数据库、普通媒体、活动相册、版本和校验。后台提供创建、验证、下载和保留策略；命令行脚本适合维护窗口和自动化。

恢复

正式恢复先备份当前实例，把旧备份恢复到隔离数据库并校验，再切换，避免直接清理新版数据库遇到外键依赖并留下半恢复状态。

升级

  • 保留原 .env、项目名、数据库密码、加密密钥和所有 volume。
  • 替换代码并修改版本标识，然后重新构建。
  • 启动时自动执行未完成迁移。
  • 生产环境不得执行 docker compose down -v，该命令会删除持久化数据卷。
  • 先在独立项目名和端口的测试实例验证，再升级现网。

3.11.0 → 3.11.1

不增加数据库迁移。升级后 schema 仍为 48；主要检查页面导航、活动发布步骤、组织中心、俱乐部、相册、运动日历和文档站。

16 · 测试与质量评估

本次验证

ESLint

通过
TypeScript/React 与项目 JavaScript 静态检查。

生产构建

通过
Vinext 五阶段构建生成 standalone 输出。

自动化测试

214 项通过
业务、权限、迁移、跨端、部署与回归契约。

小程序语法

通过
本轮相关页面 JavaScript 语法与事件契约。

覆盖重点

账户会话、微信降级、发布草稿与复制、报名、收藏、签到、名单权限、公平分组、站内消息、发现地图、俱乐部、相册、运动日历、后台运营、备份恢复、迁移、CORS、缓存和多实例部署。

测试结论

当前版本适合作为 1Panel 测试环境和受控生产升级包。自动化通过不替代微信开发者工具真机、生产域名 HTTPS、第三方 OAuth、订阅消息和实际恢复演练。

17 · 版本演进摘要

  • 1.x：完成基础活动、报名、H5/小程序、微信身份、后台和俱乐部雏形。
  • 2.x：加强地图发现、用户 360°、活动运营、备份、消息、分享、头像和 UI。
  • 3.0：前端包拆分、静态缓存、中日英 H5 和未来 App 架构准备。
  • 3.1–3.3：草稿修复、发现运营、俱乐部私域和活动复盘。
  • 3.4–3.6：独立活动相册、Live Photo、精选授权和运动日历。
  • 3.8–3.10：验收整改、日历相册闭环、平台运营工作台与岗位权限。
  • 3.11.0：俱乐部角色首页、固定计划、群通知和临时成员。
  • 3.11.1：跨页面信息架构、空状态动作、步骤校验、名单模式和文档交付。

18 · 当前边界与已知技术债务

产品边界

  • 不替代微信群或 LINE 的即时聊天。
  • 不提供复杂会费、财务会计或支付结算。
  • 不为每个俱乐部维护独立小程序 AppID。
  • 地图距离是估算，不等同实时导航时间。
  • 朋友圈分享受微信平台能力限制。

技术债务

  • AiteoneApp.tsx 仍然很大，Babel 构建提示超过 500KB 后降低代码生成样式优化。
  • 部分小程序样式文件经历多轮追加，后续应合并重复规则。
  • 浏览器端 E2E 与微信真机自动化仍应扩充。
  • 视频转码、大型相册和高并发需在真实容量下压测。
  • 多语言后台内容覆盖度需要持续补齐。
最大优先技术项

下一轮应继续把超大的 H5 主组件拆为按业务域懒加载模块，同时保持现有 API 与路由不变。这会改善构建维护性和首屏资源治理。

19 · 后续升级建议

优先级 P0：稳定和可维护

  1. 拆分 H5 超大主组件：Profile、Organizer、Club、Operator 各自独立。
  2. 增加 Playwright 关键流程：登录、发布、报名、名单、俱乐部与后台备份。
  3. 建立生产监控：健康、错误率、worker 延迟、备份失败、媒体容量。
  4. 每季度完成一次真实恢复演练。

优先级 P1：俱乐部增长

  1. 临时成员本人认领与安全合并。
  2. 新会员七日引导、活跃分层和沉睡召回。
  3. 群通知访问 → 详情 → 报名的转化漏斗。
  4. 固定计划批量生成未来多场草稿并检测场地和时间冲突。
  5. 限制模板范围内的俱乐部首页模块排序。

优先级 P2：内容和体验

  1. 活动与相册分享海报模板后台化。
  2. 发现地点更新提醒、可信来源评分和批量复核。
  3. 完整补齐日文、英文后台文案和组织者自定义译文审核。
  4. 为 iPhone App 第一版复用 API、活动发布和组织工作台。

暂不建议

暂不增加复杂即时聊天、完整财务系统、任意拖拽建站器和多俱乐部独立 AppID。这些方向会显著增加审核、客服、支付合规和维护成本。

20 · 交付与上线验收清单

程序包

  • 版本 3.11.1 / build 20260906.312
  • schema 48
  • 不包含 .env、真实密钥、node_modules、备份和 dist
  • ZIP 完整性与 SHA-256 校验通过
  • 部署脚本有执行权限

服务验收

  • Web、API、worker、PostgreSQL、gateway 健康
  • 生产域名 HTTPS 与真实 IP 正确
  • 上传、相册和备份 volume 持久化
  • 微信登录、小程序码和订阅模板可用
  • Google/邮件按配置开关工作

业务验收

  • 首页、发现、详情、报名、发布、我的可用
  • 名单查看与管理权限正确
  • 俱乐部访客、会员、组织者视角正确
  • 相册上传、收藏、授权和举报正确
  • 总后台筛选、编辑、媒体与审计可用

运维验收

  • 能创建并验证完整备份
  • 备份已下载到服务器外
  • 团队知道恢复计划和禁止操作
  • 1Panel 备份导入容量限制已放宽
  • 上线前保留可回滚旧代码与数据备份
对外介绍第一次使用管理员手册