论坛开发

forum/ 是 cikio 的社区站（与 ccu.cikio.cn 平级，不是它的附属页面）。 一句话边界：人与人围绕内容产生的讨论全部归 forum，内容本身归各内容站。

项	值
包名	cikio-forum
线上地址	https://forum.cikio.cn
技术栈	Astro 7（output: 'server'）+ @astrojs/cloudflare 14 + Tailwind 4 + daisyUI 5
存储	D1 forum-db、KV CACHE、R2 forum-assets

当前状态：骨架已就绪并部署可访问（首页、发帖、个人、设置、后台这些入口已经在位）， 业务功能仍在开发中。表结构、权限模型与接口契约已经定稿，落在 forum/ 目录下的内部文档里。

一、目录与分层

forum/
├─ src/pages/          # 页面 + api/（认证回调、登出）+ auth/backchannel-logout.ts
├─ src/db/schema/      # 按域拆分的表定义：common / users / boards / threads / replies / interactions / governance
├─ src/lib/            # auth、cookies、http、oidc、policy、region、viewer、write/
├─ src/interfaces/     # 内部数据接口类型
├─ src/components/     # 布局、导航与基础组件
├─ drizzle/            # 迁移 SQL + meta/
└─ docs/               # 仓库内部设计文档：boundary / data-model / permissions / api-contract / realtime / d1-plan

与 ccu 的差别：这里 schema 按域拆文件（再汇总），而不是单文件 —— 表多、且各域归属不同维护者。

二、数据模型（按域）

域	表
账号与会话	users、sessions（只镜像 authserver 的必要信息，不存密码）
板块与治理	boards、board_moderators、board_applications、reports、audit_logs
帖子与回复	threads、replies
互动	thread_likes、thread_favorites、reply_likes、follows、forum_mutes
投票	polls、poll_options、poll_votes
标签	tags、thread_tags

约定：

• 状态机与方向守卫：帖子/板块状态只能沿定义好的方向迁移，非法迁移返回可解释错误，不静默改状态。
• 单写入口：写入收进 src/lib/write/，与 ccu 同一套纪律（幂等、可解释错误、不静默降级）。
• 表的字段级设计、索引与迁移纪律见 forum/docs/data-model.md（内部）。

三、权限模型

三类身份输入（登录用户、板块角色、站点级角色）汇总到唯一的判定入口 can()， 所有页面与接口都从它取结论，不在各处散写判断。拒绝时返回可解释错误码（前端能据此给出具体原因）， 而不是统一的「无权限」。角色定义、板块级门槛矩阵见 forum/docs/permissions.md（内部）。

四、跨站复用（不要重复造）

能力	用哪个	不要做什么
用户收到的消息（站内信 / 邮件）	message 的 /api/ingest/messages	不建 notification 表、不直接接邮件服务
内容审核判定与留痕	@cikio/moderation	不建自己的敏感词表
账号、会话、第三方绑定	authserver（OIDC + links claim）	不做注册登录与绑定 UI

五、本地开发与迁移

pnpm --filter cikio-forum run dev              # astro dev
pnpm --filter cikio-forum run typecheck        # astro check
pnpm --filter cikio-forum run db:migrate:local
pnpm --filter cikio-forum run db:generate      # schema → drizzle/*.sql
pnpm --filter cikio-forum run db:migrate       # --remote，必须早于部署

绑定与 ccu 基本一致（同一个 Cloudflare 账号）：

binding	类型	用途
DB	D1 forum-db	本站数据
CACHE	KV	计数、热榜等缓存
BUCKET	R2 forum-assets	图片附件
MODERATION_DB / MODERATION_WORDS	D1 / KV	共享审核库与词库快照
ASSETS	构建产物 ./dist	静态资源
[vars]	—	AUTHSERVER_URL、FORUM_OIDC_CLIENT_ID（公开客户端，无密钥）

六、构建与部署

pnpm --filter cikio-forum run build     # 产物 dist/client + dist/server（Worker 入口）
pnpm --filter cikio-forum run deploy    # astro build && wrangler deploy

自定义域 forum.cikio.cn 已在 wrangler.toml 里以 routes + custom_domain 声明。 forum/ 已挂进根 pnpm-workspace.yaml，参与根目录的 typecheck / build。

七、协作纪律

• authserver/ 与 ccu/ 有并行协作者：动它们之前先对齐，渠道就是 forum/docs/boundary.md 里的待对齐清单。
• 任何边界或接口变更，先改 forum/docs/boundary.md 或 docs/api-contract.md，再改代码。
• 尚未解锁的前置项：authserver 侧注册 forum 的 OIDC 客户端（回调地址 https://forum.cikio.cn/api/auth/callback）。 在此之前登录相关功能无法端到端联调。
• 实时能力一期不引入 Durable Objects，方案取舍记录在 forum/docs/realtime.md（内部）。

相关：论坛（产品视角）、认证服务开发、共享包开发。